@cj-tech-master/excelts 9.5.0 → 9.5.1

package/dist/browser/modules/word/document-io.js

@@ -0,0 +1,239 @@
+/**
+ * DOCX Module - Document IO
+ *
+ * IO operations that depend on docx-packager and docx-reader.
+ * Separated from document.ts so that builder helpers can be imported
+ * without pulling in archive/xml/writer code.
+ */
+import { packageDocx } from "./docx-packager.js";
+import { readDocx } from "./docx-reader.js";
+import { bytesToBase64 } from "./internal-utils.js";
+// =============================================================================
+// Document IO (toBuffer / toBase64)
+// =============================================================================
+/** Package a DocxDocument model to DOCX bytes. */
+export async function toBuffer(doc, compressionLevel) {
+    return packageDocx(doc, compressionLevel);
+}
+/** Package a DocxDocument model to base64 string. */
+export async function toBase64(doc, compressionLevel) {
+    const bytes = await toBuffer(doc, compressionLevel);
+    return bytesToBase64(bytes);
+}
+/**
+ * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
+ *
+ * Placeholders are strings like `{{name}}` embedded in the document text.
+ * They may span across multiple runs — the patcher handles cross-run matching.
+ *
+ * Supported patch content types:
+ * - `text` — simple text replacement (preserves formatting of the first run)
+ * - `paragraph` — replaces the entire paragraph containing the placeholder
+ * - `table` — replaces the entire paragraph with a table
+ * - `image` — replaces the placeholder with an inline image
+ *
+ * @param buffer - The source DOCX file as a Uint8Array.
+ * @param patches - Array of patch operations to apply.
+ * @param options - Optional compression settings.
+ * @returns New DOCX file as a Uint8Array.
+ */
+export async function patchDocument(buffer, patches, options) {
+    const doc = await readDocx(buffer);
+    // Build lookup map for quick placeholder matching
+    const patchMap = new Map();
+    for (const patch of patches) {
+        patchMap.set(patch.placeholder, patch);
+    }
+    // Process body content
+    const newBody = [];
+    for (const block of doc.body) {
+        if (block.type === "paragraph") {
+            const result = patchParagraph(block, patchMap);
+            if (result) {
+                if (Array.isArray(result)) {
+                    newBody.push(...result);
+                }
+                else {
+                    newBody.push(result);
+                }
+            }
+        }
+        else if (block.type === "table") {
+            patchTable(block, patchMap);
+            newBody.push(block);
+        }
+        else {
+            newBody.push(block);
+        }
+    }
+    // Patch headers
+    if (doc.headers) {
+        for (const [, headerDef] of doc.headers) {
+            patchHeaderFooterContent(headerDef.content, patchMap);
+        }
+    }
+    // Patch footers
+    if (doc.footers) {
+        for (const [, footerDef] of doc.footers) {
+            patchHeaderFooterContent(footerDef.content, patchMap);
+        }
+    }
+    // Add any new images from patches
+    const images = doc.images ? [...doc.images] : [];
+    for (const patch of patches) {
+        if (patch.content.type === "image") {
+            const imgContent = patch.content;
+            const existing = images.find(i => i.fileName === imgContent.image.fileName);
+            if (!existing) {
+                images.push(imgContent.image);
+            }
+        }
+    }
+    const patched = {
+        ...doc,
+        body: newBody,
+        images: images.length > 0 ? images : undefined
+    };
+    return packageDocx(patched, options?.compressionLevel);
+}
+// =============================================================================
+// Internal helpers
+// =============================================================================
+/** Extract concatenated plain text from a paragraph's runs. */
+function paragraphText(para) {
+    let t = "";
+    for (const child of para.children) {
+        if ("content" in child && Array.isArray(child.content)) {
+            for (const c of child.content) {
+                if ("type" in c && c.type === "text" && "text" in c) {
+                    t += c.text;
+                }
+            }
+        }
+    }
+    return t;
+}
+/** Replace text within a single paragraph. */
+function replaceInParagraph(para, search, replacement) {
+    for (const child of para.children) {
+        if (!("content" in child) || !Array.isArray(child.content)) {
+            continue;
+        }
+        for (const c of child.content) {
+            if (!("type" in c) || c.type !== "text" || !("text" in c)) {
+                continue;
+            }
+            const before = c.text;
+            if (before.includes(search)) {
+                c.text = before.replaceAll(search, replacement);
+            }
+        }
+    }
+    // Cross-run replacement fallback
+    const fullText = paragraphText(para);
+    if (fullText.includes(search)) {
+        const newText = fullText.replaceAll(search, replacement);
+        let placed = false;
+        for (const child of para.children) {
+            if (!("content" in child) || !Array.isArray(child.content)) {
+                continue;
+            }
+            for (const c of child.content) {
+                if (!("type" in c) || c.type !== "text" || !("text" in c)) {
+                    continue;
+                }
+                if (!placed) {
+                    c.text = newText;
+                    placed = true;
+                }
+                else {
+                    c.text = "";
+                }
+            }
+        }
+    }
+}
+/** Patch a paragraph — returns replacement content or null to remove. */
+function patchParagraph(para, patchMap) {
+    const text = paragraphText(para);
+    for (const [placeholder, patch] of patchMap) {
+        if (!text.includes(placeholder)) {
+            continue;
+        }
+        switch (patch.content.type) {
+            case "text": {
+                replaceInParagraph(para, placeholder, patch.content.text);
+                return para;
+            }
+            case "paragraph": {
+                return patch.content.children;
+            }
+            case "table": {
+                return patch.content.table;
+            }
+            case "image": {
+                const img = patch.content.image;
+                const rId = img.rId ?? `rId_img_${img.fileName}`;
+                const imgContent = {
+                    type: "image",
+                    rId,
+                    width: patch.content.width,
+                    height: patch.content.height,
+                    altText: img.fileName,
+                    name: img.fileName
+                };
+                const newPara = {
+                    type: "paragraph",
+                    properties: para.properties,
+                    children: [{ content: [imgContent] }]
+                };
+                return newPara;
+            }
+        }
+    }
+    return para;
+}
+/** Patch text inside table cells recursively. */
+function patchTable(table, patchMap) {
+    for (const row of table.rows) {
+        for (const cell of row.cells) {
+            const newContent = [];
+            for (const block of cell.content) {
+                if (block.type === "paragraph") {
+                    const result = patchParagraph(block, patchMap);
+                    if (result) {
+                        if (Array.isArray(result)) {
+                            newContent.push(...result);
+                        }
+                        else {
+                            newContent.push(result);
+                        }
+                    }
+                }
+                else if (block.type === "table") {
+                    patchTable(block, patchMap);
+                    newContent.push(block);
+                }
+                else {
+                    newContent.push(block);
+                }
+            }
+            cell.content = newContent;
+        }
+    }
+}
+/** Patch text in header/footer content. */
+function patchHeaderFooterContent(content, patchMap) {
+    for (const child of content.children) {
+        if (child.type === "paragraph") {
+            for (const [placeholder, patch] of patchMap) {
+                if (patch.content.type === "text") {
+                    const text = paragraphText(child);
+                    if (text.includes(placeholder)) {
+                        replaceInParagraph(child, placeholder, patch.content.text);
+                    }
+                }
+            }
+        }
+    }
+}

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

