@docx-editor.dev/pro 2.0.1 → 2.1.1

package/dist/index.d.cts

@@ -1,9 +1,205 @@
-import { C as CustomNodeDefinition } from './define-custom-node-CkkDPdB0.cjs';
-export { A as ActivatedCustomNode, a as CustomNodesModuleOptions, P as ProLicenseOptions, R as RecognizedCustomNode, b as ReviewModuleOptions, c as customNodesModule, d as defineCustomNode, i as isCustomNodeDefinition, r as recognizeCustomNodes, e as reviewModule } from './define-custom-node-CkkDPdB0.cjs';
+import { A as AnyCustomNodeDefinition, C as CustomNodeDiagnostic, R as RecognizedCustomNode, S as StandardSchemaV1, I as InferSchemaInput, a as CustomNodeDefinition } from './define-custom-node-BTTX66B3.cjs';
+export { b as ActivatedCustomNode, c as CustomNode, d as CustomNodeDataRejection, e as CustomNodeDataResult, f as CustomNodePayloadSource, g as CustomNodesModuleOptions, h as InferSchemaOutput, M as MAX_CUSTOM_NODE_DATA_LENGTH, P as ProLicenseOptions, i as RecognizeCustomNodesOptions, j as ReviewModuleOptions, k as StandardSchemaIssue, l as StandardSchemaResult, m as customNodesModule, n as defineCustomNode, o as isCustomNodeDefinition, p as parseCustomNodeData, r as recognizeCustomNodes, q as reviewModule, s as serializeCustomNodeData } from './define-custom-node-BTTX66B3.cjs';
 import { Editor, ExecResult } from '@docx-editor.dev/core/contracts/editor';
 import '@docx-editor.dev/core/editor';
 import '@docx-editor.dev/core/store';
 
