@js-ak/excel-toolbox 1.8.2 → 1.9.0

package/build/esm/lib/workbook-builder/default/index.js

@@ -0,0 +1,5 @@
+export * from "./border.js";
+export * from "./cell-xf.js";
+export * from "./fill.js";
+export * from "./font.js";
+export * from "./sheet-name.js";

package/build/esm/lib/workbook-builder/default/sheet-name.js

@@ -0,0 +1,6 @@
+/**
+ * Returns the default sheet name.
+ *
+ * @returns Default sheet name string
+ */
+export const sheetName = () => "Sheet1";

package/build/esm/lib/workbook-builder/index.js

@@ -0,0 +1,2 @@
+export * from "./utils/constants.js";
+export * from "./workbook-builder.js";

package/build/esm/lib/workbook-builder/merge-cells/add.js

@@ -0,0 +1,36 @@
+import * as Helpers from "./helpers/index.js";
+/**
+ * Adds a merge cell range to the specified sheet.
+ *
+ * @param this - WorkbookBuilder instance
+ * @param payload - Merge cell data with sheet name
+ *
+ * @returns The added merge cell object
+ *
+ * @throws Error if sheet is not found or merge intersects with existing merged cells
+ */
+export function add(payload) {
+    const { endCol, endRow, sheetName, startCol, startRow } = payload;
+    if (!this.getSheet(sheetName)) {
+        throw new Error("Sheet not found");
+    }
+    const merges = this.mergeCells.get(sheetName) ?? [];
+    // Check for intersection with existing merge cells
+    for (const m of merges) {
+        if (Helpers.rangesEqual(m, payload)) {
+            return m; // Already exists
+        }
+        if (Helpers.rangesIntersect(m, payload)) {
+            throw new Error("Merge intersects existing merged cell");
+        }
+    }
+    const merge = {
+        endCol,
+        endRow,
+        startCol,
+        startRow,
+    };
+    merges.push(merge);
+    this.mergeCells.set(sheetName, merges);
+    return merge;
+}

package/build/esm/lib/workbook-builder/merge-cells/helpers/index.js

@@ -0,0 +1,2 @@
+export * from "./ranges-equal.js";
+export * from "./ranges-intersect.js";

package/build/esm/lib/workbook-builder/merge-cells/helpers/ranges-equal.js

@@ -0,0 +1,14 @@
+/**
+ * Compares two merge cell ranges for equality.
+ *
+ * @param a - First merge cell range to compare
+ * @param b - Second merge cell range to compare
+ *
+ * @returns True if both ranges have identical start and end coordinates
+ */
+export function rangesEqual(a, b) {
+    return a.startRow === b.startRow &&
+        a.endRow === b.endRow &&
+        a.startCol === b.startCol &&
+        a.endCol === b.endCol;
+}

package/build/esm/lib/workbook-builder/merge-cells/helpers/ranges-intersect.js

@@ -0,0 +1,14 @@
+/**
+ * Checks if two merge cell ranges intersect with each other.
+ *
+ * @param a - First merge cell range to check
+ * @param b - Second merge cell range to check
+ *
+ * @returns True if the ranges intersect (overlap), false otherwise
+ */
+export function rangesIntersect(a, b) {
+    return !(a.endRow < b.startRow ||
+        a.startRow > b.endRow ||
+        a.endCol < b.startCol ||
+        a.startCol > b.endCol);
+}

package/build/esm/lib/workbook-builder/merge-cells/index.js

@@ -0,0 +1,2 @@
+export * from "./add.js";
+export * from "./remove.js";

package/build/esm/lib/workbook-builder/merge-cells/remove.js

@@ -0,0 +1,24 @@
+import * as Helpers from "./helpers/index.js";
+/**
+ * Removes a merge cell range from the specified sheet.
+ *
+ * @param this - WorkbookBuilder instance
+ * @param payload - Merge cell data with sheet name
+ *
+ * @returns True if the merge cell was successfully removed
+ *
+ * @throws Error if sheet is not found or merge cell does not exist
+ */
+export function remove(payload) {
+    const { endCol, endRow, sheetName, startCol, startRow } = payload;
+    if (!this.getSheet(sheetName)) {
+        throw new Error("Sheet not found: " + sheetName);
+    }
+    const merges = this.mergeCells.get(sheetName) ?? [];
+    const i = merges.findIndex(m => Helpers.rangesEqual(m, { endCol, endRow, startCol, startRow }));
+    if (i === -1) {
+        throw new Error("Sheet: " + sheetName + " Invalid merge cell: " + JSON.stringify(payload));
+    }
+    merges.splice(i, 1);
+    return true;
+}

