@docx-editor.dev/pro 2.9.2 → 2.11.0

package/dist/vue/index.d.ts

@@ -1,10 +1,16 @@
 import { EditorModule } from '@docx-editor.dev/core/editor';
+import { EditorCollaborationSession, CollaborationStatus, CollaborationFailure, CollaborationParticipant, CollaborationIdentity, CollaborationRemoteSelection } from '@docx-editor.dev/core/collaboration';
+export { CollaborationFailure, CollaborationFailureCode, CollaborationIdentity, CollaborationParticipant, CollaborationRemoteSelection, CollaborationRemoteSelectionAddress, CollaborationSelectionKind, CollaborationStatus, CollaborationStatusSnapshot } from '@docx-editor.dev/core/collaboration';
 import * as vue_jsx_runtime from 'vue/jsx-runtime';
 import * as vue from 'vue';
 import { ComputedRef, Ref, VNode, MaybeRefOrGetter as MaybeRefOrGetter$1, PropType } from 'vue';
 import { ReviewItemPlacement, ReviewActivationOptions, ReviewItemQuery, Editor } from '@docx-editor.dev/core/contracts/editor';
 export { ReviewActivationOptions } from '@docx-editor.dev/core/contracts/editor';
 import { MaybeRefOrGetter, ReviewAuthorInfo } from '@docx-editor.dev/vue';
+import { C as CollaborationSession, a as CollaborationBootstrap } from '../session-okdqygLg.js';
+export { b as CollaborationIdentityUpdate } from '../session-okdqygLg.js';
+import * as Y from 'yjs';
+import { Awareness } from 'y-protocols/awareness';
 
 /**
  * Licensing, v1: honor system.
@@ -46,6 +52,28 @@ interface ReviewModuleOptions extends ProLicenseOptions {
 /** Build the review module. Construction never validates the key and never touches the network. */
 declare function reviewModule(options?: ReviewModuleOptions): EditorModule;
 
+/**
+ * The collaboration module: a replica as an `EditorModule` for
+ * `createDocxEditor({ modules })`.
+ *
+ * Registering it is the whole enablement story: the surface attaches the
+ * session, remote selections paint, and undo routes through the session.
+ * This file imports no Yjs, so the main Pro entry can re-export it without
+ * pulling a CRDT into a review-only bundle.
+ */
+
+/**
+ * How {@link collaborationModule} is configured. The session is required;
+ * the licence key is optional and never validated.
+ *
+ * @public
+ */
+interface CollaborationModuleOptions extends ProLicenseOptions {
+    readonly session: EditorCollaborationSession;
+}
+/** Build the collaboration module. Construction never validates the key and never touches the network. */
+declare function collaborationModule(options: CollaborationModuleOptions): EditorModule;
+
 /** @public */
 type ReviewItemView = ReviewItemPlacement;
 
