@js-ak/excel-toolbox 1.8.3 → 1.9.0

package/build/types/lib/workbook-builder/default/fill.d.ts

@@ -0,0 +1,7 @@
+import { XmlNode } from "../types/index.js";
+/**
+ * Creates a basic fill XML node with no pattern.
+ *
+ * @returns XML node representing an empty pattern fill
+ */
+export declare const fill: () => XmlNode;

package/build/types/lib/workbook-builder/default/font.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Creates a default font XML node with Calibri font.
+ *
+ * @returns XML node representing a default font configuration
+ */
+export declare const font: () => {
+    children: ({
+        attrs: {
+            val: string;
+            theme?: undefined;
+        };
+        tag: string;
+    } | {
+        attrs: {
+            theme: string;
+            val?: undefined;
+        };
+        tag: string;
+    })[];
+    tag: string;
+};

package/build/types/lib/workbook-builder/default/index.d.ts

@@ -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/types/lib/workbook-builder/default/sheet-name.d.ts

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

package/build/types/lib/workbook-builder/index.d.ts

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

package/build/types/lib/workbook-builder/merge-cells/add.d.ts

@@ -0,0 +1,15 @@
+import type { WorkbookBuilder } from "../workbook-builder.js";
+import { MergeCell } from "../types/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 declare function add(this: WorkbookBuilder, payload: MergeCell & {
+    sheetName: string;
+}): MergeCell;

package/build/types/lib/workbook-builder/merge-cells/helpers/index.d.ts

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

package/build/types/lib/workbook-builder/merge-cells/helpers/ranges-equal.d.ts

