web-doc 0.6.2 → 0.7.0

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

@@ -0,0 +1,92 @@
+import type { OoxmlPackage } from "../ooxml/package.js";
+import type { XmlElement, XmlPart } from "../ooxml/xml.js";
+import { DocxStyles } from "./style.js";
+import { type ParagraphText } from "./text.js";
+import type { DocxReadOnlyReason } from "./types.js";
+export interface ParagraphRecord {
+    readonly kind: "paragraph";
+    /** Eight upper-case hex digits: the `w14:paraId` or the generated id. */
+    readonly id: string;
+    /** "p:<id>". */
+    readonly elementId: string;
+    readonly node: XmlElement;
+    readonly pPr?: XmlElement;
+    /** `w:pPr/w:sectPr`: the paragraph ends a section. */
+    readonly sectPr?: XmlElement;
+    readonly text: ParagraphText;
+    /** The table whose cell holds the paragraph, when any. */
+    readonly table?: TableRecord;
+    /** The block-level wrapper (`w:sdt`, `w:customXml`) the paragraph sits in, when any. */
+    readonly wrapper?: XmlElement;
+    readonly readOnlyReason?: DocxReadOnlyReason;
+    /** Inline pictures and other objects of the paragraph, in order. */
+    readonly inlines: readonly InlineRecord[];
+}
+export interface CellRecord {
+    readonly node: XmlElement;
+    readonly paragraphs: readonly ParagraphRecord[];
+}
+export interface TableRecord {
+    readonly kind: "table";
+    /** The id of the table's first paragraph. */
+    readonly id: string;
+    /** "tbl:<id>". */
+    readonly elementId: string;
+    readonly node: XmlElement;
+    readonly rows: readonly (readonly CellRecord[])[];
+    readonly wrapper?: XmlElement;
+}
+export interface InlineRecord {
+    readonly kind: "image" | "other";
+    /** "img:<paragraph id>.<n>" or "other:<paragraph id>.<n>". */
+    readonly elementId: string;
+    readonly paragraph: ParagraphRecord;
+    /** The `w:drawing`, `w:object`, `w:pict`, math or alternate-content node. */
+    readonly node: XmlElement;
+    /** The `w:r` holding the node, when it sits in a run. */
+    readonly run?: XmlElement;
+    /** For an inline picture: `wp:extent` in EMU. */
+    readonly extent?: {
+        readonly cx: number;
+        readonly cy: number;
+    };
+}
+export type BlockRecord = ParagraphRecord | TableRecord;
+export type AnyRecord = ParagraphRecord | TableRecord | InlineRecord;
+export declare class DocxModel {
+    #private;
+    readonly revision: number;
+    readonly mainPart: string;
+    readonly document: XmlPart;
+    readonly body: XmlElement;
+    /** The body's own `w:sectPr`, when present. */
+    readonly bodySectPr: XmlElement | undefined;
+    /** Top-level blocks of the body in order; cell paragraphs hang off their table. */
+    readonly blocks: readonly BlockRecord[];
+    /** Every listed record in document order: a table before its cell paragraphs, a paragraph before its inlines. */
+    readonly records: readonly AnyRecord[];
+    readonly byId: ReadonlyMap<string, AnyRecord>;
+    /** Id of every `w:p` of the main part, listed or not. */
+    readonly paragraphIds: ReadonlyMap<XmlElement, string>;
+    /** Ids the engine owns (never written by an edit), in document order. */
+    readonly unauthoredIds: readonly string[];
+    /** Every paragraph id the document uses, in any story part. */
+    readonly takenIds: ReadonlySet<string>;
+    readonly styles: DocxStyles;
+    private constructor();
+    /**
+     * Builds the index. `unauthored` carries the ids of the paragraphs that
+     * have no `w14:paraId`, in document order, as the engine tracks them
+     * between edits; without it the ids are computed from the bytes, as the
+     * display pre-pass computes them.
+     */
+    static load(pkg: OoxmlPackage, signal?: AbortSignal, unauthored?: readonly string[], cachedStyles?: DocxStyles): Promise<DocxModel>;
+    /** The unauthored ids as a set, for "is this paragraph's id written by an edit" checks. */
+    get unauthoredSet(): ReadonlySet<string>;
+    get paragraphs(): readonly ParagraphRecord[];
+}
+/** The text of a table: cells joined by tabs, rows by newlines. */
+export declare function tableText(table: TableRecord): string;
+export declare function cellText(cell: CellRecord): string;
+/** The paragraph a cell paragraph's table starts with, for `tbl:` ids. */
+export declare function tableRows(table: TableRecord): readonly (readonly string[])[];

