@cj-tech-master/excelts 9.5.4 → 9.5.5

package/dist/cjs/modules/word/builder/run-builders.js

@@ -0,0 +1,676 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.text = text;
+exports.bold = bold;
+exports.italic = italic;
+exports.underline = underline;
+exports.strikethrough = strikethrough;
+exports.pageBreak = pageBreak;
+exports.lineBreak = lineBreak;
+exports.columnBreak = columnBreak;
+exports.tab = tab;
+exports.positionalTab = positionalTab;
+exports.ruby = ruby;
+exports.carriageReturn = carriageReturn;
+exports.noBreakHyphen = noBreakHyphen;
+exports.softHyphen = softHyphen;
+exports.field = field;
+exports.pageNumberField = pageNumberField;
+exports.totalPagesField = totalPagesField;
+exports.sectionPagesField = sectionPagesField;
+exports.sectionField = sectionField;
+exports.dateField = dateField;
+exports.sequenceField = sequenceField;
+exports.timeField = timeField;
+exports.authorField = authorField;
+exports.titleField = titleField;
+exports.subjectField = subjectField;
+exports.keywordsField = keywordsField;
+exports.fileNameField = fileNameField;
+exports.fileSizeField = fileSizeField;
+exports.styleRefField = styleRefField;
+exports.refField = refField;
+exports.pageRefField = pageRefField;
+exports.noteRefField = noteRefField;
+exports.hyperlinkField = hyperlinkField;
+exports.quoteField = quoteField;
+exports.tocField = tocField;
+exports.tcField = tcField;
+exports.indexEntryField = indexEntryField;
+exports.indexField = indexField;
+exports.ifField = ifField;
+exports.includeTextField = includeTextField;
+exports.includePictureField = includePictureField;
+exports.formTextField = formTextField;
+exports.formCheckboxField = formCheckboxField;
+exports.formDropdownField = formDropdownField;
+exports.mathBlock = mathBlock;
+exports.mathRun = mathRun;
+exports.mathFraction = mathFraction;
+exports.mathSqrt = mathSqrt;
+exports.mathRoot = mathRoot;
+exports.mathSum = mathSum;
+exports.mathIntegral = mathIntegral;
+exports.mathProduct = mathProduct;
+exports.mathSuperScript = mathSuperScript;
+exports.mathSubScript = mathSubScript;
+exports.mathSubSuperScript = mathSubSuperScript;
+exports.mathPreSubSuperScript = mathPreSubSuperScript;
+exports.mathPhantom = mathPhantom;
+exports.mathGroupChar = mathGroupChar;
+exports.mathBorderBox = mathBorderBox;
+exports.mathDelimiter = mathDelimiter;
+exports.mathNary = mathNary;
+exports.mathFunction = mathFunction;
+exports.mathLimit = mathLimit;
+exports.mathMatrix = mathMatrix;
+exports.mathAccent = mathAccent;
+exports.mathBar = mathBar;
+exports.mathBox = mathBox;
+exports.mathEquationArray = mathEquationArray;
+exports.symbol = symbol;
+exports.floatingImage = floatingImage;
+exports.drawingShape = drawingShape;
+exports.chart = chart;
+exports.structuredDocumentTag = structuredDocumentTag;
+exports.checkBox = checkBox;
+// =============================================================================
+// Run Builders
+// =============================================================================
+/** Create a text run. */
+function text(content, properties) {
+    return { properties, content: [{ type: "text", text: content }] };
+}
+/** Create a bold text run. */
+function bold(content, properties) {
+    return text(content, { ...properties, bold: true });
+}
+/** Create an italic text run. */
+function italic(content, properties) {
+    return text(content, { ...properties, italic: true });
+}
+/** Create an underlined text run. */
+function underline(content, style, properties) {
+    return text(content, { ...properties, underline: style ?? "single" });
+}
+/** Create a strikethrough text run. */
+function strikethrough(content, properties) {
+    return text(content, { ...properties, strike: true });
+}
+/** Create a run with a page break. */
+function pageBreak() {
+    return { content: [{ type: "break", breakType: "page" }] };
+}
+/** Create a run with a line break. */
+function lineBreak() {
+    return { content: [{ type: "break" }] };
+}
+/** Create a run with a column break. */
+function columnBreak() {
+    return { content: [{ type: "break", breakType: "column" }] };
+}
+/** Create a tab run. */
+function tab() {
+    return { content: [{ type: "tab" }] };
+}
+/** Create a positional tab (w:ptab). */
+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).
+ */
+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. */
+function carriageReturn() {
+    return { content: [{ type: "carriageReturn" }] };
+}
+/** Create a no-break hyphen run. */
+function noBreakHyphen() {
+    return { content: [{ type: "noBreakHyphen" }] };
+}
+/** Create a soft hyphen run. */
+function softHyphen() {
+    return { content: [{ type: "softHyphen" }] };
+}
+/** Create a run with a field code. */
+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). */
+function pageNumberField(cachedValue) {
+    return simpleField("PAGE", cachedValue ?? "1");
+}
+/** Create a NUMPAGES field (total page count). */
+function totalPagesField(cachedValue) {
+    return simpleField("NUMPAGES", cachedValue ?? "1");
+}
+/** Create a SECTIONPAGES field (pages in section). */
+function sectionPagesField(cachedValue) {
+    return simpleField("SECTIONPAGES", cachedValue ?? "1");
+}
+/** Create a SECTION field (current section number). */
+function sectionField(cachedValue) {
+    return simpleField("SECTION", cachedValue ?? "1");
+}
+/** Create a DATE field. */
+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. */
+function sequenceField(identifier, options) {
+    let instruction = ` SEQ ${identifier} `;
+    if (options?.hide) {
+        instruction += "\\h ";
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create a TIME field (current time). */
+function timeField(format, cachedValue) {
+    const fmt = format ?? "HH:mm:ss";
+    return field(` TIME \\@ "${fmt}" `, cachedValue);
+}
+/** Create an AUTHOR field. */
+function authorField(cachedValue) {
+    return simpleField("AUTHOR", cachedValue);
+}
+/** Create a TITLE field. */
+function titleField(cachedValue) {
+    return simpleField("TITLE", cachedValue);
+}
+/** Create a SUBJECT field. */
+function subjectField(cachedValue) {
+    return simpleField("SUBJECT", cachedValue);
+}
+/** Create a KEYWORDS field. */
+function keywordsField(cachedValue) {
+    return simpleField("KEYWORDS", cachedValue);
+}
+/** Create a FILENAME field. */
+function fileNameField(options) {
+    const instruction = options?.includePath ? " FILENAME \\p " : " FILENAME ";
+    return field(instruction, options?.cachedValue);
+}
+/** Create a FILESIZE field. */
+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.
+ */
+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).
+ */
+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). */
+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). */
+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). */
+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). */
+function quoteField(text, cachedValue) {
+    return field(` QUOTE "${text}" `, cachedValue ?? text);
+}
+/**
+ * Create a TOC field for table of contents.
+ *
+ * @param options - TOC options.
+ */
+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. */
+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. */
+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). */
+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). */
+function ifField(condition, trueText, falseText, cachedValue) {
+    return field(` IF ${condition} "${trueText}" "${falseText}" `, cachedValue);
+}
+/** Create an INCLUDETEXT field (includes external file content). */
+function includeTextField(filePath, options) {
+    let instruction = ` INCLUDETEXT "${filePath}" `;
+    if (options?.bookmark) {
+        instruction += `${options.bookmark} `;
+    }
+    return field(instruction, options?.cachedValue);
+}
+/** Create an INCLUDEPICTURE field. */
+function includePictureField(filePath, cachedValue) {
+    return field(` INCLUDEPICTURE "${filePath}" `, cachedValue);
+}
+/** Create a FORMTEXT field (legacy text form field) with full properties. */
+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. */
+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. */
+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. */
+function mathBlock(content) {
+    return { type: "math", content };
+}
+/** Create a math text run. */
+function mathRun(mathText, properties) {
+    return { type: "mathRun", text: mathText, properties };
+}
+/** Create a math fraction. */
+function mathFraction(numerator, denominator, fractionType) {
+    return { type: "mathFraction", fractionType, numerator, denominator };
+}
+/** Create a math square root. */
+function mathSqrt(content) {
+    return { type: "mathRadical", content, hideDegree: true };
+}
+/** Create a math nth root. */
+function mathRoot(degree, content) {
+    return { type: "mathRadical", degree, content };
+}
+/** Create a math summation. */
+function mathSum(content, sub, sup) {
+    return { type: "mathNary", char: "\u2211", sub, sup, content };
+}
+/** Create a math integral. */
+function mathIntegral(content, sub, sup) {
+    return { type: "mathNary", char: "\u222B", sub, sup, content };
+}
+/** Create a math product. */
+function mathProduct(content, sub, sup) {
+    return { type: "mathNary", char: "\u220F", sub, sup, content };
+}
+/** Create a math superscript. */
+function mathSuperScript(base, superScript) {
+    return { type: "mathSuperScript", base, superScript };
+}
+/** Create a math subscript. */
+function mathSubScript(base, subScript) {
+    return { type: "mathSubScript", base, subScript };
+}
+/** Create a math sub-superscript. */
+function mathSubSuperScript(base, subScript, superScript) {
+    return { type: "mathSubSuperScript", base, subScript, superScript };
+}
+/** Create a math pre-sub-superscript (subscript/superscript before the base). */
+function mathPreSubSuperScript(base, preSubScript, preSuperScript) {
+    return { type: "mathPreSubSuperScript", base, preSubScript, preSuperScript };
+}
+/** Create a math phantom (invisible expression that takes up space). */
+function mathPhantom(content, options) {
+    return { type: "mathPhantom", content, ...options };
+}
+/** Create a math group character (e.g. a horizontal brace over an expression). */
+function mathGroupChar(base, options) {
+    return { type: "mathGroupChar", base, ...options };
+}
+/** Create a math border box (draw borders around / strike through an expression). */
+function mathBorderBox(content, options) {
+    return { type: "mathBorderBox", content, ...options };
+}
+/** Create a math delimiter (parentheses, brackets, etc.). */
+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.). */
+function mathNary(char, content, sub, sup) {
+    return { type: "mathNary", char, sub, sup, content };
+}
+/** Create a math function (sin, cos, lim, etc.). */
+function mathFunction(name, content) {
+    return { type: "mathFunction", name, content };
+}
+/** Create a math limit (upper or lower). */
+function mathLimit(base, limit, limitType = "lower") {
+    return { type: "mathLimit", base, limit, limitType };
+}
+/** Create a math matrix. */
+function mathMatrix(rows) {
+    return { type: "mathMatrix", rows };
+}
+/** Create a math accent (hat, tilde, etc.). */
+function mathAccent(content, char) {
+    return { type: "mathAccent", content, char };
+}
+/** Create a math bar (overbar/underbar). */
+function mathBar(content, position) {
+    return { type: "mathBar", content, position: position ?? "top" };
+}
+/** Create a math box. */
+function mathBox(content) {
+    return { type: "mathBox", content };
+}
+/** Create a math equation array. */
+function mathEquationArray(rows) {
+    return { type: "mathEquationArray", rows };
+}
+// =============================================================================
+// Symbol / Image / Shape / Chart / SDT / CheckBox Builders
+// =============================================================================
+/** Create a symbol run. */
+function symbol(font, char, properties) {
+    return { properties, content: [{ type: "symbol", font, char }] };
+}
+/** Create a floating image (body-level). */
+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. */
+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. */
+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). */
+function structuredDocumentTag(content, properties) {
+    return { type: "sdt", properties: properties ?? {}, content };
+}
+/** Create a checkbox. */
+function checkBox(options) {
+    return {
+        type: "checkBox",
+        checked: options?.checked,
+        checkedState: options?.checkedState,
+        uncheckedState: options?.uncheckedState
+    };
+}