@docx4j/core-ts 0.1.0 → 0.1.1

package/dist/model/customxml/XmlMapping.d.mts

@@ -0,0 +1,46 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { ContentControl } from '../content/ContentControl.mjs';
+import type { CustomXmlPart, CustomXmlNode } from './CustomXmlPart.mjs';
+/** What `XmlMapping` needs of `pkg.customXmlParts`, so that this module does not import the package. */
+export interface CustomXmlPartLookup {
+    readonly items: CustomXmlPart[];
+    getItem(id: string): CustomXmlPart | undefined;
+}
+/**
+ * A subset of Office JS `Word.XmlMapping`: the content control's data binding. `isMapped` is
+ * whether the control has a `w:dataBinding`; `customXmlNode` evaluates the XPath now, so it needs
+ * the XPath engine to be warm (`await pkg.customXmlParts.load()` once, CR-002 section 3.6).
+ */
+export declare class XmlMapping {
+    /** The control this mapping belongs to. */
+    readonly contentControl: ContentControl;
+    private readonly lookup;
+    constructor(
+    /** The control this mapping belongs to. */
+    contentControl: ContentControl, lookup: CustomXmlPartLookup | undefined);
+    /** The `w:dataBinding` value, or undefined when the control has none (extension). */
+    get dataBinding(): wml.CTDataBinding | undefined;
+    get isMapped(): boolean;
+    get xpath(): string;
+    get prefixMappings(): string;
+    /** `w:storeItemID`, the itemID of the custom XML part (extension: Office JS reports the part). */
+    get storeItemID(): string;
+    /** The part the binding names, when the package has it. */
+    get customXmlPart(): CustomXmlPart | undefined;
+    /** The node the XPath selects now, or undefined when it selects nothing. */
+    get customXmlNode(): CustomXmlNode | undefined;
+    /**
+     * Binds the control to what the XPath selects, as Word's own mapping does: the part is the one
+     * given, else the one the control is already bound to, else the first custom XML part (the
+     * built-in property stores last) in which the XPath selects a node. Returns false and changes
+     * nothing when nothing is selected, which is what Word reports.
+     */
+    setMapping(xpath: string, prefixMappings?: string, part?: CustomXmlPart): boolean;
+    /** Binds to a node: its canonical XPath and the prefixes that path needs, as Word writes them. */
+    setMappingByNode(node: CustomXmlNode): boolean;
+    /** Removes the binding (`w:dataBinding`); the control keeps the content it shows. */
+    delete(): void;
+    private write;
+    /** The parts to try, the customer's data before Word's property stores. */
+    private candidates;
+}

package/dist/model/customxml/XmlMapping.mjs

