@js-ak/excel-toolbox 1.8.3 → 1.9.0

package/build/esm/lib/workbook-builder/utils/build-app-xml.js

@@ -0,0 +1,48 @@
+import { XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { buildXml } from "./build-xml.js";
+export function buildAppXml({ appVersion = "16.0300", application = "Microsoft Excel", company = "", hyperlinksChanged = false, linksUpToDate = false, sharedDoc = false, sheetNames = ["Sheet1"], } = {}) {
+    const app = {
+        attrs: {
+            xmlns: XML_NAMESPACES.EXTENDED_PROPERTIES,
+            "xmlns:vt": XML_NAMESPACES.DOC_PROPS_VTYPES,
+        },
+        children: [
+            { children: [application], tag: "Application" },
+            { children: ["0"], tag: "DocSecurity" },
+            { children: ["false"], tag: "ScaleCrop" },
+            {
+                children: [
+                    {
+                        attrs: { baseType: "variant", size: "2" },
+                        children: [
+                            { children: [{ children: ["Worksheets"], tag: "vt:lpstr" }], tag: "vt:variant" },
+                            { children: [{ children: [String(sheetNames.length)], tag: "vt:i4" }], tag: "vt:variant" },
+                        ],
+                        tag: "vt:vector",
+                    },
+                ],
+                tag: "HeadingPairs",
+            },
+            {
+                children: [
+                    {
+                        attrs: { baseType: "lpstr", size: String(sheetNames.length) },
+                        children: sheetNames.map((name) => ({ children: [name], tag: "vt:lpstr" })),
+                        tag: "vt:vector",
+                    },
+                ],
+                tag: "TitlesOfParts",
+            },
+            { children: [company], tag: "Company" },
+            { children: [String(linksUpToDate)], tag: "LinksUpToDate" },
+            { children: [String(sharedDoc)], tag: "SharedDoc" },
+            { children: [String(hyperlinksChanged)], tag: "HyperlinksChanged" },
+            { children: [appVersion], tag: "AppVersion" },
+        ],
+        tag: "Properties",
+    };
+    return [
+        XML_DECLARATION,
+        buildXml(app),
+    ].join("\n");
+}

package/build/esm/lib/workbook-builder/utils/build-cell-children.js

@@ -0,0 +1,56 @@
+/**
+ * Builds XML children nodes for a cell based on its type and value.
+ *
+ * @param cell - The cell data containing value and type information
+ *
+ * @returns Array of XML nodes representing the cell's content structure
+ */
+export function buildCellChildren(cell) {
+    if (cell.value === undefined) {
+        return [];
+    }
+    if (cell.isFormula) {
+        return [
+            {
+                children: [String(cell.value)],
+                tag: "f",
+            },
+        ];
+    }
+    switch (cell.type) {
+        case "b": {
+            return [
+                {
+                    children: [cell.value ? "1" : "0"],
+                    tag: "v",
+                },
+            ];
+        }
+        case "inlineStr": {
+            // For inlineStr, wrap value in <is><t>value</t></is>
+            return [
+                {
+                    children: [
+                        {
+                            children: [String(cell.value)],
+                            tag: "t",
+                        },
+                    ],
+                    tag: "is",
+                },
+            ];
+        }
+        case "s":
+        case "n":
+        case "str":
+        case "e":
+        default: {
+            return [
+                {
+                    children: [String(cell.value)],
+                    tag: "v",
+                },
+            ];
+        }
+    }
+}

package/build/esm/lib/workbook-builder/utils/build-content-types-xml.js

@@ -0,0 +1,39 @@
+import { CONTENT_TYPES, XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { buildXml } from "./build-xml.js";
+export function buildContentTypesXml(sheetsCount) {
+    const defaults = [
+        { ContentType: CONTENT_TYPES.RELATIONSHIPS, Extension: "rels" },
+        { ContentType: CONTENT_TYPES.XML, Extension: "xml" },
+    ].map(({ ContentType, Extension }) => ({
+        attrs: { ContentType, Extension },
+        tag: "Default",
+    }));
+    const overrides = [
+        { ContentType: CONTENT_TYPES.THEME, PartName: "/xl/theme/theme1.xml" },
+        { ContentType: CONTENT_TYPES.WORKBOOK, PartName: "/xl/workbook.xml" },
+        { ContentType: CONTENT_TYPES.STYLES, PartName: "/xl/styles.xml" },
+        { ContentType: CONTENT_TYPES.CORE, PartName: "/docProps/core.xml" },
+        { ContentType: CONTENT_TYPES.APP, PartName: "/docProps/app.xml" },
+        { ContentType: CONTENT_TYPES.SHARED_STRINGS, PartName: "/xl/sharedStrings.xml" },
+    ].map(({ ContentType, PartName }) => ({
+        attrs: { ContentType, PartName },
+        tag: "Override",
+    }));
+    for (let i = 1; i <= sheetsCount; i++) {
+        overrides.push({
+            attrs: {
+                ContentType: CONTENT_TYPES.WORKSHEET,
+                PartName: `/xl/worksheets/sheet${i}.xml`,
+            },
+            tag: "Override",
+        });
+    }
+    return [
+        XML_DECLARATION,
+        buildXml({
+            attrs: { xmlns: XML_NAMESPACES.CONTENT_TYPES },
+            children: [...defaults, ...overrides],
+            tag: "Types",
+        }),
+    ].join("\n");
+}

package/build/esm/lib/workbook-builder/utils/build-core-xml.js

@@ -0,0 +1,24 @@
+import { XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { buildXml } from "./build-xml.js";
+export function buildCoreXml(creator = "Excel Generator", lastModifiedBy = "Excel Generator", created = "2025-01-01T00:00:00Z", modified = "2025-01-01T00:00:00Z") {
+    const coreProps = {
+        attrs: {
+            "xmlns:cp": XML_NAMESPACES.CORE_PROPERTIES,
+            "xmlns:dc": XML_NAMESPACES.DC,
+            "xmlns:dcmitype": XML_NAMESPACES.DCMITYPE,
+            "xmlns:dcterms": XML_NAMESPACES.DCTERMS,
+            "xmlns:xsi": XML_NAMESPACES.XSI,
+        },
+        children: [
+            { children: [creator], tag: "dc:creator" },
+            { children: [lastModifiedBy], tag: "cp:lastModifiedBy" },
+            { attrs: { "xsi:type": "dcterms:W3CDTF" }, children: [created], tag: "dcterms:created" },
+            { attrs: { "xsi:type": "dcterms:W3CDTF" }, children: [modified], tag: "dcterms:modified" },
+        ],
+        tag: "cp:coreProperties",
+    };
+    return [
+        XML_DECLARATION,
+        buildXml(coreProps),
+    ].join("\n");
+}

package/build/esm/lib/workbook-builder/utils/build-rels-xml.js

@@ -0,0 +1,16 @@
+import { RELATIONSHIP_TYPES, XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { buildXml } from "./build-xml.js";
+export function buildRelsXml() {
+    return [
+        XML_DECLARATION,
+        buildXml({
+            attrs: { xmlns: XML_NAMESPACES.PACKAGE_RELATIONSHIPS },
+            children: [
+                { attrs: { Id: "rId1", Target: "xl/workbook.xml", Type: RELATIONSHIP_TYPES.OFFICE_DOCUMENT }, tag: "Relationship" },
+                { attrs: { Id: "rId2", Target: "docProps/core.xml", Type: RELATIONSHIP_TYPES.CORE }, tag: "Relationship" },
+                { attrs: { Id: "rId3", Target: "docProps/app.xml", Type: RELATIONSHIP_TYPES.APP }, tag: "Relationship" },
+            ],
+            tag: "Relationships",
+        }),
+    ].join("\n");
+}

package/build/esm/lib/workbook-builder/utils/build-shared-strings-xml.js

@@ -0,0 +1,36 @@
+import { escapeXml } from "../../utils/index.js";
+import { XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { buildXml } from "./build-xml.js";
+/**
+ * Builds the `sharedStrings.xml` content from the provided strings.
+ *
+ * Note: According to the Excel specification, leading/trailing spaces in text
+ * nodes must set the attribute `xml:space="preserve"` on the corresponding <t>.
+ *
+ * @param strings - Array of unique strings used in the workbook
+ * @returns XML string for the shared strings part
+ */
+export function buildSharedStringsXml(strings = []) {
+    return [
+        XML_DECLARATION,
+        buildXml({
+            attrs: {
+                count: String(strings.length),
+                uniqueCount: String(strings.length),
+                xmlns: XML_NAMESPACES.SPREADSHEET_ML,
+            },
+            children: strings.map((s) => ({
+                children: [
+                    {
+                        // Excel spec: leading/trailing spaces require xml:space="preserve"
+                        attrs: /^\s|\s$/.test(s) ? { "xml:space": "preserve" } : undefined,
+                        children: [escapeXml(s)],
+                        tag: "t",
+                    },
+                ],
+                tag: "si",
+            })),
+            tag: "sst",
+        }),
+    ].join("\n");
+}

package/build/esm/lib/workbook-builder/utils/build-styles-xml.js

@@ -0,0 +1,142 @@
+import * as Default from "../default/index.js";
+import { XML_DECLARATION, XML_NAMESPACES } from "./constants.js";
+import { buildXml } from "./build-xml.js";
+/**
+ * Builds the `styles.xml` part for the workbook based on provided style collections.
+ * Falls back to default font/fill/border collections when none are provided.
+ *
+ * @param data - Style collections used to construct the stylesheet
+ * @param data.borders - Array of border XmlNodes
+ * @param data.cellXfs - Array of cell format records
+ * @param data.fills - Array of fill XmlNodes
+ * @param data.fonts - Array of font XmlNodes
+ * @param data.numFmts - Array of custom number formats (formatCode and id)
+ * @returns XML string for the styles part
+ */
+export function buildStylesXml(data) {
+    const { borders = [], cellXfs = [], fills = [], fonts = [], numFmts = [], } = data || {};
+    const children = [];
+    if (numFmts.length) {
+        children.push({
+            attrs: { count: String(numFmts.length) },
+            children: numFmts.map(nf => ({
+                attrs: {
+                    formatCode: nf.formatCode,
+                    numFmtId: String(nf.id),
+                },
+                tag: "numFmt",
+            })),
+            tag: "numFmts",
+        });
+    }
+    if (fonts.length) {
+        children.push({
+            attrs: { count: String(fonts.length) },
+            children: fonts,
+            tag: "fonts",
+        });
+    }
+    else {
+        children.push({
+            attrs: { count: "1" },
+            children: [Default.font()],
+            tag: "fonts",
+        });
+    }
+    if (fills.length) {
+        children.push({
+            attrs: { count: String(fills.length) },
+            children: fills,
+            tag: "fills",
+        });
+    }
+    else {
+        children.push({
+            attrs: { count: "1" },
+            children: [Default.fill()],
+            tag: "fills",
+        });
+    }
+    if (borders.length) {
+        children.push({
+            attrs: { count: String(borders.length) },
+            children: borders,
+            tag: "borders",
+        });
+    }
+    else {
+        children.push({
+            attrs: { count: "1" },
+            children: [Default.border()],
+            tag: "borders",
+        });
+    }
+    children.push({
+        attrs: { count: "1" },
+        children: [{
+                attrs: { borderId: "0", fillId: "0", fontId: "0", numFmtId: "0" },
+                tag: "xf",
+            }],
+        tag: "cellStyleXfs",
+    });
+    if (cellXfs.length) {
+        children.push({
+            attrs: { count: String(cellXfs.length) },
+            children: cellXfs.map((xf, i) => {
+                const isBaseXf = i === 0;
+                const hasAlignment = !!xf.alignment;
+                const xfChildren = [];
+                if (hasAlignment) {
+                    xfChildren.push({
+                        attrs: {
+                            ...(xf.alignment?.horizontal ? { horizontal: xf.alignment.horizontal } : {}),
+                            ...(xf.alignment?.vertical ? { vertical: xf.alignment.vertical } : {}),
+                            ...(xf.alignment?.wrapText ? { wrapText: "1" } : {}),
+                            ...(xf.alignment?.indent !== undefined ? { indent: String(xf.alignment.indent) } : {}),
+                        },
+                        tag: "alignment",
+                    });
+                }
+                return {
+                    attrs: {
+                        ...(isBaseXf
+                            ? {}
+                            : {
+                                applyBorder: "1",
+                                applyFill: "1",
+                                applyFont: "1",
+                                applyNumberFormat: xf.numFmtId ? "1" : "0",
+                            }),
+                        ...(hasAlignment ? { applyAlignment: "1" } : {}),
+                        borderId: String(xf.borderId),
+                        fillId: String(xf.fillId),
+                        fontId: String(xf.fontId),
+                        numFmtId: String(xf.numFmtId ?? 0),
+                        xfId: "0",
+                    },
+                    children: xfChildren,
+                    tag: "xf",
+                };
+            }),
+            tag: "cellXfs",
+        });
+    }
+    else {
+        // Base style without fill
+        children.push({
+            attrs: { count: "1" },
+            children: [
+                { attrs: { borderId: "0", fillId: "0", fontId: "0", numFmtId: "0", xfId: "0" }, tag: "xf" },
+            ],
+            tag: "cellXfs",
+        });
+    }
+    return [
+        XML_DECLARATION,
+        buildXml({
+            attrs: { xmlns: XML_NAMESPACES.SPREADSHEET_ML },
+            children,
+            tag: "styleSheet",
+        }),
+    ].join("\n");
+}