@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/builder/document-handle.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Document Handle & Namespace for building DOCX documents.
+ *
+ * Provides the Document namespace with free functions for constructing
+ * documents via an opaque DocumentHandle.
+ */
+import type { DocxDocument, BodyContent, Paragraph, ParagraphProperties, ParagraphChild, RunProperties, Table, SectionProperties, StyleDef, DocDefaults, HeaderFooterContent, ImageMediaType, CoreProperties, AppProperties, DocumentSettings, FontDef, TableWidth, Emu, Twips, DocumentBackground, CustomPropertyValue, TableOfContents, MathContent, FloatingImage, Watermark } from "../types.js";
+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;
+};
+/**
+ * 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
+ * import { Document, toBuffer } from "excelts/word";
+ *
+ * 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 toBuffer(Document.build(doc));
+ * ```
+ */
+export declare const Document: {
+    /** Create a new document handle. */
+    create(): DocumentHandle;
+    /** Add raw body content. */
+    addContent(doc: DocumentHandle, content: BodyContent): void;
+    /** Insert body content at a specific index. */
+    insertContentAt(doc: DocumentHandle, index: number, content: BodyContent): void;
+    /** Remove body content at a specific index. Returns the removed item. */
+    removeContent(doc: DocumentHandle, index: number): BodyContent | undefined;
+    /** Get the number of body content items. */
+    getContentCount(doc: DocumentHandle): number;
+    /** Get body content at a specific index. */
+    getContent(doc: DocumentHandle, index: number): BodyContent | undefined;
+    /** Add a paragraph with runs. */
+    addParagraphElement(doc: DocumentHandle, para: Paragraph): void;
+    /** Add a simple text paragraph. */
+    addParagraph(doc: DocumentHandle, content: string, properties?: ParagraphProperties & {
+        run?: RunProperties;
+    }): void;
+    /** Add a heading. Accepts plain text or an array of ParagraphChild for mixed formatting. */
+    addHeading(doc: DocumentHandle, content: string | ParagraphChild[], level?: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9): void;
+    /** Add a page break. */
+    addPageBreak(doc: DocumentHandle): void;
+    /** Add a table from a 2D array. */
+    addTable(doc: DocumentHandle, data: string[][], options?: {
+        headerRow?: boolean;
+        borders?: boolean;
+        width?: TableWidth;
+        columnWidths?: Twips[];
+    }): void;
+    /** Add a table element. */
+    addTableElement(doc: DocumentHandle, tbl: Table): void;
+    /** Add an inline image. Returns the image relationship ID and drawing ID. */
+    addImage(doc: DocumentHandle, 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(doc: DocumentHandle, 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(doc: DocumentHandle, font: FontDef): void;
+    /** Set a text watermark on the document. */
+    setWatermark(doc: DocumentHandle, watermark: Watermark): void;
+    /** Add a footnote. Returns the footnote ID. */
+    addFootnote(doc: DocumentHandle, content: string | Paragraph[]): number;
+    /** Add an endnote. Returns the endnote ID. */
+    addEndnote(doc: DocumentHandle, content: string | Paragraph[]): number;
+    /** Add a comment. Returns the comment ID. */
+    addComment(doc: DocumentHandle, author: string, content: string | Paragraph[], options?: {
+        date?: string;
+        initials?: string;
+    }): number;
+    /** Add a Table of Contents. */
+    addTableOfContents(doc: DocumentHandle, options?: Partial<Omit<TableOfContents, "type">>): void;
+    /** Add a math equation block. */
+    addMath(doc: DocumentHandle, content: MathContent[]): void;
+    /** Add a text box. */
+    addTextBox(doc: DocumentHandle, content: string | Paragraph[], options?: {
+        width?: Twips;
+        height?: Twips;
+        stroke?: boolean;
+        fill?: boolean;
+    }): void;
+    /**
+     * Add a bullet list. Items can be plain strings or arrays of ParagraphChild for rich formatting.
+     */
+    addBulletList(doc: DocumentHandle, items: (string | ParagraphChild[])[], level?: number): void;
+    /** Add a numbered list. Items can be plain strings or arrays of ParagraphChild for rich formatting. */
+    addNumberedList(doc: DocumentHandle, items: (string | ParagraphChild[])[], level?: number): void;
+    /** Set section properties (page size, margins, etc.). */
+    setSectionProperties(doc: DocumentHandle, props: SectionProperties): void;
+    /** Set document defaults. */
+    setDocDefaults(doc: DocumentHandle, defaults: DocDefaults): void;
+    /** Add a style definition. */
+    addStyle(doc: DocumentHandle, style: StyleDef): void;
+    /** Set default styles (Normal, Heading1-6, Hyperlink, etc.). */
+    useDefaultStyles(doc: DocumentHandle): void;
+    /** Set a header for the given type. */
+    setHeader(doc: DocumentHandle, type: string, content: HeaderFooterContent): void;
+    /** Set a footer for the given type. */
+    setFooter(doc: DocumentHandle, type: string, content: HeaderFooterContent): void;
+    /** Set document settings. */
+    setSettings(doc: DocumentHandle, settings: DocumentSettings): void;
+    /** Set core properties (metadata). */
+    setCoreProperties(doc: DocumentHandle, props: CoreProperties): void;
+    /** Set application properties. */
+    setAppProperties(doc: DocumentHandle, props: AppProperties): void;
+    /** Set document background. */
+    setBackground(doc: DocumentHandle, background: DocumentBackground): void;
+    /** Add a custom document property. */
+    addCustomProperty(doc: DocumentHandle, name: string, value: CustomPropertyValue): void;
+    /** Add a section break with properties. */
+    addSectionBreak(doc: DocumentHandle, props: SectionProperties): void;
+    /** Get next available bookmark ID. */
+    nextBookmarkId(doc: DocumentHandle): number;
+    /** Build the DocxDocument model from the handle. */
+    build(doc: DocumentHandle): DocxDocument;
+};
+export {};