ooxml-ui 1.18.3 → 1.20.0

package/dist/docx/collaboration-room.d.ts

@@ -0,0 +1,46 @@
+import { type CollabSession } from 'ooxml-core/collab';
+import type { WordYjsOptions } from 'ooxml-core/docx/ui';
+import type { EditorCore } from './editor-core.js';
+import { type DocxCollaborationOptions, type DocxCollaborationState } from './collaboration-types.js';
+/** What the controller needs from the editor. */
+export interface RoomHost {
+    /** The editor is mounted with a view the document can be bound to. */
+    ready(): boolean;
+    /** A document is being loaded; joining waits for it. */
+    loading(): boolean;
+    author(): string;
+    join(session: CollabSession, options: WordYjsOptions): void;
+    leave(): void;
+    error(error: Error): void;
+    changed(state: DocxCollaborationState): void;
+}
+export declare class DocxRoom {
+    #private;
+    private readonly host;
+    constructor(host: RoomHost);
+    /** The options of the declarative `collaboration` property, if set. */
+    get wanted(): DocxCollaborationOptions | undefined;
+    /** Joined or joining through the property. */
+    get busy(): boolean;
+    /** The session of a join still waiting to bind, for `reconnectCollaboration`. */
+    get pendingSession(): CollabSession | undefined;
+    /** Declarative sharing: while set, the open document is shared; undefined leaves. */
+    want(options: DocxCollaborationOptions | undefined): void;
+    /** Forgets the property and leaves. True when there was anything to leave. */
+    stop(): boolean;
+    /** Leaves before the document is replaced; true when it was shared through the property. */
+    suspend(): boolean;
+    /** Joins the wanted room with the document now open. */
+    resume(): void;
+    /** The Yjs binding started or stopped (through the property or `startYjsCollaboration`). */
+    yjsChanged(session: CollabSession | undefined): void;
+    state(): DocxCollaborationState;
+    /** Leaves the room; a session the host passed in stays alive, one made here is destroyed. */
+    leave(): void;
+}
+/** Binds the open document to a synchronized session (the body of `startYjsCollaboration`). */
+export declare function joinYjs(core: EditorCore, session: CollabSession, options: WordYjsOptions): void;
+/** Detaches the Yjs binding, keeping its current content, comments and new picture parts. */
+export declare function leaveYjs(core: EditorCore): void;
+/** The controller of one editor, reporting through its events and error channel. */
+export declare function roomFor(core: EditorCore): DocxRoom;

package/dist/docx/collaboration-session.d.ts

