@docx4j/core-ts 0.4.0 → 0.6.0

package/dist/model/content/placeholders.mjs

@@ -0,0 +1,253 @@
+import * as el from '@docx4j/generated-objects-ts/el/org_docx4j_wml';
+import * as f from '@docx4j/generated-objects-ts/factory/org_docx4j_wml';
+import { sdtProperty, sdtKindOf, textOf } from '@docx4j/generated-objects-ts/builders/wml';
+import { deepCopy } from '@docx4j/generated-objects-ts';
+import { linkParents } from './tree.mjs';
+import { uuid } from '../customxml/CustomXmlPartCollection.mjs';
+import { PLACEHOLDER_STYLE, placeholderRun } from '../customxml/bindings.mjs';
+import { placeholderStyle } from '../../parts/wml/placeholderStyle.mjs';
+/** Word's default placeholder entry, which a control Word makes names (checks 64 to 66). */
+export const DEFAULT_PLACEHOLDER_ENTRY = 'DefaultPlaceholder_-1854013440';
+/** The default entry's text, as Word 365 writes it. */
+export const DEFAULT_PLACEHOLDER_TEXT = 'Click or tap here to enter text.';
+/**
+ * Word's default placeholder entry for each kind of control that has one, as Word 365 makes them from the Developer tab
+ * (Jason's `placeholders.docx`, 2026-10-25; CR-002 section 63.22, as docx4j's CR-063 D8 has it): each in the glossary
+ * with the default entry's `w:docPartPr`, its body one run in the Placeholder Text style. A picture, a check box and a
+ * repeating section have none; the group, citation, equation, bibliography and `w:docPartObj` kinds are unmeasured.
+ */
+export const DEFAULT_ENTRIES = {
+    text: { name: DEFAULT_PLACEHOLDER_ENTRY, text: DEFAULT_PLACEHOLDER_TEXT },
+    date: { name: 'DefaultPlaceholder_-1854013437', text: 'Click or tap to enter a date.' },
+    list: { name: 'DefaultPlaceholder_-1854013438', text: 'Choose an item.' },
+    buildingBlock: { name: 'DefaultPlaceholder_-1854013436', text: 'Choose a building block.' },
+    repeatingSectionItem: {
+        name: 'DefaultPlaceholder_-1854013435',
+        text: 'Enter any content that you want to repeat, including other content controls. You can also insert this control around table rows in order to repeat parts of a table.',
+    },
+};
+/** The default entry Word gives a control of this kind (`DEFAULT_ENTRIES`); undefined for a kind it gives none. */
+export function defaultEntryFor(sdtPr) {
+    switch (sdtKindOf(sdtPr)) {
+        case 'RichText':
+        case 'PlainText': return DEFAULT_ENTRIES.text;
+        case 'DatePicker': return DEFAULT_ENTRIES.date;
+        case 'DropDownList':
+        case 'ComboBox': return DEFAULT_ENTRIES.list;
+        case 'BuildingBlockGallery': return sdtProperty(sdtPr, 'docPartList') ? DEFAULT_ENTRIES.buildingBlock : undefined;
+        case 'RepeatingSectionItem': return DEFAULT_ENTRIES.repeatingSectionItem;
+        default: return undefined;
+    }
+}
+/** The glossary entry a control's `w:placeholder` names; undefined where it names none (the bare form). */
+export function placeholderEntryOf(sdtPr) {
+    var _a, _b, _c;
+    const value = (_a = sdtProperty(sdtPr, 'placeholder')) === null || _a === void 0 ? void 0 : _a.value;
+    return value === undefined ? undefined : (_c = (_b = value.docPart) === null || _b === void 0 ? void 0 : _b.val) !== null && _c !== void 0 ? _c : '';
+}
+/**
+ * Names `entry` in the control's `w:placeholder`, where Word writes it: after `w:id`, before `w:showingPlcHdr` and the
+ * binding (check 64's controls, as Word saved them).
+ */
+export function namePlaceholderEntry(sdtPr, entry) {
+    var _a;
+    const items = ((_a = sdtPr.rPrOrAliasOrLock) !== null && _a !== void 0 ? _a : (sdtPr.rPrOrAliasOrLock = []));
+    const element = el.placeholder(f.createCTPlaceholder({ docPart: f.createCTPlaceholderDocPart({ val: entry }) }));
+    const at = items.findIndex((i) => i.name.localPart === 'placeholder');
+    if (at >= 0) {
+        items[at] = element;
+        linkParents(element, sdtPr);
+        return;
+    }
+    const after = new Set(['showingPlcHdr', 'dataBinding', 'temporary']);
+    const before = items.findIndex((i) => after.has(i.name.localPart));
+    items.splice(before < 0 ? items.length : before, 0, element);
+    linkParents(element, sdtPr);
+}
+/** A new entry's name, as Word names one: 32 upper-case hex digits, a new GUID's (check 65). */
+export function newEntryName() {
+    return uuid().replace(/-/g, '').toUpperCase();
+}
+/**
+ * The placeholder entries of a package's glossary: those its glossary document part holds, read privately (the part
+ * stays untouched), and those written since, which go into the glossary when the package is saved (`flush`).
+ */
+export class GlossaryEntries {
+    constructor() {
+        /** Entries to write on save: name, text. */
+        this.pending = new Map();
+    }
+    /** Reads the glossary's entries, privately; again only where the part changed. */
+    async load(glossary) {
+        if (glossary === this.source && this.read !== undefined)
+            return;
+        this.source = glossary;
+        this.read = glossary ? entriesOf(await glossary.readContents().catch(() => undefined)) : new Map();
+    }
+    /**
+     * An entry's text, `null` where neither the glossary nor this session holds it, as Office JS reads it (check 65). An
+     * entry's paragraphs are a `\r` apart, as a control's are.
+     */
+    textOf(name) {
+        var _a, _b;
+        return (_b = (_a = this.entry(name)) === null || _a === void 0 ? void 0 : _a.text) !== null && _b !== void 0 ? _b : null;
+    }
+    /**
+     * An entry's body, the blocks of its `w:docPartBody` (not copies), `null` where neither the glossary nor this session
+     * holds it; an entry written this session is one paragraph, one run of its text in the Placeholder Text style.
+     */
+    bodyOf(name) {
+        var _a, _b;
+        return (_b = (_a = this.entry(name)) === null || _a === void 0 ? void 0 : _a.body) !== null && _b !== void 0 ? _b : null;
+    }
+    /** True once the glossary has been read (`load`): until then an entry it holds reads as missing. */
+    get loaded() {
+        var _a;
+        return this.read !== undefined || ((_a = this.source) === null || _a === void 0 ? void 0 : _a.isUnmarshalled) === true;
+    }
+    entry(name) {
+        var _a;
+        const pending = this.pending.get(name);
+        if (pending !== undefined)
+            return { text: pending, body: [el.p({ content: [placeholderRun(undefined, pending)] })] };
+        const part = this.source;
+        if (part === null || part === void 0 ? void 0 : part.isUnmarshalled)
+            return entriesOf(part.contents).get(name);
+        return (_a = this.read) === null || _a === void 0 ? void 0 : _a.get(name);
+    }
+    /** Whether the glossary holds an entry of this name, or one is waiting to be written. */
+    has(name) {
+        return this.textOf(name) !== null;
+    }
+    /** An entry to write on save, where the glossary doesn't hold one of that name. */
+    require(name, text) {
+        if (!this.has(name))
+            this.pending.set(name, text);
+    }
+    /** True while entries wait for the save. */
+    get waiting() {
+        return this.pending.size > 0;
+    }
+    /** Entries waiting for the save, for a clone. */
+    copyTo(target) {
+        for (const [name, text] of this.pending)
+            target.pending.set(name, text);
+    }
+    /**
+     * Writes the waiting entries into the glossary, making it where the file has none (D9 (a): the glossary document
+     * part and a styles part holding Placeholder Text, related from it), and puts Placeholder Text into a glossary's
+     * styles part that lacks it: an entry whose style its glossary lacks loses it in Word's save (check 65's 65b).
+     */
+    async flush(host, make) {
+        var _a;
+        if (this.pending.size === 0)
+            return;
+        const main = host.getMainDocumentPart();
+        let glossary = main.glossaryDocumentPart;
+        if (!glossary) {
+            glossary = make.glossary();
+            glossary.setContents(f.createGlossaryDocument({ docParts: f.createCTDocParts({ docPart: [] }) }));
+            main.addTargetPart(glossary);
+        }
+        const doc = await glossary.getContents();
+        const docParts = ((_a = doc.docParts) !== null && _a !== void 0 ? _a : (doc.docParts = f.createCTDocParts({ docPart: [] })));
+        linkParents(docParts, doc);
+        const present = entriesOf(doc);
+        for (const [name, text] of this.pending) {
+            if (present.has(name))
+                continue;
+            const part = docPartOf(name, text);
+            docParts.docPart.push(part);
+            linkParents(part, docParts);
+        }
+        this.pending.clear();
+        this.source = glossary;
+        await ensureGlossaryStyles(glossary, make.styles);
+    }
+}
+/** A glossary's entries by name. */
+function entriesOf(doc) {
+    var _a, _b, _c, _d, _e;
+    const out = new Map();
+    for (const part of (_b = (_a = doc === null || doc === void 0 ? void 0 : doc.docParts) === null || _a === void 0 ? void 0 : _a.docPart) !== null && _b !== void 0 ? _b : []) {
+        const name = (_c = part.docPartPr) === null || _c === void 0 ? void 0 : _c.nameOrStyleOrCategory.find((i) => i.TYPE_NAME === 'org_docx4j_wml.CTDocPartName');
+        if (!(name === null || name === void 0 ? void 0 : name.val))
+            continue;
+        const body = ((_e = (_d = part.docPartBody) === null || _d === void 0 ? void 0 : _d.content) !== null && _e !== void 0 ? _e : []);
+        const paragraphs = body.filter((e) => e.value.TYPE_NAME === 'org_docx4j_wml.P');
+        out.set(name.val, { text: paragraphs.map((p) => textOf(p.value)).join('\r'), body });
+    }
+    return out;
+}
+/**
+ * What a control shows of an entry (CR-002 section 63.18, as revised by 63.21): a copy of each of its body's paragraphs'
+ * run-level content, every run as the glossary holds it. Word brought an entry back so, the control's own run properties
+ * not over it (check 68, cases 21 to 24), and doesn't restyle it (check 65's 65b, case 9). The paragraphs' properties stay
+ * in the glossary, whose styles they name.
+ */
+export function entryContentOf(body) {
+    var _a;
+    const out = [];
+    for (const block of body) {
+        if (block.value.TYPE_NAME !== 'org_docx4j_wml.P')
+            continue;
+        const items = ((_a = block.value.content) !== null && _a !== void 0 ? _a : []).filter((e) => { var _a, _b; return !['proofErr', 'bookmarkStart', 'bookmarkEnd'].includes((_b = (_a = e.name) === null || _a === void 0 ? void 0 : _a.localPart) !== null && _b !== void 0 ? _b : ''); });
+        out.push(items.map((item) => ({ name: item.name, value: deepCopy(item.value) })));
+    }
+    return out;
+}
+/**
+ * A placeholder entry as Word writes one (check 65): the default entry's `w:docPartPr` (category General, gallery
+ * placeholder, type `bbPlcHdr`, behaviour content) with a `w:guid` of its own, and a body of one paragraph, one run in
+ * the Placeholder Text style.
+ */
+function docPartOf(name, text) {
+    const pr = f.createCTDocPartPr({
+        nameOrStyleOrCategory: [
+            f.createCTDocPartName({ val: name }),
+            f.createCTDocPartCategory({ name: f.createCTDocPartCategoryName({ val: 'General' }), gallery: f.createCTDocPartGallery({ val: 'placeholder' }) }),
+            f.createCTDocPartTypes({ type: [f.createCTDocPartType({ val: 'bbPlcHdr' })] }),
+            f.createCTDocPartBehaviors({ behavior: [f.createCTDocPartBehavior({ val: 'content' })] }),
+            f.createCTGuid({ val: `{${uuid().toUpperCase()}}` }),
+        ],
+    });
+    const body = f.createBody({ content: [el.p({ content: [placeholderRun(undefined, text)] })] });
+    return f.createCTDocPart({ docPartPr: pr, docPartBody: body });
+}
+/** Default Paragraph Font as Word defines it, which Placeholder Text is based on (check 34's glossary). */
+function defaultParagraphFont() {
+    return f.createStyle({
+        type: 'character', _default: true, styleId: 'DefaultParagraphFont',
+        name: f.createStyleName({ val: 'Default Paragraph Font' }),
+        uiPriority: f.createStyleUiPriority({ val: 1 }),
+        semiHidden: f.createBooleanDefaultTrue(),
+        unhideWhenUsed: f.createBooleanDefaultTrue(),
+    });
+}
+/** The glossary's styles part holds Placeholder Text and the style it is based on, made where the glossary has none. */
+async function ensureGlossaryStyles(glossary, make) {
+    var _a, _b;
+    const holder = glossary;
+    let part = holder.styleDefinitionsPart;
+    if (!part) {
+        part = make();
+        part.setContents(f.createStyles({ style: [] }));
+        holder.addTargetPart(part);
+    }
+    else {
+        // a styles part that has them already stays untouched
+        const read = await part.readContents().catch(() => undefined);
+        const ids = new Set(((_a = read === null || read === void 0 ? void 0 : read.style) !== null && _a !== void 0 ? _a : []).map((s) => s.styleId));
+        if (ids.has('DefaultParagraphFont') && ids.has(PLACEHOLDER_STYLE))
+            return;
+    }
+    const styles = await part.getContents();
+    const list = ((_b = styles.style) !== null && _b !== void 0 ? _b : (styles.style = []));
+    const ids = new Set(list.map((s) => s.styleId));
+    for (const style of [defaultParagraphFont(), placeholderStyle()]) {
+        if (ids.has(style.styleId))
+            continue;
+        list.push(style);
+        linkParents(style, styles);
+    }
+}