@@ -4,8 +4,11 @@
  * High-level fluent API for constructing DOCX documents programmatically.
  * Provides convenience methods for common operations including comments,
  * track changes, TOC, math, text boxes, checkboxes, and custom properties.
+ *
+ * This file has NO static imports from docx-packager or docx-reader,
+ * ensuring that importing builder helpers does not pull in archive/xml code.
  */
-import type { DocxDocument, BodyContent, Paragraph, ParagraphProperties, ParagraphChild, Run, RunProperties, Table, TableRow, TableCell, TableProperties, TableRowProperties, TableCellProperties, SectionProperties, StyleDef, DocDefaults, BookmarkStart, Hyperlink, HeaderFooterContent, ImageDef, ImageMediaType, CoreProperties, AppProperties, DocumentSettings, FontDef, Border, TableWidth, TableBorders, Emu, Twips, CommentDef, DocumentBackground, CustomPropertyValue, TableOfContents, MathBlock, MathContent, CheckBox, RevisionInfo, InsertedRun, DeletedRun, MovedFromRun, MovedToRun, MoveRangeMarker, Chart, ChartSeries, ChartAxis, ChartLegendPosition, ChartContent, CommentRangeStart, CommentRangeEnd, CommentReference, FloatingImage, StructuredDocumentTag, SdtProperties, Watermark, DocumentTheme, ColorSpec, HexColor, DrawingShape, PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader, RubyProperties } from "./types.js";
+import type { DocxDocument, BodyContent, Paragraph, ParagraphProperties, ParagraphChild, Run, RunProperties, Table, TableRow, TableCell, TableProperties, TableRowProperties, TableCellProperties, SectionProperties, StyleDef, DocDefaults, BookmarkStart, Hyperlink, HeaderFooterContent, ImageDef, ImageMediaType, CoreProperties, AppProperties, DocumentSettings, FontDef, Border, TableWidth, TableBorders, Emu, Twips, CommentDef, DocumentBackground, CustomPropertyValue, TableOfContents, MathBlock, MathContent, CheckBox, RevisionInfo, InsertedRun, DeletedRun, MovedFromRun, MovedToRun, MoveRangeMarker, Chart, ChartSeries, ChartAxis, ChartLegendPosition, ChartContent, CommentRangeStart, CommentRangeEnd, CommentReference, FloatingImage, StructuredDocumentTag, SdtProperties, Watermark, HexColor, DrawingShape, PositionalTabAlignment, PositionalTabRelativeTo, PositionalTabLeader, RubyProperties } from "./types.js";
 /** Create a text run. */
 export declare function text(content: string, properties?: RunProperties): Run;
 /** Create a bold text run. */
