@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/browser/modules/word/writers/run-writer.js

@@ -0,0 +1,649 @@
+/**
+ * DOCX Writers - Run Properties & Run Content
+ *
+ * Renders w:rPr and run-level content (w:t, w:br, w:tab, w:drawing, etc.)
+ */
+import { NS_A, NS_PIC, URI_PIC, NS_ASVG, GUID_SVG } from "../constants.js";
+/** Render a single border element. */
+export function renderBorderElement(xml, tagName, border) {
+    const attrs = { "w:val": border.style };
+    if (border.size !== undefined) {
+        attrs["w:sz"] = String(border.size);
+    }
+    if (border.space !== undefined) {
+        attrs["w:space"] = String(border.space);
+    }
+    if (border.color) {
+        attrs["w:color"] = border.color;
+    }
+    if (border.themeColor) {
+        attrs["w:themeColor"] = border.themeColor;
+    }
+    if (border.shadow) {
+        attrs["w:shadow"] = "1";
+    }
+    if (border.frame) {
+        attrs["w:frame"] = "1";
+    }
+    // Artistic border (page borders only)
+    if (border.art) {
+        attrs["w:art"] = border.art;
+    }
+    xml.leafNode(tagName, attrs);
+}
+/** Render w:rPr (run properties). Element order follows ECMA-376 CT_RPr schema. */
+export function renderRunProperties(xml, rPr, insidePropertyChange = false) {
+    xml.openNode("w:rPr");
+    // 1. rStyle
+    if (rPr.style) {
+        xml.leafNode("w:rStyle", { "w:val": rPr.style });
+    }
+    // 2. rFonts
+    if (rPr.font) {
+        if (typeof rPr.font === "string") {
+            xml.leafNode("w:rFonts", { "w:ascii": rPr.font, "w:hAnsi": rPr.font });
+        }
+        else {
+            const f = rPr.font;
+            const attrs = {};
+            if (f.ascii) {
+                attrs["w:ascii"] = f.ascii;
+            }
+            if (f.hAnsi) {
+                attrs["w:hAnsi"] = f.hAnsi;
+            }
+            if (f.eastAsia) {
+                attrs["w:eastAsia"] = f.eastAsia;
+            }
+            if (f.cs) {
+                attrs["w:cs"] = f.cs;
+            }
+            if (f.hint) {
+                attrs["w:hint"] = f.hint;
+            }
+            if (f.asciiTheme) {
+                attrs["w:asciiTheme"] = f.asciiTheme;
+            }
+            if (f.hAnsiTheme) {
+                attrs["w:hAnsiTheme"] = f.hAnsiTheme;
+            }
+            if (f.eastAsiaTheme) {
+                attrs["w:eastAsiaTheme"] = f.eastAsiaTheme;
+            }
+            if (f.cstheme) {
+                attrs["w:cstheme"] = f.cstheme;
+            }
+            xml.leafNode("w:rFonts", attrs);
+        }
+    }
+    // 3. b, bCs
+    if (rPr.bold !== undefined) {
+        xml.leafNode("w:b", !rPr.bold ? { "w:val": "0" } : undefined);
+    }
+    if (rPr.boldCs !== undefined) {
+        xml.leafNode("w:bCs", !rPr.boldCs ? { "w:val": "0" } : undefined);
+    }
+    // 4. i, iCs
+    if (rPr.italic !== undefined) {
+        xml.leafNode("w:i", !rPr.italic ? { "w:val": "0" } : undefined);
+    }
+    if (rPr.italicCs !== undefined) {
+        xml.leafNode("w:iCs", !rPr.italicCs ? { "w:val": "0" } : undefined);
+    }
+    // 5. caps, smallCaps
+    if (rPr.caps) {
+        xml.leafNode("w:caps");
+    }
+    if (rPr.smallCaps) {
+        xml.leafNode("w:smallCaps");
+    }
+    // 6. strike, dstrike
+    if (rPr.strike) {
+        xml.leafNode("w:strike");
+    }
+    if (rPr.doubleStrike) {
+        xml.leafNode("w:dstrike");
+    }
+    // 7. outline, shadow, emboss, imprint (outline effects)
+    if (rPr.outline) {
+        xml.leafNode("w:outline");
+    }
+    if (rPr.shadow) {
+        xml.leafNode("w:shadow");
+    }
+    if (rPr.emboss) {
+        xml.leafNode("w:emboss");
+    }
+    if (rPr.imprint) {
+        xml.leafNode("w:imprint");
+    }
+    // 8. noProof
+    if (rPr.noProof) {
+        xml.leafNode("w:noProof");
+    }
+    // 9. snapToGrid
+    if (rPr.snapToGrid !== undefined) {
+        xml.leafNode("w:snapToGrid", !rPr.snapToGrid ? { "w:val": "0" } : undefined);
+    }
+    // 10. vanish, webHidden
+    if (rPr.vanish) {
+        xml.leafNode("w:vanish");
+    }
+    if (rPr.webHidden) {
+        xml.leafNode("w:webHidden");
+    }
+    // 11. color
+    if (rPr.color) {
+        if (typeof rPr.color === "string") {
+            xml.leafNode("w:color", { "w:val": rPr.color });
+        }
+        else {
+            const spec = rPr.color;
+            const attrs = { "w:val": spec.val };
+            if (spec.themeColor) {
+                attrs["w:themeColor"] = spec.themeColor;
+            }
+            if (spec.themeTint) {
+                attrs["w:themeTint"] = spec.themeTint;
+            }
+            if (spec.themeShade) {
+                attrs["w:themeShade"] = spec.themeShade;
+            }
+            xml.leafNode("w:color", attrs);
+        }
+    }
+    // 12. spacing, w (scale), kern, position
+    if (rPr.spacing !== undefined) {
+        xml.leafNode("w:spacing", { "w:val": String(rPr.spacing) });
+    }
+    if (rPr.scale !== undefined) {
+        xml.leafNode("w:w", { "w:val": String(rPr.scale) });
+    }
+    if (rPr.kern !== undefined) {
+        xml.leafNode("w:kern", { "w:val": String(rPr.kern) });
+    }
+    if (rPr.position !== undefined) {
+        xml.leafNode("w:position", { "w:val": String(rPr.position) });
+    }
+    // 13. sz, szCs
+    if (rPr.size !== undefined) {
+        xml.leafNode("w:sz", { "w:val": String(rPr.size) });
+    }
+    if (rPr.sizeCs !== undefined) {
+        xml.leafNode("w:szCs", { "w:val": String(rPr.sizeCs) });
+    }
+    // 14. highlight
+    if (rPr.highlight) {
+        xml.leafNode("w:highlight", { "w:val": rPr.highlight });
+    }
+    // 15. u (underline)
+    if (rPr.underline !== undefined) {
+        if (typeof rPr.underline === "boolean") {
+            xml.leafNode("w:u", { "w:val": rPr.underline ? "single" : "none" });
+        }
+        else if (typeof rPr.underline === "string") {
+            xml.leafNode("w:u", { "w:val": rPr.underline });
+        }
+        else {
+            const spec = rPr.underline;
+            const attrs = { "w:val": spec.style };
+            if (spec.color) {
+                attrs["w:color"] = spec.color;
+            }
+            xml.leafNode("w:u", attrs);
+        }
+    }
+    // 16. effect (text animation)
+    if (rPr.effect) {
+        xml.leafNode("w:effect", { "w:val": rPr.effect });
+    }
+    // 17. bdr (character border)
+    if (rPr.border) {
+        renderBorderElement(xml, "w:bdr", rPr.border);
+    }
+    // 18. shd
+    if (rPr.shading) {
+        renderShading(xml, rPr.shading);
+    }
+    // 19. fitText
+    if (rPr.fitText) {
+        const attrs = { "w:val": String(rPr.fitText.val) };
+        if (rPr.fitText.id !== undefined) {
+            attrs["w:id"] = String(rPr.fitText.id);
+        }
+        xml.leafNode("w:fitText", attrs);
+    }
+    // 20. vertAlign
+    if (rPr.vertAlign) {
+        xml.leafNode("w:vertAlign", { "w:val": rPr.vertAlign });
+    }
+    // 21. rtl
+    if (rPr.rightToLeft) {
+        xml.leafNode("w:rtl");
+    }
+    // 22. cs (complex script toggle)
+    if (rPr.complexScript) {
+        xml.leafNode("w:cs");
+    }
+    // 23. em (emphasis mark)
+    if (rPr.emphasisMark) {
+        xml.leafNode("w:em", { "w:val": rPr.emphasisMark });
+    }
+    // 24. lang
+    if (rPr.language) {
+        const attrs = {};
+        if (rPr.language.val) {
+            attrs["w:val"] = rPr.language.val;
+        }
+        if (rPr.language.eastAsia) {
+            attrs["w:eastAsia"] = rPr.language.eastAsia;
+        }
+        if (rPr.language.bidi) {
+            attrs["w:bidi"] = rPr.language.bidi;
+        }
+        xml.leafNode("w:lang", attrs);
+    }
+    // 25. eastAsianLayout (not yet supported; placeholder)
+    // 26. specVanish
+    if (rPr.specVanish) {
+        xml.leafNode("w:specVanish");
+    }
+    // 27. oMath
+    if (rPr.math) {
+        xml.leafNode("w:oMath");
+    }
+    // 28. rPrChange (track changes) — always last; NOT recursed into when rendering previousProperties
+    if (!insidePropertyChange && rPr.propertyChange) {
+        const rev = rPr.propertyChange.revision;
+        const attrs = {
+            "w:id": String(rev.id),
+            "w:author": rev.author
+        };
+        if (rev.date) {
+            attrs["w:date"] = rev.date;
+        }
+        xml.openNode("w:rPrChange", attrs);
+        if (rPr.propertyChange.previousProperties) {
+            renderRunProperties(xml, rPr.propertyChange.previousProperties, true);
+        }
+        else {
+            xml.openNode("w:rPr");
+            xml.closeNode();
+        }
+        xml.closeNode();
+    }
+    xml.closeNode();
+}
+/** Render w:shd element. */
+export function renderShading(xml, shd) {
+    xml.leafNode("w:shd", {
+        "w:val": shd.pattern ?? "clear",
+        "w:color": shd.color ?? "auto",
+        "w:fill": shd.fill
+    });
+}
+/** Render an inline image (w:drawing > wp:inline). */
+function renderInlineImage(xml, img) {
+    const drawingId = img.drawingId ?? 1;
+    const name = img.name ?? "Picture";
+    xml.openNode("w:drawing");
+    xml.openNode("wp:inline", {
+        distT: "0",
+        distB: "0",
+        distL: "0",
+        distR: "0"
+    });
+    xml.leafNode("wp:extent", { cx: String(img.width), cy: String(img.height) });
+    xml.leafNode("wp:effectExtent", { l: "0", t: "0", r: "0", b: "0" });
+    xml.leafNode("wp:docPr", {
+        id: String(drawingId),
+        name,
+        ...(img.altText ? { descr: img.altText } : {})
+    });
+    xml.openNode("wp:cNvGraphicFramePr");
+    xml.leafNode("a:graphicFrameLocks", { "xmlns:a": NS_A, noChangeAspect: "1" });
+    xml.closeNode();
+    xml.openNode("a:graphic", { "xmlns:a": NS_A });
+    xml.openNode("a:graphicData", { uri: URI_PIC });
+    xml.openNode("pic:pic", { "xmlns:pic": NS_PIC });
+    // nvPicPr
+    xml.openNode("pic:nvPicPr");
+    xml.leafNode("pic:cNvPr", { id: String(drawingId), name });
+    xml.leafNode("pic:cNvPicPr");
+    xml.closeNode();
+    // blipFill
+    xml.openNode("pic:blipFill");
+    if (img.svgRId) {
+        xml.openNode("a:blip", { "r:embed": img.rId });
+        xml.openNode("a:extLst");
+        xml.openNode("a:ext", { uri: GUID_SVG });
+        xml.leafNode("asvg:svgBlip", {
+            "xmlns:asvg": NS_ASVG,
+            "r:embed": img.svgRId
+        });
+        xml.closeNode(); // a:ext
+        xml.closeNode(); // a:extLst
+        xml.closeNode(); // a:blip
+    }
+    else {
+        xml.leafNode("a:blip", { "r:embed": img.rId });
+    }
+    // Source rectangle (crop)
+    if (img.srcRect) {
+        const sr = img.srcRect;
+        const srAttrs = {};
+        if (sr.l !== undefined) {
+            srAttrs["l"] = String(sr.l);
+        }
+        if (sr.t !== undefined) {
+            srAttrs["t"] = String(sr.t);
+        }
+        if (sr.r !== undefined) {
+            srAttrs["r"] = String(sr.r);
+        }
+        if (sr.b !== undefined) {
+            srAttrs["b"] = String(sr.b);
+        }
+        xml.leafNode("a:srcRect", srAttrs);
+    }
+    xml.openNode("a:stretch");
+    xml.leafNode("a:fillRect");
+    xml.closeNode();
+    xml.closeNode();
+    // spPr
+    xml.openNode("pic:spPr");
+    // Transform with optional rotation/flip
+    const xfrmAttrs = {};
+    if (img.rotation) {
+        xfrmAttrs["rot"] = String(img.rotation);
+    }
+    if (img.flipHorizontal) {
+        xfrmAttrs["flipH"] = "1";
+    }
+    if (img.flipVertical) {
+        xfrmAttrs["flipV"] = "1";
+    }
+    xml.openNode("a:xfrm", Object.keys(xfrmAttrs).length > 0 ? xfrmAttrs : undefined);
+    xml.leafNode("a:off", { x: "0", y: "0" });
+    xml.leafNode("a:ext", { cx: String(img.width), cy: String(img.height) });
+    xml.closeNode();
+    xml.openNode("a:prstGeom", { prst: "rect" });
+    xml.leafNode("a:avLst");
+    xml.closeNode();
+    // Outline
+    if (img.outline) {
+        const lnAttrs = {};
+        if (img.outline.width !== undefined) {
+            lnAttrs["w"] = String(img.outline.width);
+        }
+        xml.openNode("a:ln", Object.keys(lnAttrs).length > 0 ? lnAttrs : undefined);
+        if (img.outline.color) {
+            xml.openNode("a:solidFill");
+            xml.leafNode("a:srgbClr", { val: img.outline.color });
+            xml.closeNode();
+        }
+        xml.closeNode();
+    }
+    xml.closeNode(); // pic:spPr
+    xml.closeNode(); // pic:pic
+    xml.closeNode(); // a:graphicData
+    xml.closeNode(); // a:graphic
+    xml.closeNode(); // wp:inline
+    xml.closeNode(); // w:drawing
+}
+/** Render w:ffData element for legacy form fields. */
+function renderFfData(xml, ff) {
+    xml.openNode("w:ffData");
+    if (ff.name) {
+        xml.leafNode("w:name", { "w:val": ff.name });
+    }
+    if (ff.type !== "checkBox" && ff.enabled !== undefined) {
+        xml.leafNode("w:enabled", ff.enabled ? undefined : { "w:val": "0" });
+    }
+    if (ff.type === "text") {
+        xml.openNode("w:textInput");
+        if (ff.default !== undefined) {
+            xml.leafNode("w:default", { "w:val": ff.default });
+        }
+        if (ff.maxLength !== undefined) {
+            xml.leafNode("w:maxLength", { "w:val": String(ff.maxLength) });
+        }
+        if (ff.format) {
+            xml.leafNode("w:format", { "w:val": ff.format });
+        }
+        xml.closeNode();
+        if (ff.helpText) {
+            xml.leafNode("w:helpText", { "w:type": "text", "w:val": ff.helpText });
+        }
+        if (ff.statusText) {
+            xml.leafNode("w:statusText", { "w:type": "text", "w:val": ff.statusText });
+        }
+    }
+    else if (ff.type === "checkBox") {
+        xml.openNode("w:checkBox");
+        if (ff.size !== undefined) {
+            xml.leafNode("w:size", { "w:val": String(ff.size) });
+        }
+        else {
+            xml.leafNode("w:sizeAuto");
+        }
+        if (ff.default !== undefined) {
+            xml.leafNode("w:default", { "w:val": ff.default ? "1" : "0" });
+        }
+        if (ff.checked !== undefined) {
+            xml.leafNode("w:checked", { "w:val": ff.checked ? "1" : "0" });
+        }
+        xml.closeNode();
+    }
+    else if (ff.type === "dropDown") {
+        xml.openNode("w:ddList");
+        if (ff.default !== undefined) {
+            xml.leafNode("w:default", { "w:val": String(ff.default) });
+        }
+        if (ff.entries) {
+            for (const entry of ff.entries) {
+                xml.leafNode("w:listEntry", { "w:val": entry });
+            }
+        }
+        xml.closeNode();
+        if (ff.helpText) {
+            xml.leafNode("w:helpText", { "w:type": "text", "w:val": ff.helpText });
+        }
+        if (ff.statusText) {
+            xml.leafNode("w:statusText", { "w:type": "text", "w:val": ff.statusText });
+        }
+    }
+    xml.closeNode(); // ffData
+}
+/** Render a field code (PAGE, NUMPAGES, etc.). */
+function renderField(xml, field) {
+    // Begin
+    xml.openNode("w:r");
+    if (field.formField) {
+        xml.openNode("w:fldChar", { "w:fldCharType": "begin" });
+        renderFfData(xml, field.formField);
+        xml.closeNode();
+    }
+    else {
+        xml.leafNode("w:fldChar", { "w:fldCharType": "begin" });
+    }
+    xml.closeNode();
+    // Instruction
+    xml.openNode("w:r");
+    xml.openNode("w:instrText", { "xml:space": "preserve" });
+    xml.writeText(field.instruction);
+    xml.closeNode();
+    xml.closeNode();
+    // Separate
+    xml.openNode("w:r");
+    xml.leafNode("w:fldChar", { "w:fldCharType": "separate" });
+    xml.closeNode();
+    // Cached value
+    if (field.cachedValue !== undefined) {
+        xml.openNode("w:r");
+        xml.openNode("w:t");
+        xml.writeText(field.cachedValue);
+        xml.closeNode();
+        xml.closeNode();
+    }
+    // End
+    xml.openNode("w:r");
+    xml.leafNode("w:fldChar", { "w:fldCharType": "end" });
+    xml.closeNode();
+}
+/** Render a single piece of run content. Returns true if rendered inside a w:r, false if it creates its own runs. */
+function renderRunContent(xml, content) {
+    switch (content.type) {
+        case "text":
+            xml.openNode("w:t", { "xml:space": "preserve" });
+            xml.writeText(content.text);
+            xml.closeNode();
+            return true;
+        case "break":
+            if (content.breakType) {
+                xml.leafNode("w:br", { "w:type": content.breakType });
+            }
+            else {
+                xml.leafNode("w:br");
+            }
+            return true;
+        case "tab":
+            xml.leafNode("w:tab");
+            return true;
+        case "ptab": {
+            const ptabAttrs = {
+                "w:alignment": content.alignment,
+                "w:relativeTo": content.relativeTo
+            };
+            if (content.leader) {
+                ptabAttrs["w:leader"] = content.leader;
+            }
+            xml.leafNode("w:ptab", ptabAttrs);
+            return true;
+        }
+        case "ruby": {
+            xml.openNode("w:ruby");
+            // Ruby properties
+            if (content.properties) {
+                xml.openNode("w:rubyPr");
+                const p = content.properties;
+                if (p.align) {
+                    xml.leafNode("w:rubyAlign", { "w:val": p.align });
+                }
+                if (p.fontSize !== undefined) {
+                    xml.leafNode("w:hps", { "w:val": String(p.fontSize) });
+                }
+                if (p.raise !== undefined) {
+                    xml.leafNode("w:hpsRaise", { "w:val": String(p.raise) });
+                }
+                if (p.baseFontSize !== undefined) {
+                    xml.leafNode("w:hpsBaseText", { "w:val": String(p.baseFontSize) });
+                }
+                if (p.language) {
+                    xml.leafNode("w:lid", { "w:val": p.language });
+                }
+                xml.closeNode();
+            }
+            // Ruby text (w:rt)
+            xml.openNode("w:rt");
+            for (const run of content.rubyText) {
+                renderRun(xml, run);
+            }
+            xml.closeNode();
+            // Base text (w:rubyBase)
+            xml.openNode("w:rubyBase");
+            for (const run of content.baseText) {
+                renderRun(xml, run);
+            }
+            xml.closeNode();
+            xml.closeNode(); // w:ruby
+            return true;
+        }
+        case "symbol":
+            xml.leafNode("w:sym", { "w:font": content.font, "w:char": content.char });
+            return true;
+        case "footnoteRef": {
+            const attrs = { "w:id": String(content.id) };
+            if (content.customMarkFollows) {
+                attrs["w:customMarkFollows"] = "1";
+            }
+            xml.leafNode("w:footnoteReference", attrs);
+            return true;
+        }
+        case "endnoteRef": {
+            const attrs = { "w:id": String(content.id) };
+            if (content.customMarkFollows) {
+                attrs["w:customMarkFollows"] = "1";
+            }
+            xml.leafNode("w:endnoteReference", attrs);
+            return true;
+        }
+        case "image":
+            renderInlineImage(xml, content);
+            return true;
+        case "field":
+            // Fields create their own runs — must be rendered outside the current run
+            return false;
+        case "carriageReturn":
+            xml.leafNode("w:cr");
+            return true;
+        case "noBreakHyphen":
+            xml.leafNode("w:noBreakHyphen");
+            return true;
+        case "softHyphen":
+            xml.leafNode("w:softHyphen");
+            return true;
+        case "lastRenderedPageBreak":
+            xml.leafNode("w:lastRenderedPageBreak");
+            return true;
+        case "annotationReference":
+            xml.leafNode("w:annotationRef");
+            return true;
+        case "dateField":
+            // Rendered as a field instruction
+            return false;
+        default:
+            return true;
+    }
+}
+/** Render a w:r element. */
+export function renderRun(xml, run) {
+    // Separate field content that needs its own runs
+    const normalContent = [];
+    const fieldContent = [];
+    for (const c of run.content) {
+        if (c.type === "field") {
+            fieldContent.push(c);
+        }
+        else if (c.type === "dateField") {
+            // Convert date field to field instruction
+            const fmt = c.format ?? "yyyy-MM-dd";
+            const lang = c.language ?? "en-US";
+            fieldContent.push({
+                type: "field",
+                instruction: ` DATE \\@ "${fmt}" \\l ${lang} `,
+                cachedValue: new Date().toISOString().split("T")[0]
+            });
+        }
+        else {
+            normalContent.push(c);
+        }
+    }
+    // Render normal content inside a single w:r
+    if (normalContent.length > 0) {
+        xml.openNode("w:r");
+        if (run.properties) {
+            renderRunProperties(xml, run.properties);
+        }
+        for (const content of normalContent) {
+            renderRunContent(xml, content);
+        }
+        xml.closeNode();
+    }
+    // Render field content (each field creates multiple runs)
+    for (const fc of fieldContent) {
+        if (fc.type === "field") {
+            renderField(xml, fc);
+        }
+    }
+}

package/dist/browser/modules/word/writers/section-writer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * DOCX Writers - Section Properties
+ *
+ * Renders w:sectPr element including page size, margins, columns,
+ * headers/footers, page numbering, page borders, vertical alignment, etc.
+ */
+import type { XmlSink } from "../../xml/types.js";
+import type { SectionProperties } from "../types.js";
+/** Render w:sectPr element. */
+export declare function renderSectionProperties(xml: XmlSink, sect: SectionProperties, insidePropertyChange?: boolean): void;