@@ -0,0 +1,10 @@
+import { MergeCell } from "../../types/index.js";
+/**
+ * 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 declare function rangesEqual(a: MergeCell, b: MergeCell): boolean;

package/build/types/lib/workbook-builder/merge-cells/helpers/ranges-intersect.d.ts

@@ -0,0 +1,10 @@
+import { MergeCell } from "../../types/index.js";
+/**
+ * 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 declare function rangesIntersect(a: MergeCell, b: MergeCell): boolean;

package/build/types/lib/workbook-builder/merge-cells/index.d.ts

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

package/build/types/lib/workbook-builder/merge-cells/remove.d.ts

@@ -0,0 +1,15 @@
+import type { WorkbookBuilder } from "../workbook-builder.js";
+import { MergeCell } from "../types/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 declare function remove(this: WorkbookBuilder, payload: MergeCell & {
+    sheetName: string;
+}): boolean;

package/build/types/lib/workbook-builder/shared-string-ref/add.d.ts

@@ -0,0 +1,13 @@
+import type { WorkbookBuilder } from "../workbook-builder.js";
+/**
+ * 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 declare function add(this: WorkbookBuilder, payload: {
+    sheetName: string;
+    str: string;
+}): number;

package/build/types/lib/workbook-builder/shared-string-ref/index.d.ts

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

package/build/types/lib/workbook-builder/shared-string-ref/remove-all-from-sheet.d.ts

@@ -0,0 +1,10 @@
+import type { WorkbookBuilder } from "../workbook-builder.js";
+/**
+ * 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 declare function removeAllFromSheet(this: WorkbookBuilder, payload: {
+    sheetName: string;
+}): void;

package/build/types/lib/workbook-builder/shared-string-ref/remove.d.ts

@@ -0,0 +1,13 @@
+import type { WorkbookBuilder } from "../workbook-builder.js";
+/**
+ * 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 declare function remove(this: WorkbookBuilder, payload: {
+    sheetName: string;
+    strIdx: number;
+}): true;

package/build/types/lib/workbook-builder/style-ref/add-or-get.d.ts

@@ -0,0 +1,16 @@
+import type { CellStyle } from "../types/index.js";
+import type { WorkbookBuilder } from "../workbook-builder.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 declare function addOrGet(this: WorkbookBuilder, payload: {
+    style: CellStyle;
+}): number;

package/build/types/lib/workbook-builder/style-ref/helpers/add-num-fmt.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare const addNumFmt: (payload: {
+    formatCode: string;
+    numFmts: {
+        formatCode: string;
+        id: number;
+    }[];
+}) => number;

package/build/types/lib/workbook-builder/style-ref/helpers/border-to-xml.d.ts

@@ -0,0 +1,16 @@
+import type { CellStyle, XmlNode } from "../../types/index.js";
+/**
+ * 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 declare const borderToXml: (payload: {
+    border?: CellStyle["border"];
+    existingBorders: XmlNode["children"];
+}) => XmlNode;

package/build/types/lib/workbook-builder/style-ref/helpers/fill-to-xml.d.ts

@@ -0,0 +1,17 @@
+import type { CellStyle, XmlNode } from "../../types/index.js";
+/**
+ * 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 declare const fillToXml: (payload: {
+    existingFills: XmlNode["children"];
+    fill?: CellStyle["fill"];
+}) => XmlNode;

package/build/types/lib/workbook-builder/style-ref/helpers/font-to-xml.d.ts

@@ -0,0 +1,18 @@
+import type { CellStyle, XmlNode } from "../../types/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 declare const fontToXml: (payload: {
+    existingFonts: XmlNode["children"];
+    font?: CellStyle["font"];
+}) => XmlNode;

package/build/types/lib/workbook-builder/style-ref/helpers/index.d.ts

@@ -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/types/lib/workbook-builder/style-ref/helpers/reindex-style-map-after-removal.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 declare const reindexStyleMapAfterRemoval: (payload: {
+    removedIndex: number;
+    styleMap: Map<string, number>;
+}) => void;

package/build/types/lib/workbook-builder/style-ref/index.d.ts

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

package/build/types/lib/workbook-builder/style-ref/remove-all-from-sheet.d.ts

@@ -0,0 +1,4 @@
+import { WorkbookBuilder } from "../workbook-builder.js";
+export declare function removeAllFromSheet(this: WorkbookBuilder, payload: {
+    sheetName: string;
+}): boolean;

package/build/types/lib/workbook-builder/style-ref/remove.d.ts

@@ -0,0 +1,18 @@
+import type { CellStyle } from "../types/index.js";
+import type { WorkbookBuilder } from "../workbook-builder.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 declare function remove(this: WorkbookBuilder, payload: {
+    style: CellStyle;
+}): true;

package/build/types/lib/workbook-builder/types/app-xml-options.d.ts

@@ -0,0 +1,9 @@
+export interface AppXmlOptions {
+    appVersion?: string;
+    application?: string;
+    company?: string;
+    hyperlinksChanged?: boolean;
+    linksUpToDate?: boolean;
+    sharedDoc?: boolean;
+    sheetNames?: string[];
+}

package/build/types/lib/workbook-builder/types/border-style.d.ts

@@ -0,0 +1,5 @@
+/** Border side style. */
+export type BorderStyle = {
+    style: "thin" | "medium" | "thick" | "dashed" | "dotted" | "double" | "hair" | "mediumDashed" | "dashDot" | "mediumDashDot" | "dashDotDot" | "mediumDashDotDot" | "slantDashDot";
+    color?: string;
+};

package/build/types/lib/workbook-builder/types/cell-data.d.ts

@@ -0,0 +1,10 @@
+import { CellStyle } from "./cell-style.js";
+import { CellType } from "./cell-type.js";
+import { CellValue } from "./cell-value.js";
+/** Cell representation. */
+export interface CellData {
+    value: CellValue;
+    isFormula?: boolean;
+    type?: CellType;
+    style?: CellStyle;
+}

package/build/types/lib/workbook-builder/types/cell-style.d.ts

@@ -0,0 +1,32 @@
+import { BorderStyle } from "./border-style.js";
+/** Style definition applied to a cell. */
+export type CellStyle = {
+    index?: number;
+    font?: {
+        name?: string;
+        size?: number;
+        bold?: boolean;
+        italic?: boolean;
+        underline?: boolean | "single" | "double";
+        color?: string;
+    };
+    fill?: {
+        type?: "pattern";
+        patternType?: string;
+        fgColor?: string;
+        bgColor?: string;
+    };
+    border?: {
+        top?: BorderStyle;
+        bottom?: BorderStyle;
+        left?: BorderStyle;
+        right?: BorderStyle;
+    };
+    alignment?: {
+        horizontal?: "left" | "center" | "right" | "justify";
+        vertical?: "top" | "center" | "bottom";
+        wrapText?: boolean;
+        indent?: number;
+    };
+    numberFormat?: string;
+};