package/dist/edit/docx/model.js

@@ -0,0 +1,339 @@
+import { ViewerError } from "../../errors.js";
+import { assignParagraphIds, collectIds, newIdState, OFFICE_RELATIONSHIPS, paragraphsOf, STORY_RELATIONSHIP_TYPES, W_NS, } from "./ids.js";
+import { DocxStyles } from "./style.js";
+import { readParagraphText } from "./text.js";
+export class DocxModel {
+    revision;
+    mainPart;
+    document;
+    body;
+    bodySectPr;
+    blocks;
+    records;
+    byId;
+    paragraphIds;
+    unauthoredIds;
+    takenIds;
+    styles;
+    constructor(revision, mainPart, document, body, 
+    /** The body's own `w:sectPr`, when present. */
+    bodySectPr, 
+    /** Top-level blocks of the body in order; cell paragraphs hang off their table. */
+    blocks, 
+    /** Every listed record in document order: a table before its cell paragraphs, a paragraph before its inlines. */
+    records, byId, 
+    /** Id of every `w:p` of the main part, listed or not. */
+    paragraphIds, 
+    /** Ids the engine owns (never written by an edit), in document order. */
+    unauthoredIds, 
+    /** Every paragraph id the document uses, in any story part. */
+    takenIds, styles) {
+        this.revision = revision;
+        this.mainPart = mainPart;
+        this.document = document;
+        this.body = body;
+        this.bodySectPr = bodySectPr;
+        this.blocks = blocks;
+        this.records = records;
+        this.byId = byId;
+        this.paragraphIds = paragraphIds;
+        this.unauthoredIds = unauthoredIds;
+        this.takenIds = takenIds;
+        this.styles = styles;
+    }
+    /**
+     * Builds the index. `unauthored` carries the ids of the paragraphs that
+     * have no `w14:paraId`, in document order, as the engine tracks them
+     * between edits; without it the ids are computed from the bytes, as the
+     * display pre-pass computes them.
+     */
+    static async load(pkg, signal, unauthored, cachedStyles) {
+        const root = await pkg.relationships("/", signal);
+        const main = root.byType(`${OFFICE_RELATIONSHIPS}officeDocument`)[0]
+            ?.targetPart;
+        if (!main || !pkg.has(main))
+            throw new ViewerError("invalid-file", "The package has no document part");
+        const document = await pkg.xml(main, signal);
+        const body = document.root.children.find((child) => child.local === "body" && child.namespace === W_NS);
+        if (!body)
+            throw new ViewerError("invalid-file", "The document part has no body");
+        // Ids are numbered across every story part, the main part first.
+        const relationships = await pkg.relationships(main, signal);
+        const state = newIdState();
+        collectIds(document, state);
+        for (const type of STORY_RELATIONSHIP_TYPES)
+            for (const item of relationships.byType(type))
+                if (item.targetPart && pkg.has(item.targetPart))
+                    collectIds(await pkg.xml(item.targetPart, signal), state);
+        const paragraphIds = new Map();
+        const unauthoredIds = [];
+        if (unauthored) {
+            // The engine's ids: a paragraph without `w14:paraId` takes the next
+            // one in order; a paragraph that carries one the engine stamped into
+            // a shown copy (restored as a base) keeps it and stays unauthored.
+            const owned = new Set(unauthored);
+            const paragraphs = paragraphsOf(document);
+            const attributed = new Set();
+            for (const paragraph of paragraphs) {
+                const id = document.attribute(paragraph, "w14:paraId");
+                if (id)
+                    attributed.add(id.toUpperCase());
+            }
+            const queue = unauthored.filter((id) => !attributed.has(id));
+            for (const paragraph of paragraphs) {
+                const authored = document.attribute(paragraph, "w14:paraId");
+                if (authored) {
+                    const id = authored.toUpperCase();
+                    paragraphIds.set(paragraph, id);
+                    if (owned.has(id))
+                        unauthoredIds.push(id);
+                    state.taken.add(id);
+                    continue;
+                }
+                const id = queue.shift();
+                if (id === undefined)
+                    throw new ViewerError("internal", "The document has more unmarked paragraphs than the session knows");
+                paragraphIds.set(paragraph, id);
+                unauthoredIds.push(id);
+                state.taken.add(id);
+            }
+            if (queue.length > 0)
+                throw new ViewerError("internal", "The session knows more unmarked paragraphs than the document has");
+        }
+        else
+            for (const entry of assignParagraphIds(document, state)) {
+                paragraphIds.set(entry.paragraph, entry.id);
+                if (!entry.authored)
+                    unauthoredIds.push(entry.id);
+            }
+        const styles = cachedStyles ?? (await DocxStyles.load(pkg, main, signal));
+        const builder = new Builder(document, paragraphIds);
+        let bodySectPr;
+        for (const child of body.children) {
+            if (child.namespace === W_NS && child.local === "sectPr") {
+                bodySectPr = child;
+                continue;
+            }
+            builder.block(child, undefined, undefined);
+        }
+        return new DocxModel(pkg.revision, main, document, body, bodySectPr, builder.blocks, builder.records, builder.byId, paragraphIds, unauthoredIds, state.taken, styles);
+    }
+    /** The unauthored ids as a set, for "is this paragraph's id written by an edit" checks. */
+    get unauthoredSet() {
+        return (this.#unauthoredSet ??= new Set(this.unauthoredIds));
+    }
+    #unauthoredSet;
+    get paragraphs() {
+        return this.records.filter((record) => record.kind === "paragraph");
+    }
+}
+class Builder {
+    part;
+    ids;
+    blocks = [];
+    records = [];
+    byId = new Map();
+    constructor(part, ids) {
+        this.part = part;
+        this.ids = ids;
+    }
+    /** A child of the body or of a cell; wrappers are unwrapped. */
+    block(node, table, wrapper, into) {
+        if (node.namespace !== W_NS)
+            return;
+        switch (node.local) {
+            case "p": {
+                const record = this.paragraph(node, table, wrapper);
+                if (into)
+                    into.push(record);
+                else
+                    this.blocks.push(record);
+                return;
+            }
+            case "tbl":
+                // A table inside a cell is left out: its structure is not edited here.
+                if (!table) {
+                    const record = this.table(node, wrapper);
+                    if (record)
+                        this.blocks.push(record);
+                }
+                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.block(child, table, node, into);
+                return;
+            }
+            case "customXml":
+                for (const child of node.children)
+                    this.block(child, table, node, into);
+                return;
+            default:
+                return;
+        }
+    }
+    paragraph(node, table, wrapper) {
+        const id = this.ids.get(node) ?? "00000000";
+        const pPr = node.children.find((child) => child.local === "pPr" && child.namespace === W_NS);
+        const sectPr = pPr?.children.find((child) => child.local === "sectPr" && child.namespace === W_NS);
+        const text = readParagraphText(this.part, node);
+        const fieldOnly = text.items.some((item) => item.kind === "field") &&
+            !text.items.some((item) => item.kind === "text" && item.text.length > 0);
+        const readOnlyReason = text.tracked
+            ? "tracked-changes"
+            : sectPr
+                ? "section-break"
+                : fieldOnly
+                    ? "unsupported-content"
+                    : undefined;
+        const inlines = [];
+        const record = {
+            kind: "paragraph",
+            id,
+            elementId: `p:${id}`,
+            node,
+            ...(pPr ? { pPr } : {}),
+            ...(sectPr ? { sectPr } : {}),
+            text,
+            ...(table ? { table } : {}),
+            ...(wrapper ? { wrapper } : {}),
+            ...(readOnlyReason ? { readOnlyReason } : {}),
+            inlines,
+        };
+        this.register(record);
+        let pictures = 0;
+        let others = 0;
+        for (const item of text.items) {
+            if (item.kind === "picture") {
+                const inline = item.child.children.find((child) => child.local === "inline");
+                const extentNode = inline?.children.find((child) => child.local === "extent");
+                const cx = Number(extentNode ? this.part.attribute(extentNode, "cx") : NaN);
+                const cy = Number(extentNode ? this.part.attribute(extentNode, "cy") : NaN);
+                const picture = {
+                    kind: "image",
+                    elementId: `img:${id}.${pictures}`,
+                    paragraph: record,
+                    node: item.child,
+                    run: item.run,
+                    ...(Number.isFinite(cx) && Number.isFinite(cy)
+                        ? { extent: { cx, cy } }
+                        : {}),
+                };
+                pictures += 1;
+                inlines.push(picture);
+                this.register(picture);
+            }
+            else if (item.kind === "anchor" || item.kind === "object") {
+                const other = {
+                    kind: "other",
+                    elementId: `other:${id}.${others}`,
+                    paragraph: record,
+                    node: item.child,
+                    ...(item.run === item.child ? {} : { run: item.run }),
+                };
+                others += 1;
+                inlines.push(other);
+                this.register(other);
+            }
+        }
+        return record;
+    }
+    table(node, wrapper) {
+        // The table is named after the first paragraph of its first cell, as
+        // listed: a nested table at the top of that cell does not count.
+        const firstCell = this.cellsOf(this.rowsOf(node)[0] ?? node)[0];
+        const first = firstCell ? this.firstParagraphOf(firstCell) : undefined;
+        const id = first ? this.ids.get(first) : undefined;
+        if (!id)
+            return undefined;
+        const rows = [];
+        const record = {
+            kind: "table",
+            id,
+            elementId: `tbl:${id}`,
+            node,
+            rows,
+            ...(wrapper ? { wrapper } : {}),
+        };
+        this.register(record);
+        for (const row of this.rowsOf(node))
+            rows.push(this.cellsOf(row).map((cell) => this.cell(cell, record)));
+        return record;
+    }
+    /** The first `w:p` child of a cell, through block-level wrappers. */
+    firstParagraphOf(cell) {
+        for (const child of cell.children) {
+            if (child.namespace !== W_NS)
+                continue;
+            if (child.local === "p")
+                return child;
+            if (child.local === "sdt" ||
+                child.local === "sdtContent" ||
+                child.local === "customXml") {
+                const nested = this.firstParagraphOf(child);
+                if (nested)
+                    return nested;
+            }
+        }
+        return undefined;
+    }
+    cell(node, table) {
+        const paragraphs = [];
+        for (const child of node.children)
+            this.block(child, table, undefined, paragraphs);
+        return { node, paragraphs };
+    }
+    /** `w:tr` children of a table, through row-level `w:sdt` wrappers. */
+    rowsOf(table) {
+        const out = [];
+        const walk = (node) => {
+            for (const child of node.children) {
+                if (child.namespace !== W_NS)
+                    continue;
+                if (child.local === "tr")
+                    out.push(child);
+                else if (child.local === "sdt" ||
+                    child.local === "sdtContent" ||
+                    child.local === "customXml")
+                    walk(child);
+            }
+        };
+        walk(table);
+        return out;
+    }
+    cellsOf(row) {
+        const out = [];
+        const walk = (node) => {
+            for (const child of node.children) {
+                if (child.namespace !== W_NS)
+                    continue;
+                if (child.local === "tc")
+                    out.push(child);
+                else if (child.local === "sdt" ||
+                    child.local === "sdtContent" ||
+                    child.local === "customXml")
+                    walk(child);
+            }
+        };
+        walk(row);
+        return out;
+    }
+    register(record) {
+        this.records.push(record);
+        this.byId.set(record.elementId, record);
+    }
+}
+/** The text of a table: cells joined by tabs, rows by newlines. */
+export function tableText(table) {
+    return table.rows
+        .map((row) => row.map((cell) => cellText(cell)).join("\t"))
+        .join("\n");
+}
+export function cellText(cell) {
+    return cell.paragraphs.map((paragraph) => paragraph.text.text).join("\n");
+}
+/** The paragraph a cell paragraph's table starts with, for `tbl:` ids. */
+export function tableRows(table) {
+    return table.rows.map((row) => row.map((cell) => cellText(cell)));
+}

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