@@ -0,0 +1,98 @@
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+import { canonicalXPathOf } from './xpath.mjs';
+/** The Word 2012 (w15) namespace; not imported from `ContentControl`, which imports this module. */
+const W15_NS = 'http://schemas.microsoft.com/office/word/2012/wordml';
+/**
+ * A subset of Office JS `Word.XmlMapping`: the content control's data binding. `isMapped` is
+ * whether the control has a `w:dataBinding`; `customXmlNode` evaluates the XPath now, so it needs
+ * the XPath engine to be warm (`await pkg.customXmlParts.load()` once, CR-002 section 3.6).
+ */
+export class XmlMapping {
+    constructor(
+    /** The control this mapping belongs to. */
+    contentControl, lookup) {
+        this.contentControl = contentControl;
+        this.lookup = lookup;
+    }
+    /** The `w:dataBinding` value, or undefined when the control has none (extension). */
+    get dataBinding() {
+        var _a;
+        const pr = this.contentControl.sdt.sdtPr;
+        // Word 2013 writes `w15:dataBinding` on a repeating section and on a rich-text control bound
+        // to a container; everywhere else the binding is `w:dataBinding`. Both are CT_DataBinding.
+        const item = (_a = sdtProperty(pr, 'dataBinding')) !== null && _a !== void 0 ? _a : sdtProperty(pr, 'dataBinding', W15_NS);
+        return item === null || item === void 0 ? void 0 : item.value;
+    }
+    get isMapped() {
+        return this.dataBinding !== undefined;
+    }
+    get xpath() {
+        var _a, _b;
+        return (_b = (_a = this.dataBinding) === null || _a === void 0 ? void 0 : _a.xpath) !== null && _b !== void 0 ? _b : '';
+    }
+    get prefixMappings() {
+        var _a, _b;
+        return (_b = (_a = this.dataBinding) === null || _a === void 0 ? void 0 : _a.prefixMappings) !== null && _b !== void 0 ? _b : '';
+    }
+    /** `w:storeItemID`, the itemID of the custom XML part (extension: Office JS reports the part). */
+    get storeItemID() {
+        var _a, _b;
+        return (_b = (_a = this.dataBinding) === null || _a === void 0 ? void 0 : _a.storeItemID) !== null && _b !== void 0 ? _b : '';
+    }
+    /** The part the binding names, when the package has it. */
+    get customXmlPart() {
+        var _a;
+        const id = this.storeItemID;
+        return id === '' ? undefined : (_a = this.lookup) === null || _a === void 0 ? void 0 : _a.getItem(id);
+    }
+    /** The node the XPath selects now, or undefined when it selects nothing. */
+    get customXmlNode() {
+        const part = this.customXmlPart;
+        const binding = this.dataBinding;
+        if (!part || !binding)
+            return undefined;
+        return part.selectSingleNode(binding.xpath, binding.prefixMappings);
+    }
+    /**
+     * Binds the control to what the XPath selects, as Word's own mapping does: the part is the one
+     * given, else the one the control is already bound to, else the first custom XML part (the
+     * built-in property stores last) in which the XPath selects a node. Returns false and changes
+     * nothing when nothing is selected, which is what Word reports.
+     */
+    setMapping(xpath, prefixMappings, part) {
+        const candidates = part ? [part] : this.candidates();
+        for (const candidate of candidates) {
+            const node = candidate.selectSingleNode(xpath, prefixMappings);
+            if (!node)
+                continue;
+            this.write(xpath, prefixMappings !== null && prefixMappings !== void 0 ? prefixMappings : '', candidate.id);
+            return true;
+        }
+        return false;
+    }
+    /** Binds to a node: its canonical XPath and the prefixes that path needs, as Word writes them. */
+    setMappingByNode(node) {
+        const { xpath, prefixMappings } = canonicalXPathOf(node.node);
+        this.write(xpath, prefixMappings, node.ownerPart.id);
+        return true;
+    }
+    /** Removes the binding (`w:dataBinding`); the control keeps the content it shows. */
+    delete() {
+        this.contentControl.removeProperty('dataBinding');
+    }
+    write(xpath, prefixMappings, storeItemID) {
+        const binding = { TYPE_NAME: 'org_docx4j_wml.CTDataBinding', xpath, storeItemID };
+        if (prefixMappings !== '')
+            binding.prefixMappings = prefixMappings;
+        this.contentControl.putProperty(el.dataBinding(binding));
+    }
+    /** The parts to try, the customer's data before Word's property stores. */
+    candidates() {
+        var _a, _b;
+        const current = this.customXmlPart;
+        const all = (_b = (_a = this.lookup) === null || _a === void 0 ? void 0 : _a.items) !== null && _b !== void 0 ? _b : [];
+        const rest = all.filter((p) => p !== current);
+        return [...(current ? [current] : []), ...rest.filter((p) => !p.builtIn), ...rest.filter((p) => p.builtIn)];
+    }
+}

package/dist/model/customxml/bindings.d.mts