@@ -746,6 +774,414 @@ declare const DocxEditorReview: {
 /** @public */
 type DocxEditorReviewNamespace = typeof DocxEditorReview;
 
+/** Reactive collaboration status for Vue hosts. @public */
+interface UseCollaborationStatusReturn {
+    readonly status: Readonly<Ref<CollaborationStatus | 'inactive'>>;
+    readonly reason: Readonly<Ref<CollaborationFailure | undefined>>;
+    readonly lastFailure: Readonly<Ref<CollaborationFailure | undefined>>;
+    /**
+     * Edits made now reach the room.
+     *
+     * False while joining, while the transport is down, and after a terminal failure. A host
+     * that shows nothing else should show this, because the alternative is a user typing into
+     * a replica nobody receives.
+     */
+    readonly live: ComputedRef<boolean>;
+    /**
+     * This replica no longer agrees with the room, and waiting will not fix it.
+     *
+     * `error` and `destroyed`. The replica refused an update and kept the copy it had, so it is
+     * now editing a document the others do not have. The way out is `rejoin`, not time — which
+     * is why this is separate from "not live" rather than folded into it.
+     */
+    readonly diverged: ComputedRef<boolean>;
+    /**
+     * An editor has attached its document port to this replica.
+     *
+     * False with a live session means the host did not remount the editor when the session
+     * appeared — pass `:key="session.sessionId"` — so `collaborationModule` never attached and
+     * nothing replicates, whatever `status` says.
+     */
+    readonly attached: Readonly<Ref<boolean>>;
+}
+/**
+ * Reactive status for the collaboration session, with `live` and `diverged` derived.
+ *
+ * Omit `session` and it reads the one the editor above holds. Pass it explicitly for a
+ * session this Root does not own.
+ *
+ * @public
+ */
+declare function useCollaborationStatus(session?: MaybeRefOrGetter$1<CollaborationSession | null>): UseCollaborationStatusReturn;
+
+/** Reactive participant roster for Vue hosts. @public */
+interface UseCollaborationParticipantsReturn {
+    readonly participants: Readonly<Ref<readonly CollaborationParticipant[]>>;
+}
+/**
+ * Subscribe to the participant roster of the collaboration session.
+ *
+ * Omit `session` and it reads the one the editor above holds. The ref keeps its array
+ * reference until the roster actually changes, so unrelated awareness traffic does not
+ * retrigger watchers. No session yields a stable empty array.
+ *
+ * @public
+ */
+declare function useCollaborationParticipants(session?: MaybeRefOrGetter$1<CollaborationSession | null>): UseCollaborationParticipantsReturn;
+
+/** Values {@link useCollaborationSession} returns. @public */
+interface UseCollaborationSessionReturn {
+    /** The live collaboration session of the editor above, or null. */
+    readonly session: ComputedRef<CollaborationSession | null>;
+}
+/**
+ * The live collaboration session of the editor above this component, or null.
+ *
+ * The editor already holds the session a `collaborationModule` contributed, so presence
+ * chrome reads it from here instead of being handed it: every part and composable in this
+ * package takes `session` as an OPTIONAL prop and falls back to this. A host with one Root
+ * and one room never passes it at all.
+ *
+ * Pass it explicitly when a component sits outside the Root that owns the room, or when one
+ * page renders two.
+ *
+ * @public
+ */
+declare function useCollaborationSession(): UseCollaborationSessionReturn;
+
+/**
+ * What this component needs from a room, which every collaboration composable already
+ * returns.
+ *
+ * Structural on purpose: `useHocuspocusCollaboration`, `useWebrtcCollaboration` and
+ * `useDocumentCollaboration` all satisfy it, and so does a host that owns its own resources.
+ *
+ * @public
+ */
+interface CollaborationRootSource {
+    readonly document: Uint8Array | null;
+    readonly modules: readonly EditorModule[];
+    readonly session: CollaborationSession | null;
+}
+/**
+ * Props for {@link DocxEditorCollaborationRoot}.
+ *
+ * Everything `DocxEditorRoot` takes except the three this component owns, which arrive as
+ * fallthrough attributes.
+ *
+ * @public
+ */
+interface DocxEditorCollaborationRootProps {
+    /** The room, straight from a collaboration composable. */
+    readonly collaboration: CollaborationRootSource;
+    /**
+     * Rendered before the room has a document — while connecting, or after a failure.
+     *
+     * This component does not decide what "connecting" looks like, so without the `fallback`
+     * slot nothing renders. Keep branching on the composable's `pending` and `error` for
+     * anything more specific.
+     */
+    readonly fallback?: VNode | VNode[];
+}
+/**
+ * A `DocxEditorRoot` wired to a collaboration room.
+ *
+ * ```html
+ * <DocxEditorCollaborationRoot :collaboration="collaboration">
+ *   <DocxEditorToolbar />
+ *   <DocxEditorViewport>
+ *     <DocxEditorContent />
+ *     <DocxEditorCollaboration.CaretLabels />
+ *   </DocxEditorViewport>
+ *   <template #fallback><p>Connecting…</p></template>
+ * </DocxEditorCollaborationRoot>
+ * ```
+ *
+ * The presence parts take no `session`: they read it from the editor this mounts.
+ *
+ * @public
+ */
+declare const DocxEditorCollaborationRoot: vue.DefineComponent<vue.ExtractPropTypes<{
+    collaboration: {
+        type: PropType<CollaborationRootSource>;
+        required: true;
+    };
+}>, () => VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}> | VNode<vue.RendererNode, vue.RendererElement, {
+    [key: string]: any;
+}>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+    collaboration: {
+        type: PropType<CollaborationRootSource>;
+        required: true;
+    };
+}>> & Readonly<{}>, {}, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+
+/**
+ * Full-document collaboration over the canonical primitive journal.
+ *
+ * Local direction: the canonical store commits, emits ONE journal, and the journal is applied
+ * to shared state in one Yjs transaction. Remote direction: a shared-state change materializes
+ * one canonical package, which the port publishes as one revision. The two never chase each
+ * other, because a remote publication deliberately emits no journal.
+ */
+
+/**
+ * Options for one full-document collaboration replica.
+ *
+ * The caller owns `ydoc`.
+ * @public
+ */
+interface CreateDocumentCollaborationOptions {
+    readonly ydoc: Y.Doc;
+    readonly awareness: Awareness;
+    readonly documentId: string;
+    /** Unique attachment identity. Omit it to generate a new identity for this session. */
+    readonly sessionId?: string;
+    readonly identity: CollaborationIdentity;
+    readonly bootstrap: CollaborationBootstrap;
+    /**
+     * Admit local edits while the transport is `disconnected`.
+     *
+     * A journal applies to the local `Y.Doc` either way, so buffered offline edits merge on
+     * reconnect exactly as concurrent online edits do. Off by default: a host that shows no
+     * offline indicator would let users type into a document no peer receives yet. `error`
+     * stays terminal and `initializing` stays refused regardless of this option.
+     */
+    readonly offlineEditing?: boolean;
+}
+
+/**
+ * Arguments for {@link UseDocumentCollaborationReturn.connect}: the
+ * `createDocumentCollaboration` options. The consumer owns `ydoc`, `awareness`, and
+ * whatever provider replicates them.
+ *
+ * @public
+ */
+type UseDocumentCollaborationConnectOptions = CreateDocumentCollaborationOptions;
+/** Input for {@link useDocumentCollaboration}. @public */
+interface UseDocumentCollaborationOptions {
+    /**
+     * Host modules. The composable adds `collaborationModule` when a room is ready.
+     * A host collaboration contribution is a configuration error and throws.
+     */
+    readonly modules?: readonly EditorModule[];
+    /**
+     * Connect this room when the composable starts. Omit it and call
+     * {@link UseDocumentCollaborationReturn.connect} after the host has a `ydoc` and a room.
+     */
+    readonly room?: UseDocumentCollaborationConnectOptions | null;
+}
+/** Values {@link useDocumentCollaboration} returns. @public */
+interface UseDocumentCollaborationReturn {
+    readonly document: Readonly<Ref<Uint8Array | null>>;
+    readonly modules: Readonly<Ref<readonly EditorModule[]>>;
+    readonly session: Readonly<Ref<CollaborationSession | null>>;
+    readonly pending: Readonly<Ref<boolean>>;
+    readonly error: Readonly<Ref<CollaborationFailure | null>>;
+    /**
+     * Connect a room. RESOLVES with the failure, or null on success — it does not reject.
+     *
+     * A rejection carried nothing the resolved value does not, and it made the ordinary call
+     * site wrong by default: `onClick={() => connect(options)}` produced an unhandled rejection
+     * on every failed connect. `error` reports the same failure for renderers.
+     */
+    readonly connect: (options: UseDocumentCollaborationConnectOptions) => Promise<CollaborationFailure | null>;
+    /**
+     * Destroy the session and carry on editing locally.
+     *
+     * The current bytes live in the editor, not in this composable, so the argument is
+     * required: pass `await editor.save()` to keep what the room typed. The consumer still
+     * owns `ydoc` and its provider; the composable destroys only the session it created.
+     */
+    readonly leave: (nextDocument: Uint8Array) => void;
+}
+/**
+ * Own a provider-agnostic collaboration session for a Vue host.
+ *
+ * The consumer creates the `ydoc`, the awareness, and whatever provider replicates them
+ * (WebSocket, WebRTC, offline persistence); this composable owns only the document session
+ * over them, with the same remount-safe lifecycle as `useWebrtcCollaboration`. It imports
+ * no network provider.
+ *
+ * @public
+ */
+declare function useDocumentCollaboration(options?: MaybeRefOrGetter$1<UseDocumentCollaborationOptions | null>): UseDocumentCollaborationReturn;
+
+/**
+ * What a custom remote-caret label renders with.
+ *
+ * The renderer mounts inside the adapter's provider tree, so every composable works in it —
+ * `useDocxEditor`, `useEditorState`, the review composables. It has the opened document, not
+ * only the collaborator.
+ *
+ * @public
+ */
+interface CollaborationCaretLabelRenderProps {
+    /** The remote selection this label marks, resolved into this replica's addresses. */
+    readonly selection: CollaborationRemoteSelection;
+    /** The session roster entry for the selection's actor, or null while presence catches up. */
+    readonly participant: CollaborationParticipant | null;
+    /**
+     * The resolved accent: the published colour when the engine can paint it, otherwise the
+     * review roster's colour for the name — the same resolution the painted label uses.
+     */
+    readonly color: string;
+    /**
+     * The image declared for this collaborator with `DocxEditorAuthorStyle`, or `undefined`.
+     *
+     * Presence carries no picture, so this is the host's own declaration, resolved by display
+     * name — the same key a comment card resolves. Declare it once and it reaches the caret,
+     * the avatar stack and the review card together.
+     */
+    readonly avatarUrl?: string;
+}
+/**
+ * Props for {@link DocxEditorCollaboration}.CaretLabels.
+ *
+ * The rendered content lands in the engine's label layer, which is furniture: the layer is
+ * `aria-hidden` and takes no pointer events. Assistive technology does not read a label,
+ * and nothing inside one is clickable or focusable. Keep interactive or announced presence
+ * UI in your own chrome, such as the avatar stack.
+ *
+ * @public
+ */
+interface CollaborationCaretLabelsProps {
+    /**
+     * The session whose collaborators label the carets. Omit it and the part uses the one the
+     * editor above holds; `null` renders nothing.
+     */
+    readonly session?: CollaborationSession | null;
+    /**
+     * Scoped slot: `#default="{ selection, participant, color }"`. Without it the label shows
+     * the collaborator's name, matching the engine default.
+     */
+    readonly children?: (props: CollaborationCaretLabelRenderProps) => VNode | VNode[];
+}
+/** Render props for {@link DocxEditorCollaboration}.Avatars' per-participant override. @public */
+interface CollaborationAvatarRenderProps {
+    readonly participant: CollaborationParticipant;
+    /** The resolved accent — published colour, or the review roster's colour for the name. */
+    readonly color: string;
+    /** The first letter of up to two name words, uppercased. */
+    readonly initials: string;
+    /** The image declared for this participant with `DocxEditorAuthorStyle`, or `undefined`. */
+    readonly avatarUrl?: string;
+}
+/** Props for {@link DocxEditorCollaboration}.Avatars. @public */
+interface CollaborationAvatarsProps {
+    /**
+     * The session whose participants the stack shows. Omit it and the part uses the one the
+     * editor above holds; `null` renders nothing.
+     */
+    readonly session?: CollaborationSession | null;
+    /** Avatars shown before the rest collapse into one "+N" chip. Omit to show everyone. */
+    readonly max?: number;
+    readonly className?: string;
+    /** Scoped slot: `#default="{ participant, color, initials, avatarUrl }"` replaces the disc. */
+    readonly children?: (props: CollaborationAvatarRenderProps) => VNode | VNode[];
+}
+/** Props for {@link DocxEditorCollaboration}.Avatar. @public */
+interface CollaborationAvatarProps {
+    readonly participant: CollaborationParticipant;
+    readonly className?: string;
+    /** Default slot: replaces the initials inside the disc; the accent background stays. */
+    readonly children?: VNode | VNode[];
+}
+/**
+ * Presence chrome over a live collaboration session.
+ *
+ * Compose the parts inside `DocxEditorRoot` with the collaboration module registered:
+ *
+ * @example
+ * ```html
+ * <DocxEditorCollaboration.Avatars :session="session" :max="4" />
+ * <DocxEditorCollaboration.CaretLabels :session="session" v-slot="{ selection, color }">
+ *   <MyLabel :name="selection.name" :color="color" />
+ * </DocxEditorCollaboration.CaretLabels>
+ * ```
+ *
+ * @public
+ */
+declare const DocxEditorCollaboration: {
+    /** Host-rendered remote-caret labels, with full adapter context inside each label. */
+    CaretLabels: vue.DefineComponent<vue.ExtractPropTypes<{
+        session: {
+            type: PropType<CollaborationSession | null>;
+            default: undefined;
+        };
+    }>, () => VNode<vue.RendererNode, vue.RendererElement, {
+        [key: string]: any;
+    }>[] | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+        session: {
+            type: PropType<CollaborationSession | null>;
+            default: undefined;
+        };
+    }>> & Readonly<{}>, {
+        session: CollaborationSession | null;
+    }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+    /** The packaged avatar stack, coloured to match the review module's author colours. */
+    Avatars: vue.DefineComponent<vue.ExtractPropTypes<{
+        session: {
+            type: PropType<CollaborationSession | null>;
+            default: undefined;
+        };
+        max: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        className: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>, () => VNode<vue.RendererNode, vue.RendererElement, {
+        [key: string]: any;
+    }> | null, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+        session: {
+            type: PropType<CollaborationSession | null>;
+            default: undefined;
+        };
+        max: {
+            type: NumberConstructor;
+            default: undefined;
+        };
+        className: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>> & Readonly<{}>, {
+        session: CollaborationSession | null;
+        className: string;
+        max: number;
+    }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+    /** One participant's avatar, for hosts arranging their own presence chrome. */
+    Avatar: vue.DefineComponent<vue.ExtractPropTypes<{
+        participant: {
+            type: PropType<CollaborationParticipant>;
+            required: true;
+        };
+        className: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>, () => VNode<vue.RendererNode, vue.RendererElement, {
+        [key: string]: any;
+    }>, {}, {}, {}, vue.ComponentOptionsMixin, vue.ComponentOptionsMixin, {}, string, vue.PublicProps, Readonly<vue.ExtractPropTypes<{
+        participant: {
+            type: PropType<CollaborationParticipant>;
+            required: true;
+        };
+        className: {
+            type: StringConstructor;
+            default: undefined;
+        };
+    }>> & Readonly<{}>, {
+        className: string;
+    }, {}, {}, {}, string, vue.ComponentProvideOptions, true, {}, any>;
+};
+/** @public */
+type DocxEditorCollaborationNamespace = typeof DocxEditorCollaboration;
+
 /**
  * The Standard Schema interface, vendored.
  *
@@ -1085,4 +1521,4 @@ declare function activatedCustomNodeOf(resolved: ResolvedCustomNodeActivation, e
 /** Resolves a painted pointer target to a registered custom-node definition. @public */
 declare function resolveCustomNodeActivation(target: EventTarget | null, nodes: readonly AnyCustomNodeDefinition[]): ResolvedCustomNodeActivation | null;
 
-export { CustomNodeChrome, type CustomNodeChromeProps, CustomNodeContextMenu, type CustomNodeContextMenuProps, DocxEditorReview, type DocxEditorReviewNamespace, type ProLicenseOptions, type ResolvedCustomNodeActivation, type ReviewActionProps, type ReviewItemView, type ReviewMarkersProps, type ReviewModuleOptions, type ReviewPartProps, type ReviewProps, type UseReviewReturn, activatedCustomNodeOf, resolveCustomNodeActivation, reviewModule, useCustomNodeDefinitions, useReview, useReviewAuthor, useReviewItem, useReviewOf, useStackedReviewPositions };
+export { type CollaborationAvatarProps, type CollaborationAvatarRenderProps, type CollaborationAvatarsProps, CollaborationBootstrap, type CollaborationCaretLabelRenderProps, type CollaborationCaretLabelsProps, type CollaborationModuleOptions, type CollaborationRootSource, CollaborationSession, type CreateDocumentCollaborationOptions, CustomNodeChrome, type CustomNodeChromeProps, CustomNodeContextMenu, type CustomNodeContextMenuProps, DocxEditorCollaboration, type DocxEditorCollaborationNamespace, DocxEditorCollaborationRoot, type DocxEditorCollaborationRootProps, DocxEditorReview, type DocxEditorReviewNamespace, type ProLicenseOptions, type ResolvedCustomNodeActivation, type ReviewActionProps, type ReviewItemView, type ReviewMarkersProps, type ReviewModuleOptions, type ReviewPartProps, type ReviewProps, type UseCollaborationParticipantsReturn, type UseCollaborationSessionReturn, type UseCollaborationStatusReturn, type UseDocumentCollaborationConnectOptions, type UseDocumentCollaborationOptions, type UseDocumentCollaborationReturn, type UseReviewReturn, activatedCustomNodeOf, collaborationModule, resolveCustomNodeActivation, reviewModule, useCollaborationParticipants, useCollaborationSession, useCollaborationStatus, useCustomNodeDefinitions, useDocumentCollaboration, useReview, useReviewAuthor, useReviewItem, useReviewOf, useStackedReviewPositions };