@@ -0,0 +1,37 @@
+import type { ResourceLimits, ViewerWarning } from "../../contracts.js";
+import type { AssetSource } from "../assets.js";
+import type { OoxmlPackage } from "../ooxml/package.js";
+import type { OperationIssue } from "../types.js";
+import type { DocxModel } from "./model.js";
+import type { DocxOperation } from "./types.js";
+export interface DocxOperationContext {
+    readonly pkg: OoxmlPackage;
+    readonly model: DocxModel;
+    readonly limits: ResourceLimits;
+    /** Bytes behind `asset:` references. */
+    readonly assets: AssetSource;
+    /** The batch's state id, for ids an operation derives. */
+    readonly stateId: number;
+    readonly operationIndex: number;
+    /** A paragraph id no paragraph of the document or of this batch uses. */
+    freshParagraphId(): string;
+}
+export interface DocxOperationResult {
+    readonly createdIds: readonly string[];
+    readonly removedIds?: readonly string[];
+    readonly warnings: readonly ViewerWarning[];
+    /** Paragraphs the operation wrote a `w14:paraId` on, by id. */
+    readonly stamped?: readonly string[];
+    /** Paragraphs the operation removed from the document, by id, nested ones included. */
+    readonly removedParagraphIds?: readonly string[];
+    /** The paragraph id the document reflows from. */
+    readonly reflowFrom?: string;
+    /** Old id → new id, for a table whose first paragraph changed. */
+    readonly remappedIds?: Readonly<Record<string, string>>;
+}
+export type Issue = (path: string, code: string, message: string) => void;
+export interface DocxOperationHandler<T extends DocxOperation = DocxOperation> {
+    validate(operation: T, context: DocxOperationContext, issue: Issue): Promise<void>;
+    apply(operation: T, context: DocxOperationContext): Promise<DocxOperationResult>;
+}
+export declare function issueCollector(operationIndex: number, issues: OperationIssue[]): Issue;