@@ -0,0 +1,41 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type { Element } from '../content/tree.mjs';
+import type { ContentControl } from '../content/ContentControl.mjs';
+/** The style Word gives placeholder text, and the text docx4j's placeholder.xml carries. */
+export declare const PLACEHOLDER_STYLE = "PlaceholderText";
+export declare const PLACEHOLDER_TEXT = "Click here to enter text.";
+/** What `applyBindings` and `updateFromContentControls` report. */
+export interface BindingResult {
+    /** Controls carrying a `w:dataBinding`. */
+    bound: number;
+    /** Controls whose value was written (into the document, or into the custom XML). */
+    updated: number;
+    /** Controls left alone: the part is missing, the XPath selects nothing, or the kind is not handled. */
+    skipped: number;
+}
+/** docx4j ValueInserterPlainTextImpl: the runs for a value, with the w:sdtPr run properties. */
+export declare function runsForValue(value: string, rPr: wml.RPr | undefined, multiLine: boolean): Element[];
+/**
+ * A date in Word's `w:dateFormat` pattern (the .NET forms Word writes: `d MMMM yyyy`,
+ * `dddd, d MMMM yyyy`, `d/MM/yyyy`), in the control's `w:lid` locale. Month and day names come
+ * from `Intl`; text inside single or double quotes is literal. docx4j uses Java's
+ * `SimpleDateFormat` with `dddd` mapped to `EEEE`; this is the same vocabulary.
+ */
+export declare function formatDate(pattern: string, date: Date, locale?: string): string;
+/**
+ * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
+ * false when nothing was written: no binding, no part, an XPath that selects nothing, or a kind
+ * this phase does not handle (pictures, explicit rich text).
+ */
+export declare function applyBindingTo(control: ContentControl): boolean;
+/** `applyBindings` over a list of controls. */
+export declare function applyBindingsTo(controls: ContentControl[]): BindingResult;
+/**
+ * Writes what one control shows back into the node it is bound to (docx4j
+ * UpdateXmlFromDocumentSurface). A checkbox writes 'true' or 'false' and a list writes the entry's
+ * value rather than its display text, which is what the data meant in the first place (docx4j
+ * writes the rendered glyph; section 12).
+ */
+export declare function updateFromControl(control: ContentControl): boolean;
+/** `updateFromContentControls` over a list of controls. */
+export declare function updateFromControls(controls: ContentControl[]): BindingResult;

package/dist/model/customxml/bindings.mjs

