@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/html.d.ts

@@ -1,13 +1,14 @@
 /**
- * DOCX Module - HTML Renderer (Subpath Export)
+ * DOCX Module - HTML Converters (Subpath Entry)
  *
- * Import separately to avoid pulling html-renderer into the bundle
- * when only core document building is needed.
+ * Re-exports the HTML converter API at `excelts/word/html`. This file is
+ * referenced by `package.json#exports["./word/html"]`; it forwards to the
+ * implementation under `./convert/html`.
  *
  * @example
  * ```ts
- * import { renderToHtml } from "excelts/word/html";
+ * import { renderToHtml, htmlToDocxBody } from "excelts/word/html";
  * ```
  */
-export { renderToHtml } from "./html-renderer.js";
-export type { HtmlRenderOptions, HtmlRenderResult } from "./html-renderer.js";
+export { renderToHtml, htmlToDocxBody } from "./convert/html/html.js";
+export type { HtmlRenderOptions, HtmlRenderResult, HtmlImportOptions } from "./convert/html/html.js";

package/dist/browser/modules/word/html.js

@@ -1,12 +1,13 @@
 /**
- * DOCX Module - HTML Renderer (Subpath Export)
+ * DOCX Module - HTML Converters (Subpath Entry)
  *
- * Import separately to avoid pulling html-renderer into the bundle
- * when only core document building is needed.
+ * Re-exports the HTML converter API at `excelts/word/html`. This file is
+ * referenced by `package.json#exports["./word/html"]`; it forwards to the
+ * implementation under `./convert/html`.
  *
  * @example
  * ```ts
- * import { renderToHtml } from "excelts/word/html";
+ * import { renderToHtml, htmlToDocxBody } from "excelts/word/html";
  * ```
  */
-export { renderToHtml } from "./html-renderer.js";
+export { renderToHtml, htmlToDocxBody } from "./convert/html/html.js";

package/dist/browser/modules/word/incremental-edit.d.ts

