@docx-editor.dev/react 2.4.0 → 2.5.0

package/dist/index.d.mts

@@ -38,6 +38,16 @@ interface DocxEditorLoadingProps {
      * provider only after those resolve.
      */
     when?: boolean;
+    /**
+     * Render as an opaque overlay pinned over the nearest positioned ancestor, covering
+     * the previous document while the next one opens. This is the shape for the big-file
+     * case: a large document mounts behind one painted frame, and the overlay is what
+     * that frame shows. It carries a short appearance delay, so an open that finishes
+     * quickly never flashes it. Compose it INSIDE a positioned box (the packaged frame
+     * puts it in the workspace row); without `overlay` the part is an in-flow box that
+     * fills whatever the host gives it.
+     */
+    overlay?: boolean;
     /** Appended after the load-bearing `docx-editor docx-editor__loading` classes. */
     className?: string;
     /** Inline styles for the loading container, as on `DocxEditor.Viewport`. */
@@ -91,11 +101,17 @@ interface DocxEditorLoadingComponent {
  * </DocxEditor.Root>
  * ```
  *
- * It clears as soon as bytes are handed over — NOT when pages finish painting — so it is
- * safe to gate a `DocxEditor.Content` on, and an unmounted viewport does not bring it
- * back. A parse failure clears it too, so a broken document never spins forever; report
- * that from `snapshot().parseError` or the `error` event. Add `when` only for async the
- * editor cannot observe, typically a host that mounts the provider after its own fetch.
+ * It covers TWO windows. Before bytes arrive it is the empty-state screen. And while a
+ * LARGE document opens — the engine mounts it behind one painted frame precisely so this
+ * screen can paint before the blocking parse and layout — it holds until the pages land;
+ * pass `overlay` to pin it over the previous document for that window. A parse failure
+ * clears both, so a broken document never spins forever; report that from
+ * `snapshot().parseError` or the `error` event. Add `when` only for async the editor
+ * cannot observe, typically a host that mounts the provider after its own fetch.
+ *
+ * A host gating its own `DocxEditor.Content` must key that on `snapshot().isLoading`,
+ * which clears as soon as bytes are handed over — never on `isOpening`, whose scheduled
+ * mount needs the mount point to stay in the tree.
  *
  * Rendered OUTSIDE a `DocxEditor.Root` it always shows, because there is no editor to
  * report otherwise — the same rule `useEditorState` documents for a null editor. Place
@@ -137,8 +153,16 @@ interface DocxEditorRootProps {
      * construction-time in the engine.
      */
     modules?: readonly EditorModule[];
-    /** `'edit'` (default) or `'view'` (read-only). Sampled at mount only. */
-    mode?: 'edit' | 'view';
+    /**
+     * The mode the editor opens in, matching the toolbar's three-state pill. Sampled at
+     * mount only.
+     *
+     * `'edit'` opens in editing even when the document's `w:trackRevisions` asks for
+     * tracked changes; `'suggesting'` opens in suggesting (needs a review module and an
+     * `author`); `'view'` is read-only and the toolbar cannot leave it. Omitted, the
+     * DOCUMENT decides: a package carrying `w:trackRevisions` opens in suggesting.
+     */
+    mode?: 'edit' | 'view' | 'suggesting';
     /**
      * A fixed scale. Supplying one also means the mode is fixed, unless `zoomMode` says
      * otherwise: an app that pinned 100% keeps 100% on every window size.
@@ -154,7 +178,9 @@ interface DocxEditorRootProps {
      */
     zoomMode?: ZoomMode | 'auto';
     /** Fired once per instance, after it is published to the tree (and after any
-     *  `DocxEditor.Content` in the same commit has attached its mount point). */
+     *  `DocxEditor.Content` in the same commit has attached its mount point). A large
+     *  document mounts behind one painted frame; `onReady` fires AFTER that mount lands,
+     *  so scrolling or selecting from it works on any document size. */
     onReady?: (editor: Editor) => void;
     /** Fired when the document changes (revision + identity deltas, not bytes). */
     onChange?: (change: DocumentChange) => void;
@@ -1841,7 +1867,7 @@ interface DocxEditorContentControlNamespace {
 }
 declare const DocxEditorContentControl: DocxEditorContentControlNamespace;
 
-type EditorMode = 'edit' | 'view';
+type EditorMode = 'edit' | 'view' | 'suggesting';
 /**
  * Props for the React `DocxEditor`. The adapter is a thin renderer over the
  * `Editor` contract; it holds no editing-engine state of its own and never
@@ -1987,7 +2013,17 @@ interface DocxEditorProps {
     rulers?: boolean;
     /** A document to load: DOCX bytes or an existing handle. */
     document?: DocumentSource;
-    /** 'edit' (default) or 'view' (read-only). Applied at mount only — not reactive; remount to change. */
+    /**
+     * The mode the editor opens in, matching the toolbar's three-state pill. Applied at
+     * mount only — not reactive; remount to change.
+     *
+     * Defaults to `'edit'`: the packaged editor opens every document ready to type, even
+     * one whose `w:trackRevisions` asks for tracked changes. Pass `'suggesting'` (needs
+     * `modules` with a review module and an `author`) to open in suggesting, or `'view'`
+     * for read-only. To let the DOCUMENT decide — Word's behavior, where
+     * `w:trackRevisions` opens in suggesting — compose `DocxEditor.Root`, which follows
+     * the file's request when `mode` is omitted.
+     */
     mode?: EditorMode;
     /** A fixed scale. Supplying one also makes the mode fixed unless `zoomMode` says otherwise. */
     zoom?: number;

package/dist/index.d.ts

@@ -38,6 +38,16 @@ interface DocxEditorLoadingProps {
      * provider only after those resolve.
      */
     when?: boolean;
+    /**
+     * Render as an opaque overlay pinned over the nearest positioned ancestor, covering
+     * the previous document while the next one opens. This is the shape for the big-file
+     * case: a large document mounts behind one painted frame, and the overlay is what
+     * that frame shows. It carries a short appearance delay, so an open that finishes
+     * quickly never flashes it. Compose it INSIDE a positioned box (the packaged frame
+     * puts it in the workspace row); without `overlay` the part is an in-flow box that
+     * fills whatever the host gives it.
+     */
+    overlay?: boolean;
     /** Appended after the load-bearing `docx-editor docx-editor__loading` classes. */
     className?: string;
     /** Inline styles for the loading container, as on `DocxEditor.Viewport`. */
@@ -91,11 +101,17 @@ interface DocxEditorLoadingComponent {
  * </DocxEditor.Root>
  * ```
  *
- * It clears as soon as bytes are handed over — NOT when pages finish painting — so it is
- * safe to gate a `DocxEditor.Content` on, and an unmounted viewport does not bring it
- * back. A parse failure clears it too, so a broken document never spins forever; report
- * that from `snapshot().parseError` or the `error` event. Add `when` only for async the
- * editor cannot observe, typically a host that mounts the provider after its own fetch.
+ * It covers TWO windows. Before bytes arrive it is the empty-state screen. And while a
+ * LARGE document opens — the engine mounts it behind one painted frame precisely so this
+ * screen can paint before the blocking parse and layout — it holds until the pages land;
+ * pass `overlay` to pin it over the previous document for that window. A parse failure
+ * clears both, so a broken document never spins forever; report that from
+ * `snapshot().parseError` or the `error` event. Add `when` only for async the editor
+ * cannot observe, typically a host that mounts the provider after its own fetch.
+ *
+ * A host gating its own `DocxEditor.Content` must key that on `snapshot().isLoading`,
+ * which clears as soon as bytes are handed over — never on `isOpening`, whose scheduled
+ * mount needs the mount point to stay in the tree.
  *
  * Rendered OUTSIDE a `DocxEditor.Root` it always shows, because there is no editor to
  * report otherwise — the same rule `useEditorState` documents for a null editor. Place
@@ -137,8 +153,16 @@ interface DocxEditorRootProps {
      * construction-time in the engine.
      */
     modules?: readonly EditorModule[];
-    /** `'edit'` (default) or `'view'` (read-only). Sampled at mount only. */
-    mode?: 'edit' | 'view';
+    /**
+     * The mode the editor opens in, matching the toolbar's three-state pill. Sampled at
+     * mount only.
+     *
+     * `'edit'` opens in editing even when the document's `w:trackRevisions` asks for
+     * tracked changes; `'suggesting'` opens in suggesting (needs a review module and an
+     * `author`); `'view'` is read-only and the toolbar cannot leave it. Omitted, the
+     * DOCUMENT decides: a package carrying `w:trackRevisions` opens in suggesting.
+     */
+    mode?: 'edit' | 'view' | 'suggesting';
     /**
      * A fixed scale. Supplying one also means the mode is fixed, unless `zoomMode` says
      * otherwise: an app that pinned 100% keeps 100% on every window size.
@@ -154,7 +178,9 @@ interface DocxEditorRootProps {
      */
     zoomMode?: ZoomMode | 'auto';
     /** Fired once per instance, after it is published to the tree (and after any
-     *  `DocxEditor.Content` in the same commit has attached its mount point). */
+     *  `DocxEditor.Content` in the same commit has attached its mount point). A large
+     *  document mounts behind one painted frame; `onReady` fires AFTER that mount lands,
+     *  so scrolling or selecting from it works on any document size. */
     onReady?: (editor: Editor) => void;
     /** Fired when the document changes (revision + identity deltas, not bytes). */
     onChange?: (change: DocumentChange) => void;
@@ -1841,7 +1867,7 @@ interface DocxEditorContentControlNamespace {
 }
 declare const DocxEditorContentControl: DocxEditorContentControlNamespace;
 
-type EditorMode = 'edit' | 'view';
+type EditorMode = 'edit' | 'view' | 'suggesting';
 /**
  * Props for the React `DocxEditor`. The adapter is a thin renderer over the
  * `Editor` contract; it holds no editing-engine state of its own and never
@@ -1987,7 +2013,17 @@ interface DocxEditorProps {
     rulers?: boolean;
     /** A document to load: DOCX bytes or an existing handle. */
     document?: DocumentSource;
-    /** 'edit' (default) or 'view' (read-only). Applied at mount only — not reactive; remount to change. */
+    /**
+     * The mode the editor opens in, matching the toolbar's three-state pill. Applied at
+     * mount only — not reactive; remount to change.
+     *
+     * Defaults to `'edit'`: the packaged editor opens every document ready to type, even
+     * one whose `w:trackRevisions` asks for tracked changes. Pass `'suggesting'` (needs
+     * `modules` with a review module and an `author`) to open in suggesting, or `'view'`
+     * for read-only. To let the DOCUMENT decide — Word's behavior, where
+     * `w:trackRevisions` opens in suggesting — compose `DocxEditor.Root`, which follows
+     * the file's request when `mode` is omitted.
+     */
     mode?: EditorMode;
     /** A fixed scale. Supplying one also makes the mode fixed unless `zoomMode` says otherwise. */
     zoom?: number;