feat(superdoc): expose built-in loading UI toggle as ui.loading (IT-1365)

[caio-pizzol]

Stack 2/2 — depends on #3880. Review/merge #3880 first.

Problem

Keyora (IT-1365) has no supported way to turn off SuperDoc's built-in loading UI. editorOptions() in SuperDoc.vue:840 is an explicit allow-list with no spread, so the internal option was unreachable from Config.

This was the only remaining V1→V2 migration blocker Soumi identified.

Change

new SuperDoc({
  document: file,
  ui: { loading: false }, // default: true
});

<SuperDocEditor document={file} ui={{ loading: false }} />

Presentation-only: it does not change document initialization, collaboration synchronization or load time. Editing stays blocked until the editor is ready (see #3880), and host-provided loading UI such as React's renderLoading is unaffected.

Why a ui namespace

• Separate from modules, which is for feature modules and is an explicit full-rebuild trigger in the React wrapper.
• Separate from the superdoc/ui controller entry point: that is for building a custom UI, this configures the built-in one. A config property and a module specifier do not collide.
• Gives future built-in-UI toggles a home instead of adding another permanent top-level Config boolean.
• No public flat alias, since nothing has shipped yet, so supporting both would be needless compatibility debt.

Reaches @superdoc-dev/react automatically and typed via SuperDocEditorProps extends Omit<SuperDocConfig, ...>, riding restProps, which is excluded from the rebuild deps.

Docs

Documented on both manually maintained config pages, including how ui.loading relates to React's renderLoading. Additive only (26 lines); .mdx is outside the repo's prettier glob, so no reformatting churn.

Verification

• SuperDoc.test.js: 101/101, incl. 3 new (omitted ui; ui without loading; ui.loading: false)
• pnpm check:public:superdoc: PASS, 14/14 stages
• @superdoc-dev/react tsc --noEmit: clean
• docs check:imports, check:icons, test:examples (295): pass

Two pre-existing repo conditions, not caused by this stack

• packages/react vitest fails 15/31 locally (Cannot find module .../superdoc/dist/superdoc.es.js). Reproduced identically on unmodified main in a separate clean checkout, after a package rebuild and after ensure-superdoc-build.js.
• docs-check-em-dashes fails repo-wide (128 pre-existing on main; 0 in these changes), so it blocks any docs commit. Skipped via LEFTHOOK_EXCLUDE for this commit only; every other hook ran and passed.

Scope note

Loading lifecycle events are deliberately deferred. Soumi said exposing the variable is sufficient, and today's readiness signals do not describe a coherent loading lifecycle: editorReady flips immediately after async init starts without collaboration, lifecycleState emits no change event, and replaceFile() does not transition through documentLoading. That needs its own state model.

Refs IT-1365

🤖 Generated with Claude Code

[linear-code]

IT-1365

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

---

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

---

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

Previous review results

Review updated until commit 19ead3a ⚖️ Balanced

Results up to commit 081f67a 🚀 Fast

No changes from previous review

Powered by Qodo

[cubic-dev-ai]

No issues found across 3 files

_{Re-trigger cubic}

[caio-pizzol]

Closing as superseded by superdoc/orbit#1474.

This targeted V1 (superdoc@1.x on docx-editor/main) and fixed the V1 EditorSkeleton. That was the wrong product: IT-1365 is a V2 blocker for Keyora, and V2 lives on superdoc/orbit branch v2 (superdoc@2.4.0-next.48), which has no super-editor package and no EditorSkeleton at all.

V2 has its own loading overlay with a progress percentage, which matches the reporter's description far better than the V1 skeleton did. It also explains the ticket's replaceFile claim, which is real on V2 (replacement resets the loading state and re-arms the overlay) and is not on V1.

The API intent and the test scenarios carried over; none of the V1 skeleton or interaction-barrier implementation did, because V2's architecture already prevents a partial first paint.