package/dist/edit/docx/operations.js

@@ -0,0 +1,3 @@
+export function issueCollector(operationIndex, issues) {
+    return (path, code, message) => issues.push({ operationIndex, path, code, message });
+}

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

@@ -0,0 +1,13 @@
+import type { EditEngineContext } from "../engine.js";
+import { type OoxmlEditProviderOptions } from "../ooxml/worker.js";
+import { WorkerEngineClient } from "../worker-engine.js";
+export type DocxEditProviderOptions = OoxmlEditProviderOptions;
+/**
+ * Starts the OOXML edit worker for `original` as a DOCX engine. Loaded
+ * lazily by the Office adapter's provider on the first `edit()`.
+ */
+export declare function loadDocxEditEngine(original: Uint8Array, context: EditEngineContext, options?: DocxEditProviderOptions): Promise<DocxEditEngineClient>;
+export declare class DocxEditEngineClient extends WorkerEngineClient {
+    readonly schemas: import("../types.js").OperationSchemaSet;
+    start(original: Uint8Array): Promise<void>;
+}

package/dist/edit/docx/provider.js

@@ -0,0 +1,34 @@
+import { WorkerRpcClient } from "../../worker-client.js";
+import { createOoxmlEditWorker, } from "../ooxml/worker.js";
+import { WorkerEngineClient } from "../worker-engine.js";
+import { docxOperationSchemas } from "./schemas.js";
+/**
+ * Starts the OOXML edit worker for `original` as a DOCX engine. Loaded
+ * lazily by the Office adapter's provider on the first `edit()`.
+ */
+export async function loadDocxEditEngine(original, context, options = {}) {
+    const worker = createOoxmlEditWorker(options, context);
+    const rpc = new WorkerRpcClient(worker);
+    const engine = new DocxEditEngineClient(rpc, context);
+    try {
+        await engine.start(original);
+        return engine;
+    }
+    catch (error) {
+        rpc.destroy();
+        throw error;
+    }
+}
+export class DocxEditEngineClient extends WorkerEngineClient {
+    schemas = docxOperationSchemas;
+    async start(original) {
+        const data = original.slice().buffer;
+        const open = {
+            data,
+            limits: this.context.limits,
+            format: "docx",
+            ...(this.context.fileName ? { fileName: this.context.fileName } : {}),
+        };
+        await this.request("edit-open", open, this.context.signal, [data]);
+    }
+}

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

@@ -0,0 +1,6 @@
+import type { OperationSchemaSet } from "../types.js";
+/** Operations with an engine handler; grows as the tasks land. */
+export declare const IMPLEMENTED_OPERATIONS: readonly string[];
+export declare const docxOperationSchemas: OperationSchemaSet;
+/** Every schema, implemented or not, for the conformance test. */
+export declare const docxOperationSchemaDrafts: Readonly<Record<string, Readonly<Record<string, unknown>>>>;