@@ -0,0 +1,230 @@
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import { sdtProperty } from '@docx4j/generated-objects-ts/builders/wml';
+/** The style Word gives placeholder text, and the text docx4j's placeholder.xml carries. */
+export const PLACEHOLDER_STYLE = 'PlaceholderText';
+export const PLACEHOLDER_TEXT = 'Click here to enter text.';
+function isTrue(value) {
+    const v = value.trim().toLowerCase();
+    return v === 'true' || v === '1' || v === 'on' || v === 'yes';
+}
+/**
+ * Kinds that hold structure rather than a value. Word maps a repeating section to a node set and
+ * repeats what is inside it; writing a bound value into one would flatten the repeat, so these are
+ * left alone in both directions (CR-002 section 12) — as is any control that holds a table or
+ * another control.
+ */
+const CONTAINER_KINDS = new Set(['RepeatingSection', 'RepeatingSectionItem', 'Group', 'BuildingBlockGallery']);
+function isContainer(control) {
+    if (CONTAINER_KINDS.has(control.type))
+        return true;
+    if (control.contentControls.length > 0)
+        return true;
+    return control.form === 'Block' && control.tables.length > 0;
+}
+/** docx4j ValueInserterPlainTextImpl: the runs for a value, with the w:sdtPr run properties. */
+export function runsForValue(value, rPr, multiLine) {
+    if (value === '')
+        return [placeholderRun(rPr)];
+    const lines = multiLine ? value.split(/[\n\r\f]+/).filter((line) => line !== '') : [value.replace(/[\n\r\f]+/g, '')];
+    const out = [];
+    lines.forEach((line, i) => {
+        if (i > 0)
+            out.push(el.r({ ...(rPr ? { rPr: deepCopy(rPr) } : {}), content: [el.br({})] }));
+        const text = { TYPE_NAME: 'org_docx4j_wml.Text', value: line };
+        if (line.startsWith(' ') || line.endsWith(' '))
+            text.space = 'preserve';
+        out.push(el.r({ ...(rPr ? { rPr: deepCopy(rPr) } : {}), content: [el.t(text)] }));
+    });
+    return out;
+}
+/** docx4j's placeholder.xml: a PlaceholderText-styled run, which goes with w:showingPlcHdr. */
+function placeholderRun(rPr) {
+    const properties = rPr ? deepCopy(rPr) : {};
+    properties.rStyle = { val: PLACEHOLDER_STYLE };
+    return el.r({ rPr: properties, content: [el.t({ value: PLACEHOLDER_TEXT })] });
+}
+/**
+ * A date in Word's `w:dateFormat` pattern (the .NET forms Word writes: `d MMMM yyyy`,
+ * `dddd, d MMMM yyyy`, `d/MM/yyyy`), in the control's `w:lid` locale. Month and day names come
+ * from `Intl`; text inside single or double quotes is literal. docx4j uses Java's
+ * `SimpleDateFormat` with `dddd` mapped to `EEEE`; this is the same vocabulary.
+ */
+export function formatDate(pattern, date, locale = 'en-US') {
+    const pad = (n, width) => String(n).padStart(width, '0');
+    const name = (options) => {
+        try {
+            return new Intl.DateTimeFormat(locale, options).format(date);
+        }
+        catch {
+            return new Intl.DateTimeFormat('en-US', options).format(date);
+        }
+    };
+    const hours12 = date.getHours() % 12 === 0 ? 12 : date.getHours() % 12;
+    return pattern.replace(/d{1,4}|M{1,4}|y{2,4}|H{1,2}|h{1,2}|m{1,2}|s{1,2}|tt|'[^']*'|"[^"]*"/g, (token) => {
+        if (token.startsWith("'") || token.startsWith('"'))
+            return token.slice(1, -1);
+        switch (token) {
+            case 'd': return String(date.getDate());
+            case 'dd': return pad(date.getDate(), 2);
+            case 'ddd': return name({ weekday: 'short' });
+            case 'dddd': return name({ weekday: 'long' });
+            case 'M': return String(date.getMonth() + 1);
+            case 'MM': return pad(date.getMonth() + 1, 2);
+            case 'MMM': return name({ month: 'short' });
+            case 'MMMM': return name({ month: 'long' });
+            case 'yy': return pad(date.getFullYear() % 100, 2);
+            case 'yyy':
+            case 'yyyy': return String(date.getFullYear());
+            case 'H': return String(date.getHours());
+            case 'HH': return pad(date.getHours(), 2);
+            case 'h': return String(hours12);
+            case 'hh': return pad(hours12, 2);
+            case 'm': return String(date.getMinutes());
+            case 'mm': return pad(date.getMinutes(), 2);
+            case 's': return String(date.getSeconds());
+            case 'ss': return pad(date.getSeconds(), 2);
+            case 'tt': return date.getHours() < 12 ? 'AM' : 'PM';
+            default: return token;
+        }
+    });
+}
+/** Word's stored date form, `2015-01-29T00:00:00` (local, as `w:fullDate` without a zone). */
+function isoOf(date) {
+    const pad = (n) => String(n).padStart(2, '0');
+    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+/** The date a bound value holds, when it is one (`2015-01-29T00:00:00`, `2015-01-29`, or with a Z). */
+function dateOf(value) {
+    if (!/^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2})?)?/.test(value))
+        return undefined;
+    const parsed = new Date(value.replace(/Z$/, '').replace(' ', 'T'));
+    return Number.isNaN(parsed.getTime()) ? undefined : parsed;
+}
+/**
+ * Pushes the custom XML value into one control (docx4j BindingHandler's per-sdt work). Returns
+ * false when nothing was written: no binding, no part, an XPath that selects nothing, or a kind
+ * this phase does not handle (pictures, explicit rich text).
+ */
+export function applyBindingTo(control) {
+    var _a;
+    const mapping = control.xmlMapping;
+    if (!mapping.isMapped)
+        return false;
+    const node = mapping.customXmlNode;
+    if (!node)
+        return false;
+    const value = node.text.trim();
+    // A picture binding carries base64 image data; docx4j replaces the a:blip embed. Deferred (section 12).
+    if (control.type === 'Picture')
+        return false;
+    // Explicit rich text is bound from flat OPC or XHTML in docx4j; deferred, as it is there for this route.
+    if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
+        return false;
+    if (isContainer(control))
+        return false;
+    if (control.type === 'CheckBox') {
+        const checkbox = control.checkboxContentControl;
+        if (!checkbox)
+            return false;
+        checkbox.isChecked = isTrue(value);
+        return true;
+    }
+    let display = value;
+    if (control.type === 'DropDownList' || control.type === 'ComboBox') {
+        const list = (_a = control.dropDownListContentControl) !== null && _a !== void 0 ? _a : control.comboBoxContentControl;
+        if (list) {
+            const match = list.listItems.find((item) => item.value === value);
+            if (match)
+                display = match.displayText;
+            list.lastValue = value;
+        }
+    }
+    else if (control.type === 'DatePicker') {
+        const date = control.datePickerContentControl;
+        const parsed = dateOf(value);
+        if (date && parsed) {
+            date.fullDate = parsed;
+            // Word shows the date in w:dateFormat, not the stored form (docx4j formats it the same way)
+            if (date.dateFormat !== '')
+                display = formatDate(date.dateFormat, parsed, date.dateDisplayLocale || undefined);
+        }
+    }
+    control.setBoundContent(runsForValue(display, control.runProperties, control.isMultiLine), display === '');
+    return true;
+}
+/** `applyBindings` over a list of controls. */
+export function applyBindingsTo(controls) {
+    const result = { bound: 0, updated: 0, skipped: 0 };
+    for (const control of controls) {
+        if (!control.xmlMapping.isMapped)
+            continue;
+        result.bound++;
+        if (applyBindingTo(control))
+            result.updated++;
+        else
+            result.skipped++;
+    }
+    return result;
+}
+/**
+ * Writes what one control shows back into the node it is bound to (docx4j
+ * UpdateXmlFromDocumentSurface). A checkbox writes 'true' or 'false' and a list writes the entry's
+ * value rather than its display text, which is what the data meant in the first place (docx4j
+ * writes the rendered glyph; section 12).
+ */
+export function updateFromControl(control) {
+    var _a, _b;
+    const mapping = control.xmlMapping;
+    if (!mapping.isMapped)
+        return false;
+    const node = mapping.customXmlNode;
+    if (!node)
+        return false;
+    if (control.type === 'Picture')
+        return false;
+    if (sdtProperty(control.sdt.sdtPr, 'richText') !== undefined)
+        return false;
+    if (isContainer(control))
+        return false;
+    // A control showing its placeholder holds no value.
+    if (control.isShowingPlaceholder)
+        return false;
+    let value = control.text;
+    if (control.type === 'CheckBox') {
+        const checkbox = control.checkboxContentControl;
+        if (!checkbox)
+            return false;
+        value = checkbox.isChecked ? 'true' : 'false';
+    }
+    else if (control.type === 'DropDownList' || control.type === 'ComboBox') {
+        const list = (_a = control.dropDownListContentControl) !== null && _a !== void 0 ? _a : control.comboBoxContentControl;
+        const match = list === null || list === void 0 ? void 0 : list.listItems.find((item) => item.displayText === value);
+        if (match)
+            value = match.value;
+    }
+    else if (control.type === 'DatePicker') {
+        // the control shows the formatted date; the data keeps Word's stored form (docx4j skips dates)
+        const full = (_b = control.datePickerContentControl) === null || _b === void 0 ? void 0 : _b.fullDate;
+        if (full)
+            value = isoOf(full);
+    }
+    if (node.text === value)
+        return false;
+    node.text = value;
+    return true;
+}
+/** `updateFromContentControls` over a list of controls. */
+export function updateFromControls(controls) {
+    const result = { bound: 0, updated: 0, skipped: 0 };
+    for (const control of controls) {
+        if (!control.xmlMapping.isMapped)
+            continue;
+        result.bound++;
+        if (updateFromControl(control))
+            result.updated++;
+        else
+            result.skipped++;
+    }
+    return result;
+}