package/build/esm/lib/workbook-builder/shared-string-ref/add.js

@@ -0,0 +1,21 @@
+/**
+ * Adds a shared string to the workbook and returns its index.
+ *
+ * @param this - WorkbookBuilder instance
+ * @param payload - Object containing sheet name and string value
+ *
+ * @returns The index of the shared string in the shared strings array
+ */
+export function add(payload) {
+    const { sheetName, str } = payload;
+    if (!this.getSheet(sheetName)) {
+        throw new Error("SheetName was not found");
+    }
+    let idx = this.sharedStringMap.get(str);
+    if (idx === undefined) {
+        idx = this.sharedStrings.length;
+        this.sharedStrings.push(str);
+        this.sharedStringMap.set(str, idx);
+    }
+    return idx;
+}

package/build/esm/lib/workbook-builder/shared-string-ref/index.js

@@ -0,0 +1,3 @@
+export * from "./add.js";
+export * from "./remove-all-from-sheet.js";
+export * from "./remove.js";

package/build/esm/lib/workbook-builder/shared-string-ref/remove-all-from-sheet.js

@@ -0,0 +1,63 @@
+/**
+ * Removes all shared string references for a specific sheet and cleans up unused strings.
+ *
+ * @param this - WorkbookBuilder instance
+ * @param payload - Object containing the sheet name to remove references from
+ */
+export function removeAllFromSheet(payload) {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { sheetName } = payload;
+    return;
+    // // 1. Collect strings that need to be removed
+    // const stringsToRemove: string[] = [];
+    // for (const [str, sheetsSet] of this.sharedStringRefs) {
+    // 	sheetsSet.delete(sheetName);
+    // 	if (sheetsSet.size === 0) {
+    // 		stringsToRemove.push(str);
+    // 	}
+    // }
+    // if (stringsToRemove.length === 0) {
+    // 	return;
+    // }
+    // // 2. Build map of old indices → new indices
+    // const oldToNew = new Map<number, number>();
+    // let newIdx = 0;
+    // for (let oldIdx = 0; oldIdx < this.sharedStrings.length; oldIdx++) {
+    // 	const str = this.sharedStrings[oldIdx];
+    // 	if (!str) {
+    // 		continue; // Skip if undefined
+    // 	}
+    // 	if (stringsToRemove.includes(str)) {
+    // 		// Remove string from refs
+    // 		this.sharedStringRefs.delete(str);
+    // 		continue; // Index is not accounted for
+    // 	}
+    // 	oldToNew.set(oldIdx, newIdx++);
+    // }
+    // // 3. Update sharedStrings array
+    // this.sharedStrings = this.sharedStrings.filter(s => !stringsToRemove.includes(s));
+    // // 4. Update sharedStringMap with new indices
+    // this.sharedStringMap.clear();
+    // for (let i = 0; i < this.sharedStrings.length; i++) {
+    // 	const str = this.sharedStrings[i];
+    // 	if (str) {
+    // 		this.sharedStringMap.set(str, i);
+    // 	}
+    // }
+    // // 5. Update indices in cells across all sheets
+    // for (const sheet of this.sheets.values()) {
+    // 	for (const row of sheet.rows.values()) {
+    // 		for (const cell of row.cells.values()) {
+    // 			if (cell.type === "s" && typeof cell.value === "number") {
+    // 				const newIdx = oldToNew.get(cell.value);
+    // 				if (newIdx !== undefined) {
+    // 					cell.value = newIdx;
+    // 				} else {
+    // 					// If cell.value was a removed string, set to 0 or null
+    // 					cell.value = 0;
+    // 				}
+    // 			}
+    // 		}
+    // 	}
+    // }
+}

package/build/esm/lib/workbook-builder/shared-string-ref/remove.js

