@docx4j/core-ts 0.1.0 → 0.1.2

package/dist/office-js/toApiScript.d.mts

@@ -0,0 +1,25 @@
+import { Body } from '../model/content/Body.mjs';
+import { Paragraph } from '../model/content/Paragraph.mjs';
+import { Range } from '../model/content/Range.mjs';
+import { type Element } from '../model/content/tree.mjs';
+export interface ApiScriptOptions {
+    /** The variable the script inserts into; default `'body'`. */
+    variable?: string;
+    /** The insert location; default `'End'`. */
+    location?: 'Start' | 'End';
+    /** Prefix for every line; default `''`. */
+    indent?: string;
+}
+/** What `toApiScript` takes: a view, an element of the tree, or several. */
+export type ApiScriptTarget = Body | Paragraph | Range | Element | Element[];
+/**
+ * The content-API script that reproduces what it is given, as TypeScript against `body`: the verbs
+ * where they exist (`insertParagraph`, `style`, `alignment`, the indents and spacing, `insertText`
+ * with `Range.font` per run, `insertBreak`, `insertTable`), and `insertXml` with the marshalled
+ * fragment for the rest. Emitted for reveal codes, for teaching the API by example, and for an
+ * agent that wants the calls rather than the tree.
+ *
+ * The script is a sequence of statements over `body`; it uses `await` for the `insertXml` lines,
+ * so run it in an async function (`new Function('body', 'return (async () => {' + script + '})()')`).
+ */
+export declare function toApiScript(target: ApiScriptTarget, options?: ApiScriptOptions): Promise<string>;

package/dist/office-js/toApiScript.mjs