package/dist/model/customxml/index.d.mts

@@ -0,0 +1,7 @@
+export { type XPathEngine, type XPathValue, DefaultXPathEngine, parsePrefixMappings, formatPrefixMappings, canonicalXPathOf, xmlOf, type CanonicalXPath } from './xpath.mjs';
+export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection, type CustomXmlNodeType, type CustomXmlPrefixMapping, type CustomXmlPartOwner } from './CustomXmlPart.mjs';
+export { CustomXmlPartCollection, type CustomXmlHost } from './CustomXmlPartCollection.mjs';
+export { XmlMapping, type CustomXmlPartLookup } from './XmlMapping.mjs';
+export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
+export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT, type BindingResult } from './bindings.mjs';
+export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';

package/dist/model/customxml/index.mjs

@@ -0,0 +1,9 @@
+// CR-002 phase E: custom XML parts, XML mapping, the XPath engine and the typed content controls
+// (CR-002 sections 3.5 and 3.6). Exported from '.' and './model', as the content API is.
+export { DefaultXPathEngine, parsePrefixMappings, formatPrefixMappings, canonicalXPathOf, xmlOf } from './xpath.mjs';
+export { CustomXmlPart, CustomXmlNode, CustomXmlPrefixMappingCollection } from './CustomXmlPart.mjs';
+export { CustomXmlPartCollection } from './CustomXmlPartCollection.mjs';
+export { XmlMapping } from './XmlMapping.mjs';
+export { CheckboxContentControl, DatePickerContentControl, ListContentControl, ContentControlListItem, PictureContentControl, RepeatingSectionContentControl, GroupContentControl, checkboxRun, CHECKED_SYMBOL, UNCHECKED_SYMBOL, CHECKBOX_FONT, } from './kinds.mjs';
+export { applyBindingsTo, applyBindingTo, updateFromControls, updateFromControl, runsForValue, formatDate, PLACEHOLDER_STYLE, PLACEHOLDER_TEXT } from './bindings.mjs';
+export { controlIdScope, sdtKindFor, isRunLevel } from './insert.mjs';