@@ -411,71 +414,55 @@ export declare function simpleTable(data: string[][], options?: {
     width?: TableWidth;
     columnWidths?: Twips[];
 }): Table;
+declare const _documentBrand: unique symbol;
+/**
+ * Opaque handle representing a document being built.
+ * Created via `Document.create()`, passed to `Document.*` functions.
+ */
+export type DocumentHandle = {
+    readonly [_documentBrand]: true;
+};
 /**
- * Fluent builder for constructing DOCX documents.
+ * Namespace of free functions for building DOCX documents.
+ *
+ * Replaces the former `DocumentBuilder` class with tree-shakeable free functions.
+ * Each function operates on an opaque `DocumentHandle`.
  *
  * @example
  * ```ts
- * const doc = new DocumentBuilder()
- *   .addHeading("Hello World", 1)
- *   .addParagraph("This is a paragraph.")
- *   .addTable([["Name", "Age"], ["Alice", "30"]])
- *   .build();
- *
- * const bytes = await doc.toBuffer();
+ * const doc = Document.create();
+ * Document.addHeading(doc, "Hello World", 1);
+ * Document.addParagraph(doc, "This is a paragraph.");
+ * Document.addTable(doc, [["Name", "Age"], ["Alice", "30"]]);
+ * const bytes = await Document.toBuffer(doc);
  * ```
  */