+/** How {@link customNodesOf} narrows what it answers. */
+interface CustomNodesOfOptions {
+    /**
+     * Which definitions to recognize. Defaults to everything registered on the editor, which is
+     * what a host almost always wants — passing a subset answers only those.
+     */
+    readonly nodes?: readonly AnyCustomNodeDefinition[];
+    /**
+     * Told about a node whose payload could not be read.
+     *
+     * Defaults to the listeners the editor's own modules registered, so a host that passed
+     * `onDiagnostic` to `customNodesModule` hears from this call too without repeating itself.
+     */
+    readonly onDiagnostic?: (diagnostic: CustomNodeDiagnostic) => void;
+}
+/**
+ * Every recognized custom node in the editor's body, in document order, with its payload.
+ *
+ * ```ts
+ * for (const node of customNodesOf(editor)) {
+ *   const citation = Citation.dataOf(node);
+ *   if (citation) index.add(citation.sourceId);
+ * }
+ * ```
+ *
+ * Reads the body story. A node in a header or footer is not answered here — the same limit
+ * `recognizeCustomNodes` has, since it takes one part.
+ *
+ * Derived fresh on every call from the canonical package: there is no cache to go stale, and no
+ * change event either, so re-read after an edit rather than holding the array.
+ */
+declare function customNodesOf(editor: Editor, options?: CustomNodesOfOptions): readonly RecognizedCustomNode[];
+
+/**
+ * The exported document, or the reason there is not one.
+ *
+ * A refusal answers no bytes. "Stripping failed, here are the bytes anyway" is the one outcome
+ * that must not be possible: a caller would ship the markup it asked to remove and have been
+ * told the export succeeded.
+ *
+ * @public
+ */
+type DocumentExportResult = {
+    readonly ok: true;
+    readonly bytes: Uint8Array;
+    /** Controls unwrapped to their text, and controls removed outright. */
+    readonly unwrapped: number;
+    readonly removed: number;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Where this copy of the document is going.
+ *
+ * The distinction the whole option exists for, made explicit at the call site so a host writes
+ * intent rather than remembering which function strips:
+ *
+ *  - `internal` — the copy you keep. Your own storage, your own system, a draft a user will
+ *    reopen HERE. Nothing is stripped, because a stripped copy reopens as plain text and the
+ *    chips are gone for good.
+ *  - `external` — the copy that leaves. A download, an email attachment, a hand-off to someone
+ *    who does not run this library. `preserveOnExport` decides what travels.
+ *
+ * A UI with one Download button and a "keep our markup" checkbox drives both from one call.
+ *
+ * @public
+ */
+type DocumentDestination = 'internal' | 'external';
+/** How {@link saveForExport} and {@link prepareForExport} treat this copy. */
+interface DocumentExportOptions {
+    /**
+     * Defaults to `external`, because that is what calling an export function means.
+     *
+     * `internal` answers the bytes unchanged — the identity case, present so a caller with one
+     * code path and a runtime choice does not need two.
+     */
+    readonly destination?: DocumentDestination;
+}
+/**
+ * Apply every definition's `preserveOnExport` to a document, and answer the bytes to ship.
+ *
+ * The BYTES form, for a caller with no editor: a request handler, a queue worker, a build step, a
+ * document `customNodeXml` authored server-side. In a browser with an editor mounted, reach for
+ * {@link saveForExport} instead — it reads the definitions off the editor, so a node cannot leave
+ * because the list passed here forgot it.
+ *
+ * `true` (the default) leaves a node untouched. `'text'` unwraps the control, keeping the words
+ * and dropping the tag, the binding and the payload. `false` removes the node with its content.
+ * A tag no definition claims is never touched — this is a host applying its own policy to its
+ * own markup, not a scrub of the document.
+ *
+ * ```ts
+ * const generated = await renderContract(order);
+ * const outgoing = prepareForExport(generated, [Clause, InternalNote]);
+ * if (outgoing.ok) await email.attach(outgoing.bytes);
+ * ```
+ *
+ * Applied to EVERY story, so a chip in a header is treated like a chip in the body. The payload
+ * stores hang off the main document part, which is where Word enumerates its data store from, so
+ * that is the only part they are cleaned up against.
+ */
+declare function prepareForExport(bytes: Uint8Array, definitions: readonly AnyCustomNodeDefinition[], options?: DocumentExportOptions): DocumentExportResult;
+
+/**
+ * How {@link saveForExport} treats this copy.
+ *
+ * @public
+ */
+interface SaveForExportOptions extends DocumentExportOptions {
+    /**
+     * Which definitions to apply. Defaults to everything registered on the editor, which is the
+     * answer a host almost always wants — passing a subset leaves the rest untouched, and an
+     * untouched node travels whole.
+     */
+    readonly nodes?: readonly AnyCustomNodeDefinition[];
+}
+/**
+ * Save the document as the copy that leaves your system.
+ *
+ * NOT THE DEFAULT PATH. A custom node is an ordinary inline content control: Word and Word Online
+ * both render its text and hand the tag, binding and payload back unchanged, so `editor.save()`
+ * already produces a file that opens correctly for a recipient who has never heard of this
+ * library. This is for the narrower case where the recipient should not have the nodes at all —
+ * internal annotations that must not leave, markup that means nothing outside your system.
+ *
+ * `editor.save()` is the copy you keep — every node intact, reopens here with the chips working.
+ * This is its pair: the same document with each definition's `preserveOnExport` applied, for a
+ * download, an attachment, or a hand-off you want stripped.
+ *
+ * ```ts
+ * await storage.put(docId, new Uint8Array(await editor.save())); // yours
+ *
+ * const outgoing = await saveForExport(editor);                  // theirs
+ * if (outgoing.ok) download(outgoing.bytes);
+ * ```
+ *
+ * Store the saved bytes, never these. What the export stripped is gone for good: unwrapped text
+ * does not become a node again. Produce this copy fresh from the saved one each time you hand
+ * one out.
+ *
+ * Definitions come from the editor's registered modules, so a node cannot leave because a list
+ * forgot it. On a server, where there is no editor, use `prepareForExport` with an explicit list.
+ *
+ * @public
+ */
+declare function saveForExport(editor: Editor, options?: SaveForExportOptions): Promise<DocumentExportResult>;
+
+/**
+ * One field a payload got wrong.
+ *
+ * `path` is the route to it — `['authors', 0, 'name']` — which is what a form needs to find the
+ * input to mark. Empty for an issue about the payload as a whole.
+ *
+ * @public
+ */
+interface CustomNodeIssue {
+    readonly message: string;
+    readonly path: readonly (string | number)[];
+    /** `authors.0.name`, for a log line or a message. Derived from `path`. */
+    readonly pointer: string;
+}
+/**
+ * What {@link insertCustomNode} and {@link updateCustomNode} answer.
+ *
+ * The engine's `ExecResult`, plus `issues` when the refusal was a schema failure. A host that
+ * only branches on `ok` sees no difference.
+ *
+ * @public
+ */
+type CustomNodeWriteOutcome = (Extract<ExecResult, {
+    ok: true;
+}> & {
+    /**
+     * The control this write authored. A rewrite replaces the control rather than editing it,
+     * so the id passed to `updateCustomNode` names nothing afterwards — re-point anything
+     * attached to that node at this one.
+     */
+    readonly nodeId?: string;
+}) | (Extract<ExecResult, {
+    ok: false;
+}> & {
+    /** Present only for a payload the definition's schema refused. */
+    readonly issues?: readonly CustomNodeIssue[];
+});
+
+/** The local name of every payload store this library authors. */
+declare const CUSTOM_NODE_STORE_ROOT = "docxEditor";
+/**
+ * The namespace a definition's payloads live in.
+ *
+ * Keyed on `tagPrefix` rather than on `name`, so one integrator's nodes share one store. A
+ * document with a citation and a figure carries one customXml part, not two.
+ */
+declare function customNodeNamespace(definition: AnyCustomNodeDefinition): string;
+
 /** Word refuses to store more than 64 characters in `w:tag`. */
 declare const MAX_TAG_LENGTH = 64;
 /**
@@ -52,46 +248,67 @@ interface DecodedCustomNodeTag {
 declare function decodeCustomNodeTag(tag: string): DecodedCustomNodeTag | null;
 
 /**
- * How {@link insertCustomNode} places a node.
+ * What a node says and where it goes — one object, so the parts cannot be passed in the wrong
+ * order or get out of step.
  *
- * Every field is optional: the ordinary call inserts at the caret with `contentLocked`, which is
- * the behaviour that keeps a chip's label from drifting out of sync with its attrs while leaving
- * the node deletable as one unit.
+ * A definition with `text` needs only `data`: what the document shows is computed from it.
+ *
+ * ```ts
+ * insertCustomNode(editor, Citation, { data: citation });                 // text derives
+ * insertCustomNode(editor, Tag, { attrs: { id: 'x' }, text: '[tag]' });   // no payload
+ * ```
  *
  * @public
  */
-interface InsertCustomNodeOptions {
+interface CustomNodeInput<Schema extends StandardSchemaV1 | undefined = any> {
+    /**
+     * The node's payload: everything that does not fit in 64 characters of `w:tag`.
+     *
+     * Written into a customXml data part and bound to the control, in the SAME transaction as the
+     * control itself. Validated against the definition's `schema` first, so a payload that does
+     * not match is refused here — with the failing fields in `issues` — rather than written and
+     * rejected on the next open.
+     */
+    readonly data?: InferSchemaInput<Schema>;
     /**
-     * Where to insert. Omitted, the node lands at the current selection HEAD —
-     * the programmatic mirror of "type a citation at the caret".
+     * The `w:tag` attrs. Derived by the definition's `tagAttrs` when it declares one.
+     *
+     * Word caps the encoded tag at 64 characters, so this is the node's IDENTITY and nothing else.
+     */
+    readonly attrs?: Readonly<Record<string, string>>;
+    /** What the document shows. Derived by the definition's `text` when it declares one. */
+    readonly text?: string;
+    /**
+     * Where to insert. Omitted, the node lands at the current selection HEAD — the programmatic
+     * mirror of "type a citation at the caret".
      */
     readonly at?: {
         readonly paragraphId: string;
         readonly offset: number;
     };
     /**
-     * The `w:lock` written on the control. Defaults to `contentLocked` — the text
-     * is locked so the label cannot drift out of sync with the attrs by inline
-     * typing (editing goes through the `onEdit` flow), while the node itself stays
-     * DELETABLE as one unit, in the editor and in Word alike. `false` writes no
-     * lock; `sdtContentLocked` also forbids deleting the node.
+     * The `w:lock` written on the control. Defaults to `contentLocked` — the text is locked so the
+     * label cannot drift out of sync with the attrs by inline typing, while the node itself stays
+     * DELETABLE as one unit, in the editor and in Word alike. `false` writes no lock;
+     * `sdtContentLocked` also forbids deleting the node.
+     *
+     * A node carrying a payload is uneditable whatever this says: the engine refuses content edits
+     * inside a bound control, and so does Word.
      */
     readonly lock?: false | 'sdtLocked' | 'sdtContentLocked' | 'contentLocked';
-    /**
-     * `w:alias` — the human title Word shows on the control, and what the
-     * engine's control chrome uses as its floating label.
-     */
+    /** `w:alias` — the human title Word shows on the control, and the chrome's floating label. */
     readonly alias?: string;
 }
 /**
- * Insert one custom node. Returns the engine's typed result: refusals carry the
- * engine's own reason (tag overflow, offset out of range, viewing mode, …).
+ * Insert one custom node. Returns the engine's typed result: refusals carry the engine's own
+ * reason (tag overflow, offset out of range, viewing mode, …), and a payload the schema refused
+ * carries the failing fields in `issues`.
  *
  * ```ts
- * insertCustomNode(editor, citation, { sourceId: 'src_9f3' }, '(Smith 2024)');
+ * insertCustomNode(editor, citation, { data: { sourceId: 'src_9f3', year: 2024 } });
  * ```
  */
-declare function insertCustomNode(editor: Editor, definition: CustomNodeDefinition, attrs: Readonly<Record<string, string>>, text: string, options?: InsertCustomNodeOptions): ExecResult;
+declare function insertCustomNode<Schema extends StandardSchemaV1 | undefined = undefined>(editor: Editor, definition: CustomNodeDefinition<Schema>, input?: CustomNodeInput<Schema>): CustomNodeWriteOutcome;
 
 /**
  * Delete one custom node — wrapper AND content, one undo step.
@@ -99,28 +316,42 @@ declare function insertCustomNode(editor: Editor, definition: CustomNodeDefiniti
  * The default `contentLocked` chip deletes fine (the lock guards its characters, not its
  * existence); a `sdtLocked`/`sdtContentLocked` wrapper refuses with the engine's reason.
  */
-declare function removeCustomNode(editor: Editor, nodeId: string): ExecResult;
+declare function removeCustomNode(editor: Editor, nodeId: string): CustomNodeWriteOutcome;
 /**
  * How {@link updateCustomNode} rewrites the control it replaces.
  *
+ * The same shape {@link CustomNodeInput} takes, minus `at` — an update happens where the node
+ * already is — and with `data` able to be `null`.
+ *
  * @public
  */
-interface UpdateCustomNodeOptions {
-    /** `w:alias` for the rewritten control. */
-    readonly alias?: string;
-    /** `w:lock` for the rewritten control. Defaults to `contentLocked`, like the insert. */
-    readonly lock?: false | 'sdtLocked' | 'sdtContentLocked' | 'contentLocked';
+interface CustomNodeUpdate<Schema extends StandardSchemaV1 | undefined = undefined> extends Omit<CustomNodeInput<Schema>, 'at' | 'data'> {
+    /**
+     * The payload the rewritten node carries.
+     *
+     * Written in the SAME transaction as the label, so an update cannot leave the two
+     * disagreeing — which is the one way a bound chip could ever show text its payload does not
+     * describe.
+     *
+     * OMITTING IT KEEPS THE PAYLOAD the node already had. That is the important default: the
+     * commonest update is a label edit, and an omission that dropped the citation's authors and
+     * year would be data loss the caller never asked for and could not see. Pass `null` to remove
+     * the payload deliberately.
+     *
+     * A definition with `text` re-derives what the document shows from whichever payload ends up
+     * being written, so `updateCustomNode(editor, def, id, { data })` rewrites both together.
+     */
+    readonly data?: InferSchemaInput<Schema> | null;
 }
 /**
- * Replace one custom node's attrs and text in place: the node is removed and a fresh one
- * with the new tag and label is inserted at its own span — ONE transaction, one undo step,
- * recognized by construction like `insertCustomNode`.
+ * Replace one custom node in place: the node is removed and a fresh one is inserted at its own
+ * span — ONE transaction, one undo step, recognized by construction like `insertCustomNode`.
  *
  * ```ts
- * updateCustomNode(editor, citation, node.nodeId, { sourceId: 'src_2' }, '(Jones 2025)');
+ * updateCustomNode(editor, citation, node.nodeId, { data: { ...citation, year: 2025 } });
  * ```
  */
-declare function updateCustomNode(editor: Editor, definition: CustomNodeDefinition, nodeId: string, attrs: Readonly<Record<string, string>>, text: string, options?: UpdateCustomNodeOptions): ExecResult;
+declare function updateCustomNode<Schema extends StandardSchemaV1 | undefined = undefined>(editor: Editor, definition: CustomNodeDefinition<Schema>, nodeId: string, update?: CustomNodeUpdate<Schema>): CustomNodeWriteOutcome;
 
 /**
  * How {@link customNodeXml} writes the control, for server-side templating where there is no
@@ -128,7 +359,7 @@ declare function updateCustomNode(editor: Editor, definition: CustomNodeDefiniti
  *
  * @public
  */
-interface CustomNodeXmlOptions {
+interface CustomNodeXmlOptions<Schema extends StandardSchemaV1 | undefined = undefined> {
     /** `w:alias` — the human title Word shows on the control. */
     readonly alias?: string;
     /** `w:lock`. Defaults to `contentLocked`, matching `insertCustomNode`. `false` omits it. */
@@ -140,6 +371,60 @@ interface CustomNodeXmlOptions {
      * open, but a caller splicing many copies of the same node can pass distinct ids.
      */
     readonly id?: number;
+    /**
+     * The node's payload — everything past the 64 characters `w:tag` holds.
+     *
+     * A template engine can splice markup but cannot author a package, so this cannot write the
+     * data part itself. It answers the part CONTENTS instead (see {@link CustomNodeXmlStore}) and
+     * the caller adds them to the zip it is assembling. The markup and the parts agree by
+     * construction: the same `ds:itemID` is minted once and written into both.
+     */
+    readonly data?: InferSchemaInput<Schema>;
+    /**
+     * Which `/customXml/itemN.xml` this store claims. Defaults to 1.
+     *
+     * A caller splicing into a template that ALREADY carries a store — Word's Cover Page
+     * Properties rides in most of them — has to pick a free index, and only the caller can see
+     * the package to know which one is free.
+     */
+    readonly storeIndex?: number;
+    /**
+     * The node's id inside the store, which the binding's xpath quotes. Defaults to `cx1`.
+     *
+     * Splicing several nodes into one document means several ids: two nodes sharing one makes
+     * the xpath ambiguous, and Word resolves an ambiguous xpath to the first match — so the
+     * second chip would paint the first one's text forever.
+     */
+    readonly nodeId?: string;
+}
+/**
+ * The package a spliced payload needs, as parts a caller adds to the zip it is assembling.
+ *
+ * Everything here is required. A control carrying a `w:dataBinding` whose store is missing is a
+ * document Word opens and offers to repair, and repairing it throws the control away.
+ *
+ * @public
+ */
+interface CustomNodeXmlStore {
+    /** `/customXml/itemN.xml` — the payload itself. Rides the package's `xml` content-type default. */
+    readonly itemPartName: string;
+    readonly itemXml: string;
+    /** `/customXml/itemPropsN.xml` — carries the `ds:itemID` the binding quotes. */
+    readonly propsPartName: string;
+    readonly propsXml: string;
+    /** The `ds:itemID`, which is also the `w:storeItemID` already written into the markup. */
+    readonly storeItemId: string;
+    /** Relationships the caller must declare, each from the part named to the target named. */
+    readonly relationships: readonly {
+        readonly from: string;
+        readonly type: string;
+        readonly target: string;
+    }[];
+    /** The content-type Override the properties part needs. `itemN.xml` needs none. */
+    readonly contentTypeOverride: {
+        readonly partName: string;
+        readonly contentType: string;
+    };
 }
 /**
  * What {@link customNodeXml} answers: the `w:sdt` markup, or a refusal.
@@ -152,6 +437,8 @@ interface CustomNodeXmlOptions {
 type CustomNodeXmlResult = {
     readonly ok: true;
     readonly xml: string;
+    /** Present only when `data` was given. Absent means the node carries no payload. */
+    readonly store?: CustomNodeXmlStore;
 } | {
     readonly ok: false;
     readonly code: 'invalidArgs';
@@ -170,6 +457,6 @@ type CustomNodeXmlResult = {
  * if (sdt.ok) template.replace('{{citation}}', sdt.xml);
  * ```
  */
-declare function customNodeXml(definition: CustomNodeDefinition, attrs: Readonly<Record<string, string>>, text: string, options?: CustomNodeXmlOptions): CustomNodeXmlResult;
+declare function customNodeXml<Schema extends StandardSchemaV1 | undefined = undefined>(definition: CustomNodeDefinition<Schema>, attrs: Readonly<Record<string, string>>, text: string, options?: CustomNodeXmlOptions<Schema>): CustomNodeXmlResult;
 
-export { CustomNodeDefinition, type CustomNodeXmlOptions, type CustomNodeXmlResult, type DecodedCustomNodeTag, type EncodeTagResult, type InsertCustomNodeOptions, MAX_TAG_LENGTH, type UpdateCustomNodeOptions, customNodeXml, decodeCustomNodeTag, encodeCustomNodeTag, insertCustomNode, removeCustomNode, updateCustomNode };
+export { AnyCustomNodeDefinition, CUSTOM_NODE_STORE_ROOT, CustomNodeDefinition, CustomNodeDiagnostic, type CustomNodeInput, type CustomNodeIssue, type CustomNodeUpdate, type CustomNodeWriteOutcome, type CustomNodeXmlOptions, type CustomNodeXmlResult, type CustomNodeXmlStore, type CustomNodesOfOptions, type DecodedCustomNodeTag, type DocumentDestination, type DocumentExportOptions, type DocumentExportResult, type EncodeTagResult, InferSchemaInput, MAX_TAG_LENGTH, RecognizedCustomNode, type SaveForExportOptions, StandardSchemaV1, customNodeNamespace, customNodeXml, customNodesOf, decodeCustomNodeTag, encodeCustomNodeTag, insertCustomNode, prepareForExport, removeCustomNode, saveForExport, updateCustomNode };