package/dist/model/customxml/insert.d.mts

@@ -0,0 +1,20 @@
+import type { SdtKind } from '@docx4j/generated-objects-ts/builders/wml';
+import type { XmlPart } from '../../parts/XmlPart.mjs';
+import { type Element } from '../content/tree.mjs';
+import type { ContentControlType } from '../content/ContentControl.mjs';
+/**
+ * The kind the builders' `sdt` takes: Office JS's `Unknown` has no kind element, as `RichText`
+ * has none (Word reports an untyped control as rich text).
+ */
+export declare function sdtKindFor(kind: ContentControlType | undefined): SdtKind | undefined;
+/**
+ * The tree a new control's `w:id` must be free in (what `nextSdtId` scans): the part's whole
+ * contents when the body has a part, so that a control added inside another control, a cell or a
+ * header still gets an id free in the part; the container itself otherwise.
+ */
+export declare function controlIdScope(body: {
+    part?: XmlPart<unknown> | undefined;
+    container: object;
+}): object;
+/** True for a run-level item (what a Range wraps). */
+export declare function isRunLevel(element: Element): boolean;

package/dist/model/customxml/insert.mjs

@@ -0,0 +1,22 @@
+import { typeNameOf } from '../content/tree.mjs';
+/**
+ * The kind the builders' `sdt` takes: Office JS's `Unknown` has no kind element, as `RichText`
+ * has none (Word reports an untyped control as rich text).
+ */
+export function sdtKindFor(kind) {
+    return kind === undefined || kind === 'Unknown' ? undefined : kind;
+}
+/**
+ * The tree a new control's `w:id` must be free in (what `nextSdtId` scans): the part's whole
+ * contents when the body has a part, so that a control added inside another control, a cell or a
+ * header still gets an id free in the part; the container itself otherwise.
+ */
+export function controlIdScope(body) {
+    const part = body.part;
+    return (part === null || part === void 0 ? void 0 : part.isUnmarshalled) ? part.contents : body.container;
+}
+/** True for a run-level item (what a Range wraps). */
+export function isRunLevel(element) {
+    const tn = typeNameOf(element);
+    return tn === 'org_docx4j_wml.R' || tn === 'org_docx4j_wml.SdtRun' || tn === 'org_docx4j_wml.P.Hyperlink';
+}

package/dist/model/customxml/kinds.d.mts