package/dist/model/content/relationships.d.mts

@@ -0,0 +1,30 @@
+import type { Part } from '../../parts/Part.mjs';
+/**
+ * Adds to `into` every relationship id a tree references: the `r:` attributes of its typed objects (read
+ * off the model's mapping, as docx4j reads its fields' `@XmlAttribute`), those kept in an
+ * `otherAttributes` map, and those of any DOM it holds.
+ */
+export declare function relationshipIdsIn(tree: unknown, into: Set<string>): void;
+/**
+ * The relationships of `part` among `candidates` that nothing left in the part references are removed,
+ * and the part each targeted when no relationship in the package targets it any more, with what that
+ * part alone related to (`RelationshipsPart.removeParts`). A part not unmarshalled can't be read for
+ * what still references, so nothing is removed from it.
+ */
+export declare function dropRelationshipsUnused(part: Part, candidates: Set<string>): void;
+/**
+ * Relationship ids, by the name of the part they belong to, that content removed outside a
+ * resolution referenced: a picture deleted with tracking off, or taken back from its author's own
+ * insertion. They are settled when the package is saved rather than at once, so that content put
+ * back in the meantime (a cut and a paste of the same drawing) keeps its relationship.
+ */
+export type RelationshipRemovals = Map<string, Set<string>>;
+/** Queues `ids` of `part` for `flushPendingRelationshipRemovals`. */
+export declare function queueRelationshipRemovals(pending: RelationshipRemovals | undefined, part: Part | undefined, ids: Iterable<string>): void;
+/** What `flushPendingRelationshipRemovals` needs of the package. */
+interface PartsHost {
+    getPart(name: string): Part | undefined;
+}
+/** Settles the queued ids against each part as it now stands (`dropRelationshipsUnused`); then `pending` is empty. */
+export declare function flushPendingRelationshipRemovals(pkg: PartsHost, pending: RelationshipRemovals): void;
+export {};

