@eigenpal/docx-editor-core 1.1.0 → 1.2.0

package/dist/{content-CmqAwdFL.d.ts → content-CYXJ2tfQ.d.ts}

@@ -516,111 +516,6 @@ interface Table {
     rows: TableRow[];
 }
 
-/**
- * Structured Document Tags / content controls (`w:sdt`) — inline and
- * block variants, plus properties (alias, tag, lock, list items,
- * checkbox state) for the supported SDT types.
- */
-
-/**
- * SDT type (content control type)
- */
-type SdtType = 'richText' | 'plainText' | 'date' | 'dropdown' | 'comboBox' | 'checkbox' | 'picture' | 'buildingBlockGallery' | 'group' | 'unknown';
-/**
- * SDT properties (w:sdtPr)
- */
-interface SdtProperties {
-    /** SDT type */
-    sdtType: SdtType;
-    /** Alias (friendly name) */
-    alias?: string;
-    /** Tag (developer identifier) */
-    tag?: string;
-    /** Lock content editing */
-    lock?: 'sdtLocked' | 'contentLocked' | 'sdtContentLocked' | 'unlocked';
-    /** Placeholder text */
-    placeholder?: string;
-    /** Whether showing placeholder */
-    showingPlaceholder?: boolean;
-    /** Date format for date controls */
-    dateFormat?: string;
-    /** Dropdown/combobox list items */
-    listItems?: {
-        displayText: string;
-        value: string;
-    }[];
-    /** Checkbox checked state */
-    checked?: boolean;
-}
-/**
- * Inline SDT (content control within a paragraph)
- */
-interface InlineSdt {
-    type: 'inlineSdt';
-    /** SDT properties */
-    properties: SdtProperties;
-    /**
-     * Inline content held inside the control. OOXML allows runs,
-     * hyperlinks, simple/complex fields, nested SDTs, and math at this
-     * level; the renderer must descend into all of them so docProps-bound
-     * fields and similar template content survive paged rendering.
-     */
-    content: (Run | Hyperlink | SimpleField | ComplexField | InlineSdt | MathEquation)[];
-}
-/**
- * Block-level SDT (content control wrapping paragraphs/tables)
- */
-interface BlockSdt {
-    type: 'blockSdt';
-    /** SDT properties */
-    properties: SdtProperties;
-    /** Block content inside the control */
-    content: (Paragraph | Table)[];
-}
-
-/**
- * Comments (`w:comment` in `comments.xml`) and the inline range markers
- * (`w:commentRangeStart`/`End`) that anchor them inside paragraphs.
- */
-
-/**
- * A comment from `comments.xml` — the top-level entity for review
- * comments and replies. `id` matches the inline `CommentRangeStart` /
- * `CommentRangeEnd` markers that anchor it inside a paragraph; `parentId`
- * threads replies under their parent; `done` reflects Word's "Resolve"
- * state (`w15:done`).
- */
-interface Comment {
-    /** Comment ID (matches commentRangeStart/End) */
-    id: number;
-    /** Author name */
-    author: string;
-    /** Author initials */
-    initials?: string;
-    /** Date */
-    date?: string;
-    /** Comment content (paragraphs) */
-    content: Paragraph[];
-    /** Parent comment ID (for replies) */
-    parentId?: number;
-    /** Whether the comment is resolved/done */
-    done?: boolean;
-}
-/**
- * Comment range start marker in paragraph content
- */
-interface CommentRangeStart {
-    type: 'commentRangeStart';
-    id: number;
-}
-/**
- * Comment range end marker in paragraph content
- */
-interface CommentRangeEnd {
-    type: 'commentRangeEnd';
-    id: number;
-}
-
 /**
  * Page furniture — headers (`w:hdr`), footers (`w:ftr`), footnotes
  * (`w:footnote`), and endnotes (`w:endnote`), plus the section-level
@@ -650,7 +545,7 @@ interface HeaderFooter {
     /** Header/footer type */
     hdrFtrType: HeaderFooterType;
     /** Content (paragraphs, tables, etc.) */
-    content: (Paragraph | Table)[];
+    content: BlockContent[];
 }
 /**
  * Footnote position
@@ -698,7 +593,7 @@ interface Footnote {
      * widened to match HeaderFooter / TableCell shape so the body pipeline
      * (toProseDoc → toFlowBlocks) can render them uniformly.
      */
