@cj-tech-master/excelts 9.4.2 → 9.5.0

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

@@ -0,0 +1,728 @@
+/**
+ * DOCX Module - Document Builder
+ *
+ * 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.
+ */
+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";
+/** Create a text run. */
+export declare function text(content: string, properties?: RunProperties): Run;
+/** Create a bold text run. */
+export declare function bold(content: string, properties?: Omit<RunProperties, "bold">): Run;
+/** Create an italic text run. */
+export declare function italic(content: string, properties?: Omit<RunProperties, "italic">): Run;
+/** Create a run with a page break. */
+export declare function pageBreak(): Run;
+/** Create a run with a line break. */
+export declare function lineBreak(): Run;
+/** Create a run with a column break. */
+export declare function columnBreak(): Run;
+/** Create a tab run. */
+export declare function tab(): Run;
+/** Create a positional tab (w:ptab). */
+export declare function positionalTab(options: {
+    alignment: PositionalTabAlignment;
+    relativeTo: PositionalTabRelativeTo;
+    leader?: PositionalTabLeader;
+}): Run;
+/**
+ * Create a ruby (phonetic guide) run — e.g. Japanese furigana or Chinese pinyin.
+ *
+ * @param baseText - The main text being annotated.
+ * @param rubyText - The phonetic text shown above the base.
+ * @param properties - Optional ruby properties (alignment, font size, language).
+ */
+export declare function ruby(baseText: string | Run | readonly Run[], rubyText: string | Run | readonly Run[], properties?: RubyProperties): Run;
+/** Create a carriage return run. */
+export declare function carriageReturn(): Run;
+/** Create a no-break hyphen run. */
+export declare function noBreakHyphen(): Run;
+/** Create a soft hyphen run. */
+export declare function softHyphen(): Run;
+/** Create a run with a field code. */
+export declare function field(instruction: string, cachedValue?: string): Run;
+/** Create a PAGE field (current page number). */
+export declare function pageNumberField(cachedValue?: string): Run;
+/** Create a NUMPAGES field (total page count). */
+export declare function totalPagesField(cachedValue?: string): Run;
+/** Create a SECTIONPAGES field (pages in section). */
+export declare function sectionPagesField(cachedValue?: string): Run;
+/** Create a SECTION field (current section number). */
+export declare function sectionField(cachedValue?: string): Run;
+/** Create a DATE field. */
+export declare function dateField(format?: string, cachedValue?: string): Run;
+/** Create a SEQ (sequence) field for numbering figures, tables, etc. */
+export declare function sequenceField(identifier: string, options?: {
+    cachedValue?: string;
+    hide?: boolean;
+}): Run;
+/** Create a TIME field (current time). */
+export declare function timeField(format?: string, cachedValue?: string): Run;
+/** Create an AUTHOR field. */
+export declare function authorField(cachedValue?: string): Run;
+/** Create a TITLE field. */
+export declare function titleField(cachedValue?: string): Run;
+/** Create a SUBJECT field. */
+export declare function subjectField(cachedValue?: string): Run;
+/** Create a KEYWORDS field. */
+export declare function keywordsField(cachedValue?: string): Run;
+/** Create a FILENAME field. */
+export declare function fileNameField(options?: {
+    includePath?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create a FILESIZE field. */
+export declare function fileSizeField(cachedValue?: string): Run;
+/**
+ * Create a STYLEREF field (references text from nearest paragraph with given style).
+ *
+ * Commonly used in headers to show current chapter/section heading.
+ */
+export declare function styleRefField(styleName: string, options?: {
+    /** Search from bottom of page (default: top). */
+    fromBottom?: boolean;
+    /** Insert paragraph number instead of text. */
+    insertParagraphNumber?: boolean;
+    /** Insert position (above/below) reference. */
+    insertPosition?: boolean;
+    /** Suppress non-delimiter/non-numerical text. */
+    suppressNonNumeric?: boolean;
+    cachedValue?: string;
+}): Run;
+/**
+ * Create a REF field (references a bookmark).
+ */
+export declare function refField(bookmarkName: string, options?: {
+    /** Insert bookmark number. */
+    insertNumber?: boolean;
+    /** Hyperlink to bookmark. */
+    hyperlink?: boolean;
+    /** Paragraph number (no context). */
+    paragraphNumber?: boolean;
+    /** Relative paragraph number. */
+    relativeParagraphNumber?: boolean;
+    /** Full context paragraph number. */
+    fullContext?: boolean;
+    /** Suppress non-delimiter. */
+    suppressNonDelimiter?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create a PAGEREF field (references page of bookmark). */
+export declare function pageRefField(bookmarkName: string, options?: {
+    hyperlink?: boolean;
+    relativePosition?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create a NOTEREF field (references a footnote/endnote). */
+export declare function noteRefField(bookmarkName: string, options?: {
+    hyperlink?: boolean;
+    insertNumberFormat?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create a HYPERLINK field (alternative to w:hyperlink element). */
+export declare function hyperlinkField(target: string, options?: {
+    /** Anchor within target (bookmark). */
+    anchor?: string;
+    /** Open in new window. */
+    newWindow?: boolean;
+    /** Display text (if omitted, uses target). */
+    displayText?: string;
+    /** Screen tip tooltip. */
+    tooltip?: string;
+    cachedValue?: string;
+}): Run;
+/** Create a QUOTE field (literal text). */
+export declare function quoteField(text: string, cachedValue?: string): Run;
+/**
+ * Create a TOC field for table of contents.
+ *
+ * @param options - TOC options.
+ */
+export declare function tocField(options?: {
+    /** Heading levels to include (e.g. "1-3"). */
+    headingLevels?: string;
+    /** Include paragraphs with these styles. */
+    styles?: readonly string[];
+    /** Include table entries (TC fields) with these levels. */
+    tcLevels?: string;
+    /** Hyperlinks for entries. */
+    hyperlink?: boolean;
+    /** Right-align page numbers. */
+    rightAlignedPageNumbers?: boolean;
+    /** Use tab leader (default "." dots). */
+    tabLeader?: "." | "-" | "_" | " ";
+    /** Suppress page numbers. */
+    noPageNumbers?: boolean;
+    /** Identifier for table of captions. */
+    captionIdentifier?: string;
+    cachedValue?: string;
+}): Run;
+/** Create a TC (table of contents entry) field. */
+export declare function tcField(text: string, options?: {
+    level?: number;
+    suppressPageNumber?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create an XE (index entry) field. */
+export declare function indexEntryField(text: string, options?: {
+    bold?: boolean;
+    italic?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create an INDEX field (renders index from XE entries). */
+export declare function indexField(options?: {
+    bookmark?: string;
+    columns?: number;
+    entryType?: string;
+    cachedValue?: string;
+}): Run;
+/** Create an IF field (conditional content). */
+export declare function ifField(condition: string, trueText: string, falseText: string, cachedValue?: string): Run;
+/** Create an INCLUDETEXT field (includes external file content). */
+export declare function includeTextField(filePath: string, options?: {
+    bookmark?: string;
+    cachedValue?: string;
+}): Run;
+/** Create an INCLUDEPICTURE field. */
+export declare function includePictureField(filePath: string, cachedValue?: string): Run;
+/** Create a FORMTEXT field (legacy text form field). */
+export declare function formTextField(cachedValue?: string): Run;
+/** Create a FORMCHECKBOX field (legacy checkbox form field). */
+export declare function formCheckboxField(cachedValue?: string): Run;
+/** Create a FORMDROPDOWN field (legacy dropdown form field). */
+export declare function formDropdownField(cachedValue?: string): Run;
+/** Create a paragraph. */
+export declare function paragraph(children: ParagraphChild[], properties?: ParagraphProperties): Paragraph;
+/** Create a simple text paragraph. */
+export declare function textParagraph(content: string, properties?: ParagraphProperties & {
+    run?: RunProperties;
+}): Paragraph;
+/** Create a heading paragraph. */
+export declare function heading(content: string, level: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): Paragraph;
+/** Create a hyperlink. */
+export declare function hyperlink(linkText: string, options: {
+    rId?: string;
+    url?: string;
+    anchor?: string;
+    tooltip?: string;
+    properties?: RunProperties;
+}): ParagraphChild;
+/** Create a bookmark start. */
+export declare function bookmarkStart(id: number, name: string): ParagraphChild;
+/** Create a bookmark end. */
+export declare function bookmarkEnd(id: number): ParagraphChild;
+/** Create a comment range start marker. */
+export declare function commentRangeStart(id: number): CommentRangeStart;
+/** Create a comment range end marker. */
+export declare function commentRangeEnd(id: number): CommentRangeEnd;
+/** Create a comment reference (inside paragraph children). */
+export declare function commentReference(id: number): CommentReference;
+/** Create an inserted run (track changes). */
+export declare function insertedRun(run: Run, revision: RevisionInfo): InsertedRun;
+/** Create a deleted run (track changes). */
+export declare function deletedRun(run: Run, revision: RevisionInfo): DeletedRun;
+/** Create a moved-from run (track changes — source of a move). */
+export declare function movedFromRun(run: Run, revision: RevisionInfo): MovedFromRun;
+/** Create a moved-to run (track changes — destination of a move). */
+export declare function movedToRun(run: Run, revision: RevisionInfo): MovedToRun;
+/** Create a move range start marker. */
+export declare function moveFromRangeStart(id: number, author: string, options?: {
+    date?: string;
+    name?: string;
+}): MoveRangeMarker;
+/** Create a move range end marker. */
+export declare function moveFromRangeEnd(id: number): MoveRangeMarker;
+/** Create a move-to range start marker. */
+export declare function moveToRangeStart(id: number, author: string, options?: {
+    date?: string;
+    name?: string;
+}): MoveRangeMarker;
+/** Create a move-to range end marker. */
+export declare function moveToRangeEnd(id: number): MoveRangeMarker;
+/** Create a checkbox. */
+export declare function checkBox(options?: {
+    checked?: boolean;
+    checkedState?: {
+        value: string;
+        font?: string;
+    };
+    uncheckedState?: {
+        value: string;
+        font?: string;
+    };
+}): CheckBox;
+/** Create a math block. */
+export declare function mathBlock(content: MathContent[]): MathBlock;
+/** Create a math text run. */
+export declare function mathRun(mathText: string, properties?: {
+    italic?: boolean;
+    bold?: boolean;
+    font?: string;
+}): MathContent;
+/** Create a math fraction. */
+export declare function mathFraction(numerator: MathContent[], denominator: MathContent[], fractionType?: "bar" | "skw" | "lin" | "noBar"): MathContent;
+/** Create a math square root. */
+export declare function mathSqrt(content: MathContent[]): MathContent;
+/** Create a math nth root. */
+export declare function mathRoot(degree: MathContent[], content: MathContent[]): MathContent;
+/** Create a math summation. */
+export declare function mathSum(content: MathContent[], sub?: MathContent[], sup?: MathContent[]): MathContent;
+/** Create a math integral. */
+export declare function mathIntegral(content: MathContent[], sub?: MathContent[], sup?: MathContent[]): MathContent;
+/** Create a math product. */
+export declare function mathProduct(content: MathContent[], sub?: MathContent[], sup?: MathContent[]): MathContent;
+/** Create a math superscript. */
+export declare function mathSuperScript(base: MathContent[], superScript: MathContent[]): MathContent;
+/** Create a math subscript. */
+export declare function mathSubScript(base: MathContent[], subScript: MathContent[]): MathContent;
+/** Create a math sub-superscript. */
+export declare function mathSubSuperScript(base: MathContent[], subScript: MathContent[], superScript: MathContent[]): MathContent;
+/** Create a math pre-sub-superscript (subscript/superscript before the base). */
+export declare function mathPreSubSuperScript(base: MathContent[], preSubScript: MathContent[], preSuperScript: MathContent[]): MathContent;
+/** Create a math phantom (invisible expression that takes up space). */
+export declare function mathPhantom(content: MathContent[], options?: {
+    show?: boolean;
+    zeroWidth?: boolean;
+    zeroAscent?: boolean;
+    zeroDescent?: boolean;
+    transparent?: boolean;
+}): MathContent;
+/** Create a math group character (e.g. a horizontal brace over an expression). */
+export declare function mathGroupChar(base: MathContent[], options?: {
+    char?: string;
+    position?: "top" | "bottom";
+    verticalAlign?: "top" | "center" | "bottom";
+}): MathContent;
+/** Create a math border box (draw borders around / strike through an expression). */
+export declare function mathBorderBox(content: MathContent[], options?: {
+    hideTop?: boolean;
+    hideBottom?: boolean;
+    hideLeft?: boolean;
+    hideRight?: boolean;
+    strikeBlTr?: boolean;
+    strikeTlBr?: boolean;
+    strikeH?: boolean;
+    strikeV?: boolean;
+}): MathContent;
+/** Create a math delimiter (parentheses, brackets, etc.). */
+export declare function mathDelimiter(content: MathContent[][], options?: {
+    beginChar?: string;
+    endChar?: string;
+    separatorChar?: string;
+}): MathContent;
+/** Create a math n-ary operator (sum, integral, product, etc.). */
+export declare function mathNary(char: string, content: MathContent[], sub?: MathContent[], sup?: MathContent[]): MathContent;
+/** Create a math function (sin, cos, lim, etc.). */
+export declare function mathFunction(name: MathContent[], content: MathContent[]): MathContent;
+/** Create a math limit (upper or lower). */
+export declare function mathLimit(base: MathContent[], limit: MathContent[], limitType?: "upper" | "lower"): MathContent;
+/** Create a math matrix. */
+export declare function mathMatrix(rows: MathContent[][][]): MathContent;
+/** Create a math accent (hat, tilde, etc.). */
+export declare function mathAccent(content: MathContent[], char?: string): MathContent;
+/** Create a math bar (overbar/underbar). */
+export declare function mathBar(content: MathContent[], position?: "top" | "bottom"): MathContent;
+/** Create a math box. */
+export declare function mathBox(content: MathContent[]): MathContent;
+/** Create a math equation array. */
+export declare function mathEquationArray(rows: MathContent[][]): MathContent;
+/** Create a symbol run. */
+export declare function symbol(font: string, char: string, properties?: RunProperties): Run;
+/** Create a floating image (body-level). */
+export declare function floatingImage(options: {
+    rId: string;
+    width: Emu;
+    height: Emu;
+    horizontalPosition?: FloatingImage["horizontalPosition"];
+    verticalPosition?: FloatingImage["verticalPosition"];
+    wrap?: FloatingImage["wrap"];
+    altText?: string;
+    name?: string;
+    behindDoc?: boolean;
+    lockAnchor?: boolean;
+    layoutInCell?: boolean;
+    allowOverlap?: boolean;
+    simplePos?: {
+        x: Emu;
+        y: Emu;
+    };
+    distT?: Emu;
+    distB?: Emu;
+    distL?: Emu;
+    distR?: Emu;
+    rotation?: number;
+    flipHorizontal?: boolean;
+    flipVertical?: boolean;
+    srcRect?: FloatingImage["srcRect"];
+}): FloatingImage;
+/** Create a DrawingML shape. */
+export declare function drawingShape(options: {
+    shapeType: DrawingShape["shapeType"];
+    width: Emu;
+    height: Emu;
+    fillColor?: HexColor;
+    noFill?: boolean;
+    outlineColor?: HexColor;
+    outlineWidth?: Emu;
+    noOutline?: boolean;
+    textContent?: readonly Paragraph[];
+    altText?: string;
+    name?: string;
+    horizontalPosition?: DrawingShape["horizontalPosition"];
+    verticalPosition?: DrawingShape["verticalPosition"];
+    wrap?: DrawingShape["wrap"];
+    behindDoc?: boolean;
+    rotation?: number;
+}): DrawingShape;
+/** Create a chart content block. */
+export declare function chart(options: {
+    type: Chart["type"];
+    series: readonly ChartSeries[];
+    title?: string;
+    legend?: ChartLegendPosition;
+    categoryAxis?: ChartAxis;
+    valueAxis?: ChartAxis;
+    plotAreaColor?: HexColor;
+    chartAreaColor?: HexColor;
+    view3d?: boolean;
+    style?: number;
+    width?: Emu;
+    height?: Emu;
+    altText?: string;
+    name?: string;
+}): ChartContent;
+/** Create a structured document tag (content control). */
+export declare function structuredDocumentTag(content: (Paragraph | Table)[], properties?: SdtProperties): StructuredDocumentTag;
+/** Shorthand border. */
+export declare function border(style?: Border["style"], size?: number, color?: string): Border;
+/** Create standard grid borders for a table. */
+export declare function gridBorders(size?: number, color?: string): TableBorders;
+/** Create a table cell. */
+export declare function cell(content: string | (Paragraph | Table)[], properties?: TableCellProperties): TableCell;
+/** Create a table row. */
+export declare function row(cells: TableCell[], properties?: TableRowProperties): TableRow;
+/** Create a table. */
+export declare function table(rows: TableRow[], properties?: TableProperties, columnWidths?: Twips[]): Table;
+/** Create a simple table from a 2D string array. */
+export declare function simpleTable(data: string[][], options?: {
+    headerRow?: boolean;
+    borders?: boolean;
+    width?: TableWidth;
+    columnWidths?: Twips[];
+}): Table;
+/**
+ * Fluent builder for constructing DOCX documents.
+ *
+ * @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();
+ * ```
+ */
+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;
+    /** Add raw body content. */
+    addContent(content: BodyContent): this;
+    /** Add a paragraph with runs. */
+    addParagraphElement(para: Paragraph): this;
+    /** Add a simple text paragraph. */
+    addParagraph(content: string, properties?: ParagraphProperties & {
+        run?: RunProperties;
+    }): this;
+    /** Add a heading. */
+    addHeading(content: string, level?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): this;
+    /** Add a page break. */
+    addPageBreak(): this;
+    /** Add a table from a 2D array. */
+    addTable(data: string[][], options?: {
+        headerRow?: boolean;
+        borders?: boolean;
+        width?: TableWidth;
+        columnWidths?: Twips[];
+    }): this;
+    /** Add a table element. */
+    addTableElement(tbl: Table): this;
+    /** Add an inline image. Returns the image relationship ID and drawing ID. */
+    addImage(data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
+        altText?: string;
+        name?: string;
+    }): {
+        rId: string;
+        drawingId: number;
+    };
+    /** Add a floating image. Returns the image relationship ID. */
+    addFloatingImage(data: Uint8Array, mediaType: ImageMediaType, width: Emu, height: Emu, options?: {
+        altText?: string;
+        name?: string;
+        horizontalPosition?: FloatingImage["horizontalPosition"];
+        verticalPosition?: FloatingImage["verticalPosition"];
+        wrap?: FloatingImage["wrap"];
+        behindDoc?: boolean;
+        lockAnchor?: boolean;
+        layoutInCell?: boolean;
+        allowOverlap?: boolean;
+        distT?: Emu;
+        distB?: Emu;
+        distL?: Emu;
+        distR?: Emu;
+        rotation?: number;
+        flipHorizontal?: boolean;
+        flipVertical?: boolean;
+    }): string;
+    /** Add a custom font definition. */
+    addFont(font: FontDef): this;
+    /** Set a text watermark on the document. */
+    setWatermark(watermark: Watermark): this;
+    /** Add a footnote. Returns the footnote ID. */
+    addFootnote(content: string | Paragraph[]): number;
+    /** Add an endnote. Returns the endnote ID. */
+    addEndnote(content: string | Paragraph[]): number;
+    /** Add a comment. Returns the comment ID. */
+    addComment(author: string, content: string | Paragraph[], options?: {
+        date?: string;
+        initials?: string;
+    }): number;
+    /** Add a Table of Contents. */
+    addTableOfContents(options?: Partial<Omit<TableOfContents, "type">>): this;
+    /** Add a math equation block. */
+    addMath(content: MathContent[]): this;
+    /** Add a text box. */
+    addTextBox(content: string | Paragraph[], options?: {
+        width?: Twips;
+        height?: Twips;
+        stroke?: boolean;
+        fill?: boolean;
+    }): this;
+    /** Add a bullet list. */
+    addBulletList(items: string[], level?: number): this;
+    /** Add a numbered list. */
+    addNumberedList(items: string[], level?: number): this;
+    /** Set section properties (page size, margins, etc.). */
+    setSectionProperties(props: SectionProperties): this;
+    /** Set document defaults. */
+    setDocDefaults(defaults: DocDefaults): this;
+    /** Add a style definition. */
+    addStyle(style: StyleDef): this;
+    /** Set default styles (Normal, Heading1-6, Hyperlink, etc.). */
+    useDefaultStyles(): this;
+    /** Set a header for the given type. */
+    setHeader(type: string, content: HeaderFooterContent): this;
+    /** Set a footer for the given type. */
+    setFooter(type: string, content: HeaderFooterContent): this;
+    /** Set document settings. */
+    setSettings(settings: DocumentSettings): this;
+    /** Set core properties (metadata). */
+    setCoreProperties(props: CoreProperties): this;
+    /** Set application properties. */
+    setAppProperties(props: AppProperties): this;
+    /** Set document background. */
+    setBackground(background: DocumentBackground): this;
+    /** Add a custom document property. */
+    addCustomProperty(name: string, value: CustomPropertyValue): this;
+    /** Add a section break with properties. */
+    addSectionBreak(props: SectionProperties): this;
+    /** 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;
+/** Result of a text search in a document. */
+export interface SearchResult {
+    /** Paragraph index in body. */
+    readonly paragraphIndex: number;
+    /** The matched text. */
+    readonly match: string;
+    /** Character offset within the paragraph's concatenated text. */
+    readonly offset: number;
+}
+/**
+ * Count all top-level paragraphs in the document body.
+ */
+export declare function paragraphCount(doc: DocxDocument): number;
+/**
+ * Count words across all paragraphs in the document body.
+ * Uses simple whitespace splitting; for East Asian text, each CJK character
+ * is counted as one "word" to approximate meaningful unit count.
+ */
+export declare function countWords(doc: DocxDocument): number;
+/** A heading extracted from a document. */
+export interface DocumentHeading {
+    /** Heading level (1-9). */
+    readonly level: number;
+    /** Plain text of the heading. */
+    readonly text: string;
+    /** Index into doc.body where the paragraph resides. */
+    readonly paragraphIndex: number;
+    /** Style ID used (e.g. "Heading1"). */
+    readonly style?: string;
+}
+/**
+ * Extract the heading outline from a document.
+ *
+ * Matches paragraphs whose style is `Heading1` through `Heading9` (case-insensitive),
+ * or whose `outlineLevel` property is set (0-8).
+ */
+export declare function getHeadings(doc: DocxDocument): DocumentHeading[];
+/**
+ * Find a bookmark by name.
+ *
+ * @returns The bookmark start marker + its location, or `undefined` if not found.
+ */
+export declare function findBookmark(doc: DocxDocument, name: string): {
+    bookmark: BookmarkStart;
+    paragraphIndex: number;
+    childIndex: number;
+} | undefined;
+/**
+ * Find a comment by its ID.
+ */
+export declare function findComment(doc: DocxDocument, id: number): CommentDef | undefined;
+/**
+ * List all images registered in the document.
+ */
+export declare function listImages(doc: DocxDocument): readonly ImageDef[];
+/**
+ * List all tables in the document body (top-level only).
+ */
+export declare function listTables(doc: DocxDocument): readonly Table[];
+/**
+ * Collect all hyperlinks in the document body.
+ */
+export declare function listHyperlinks(doc: DocxDocument): readonly Hyperlink[];
+/**
+ * Get the total number of tables (top-level) and nested tables.
+ */
+export declare function tableCount(doc: DocxDocument): number;
+/**
+ * Extract plain text from the entire document body.
+ *
+ * Paragraphs are separated by `\n`. Tables render as tab-separated cell text.
+ */
+export declare function extractText(doc: DocxDocument): string;
+/**
+ * Search for text occurrences in a document's body paragraphs.
+ *
+ * @param doc - The document model to search.
+ * @param query - String or RegExp to search for.
+ * @returns Array of search results.
+ */
+export declare function searchText(doc: DocxDocument, query: string | RegExp): SearchResult[];
+/**
+ * Replace text in a document's body paragraphs (mutates the document).
+ *
+ * Performs simple text replacement within run content. Each run's text content
+ * is individually searched and replaced. For cross-run matches, the paragraph
+ * text is reconstructed and split back into runs.
+ *
+ * @param doc - The document model to modify (mutated in place).
+ * @param search - String or RegExp to find.
+ * @param replacement - Replacement string (supports $1, $2 etc. for RegExp).
+ * @returns Number of replacements made.
+ */
+export declare function replaceText(doc: DocxDocument, search: string | RegExp, replacement: string): number;
+/**
+ * Execute a mail merge: replace all MERGEFIELD fields in the document with values from the data map.
+ *
+ * Fields not found in the data map are left unchanged (or optionally cleared).
+ *
+ * @param doc - The document to modify (mutated in place).
+ * @param data - Map of field names to replacement values.
+ * @param options - Optional settings.
+ * @returns The number of fields replaced.
+ */
+export declare function mailMerge(doc: DocxDocument, data: Record<string, string>, options?: {
+    /** 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>;