package/build/types/lib/workbook-builder/types/cell-type.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Supported Excel cell types.
+ *
+ * s           - Shared string (reference to sharedStrings.xml). <v> contains index in sharedStrings
+ * inlineStr   - Inline string. Wrap value in <is><t>value</t></is>
+ * str         - Formula string result. Not for plain text, only formula result
+ * b           - Boolean. <v> — 0 or 1
+ * e           - Error. <v> — error code
+ * n           - Number. No attribute t or t="n"
+*/
+export type CellType = "s" | "inlineStr" | "n" | "b" | "str" | "e";

package/build/types/lib/workbook-builder/types/cell-value.d.ts

@@ -0,0 +1,2 @@
+/** Allowed cell value types. */
+export type CellValue = string | number | boolean | Date | null | undefined;

package/build/types/lib/workbook-builder/types/cell-xf.d.ts

@@ -0,0 +1,13 @@
+export type Alignment = {
+    horizontal?: "left" | "center" | "right" | "justify";
+    vertical?: "top" | "center" | "bottom";
+    wrapText?: boolean;
+    indent?: number;
+};
+export type CellXf = {
+    borderId: number;
+    fillId: number;
+    fontId: number;
+    numFmtId: number;
+    alignment?: Alignment;
+};

package/build/types/lib/workbook-builder/types/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./app-xml-options.js";
+export * from "./border-style.js";
+export * from "./cell-data.js";
+export * from "./cell-style.js";
+export * from "./cell-type.js";
+export * from "./cell-value.js";
+export * from "./cell-xf.js";
+export * from "./merge-cell.js";
+export * from "./row-data.js";
+export * from "./sheet-data.js";
+export * from "./xml-node.js";

package/build/types/lib/workbook-builder/types/merge-cell.d.ts

@@ -0,0 +1,6 @@
+export interface MergeCell {
+    startRow: number;
+    startCol: number;
+    endRow: number;
+    endCol: number;
+}

package/build/types/lib/workbook-builder/types/row-data.d.ts

@@ -0,0 +1,5 @@
+import { CellData } from "./cell-data.js";
+/** Row representation. */
+export interface RowData {
+    cells: Map<string, CellData>;
+}

package/build/types/lib/workbook-builder/types/sheet-data.d.ts

@@ -0,0 +1,13 @@
+import { CellData } from "./cell-data.js";
+import { MergeCell } from "./merge-cell.js";
+import { RowData } from "./row-data.js";
+/** Sheet representation with convenience methods. */
+export interface SheetData {
+    name: string;
+    rows: Map<number, RowData>;
+    addMerge(mergeCell: MergeCell): MergeCell;
+    removeMerge(mergeCell: MergeCell): boolean;
+    setCell(rowIndex: number, column: string | number, cell: CellData): void;
+    getCell(rowIndex: number, column: string | number): CellData | undefined;
+    removeCell(rowIndex: number, column: string | number): boolean;
+}

package/build/types/lib/workbook-builder/types/xml-node.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Represents an XML node structure for building XML documents.
+ */
+export type XmlNode = {
+    /** The XML tag name */
+    tag: string;
+    /** Optional attributes for the XML element */
+    attrs?: Record<string, string | number | undefined | null>;
+    /** Child elements or text content */
+    children?: (string | XmlNode)[];
+};

package/build/types/lib/workbook-builder/utils/build-app-xml.d.ts

@@ -0,0 +1,2 @@
+import { AppXmlOptions } from "../types/index.js";
+export declare function buildAppXml({ appVersion, application, company, hyperlinksChanged, linksUpToDate, sharedDoc, sheetNames, }?: AppXmlOptions): string;

package/build/types/lib/workbook-builder/utils/build-cell-children.d.ts

