web-doc 0.6.2 → 0.7.0

package/dist/edit/docx/text.js

@@ -0,0 +1,263 @@
+var _a;
+import { W_NS } from "./ids.js";
+/*
+ * The text model of a paragraph: `w:t` text, a tab, a line break (`\v`), a
+ * page or column break (`\f`), an inline picture or an embedded object as
+ * one object character, a field (`w:fldSimple`, or a complex field from
+ * `fldChar begin` to `end`) as its cached result text, hyperlinks and
+ * inline `w:sdt` as their runs, hidden runs as text, deleted text (`w:del`)
+ * left out. Offsets are UTF-16 code units of the paragraph's text. Every
+ * item remembers the XML it came from, so a later patch can keep the bytes
+ * of what an edit does not touch.
+ */
+export const TAB = "\t";
+export const LINE_BREAK = "\u000b";
+export const PAGE_BREAK = "\f";
+/** The object replacement character: an inline picture or an embedded object. */
+export const OBJECT = "";
+/** Wrappers whose children are read as the paragraph's own runs. */
+const TRANSPARENT = new Set([
+    "hyperlink",
+    "smartTag",
+    "customXml",
+    "dir",
+    "bdo",
+    "ins",
+    "moveTo",
+    "sdtContent",
+    "fldSimple",
+]);
+/** Wrappers whose content is deleted text: left out, the paragraph is tracked. */
+const DELETED = new Set(["del", "moveFrom"]);
+class Reader {
+    part;
+    items = [];
+    text = "";
+    tracked = false;
+    #field;
+    constructor(part) {
+        this.part = part;
+    }
+    paragraph(paragraph) {
+        for (const child of paragraph.children)
+            this.#child(child, undefined);
+        if (this.#field)
+            this.#closeField();
+    }
+    #child(node, wrapper) {
+        if (node.namespace !== W_NS) {
+            // DrawingML, math and markup compatibility live outside w:; a math
+            // zone or an alternate-content block counts as one object.
+            if (node.local === "oMath" ||
+                node.local === "oMathPara" ||
+                node.local === "AlternateContent")
+                this.#push("object", OBJECT, node, node, wrapper);
+            return;
+        }
+        switch (node.local) {
+            case "r":
+                this.#run(node, wrapper);
+                return;
+            case "sdt": {
+                const content = node.children.find((child) => child.local === "sdtContent" && child.namespace === W_NS);
+                if (content)
+                    for (const child of content.children)
+                        this.#child(child, node);
+                return;
+            }
+            case "ins":
+            case "moveTo":
+                this.#tracked();
+                for (const child of node.children)
+                    this.#child(child, node);
+                return;
+            default:
+                break;
+        }
+        if (DELETED.has(node.local)) {
+            this.#tracked();
+            return;
+        }
+        if (TRANSPARENT.has(node.local)) {
+            if (node.local === "fldSimple") {
+                this.#simpleField(node, wrapper);
+                return;
+            }
+            for (const child of node.children)
+                this.#child(child, node);
+        }
+    }
+    #tracked() {
+        this.tracked = true;
+    }
+    /** A simple field: one item carrying the text of its result runs. */
+    #simpleField(node, wrapper) {
+        const inner = new _a(this.part);
+        for (const child of node.children)
+            inner.#child(child, node);
+        this.tracked ||= inner.tracked;
+        this.#push("field", inner.text, node, node, wrapper);
+    }
+    #run(run, wrapper) {
+        const rPr = run.children.find((child) => child.local === "rPr" && child.namespace === W_NS);
+        if (rPr) {
+            const marked = rPr.children.some((child) => child.namespace === W_NS &&
+                (child.local === "ins" || child.local === "del"));
+            if (marked)
+                this.#tracked();
+        }
+        if (this.#field)
+            this.#field.runs.push(run);
+        for (const child of run.children) {
+            if (child.namespace !== W_NS) {
+                if (child.local === "AlternateContent")
+                    this.#emit("object", OBJECT, run, child, rPr, wrapper);
+                continue;
+            }
+            switch (child.local) {
+                case "rPr":
+                case "lastRenderedPageBreak":
+                case "instrText":
+                case "delInstrText":
+                case "delText":
+                    break;
+                case "fldChar":
+                    this.#fieldChar(child, run);
+                    break;
+                case "t":
+                    this.#emit("text", this.part.textOf(child), run, child, rPr, wrapper);
+                    break;
+                case "tab":
+                case "ptab":
+                    this.#emit("tab", TAB, run, child, rPr, wrapper);
+                    break;
+                case "br": {
+                    const type = this.part.attribute(child, "w:type");
+                    if (type === "page" || type === "column")
+                        this.#emit("pageBreak", PAGE_BREAK, run, child, rPr, wrapper);
+                    else
+                        this.#emit("break", LINE_BREAK, run, child, rPr, wrapper);
+                    break;
+                }
+                case "cr":
+                    this.#emit("break", LINE_BREAK, run, child, rPr, wrapper);
+                    break;
+                case "sym": {
+                    const code = Number.parseInt(this.part.attribute(child, "w:char") ?? "", 16);
+                    this.#emit("text", Number.isFinite(code) && code > 0 && code <= 0x10ffff
+                        ? String.fromCodePoint(code)
+                        : "", run, child, rPr, wrapper);
+                    break;
+                }
+                case "noBreakHyphen":
+                    this.#emit("text", "‑", run, child, rPr, wrapper);
+                    break;
+                case "softHyphen":
+                    this.#emit("text", "­", run, child, rPr, wrapper);
+                    break;
+                case "drawing": {
+                    const inline = child.children.some((node) => node.local === "inline");
+                    if (inline)
+                        this.#emit("picture", OBJECT, run, child, rPr, wrapper);
+                    else
+                        this.#emit("anchor", "", run, child, rPr, wrapper);
+                    break;
+                }
+                case "object":
+                case "pict":
+                    this.#emit("object", OBJECT, run, child, rPr, wrapper);
+                    break;
+                case "footnoteReference":
+                case "endnoteReference":
+                    this.#emit("note", "", run, child, rPr, wrapper);
+                    break;
+                case "ruby": {
+                    const base = child.children.find((node) => node.local === "rubyBase");
+                    if (base)
+                        for (const node of base.children)
+                            this.#child(node, wrapper);
+                    break;
+                }
+                default:
+                    break;
+            }
+        }
+    }
+    #fieldChar(node, run) {
+        const type = this.part.attribute(node, "w:fldCharType");
+        if (type === "begin") {
+            if (this.#field)
+                this.#field.inResult.push(false);
+            else
+                this.#field = { begin: run, runs: [run], text: "", inResult: [false] };
+            return;
+        }
+        if (!this.#field)
+            return;
+        const levels = this.#field.inResult;
+        if (type === "separate") {
+            levels[levels.length - 1] = true;
+            return;
+        }
+        if (type === "end") {
+            if (levels.length > 1)
+                levels.pop();
+            else
+                this.#closeField();
+        }
+    }
+    #closeField() {
+        const field = this.#field;
+        this.#field = undefined;
+        const rPr = field.begin.children.find((child) => child.local === "rPr" && child.namespace === W_NS);
+        this.#append({
+            kind: "field",
+            start: this.text.length,
+            end: this.text.length + field.text.length,
+            text: field.text,
+            run: field.begin,
+            child: field.begin,
+            ...(rPr ? { rPr } : {}),
+            fieldRuns: field.runs,
+        });
+    }
+    /** Text inside an open field goes to its result; outside it is an item. */
+    #emit(kind, text, run, child, rPr, wrapper) {
+        const field = this.#field;
+        if (field) {
+            // What Word shows: the result of the outer field, which holds the
+            // results of the fields nested in it and none of their instructions.
+            if (field.inResult.every(Boolean))
+                field.text += text;
+            return;
+        }
+        this.#push(kind, text, run, child, wrapper, rPr);
+    }
+    #push(kind, text, run, child, wrapper, rPr) {
+        this.#append({
+            kind,
+            start: this.text.length,
+            end: this.text.length + text.length,
+            text,
+            run,
+            child,
+            ...(rPr ? { rPr } : {}),
+            ...(wrapper ? { wrapper } : {}),
+        });
+    }
+    #append(item) {
+        this.items.push(item);
+        this.text += item.text;
+    }
+}
+_a = Reader;
+/** Reads the text of a `w:p`. */
+export function readParagraphText(part, paragraph) {
+    const reader = new Reader(part);
+    reader.paragraph(paragraph);
+    return { text: reader.text, items: reader.items, tracked: reader.tracked };
+}
+/** The first item that draws text, for the resolved style of a paragraph. */
+export function firstTextItem(model) {
+    return model.items.find((item) => (item.kind === "text" || item.kind === "field") && item.text.length > 0);
+}

