@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/browser/modules/word/builder/paragraph-builders.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Paragraph-level builder functions for DOCX documents.
+ *
+ * Includes paragraph, textParagraph, heading, hyperlink, bookmarks,
+ * comment markers, and track-change run wrappers.
+ */
+import type { Paragraph, ParagraphProperties, ParagraphChild, Run, RunProperties, CommentRangeStart, CommentRangeEnd, CommentReference, InsertedRun, DeletedRun, MovedFromRun, MovedToRun, MoveRangeMarker, RevisionInfo } from "../types.js";
+/** 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. Accepts plain text or an array of runs for mixed formatting. */
+export declare function heading(content: string | ParagraphChild[], 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;
+    /** Document location bookmark / fragment id (`w:docLocation`). */
+    docLocation?: string;
+    /** Target frame name for web views (`w:tgtFrame`). */
+    tgtFrame?: string;
+    /** Whether the hyperlink has been visited (`w:history`). */
+    history?: boolean;
+    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;

package/dist/browser/modules/word/builder/paragraph-builders.js

@@ -0,0 +1,90 @@
+/**
+ * Paragraph-level builder functions for DOCX documents.
+ *
+ * Includes paragraph, textParagraph, heading, hyperlink, bookmarks,
+ * comment markers, and track-change run wrappers.
+ */
+import { text } from "./run-builders.js";
+// =============================================================================
+// Paragraph Builders
+// =============================================================================
+/** Create a paragraph. */
+export function paragraph(children, properties) {
+    return { type: "paragraph", properties, children };
+}
+/** Create a simple text paragraph. */
+export function textParagraph(content, properties) {
+    const { run: runProps, ...pProps } = properties ?? {};
+    return paragraph([text(content, runProps)], Object.keys(pProps).length > 0 ? pProps : undefined);
+}
+/** Create a heading paragraph. Accepts plain text or an array of runs for mixed formatting. */
+export function heading(content, level) {
+    const children = typeof content === "string" ? [text(content)] : content;
+    return paragraph(children, { style: `Heading${level}` });
+}
+/** Create a hyperlink. */
+export function hyperlink(linkText, options) {
+    return {
+        type: "hyperlink",
+        rId: options.rId,
+        url: options.url,
+        anchor: options.anchor,
+        tooltip: options.tooltip,
+        docLocation: options.docLocation,
+        tgtFrame: options.tgtFrame,
+        history: options.history,
+        children: [text(linkText, options.properties ?? { color: "0563C1", underline: "single" })]
+    };
+}
+/** Create a bookmark start. */
+export function bookmarkStart(id, name) {
+    return { type: "bookmarkStart", id, name };
+}
+/** Create a bookmark end. */
+export function bookmarkEnd(id) {
+    return { type: "bookmarkEnd", id };
+}
+/** Create a comment range start marker. */
+export function commentRangeStart(id) {
+    return { type: "commentRangeStart", id };
+}
+/** Create a comment range end marker. */
+export function commentRangeEnd(id) {
+    return { type: "commentRangeEnd", id };
+}
+/** Create a comment reference (inside paragraph children). */
+export function commentReference(id) {
+    return { type: "commentReference", id };
+}
+/** Create an inserted run (track changes). */
+export function insertedRun(run, revision) {
+    return { type: "insertedRun", revision, run };
+}
+/** Create a deleted run (track changes). */
+export function deletedRun(run, revision) {
+    return { type: "deletedRun", revision, run };
+}
+/** Create a moved-from run (track changes — source of a move). */
+export function movedFromRun(run, revision) {
+    return { type: "movedFromRun", revision, run };
+}
+/** Create a moved-to run (track changes — destination of a move). */
+export function movedToRun(run, revision) {
+    return { type: "movedToRun", revision, run };
+}
+/** Create a move range start marker. */
+export function moveFromRangeStart(id, author, options) {
+    return { type: "moveFromRangeStart", id, author, date: options?.date, name: options?.name };
+}
+/** Create a move range end marker. */
+export function moveFromRangeEnd(id) {
+    return { type: "moveFromRangeEnd", id };
+}
+/** Create a move-to range start marker. */
+export function moveToRangeStart(id, author, options) {
+    return { type: "moveToRangeStart", id, author, date: options?.date, name: options?.name };
+}
+/** Create a move-to range end marker. */
+export function moveToRangeEnd(id) {
+    return { type: "moveToRangeEnd", id };
+}

package/dist/browser/modules/word/builder/run-builders.d.ts

@@ -0,0 +1,374 @@
+/**
+ * Run-level builder functions for DOCX documents.
+ *
+ * These are pure run/field/math/symbol/image/shape/chart/SDT/checkbox builders
+ * that do not depend on paragraph or table builders.
+ */
+import type { Run, RunProperties, MathBlock, MathContent, CheckBox, FloatingImage, DrawingShape, Chart, ChartSeries, ChartAxis, ChartLegendPosition, ChartContent, StructuredDocumentTag, SdtProperties, Paragraph, Table, Emu, HexColor, 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 an underlined text run. */
+export declare function underline(content: string, style?: "single" | "double" | "thick" | "dotted" | "dash" | "wave", properties?: Omit<RunProperties, "underline">): Run;
+/** Create a strikethrough text run. */
+export declare function strikethrough(content: string, properties?: Omit<RunProperties, "strike">): 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) with full properties. */
+export declare function formTextField(options?: {
+    name?: string;
+    default?: string;
+    maxLength?: number;
+    format?: string;
+    helpText?: string;
+    statusText?: string;
+    enabled?: boolean;
+    cachedValue?: string;
+}): Run;
+/** Create a FORMCHECKBOX field (legacy checkbox form field) with full properties. */
+export declare function formCheckboxField(options?: {
+    name?: string;
+    checked?: boolean;
+    default?: boolean;
+    size?: number;
+    cachedValue?: string;
+}): Run;
+/** Create a FORMDROPDOWN field (legacy dropdown form field) with full properties. */
+export declare function formDropdownField(options?: {
+    name?: string;
+    entries?: readonly string[];
+    default?: number;
+    helpText?: string;
+    statusText?: string;
+    enabled?: boolean;
+    cachedValue?: string;
+}): Run;
+/** 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;
+/** Create a checkbox. */
+export declare function checkBox(options?: {
+    checked?: boolean;
+    checkedState?: {
+        value: string;
+        font?: string;
+    };
+    uncheckedState?: {
+        value: string;
+        font?: string;
+    };
+}): CheckBox;