@@ -0,0 +1,63 @@
+/**
+ * Removes a shared string reference for a specific sheet and cleans up if unused.
+ *
+ * @param this - WorkbookBuilder instance
+ * @param payload - Object containing sheet name and string index to remove
+ *
+ * @returns True if the reference was successfully removed, false if string or reference not found
+ */
+export function remove(payload) {
+    const { sheetName, strIdx } = payload;
+    if (!this.getSheet(sheetName)) {
+        throw new Error(`Sheet not found: ${sheetName}`);
+    }
+    const str = this.sharedStrings[strIdx];
+    if (!str) {
+        throw new Error(`String not found: ${strIdx}`);
+    }
+    return true;
+    // const refs = this.sharedStringRefs.get(str);
+    // if (!refs || !refs.has(sheetName)) {
+    // 	return false;
+    // }
+    // refs.delete(sheetName);
+    // if (refs.size === 0) {
+    // 	// Build map of old indices → new indices before removal
+    // 	const oldToNew = new Map<number, number>();
+    // 	for (let i = 0; i < this.sharedStrings.length; i++) {
+    // 		if (i < strIdx) {
+    // 			oldToNew.set(i, i);
+    // 		} else if (i > strIdx) {
+    // 			oldToNew.set(i, i - 1);
+    // 		}
+    // 		// i === strIdx — this string will be removed, no index
+    // 	}
+    // 	// Remove string from array and refs
+    // 	this.sharedStrings.splice(strIdx, 1);
+    // 	this.sharedStringMap.delete(str);
+    // 	this.sharedStringRefs.delete(str);
+    // 	// Update sharedStringMap with new indices
+    // 	for (let i = 0; i < this.sharedStrings.length; i++) {
+    // 		const str = this.sharedStrings[i];
+    // 		if (str) {
+    // 			this.sharedStringMap.set(str, i);
+    // 		}
+    // 	}
+    // 	// Update indices across all sheets
+    // 	for (const sheet of this.sheets.values()) {
+    // 		for (const row of sheet.rows.values()) {
+    // 			for (const cell of row.cells.values()) {
+    // 				if (cell.type === "s" && typeof cell.value === "number") {
+    // 					const newIdx = oldToNew.get(cell.value);
+    // 					if (newIdx !== undefined) {
+    // 						cell.value = newIdx;
+    // 					} else {
+    // 						// Just in case, if cell.value was a removed string
+    // 						cell.value = 0; // or null, according to your application logic
+    // 					}
+    // 				}
+    // 			}
+    // 		}
+    // 	}
+    // }
+}

package/build/esm/lib/workbook-builder/style-ref/add-or-get.js

@@ -0,0 +1,58 @@
+import * as Helpers from "./helpers/index.js";
+/**
+ * Adds a new cell style to the workbook or returns the index of an existing identical style.
+ * This function manages style deduplication by checking if an identical style already exists
+ * before creating a new one.
+ *
+ * @param this - The WorkbookBuilder instance
+ * @param payload - Object containing the style to add or get
+ * @param payload.style - The cell style configuration
+ *
+ * @returns The index of the style in the cellXfs array
+ */
+export function addOrGet(payload) {
+    const { style } = payload;
+    // Convert each style component to XML and get their IDs using Map-backed de-duplication
+    const fontXml = Helpers.fontToXml({ existingFonts: this.fonts, font: style.font });
+    const fontKey = JSON.stringify(fontXml);
+    let fontId = this.fontsMap.get(fontKey);
+    if (fontId === undefined) {
+        fontId = this.fonts.length;
+        this.fonts.push(fontXml);
+        this.fontsMap.set(fontKey, fontId);
+    }
+    const fillXml = Helpers.fillToXml({ existingFills: this.fills, fill: style.fill });
+    const fillKey = JSON.stringify(fillXml);
+    let fillId = this.fillsMap.get(fillKey);
+    if (fillId === undefined) {
+        fillId = this.fills.length;
+        this.fills.push(fillXml);
+        this.fillsMap.set(fillKey, fillId);
+    }
+    const borderXml = Helpers.borderToXml({ border: style.border, existingBorders: this.borders });
+    const borderKey = JSON.stringify(borderXml);
+    let borderId = this.bordersMap.get(borderKey);
+    if (borderId === undefined) {
+        borderId = this.borders.length;
+        this.borders.push(borderXml);
+        this.bordersMap.set(borderKey, borderId);
+    }
+    const numFmtId = style.numberFormat
+        ? Helpers.addNumFmt({ formatCode: style.numberFormat, numFmts: this.numFmts })
+        : 0;
+    const xf = {
+        alignment: style.alignment,
+        borderId,
+        fillId,
+        fontId,
+        numFmtId,
+    };
+    const xfKey = JSON.stringify(xf);
+    if (this.styleMap.has(xfKey)) {
+        return this.styleMap.get(xfKey);
+    }
+    const index = this.cellXfs.length;
+    this.cellXfs.push(xf);
+    this.styleMap.set(xfKey, index);
+    return index;
+}