package/dist/edit/docx/types.d.ts

@@ -0,0 +1,191 @@
+import type { ApplyOptions, BinaryData, EditColor, EditElement, EditReceipt, EditSessionBase, SavedDocument, SaveOptions, TextRange } from "../types.js";
+export type DocxElementKind = "paragraph" | "table" | "image" | "other";
+export type DocxTextAlign = "left" | "center" | "right" | "justify";
+/** Word's sixteen highlight colours (`w:highlight/@w:val`). */
+export type DocxHighlight = "yellow" | "green" | "cyan" | "magenta" | "blue" | "red" | "darkBlue" | "darkCyan" | "darkGreen" | "darkMagenta" | "darkRed" | "darkYellow" | "darkGray" | "lightGray" | "black" | "white";
+/** The style of a paragraph's first run with text, resolved through the style chain and the theme. */
+export interface DocxTextStyle {
+    /** Theme fonts resolved ("minorHAnsi" becomes the minor Latin face). */
+    readonly fontFamily: string;
+    /** Points. */
+    readonly fontSize: number;
+    readonly bold: boolean;
+    readonly italic: boolean;
+    readonly underline: boolean;
+    /** `#RRGGBB`, `{ theme }` for a theme colour, "auto" for Word's automatic colour. */
+    readonly color: EditColor;
+    readonly highlight?: DocxHighlight;
+}
+export interface DocxParagraphSpacing {
+    /** Points before the paragraph; absent when inherited. */
+    readonly before?: number;
+    /** Points after the paragraph; absent when inherited. */
+    readonly after?: number;
+    /**
+     * Line spacing: points for `exact` and `atLeast`, a multiple of single
+     * spacing (1 = single, 1.5, 2) for `auto`; absent when inherited.
+     */
+    readonly line?: number;
+    readonly lineRule?: "auto" | "exact" | "atLeast";
+}
+export interface DocxParagraphStyle {
+    /** `w:pStyle`, when the paragraph names a style. */
+    readonly styleId?: string;
+    readonly align: DocxTextAlign;
+    readonly spacing: DocxParagraphSpacing;
+    /** `w:numPr`: the paragraph belongs to a list. */
+    readonly numbering?: {
+        readonly numId: number;
+        readonly level: number;
+    };
+}
+/** Why a paragraph's text cannot be edited in place. */
+export type DocxReadOnlyReason = "tracked-changes" | "section-break" | "unsupported-content";
+/**
+ * An element of the body story. Geometry comes from the renderer: `bounds`
+ * and `fragments` are the unions of the element's text runs per page, so
+ * an element whose pages the viewer has not laid out yet, or which draws
+ * no run (an empty paragraph), has `pageIndex` −1, empty `bounds` and an
+ * empty `fragments` list until a query names its page.
+ */
+export interface DocxElement extends EditElement {
+    readonly kind: DocxElementKind;
+    /** Present for a paragraph: resolved style of its first run with text. */
+    readonly textStyle?: DocxTextStyle;
+    /** Present for a paragraph. */
+    readonly paragraphStyle?: DocxParagraphStyle;
+    /** Present for a table: cell text by row. */
+    readonly table?: {
+        readonly rows: readonly (readonly string[])[];
+    };
+    /** Present for a paragraph whose text cannot be edited in place. */
+    readonly readOnlyReason?: DocxReadOnlyReason;
+    /** Present for an inline picture: its declared extent in page space (CSS pixels). */
+    readonly imageSize?: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+export interface DocxTextStyleChange {
+    /** `w:rFonts` ascii and hAnsi faces. */
+    readonly fontFamily?: string;
+    /** 1–400 points. */
+    readonly fontSize?: number;
+    readonly bold?: boolean;
+    readonly italic?: boolean;
+    /** `w:u` single or none. */
+    readonly underline?: boolean;
+    /** `#RRGGBB` writes `w:color`; `{ theme }` writes the theme colour and its resolved value. */
+    readonly color?: EditColor;
+    /** `w:highlight`; "none" removes it. */
+    readonly highlight?: DocxHighlight | "none";
+}
+export interface DocxParagraphStyleChange {
+    readonly align?: DocxTextAlign;
+    /** Points; a field absent keeps its bytes. */
+    readonly spacing?: {
+        readonly before?: number;
+        readonly after?: number;
+        /** A multiple of single spacing, written with `w:lineRule="auto"`. */
+        readonly line?: number;
+    };
+}
+export interface DocxReplaceTextOperation {
+    readonly op: "replaceText";
+    /** A `paragraph` element. */
+    readonly target: string;
+    readonly text: string;
+    /** Both ends on the target; absent, the whole text; collapsed, an insertion. */
+    readonly range?: TextRange;
+}
+export interface DocxSetTextStyleOperation {
+    readonly op: "setTextStyle";
+    readonly target: string;
+    readonly range?: TextRange;
+    readonly style: DocxTextStyleChange;
+}
+export interface DocxSetParagraphStyleOperation {
+    readonly op: "setParagraphStyle";
+    readonly target: string;
+    readonly style: DocxParagraphStyleChange;
+}
+export interface DocxInsertParagraphOperation {
+    readonly op: "insertParagraph";
+    /** Exactly one of `before` and `after`: a paragraph or table id. */
+    readonly before?: string;
+    readonly after?: string;
+    readonly text: string;
+    readonly style?: DocxTextStyleChange;
+}
+export interface DocxDeleteElementOperation {
+    readonly op: "deleteElement";
+    /** A paragraph, a table or an inline picture. */
+    readonly target: string;
+}
+export interface DocxMoveElementOperation {
+    readonly op: "moveElement";
+    /** A paragraph or a table. */
+    readonly target: string;
+    /** Exactly one of `before` and `after`: a paragraph or table id of the same container. */
+    readonly before?: string;
+    readonly after?: string;
+}
+export interface DocxInsertTableOperation {
+    readonly op: "insertTable";
+    readonly before?: string;
+    readonly after?: string;
+    /** Cell text by row; every row has the same number of cells. 1–100 rows, 1–20 columns. */
+    readonly rows: readonly (readonly string[])[];
+    /** Relative column weights, one per column; equal when omitted. */
+    readonly columnWidths?: readonly number[];
+}
+export interface DocxSetTableCellOperation {
+    readonly op: "setTableCell";
+    /** A `table` element. */
+    readonly target: string;
+    readonly row: number;
+    readonly column: number;
+    /** The cell's new text; empty clears the cell. */
+    readonly text: string;
+}
+export interface DocxInsertImageOperation {
+    readonly op: "insertImage";
+    readonly before?: string;
+    readonly after?: string;
+    /** PNG or JPEG bytes; base64 over pure-JSON transports. */
+    readonly data: BinaryData;
+    readonly mimeType: "image/png" | "image/jpeg";
+    /** Points. */
+    readonly size: {
+        readonly width: number;
+        readonly height: number;
+    };
+}
+/** The DOCX operation union; operations are added as they ship. */
+export type DocxOperation = DocxReplaceTextOperation | DocxSetTextStyleOperation | DocxSetParagraphStyleOperation | DocxInsertParagraphOperation | DocxDeleteElementOperation | DocxMoveElementOperation | DocxInsertTableOperation | DocxSetTableCellOperation | DocxInsertImageOperation;
+/** DOCX saves have no fields of their own. */
+export type DocxSaveOptions = SaveOptions;
+/** An operation's fields without its `op`, as the typed methods take them. */
+export type DocxFields<T extends DocxOperation> = T extends unknown ? Omit<T, "op"> : never;
+export interface DocxEditSession extends EditSessionBase<DocxOperation, DocxElement> {
+    readonly format: "docx";
+    save(options?: DocxSaveOptions): Promise<SavedDocument>;
+    /** Replaces the whole text of a paragraph, or the part a range covers. */
+    replaceText(fields: DocxFields<DocxReplaceTextOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Changes run properties; unspecified ones keep their bytes. */
+    setTextStyle(fields: DocxFields<DocxSetTextStyleOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Changes alignment and spacing of a paragraph. */
+    setParagraphStyle(fields: DocxFields<DocxSetParagraphStyleOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Adds a paragraph next to another element; its id is in `createdIds`. */
+    insertParagraph(fields: DocxFields<DocxInsertParagraphOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Removes a paragraph, a table or an inline picture. */
+    deleteElement(fields: DocxFields<DocxDeleteElementOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Moves a paragraph or a table next to another element of the same container. */
+    moveElement(fields: DocxFields<DocxMoveElementOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Adds a table with the given cell text. */
+    insertTable(fields: DocxFields<DocxInsertTableOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Changes one cell's text. */
+    setTableCell(fields: DocxFields<DocxSetTableCellOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+    /** Adds a paragraph holding an inline PNG or JPEG. */
+    insertImage(fields: DocxFields<DocxInsertImageOperation>, options?: ApplyOptions): Promise<EditReceipt>;
+}

package/dist/edit/docx/types.js

@@ -0,0 +1 @@
+export {};

package/dist/edit/docx/write.d.ts

@@ -0,0 +1,50 @@
+import { type XmlPatch } from "../ooxml/patch.js";
+import { type XmlElement, type XmlPart } from "../ooxml/xml.js";
+import type { EditColor } from "../types.js";
+import { type DocxStyles } from "./style.js";
+import type { DocxParagraphStyleChange, DocxTextStyleChange } from "./types.js";
+/** Why a text cannot be written, or undefined when it can. */
+export declare function textProblem(text: string): string | undefined;
+/** Why a value cannot be written as an attribute: text problems plus the breaks text may hold. */
+export declare function attributeProblem(value: string): string | undefined;
+export declare function colorProblem(color: unknown): string | undefined;
+/** Text as the engine stores it: Windows and classic Mac line ends become "\n". */
+export declare function normalizeText(text: string): string;
+export declare function sliceOf(part: XmlPart, node: XmlElement | undefined): string;
+export declare function escapeAttributeValue(value: string): string;
+/** The content elements of a run for `text`: `w:t`, `w:tab`, `w:br`. */
+export declare function runContentXml(text: string): string;
+/** A run with `rPr` bytes (or "") and the given content; nothing for empty content. */
+export declare function runXml(rPr: string, content: string): string;
+/**
+ * Properties with changes merged in schema order: every child of `source`
+ * keeps its bytes unless `set` names its local name, in which case the
+ * replacement (or nothing, for `null`) takes its place; new children go
+ * where the schema puts them. Returns "" for no properties at all.
+ */
+export declare function mergedProperties(part: XmlPart, source: XmlElement | undefined, tag: "w:rPr" | "w:pPr", order: readonly string[], set: ReadonlyMap<string, string | null>): string;
+/** `w:rPr` bytes with a text style change applied. */
+export declare function changedRunProperties(part: XmlPart, rPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles): string;
+/** `w:color` for a colour: RGB, automatic, or a theme name with the theme's value. */
+export declare function colorXml(color: EditColor, styles: DocxStyles): string;
+/** `w:pPr` bytes with alignment and spacing changed, other children kept. */
+export declare function changedParagraphProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxParagraphStyleChange): string;
+export declare function alignValue(align: NonNullable<DocxParagraphStyleChange["align"]>): string;
+/** `w:pPr` bytes with the paragraph mark's `w:rPr` changed (created when absent). */
+export declare function paragraphMarkProperties(part: XmlPart, pPr: XmlElement | undefined, change: DocxTextStyleChange, styles: DocxStyles): string;
+/** `w:pPr` bytes without the section properties, for a paragraph copied next to one that ends a section. */
+export declare function paragraphPropertiesWithoutSection(part: XmlPart, pPr: XmlElement | undefined): string;
+/**
+ * The start tag of a `w:p` with its id written: the paragraph's own
+ * attributes, `w14:paraId` and `w14:textId` replaced.
+ */
+export declare function paragraphStartTag(source: XmlElement | undefined, id: string): string;
+/** A whole paragraph from its start tag, property bytes and content. */
+export declare function paragraphXml(source: XmlElement | undefined, id: string, pPr: string, content: string): string;
+/**
+ * Patches that declare the `w14` namespace on the document root and list
+ * it as ignorable, when the root does not yet; nothing when it does.
+ */
+export declare function namespacePatches(part: XmlPart): XmlPatch[];
+/** Whether the paragraph already carries a `w14:paraId`. */
+export declare function isAuthored(part: XmlPart, paragraph: XmlElement): boolean;