package/dist/model/content/relationships.mjs

@@ -0,0 +1,133 @@
+/**
+ * The relationships content references, and the removal of those nothing references any more
+ * (CR-002 section 46, docx4j CR-043's D7): shared by the tracked-change resolution
+ * (`TrackedChange.mts`) and the pictures (`InlinePicture.delete`, section 47).
+ */
+import { getContextSync } from '@docx4j/generated-objects-ts';
+const R_NS = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+/** Per type, the properties that are attributes in the relationships namespace (`r:id`, `r:embed`, `r:link`, ...). */
+const relationshipAttributes = new Map();
+function relationshipAttributesOf(typeName) {
+    var _a, _b;
+    let names = relationshipAttributes.get(typeName);
+    if (names)
+        return names;
+    const found = [];
+    let info;
+    try {
+        info = getContextSync().getTypeInfoByName(typeName);
+    }
+    catch {
+        info = undefined;
+    }
+    for (let ti = info; ti; ti = ti.baseTypeInfo) {
+        for (const property of (_a = ti.properties) !== null && _a !== void 0 ? _a : []) {
+            if (((_b = property.attributeName) === null || _b === void 0 ? void 0 : _b.namespaceURI) === R_NS && property.name)
+                found.push(property.name);
+        }
+    }
+    relationshipAttributes.set(typeName, names = found);
+    return names;
+}
+/**
+ * Adds to `into` every relationship id a tree references: the `r:` attributes of its typed objects (read
+ * off the model's mapping, as docx4j reads its fields' `@XmlAttribute`), those kept in an
+ * `otherAttributes` map, and those of any DOM it holds.
+ */
+export function relationshipIdsIn(tree, into) {
+    const seen = new Set();
+    const visitDom = (node) => {
+        if (node.nodeType !== 1)
+            return;
+        const attributes = node.attributes;
+        for (let i = 0; i < attributes.length; i++) {
+            const a = attributes[i];
+            if (a.namespaceURI === R_NS && a.value)
+                into.add(a.value);
+        }
+        for (let c = node.firstChild; c; c = c.nextSibling)
+            visitDom(c);
+    };
+    const visit = (o) => {
+        if (typeof o !== 'object' || o === null || seen.has(o))
+            return;
+        seen.add(o);
+        if (Array.isArray(o)) {
+            for (const item of o)
+                visit(item);
+            return;
+        }
+        if (typeof o.nodeType === 'number') {
+            visitDom(o);
+            return;
+        }
+        const record = o;
+        const typeName = record.TYPE_NAME;
+        if (typeof typeName === 'string') {
+            for (const name of relationshipAttributesOf(typeName)) {
+                const value = record[name];
+                if (typeof value === 'string' && value)
+                    into.add(value);
+            }
+        }
+        const other = record.otherAttributes;
+        if (other && typeof other === 'object') {
+            for (const [key, value] of Object.entries(other))
+                if (key.startsWith(`{${R_NS}}`) && typeof value === 'string')
+                    into.add(value);
+        }
+        for (const key in record)
+            if (key !== 'PARENT' && key !== 'otherAttributes')
+                visit(record[key]);
+    };
+    visit(tree);
+}
+/**
+ * The relationships of `part` among `candidates` that nothing left in the part references are removed,
+ * and the part each targeted when no relationship in the package targets it any more, with what that
+ * part alone related to (`RelationshipsPart.removeParts`). A part not unmarshalled can't be read for
+ * what still references, so nothing is removed from it.
+ */
+export function dropRelationshipsUnused(part, candidates) {
+    var _a, _b;
+    const rels = part.relationshipsPart;
+    const contents = part.isUnmarshalled
+        ? part.contents : undefined;
+    if (!rels || contents === undefined)
+        return;
+    const used = new Set();
+    relationshipIdsIn(contents, used);
+    for (const id of candidates) {
+        if (used.has(id))
+            continue;
+        const rel = rels.getRelationshipById(id);
+        if (!rel)
+            continue;
+        const target = rels.getPart(rel);
+        rels.removeRelationship(rel);
+        if (target && target.sourceRelationships.length === 0) {
+            (_a = target.relationshipsPart) === null || _a === void 0 ? void 0 : _a.removeParts();
+            (_b = target.package) === null || _b === void 0 ? void 0 : _b.parts.remove(target.partName);
+        }
+    }
+}
+/** Queues `ids` of `part` for `flushPendingRelationshipRemovals`. */
+export function queueRelationshipRemovals(pending, part, ids) {
+    if (!pending || !part)
+        return;
+    let set = pending.get(part.partName.name);
+    for (const id of ids) {
+        if (!set)
+            pending.set(part.partName.name, set = new Set());
+        set.add(id);
+    }
+}
+/** Settles the queued ids against each part as it now stands (`dropRelationshipsUnused`); then `pending` is empty. */
+export function flushPendingRelationshipRemovals(pkg, pending) {
+    for (const [name, ids] of pending) {
+        const part = pkg.getPart(name);
+        if (part)
+            dropRelationshipsUnused(part, ids);
+    }
+    pending.clear();
+}

