@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/esm/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/esm/modules/word/builder/run-builders.js

@@ -0,0 +1,600 @@
+/**
+ * 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.
+ */
+// =============================================================================
+// Run Builders
+// =============================================================================
+/** Create a text run. */
+export function text(content, properties) {
+    return { properties, content: [{ type: "text", text: content }] };
+}
+/** Create a bold text run. */
+export function bold(content, properties) {
+    return text(content, { ...properties, bold: true });
+}
+/** Create an italic text run. */
+export function italic(content, properties) {
+    return text(content, { ...properties, italic: true });
+}
+/** Create an underlined text run. */
+export function underline(content, style, properties) {
+    return text(content, { ...properties, underline: style ?? "single" });
+}
+/** Create a strikethrough text run. */
+export function strikethrough(content, properties) {
+    return text(content, { ...properties, strike: true });
+}
+/** Create a run with a page break. */
+export function pageBreak() {
+    return { content: [{ type: "break", breakType: "page" }] };
+}
+/** Create a run with a line break. */
+export function lineBreak() {
+    return { content: [{ type: "break" }] };
+}
+/** Create a run with a column break. */
+export function columnBreak() {
+    return { content: [{ type: "break", breakType: "column" }] };
+}
+/** Create a tab run. */
+export function tab() {
+    return { content: [{ type: "tab" }] };
+}
+/** Create a positional tab (w:ptab). */
+export function positionalTab(options) {
+    return {
+        content: [
+            {
+                type: "ptab",
+                alignment: options.alignment,
+                relativeTo: options.relativeTo,
+                leader: options.leader
+            }
+        ]
+    };
+}
+/**
+ * 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 function ruby(baseText, rubyText, properties) {
+    const normalize = (v) => {
+        if (typeof v === "string") {
+            return [text(v)];
+        }
+        if (Array.isArray(v)) {
+            return v;
+        }
+        return [v];
+    };
+    return {
+        content: [
+            {
+                type: "ruby",
+                properties,
+                baseText: normalize(baseText),
+                rubyText: normalize(rubyText)
+            }
+        ]
+    };
+}
+/** Create a carriage return run. */
+export function carriageReturn() {
+    return { content: [{ type: "carriageReturn" }] };
+}
+/** Create a no-break hyphen run. */
+export function noBreakHyphen() {
+    return { content: [{ type: "noBreakHyphen" }] };
+}
+/** Create a soft hyphen run. */
+export function softHyphen() {
+    return { content: [{ type: "softHyphen" }] };
+}
+/** Create a run with a field code. */
+export function field(instruction, cachedValue) {
+    return { content: [{ type: "field", instruction, cachedValue }] };
+}
+/**
+ * Internal helper: create a field with a fixed instruction code.
+ * Used to simplify the dozens of single-instruction field builders.
+ */
+function simpleField(code, cachedValue) {
+    return field(` ${code} `, cachedValue);
+}
+/** Create a PAGE field (current page number). */
+export function pageNumberField(cachedValue) {
+    return simpleField("PAGE", cachedValue ?? "1");
+}
+/** Create a NUMPAGES field (total page count). */
+export function totalPagesField(cachedValue) {
+    return simpleField("NUMPAGES", cachedValue ?? "1");
+}
+/** Create a SECTIONPAGES field (pages in section). */
+export function sectionPagesField(cachedValue) {
+    return simpleField("SECTIONPAGES", cachedValue ?? "1");
+}
+/** Create a SECTION field (current section number). */
+export function sectionField(cachedValue) {
+    return simpleField("SECTION", cachedValue ?? "1");
+}
+/** Create a DATE field. */
+export function dateField(format, cachedValue) {
+    const fmt = format ?? "yyyy-MM-dd";
+    return field(` DATE \\@ "${fmt}" `, cachedValue);
+}
+/** Create a SEQ (sequence) field for numbering figures, tables, etc. */
+export function sequenceField(identifier, options) {
+    let instruction = ` SEQ ${identifier} `;
+    if (options?.hide) {
+        instruction += "\\h ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a TIME field (current time). */
+export function timeField(format, cachedValue) {
+    const fmt = format ?? "HH:mm:ss";
+    return field(` TIME \\@ "${fmt}" `, cachedValue);
+}
+/** Create an AUTHOR field. */
+export function authorField(cachedValue) {
+    return simpleField("AUTHOR", cachedValue);
+}
+/** Create a TITLE field. */
+export function titleField(cachedValue) {
+    return simpleField("TITLE", cachedValue);
+}
+/** Create a SUBJECT field. */
+export function subjectField(cachedValue) {
+    return simpleField("SUBJECT", cachedValue);
+}
+/** Create a KEYWORDS field. */
+export function keywordsField(cachedValue) {
+    return simpleField("KEYWORDS", cachedValue);
+}
+/** Create a FILENAME field. */
+export function fileNameField(options) {
+    const instruction = options?.includePath ? " FILENAME \\p " : " FILENAME ";
+    return field(instruction, options?.cachedValue);
+}
+/** Create a FILESIZE field. */
+export function fileSizeField(cachedValue) {
+    return simpleField("FILESIZE", cachedValue);
+}
+/**
+ * Create a STYLEREF field (references text from nearest paragraph with given style).
+ *
+ * Commonly used in headers to show current chapter/section heading.
+ */
+export function styleRefField(styleName, options) {
+    let instruction = ` STYLEREF "${styleName}" `;
+    if (options?.fromBottom) {
+        instruction += "\\l ";
+    }
+    if (options?.insertParagraphNumber) {
+        instruction += "\\n ";
+    }
+    if (options?.insertPosition) {
+        instruction += "\\p ";
+    }
+    if (options?.suppressNonNumeric) {
+        instruction += "\\t ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/**
+ * Create a REF field (references a bookmark).
+ */
+export function refField(bookmarkName, options) {
+    let instruction = ` REF ${bookmarkName} `;
+    if (options?.insertNumber) {
+        instruction += "\\n ";
+    }
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.paragraphNumber) {
+        instruction += "\\w ";
+    }
+    if (options?.relativeParagraphNumber) {
+        instruction += "\\r ";
+    }
+    if (options?.fullContext) {
+        instruction += "\\w ";
+    }
+    if (options?.suppressNonDelimiter) {
+        instruction += "\\t ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a PAGEREF field (references page of bookmark). */
+export function pageRefField(bookmarkName, options) {
+    let instruction = ` PAGEREF ${bookmarkName} `;
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.relativePosition) {
+        instruction += "\\p ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a NOTEREF field (references a footnote/endnote). */
+export function noteRefField(bookmarkName, options) {
+    let instruction = ` NOTEREF ${bookmarkName} `;
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.insertNumberFormat) {
+        instruction += "\\f ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a HYPERLINK field (alternative to w:hyperlink element). */
+export function hyperlinkField(target, options) {
+    let instruction = ` HYPERLINK "${target}" `;
+    if (options?.anchor) {
+        instruction += `\\l "${options.anchor}" `;
+    }
+    if (options?.newWindow) {
+        instruction += "\\n ";
+    }
+    if (options?.tooltip) {
+        instruction += `\\o "${options.tooltip}" `;
+    }
+    return field(instruction, options?.cachedValue ?? options?.displayText);
+}
+/** Create a QUOTE field (literal text). */
+export function quoteField(text, cachedValue) {
+    return field(` QUOTE "${text}" `, cachedValue ?? text);
+}
+/**
+ * Create a TOC field for table of contents.
+ *
+ * @param options - TOC options.
+ */
+export function tocField(options) {
+    let instruction = " TOC ";
+    if (options?.headingLevels) {
+        instruction += `\\o "${options.headingLevels}" `;
+    }
+    if (options?.styles && options.styles.length > 0) {
+        instruction += `\\t "${options.styles.join(";")}" `;
+    }
+    if (options?.tcLevels) {
+        instruction += `\\f ${options.tcLevels} `;
+    }
+    if (options?.hyperlink) {
+        instruction += "\\h ";
+    }
+    if (options?.rightAlignedPageNumbers) {
+        instruction += "\\z ";
+    }
+    if (options?.tabLeader) {
+        instruction += `\\p "${options.tabLeader}" `;
+    }
+    if (options?.noPageNumbers) {
+        instruction += "\\n ";
+    }
+    if (options?.captionIdentifier) {
+        instruction += `\\c "${options.captionIdentifier}" `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a TC (table of contents entry) field. */
+export function tcField(text, options) {
+    let instruction = ` TC "${text}" `;
+    if (options?.level !== undefined) {
+        instruction += `\\l ${options.level} `;
+    }
+    if (options?.suppressPageNumber) {
+        instruction += "\\n ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an XE (index entry) field. */
+export function indexEntryField(text, options) {
+    let instruction = ` XE "${text}" `;
+    if (options?.bold) {
+        instruction += "\\b ";
+    }
+    if (options?.italic) {
+        instruction += "\\i ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an INDEX field (renders index from XE entries). */
+export function indexField(options) {
+    let instruction = " INDEX ";
+    if (options?.bookmark) {
+        instruction += `\\b ${options.bookmark} `;
+    }
+    if (options?.columns) {
+        instruction += `\\c ${options.columns} `;
+    }
+    if (options?.entryType) {
+        instruction += `\\f "${options.entryType}" `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an IF field (conditional content). */
+export function ifField(condition, trueText, falseText, cachedValue) {
+    return field(` IF ${condition} "${trueText}" "${falseText}" `, cachedValue);
+}
+/** Create an INCLUDETEXT field (includes external file content). */
+export function includeTextField(filePath, options) {
+    let instruction = ` INCLUDETEXT "${filePath}" `;
+    if (options?.bookmark) {
+        instruction += `${options.bookmark} `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an INCLUDEPICTURE field. */
+export function includePictureField(filePath, cachedValue) {
+    return field(` INCLUDEPICTURE "${filePath}" `, cachedValue);
+}
+/** Create a FORMTEXT field (legacy text form field) with full properties. */
+export function formTextField(options) {
+    const formField = {
+        type: "text",
+        ...(options?.name !== undefined && { name: options.name }),
+        ...(options?.default !== undefined && { default: options.default }),
+        ...(options?.maxLength !== undefined && { maxLength: options.maxLength }),
+        ...(options?.format !== undefined && { format: options.format }),
+        ...(options?.helpText !== undefined && { helpText: options.helpText }),
+        ...(options?.statusText !== undefined && { statusText: options.statusText }),
+        ...(options?.enabled !== undefined && { enabled: options.enabled })
+    };
+    return {
+        content: [
+            {
+                type: "field",
+                instruction: " FORMTEXT ",
+                cachedValue: options?.cachedValue,
+                formField
+            }
+        ]
+    };
+}
+/** Create a FORMCHECKBOX field (legacy checkbox form field) with full properties. */
+export function formCheckboxField(options) {
+    const formField = {
+        type: "checkBox",
+        ...(options?.name !== undefined && { name: options.name }),
+        ...(options?.checked !== undefined && { checked: options.checked }),
+        ...(options?.default !== undefined && { default: options.default }),
+        ...(options?.size !== undefined && { size: options.size })
+    };
+    return {
+        content: [
+            {
+                type: "field",
+                instruction: " FORMCHECKBOX ",
+                cachedValue: options?.cachedValue,
+                formField
+            }
+        ]
+    };
+}
+/** Create a FORMDROPDOWN field (legacy dropdown form field) with full properties. */
+export function formDropdownField(options) {
+    const formField = {
+        type: "dropDown",
+        ...(options?.name !== undefined && { name: options.name }),
+        ...(options?.entries !== undefined && { entries: options.entries }),
+        ...(options?.default !== undefined && { default: options.default }),
+        ...(options?.helpText !== undefined && { helpText: options.helpText }),
+        ...(options?.statusText !== undefined && { statusText: options.statusText }),
+        ...(options?.enabled !== undefined && { enabled: options.enabled })
+    };
+    return {
+        content: [
+            {
+                type: "field",
+                instruction: " FORMDROPDOWN ",
+                cachedValue: options?.cachedValue,
+                formField
+            }
+        ]
+    };
+}
+// =============================================================================
+// Math Builders
+// =============================================================================
+/** Create a math block. */
+export function mathBlock(content) {
+    return { type: "math", content };
+}
+/** Create a math text run. */
+export function mathRun(mathText, properties) {
+    return { type: "mathRun", text: mathText, properties };
+}
+/** Create a math fraction. */
+export function mathFraction(numerator, denominator, fractionType) {
+    return { type: "mathFraction", fractionType, numerator, denominator };
+}
+/** Create a math square root. */
+export function mathSqrt(content) {
+    return { type: "mathRadical", content, hideDegree: true };
+}
+/** Create a math nth root. */
+export function mathRoot(degree, content) {
+    return { type: "mathRadical", degree, content };
+}
+/** Create a math summation. */
+export function mathSum(content, sub, sup) {
+    return { type: "mathNary", char: "\u2211", sub, sup, content };
+}
+/** Create a math integral. */
+export function mathIntegral(content, sub, sup) {
+    return { type: "mathNary", char: "\u222B", sub, sup, content };
+}
+/** Create a math product. */
+export function mathProduct(content, sub, sup) {
+    return { type: "mathNary", char: "\u220F", sub, sup, content };
+}
+/** Create a math superscript. */
+export function mathSuperScript(base, superScript) {
+    return { type: "mathSuperScript", base, superScript };
+}
+/** Create a math subscript. */
+export function mathSubScript(base, subScript) {
+    return { type: "mathSubScript", base, subScript };
+}
+/** Create a math sub-superscript. */
+export function mathSubSuperScript(base, subScript, superScript) {
+    return { type: "mathSubSuperScript", base, subScript, superScript };
+}
+/** Create a math pre-sub-superscript (subscript/superscript before the base). */
+export function mathPreSubSuperScript(base, preSubScript, preSuperScript) {
+    return { type: "mathPreSubSuperScript", base, preSubScript, preSuperScript };
+}
+/** Create a math phantom (invisible expression that takes up space). */
+export function mathPhantom(content, options) {
+    return { type: "mathPhantom", content, ...options };
+}
+/** Create a math group character (e.g. a horizontal brace over an expression). */
+export function mathGroupChar(base, options) {
+    return { type: "mathGroupChar", base, ...options };
+}
+/** Create a math border box (draw borders around / strike through an expression). */
+export function mathBorderBox(content, options) {
+    return { type: "mathBorderBox", content, ...options };
+}
+/** Create a math delimiter (parentheses, brackets, etc.). */
+export function mathDelimiter(content, options) {
+    return {
+        type: "mathDelimiter",
+        beginChar: options?.beginChar,
+        endChar: options?.endChar,
+        separatorChar: options?.separatorChar,
+        content
+    };
+}
+/** Create a math n-ary operator (sum, integral, product, etc.). */
+export function mathNary(char, content, sub, sup) {
+    return { type: "mathNary", char, sub, sup, content };
+}
+/** Create a math function (sin, cos, lim, etc.). */
+export function mathFunction(name, content) {
+    return { type: "mathFunction", name, content };
+}
+/** Create a math limit (upper or lower). */
+export function mathLimit(base, limit, limitType = "lower") {
+    return { type: "mathLimit", base, limit, limitType };
+}
+/** Create a math matrix. */
+export function mathMatrix(rows) {
+    return { type: "mathMatrix", rows };
+}
+/** Create a math accent (hat, tilde, etc.). */
+export function mathAccent(content, char) {
+    return { type: "mathAccent", content, char };
+}
+/** Create a math bar (overbar/underbar). */
+export function mathBar(content, position) {
+    return { type: "mathBar", content, position: position ?? "top" };
+}
+/** Create a math box. */
+export function mathBox(content) {
+    return { type: "mathBox", content };
+}
+/** Create a math equation array. */
+export function mathEquationArray(rows) {
+    return { type: "mathEquationArray", rows };
+}
+// =============================================================================
+// Symbol / Image / Shape / Chart / SDT / CheckBox Builders
+// =============================================================================
+/** Create a symbol run. */
+export function symbol(font, char, properties) {
+    return { properties, content: [{ type: "symbol", font, char }] };
+}
+/** Create a floating image (body-level). */
+export function floatingImage(options) {
+    return {
+        type: "floatingImage",
+        rId: options.rId,
+        width: options.width,
+        height: options.height,
+        horizontalPosition: options.horizontalPosition ?? { relativeTo: "column", offset: 0 },
+        verticalPosition: options.verticalPosition ?? { relativeTo: "paragraph", offset: 0 },
+        wrap: options.wrap ?? { style: "square" },
+        altText: options.altText,
+        name: options.name,
+        behindDoc: options.behindDoc,
+        lockAnchor: options.lockAnchor,
+        layoutInCell: options.layoutInCell,
+        allowOverlap: options.allowOverlap,
+        simplePos: options.simplePos,
+        distT: options.distT,
+        distB: options.distB,
+        distL: options.distL,
+        distR: options.distR,
+        rotation: options.rotation,
+        flipHorizontal: options.flipHorizontal,
+        flipVertical: options.flipVertical,
+        srcRect: options.srcRect
+    };
+}
+/** Create a DrawingML shape. */
+export function drawingShape(options) {
+    return {
+        type: "drawingShape",
+        shapeType: options.shapeType,
+        width: options.width,
+        height: options.height,
+        fillColor: options.fillColor,
+        noFill: options.noFill,
+        outlineColor: options.outlineColor,
+        outlineWidth: options.outlineWidth,
+        noOutline: options.noOutline,
+        textContent: options.textContent,
+        altText: options.altText,
+        name: options.name,
+        horizontalPosition: options.horizontalPosition ?? { relativeTo: "column", offset: 0 },
+        verticalPosition: options.verticalPosition ?? { relativeTo: "paragraph", offset: 0 },
+        wrap: options.wrap ?? { style: "square" },
+        behindDoc: options.behindDoc,
+        rotation: options.rotation
+    };
+}
+/** Create a chart content block. */
+export function chart(options) {
+    return {
+        type: "chart",
+        chart: {
+            type: options.type,
+            series: options.series,
+            title: options.title,
+            legend: options.legend,
+            categoryAxis: options.categoryAxis,
+            valueAxis: options.valueAxis,
+            plotAreaColor: options.plotAreaColor,
+            chartAreaColor: options.chartAreaColor,
+            view3d: options.view3d,
+            style: options.style,
+            width: options.width,
+            height: options.height
+        },
+        altText: options.altText,
+        name: options.name
+    };
+}
+/** Create a structured document tag (content control). */
+export function structuredDocumentTag(content, properties) {
+    return { type: "sdt", properties: properties ?? {}, content };
+}
+/** Create a checkbox. */
+export function checkBox(options) {
+    return {
+        type: "checkBox",
+        checked: options?.checked,
+        checkedState: options?.checkedState,
+        uncheckedState: options?.uncheckedState
+    };
+}