-export declare class DocumentBuilder {
-    private _body;
-    private _sectionProperties?;
-    private _styles;
-    private _docDefaults?;
-    private _abstractNumberings;
-    private _numberingInstances;
-    private _headers;
-    private _footers;
-    private _footnotes;
-    private _endnotes;
-    private _images;
-    private _fonts;
-    private _settings?;
-    private _coreProperties?;
-    private _appProperties?;
-    private _comments;
-    private _background?;
-    private _customProperties;
-    private _watermark?;
-    private _nextImageId;
-    private _nextFootnoteId;
-    private _nextEndnoteId;
-    private _nextBookmarkId;
-    private _nextAbstractNumId;
-    private _nextNumId;
-    private _nextDrawingId;
-    private _nextCommentId;
+export declare const Document: {
+    /** Create a new document handle. */
+    create(): DocumentHandle;
     /** Add raw body content. */
-    addContent(content: BodyContent): this;
+    addContent(doc: DocumentHandle, content: BodyContent): void;
     /** Add a paragraph with runs. */
-    addParagraphElement(para: Paragraph): this;
+    addParagraphElement(doc: DocumentHandle, para: Paragraph): void;
     /** Add a simple text paragraph. */
-    addParagraph(content: string, properties?: ParagraphProperties & {
+    addParagraph(doc: DocumentHandle, content: string, properties?: ParagraphProperties & {
         run?: RunProperties;
-    }): this;
+    }): void;
     /** Add a heading. */
-    addHeading(content: string, level?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): this;
+    addHeading(doc: DocumentHandle, content: string, level?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): void;
     /** Add a page break. */
-    addPageBreak(): this;
+    addPageBreak(doc: DocumentHandle): void;
     /** Add a table from a 2D array. */
-    addTable(data: string[][], options?: {
+    addTable(doc: DocumentHandle, data: string[][], options?: {
         headerRow?: boolean;
         borders?: boolean;
         width?: TableWidth;
         columnWidths?: Twips[];
-    }): this;
+    }): void;
     /** Add a table element. */
-    addTableElement(tbl: Table): this;
+    addTableElement(doc: DocumentHandle, tbl: Table): void;
     /** Add an inline image. Returns the image relationship ID and drawing ID. */
-    addImage(data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
+    addImage(doc: DocumentHandle, data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
         altText?: string;
         name?: string;
     }): {
@@ -483,7 +470,7 @@ export declare class DocumentBuilder {
         drawingId: number;
     };
     /** Add a floating image. Returns the image relationship ID. */
-    addFloatingImage(data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
+    addFloatingImage(doc: DocumentHandle, data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
         altText?: string;
         name?: string;
         horizontalPosition?: FloatingImage["horizontalPosition"];
@@ -502,76 +489,63 @@ export declare class DocumentBuilder {
         flipVertical?: boolean;
     }): string;
     /** Add a custom font definition. */
-    addFont(font: FontDef): this;
+    addFont(doc: DocumentHandle, font: FontDef): void;
     /** Set a text watermark on the document. */
-    setWatermark(watermark: Watermark): this;
+    setWatermark(doc: DocumentHandle, watermark: Watermark): void;
     /** Add a footnote. Returns the footnote ID. */
-    addFootnote(content: string | Paragraph[]): number;
+    addFootnote(doc: DocumentHandle, content: string | Paragraph[]): number;
     /** Add an endnote. Returns the endnote ID. */
-    addEndnote(content: string | Paragraph[]): number;
+    addEndnote(doc: DocumentHandle, content: string | Paragraph[]): number;
     /** Add a comment. Returns the comment ID. */
-    addComment(author: string, content: string | Paragraph[], options?: {
+    addComment(doc: DocumentHandle, author: string, content: string | Paragraph[], options?: {
         date?: string;
         initials?: string;
     }): number;
     /** Add a Table of Contents. */
-    addTableOfContents(options?: Partial<Omit<TableOfContents, "type">>): this;
+    addTableOfContents(doc: DocumentHandle, options?: Partial<Omit<TableOfContents, "type">>): void;
     /** Add a math equation block. */
-    addMath(content: MathContent[]): this;
+    addMath(doc: DocumentHandle, content: MathContent[]): void;
     /** Add a text box. */
-    addTextBox(content: string | Paragraph[], options?: {
+    addTextBox(doc: DocumentHandle, content: string | Paragraph[], options?: {
         width?: Twips;
         height?: Twips;
         stroke?: boolean;
         fill?: boolean;
-    }): this;
+    }): void;
     /** Add a bullet list. */
-    addBulletList(items: string[], level?: number): this;
+    addBulletList(doc: DocumentHandle, items: string[], level?: number): void;
     /** Add a numbered list. */
-    addNumberedList(items: string[], level?: number): this;
+    addNumberedList(doc: DocumentHandle, items: string[], level?: number): void;
     /** Set section properties (page size, margins, etc.). */
-    setSectionProperties(props: SectionProperties): this;
+    setSectionProperties(doc: DocumentHandle, props: SectionProperties): void;
     /** Set document defaults. */
-    setDocDefaults(defaults: DocDefaults): this;
+    setDocDefaults(doc: DocumentHandle, defaults: DocDefaults): void;
     /** Add a style definition. */
-    addStyle(style: StyleDef): this;
+    addStyle(doc: DocumentHandle, style: StyleDef): void;
     /** Set default styles (Normal, Heading1-6, Hyperlink, etc.). */
-    useDefaultStyles(): this;
+    useDefaultStyles(doc: DocumentHandle): void;
     /** Set a header for the given type. */
-    setHeader(type: string, content: HeaderFooterContent): this;
+    setHeader(doc: DocumentHandle, type: string, content: HeaderFooterContent): void;
     /** Set a footer for the given type. */
-    setFooter(type: string, content: HeaderFooterContent): this;
+    setFooter(doc: DocumentHandle, type: string, content: HeaderFooterContent): void;
     /** Set document settings. */
-    setSettings(settings: DocumentSettings): this;
+    setSettings(doc: DocumentHandle, settings: DocumentSettings): void;
     /** Set core properties (metadata). */
-    setCoreProperties(props: CoreProperties): this;
+    setCoreProperties(doc: DocumentHandle, props: CoreProperties): void;
     /** Set application properties. */
-    setAppProperties(props: AppProperties): this;
+    setAppProperties(doc: DocumentHandle, props: AppProperties): void;
     /** Set document background. */
-    setBackground(background: DocumentBackground): this;
+    setBackground(doc: DocumentHandle, background: DocumentBackground): void;
     /** Add a custom document property. */
-    addCustomProperty(name: string, value: CustomPropertyValue): this;
+    addCustomProperty(doc: DocumentHandle, name: string, value: CustomPropertyValue): void;
     /** Add a section break with properties. */
-    addSectionBreak(props: SectionProperties): this;
+    addSectionBreak(doc: DocumentHandle, props: SectionProperties): void;
     /** Get next available bookmark ID. */
-    nextBookmarkId(): number;
-    /** Build the DocxDocument model. */
-    build(): DocxDocument;
-    /** Build and package to DOCX bytes. */
-    toBuffer(compressionLevel?: number): Promise<Uint8Array>;
-    /** Build and package to base64 string. */
-    toBase64(compressionLevel?: number): Promise<string>;
-}
-/**
- * Resolve a ColorSpec to an actual hex RGB color using the document theme.
- *
- * Applies theme color lookup + tint/shade transformations per OOXML spec.
- *
- * @param color - The color value (HexColor string or ColorSpec).
- * @param theme - The document theme (from `doc.theme`).
- * @returns Resolved hex color string (6 chars, no #), or undefined if unresolvable.
- */
-export declare function resolveThemeColor(color: HexColor | ColorSpec | undefined, theme?: DocumentTheme): HexColor | undefined;
+    nextBookmarkId(doc: DocumentHandle): number;
+    /** Build the DocxDocument model from the handle. */
+    build(doc: DocumentHandle): DocxDocument;
+};
+export { resolveThemeColor } from "./color-utils.js";
 /** Result of a text search in a document. */
 export interface SearchResult {
     /** Paragraph index in body. */
@@ -680,49 +654,4 @@ export declare function mailMerge(doc: DocxDocument, data: Record<string, string
     /** If true, remove fields not found in data. Default: false (leave unchanged). */
     removeUnmatched?: boolean;
 }): number;
-/** Type of content to patch into a placeholder. */
-export type PatchContent = {
-    readonly type: "text";
-    readonly text: string;
-} | {
-    readonly type: "paragraph";
-    readonly children: readonly Paragraph[];
-} | {
-    readonly type: "table";
-    readonly table: Table;
-} | {
-    readonly type: "image";
-    readonly image: ImageDef;
-    readonly width: number;
-    readonly height: number;
-};
-/** A single patch operation mapping a placeholder to replacement content. */
-export interface PatchOperation {
-    /** Placeholder string to find (e.g. "{{name}}"). */
-    readonly placeholder: string;
-    /** Content to replace the placeholder with. */
-    readonly content: PatchContent;
-}
-/** Options for patchDocument. */
-export interface PatchOptions {
-    /** Compression level (0-9). Default: 6. */
-    readonly compressionLevel?: number;
-}
-/**
- * Read an existing DOCX file, replace placeholders with content, and produce a new DOCX.
- *
- * Placeholders are strings like `{{name}}` embedded in the document text.
- * They may span across multiple runs — the patcher handles cross-run matching.
- *
- * Supported patch content types:
- * - `text` — simple text replacement (preserves formatting of the first run)
- * - `paragraph` — replaces the entire paragraph containing the placeholder
- * - `table` — replaces the entire paragraph with a table
- * - `image` — replaces the placeholder with an inline image
- *
- * @param buffer - The source DOCX file as a Uint8Array.
- * @param patches - Array of patch operations to apply.
- * @param options - Optional compression settings.
- * @returns New DOCX file as a Uint8Array.
- */
-export declare function patchDocument(buffer: Uint8Array, patches: readonly PatchOperation[], options?: PatchOptions): Promise<Uint8Array>;
+export type { PatchContent, PatchOperation, PatchOptions } from "./document-io.js";