@@ -0,0 +1,123 @@
+/**
+ * DOCX Incremental Edit API
+ *
+ * Supports efficient "open → modify → save" workflows by editing a DOCX
+ * file at the ZIP entry level.
+ *
+ * Use cases:
+ * - Replace just the document.xml in an existing template
+ * - Update headers/footers without touching styles or images
+ * - Patch specific parts (e.g. core properties metadata)
+ *
+ * **Limitations and caveats — read before using `replacePart`/`deletePart`:**
+ *
+ * This API is a thin wrapper around ZIP entry mutation. It deliberately
+ * does not understand DOCX semantics:
+ *
+ * - `[Content_Types].xml` is **not** updated when you add a new part with
+ *   a previously-unseen content type. If your replacement part introduces
+ *   a new MIME type, callers must also patch `[Content_Types].xml` (or
+ *   round-trip through `readDocx` + `packageDocx` instead).
+ * - Relationship files (`*.rels`) are **not** rebuilt. Adding or deleting
+ *   a part with relationships will leave the corresponding `_rels/*.rels`
+ *   stale.
+ * - `replaceBody`, `replaceHeader`, `replaceFooter` only rewrite their
+ *   target XML part; they do **not** modify the corresponding `.rels` file
+ *   or copy in new media binaries. As a result they reject content that
+ *   would introduce new relationship IDs (images, hyperlinks, charts,
+ *   altChunks, opaque drawings carrying rIds) — use `patchDocument` /
+ *   `packageDocx` for those cases. Existing references that survive
+ *   unchanged are fine because their `.rels` entries already exist.
+ *
+ * For DOCX-aware edits (changes that may add/remove relationships or
+ * content types) use `patchDocument` or `compileTemplate`, or round-trip
+ * through `readDocx` + `packageDocx`.
+ *
+ * Note: This API operates on raw ZIP entries; it does not parse the DOCX
+ * model. For higher-level edits use `patchDocument` or `compileTemplate`.
+ */
+import type { BodyContent, Paragraph, Table } from "./types.js";
+/** A single incremental edit operation. */
+export type IncrementalEdit = {
+    /**
+     * Replace a specific part by raw bytes.
+     *
+     * Caveat: does not update `[Content_Types].xml` or any `.rels` file.
+     * Adding a part with a new content type or new relationships will
+     * produce a malformed package. See the file header for details.
+     */
+    readonly type: "replacePart";
+    readonly path: string;
+    readonly data: Uint8Array;
+} | {
+    /** Replace a part with a string (UTF-8 encoded). Same caveats as `replacePart`. */
+    readonly type: "replacePartText";
+    readonly path: string;
+    readonly text: string;
+} | {
+    /**
+     * Delete a specific part.
+     *
+     * Caveat: does not update `[Content_Types].xml` or any `.rels` file.
+     * Deleting a part that other parts reference (via rels or other XML)
+     * will leave dangling references — round-trip through readDocx +
+     * packageDocx if you need a consistent package.
+     */
+    readonly type: "deletePart";
+    readonly path: string;
+} | {
+    /** Replace the body content of `word/document.xml`. */
+    readonly type: "replaceBody";
+    readonly body: readonly BodyContent[];
+} | {
+    /** Replace a header part identified by path (e.g. `word/header1.xml`). */
+    readonly type: "replaceHeader";
+    readonly path: string;
+    readonly children: readonly (Paragraph | Table)[];
+} | {
+    /** Replace a footer part identified by path (e.g. `word/footer1.xml`). */
+    readonly type: "replaceFooter";
+    readonly path: string;
+    readonly children: readonly (Paragraph | Table)[];
+};
+/** Options for incremental editing. */
+export interface IncrementalEditOptions {
+    /** Compression level for replaced entries (0-9). Default: 6. */
+    readonly compressionLevel?: number;
+}
+/**
+ * Apply incremental edits to an existing DOCX file.
+ *
+ * Reads all parts from the original ZIP, applies the edits, and writes a
+ * new ZIP. Unchanged parts are passed through (decompressed and recompressed,
+ * but their content is not parsed).
+ *
+ * @param buffer - The original DOCX file as a Uint8Array.
+ * @param edits - Array of incremental edits to apply.
+ * @param options - Optional settings.
+ * @returns A new DOCX file as a Uint8Array.
+ *
+ * @example
+ * ```ts
+ * const original = await fs.readFile("template.docx");
+ * const edited = await editDocxIncremental(original, [
+ *   { type: "replaceBody", body: [...newParagraphs] }
+ * ]);
+ * ```
+ */
+export declare function editDocxIncremental(buffer: Uint8Array, edits: readonly IncrementalEdit[], options?: IncrementalEditOptions): Promise<Uint8Array>;
+/**
+ * List all part paths in a DOCX file without parsing the model.
+ *
+ * @param buffer - The DOCX file as a Uint8Array.
+ * @returns Array of part paths.
+ */
+export declare function listDocxParts(buffer: Uint8Array): Promise<string[]>;
+/**
+ * Read a single part's raw bytes from a DOCX file.
+ *
+ * @param buffer - The DOCX file as a Uint8Array.
+ * @param path - The part path (e.g. `"word/document.xml"`).
+ * @returns The part's raw bytes, or undefined if the part doesn't exist.
+ */
+export declare function readDocxPart(buffer: Uint8Array, path: string): Promise<Uint8Array | undefined>;

package/dist/browser/modules/word/incremental-edit.js

