@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/model/content/tree.mjs

@@ -1,32 +1,33 @@
-import { isElement, typeNameOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { isElement, typeNameOf, runItemsOf } from '@docx4j/generated-objects-ts/builders/wml';
 export { isElement, typeNameOf, walk, find, linkParents, textOf, W_NS } from '@docx4j/generated-objects-ts/builders/wml';
-/** Types whose value holds runs (directly or through sdtContent); w:del is not among them: deleted text is not the text. */
+/** Types whose value holds runs (directly or through sdtContent); the revision holders are separate. */
 const RUN_HOLDERS = new Set([
-    'org_docx4j_wml.P.Hyperlink', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.RunIns', 'org_docx4j_wml.CTSmartTagRun',
+    'org_docx4j_wml.P.Hyperlink', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.CTSmartTagRun',
     'org_docx4j_wml.CTCustomXmlRun', 'org_docx4j_wml.P.Dir', 'org_docx4j_wml.P.Bdo', 'org_docx4j_wml.CTSimpleField',
-    'org_docx4j_wml.RunTrackChange', 'org_docx4j_wml.CTSdtContentRun',
+    'org_docx4j_wml.CTSdtContentRun',
 ]);
-/**
- * The run-level items a holder keeps, by the model's own property names: `content` for most,
- * `customXmlOrSmartTagOrSdt` for w:ins, w:del, w:moveFrom and w:moveTo (docx4j's names for
- * the choice groups), `sdtContent.content` for a run-level content control.
- */
-export function runItemsOf(value) {
-    const v = value;
-    if (Array.isArray(v.content))
-        return v.content;
-    if (Array.isArray(v.customXmlOrSmartTagOrSdt))
-        return v.customXmlOrSmartTagOrSdt;
-    if (v.sdtContent)
-        return runItemsOf(v.sdtContent);
-    return undefined;
+/** w:ins, w:del and the two w:move forms (w:moveFrom and w:moveTo share docx4j's RunTrackChange). */
+const REVISION_HOLDERS = new Set(['org_docx4j_wml.RunIns', 'org_docx4j_wml.RunDel', 'org_docx4j_wml.RunTrackChange']);
+/** The kind of a run-level revision element, by its name; undefined when it is not one. */
+export function revisionKindOf(el) {
+    var _a;
+    if (!REVISION_HOLDERS.has((_a = typeNameOf(el)) !== null && _a !== void 0 ? _a : ''))
+        return undefined;
+    const name = el.name.localPart;
+    return name === 'ins' || name === 'del' || name === 'moveFrom' || name === 'moveTo' ? name : undefined;
+}
+/** True when this view shows the runs of a revision of that kind. */
+function shows(view, kind) {
+    return view === 'accepted' ? kind === 'ins' || kind === 'moveTo' : kind === 'del' || kind === 'moveFrom';
 }
+export { runItemsOf };
 function itemText(item) {
     var _a, _b;
     const t = item.name.localPart;
     const v = item.value;
     switch (t) {
-        case 't': return String((_a = v.value) !== null && _a !== void 0 ? _a : '');
+        case 't':
+        case 'delText': return String((_a = v.value) !== null && _a !== void 0 ? _a : '');
         case 'tab': return '\t';
         case 'br': return '\n';
         case 'cr': return '\n';
@@ -39,11 +40,17 @@ function itemText(item) {
         default: return undefined;
     }
 }
-/** The text segments of a paragraph (or any run holder) in order. Deleted text (w:del) is skipped. */
-export function segmentsOf(container) {
+/**
+ * The text segments of a paragraph (or any run holder) in order. The default view is the
+ * accepted one: the runs of a `w:ins` or `w:moveTo` count, those of a `w:del` or `w:moveFrom`
+ * do not. `{ view: 'original' }` is the other way round (CR-002 phase F).
+ */
+export function segmentsOf(container, options) {
+    var _a;
+    const view = (_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted';
     const out = [];
     let pos = 0;
-    const visitRuns = (items) => {
+    const visitRuns = (items, revision) => {
         var _a;
         if (!items)
             return;
@@ -58,28 +65,56 @@ export function segmentsOf(container) {
                     const text = itemText(item);
                     if (text === undefined)
                         continue;
-                    out.push({ item, owner: content, index: j, run, runOwner: items, runIndex: i, text, start: pos, end: pos + text.length, editable: item.name.localPart === 't' });
+                    const seg = {
+                        item, owner: content, index: j, run, runOwner: items, runIndex: i, text,
+                        start: pos, end: pos + text.length, editable: item.name.localPart === 't',
+                    };
+                    if (revision)
+                        seg.revision = revision;
+                    out.push(seg);
                     pos += text.length;
                 }
+                continue;
+            }
+            const kind = revisionKindOf(el);
+            if (kind !== undefined) {
+                if (!shows(view, kind))
+                    continue;
+                const nested = runItemsOf(el.value);
+                if (nested)
+                    visitRuns(nested, { kind, element: el, value: el.value, items: nested, owner: items });
             }
             else if (tn !== undefined && RUN_HOLDERS.has(tn)) {
-                visitRuns(runItemsOf(el.value));
+                visitRuns(runItemsOf(el.value), revision);
             }
         }
     };
-    visitRuns(runItemsOf(container));
+    visitRuns(runItemsOf(container), undefined);
     return out;
 }
+/** The text of a paragraph or container in one of the two views (`textOf` is the accepted one). */
+export function textOfView(container, options) {
+    return segmentsOf(container, options).map((s) => s.text).join('');
+}
 /** The runs of a paragraph, direct and nested in hyperlinks, content controls and insertions, in order. */
-export function runsOf(container) {
+export function runsOf(container, options) {
+    var _a;
+    const view = (_a = options === null || options === void 0 ? void 0 : options.view) !== null && _a !== void 0 ? _a : 'accepted';
     const out = [];
     const visit = (items) => {
         if (!items)
             return;
         for (const el of items) {
             const tn = typeNameOf(el);
-            if (tn === 'org_docx4j_wml.R')
+            if (tn === 'org_docx4j_wml.R') {
                 out.push(el);
+                continue;
+            }
+            const kind = revisionKindOf(el);
+            if (kind !== undefined) {
+                if (shows(view, kind))
+                    visit(runItemsOf(el.value));
+            }
             else if (tn !== undefined && RUN_HOLDERS.has(tn))
                 visit(runItemsOf(el.value));
         }
@@ -87,14 +122,49 @@ export function runsOf(container) {
     visit(runItemsOf(container));
     return out;
 }
-/** The block-level children of a container: body, header, footer, cell, sdt content, table (rows), row (cells). */
+/**
+ * The block-level children of a container: body, header, footer, cell, sdt content, table (rows),
+ * row (cells). A content control of any kind (block, row, cell, run) answers with its
+ * `sdtContent`'s content, so that a traversal does not have to know the four types.
+ */
 export function childrenOf(value) {
-    var _a;
     const v = value;
-    if (v.TYPE_NAME === 'org_docx4j_wml.SdtBlock')
-        return (_a = v.sdtContent) === null || _a === void 0 ? void 0 : _a.content;
+    if (v.sdtContent)
+        return v.sdtContent.content;
     return Array.isArray(v.content) ? v.content : undefined;
 }
+/** w:sdt and w:customXml at row level: they hold the rows of a table (docx4j CTSdtRow, CTCustomXmlRow). */
+const ROW_HOLDERS = new Set(['org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTCustomXmlRow']);
+/** The same at cell level. */
+const CELL_HOLDERS = new Set(['org_docx4j_wml.CTSdtCell', 'org_docx4j_wml.CTCustomXmlCell']);
+/** The rows of a table, in order, descending into row-level content controls (an OpenDoPE repeat). */
+export function rowsOf(tbl) {
+    return located(childrenOf(tbl), 'org_docx4j_wml.Tr', ROW_HOLDERS);
+}
+/** The cells of a row, in order, descending into cell-level content controls. */
+export function cellsOf(tr) {
+    return located(childrenOf(tr), 'org_docx4j_wml.Tc', CELL_HOLDERS);
+}
+function located(items, typeName, holders) {
+    const out = [];
+    const visit = (list) => {
+        if (!list)
+            return;
+        for (const element of list) {
+            const tn = typeNameOf(element);
+            if (tn === typeName)
+                out.push({ element, container: list });
+            else if (tn !== undefined && holders.has(tn) && typeof element.value === 'object' && element.value !== null)
+                visit(childrenOf(element.value));
+        }
+    };
+    visit(items);
+    return out;
+}
+/** Content controls: `w:sdt` at block, row, cell and run level, by TYPE_NAME. */
+export const SDT_TYPES = new Set([
+    'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.SdtRun', 'org_docx4j_wml.CTSdtRow', 'org_docx4j_wml.CTSdtCell',
+]);
 /** True for what a body or cell may hold directly (the Body content union), by TYPE_NAME. */
 export const BLOCK_LEVEL_TYPES = new Set([
     'org_docx4j_wml.P', 'org_docx4j_wml.Tbl', 'org_docx4j_wml.SdtBlock', 'org_docx4j_wml.CTCustomXmlBlock', 'org_docx4j_wml.CTAltChunk',
@@ -118,3 +188,6 @@ export function paragraphOf(runs, pPr) {
     return { name: { namespaceURI: 'http://schemas.openxmlformats.org/wordprocessingml/2006/main', localPart: 'p' }, value };
 }
 export { isElement as isTypedElement };
+// CR-002 phase G (comments) needs the two internals above: the run holders to walk to the
+// markers inside hyperlinks and insertions, and the per-item text to give a marker its offset.
+export { RUN_HOLDERS, itemText as itemTextOf };

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

@@ -0,0 +1,158 @@
+import type { CustomXmlDataStoragePart } from '../../parts/DefaultXmlPart.mjs';
+import { type XPathEngine, parsePrefixMappings, formatPrefixMappings } from './xpath.mjs';
+/** Office JS `Word.CustomXmlNodeType`, in the CR's spelling. */
+export type CustomXmlNodeType = 'Element' | 'Attribute' | 'Text' | 'CData' | 'ProcessingInstruction' | 'Comment' | 'Document' | 'Other';
+/** One prefix mapping of a part's namespace manager. */
+export interface CustomXmlPrefixMapping {
+    prefix: string;
+    namespaceUri: string;
+}
+/**
+ * Office JS `Word.CustomXmlPrefixMappingCollection`: the prefixes an XPath over this part may use.
+ * Seeded from the namespace declarations of the document element, so that a part Word wrote can be
+ * queried without declaring anything.
+ */
+export declare class CustomXmlPrefixMappingCollection {
+    private readonly map;
+    constructor(seed?: Record<string, string>);
+    get items(): CustomXmlPrefixMapping[];
+    addNamespace(prefix: string, namespaceUri: string): void;
+    /** The URI a prefix stands for, '' when it stands for none (Office JS lookupNamespace). */
+    lookupNamespace(prefix: string): string;
+    /** The first prefix bound to a URI, '' when none is (Office JS lookupPrefix). */
+    lookupPrefix(namespaceUri: string): string;
+    /** The mappings as an `xmlns:ns0='...'` string and as a map, for the engine. */
+    toMap(): Record<string, string>;
+}
+/** What a part view needs of its collection: the engine, and the removal of a part. */
+export interface CustomXmlPartOwner {
+    readonly xpathEngine: XPathEngine;
+    removePart(part: CustomXmlPart): void;
+}
+/**
+ * A subset of Office JS `Word.CustomXmlPart` over a `CustomXmlDataStoragePart` (the customer's XML,
+ * a DOM) and its properties part (the `ds:datastoreItem` with the itemID and the schema
+ * references). The properties part is read from its DOM, never unmarshalled, so it stays byte for
+ * byte (as `Load` does for the itemID).
+ */
+export declare class CustomXmlPart {
+    /** The data part (extension: docx4j's part is the object here). */
+    readonly part: CustomXmlDataStoragePart;
+    private readonly owner;
+    /** The itemID as the properties part spells it, '{...}'. */
+    readonly itemID: string;
+    /** The `ds:schemaRef` URIs of the properties part. */
+    private readonly schemaRefs;
+    private prefixes;
+    constructor(
+    /** The data part (extension: docx4j's part is the object here). */
+    part: CustomXmlDataStoragePart, owner: CustomXmlPartOwner, 
+    /** The itemID as the properties part spells it, '{...}'. */
+    itemID: string, 
+    /** The `ds:schemaRef` URIs of the properties part. */
+    schemaRefs?: string[]);
+    /** The itemID, as Office JS reports it ('{...}'). */
+    get id(): string;
+    /** The DOM; throws when the part has not been parsed yet (`await pkg.customXmlParts.load()`). */
+    get document(): Document;
+    /** The document element as a node view. */
+    get documentElement(): CustomXmlNode;
+    /** The namespace of the document element ('' when it is in none). */
+    get namespaceUri(): string;
+    /** True for Word's own property stores (core, extended, custom and cover-page properties). */
+    get builtIn(): boolean;
+    /** The prefixes an XPath over this part may use; seeded from the document element's declarations. */
+    get namespaceManager(): CustomXmlPrefixMappingCollection;
+    /** The `ds:schemaRef` URIs of the properties part (Office JS schemaCollection). */
+    get schemaCollection(): string[];
+    /** The part's XML. Synchronous: a DOM part does not go through the marshaller. */
+    getXml(): string;
+    /** Replaces the part's XML; the part is re-marshalled on save. */
+    setXml(xml: string): void;
+    /** The nodes an XPath selects; `namespaceMappings` is Word's `xmlns:ns0='...'` string, else the namespace manager's. */
+    selectNodes(xpath: string, namespaceMappings?: string): CustomXmlNode[];
+    selectSingleNode(xpath: string, namespaceMappings?: string): CustomXmlNode | undefined;
+    /**
+     * Inserts `xml` as a child of the node the XPath selects, at `index` (appended when omitted).
+     * Departure from Office JS, which puts `namespaceMappings` second: here it is last and optional,
+     * as CR-002 section 3.5 specifies (section 12).
+     */
+    insertElement(xpath: string, xml: string, namespaceMappings?: string, index?: number): CustomXmlNode;
+    /** Replaces the element the XPath selects with `xml`. */
+    updateElement(xpath: string, xml: string, namespaceMappings?: string): void;
+    /** Removes the element the XPath selects. */
+    deleteElement(xpath: string, namespaceMappings?: string): void;
+    /** Adds an attribute to the element the XPath selects. */
+    insertAttribute(xpath: string, name: string, value: string, namespaceMappings?: string): void;
+    /** Sets an attribute of the element the XPath selects (`prefix:name` is written in that prefix's namespace). */
+    updateAttribute(xpath: string, name: string, value: string, namespaceMappings?: string): void;
+    /** Removes an attribute of the element the XPath selects. */
+    deleteAttribute(xpath: string, name: string, namespaceMappings?: string): void;
+    /** Removes the part, its properties part and the relationships; bound controls lose their mapping. */
+    delete(): void;
+    /** Marks the part for re-marshalling: a DOM read for a query alone leaves it byte for byte. */
+    touch(): void;
+    get engine(): XPathEngine;
+    /** The prefix map to use: the given string, else the namespace manager's. */
+    mappingsFor(namespaceMappings: string | undefined): Record<string, string>;
+    selectFrom(context: Node, xpath: string, namespaceMappings?: string): CustomXmlNode[];
+    private requireNode;
+}
+/**
+ * A subset of Office JS `Word.CustomXmlNode`: a view over one DOM node of a custom XML part.
+ * `xpath` is the canonical `/ns0:a[1]/ns0:b[2]` form Word writes, which is what
+ * `XmlMapping.setMappingByNode` stores.
+ */
+export declare class CustomXmlNode {
+    /** The DOM node (extension). */
+    readonly node: Node;
+    /** The part the node belongs to. */
+    readonly ownerPart: CustomXmlPart;
+    constructor(
+    /** The DOM node (extension). */
+    node: Node, 
+    /** The part the node belongs to. */
+    ownerPart: CustomXmlPart);
+    /** The local name; for an attribute, its name. */
+    get baseName(): string;
+    get namespaceUri(): string;
+    get nodeType(): CustomXmlNodeType;
+    /** The node's value: an attribute's value, a text node's data, an element's text. */
+    get nodeValue(): string;
+    set nodeValue(value: string);
+    /** The node's text content; setting replaces an element's children with one text node. */
+    get text(): string;
+    set text(value: string);
+    /** The node's XML. */
+    get xml(): string;
+    /** The canonical XPath of this node, as Word writes it into `w:dataBinding`. */
+    get xpath(): string;
+    /** The prefix mappings that XPath needs (empty when the node is in no namespace). */
+    get prefixMappings(): string;
+    get attributes(): CustomXmlNode[];
+    get childNodes(): CustomXmlNode[];
+    /** The element children only (extension: what a reader of a data store usually wants). */
+    get childElements(): CustomXmlNode[];
+    get parentNode(): CustomXmlNode | undefined;
+    get firstChild(): CustomXmlNode | undefined;
+    get lastChild(): CustomXmlNode | undefined;
+    get nextSibling(): CustomXmlNode | undefined;
+    get previousSibling(): CustomXmlNode | undefined;
+    hasChildNodes(): boolean;
+    selectNodes(xpath: string, namespaceMappings?: string): CustomXmlNode[];
+    selectSingleNode(xpath: string, namespaceMappings?: string): CustomXmlNode | undefined;
+    /**
+     * Appends a child. Both forms of CR-002 open question 8 are taken: the XML text form
+     * `appendChildNode('<price>$20</price>')`, which is what an agent produces, and Office JS's
+     * `appendChildNode(name, namespaceUri, nodeType, nodeValue)`.
+     */
+    appendChildNode(xml?: string, namespaceUri?: string, nodeType?: CustomXmlNodeType, nodeValue?: string, index?: number): CustomXmlNode;
+    /** Inserts a node before a sibling (appended when the sibling is omitted), as Office JS. */
+    insertNodeBefore(xml: string, nextSibling?: CustomXmlNode): CustomXmlNode;
+    removeChild(child: CustomXmlNode): void;
+    replaceChildNode(oldNode: CustomXmlNode, xml: string): CustomXmlNode;
+    /** Removes this node from its parent. */
+    delete(): void;
+    private create;
+}
+export { formatPrefixMappings, parsePrefixMappings };