package/dist/model/content/search.d.mts

@@ -43,3 +43,75 @@ export declare function matchesOf(text: string, pattern: RegExp): RegExpExecArra
  * to nothing, as both languages do.
  */
 export declare function expandReplacement(replacement: string, match: RegExpExecArray, options?: SearchOptions): string;
+/** What `officeMatches` reads of a paragraph: its segments in Office JS's characters, the objects and hidden items listed. */
+export interface SearchSegment {
+    text: string;
+    start: number;
+    object?: boolean;
+    hidden?: boolean;
+    item: {
+        name: {
+            localPart: string;
+        };
+    };
+}
+/** One match, as offsets in `Paragraph.text`, with the expression's match over the search's own text. */
+export interface OfficeMatch {
+    start: number;
+    end: number;
+    match: RegExpExecArray;
+}
+/**
+ * Every match of a query in a paragraph's text by Office JS's rules (check 48, Word's default view): the
+ * text is `Paragraph.text` (hidden text left out, so a query matches across it and never in it), where a
+ * picture is a place of no text that a plain query doesn't match across and `^g` matches, and an optional
+ * hyphen is passed over unless the query names it (`^-`). A plain query takes Word's Find codes
+ * (`FIND_CODES`), and its `-` matches a non-breaking hyphen too. Wildcards read the same text, the codes
+ * not translated; a regular expression (`matchRegExp`, this package's extension) reads `Paragraph.text`
+ * itself. Only text in [from, to) is read: a range's search.
+ */
+export declare function officeMatches(segments: readonly SearchSegment[], query: string, options?: SearchOptions, from?: number, to?: number): OfficeMatch[];
+/** A paragraph's part in a wildcard search across its marks: its segments, the [from, to) of its text read, its text's length, whether its mark follows. */
+export interface MarkedSegments {
+    segments: readonly SearchSegment[];
+    from: number;
+    to: number;
+    length: number;
+    mark: boolean;
+}
+/** A hit of a wildcard search across marks: from offset `start` in piece `first` to `end` in piece `last`, which holds its mark where `mark`. */
+export interface MarkedMatch {
+    first: number;
+    start: number;
+    last: number;
+    end: number;
+    mark: boolean;
+    match: RegExpExecArray;
+}
+/**
+ * A wildcard query's hits over consecutive paragraphs, each followed by its mark where `mark` says, as Word's wildcards
+ * match a paragraph mark (check 59; CR-002 section 32, K7): `?`, `*` and a class cross one, `^13` is one. The text read
+ * in each paragraph is `officeMatches`' for wildcards; the caller gives only paragraphs a hit may span (one cell's, or
+ * none's) and only the marks it may hold (a paragraph's own, never a cell's or a row's end).
+ */
+export declare function wildcardMatchesAcross(pieces: readonly MarkedSegments[], query: string, options: SearchOptions): MarkedMatch[];
+/**
+ * Refuses a wildcard replacement where a hit holds a paragraph mark (CR-002 section 32, K7): `search` finds it, as
+ * Word's does (check 59), but what replacing a mark leaves isn't measured, as for a plain `^p` (`refuseMarkReplacement`).
+ */
+export declare function refuseWildcardMarkReplacement(className: string, hits: readonly {
+    spansParagraphs: boolean;
+    holdsEndMark: boolean;
+}[]): void;
+/**
+ * A plain query split at Word's paragraph mark code, `^p`: its pieces, one more than the marks, each a plain
+ * query of its own (`^^` stays an escaped caret); undefined where the query holds no `^p`. What a `Range`'s search
+ * across paragraphs matches piece by piece (CR-014 phase 3).
+ */
+export declare function paragraphMarkPieces(query: string): string[] | undefined;
+/**
+ * Refuses a replacement whose query holds `^p` (CR-014 phase 3): `search` finds such a hit, but what Office JS's
+ * replacement of a paragraph mark leaves isn't measured, and `insertText('Replace')` keeps a last mark (check 52).
+ * Until phase 3 such a query matched the two characters `^p`, where Word matches a mark.
+ */
+export declare function refuseMarkReplacement(className: string, find: string, options?: SearchOptions): void;