@@ -0,0 +1,361 @@
+/**
+ * DOCX Incremental Edit API
+ *
+ * Supports efficient "open → modify → save" workflows by editing a DOCX
+ * file at the ZIP entry level.
+ *
+ * Use cases:
+ * - Replace just the document.xml in an existing template
+ * - Update headers/footers without touching styles or images
+ * - Patch specific parts (e.g. core properties metadata)
+ *
+ * **Limitations and caveats — read before using `replacePart`/`deletePart`:**
+ *
+ * This API is a thin wrapper around ZIP entry mutation. It deliberately
+ * does not understand DOCX semantics:
+ *
+ * - `[Content_Types].xml` is **not** updated when you add a new part with
+ *   a previously-unseen content type. If your replacement part introduces
+ *   a new MIME type, callers must also patch `[Content_Types].xml` (or
+ *   round-trip through `readDocx` + `packageDocx` instead).
+ * - Relationship files (`*.rels`) are **not** rebuilt. Adding or deleting
+ *   a part with relationships will leave the corresponding `_rels/*.rels`
+ *   stale.
+ * - `replaceBody`, `replaceHeader`, `replaceFooter` only rewrite their
+ *   target XML part; they do **not** modify the corresponding `.rels` file
+ *   or copy in new media binaries. As a result they reject content that
+ *   would introduce new relationship IDs (images, hyperlinks, charts,
+ *   altChunks, opaque drawings carrying rIds) — use `patchDocument` /
+ *   `packageDocx` for those cases. Existing references that survive
+ *   unchanged are fine because their `.rels` entries already exist.
+ *
+ * For DOCX-aware edits (changes that may add/remove relationships or
+ * content types) use `patchDocument` or `compileTemplate`, or round-trip
+ * through `readDocx` + `packageDocx`.
+ *
+ * Note: This API operates on raw ZIP entries; it does not parse the DOCX
+ * model. For higher-level edits use `patchDocument` or `compileTemplate`.
+ */
+import { zip } from "../archive/create-archive.js";
+import { unzip } from "../archive/read-archive.js";
+import { XmlWriter } from "../xml/writer.js";
+import { PartPath } from "./constants.js";
+import { utf8Decoder, utf8Encoder } from "./core/internal-utils.js";
+import { walkBlocks } from "./core/walker.js";
+import { DocxUnsupportedFeatureError } from "./errors.js";
+import { renderBodyContent, renderDocument } from "./writer/document-writer.js";
+import { renderHeader, renderFooter } from "./writer/header-footer-writer.js";
+import { createRenderContext } from "./writer/render-context.js";
+/**
+ * Apply incremental edits to an existing DOCX file.
+ *
+ * Reads all parts from the original ZIP, applies the edits, and writes a
+ * new ZIP. Unchanged parts are passed through (decompressed and recompressed,
+ * but their content is not parsed).
+ *
+ * @param buffer - The original DOCX file as a Uint8Array.
+ * @param edits - Array of incremental edits to apply.
+ * @param options - Optional settings.
+ * @returns A new DOCX file as a Uint8Array.
+ *
+ * @example
+ * ```ts
+ * const original = await fs.readFile("template.docx");
+ * const edited = await editDocxIncremental(original, [
+ *   { type: "replaceBody", body: [...newParagraphs] }
+ * ]);
+ * ```
+ */
+export async function editDocxIncremental(buffer, edits, options) {
+    // Read all entries from the original ZIP. Some third-party ZIP writers emit
+    // entry paths with a leading "/" — strip it so lookups by canonical path
+    // (e.g. "word/document.xml") match consistently with the rest of the
+    // codebase (see readDocxPart below).
+    const reader = unzip(buffer);
+    const parts = new Map();
+    for await (const entry of reader.entries()) {
+        const normalizedPath = entry.path.replace(/^\/+/, "");
+        parts.set(normalizedPath, await entry.bytes());
+    }
+    // Apply edits
+    for (const edit of edits) {
+        switch (edit.type) {
+            case "replacePart":
+                parts.set(edit.path.replace(/^\/+/, ""), edit.data);
+                break;
+            case "replacePartText":
+                parts.set(edit.path.replace(/^\/+/, ""), utf8Encoder.encode(edit.text));
+                break;
+            case "deletePart":
+                parts.delete(edit.path.replace(/^\/+/, ""));
+                break;
+            case "replaceBody": {
+                // Preserve the original document's section properties, background,
+                // and document-level wrappers — only swap the children inside w:body.
+                // Reject new external references for the same reason as
+                // replaceHeader/Footer: this editor doesn't rewrite document.xml.rels.
+                assertNoExternalReferences(edit.body, "body");
+                const original = parts.get(PartPath.Document);
+                parts.set(PartPath.Document, original
+                    ? replaceBodyChildrenInDocumentXml(original, edit.body)
+                    : renderBodyOnly(edit.body));
+                break;
+            }
+            case "replaceHeader":
+                parts.set(edit.path.replace(/^\/+/, ""), renderHeaderFooter("header", edit.children));
+                break;
+            case "replaceFooter":
+                parts.set(edit.path.replace(/^\/+/, ""), renderHeaderFooter("footer", edit.children));
+                break;
+        }
+    }
+    // Write back to a new ZIP
+    const archive = zip({ level: options?.compressionLevel ?? 6 });
+    for (const [path, data] of parts) {
+        archive.add(path, data);
+    }
+    return archive.bytes();
+}
+/**
+ * List all part paths in a DOCX file without parsing the model.
+ *
+ * @param buffer - The DOCX file as a Uint8Array.
+ * @returns Array of part paths.
+ */
+export async function listDocxParts(buffer) {
+    const reader = unzip(buffer);
+    const paths = [];
+    for await (const entry of reader.entries()) {
+        paths.push(entry.path);
+    }
+    return paths;
+}
+/**
+ * Read a single part's raw bytes from a DOCX file.
+ *
+ * @param buffer - The DOCX file as a Uint8Array.
+ * @param path - The part path (e.g. `"word/document.xml"`).
+ * @returns The part's raw bytes, or undefined if the part doesn't exist.
+ */
+export async function readDocxPart(buffer, path) {
+    const reader = unzip(buffer);
+    for await (const entry of reader.entries()) {
+        const normalizedPath = entry.path.replace(/^\//, "");
+        if (normalizedPath === path) {
+            return entry.bytes();
+        }
+    }
+    return undefined;
+}
+// =============================================================================
+// Internal helpers
+// =============================================================================
+function renderBodyOnly(body) {
+    const minimalDoc = { body };
+    const ctx = createRenderContext();
+    const xml = new XmlWriter();
+    renderDocument(xml, minimalDoc, ctx);
+    return utf8Encoder.encode(xml.toString());
+}
+/**
+ * Replace the children inside `<w:body>...</w:body>` of an existing
+ * document.xml, preserving the original section properties (the trailing
+ * `w:sectPr` directly under w:body), the document background, and any other
+ * document-level structure (namespace declarations, custom attributes, etc.).
+ *
+ * If the document doesn't contain a parseable `<w:body>` block we fall back
+ * to a minimal render so callers still get a valid DOCX (this matches the
+ * legacy behavior of `replaceBody`).
+ */
+function replaceBodyChildrenInDocumentXml(original, body) {
+    const text = utf8Decoder.decode(original);
+    // Locate <w:body...> opening tag and the matching </w:body>. We must
+    // ignore any literal "<w:body" or "</w:body>" sitting inside an XML
+    // comment, CDATA section, or processing instruction — those are common
+    // in author-edited documents and confused the previous purely-regex
+    // scan.
+    const range = findBodyTagRange(text);
+    if (!range) {
+        return renderBodyOnly(body);
+    }
+    const { bodyStart, bodyCloseIdx } = range;
+    const innerBody = text.slice(bodyStart, bodyCloseIdx);
+    // Preserve the trailing <w:sectPr ...>...</w:sectPr> if present. Section
+    // properties at this level apply to the whole document and would otherwise
+    // be lost.
+    let trailingSectPr = "";
+    const sectPrMatch = /<w:sectPr(?:\s[^>]*)?>[\s\S]*?<\/w:sectPr>\s*$|<w:sectPr(?:\s[^>]*)?\/>\s*$/.exec(innerBody);
+    if (sectPrMatch) {
+        trailingSectPr = sectPrMatch[0].trimEnd();
+    }
+    // Render new body children (no document/body wrappers, no sectPr — we add
+    // back the preserved one ourselves).
+    const ctx = createRenderContext();
+    const xml = new XmlWriter();
+    for (const block of body) {
+        renderBodyContent(xml, block, ctx);
+    }
+    const newInner = xml.toString() + trailingSectPr;
+    const updated = text.slice(0, bodyStart) + newInner + text.slice(bodyCloseIdx);
+    return utf8Encoder.encode(updated);
+}
+/**
+ * Locate the inner-text range of `<w:body>...</w:body>`, ignoring any
+ * occurrence of the literal tag inside XML comments (`<!-- ... -->`),
+ * CDATA sections (`<![CDATA[ ... ]]>`), or processing instructions
+ * (`<?...?>`). Returns the offsets of the first byte after the body open
+ * tag and the first byte of the body close tag, or `undefined` if either
+ * tag was not found.
+ *
+ * The scanner is a tiny linear pass — no lexer, no DOM. It only knows
+ * about the three "skip these contents" sections that can legitimately
+ * contain `<` and `>` characters.
+ */
+function findBodyTagRange(text) {
+    let bodyStart = -1;
+    let bodyCloseIdx = -1;
+    let i = 0;
+    while (i < text.length) {
+        const lt = text.indexOf("<", i);
+        if (lt < 0) {
+            break;
+        }
+        // Comment <!-- ... -->
+        if (text.startsWith("<!--", lt)) {
+            const end = text.indexOf("-->", lt + 4);
+            i = end < 0 ? text.length : end + 3;
+            continue;
+        }
+        // CDATA <![CDATA[ ... ]]>
+        if (text.startsWith("<![CDATA[", lt)) {
+            const end = text.indexOf("]]>", lt + 9);
+            i = end < 0 ? text.length : end + 3;
+            continue;
+        }
+        // Processing instruction <? ... ?>
+        if (text.startsWith("<?", lt)) {
+            const end = text.indexOf("?>", lt + 2);
+            i = end < 0 ? text.length : end + 2;
+            continue;
+        }
+        // Closing tag </w:body>
+        if (text.startsWith("</w:body>", lt)) {
+            // Track the LAST close tag (matches the previous behaviour of
+            // picking up the outermost body) — there should only be one in a
+            // well-formed document anyway, but a stale match would just be
+            // overwritten by the real one.
+            bodyCloseIdx = lt;
+            i = lt + "</w:body>".length;
+            continue;
+        }
+        // Opening tag <w:body...>
+        if (text.startsWith("<w:body", lt)) {
+            const next = text.charCodeAt(lt + 7);
+            // Must be either whitespace before attributes or '>' for the bare tag,
+            // or '/' for the (rare) self-closing form. Anything else (e.g.
+            // "<w:bodyExtra") is a different element name.
+            if (next === 0x20 ||
+                next === 0x09 ||
+                next === 0x0a ||
+                next === 0x0d ||
+                next === 0x3e ||
+                next === 0x2f) {
+                const gt = text.indexOf(">", lt);
+                if (gt < 0) {
+                    break;
+                }
+                // Self-closing `<w:body/>` carries no children — fall back to a
+                // full render rather than trying to splice into nothing.
+                if (text.charCodeAt(gt - 1) === 0x2f) {
+                    return undefined;
+                }
+                if (bodyStart < 0) {
+                    bodyStart = gt + 1;
+                }
+                i = gt + 1;
+                continue;
+            }
+        }
+        // Any other tag — skip past its '>'.
+        const gt = text.indexOf(">", lt + 1);
+        i = gt < 0 ? text.length : gt + 1;
+    }
+    if (bodyStart < 0 || bodyCloseIdx < 0 || bodyStart >= bodyCloseIdx) {
+        return undefined;
+    }
+    return { bodyStart, bodyCloseIdx };
+}
+function renderHeaderFooter(kind, children) {
+    // Reject content that requires fresh part-level relationships (images,
+    // external hyperlinks, charts, alt-chunks, embedded fonts, etc.). The
+    // incremental editor only rewrites individual XML parts; it does not
+    // rebuild the per-part `*.rels` file or copy in new media binaries, so
+    // any new `r:embed` / `r:id` reference would dangle. Callers wanting to
+    // add such content should use the full `patchDocument` / `packageDocx`
+    // flow instead.
+    assertNoExternalReferences(children, kind);
+    const xml = new XmlWriter();
+    if (kind === "header") {
+        renderHeader(xml, { children });
+    }
+    else {
+        renderFooter(xml, { children });
+    }
+    return utf8Encoder.encode(xml.toString());
+}
+/**
+ * Walk a header/footer / body fragment and throw if it contains any element
+ * that needs a per-part relationship registration the incremental editor
+ * cannot perform.
+ *
+ * The list mirrors what {@link renderBodyContent} writes as `r:embed` /
+ * `r:id` / `r:link` attributes:
+ *   - inline & floating images (`r:embed` / `r:link`)
+ *   - external hyperlinks (`r:id` on `w:hyperlink`)
+ *   - charts and chart extensions (`r:id` on `w:chart` / `cx:chart`)
+ *   - alt-chunks (`r:id` on `w:altChunk`)
+ *   - opaque drawings carrying preserved relationships
+ */
+function assertNoExternalReferences(blocks, context) {
+    let offending;
+    walkBlocks(blocks, {
+        enterRun(run) {
+            for (const c of run.content) {
+                if (c.type === "image") {
+                    offending ?? (offending = "inline image");
+                    return "stop";
+                }
+            }
+            return "continue";
+        },
+        enterHyperlink(h) {
+            if (h.url || h.rId) {
+                offending ?? (offending = "hyperlink");
+                return "stop";
+            }
+            return "continue";
+        },
+        visitFloatingImage() {
+            offending ?? (offending = "floating image");
+        },
+        visitChart() {
+            offending ?? (offending = "chart");
+        },
+        visitChartEx() {
+            offending ?? (offending = "chart (extended)");
+        },
+        visitAltChunk() {
+            offending ?? (offending = "altChunk");
+        },
+        visitOpaqueDrawing(drawing) {
+            if (drawing.referencedRIds.length > 0) {
+                offending ?? (offending = "opaque drawing with relationships");
+            }
+        }
+    });
+    if (offending) {
+        throw new DocxUnsupportedFeatureError(`incremental ${context} replacement does not support ${offending}: ` +
+            "relationship parts (.rels) are not rewritten. Use patchDocument() or " +
+            "rebuild the document with packageDocx() instead.");
+    }
+}