package/build/esm/lib/workbook-builder/style-ref/helpers/add-num-fmt.js

@@ -0,0 +1,21 @@
+/**
+ * Adds a custom number format to the collection or returns the existing id.
+ *
+ * Excel reserves built-in ids below 164; custom formats start from 164.
+ *
+ * @param payload - Input arguments
+ * @param payload.formatCode - Format code, e.g., "0.00" or "dd/mm/yyyy"
+ * @param payload.numFmts - Mutable list of custom formats to search/extend
+ * @returns Numeric id of the number format
+ */
+export const addNumFmt = (payload) => {
+    const { formatCode, numFmts } = payload;
+    // 164+ is reserved for custom formats
+    const existing = numFmts.find(nf => nf.formatCode === formatCode);
+    if (existing) {
+        return existing.id;
+    }
+    const id = 164 + numFmts.length;
+    numFmts.push({ formatCode, id });
+    return id;
+};

package/build/esm/lib/workbook-builder/style-ref/helpers/border-to-xml.js

@@ -0,0 +1,45 @@
+/**
+ * Builds an XmlNode representing a <border> element based on the provided CellStyle.
+ *
+ * If no border is provided, the first existing border is returned (assumed default).
+ * Color values beginning with # are converted to RGB without the leading hash, as expected by Excel.
+ *
+ * @param payload - Input arguments
+ * @param payload.border - Optional border style from the cell style
+ * @param payload.existingBorders - Existing borders collection to fall back to
+ * @returns XmlNode representing a <border> element
+ */
+export const borderToXml = (payload) => {
+    const { border, existingBorders } = payload;
+    if (!existingBorders?.length) {
+        throw new Error("existingBorders is empty");
+    }
+    if (!border) {
+        return existingBorders[0];
+    }
+    const children = [];
+    for (const side of ["left", "right", "top", "bottom"]) {
+        const b = border?.[side];
+        if (b) {
+            const attrs = { style: b.style };
+            const sideChildren = b.color
+                ? [{
+                        attrs: { rgb: b.color.replace(/^#/, "") },
+                        tag: "color",
+                    }]
+                : [];
+            children.push({
+                attrs,
+                children: sideChildren,
+                tag: side,
+            });
+        }
+        else {
+            children.push({ tag: side });
+        }
+    }
+    return {
+        children,
+        tag: "border",
+    };
+};

package/build/esm/lib/workbook-builder/style-ref/helpers/fill-to-xml.js

@@ -0,0 +1,47 @@
+/**
+ * Builds an XmlNode representing a <fill> element based on the provided CellStyle.
+ *
+ * If no fill is provided, the first existing fill is returned (assumed default).
+ * Foreground/background colors may include a leading '#', which is removed to
+ * match Excel's expected RGB format.
+ *
+ * @param payload - Input arguments
+ * @param payload.existingFills - Existing fills collection to fall back to
+ * @param payload.fill - Optional fill from the cell style
+ * @returns XmlNode representing a <fill> element
+ */
+export const fillToXml = (payload) => {
+    const { existingFills, fill } = payload;
+    if (!existingFills?.length) {
+        throw new Error("existingFills is empty");
+    }
+    if (!fill)
+        return existingFills[0];
+    const patternType = fill.patternType ?? "solid";
+    const children = [];
+    const attrs = { patternType };
+    const fillChildren = [];
+    if (fill.fgColor) {
+        const colorVal = fill.fgColor.startsWith("#") ? fill.fgColor.slice(1) : fill.fgColor;
+        fillChildren.push({
+            attrs: { rgb: colorVal },
+            tag: "fgColor",
+        });
+    }
+    if (fill.bgColor) {
+        const colorVal = fill.bgColor.startsWith("#") ? fill.bgColor.slice(1) : fill.bgColor;
+        fillChildren.push({
+            attrs: { rgb: colorVal },
+            tag: "bgColor",
+        });
+    }
+    children.push({
+        attrs,
+        children: fillChildren,
+        tag: "patternFill",
+    });
+    return {
+        children,
+        tag: "fill",
+    };
+};

package/build/esm/lib/workbook-builder/style-ref/helpers/font-to-xml.js

@@ -0,0 +1,75 @@
+import * as Default from "../../default/index.js";
+/**
+ * Builds an XmlNode representing a <font> element based on the provided CellStyle.
+ *
+ * If no font is provided, returns the default font from the template. Color
+ * values may include a leading '#'. Six-digit RGB values are prefixed with
+ * 'FF' (alpha) to form ARGB; eight-digit values are used as-is. Throws for
+ * invalid color lengths.
+ *
+ * @param payload - Input arguments
+ * @param payload.existingFonts - Existing fonts collection (not used directly; kept for parity)
+ * @param payload.font - Optional font from the cell style
+ * @returns XmlNode representing a <font> element
+ */
+export const fontToXml = (payload) => {
+    const { existingFonts, font } = payload;
+    if (!existingFonts?.length) {
+        throw new Error("existingFonts is empty");
+    }
+    // Default values
+    const defaultFont = Default.font();
+    if (!font) {
+        // If no font style provided — return default font (as in Excel template)
+        return defaultFont;
+    }
+    const children = [];
+    // Size is always present
+    children.push({
+        attrs: { val: String(font.size ?? defaultFont.children.at(0)?.attrs.val) },
+        tag: "sz",
+    });
+    // Color (if provided) otherwise default
+    if (font.color) {
+        const colorVal = font.color.startsWith("#") ? font.color.slice(1) : font.color;
+        if (colorVal.length === 6) {
+            children.push({
+                attrs: { rgb: "FF" + colorVal.toUpperCase() },
+                tag: "color",
+            });
+        }
+        else if (colorVal.length === 8) {
+            children.push({
+                attrs: { rgb: colorVal.toUpperCase() },
+                tag: "color",
+            });
+        }
+        else {
+            throw new Error(`Invalid font color: ${font.color}`);
+        }
+    }
+    else {
+        children.push(defaultFont.children.at(1));
+    }
+    // Font name (required)
+    children.push({
+        attrs: { val: font.name ?? defaultFont.children.at(2)?.attrs.val },
+        tag: "name",
+    });
+    // Additional attributes
+    if (font.bold)
+        children.push({ tag: "b" });
+    if (font.italic)
+        children.push({ tag: "i" });
+    if (font.underline) {
+        const val = font.underline === true ? "single" : font.underline;
+        children.push({
+            attrs: { val },
+            tag: "u",
+        });
+    }
+    return {
+        children,
+        tag: "font",
+    };
+};

package/build/esm/lib/workbook-builder/style-ref/helpers/index.js

@@ -0,0 +1,5 @@
+export * from "./add-num-fmt.js";
+export * from "./border-to-xml.js";
+export * from "./fill-to-xml.js";
+export * from "./font-to-xml.js";
+export * from "./reindex-style-map-after-removal.js";

package/build/esm/lib/workbook-builder/style-ref/helpers/reindex-style-map-after-removal.js

@@ -0,0 +1,26 @@
+/**
+ * Reindexes a style map in-place after removing a style at a given index.
+ *
+ * - Deletes entries that point to the removed index
+ * - Decrements by 1 all indices greater than the removed index
+ *
+ * @param payload - Input arguments
+ * @param payload.removedIndex - The style index that was removed
+ * @param payload.styleMap - Map of serialized style key to style index
+ * @returns void
+ */
+export const reindexStyleMapAfterRemoval = (payload) => {
+    const { removedIndex, styleMap } = payload;
+    const updates = [];
+    for (const [key, idx] of styleMap.entries()) {
+        if (idx === removedIndex) {
+            styleMap.delete(key);
+        }
+        else if (idx > removedIndex) {
+            updates.push([key, idx - 1]);
+        }
+    }
+    for (const [key, newIdx] of updates) {
+        styleMap.set(key, newIdx);
+    }
+};

package/build/esm/lib/workbook-builder/style-ref/index.js

@@ -0,0 +1,3 @@
+export * from "./add-or-get.js";
+export * from "./remove-all-from-sheet.js";
+export * from "./remove.js";

package/build/esm/lib/workbook-builder/style-ref/remove-all-from-sheet.js

@@ -0,0 +1,23 @@
+import { remove } from "./remove.js";
+export function removeAllFromSheet(payload) {
+    const { sheetName } = payload;
+    const sheet = this.sheets.get(sheetName);
+    if (!sheet)
+        return false;
+    const stylesToRemove = [];
+    let removedSomething = false;
+    for (const row of sheet.rows.values()) {
+        for (const cell of row.cells.values()) {
+            if (cell.style?.index !== undefined) {
+                stylesToRemove.push(cell.style);
+            }
+        }
+    }
+    for (const style of stylesToRemove) {
+        const removed = remove.bind(this)({ style });
+        if (removed) {
+            removedSomething = true;
+        }
+    }
+    return removedSomething;
+}

package/build/esm/lib/workbook-builder/style-ref/remove.js

@@ -0,0 +1,49 @@
+// import * as Helpers from "./helpers/index.js";
+/**
+ * Validates a cell style index and checks if the style exists in the workbook.
+ * This function performs validation checks on the provided style index and
+ * verifies that the style exists at the given index in the cellXfs array.
+ *
+ * @param this - The WorkbookBuilder instance
+ * @param payload - Object containing the style to validate
+ * @param payload.style - The cell style configuration with index
+ *
+ * @returns True if the style index is valid and the style exists
+ *
+ * @throws {Error} When styleIndex is invalid (not a number) or when style doesn't exist at the given index
+ */
+export function remove(payload) {
+    const { style } = payload;
+    const styleIndex = style.index;
+    if (typeof styleIndex !== "number") {
+        throw new Error("Invalid styleIndex: not a number");
+    }
+    if (styleIndex === 0) {
+        throw new Error("Invalid styleIndex: 0 is the default style and cannot be removed");
+    }
+    const xf = this.cellXfs[styleIndex];
+    if (!xf) {
+        throw new Error(`Invalid styleIndex: style not found at index ${styleIndex}`);
+    }
+    return true;
+    // let removedSomething = false;
+    // // Get style parts before splice - indices are still valid
+    // const xf = this.cellXfs[styleIndex];
+    // if (xf) {
+    // 	this.cellXfs.splice(styleIndex, 1);
+    // 	// Fix: reindex styleMap after splice
+    // 	Helpers.reindexStyleMapAfterRemoval({ removedIndex: styleIndex, styleMap: this.styleMap });
+    // 	// Reindex style references in cells across all sheets
+    // 	for (const sheet of this.sheets.values()) {
+    // 		for (const row of sheet.rows.values()) {
+    // 			for (const cell of row.cells.values()) {
+    // 				if (cell.style?.index !== undefined && cell.style.index > styleIndex) {
+    // 					cell.style.index -= 1;
+    // 				}
+    // 			}
+    // 		}
+    // 	}
+    // 	removedSomething = true;
+    // }
+    // return removedSomething;
+}

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

@@ -0,0 +1 @@
+export {};

package/build/esm/lib/workbook-builder/types/border-style.js

@@ -0,0 +1 @@
+export {};

package/build/esm/lib/workbook-builder/types/cell-data.js

@@ -0,0 +1 @@
+export {};

package/build/esm/lib/workbook-builder/types/cell-style.js

@@ -0,0 +1 @@
+export {};

package/build/esm/lib/workbook-builder/types/cell-type.js

@@ -0,0 +1 @@
+export {};

package/build/esm/lib/workbook-builder/types/cell-value.js

@@ -0,0 +1 @@
+export {};

package/build/esm/lib/workbook-builder/types/cell-xf.js

@@ -0,0 +1 @@
+export {};