-    content: (Paragraph | Table)[];
+    content: BlockContent[];
 }
 /**
  * Endnote (w:endnote)
@@ -713,7 +608,50 @@ interface Endnote {
      * Content. Per ECMA-376 §17.11.4 endnotes can hold the same blocks as
      * the body — paragraphs and tables. See note on `Footnote.content`.
      */
-    content: (Paragraph | Table)[];
+    content: BlockContent[];
+}
+
+/**
+ * Comments (`w:comment` in `comments.xml`) and the inline range markers
+ * (`w:commentRangeStart`/`End`) that anchor them inside paragraphs.
+ */
+
+/**
+ * A comment from `comments.xml` — the top-level entity for review
+ * comments and replies. `id` matches the inline `CommentRangeStart` /
+ * `CommentRangeEnd` markers that anchor it inside a paragraph; `parentId`
+ * threads replies under their parent; `done` reflects Word's "Resolve"
+ * state (`w15:done`).
+ */
+interface Comment {
+    /** Comment ID (matches commentRangeStart/End) */
+    id: number;
+    /** Author name */
+    author: string;
+    /** Author initials */
+    initials?: string;
+    /** Date */
+    date?: string;
+    /** Comment content (paragraphs) */
+    content: Paragraph[];
+    /** Parent comment ID (for replies) */
+    parentId?: number;
+    /** Whether the comment is resolved/done */
+    done?: boolean;
+}
+/**
+ * Comment range start marker in paragraph content
+ */
+interface CommentRangeStart {
+    type: 'commentRangeStart';
+    id: number;
+}
+/**
+ * Comment range end marker in paragraph content
+ */
+interface CommentRangeEnd {
+    type: 'commentRangeEnd';
+    id: number;
 }
 
 /**
@@ -888,6 +826,126 @@ interface DocumentBody {
     comments?: Comment[];
 }
 
+/**
+ * Structured Document Tags / content controls (`w:sdt`) — inline and
+ * block variants, plus properties (alias, tag, lock, list items,
+ * checkbox state) for the supported SDT types.
+ */
+
+/**
+ * SDT type (content control type).
+ *
+ * Values mirror the `w:sdtPr` type-marker element names from ECMA-376
+ * §17.5.2 (`CT_SdtPr`), with two deliberate exceptions:
+ * - `checkbox` is the `w14:checkbox` (Office 2010) extension, not a base
+ *   OOXML type marker.
+ * - `buildingBlockGallery` covers both `w:docPartObj` and `w:docPartList`.
+ *
+ * A `w:sdtPr` with no type marker means `richText` (the spec default). A
+ * type marker the parser does not model maps to `unknown` — it is never
+ * coerced to `richText`, so the projection stays honest. Round-trip
+ * fidelity does not depend on this enum: the raw `w:sdtPr` is replayed
+ * verbatim (see `rawPropertiesXml`).
+ */
+type SdtType = 'richText' | 'plainText' | 'date' | 'dropDownList' | 'comboBox' | 'checkbox' | 'picture' | 'buildingBlockGallery' | 'group' | 'equation' | 'citation' | 'bibliography' | 'unknown';
+/**
+ * XML data binding (`w:dataBinding`) — links a content control to a node in a
+ * Custom XML data store. Modeled read-only; the binding round-trips verbatim
+ * via `rawPropertiesXml` (this projection is for inspection, e.g. "which
+ * controls are bound, and to what XPath"). The editor does not resolve or
+ * sync bound values.
+ */
+interface SdtDataBinding {
+    /** XPath into the bound Custom XML part (`w:xpath`). */
+    xpath?: string;
+    /** Target Custom XML store id (`w:storeItemID`). */
+    storeItemID?: string;
+    /** Namespace prefix mappings used by the XPath (`w:prefixMappings`). */
+    prefixMappings?: string;
+}
+/**
+ * SDT properties (`w:sdtPr`).
+ *
+ * The modeled fields are a **read-only projection** for downstream tooling
+ * (tag/alias addressing, template extraction). They are NOT the
+ * serialization source: the original `w:sdtPr` is captured verbatim in
+ * `rawPropertiesXml` and replayed on save, which preserves element order
+ * (`CT_SdtPr` is an `xsd:sequence`), avoids double-emission, and keeps
+ * unmodeled features (data binding, `w15:*`, `@lastValue`) lossless.
+ */
+interface SdtProperties {
+    /** SDT type (projection; see {@link SdtType}). */
+    sdtType: SdtType;
+    /** Unique numeric id (`w:id`, signed). */
+    id?: number;
+    /** Alias (friendly name, `w:alias`). */
+    alias?: string;
+    /** Tag (developer identifier, `w:tag`). */
+    tag?: string;
+    /** Lock setting (`w:lock`). */
+    lock?: 'sdtLocked' | 'contentLocked' | 'sdtContentLocked' | 'unlocked';
+    /**
+     * Placeholder building-block name (`w:placeholder/w:docPart@w:val`).
+     * This is a reference to a glossary docPart that supplies the placeholder
+     * content — NOT the literal placeholder text.
+     */
+    placeholder?: string;
+    /** Whether the control is currently showing its placeholder (`w:showingPlcHdr`). */
+    showingPlaceholder?: boolean;
+    /** Date format for date controls (`w:date@w:fullDate`). */
+    dateFormat?: string;
+    /** Dropdown/combobox list items. */
+    listItems?: {
+        displayText: string;
+        value: string;
+    }[];
+    /** Checkbox checked state (`w14:checkbox`). */
+    checked?: boolean;
+    /** XML data binding (`w:dataBinding`), if the control is bound. */
+    dataBinding?: SdtDataBinding;
+    /**
+     * The original `<w:sdtPr>` serialized verbatim as an XML string, captured
+     * at parse time. Replayed unchanged on save so the properties block
+     * round-trips losslessly. Stored as a string (not an `XmlElement`) so the
+     * types layer stays free of the parser/`xml-js` dependency. Absent for
+     * SDTs created programmatically — the serializer then synthesizes a
+     * minimal, sequence-valid `w:sdtPr` from the modeled fields.
+     */
+    rawPropertiesXml?: string;
+    /** The original `<w:sdtEndPr>` serialized verbatim, if present. */
+    rawEndPropertiesXml?: string;
+}
+/**
+ * Inline SDT (content control within a paragraph)
+ */
+interface InlineSdt {
+    type: 'inlineSdt';
+    /** SDT properties */
+    properties: SdtProperties;
+    /**
+     * Inline content held inside the control. OOXML allows runs,
+     * hyperlinks, simple/complex fields, nested SDTs, and math at this
+     * level; the renderer must descend into all of them so docProps-bound
+     * fields and similar template content survive paged rendering.
+     */
+    content: (Run | Hyperlink | SimpleField | ComplexField | InlineSdt | MathEquation)[];
+}
+/**
+ * Block-level SDT (content control wrapping block content).
+ *
+ * `content` is `BlockContent[]` (not just paragraphs/tables) so a nested
+ * block SDT survives the round trip. `CT_SdtContentBlock` also permits
+ * run-level content (bookmarks, etc.); that is carried through the same
+ * block-content parsing as elsewhere in the document.
+ */
+interface BlockSdt {
+    type: 'blockSdt';
+    /** SDT properties */
+    properties: SdtProperties;
+    /** Block content inside the control */
+    content: BlockContent[];
+}
+
 /**
  * Paragraph (`w:p`) — the union of inline content that can sit inside a
  * paragraph (runs, hyperlinks, bookmarks, fields, SDT, comment ranges,
@@ -1357,4 +1415,4 @@ interface Run {
     content: RunContent[];
 }
 
-export type { ImagePadding as $, AbstractNumbering as A, BlockContent as B, Comment as C, Deletion as D, Endnote as E, Footnote as F, DrawingContent as G, Hyperlink as H, Image as I, EndnotePosition as J, EndnoteProperties as K, ListLevel as L, MoveFrom as M, NumberingDefinitions as N, Field as O, Paragraph as P, FieldCharContent as Q, Run as R, SectionProperties as S, Table as T, FieldType as U, FooterReference as V, FootnotePosition as W, FootnoteProperties as X, HeaderFooterType as Y, HeaderReference as Z, ImageCrop as _, CommentRangeEnd as a, ImagePosition as a0, ImageSize as a1, ImageTransform as a2, ImageWrap as a3, InlineSdt as a4, InstrTextContent as a5, LevelSuffix as a6, LineNumberRestart as a7, ListRendering as a8, MathEquation as a9, TextBox as aA, VerticalAlign as aB, MoveFromRangeEnd as aa, MoveFromRangeStart as ab, MoveToRangeEnd as ac, MoveToRangeStart as ad, NoBreakHyphenContent as ae, NoteNumberRestart as af, NoteReferenceContent as ag, NumberingInstance as ah, PageOrientation as ai, PropertyChangeInfo as aj, RunPropertyChange as ak, SdtProperties as al, SdtType as am, Section as an, SectionStart as ao, Shape as ap, ShapeContent as aq, ShapeFill as ar, ShapeOutline as as, ShapeTextBody as at, ShapeType as au, SimpleField as av, SoftHyphenContent as aw, SymbolContent as ax, TabContent as ay, TableStructuralChangeInfo as az, CommentRangeStart as b, DocumentBody as c, Insertion as d, MoveTo as e, ParagraphContent as f, RunContent as g, TableCell as h, TableRow as i, TextContent as j, TrackedChangeInfo as k, TrackedRunChange as l, RevisionInfo as m, CellMarker as n, NumberFormat as o, ParagraphPropertyChange as p, TablePropertyChange as q, TableCellPropertyChange as r, TableRowPropertyChange as s, BreakContent as t, HeaderFooter as u, BlockSdt as v, BookmarkEnd as w, BookmarkStart as x, Column as y, ComplexField as z };
+export type { HeaderFooterType as $, AbstractNumbering as A, BlockContent as B, Comment as C, Deletion as D, Endnote as E, Footnote as F, BookmarkStart as G, Hyperlink as H, Image as I, Column as J, ComplexField as K, ListLevel as L, MoveFrom as M, NumberingDefinitions as N, DrawingContent as O, Paragraph as P, EndnotePosition as Q, Run as R, SectionProperties as S, Table as T, EndnoteProperties as U, Field as V, FieldCharContent as W, FieldType as X, FooterReference as Y, FootnotePosition as Z, FootnoteProperties as _, CommentRangeEnd as a, HeaderReference as a0, ImageCrop as a1, ImagePadding as a2, ImagePosition as a3, ImageSize as a4, ImageTransform as a5, ImageWrap as a6, InlineSdt as a7, InstrTextContent as a8, LevelSuffix as a9, TableStructuralChangeInfo as aA, TextBox as aB, VerticalAlign as aC, LineNumberRestart as aa, ListRendering as ab, MathEquation as ac, MoveFromRangeEnd as ad, MoveFromRangeStart as ae, MoveToRangeEnd as af, MoveToRangeStart as ag, NoBreakHyphenContent as ah, NoteNumberRestart as ai, NoteReferenceContent as aj, NumberingInstance as ak, PageOrientation as al, PropertyChangeInfo as am, RunPropertyChange as an, Section as ao, SectionStart as ap, Shape as aq, ShapeContent as ar, ShapeFill as as, ShapeOutline as at, ShapeTextBody as au, ShapeType as av, SimpleField as aw, SoftHyphenContent as ax, SymbolContent as ay, TabContent as az, CommentRangeStart as b, DocumentBody as c, Insertion as d, MoveTo as e, ParagraphContent as f, RunContent as g, TableCell as h, TableRow as i, TextContent as j, TrackedChangeInfo as k, TrackedRunChange as l, RevisionInfo as m, CellMarker as n, NumberFormat as o, ParagraphPropertyChange as p, TablePropertyChange as q, TableCellPropertyChange as r, TableRowPropertyChange as s, SdtType as t, SdtProperties as u, SdtDataBinding as v, BlockSdt as w, BreakContent as x, HeaderFooter as y, BookmarkEnd as z };

package/dist/contentControlValues-DAwTWfgR.d.mts

@@ -0,0 +1,187 @@
+import { Document } from './types/document.mjs';
+import { t as SdtType, u as SdtProperties, v as SdtDataBinding, c as DocumentBody, w as BlockSdt, B as BlockContent } from './content-CE-ZdMwG.mjs';
+
+/**
+ * Content-control (SDT) addressing for the document model.
+ *
+ * Block-level content controls (`w:sdt`) are the natural anchor for template
+ * logic and agent edits: they survive the round trip (see the parser +
+ * serializer) and carry a stable `tag`/`alias`/`id`. This module is the
+ * read side of that contract — discover controls and read their content
+ * without a DOM or an editor instance, so server-side pipelines and AI
+ * agents can find an anchor by tag and act on it.
+ *
+ * Walks the body recursively, descending into nested controls so a control
+ * inside another control is still found. (The model places block content
+ * controls at body level or nested in other controls, not inside table
+ * cells.) The returned `path` (block indices from the body root) addresses
+ * the control unambiguously for a follow-up edit.
+ */
+
+/** Filter for {@link findContentControls}. All provided fields must match (AND). */
+interface ContentControlFilter {
+    /** Developer identifier (`w:tag`), exact match. */
+    tag?: string;
+    /** Friendly name (`w:alias`), exact match. */
+    alias?: string;
+    /** Numeric id (`w:id`), exact match. */
+    id?: number;
+    /** Control type projection (`richText`, `dropDownList`, …). */
+    type?: SdtType;
+}
+/** A discovered content control plus enough context to address and edit it. */
+interface ContentControlInfo {
+    /** Developer identifier (`w:tag`). */
+    tag?: string;
+    /** Friendly name (`w:alias`). */
+    alias?: string;
+    /** Numeric id (`w:id`). */
+    id?: number;
+    /** Control type projection. */
+    sdtType: SdtType;
+    /** Lock setting, if any. A locked control should refuse content edits. */
+    lock?: SdtProperties['lock'];
+    /** Dropdown/combobox list items, if modeled. */
+    listItems?: {
+        displayText: string;
+        value: string;
+    }[];
+    /** Placeholder docPart reference, if any. */
+    placeholder?: string;
+    /** Whether the control is currently showing placeholder text (`w:showingPlcHdr`). */
+    showingPlaceholder?: boolean;
+    /** Checkbox state, for checkbox controls. */
+    checked?: boolean;
+    /** Date format string, for date controls. */
+    dateFormat?: string;
+    /** XML data binding (`w:dataBinding`), if the control is bound. */
+    dataBinding?: SdtDataBinding;
+    /** Plain text of the control's content (paragraphs/tables/nested controls flattened). */
+    text: string;
+    /**
+     * Block-index path from the document body to this control. Top-level
+     * controls are `[i]`; a control nested inside the i-th body block's content
+     * is `[i, j]`, and so on. Stable address for a follow-up edit.
+     */
+    path: number[];
+    /** Nesting depth (0 = direct child of the body). */
+    depth: number;
+}
+/** Plain text of a control's content, descending into tables and nested SDTs. */
+declare function getContentControlText(control: BlockSdt): string;
+/**
+ * Find every block-level content control in the document, optionally filtered
+ * by tag/alias/id/type. Results are in document order; nested controls follow
+ * their parent. Searches the body and controls nested inside controls. Table
+ * cells are not searched (the current model/parser does not surface cell-level
+ * controls), and headers/footers live in a separate content tree.
+ */
+declare function findContentControls(input: Document | DocumentBody, filter?: ContentControlFilter): ContentControlInfo[];
+/** Convenience: the first control matching `filter`, or `undefined`. */
+declare function findContentControl(input: Document | DocumentBody, filter: ContentControlFilter): ContentControlInfo | undefined;
+/** No control matched the filter. */
+declare class ContentControlNotFoundError extends Error {
+    constructor(filter: ContentControlFilter);
+}
+/** The matched control's lock forbids the attempted edit (pass `force` to override). */
+declare class ContentControlLockedError extends Error {
+    constructor(lock: SdtProperties['lock'], op: 'edit' | 'remove');
+}
+/**
+ * The control's type doesn't support free text/block replacement (e.g. a
+ * dropdown, date, checkbox, or picture control), so writing arbitrary content
+ * would desync the type marker from its value. Use a type-specific setter, or
+ * pass `{ force: true }` to override.
+ */
+declare class ContentControlTypeError extends Error {
+    constructor(sdtType: SdtType);
+}
+/**
+ * The control is bound to a Custom XML data store (`w:dataBinding`). Writing its
+ * content won't stick — Word re-renders the control from the bound XML node — so
+ * the write is refused. Update the data store instead, or pass `{ force: true }`.
+ */
+declare class ContentControlBoundError extends Error {
+    constructor();
+}
+/**
+ * Replace the content of the first control matching `filter`. `replacement`
+ * may be a string (split into paragraphs on newlines) or block content. The
+ * control's properties, tag/alias, and lossless raw `w:sdtPr` are preserved —
+ * only the contained blocks change, so the result still round-trips.
+ *
+ * When the control was showing its placeholder (`w:showingPlcHdr`), that flag
+ * is cleared so Word doesn't render the new content as placeholder text.
+ *
+ * Throws {@link ContentControlNotFoundError} if nothing matches,
+ * {@link ContentControlLockedError} if the control's lock forbids editing, and
+ * {@link ContentControlTypeError} if the control is a typed (dropdown/date/…)
+ * control whose value shouldn't be set as free text. Pass `{ force: true }` to
+ * override the lock/type guards.
+ */
+declare function setContentControlContent(doc: Document, filter: ContentControlFilter, replacement: string | BlockContent[], options?: {
+    force?: boolean;
+}): Document;
+/**
+ * Remove the first control matching `filter` from the document. With
+ * `keepContent: true` the control's blocks are unwrapped in place (the box
+ * goes away, the content stays) — useful for "resolve this conditional
+ * section into plain content". Otherwise the whole region is deleted.
+ *
+ * Unwrapping a repeating-section (item) is refused unless `force`, since
+ * lifting its blocks out would orphan the (w15) repeating structure.
+ *
+ * Throws {@link ContentControlNotFoundError} / {@link ContentControlLockedError}
+ * as {@link setContentControlContent} does.
+ */
+declare function removeContentControl(doc: Document, filter: ContentControlFilter, options?: {
+    force?: boolean;
+    keepContent?: boolean;
+}): Document;
+
+/**
+ * Typed value setters for block-level content controls — set a dropdown
+ * selection, toggle a checkbox, or set a date. These produce both the visible
+ * content (the run text Word shows) and the structured state inside the
+ * captured raw `w:sdtPr` (dropdown `w:lastValue`, `w14:checked`, `w:date`'s
+ * `w:fullDate`), patched in place so the rest of the control round-trips
+ * verbatim. Use these instead of {@link setContentControlContent} for typed
+ * controls, which that function refuses by design.
+ *
+ * Raw `w:sdtPr` is patched with targeted string edits (not a full re-serialize)
+ * to preserve the `CT_SdtPr` element order and any unmodeled properties — the
+ * same capture-and-replay contract used everywhere else for SDTs.
+ */
+
+/** A typed value to apply to a content control. */
+type ContentControlValue = {
+    kind: 'dropdown';
+    value: string;
+} | {
+    kind: 'checkbox';
+    checked: boolean;
+} | {
+    kind: 'date';
+    date: string;
+};
+/** The control doesn't support the requested value kind, or the value is invalid. */
+declare class ContentControlValueError extends Error {
+    constructor(message: string);
+}
+/** Format an ISO date (yyyy-mm-dd) with a subset of OOXML date tokens. */
+declare function formatSdtDate(iso: string, pattern?: string): string;
+/**
+ * Set a typed value (dropdown selection / checkbox / date) on the first control
+ * matching `filter`, returning a new {@link Document}. Updates both the visible
+ * content and the structured raw state, so the result round-trips and Word
+ * shows the new value. Throws {@link ContentControlNotFoundError} if nothing
+ * matches, {@link ContentControlLockedError} if content-locked,
+ * {@link ContentControlBoundError} if data-bound (the store would override the
+ * write), and {@link ContentControlValueError} if the value doesn't fit the
+ * control type. The lock/bound guards are overridable with `{ force: true }`.
+ */
+declare function setContentControlValue(doc: Document, filter: ContentControlFilter, value: ContentControlValue, options?: {
+    force?: boolean;
+}): Document;
+
+export { ContentControlBoundError as C, type ContentControlFilter as a, type ContentControlInfo as b, ContentControlLockedError as c, ContentControlNotFoundError as d, ContentControlTypeError as e, type ContentControlValue as f, ContentControlValueError as g, findContentControl as h, findContentControls as i, formatSdtDate as j, getContentControlText as k, setContentControlValue as l, removeContentControl as r, setContentControlContent as s };