@@ -0,0 +1,394 @@
+// `toApiScript` (CR-002 section 3.10): the content-API calls that reproduce a paragraph, a range,
+// a table or a body, emitted as TypeScript against `body`. The counterpart of the objects
+// package's `toSource`, which emits the factory calls that build the element; this one stays in
+// the vocabulary an add-in author (or an agent writing one) reads, and falls back to `insertXml`
+// with the marshalled fragment for what the verbs cannot express.
+import { marshalString } from '@docx4j/generated-objects-ts';
+import { readRunOptions } from '@docx4j/generated-objects-ts/builders/wml';
+import { Docx4JException } from '../opc/exceptions.mjs';
+import { Body } from '../model/content/Body.mjs';
+import { Paragraph } from '../model/content/Paragraph.mjs';
+import { Range } from '../model/content/Range.mjs';
+import { isElement, typeNameOf, textOf } from '../model/content/tree.mjs';
+import { paragraphElementOfRange } from './fragment.mjs';
+import { builtInOf, displayNameOf } from '../model/content/styles.mjs';
+const TWIPS_PER_POINT = 20;
+/** Paragraph properties the verbs express; anything else sends the paragraph to `insertXml`. */
+const PPR_KEYS = new Set(['TYPE_NAME', 'PARENT', 'pStyle', 'jc', 'ind', 'spacing', 'outlineLvl', 'numPr']);
+const NUMPR_KEYS = new Set(['TYPE_NAME', 'PARENT', 'numId', 'ilvl']);
+/** The `member` of a property pair that is a **call**, not an assignment (`attachToList`). */
+const CALL = '()';
+const IND_KEYS = new Set(['TYPE_NAME', 'PARENT', 'left', 'right', 'firstLine', 'hanging']);
+const SPACING_KEYS = new Set(['TYPE_NAME', 'PARENT', 'before', 'after', 'line', 'lineRule']);
+/** Run properties the `Font` members express (the objects package's applyRunOptions vocabulary). */
+const RPR_KEYS = new Set(['TYPE_NAME', 'PARENT', 'b', 'bCs', 'i', 'iCs', 'u', 'strike', 'dstrike', 'vertAlign', 'rFonts', 'sz', 'szCs', 'color', 'highlight']);
+const RFONTS_KEYS = new Set(['TYPE_NAME', 'PARENT', 'ascii', 'hAnsi']);
+/** Markers that carry no content: dropped, since no verb writes them. */
+const IGNORED_TYPES = new Set(['org_docx4j_wml.ProofErr', 'org_docx4j_wml.CTEmpty']);
+const BOOKMARK_TYPES = new Set(['org_docx4j_wml.CTBookmark', 'org_docx4j_wml.CTMarkupRange']);
+/** Table properties `insertTable` can reproduce. */
+const TBLPR_KEYS = new Set(['TYPE_NAME', 'PARENT', 'tblStyle', 'tblW', 'tblLook']);
+/** Marks a construct the verbs cannot express: the caller falls back to `insertXml`. */
+class Unexpressible extends Error {
+}
+function quote(text) {
+    const escaped = text
+        .replace(/\\/g, '\\\\')
+        .replace(/'/g, "\\'")
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')
+        .replace(/\t/g, '\\t');
+    return `'${escaped}'`;
+}
+function template(xml) {
+    return '`' + xml.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${') + '`';
+}
+function num(value) {
+    return String(Math.round(value * 100) / 100);
+}
+function keysOf(value) {
+    return Object.keys(value).filter((k) => value[k] !== undefined);
+}
+function within(value, allowed) {
+    return keysOf(value).every((k) => allowed.has(k));
+}
+const DEFAULT_FORMAT = readRunOptions(undefined);
+/** The `Font` assignments that turn `from` into `to`; throws when a property cannot be unset. */
+function fontDiff(from, to) {
+    const out = [];
+    const flags = ['bold', 'italic', 'strikeThrough', 'doubleStrikeThrough', 'subscript', 'superscript'];
+    for (const flag of flags)
+        if (from[flag] !== to[flag])
+            out.push([flag, String(to[flag])]);
+    if (from.underline !== to.underline)
+        out.push(['underline', quote(to.underline)]);
+    if (from.name !== to.name)
+        out.push(['name', quote(to.name)]);
+    if (from.size !== to.size) {
+        // Font.size writes w:sz; there is no size that removes it, so a run that drops a direct size
+        // after one that set it is not expressible (CR-002 section 10).
+        if (to.size === 0)
+            throw new Unexpressible('a run drops a direct font size');
+        out.push(['size', num(to.size)]);
+    }
+    if (from.color !== to.color)
+        out.push(['color', quote(to.color)]);
+    if (from.highlightColor !== to.highlightColor)
+        out.push(['highlightColor', to.highlightColor === null ? 'null' : quote(to.highlightColor)]);
+    if (from.style !== to.style)
+        throw new Unexpressible('a run style (w:rStyle)');
+    return out;
+}
+/** The emitter: one instance per call, so that variable names are stable and readable. */
+class Emitter {
+    constructor(options) {
+        var _a, _b, _c;
+        this.lines = [];
+        this.paragraphs = 0;
+        this.ranges = 0;
+        this.tables = 0;
+        this.variable = (_a = options.variable) !== null && _a !== void 0 ? _a : 'body';
+        this.location = (_b = options.location) !== null && _b !== void 0 ? _b : 'End';
+        this.indent = (_c = options.indent) !== null && _c !== void 0 ? _c : '';
+    }
+    script() {
+        return this.lines.join('\n');
+    }
+    line(text) {
+        this.lines.push(this.indent + text);
+    }
+    /** A block-level element: a paragraph, a table, or anything else through `insertXml`. */
+    async element(element) {
+        const typeName = typeNameOf(element);
+        if (typeName === 'org_docx4j_wml.P')
+            await this.paragraph(element);
+        else if (typeName === 'org_docx4j_wml.Tbl')
+            await this.table(element);
+        else
+            await this.fallback(element);
+    }
+    async paragraph(element) {
+        try {
+            this.emitParagraph(element.value);
+        }
+        catch (error) {
+            if (!(error instanceof Unexpressible))
+                throw error;
+            await this.fallback(element, error.message);
+        }
+    }
+    /** A range: its text and run formatting, as one paragraph. */
+    async range(range) {
+        await this.paragraph(paragraphElementOfRange(range));
+    }
+    emitParagraph(p) {
+        const properties = this.paragraphProperties(p);
+        const pieces = piecesOf(p);
+        const first = pieces[0];
+        const plainFirst = first !== undefined && first.kind === 'text' && sameFormat(first.format, DEFAULT_FORMAT);
+        // Every font change is checked before a line is emitted, so a paragraph either comes out whole
+        // or falls back whole.
+        let previous = DEFAULT_FORMAT;
+        const diffs = [];
+        for (const piece of pieces.slice(plainFirst ? 1 : 0)) {
+            if (piece.kind === 'break') {
+                diffs.push(undefined);
+                previous = DEFAULT_FORMAT;
+                continue;
+            }
+            diffs.push(fontDiff(previous, piece.format));
+            previous = piece.format;
+        }
+        if (properties.length === 0 && plainFirst && pieces.length === 1) {
+            this.line(`${this.variable}.insertParagraph(${quote(first.text)}, '${this.location}');`);
+            return;
+        }
+        const name = `p${++this.paragraphs}`;
+        this.line(`const ${name} = ${this.variable}.insertParagraph(${quote(plainFirst ? first.text : '')}, '${this.location}');`);
+        for (const [member, value] of properties)
+            this.line(member === CALL ? `${name}.${value};` : `${name}.${member} = ${value};`);
+        pieces.slice(plainFirst ? 1 : 0).forEach((piece, i) => {
+            var _a;
+            if (piece.kind === 'break') {
+                this.line(`${name}.insertBreak('${piece.breakType}', 'End');`);
+                return;
+            }
+            const diff = (_a = diffs[i]) !== null && _a !== void 0 ? _a : [];
+            if (diff.length === 0) {
+                this.line(`${name}.insertText(${quote(piece.text)}, 'End');`);
+                return;
+            }
+            const range = `r${++this.ranges}`;
+            this.line(`const ${range} = ${name}.insertText(${quote(piece.text)}, 'End');`);
+            for (const [member, value] of diff)
+                this.line(`${range}.font.${member} = ${value};`);
+        });
+    }
+    /**
+     * The paragraph members that carry `w:pPr`; throws when it holds anything else.
+     *
+     * Reads the tree directly, not the property resolver: a script reproduces *markup*, not
+     * appearance, so it must set what the document states and nothing more. Emitting effective
+     * values would write a style's alignment, indents and size onto every paragraph and run of
+     * the generated document (CR-001 Phase B step 2; the same holds for `runFormat` below).
+     */
+    paragraphProperties(p) {
+        var _a, _b, _c, _d, _e, _f, _g;
+        const pPr = p.pPr;
+        if (!pPr)
+            return [];
+        if (!within(pPr, PPR_KEYS))
+            throw new Unexpressible(`paragraph properties (${keysOf(pPr).filter((k) => !PPR_KEYS.has(k)).join(', ')})`);
+        const out = [];
+        const style = (_a = pPr.pStyle) === null || _a === void 0 ? void 0 : _a.val;
+        if (style !== undefined && style !== 'Normal')
+            out.push(styleAssignment(style));
+        const jc = (_b = pPr.jc) === null || _b === void 0 ? void 0 : _b.val;
+        if (jc !== undefined) {
+            const alignment = jc === 'left' ? 'Left' : jc === 'center' ? 'Centered' : jc === 'right' ? 'Right' : jc === 'both' ? 'Justified' : undefined;
+            if (alignment === undefined)
+                throw new Unexpressible(`w:jc ${jc}`);
+            out.push(['alignment', quote(alignment)]);
+        }
+        const ind = pPr.ind;
+        if (ind) {
+            if (!within(ind, IND_KEYS))
+                throw new Unexpressible(`w:ind (${keysOf(ind).filter((k) => !IND_KEYS.has(k)).join(', ')})`);
+            if (ind.left !== undefined)
+                out.push(['leftIndent', num(ind.left / TWIPS_PER_POINT)]);
+            if (ind.right !== undefined)
+                out.push(['rightIndent', num(ind.right / TWIPS_PER_POINT)]);
+            if (ind.hanging !== undefined)
+                out.push(['firstLineIndent', num(-ind.hanging / TWIPS_PER_POINT)]);
+            else if (ind.firstLine !== undefined)
+                out.push(['firstLineIndent', num(ind.firstLine / TWIPS_PER_POINT)]);
+        }
+        const spacing = pPr.spacing;
+        if (spacing) {
+            if (!within(spacing, SPACING_KEYS))
+                throw new Unexpressible(`w:spacing (${keysOf(spacing).filter((k) => !SPACING_KEYS.has(k)).join(', ')})`);
+            if (spacing.before !== undefined)
+                out.push(['spaceBefore', num(spacing.before / TWIPS_PER_POINT)]);
+            if (spacing.after !== undefined)
+                out.push(['spaceAfter', num(spacing.after / TWIPS_PER_POINT)]);
+            if (spacing.line !== undefined) {
+                // Paragraph.lineSpacing writes w:lineRule="exact", so only an exact rule round-trips.
+                if (spacing.lineRule !== 'exact')
+                    throw new Unexpressible(`w:spacing w:lineRule="${(_c = spacing.lineRule) !== null && _c !== void 0 ? _c : 'auto'}"`);
+                out.push(['lineSpacing', num(spacing.line / TWIPS_PER_POINT)]);
+            }
+        }
+        const outlineLvl = (_d = pPr.outlineLvl) === null || _d === void 0 ? void 0 : _d.val;
+        if (outlineLvl !== undefined)
+            out.push(['outlineLevel', num(outlineLvl + 1)]);
+        const numPr = pPr.numPr;
+        if (numPr) {
+            // A direct `w:numPr` is `attachToList(numId, ilvl)`, which names the `w:numId` as the
+            // style assignment above names the style id: both assume the target document defines it.
+            // `startNewList()` is not emitted - it is asynchronous and would need the numbering part
+            // to know whether the list is a bullet one (CR-002 section 17).
+            if (!within(numPr, NUMPR_KEYS))
+                throw new Unexpressible(`w:numPr (${keysOf(numPr).filter((k) => !NUMPR_KEYS.has(k)).join(', ')})`);
+            const numId = (_e = numPr.numId) === null || _e === void 0 ? void 0 : _e.val;
+            if (numId === undefined)
+                throw new Unexpressible('w:numPr with no w:numId');
+            out.push([CALL, numId === 0 ? 'detachFromList()' : `attachToList(${numId}, ${(_g = (_f = numPr.ilvl) === null || _f === void 0 ? void 0 : _f.val) !== null && _g !== void 0 ? _g : 0})`]);
+        }
+        return out;
+    }
+    /** A table through `insertTable` when the grid is plain text; otherwise `insertXml`. */
+    async table(element) {
+        const grid = tableGrid(element.value);
+        const hasInsertTable = typeof Body.prototype.insertTable === 'function';
+        if (!grid || !hasInsertTable) {
+            await this.fallback(element, grid ? 'insertTable is CR-002 phase C' : 'the table is not a plain grid of text');
+            return;
+        }
+        const name = `t${++this.tables}`;
+        const values = `[${grid.values.map((row) => `[${row.map(quote).join(', ')}]`).join(', ')}]`;
+        this.line(`const ${name} = ${this.variable}.insertTable(${grid.rows}, ${grid.columns}, '${this.location}', ${values});`);
+        if (grid.style !== undefined) {
+            const [member, value] = styleAssignment(grid.style);
+            this.line(`${name}.${member} = ${value};`);
+        }
+    }
+    /** What no verb expresses: the marshalled fragment, which `insertXml` takes back. */
+    async fallback(element, reason) {
+        const xml = await marshalString(element);
+        if (reason !== undefined)
+            this.line(`// ${reason}: as XML`);
+        this.line(`await ${this.variable}.insertXml(${template(xml)}, '${this.location}');`);
+    }
+}
+function sameFormat(a, b) {
+    return Object.keys(a).every((k) => a[k] === b[k]);
+}
+/** The text and breaks of a paragraph's runs, in order; throws for anything a verb cannot write. */
+function piecesOf(p) {
+    var _a, _b, _c, _d, _e, _f;
+    const out = [];
+    for (const item of ((_a = p.content) !== null && _a !== void 0 ? _a : [])) {
+        const typeName = typeNameOf(item);
+        if (typeName !== undefined && IGNORED_TYPES.has(typeName))
+            continue;
+        if (typeName !== undefined && BOOKMARK_TYPES.has(typeName))
+            continue;
+        if (typeName !== 'org_docx4j_wml.R')
+            throw new Unexpressible(`${(_c = (_b = item.name) === null || _b === void 0 ? void 0 : _b.localPart) !== null && _c !== void 0 ? _c : 'content'} in the paragraph`);
+        const run = item.value;
+        if (run.rPr) {
+            if (!within(run.rPr, RPR_KEYS))
+                throw new Unexpressible(`run properties (${keysOf(run.rPr).filter((k) => !RPR_KEYS.has(k)).join(', ')})`);
+            if (run.rPr.rFonts && !within(run.rPr.rFonts, RFONTS_KEYS))
+                throw new Unexpressible('w:rFonts beyond ascii and hAnsi');
+        }
+        const format = readRunOptions(run.rPr);
+        for (const child of ((_d = run.content) !== null && _d !== void 0 ? _d : [])) {
+            const local = (_e = child.name) === null || _e === void 0 ? void 0 : _e.localPart;
+            if (local === 't') {
+                const text = String((_f = child.value.value) !== null && _f !== void 0 ? _f : '');
+                if (text !== '')
+                    out.push({ kind: 'text', text, breakType: 'Line', format });
+            }
+            else if (local === 'tab') {
+                // insertText writes a tab character, not a w:tab; the text model reads both as \t.
+                out.push({ kind: 'text', text: '\t', breakType: 'Line', format });
+            }
+            else if (local === 'br') {
+                const type = child.value.type;
+                if (type !== undefined && type !== 'page' && type !== 'textWrapping')
+                    throw new Unexpressible(`w:br type ${type}`);
+                out.push({ kind: 'break', text: '', breakType: type === 'page' ? 'Page' : 'Line', format });
+            }
+            else if (local === 'lastRenderedPageBreak') {
+                continue;
+            }
+            else {
+                throw new Unexpressible(`w:${local !== null && local !== void 0 ? local : '?'} in a run`);
+            }
+        }
+    }
+    return out;
+}
+/** `styleBuiltIn` with the `Word.Style` value for a built-in style id, else `style` with the display name. */
+function styleAssignment(styleId) {
+    const builtIn = builtInOf(styleId);
+    return builtIn === 'Other' ? ['style', quote(displayNameOf(styleId))] : ['styleBuiltIn', quote(builtIn)];
+}
+/** A table as `insertTable` would build it, or undefined when it is more than a grid of text. */
+function tableGrid(tbl) {
+    var _a, _b, _c, _d, _e;
+    const tblPr = tbl.tblPr;
+    if (tblPr && !within(tblPr, TBLPR_KEYS))
+        return undefined;
+    const values = [];
+    for (const item of ((_a = tbl.content) !== null && _a !== void 0 ? _a : [])) {
+        const typeName = typeNameOf(item);
+        if (typeName === 'org_docx4j_wml.CTTblGridCol' || typeName === 'org_docx4j_wml.TblGrid')
+            continue;
+        if (typeName !== 'org_docx4j_wml.Tr')
+            continue;
+        const row = [];
+        for (const cell of ((_b = item.value.content) !== null && _b !== void 0 ? _b : [])) {
+            if (typeNameOf(cell) !== 'org_docx4j_wml.Tc')
+                continue;
+            const tc = cell.value;
+            const blocks = ((_c = tc.content) !== null && _c !== void 0 ? _c : []).filter((b) => typeNameOf(b) !== 'org_docx4j_wml.TcPr');
+            if (blocks.length !== 1 || typeNameOf(blocks[0]) !== 'org_docx4j_wml.P')
+                return undefined;
+            const paragraph = blocks[0].value;
+            if (paragraph.pPr)
+                return undefined;
+            for (const run of ((_d = paragraph.content) !== null && _d !== void 0 ? _d : [])) {
+                if (typeNameOf(run) !== 'org_docx4j_wml.R')
+                    return undefined;
+                if (run.value.rPr)
+                    return undefined;
+            }
+            row.push(textOf(paragraph));
+        }
+        values.push(row);
+    }
+    if (values.length === 0)
+        return undefined;
+    const columns = values[0].length;
+    if (columns === 0 || values.some((r) => r.length !== columns))
+        return undefined;
+    const grid = { rows: values.length, columns, values };
+    const style = (_e = tblPr === null || tblPr === void 0 ? void 0 : tblPr.tblStyle) === null || _e === void 0 ? void 0 : _e.val;
+    if (style !== undefined)
+        grid.style = style;
+    return grid;
+}
+/**
+ * The content-API script that reproduces what it is given, as TypeScript against `body`: the verbs
+ * where they exist (`insertParagraph`, `style`, `alignment`, the indents and spacing, `insertText`
+ * with `Range.font` per run, `insertBreak`, `insertTable`), and `insertXml` with the marshalled
+ * fragment for the rest. Emitted for reveal codes, for teaching the API by example, and for an
+ * agent that wants the calls rather than the tree.
+ *
+ * The script is a sequence of statements over `body`; it uses `await` for the `insertXml` lines,
+ * so run it in an async function (`new Function('body', 'return (async () => {' + script + '})()')`).
+ */
+export async function toApiScript(target, options = {}) {
+    const emitter = new Emitter(options);
+    if (target instanceof Paragraph)
+        await emitter.paragraph(target.element);
+    else if (target instanceof Range)
+        await emitter.range(target);
+    else if (target instanceof Body) {
+        for (const element of target.content)
+            await emitter.element(element);
+    }
+    else if (Array.isArray(target)) {
+        for (const element of target)
+            await emitter.element(element);
+    }
+    else if (isElement(target)) {
+        await emitter.element(target);
+    }
+    else {
+        throw new Docx4JException('toApiScript takes a Body, a Paragraph, a Range, or w:p / w:tbl elements');
+    }
+    return emitter.script();
+}

package/dist/opc/ContentTypes.d.mts

@@ -28,6 +28,7 @@ export declare const ContentTypes: {
     readonly WORDPROCESSINGML_COMMENTS: "application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml";
     readonly WORDPROCESSINGML_COMMENTS_EXTENDED: "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml";
     readonly WORDPROCESSINGML_COMMENTS_IDS: "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml";
+    readonly WORDPROCESSINGML_COMMENTS_EXTENSIBLE: "application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml";
     readonly WORDPROCESSINGML_ENDNOTES: "application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml";
     readonly WORDPROCESSINGML_FONTTABLE: "application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml";
     readonly WORDPROCESSINGML_FOOTER: "application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml";
@@ -91,6 +92,16 @@ export declare const ContentTypes: {
     readonly SPREADSHEETML_COMMENTS: "application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml";
     readonly SPREADSHEETML_CONNECTIONS: "application/vnd.openxmlformats-officedocument.spreadsheetml.connections+xml";
     readonly SPREADSHEETML_EXTERNAL_LINK: "application/vnd.openxmlformats-officedocument.spreadsheetml.externalLink+xml";
+    readonly SPREADSHEETML_SLICER_CACHE: "application/vnd.ms-excel.slicerCache+xml";
+    readonly SPREADSHEETML_SLICERS: "application/vnd.ms-excel.slicer+xml";
+    readonly SPREADSHEETML_TIMELINE_CACHE: "application/vnd.ms-excel.timelineCache+xml";
+    readonly SPREADSHEETML_TIMELINES: "application/vnd.ms-excel.timeline+xml";
+    readonly SPREADSHEETML_CONTROL_PROPERTIES: "application/vnd.ms-excel.controlproperties+xml";
+    readonly SPREADSHEETML_CUSTOM_DATA_PROPERTIES: "application/vnd.openxmlformats-officedocument.customDataProperties+xml";
+    /** Generic, so `CustomDataPart` is registered by relationship type instead. */
+    readonly SPREADSHEETML_CUSTOM_DATA: "application/binary";
+    readonly SPREADSHEETML_SURVEY: "application/vnd.ms-excel.Survey+xml";
+    readonly SPREADSHEETML_DATA_MODEL: "application/vnd.openxmlformats-officedocument.model+data";
     readonly DIGITAL_SIGNATURE_ORIGIN_PART: "application/vnd.openxmlformats-package.digital-signature-origin";
     readonly DIGITAL_SIGNATURE_XML_SIGNATURE_PART: "application/vnd.openxmlformats-package.digital-signature-xmlsignature+xml";
     readonly INK_ML: "application/inkml+xml";

package/dist/opc/ContentTypes.mjs

@@ -28,6 +28,7 @@ export const ContentTypes = {
     WORDPROCESSINGML_COMMENTS: 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml',
     WORDPROCESSINGML_COMMENTS_EXTENDED: 'application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtended+xml',
     WORDPROCESSINGML_COMMENTS_IDS: 'application/vnd.openxmlformats-officedocument.wordprocessingml.commentsIds+xml',
+    WORDPROCESSINGML_COMMENTS_EXTENSIBLE: 'application/vnd.openxmlformats-officedocument.wordprocessingml.commentsExtensible+xml',
     WORDPROCESSINGML_ENDNOTES: 'application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml',
     WORDPROCESSINGML_FONTTABLE: 'application/vnd.openxmlformats-officedocument.wordprocessingml.fontTable+xml',
     WORDPROCESSINGML_FOOTER: 'application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml',
@@ -91,6 +92,19 @@ export const ContentTypes = {
     SPREADSHEETML_COMMENTS: 'application/vnd.openxmlformats-officedocument.spreadsheetml.comments+xml',
     SPREADSHEETML_CONNECTIONS: 'application/vnd.openxmlformats-officedocument.spreadsheetml.connections+xml',
     SPREADSHEETML_EXTERNAL_LINK: 'application/vnd.openxmlformats-officedocument.spreadsheetml.externalLink+xml',
+    // The Excel 2010 and 2013 extension parts ([MS-XLSX] 2.1; docx4j 17.2.0 CR-022, CR-004 here).
+    // The strings are Excel 365's as docx4j measured them: the timeline pair is lowercase, and
+    // the survey's capital S is Excel's too.
+    SPREADSHEETML_SLICER_CACHE: 'application/vnd.ms-excel.slicerCache+xml',
+    SPREADSHEETML_SLICERS: 'application/vnd.ms-excel.slicer+xml',
+    SPREADSHEETML_TIMELINE_CACHE: 'application/vnd.ms-excel.timelineCache+xml',
+    SPREADSHEETML_TIMELINES: 'application/vnd.ms-excel.timeline+xml',
+    SPREADSHEETML_CONTROL_PROPERTIES: 'application/vnd.ms-excel.controlproperties+xml',
+    SPREADSHEETML_CUSTOM_DATA_PROPERTIES: 'application/vnd.openxmlformats-officedocument.customDataProperties+xml',
+    /** Generic, so `CustomDataPart` is registered by relationship type instead. */
+    SPREADSHEETML_CUSTOM_DATA: 'application/binary',
+    SPREADSHEETML_SURVEY: 'application/vnd.ms-excel.Survey+xml',
+    SPREADSHEETML_DATA_MODEL: 'application/vnd.openxmlformats-officedocument.model+data',
     DIGITAL_SIGNATURE_ORIGIN_PART: 'application/vnd.openxmlformats-package.digital-signature-origin',
     DIGITAL_SIGNATURE_XML_SIGNATURE_PART: 'application/vnd.openxmlformats-package.digital-signature-xmlsignature+xml',
     INK_ML: 'application/inkml+xml',

package/dist/opc/DirectoryPartStore.d.mts

@@ -0,0 +1,47 @@
+import type { PartStore, PartSink, PutOptions } from './PartStore.mjs';
+/**
+ * A package spread over a directory: `word/document.xml` is the file `<dir>/word/document.xml`,
+ * `[Content_Types].xml` is read from the directory like any other entry, and a part's size comes
+ * from the file rather than from a central directory.
+ *
+ * ```ts
+ * const pkg = await WordprocessingMLPackage.load(await DirectoryPartStore.open('unzipped'));
+ * ```
+ *
+ * The directory is scanned once (`open`), because a `PartStore` lists its names synchronously.
+ * A part that is never touched is copied from here to the sink byte for byte, as from a zip, so
+ * zip to directory to zip reproduces every part.
+ */
+export declare class DirectoryPartStore implements PartStore {
+    readonly dir: string;
+    /** Store name (no leading '/') to [absolute file path, size]. */
+    private readonly entries;
+    private constructor();
+    /** Scans a directory and returns a store over it. */
+    static open(dir: string): Promise<DirectoryPartStore>;
+    private scan;
+    partNames(): Iterable<string>;
+    has(partName: string): boolean;
+    load(partName: string): Promise<Uint8Array>;
+    size(partName: string): number | undefined;
+}
+/**
+ * Writes a package to a directory (docx4j `UnzippedPartStore`'s save half): one file per part,
+ * directories created as needed, `[Content_Types].xml` first. `finish()` resolves to the
+ * directory path.
+ *
+ * ```ts
+ * await pkg.saveTo(new DirectoryPartSink('unzipped'));
+ * ```
+ *
+ * Nothing already in the directory is removed: a part the package no longer has stays on disk.
+ */
+export declare class DirectoryPartSink implements PartSink<string> {
+    readonly dir: string;
+    /** Insertion-ordered, so `[Content_Types].xml` (which `savePackage` puts first) is written first. */
+    private readonly pending;
+    constructor(dir: string);
+    put(partName: string, bytes: Uint8Array, _options?: PutOptions): void;
+    finish(): Promise<string>;
+    private write;
+}

package/dist/opc/DirectoryPartStore.mjs

@@ -0,0 +1,123 @@
+// An unzipped package on the file system (docx4j io3.stores.UnzippedPartStore). Node only: it is
+// the one module here that imports `node:` builtins, and it is exported from the `./node` subpath
+// only, never from `.` or `./opc`, so a browser or add-in bundle never sees them.
+import { readFile, readdir, stat, mkdir, writeFile } from 'node:fs/promises';
+import { join, dirname, sep } from 'node:path';
+import { CONTENT_TYPES_NAME } from './PartName.mjs';
+import { Docx4JException } from './exceptions.mjs';
+/**
+ * A package spread over a directory: `word/document.xml` is the file `<dir>/word/document.xml`,
+ * `[Content_Types].xml` is read from the directory like any other entry, and a part's size comes
+ * from the file rather than from a central directory.
+ *
+ * ```ts
+ * const pkg = await WordprocessingMLPackage.load(await DirectoryPartStore.open('unzipped'));
+ * ```
+ *
+ * The directory is scanned once (`open`), because a `PartStore` lists its names synchronously.
+ * A part that is never touched is copied from here to the sink byte for byte, as from a zip, so
+ * zip to directory to zip reproduces every part.
+ */
+export class DirectoryPartStore {
+    constructor(dir) {
+        this.dir = dir;
+        /** Store name (no leading '/') to [absolute file path, size]. */
+        this.entries = new Map();
+    }
+    /** Scans a directory and returns a store over it. */
+    static async open(dir) {
+        const store = new DirectoryPartStore(dir);
+        await store.scan('');
+        return store;
+    }
+    async scan(relative) {
+        const here = relative === '' ? this.dir : join(this.dir, relative);
+        let listing;
+        try {
+            listing = await readdir(here, { withFileTypes: true });
+        }
+        catch (e) {
+            throw new Docx4JException(`Cannot read package directory ${here}`, { cause: e });
+        }
+        // Names in a stable order, with [Content_Types].xml first as a zip written by Word has it.
+        const names = listing.map((entry) => entry.name).sort(compareNames);
+        for (const name of names) {
+            const childRelative = relative === '' ? name : `${relative}/${name}`;
+            const childPath = join(this.dir, childRelative);
+            const info = await stat(childPath);
+            if (info.isDirectory())
+                await this.scan(childRelative);
+            else if (info.isFile())
+                this.entries.set(childRelative, [childPath, info.size]);
+        }
+    }
+    partNames() {
+        return this.entries.keys();
+    }
+    has(partName) {
+        return this.entries.has(normalize(partName));
+    }
+    async load(partName) {
+        const entry = this.entries.get(normalize(partName));
+        if (!entry)
+            throw new Docx4JException(`No part ${partName} in ${this.dir}`);
+        return new Uint8Array(await readFile(entry[0]));
+    }
+    size(partName) {
+        var _a;
+        return (_a = this.entries.get(normalize(partName))) === null || _a === void 0 ? void 0 : _a[1];
+    }
+}
+/**
+ * Writes a package to a directory (docx4j `UnzippedPartStore`'s save half): one file per part,
+ * directories created as needed, `[Content_Types].xml` first. `finish()` resolves to the
+ * directory path.
+ *
+ * ```ts
+ * await pkg.saveTo(new DirectoryPartSink('unzipped'));
+ * ```
+ *
+ * Nothing already in the directory is removed: a part the package no longer has stays on disk.
+ */
+export class DirectoryPartSink {
+    constructor(dir) {
+        this.dir = dir;
+        /** Insertion-ordered, so `[Content_Types].xml` (which `savePackage` puts first) is written first. */
+        this.pending = new Map();
+    }
+    put(partName, bytes, _options) {
+        this.pending.set(normalize(partName), bytes);
+    }
+    async finish() {
+        const first = this.pending.get(CONTENT_TYPES_NAME);
+        if (first !== undefined) {
+            // written first even if a caller put it later
+            this.pending.delete(CONTENT_TYPES_NAME);
+            await this.write(CONTENT_TYPES_NAME, first);
+        }
+        for (const [name, bytes] of this.pending)
+            await this.write(name, bytes);
+        this.pending.clear();
+        return this.dir;
+    }
+    async write(partName, bytes) {
+        const path = join(this.dir, partName);
+        // A part name that climbs out of the directory (docx4j's "Zip Slip" check).
+        if (path !== this.dir && !path.startsWith(this.dir.endsWith(sep) ? this.dir : this.dir + sep)) {
+            throw new Docx4JException(`Part ${partName} is outside the target directory`);
+        }
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(path, bytes);
+    }
+}
+function normalize(name) {
+    return name.startsWith('/') ? name.substring(1) : name;
+}
+/** `[Content_Types].xml` first, then by name; the order the entries are listed in. */
+function compareNames(a, b) {
+    if (a === CONTENT_TYPES_NAME)
+        return -1;
+    if (b === CONTENT_TYPES_NAME)
+        return 1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}