@@ -0,0 +1,103 @@
+import type * as wml from '@docx4j/generated-objects-ts/modules/org_docx4j_wml';
+import type * as w14 from '@docx4j/generated-objects-ts/modules/org_docx4j_w14';
+import type * as w15 from '@docx4j/generated-objects-ts/modules/org_docx4j_w15';
+import type { Element } from '../content/tree.mjs';
+import type { ContentControl } from '../content/ContentControl.mjs';
+import type { InlinePicture } from '../content/InlinePicture.mjs';
+/** Word's default checkbox glyphs (docx4j BindingTraverserXSLT uses the same two). */
+export declare const CHECKED_SYMBOL = "\u2612";
+export declare const UNCHECKED_SYMBOL = "\u2610";
+/** The font Word writes with them. */
+export declare const CHECKBOX_FONT = "MS Gothic";
+/** Office JS `Word.CheckboxContentControl` over `w14:checkbox`. */
+export declare class CheckboxContentControl {
+    private readonly control;
+    private readonly checkbox;
+    constructor(control: ContentControl, checkbox: w14.CTSdtCheckbox);
+    get isChecked(): boolean;
+    set isChecked(value: boolean);
+    /** The glyph shown when checked (`w14:checkedState/@w14:val`, a hex character code). */
+    get checkedSymbol(): string;
+    set checkedSymbol(symbol: string);
+    get uncheckedSymbol(): string;
+    set uncheckedSymbol(symbol: string);
+    /** The font of the two glyphs (extension; Word writes MS Gothic). */
+    get font(): string;
+}
+/** Office JS `Word.DatePickerContentControl` over `w:date`. */
+export declare class DatePickerContentControl {
+    private readonly date;
+    constructor(date: wml.CTSdtDate);
+    /** `w:dateFormat`, Word's .NET date pattern ('d MMMM yyyy'). Office JS calls it dateDisplayFormat. */
+    get dateFormat(): string;
+    set dateFormat(format: string);
+    /** Office JS's name for the same property. */
+    get dateDisplayFormat(): string;
+    set dateDisplayFormat(format: string);
+    /** `w:lid`, the language the date is shown in ('en-AU'). */
+    get dateDisplayLocale(): string;
+    set dateDisplayLocale(locale: string);
+    /** `w:calendar` ('gregorian', 'hijri', ...). */
+    get dateCalendarType(): string;
+    set dateCalendarType(calendar: string);
+    /** `w:storeMappedDataAs`: how a bound date is written into the custom XML ('dateTime', 'date', 'text'). */
+    get dateStorageFormat(): string;
+    set dateStorageFormat(format: string);
+    /** `w:fullDate`, the date itself when Word has one (extension). */
+    get fullDate(): Date | undefined;
+    set fullDate(value: Date | undefined);
+}
+/** One entry of a drop-down list or combo box (Office JS `Word.ContentControlListItem`). */
+export declare class ContentControlListItem {
+    private readonly items;
+    private readonly item;
+    constructor(items: wml.CTSdtListItem[], item: wml.CTSdtListItem);
+    get displayText(): string;
+    set displayText(text: string);
+    get value(): string;
+    set value(value: string);
+    get index(): number;
+    delete(): void;
+}
+/** Office JS `Word.DropDownListContentControl` / `Word.ComboBoxContentControl`: the same shape. */
+export declare class ListContentControl {
+    private readonly list;
+    constructor(list: wml.CTSdtDropDownList | wml.CTSdtComboBox);
+    get listItems(): ContentControlListItem[];
+    /** Adds an entry; `value` defaults to the display text, `index` appends when omitted. */
+    addListItem(displayText: string, value?: string, index?: number): ContentControlListItem;
+    deleteAllListItems(): void;
+    /** `w:lastValue`, what Word last showed (extension). */
+    get lastValue(): string;
+    set lastValue(value: string);
+}
+/** Office JS `Word.PictureContentControl`. */
+export declare class PictureContentControl {
+    private readonly control;
+    constructor(control: ContentControl);
+    /** The picture the control holds, if any. */
+    get inlinePicture(): InlinePicture | undefined;
+}
+/** Office JS `Word.RepeatingSectionContentControl` over `w15:repeatingSection`. */
+export declare class RepeatingSectionContentControl {
+    private readonly control;
+    private readonly section;
+    constructor(control: ContentControl, section: w15.CTSdtRepeatedSection);
+    /** The repeated items: the `w15:repeatingSectionItem` controls directly inside. */
+    get items(): ContentControl[];
+    get sectionTitle(): string;
+    set sectionTitle(title: string);
+    /** Whether Word offers the + and x buttons (`w15:doNotAllowInsertDeleteSection`, inverted). */
+    get allowInsertDeleteSection(): boolean;
+    set allowInsertDeleteSection(allow: boolean);
+    /**
+     * Adds a copy of the item at `index` after it, as Word's + button does, and returns the new
+     * item's control. The copy is a deep copy with its PARENT links rebuilt by the container.
+     */
+    insertItemAfter(index: number): ContentControl;
+}
+/** Office JS `Word.GroupContentControl`: no members of its own. */
+export declare class GroupContentControl {
+}
+/** The `w:sdtContent` glyph run of a checkbox, as Word writes it (docx4j's binding does the same). */
+export declare function checkboxRun(symbol: string, font: string, rPr?: wml.RPr): Element;