@@ -0,0 +1,9 @@
+import type { CellData, XmlNode } from "../types/index.js";
+/**
+ * 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 declare function buildCellChildren(cell: CellData): XmlNode[];

package/build/types/lib/workbook-builder/utils/build-content-types-xml.d.ts

@@ -0,0 +1 @@
+export declare function buildContentTypesXml(sheetsCount: number): string;

package/build/types/lib/workbook-builder/utils/build-core-xml.d.ts

@@ -0,0 +1 @@
+export declare function buildCoreXml(creator?: string, lastModifiedBy?: string, created?: string, modified?: string): string;

package/build/types/lib/workbook-builder/utils/build-rels-xml.d.ts

@@ -0,0 +1 @@
+export declare function buildRelsXml(): string;

package/build/types/lib/workbook-builder/utils/build-shared-strings-xml.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 declare function buildSharedStringsXml(strings?: string[]): string;

package/build/types/lib/workbook-builder/utils/build-styles-xml.d.ts

@@ -0,0 +1,23 @@
+import type { CellXf, XmlNode } from "../types/index.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 declare function buildStylesXml(data?: {
+    borders: XmlNode["children"];
+    cellXfs: CellXf[];
+    fills: XmlNode["children"];
+    fonts: XmlNode["children"];
+    numFmts: {
+        formatCode: string;
+        id: number;
+    }[];
+}): string;

package/build/types/lib/workbook-builder/utils/build-theme-xml.d.ts

@@ -0,0 +1 @@
+export declare function buildThemeXml(): string;

package/build/types/lib/workbook-builder/utils/build-workbook-rels-xml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Builds the `_rels/workbook.xml.rels` content for the given number of sheets.
+ *
+ * Relationships are created for each worksheet and then for styles, theme, and shared strings.
+ *
+ * @param sheetsCount - Number of worksheets in the workbook
+ * @returns XML string for the workbook relationships part
+ */
+export declare function buildWorkbookRels(sheetsCount: number): string;

package/build/types/lib/workbook-builder/utils/build-workbook-xml.d.ts

@@ -0,0 +1,3 @@
+export declare function buildWorkbookXml(sheets: {
+    name: string;
+}[]): string;

package/build/types/lib/workbook-builder/utils/build-worksheet-xml.d.ts

@@ -0,0 +1,2 @@
+import { SheetData } from "../types/index.js";
+export declare function buildWorksheetXml(rows?: SheetData["rows"], merges?: string[]): string;

package/build/types/lib/workbook-builder/utils/build-xml.d.ts

@@ -0,0 +1,50 @@
+import { XmlNode } from "../types/index.js";
+/**
+ * Builds XML string from an XmlNode structure.
+ *
+ * @param node - The XML node to convert to string
+ * @param level - The indentation level for formatting (default: 0)
+ *
+ * @returns The formatted XML string
+ */
+export declare function buildXml(node: XmlNode, level?: number): string;
+/**
+ * Cell XML Structure Documentation
+ *
+ * Reference: https://learn.microsoft.com/en-us/dotnet/api/documentformat.openxml.spreadsheet.cell?view=openxml-3.0.1
+ *
+ * Parent Elements:
+ * - row
+ *
+ * Child Elements:
+ * - extLst (Future Feature Data Storage Area)
+ * - f (Formula)
+ * - is (Rich Text Inline)
+ * - v (Cell Value)
+ *
+ * Attributes:
+ * - cm (Cell Metadata Index): The zero-based index of the cell metadata record associated with this cell.
+ *   Metadata information is found in the Metadata Part. Cell metadata is extra information stored at the
+ *   cell level, and is attached to the cell (travels through moves, copy / paste, clear, etc).
+ *   Cell metadata is not accessible via formula reference.
+ *   The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype.
+ *
+ * - ph (Show Phonetic): A Boolean value indicating if the spreadsheet application should show phonetic
+ *   information. Phonetic information is displayed in the same cell across the top of the cell and serves
+ *   as a 'hint' which indicates how the text should be pronounced. This should only be used for East Asian languages.
+ *   The possible values for this attribute are defined by the W3C XML Schema boolean datatype.
+ *
+ * - r (Reference): An A1 style reference to the location of this cell
+ *   The possible values for this attribute are defined by the ST_CellRef simple type.
+ *
+ * - s (Style Index): The index of this cell's style. Style records are stored in the Styles Part.
+ *   The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype.
+ *
+ * - t (Cell Data Type): An enumeration representing the cell's data type.
+ *   The possible values for this attribute are defined by the ST_CellType simple type.
+ *
+ * - vm (Value Metadata Index): The zero-based index of the value metadata record associated with this cell's value.
+ *   Metadata records are stored in the Metadata Part. Value metadata is extra information stored at the cell level,
+ *   but associated with the value rather than the cell itself. Value metadata is accessible via formula reference.
+ *   The possible values for this attribute are defined by the W3C XML Schema unsignedInt datatype.
+ */