@@ -12,6 +12,8 @@ export declare class CollaborationSession {
     yjs?: WordYjsCollaboration | undefined;
     presence?: EditorPresence | undefined;
     ids?: ((kind: string) => string) | undefined;
+    /** Called after a Yjs binding starts (with its session) or stops (undefined). */
+    onYjsChange?: ((session: CollabSession | undefined) => void) | undefined;
     private sendScheduled;
     constructor(element: HTMLElement, getView: () => EditorView | undefined);
     get active(): boolean;

package/dist/docx/collaboration-types.d.ts

@@ -0,0 +1,13 @@
+import type { CollaborationOptions, CollaborationState, Collaborator } from 'ooxml-core/collab';
+/**
+ * How to join a shared document (see `CollaborationOptions`): `session`, `provider`, `serverUrl`,
+ * else a BroadcastChannel. The user name defaults to `reviewAuthor`. The room name doubles as the
+ * Word `documentId`, so every participant must have loaded the same source package. `intent:
+ * 'join'` never seeds an empty room; anything else lets this window seed it.
+ */
+export type DocxCollaborationOptions = CollaborationOptions;
+/** One person in the room, as `collaboration-change` lists them. */
+export type DocxCollaborator = Collaborator;
+/** Collaboration state, reported by `collaborationState` and the `collaboration-change` event. */
+export type DocxCollaborationState = CollaborationState;
+export declare const OFF_STATE: DocxCollaborationState;

package/dist/docx/component.d.ts

@@ -1,6 +1,7 @@
 import type { DocumentModel } from 'ooxml-core/docx';
 import type { CollaborationConfig, ClientReceiveResult, StepBatch } from 'ooxml-core/docx/ui';
 import { type EditorTheme, type EditorThemeMode } from 'ooxml-core/docx/ui';
+import type { DocxCollaborationOptions } from './collaboration-types.js';
 import { EditorCore, type LoadedDocument } from './editor-core.js';
 import { DocxEditorApi } from './element-api.js';
 import { type DocxEditorEventMap } from './events.js';
@@ -30,7 +31,7 @@ export declare class DocxEditorElement extends DocxEditorApi {
     /** File name shown in the title bar and used for downloads from the built-in File commands. */
     get fileName(): string;
     set fileName(value: string);
-    /** `light`, `dark`, or `auto` (default, follows the OS). Reflected to the `theme` attribute. */
+    /** `light`, `dark`, or `auto` (default, inherits the Office theme, then follows the OS). Reflected to the `theme` attribute. */
     get theme(): EditorThemeMode;
     set theme(value: EditorThemeMode);
     /** Token overrides applied as inline `--dve-*` custom properties on the host. */
@@ -42,6 +43,18 @@ export declare class DocxEditorElement extends DocxEditorApi {
     set documentModel(value: DocumentModel | null);
     get readOnly(): boolean;
     set readOnly(value: boolean);
+    /**
+     * Shares the loaded document in a room while set; `null` leaves (see
+     * `DocxCollaborationOptions`). A document loaded later is shared too: the editor leaves
+     * before it is replaced and rejoins after. With `intent: 'join'` an empty room is never seeded.
+     * Race: with the default `create`, two windows that open one empty room at the same moment both
+     * seed it and the room holds both bodies, so give exactly one window `create` and the others
+     * `join`. A room name is also the Word `documentId`: nothing verifies that every window
+     * loaded the same source package. A viewer `user.role` blocks local edits (advisory).
+     * Leaving keeps the content; a session the editor opened is destroyed, a host `session` is not.
+     */
+    get collaboration(): DocxCollaborationOptions | null;
+    set collaboration(value: DocxCollaborationOptions | null | undefined);
     connectedCallback(): void;
     disconnectedCallback(): void;
     load(input: Uint8Array | ArrayBuffer): Promise<void>;

package/dist/docx/editor-core.d.ts

@@ -6,6 +6,7 @@ import type { DocumentModel } from 'ooxml-core/docx';
 import type { loadDocument } from 'ooxml-core/docx/load';
 import type { SearchPanelHandle } from './search-panel.js';
 import { CollaborationSession } from './collaboration-session.js';
+import { type DocxRoom } from './collaboration-room.js';
 import type { EditorTheme, EditorThemeMode } from 'ooxml-core/docx/ui';
 import type { EditorLocale } from './localization.js';
 import type { PrintEditingBridge } from './print-editing.js';
@@ -57,7 +58,10 @@ export declare class EditorCore {
     view?: EditorView | undefined;
     loaded?: LoadedDocument | undefined;
     loadGeneration: number;
+    loading: boolean;
     readOnly: boolean;
+    /** Set before mounting to render only the document surface. */
+    surfaceOnly: boolean;
     locale: EditorLocale;
     reviewAuthor: string;
     theme: EditorThemeMode;
@@ -68,6 +72,8 @@ export declare class EditorCore {
     pendingFileName?: string;
     readonly shell: ShellParts;
     readonly collab: CollaborationSession;
+    /** The declarative `collaboration` property and the Yjs state reporting. */
+    readonly room: DocxRoom;
     readonly inserts: InsertController;
     readonly formatDialogs: FormatDialogs;
     readonly imageMedia: ImageMediaCache;

package/dist/docx/element-api.d.ts

@@ -1,19 +1,30 @@
 import type { RibbonAddInTab } from '../ribbon/add-in-tabs.js';
 import type { CollabSession } from 'ooxml-core/collab';
 import type { WordYjsOptions } from 'ooxml-core/docx/ui';
+import type { DocxCollaborationState } from './collaboration-types.js';
 import type { EditorCore } from './editor-core.js';
 import { type RibbonActionId, type RibbonActionInput } from 'ooxml-core/docx/ui';
+import { type WordToolbarProps } from './building-blocks.js';
 declare const HTMLElementBase: typeof HTMLElement;
 /**
  * Save, collaboration, dirty-tracking and UI-customisation surface of `<docx-editor>`.
  * the shared `EditorCore`, so the element class stays a thin lifecycle facade.
  */
 export declare abstract class DocxEditorApi extends HTMLElementBase {
+    /** Choose before connecting. This mode mounts only the document and its editing surface. */
+    get surfaceOnly(): boolean;
+    set surfaceOnly(value: boolean);
+    getToolbarProps(): WordToolbarProps;
+    get loading(): boolean;
+    /** Selection and formatting updates, including changes which do not dirty the document. */
+    subscribeEditorState(listener: () => void): () => void;
     protected abstract readonly core: EditorCore;
     abstract fileName: string;
     abstract reviewAuthor: string;
     /** Join a synchronized Yjs room after loading its matching source package. */
     startYjsCollaboration(session: CollabSession, options: WordYjsOptions): void;
+    /** Who is in the room, and whether it is synced; the off state when not sharing. */
+    get collaborationState(): DocxCollaborationState;
     reconnectCollaboration(): void;
     resyncCollaboration(): boolean;
     publishPresence(profile: {

package/dist/docx/events.d.ts

@@ -1,6 +1,7 @@
 import type { DocumentModel } from 'ooxml-core/docx';
 import type { RibbonAddInCommandDetail } from 'ooxml-core/ribbon';
 import type { StepBatch } from 'ooxml-core/docx/ui';
+import type { DocxCollaborationState } from './collaboration-types.js';
 import type { FileCommandDetail } from './file-commands.js';
 import type { PageChangeDetail } from './page-sync.js';
 import type { PresenceMessage } from './presence.js';
@@ -29,6 +30,8 @@ export interface DocxEditorEventMap {
     'presence-send': CustomEvent<PresenceMessage>;
     /** Local steps are pending; transport the batch to the collaboration authority. */
     'collaboration-send': CustomEvent<StepBatch>;
+    /** Sharing started, stopped, reconnected, synced or the people in the room changed. */
+    'collaboration-change': CustomEvent<DocxCollaborationState>;
     /** A command of a host tab (`ribbonAddIns`) was chosen. */
     'office-ribbon-add-in': CustomEvent<RibbonAddInCommandDetail>;
 }
@@ -36,7 +39,7 @@ export type DocxEditorEventName = keyof DocxEditorEventMap;
 /** Detail payload type of the named event. */
 export type DocxEditorEventDetail<K extends DocxEditorEventName> = DocxEditorEventMap[K] extends CustomEvent<infer D> ? D : never;
 /** Runtime list of every event name; the `satisfies` check keeps it a subset of the map. */
-export declare const DOCX_EDITOR_EVENTS: readonly ["document-change", "document-error", "document-warning", "readonly-change", "ribbon-action", "ribbon-customize", "file-command", "page-change", "dirty-change", "presence-send", "collaboration-send", "office-ribbon-add-in"];
+export declare const DOCX_EDITOR_EVENTS: readonly ["document-change", "document-error", "document-warning", "readonly-change", "ribbon-action", "ribbon-customize", "file-command", "page-change", "dirty-change", "presence-send", "collaboration-send", "collaboration-change", "office-ribbon-add-in"];
 /** Typed listener for plain elements (such as the ribbon) that are not a `<docx-editor>`. */
 export declare function on<K extends DocxEditorEventName>(target: EventTarget, name: K, listener: (event: DocxEditorEventMap[K]) => void): void;
 /**

package/dist/docx/field-update.d.ts

@@ -1,16 +1,20 @@
+import { type DocumentModel } from 'ooxml-core/docx';
 import type { Transaction } from 'prosemirror-state';
 import type { EditorView } from 'prosemirror-view';
 /**
  * Word's Update Field for the whole body: every `SEQ` caption is renumbered, then `REF` results
  * follow their bookmarked paragraph and `PAGEREF` results take the page from `pageOf`. A REF that
  * pointed at a caption's label and number keeps showing the label; a longer result is treated as
- * the entire caption. Fields with other switches or a missing bookmark are left as they are.
- * One undoable step; returns whether anything changed.
+ * the entire caption. With the document's `model`, `STYLEREF` results take the nearest text in
+ * their style before the field, else after it, which an empty paragraph in the style makes empty
+ * (the field stays, with its instruction, and a later update fills it). Fields with other
+ * switches or a missing bookmark or style are left as they are. One undoable step; returns
+ * whether anything changed.
  */
-export declare function updateFields(view: EditorView, pageOf: (id: string) => string | undefined): boolean;
+export declare function updateFields(view: EditorView, pageOf: (id: string) => string | undefined, model?: DocumentModel): boolean;
 /**
  * The refresh behind `updateFields`, applied to `tr` so other commands (a new caption) can include
  * it in their own undo step. Without `pageOf`, `PAGEREF` results are left alone: pages need a layout.
  * With `captionsOnly`, only references that quote a caption are refreshed.
  */
-export declare function refreshFieldResults(tr: Transaction, pageOf?: (id: string) => string | undefined, captionsOnly?: boolean): Transaction;
+export declare function refreshFieldResults(tr: Transaction, pageOf?: (id: string) => string | undefined, captionsOnly?: boolean, model?: DocumentModel): Transaction;

package/dist/docx/form-field-view.d.ts

@@ -0,0 +1,3 @@
+import { type DocumentModel } from 'ooxml-core/docx';
+import { Plugin } from 'prosemirror-state';
+export declare function formFieldViewPlugin(model: () => DocumentModel): Plugin;

package/dist/docx/index.d.ts

@@ -1,4 +1,5 @@
 export { DocxEditorElement, registerDocxEditor } from './component.js';
+export type { WordToolbarProps } from './building-blocks.js';
 export { DOCX_EDITOR_EVENTS } from './events.js';
 export type { RibbonAction } from './ribbon.js';
 export { RIBBON_ACTION_IDS, RIBBON_ACTION_LABELS, normalizeRibbonActions, isRibbonActionId, } from 'ooxml-core/docx/ui';
@@ -11,6 +12,7 @@ export type { DocxEditorAttribute } from './editor-attributes.js';
 export { CollaborationClient, CollaborationAuthority } from 'ooxml-core/docx/ui';
 export type { CollaborationConfig, StepBatch, ClientReceiveResult, AuthorityResult, } from 'ooxml-core/docx/ui';
 export type { CollaborationAuthorityConfig } from 'ooxml-core/docx/ui';
+export type { DocxCollaborationOptions, DocxCollaborationState, DocxCollaborator, } from './collaboration-types.js';
 export type { WordYjsOptions } from 'ooxml-core/docx/ui';
 export { createCollaborationAuthority } from './collaboration-model.js';
 export { PresenceClient, PRESENCE_PALETTE } from './presence.js';

package/dist/docx/ribbon-popover.d.ts

@@ -9,8 +9,9 @@ export declare function mountPopover(anchor: HTMLElement, pop: HTMLElement, expa
 /** Opens a swatch grid under the caret button `anchor`. */
 export declare function openSwatchPopover(anchor: HTMLElement, choices: Array<[string, string]>, choose: (value: string) => void): void;
 /**
- * Opens a scrolling list of `items` under a combo box, with `current` marked and scrolled into view.
- * Up/Down move through the entries, Enter chooses, Escape closes. `preview` sets each entry in its
- * own font face.
+ * Opens a scrolling list of `items` under a combo box, with `current` (an entry, or its index when
+ * entries can repeat) marked and scrolled into view. Up/Down move through the entries, Enter
+ * chooses, Escape closes. `preview` sets each entry in its own font face. `choose` gets the entry
+ * and its index.
  */
-export declare function openListPopover(anchor: HTMLElement, items: readonly string[], current: string, preview: boolean, choose: (value: string) => void): void;
+export declare function openListPopover(anchor: HTMLElement, items: readonly string[], current: string | number, preview: boolean, choose: (value: string, index: number) => void): void;

package/dist/docx/styles/index.d.ts

@@ -1,6 +1,2 @@
-/**
- * Token presets are generated from theme/defaults.ts so the TypeScript presets and the shadow-root
- * CSS cannot drift. `theme="auto"` (the default) follows the OS; explicit values always win.
- */
 export declare const themeTokenText: string;
 export declare const editorStyleText: string;

package/dist/docx/table-model-adapter.d.ts

@@ -1,6 +1,8 @@
 import type { Node as ProseMirrorNode } from 'prosemirror-model';
 import type { Paragraph, Table, TableStyleCatalog } from 'ooxml-core/docx';
 export declare function tableNode(block: Table, paragraphNode: (paragraph: Paragraph) => ProseMirrorNode, tableStyles?: TableStyleCatalog, nested?: boolean): ProseMirrorNode;
+/** The block control around a table as the editor holds it. */
+export declare const tableControl: (node: ProseMirrorNode, prior?: Table) => Pick<Table, 'contentControl'>;
 /** Reads editable formatting from nodes rather than a stale prior model. */
 export declare function tableFormattingFromNode(node: ProseMirrorNode): {
     rowProperties: Table['rowProperties'];