@8ms/helpers 3.1.0 → 3.2.0

package/dist/xlsx/_shared/cell.cjs

@@ -0,0 +1,102 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_xlsx__shared_column = require("./column.cjs");
+//#region src/xlsx/_shared/cell.ts
+/**
+* Parse the 1-based column number out of an Excel cell reference.
+*
+* Examples: "A1" → 1, "B3" → 2, "AA1" → 27.
+*/
+const getCellColNum = (ref) => {
+	const letters = ref.match(/^([A-Z]+)/)?.[1] ?? "A";
+	let colNum = 0;
+	for (const char of letters) colNum = colNum * 26 + (char.charCodeAt(0) - 64);
+	return colNum;
+};
+/**
+* Excel only understands finite numbers inside a <v> element — NaN or Infinity
+* produce a file it offers to "repair". Those fall back to text instead.
+*/
+const getCellValue = (value) => {
+	if (null === value || void 0 === value) return "";
+	if ("number" === typeof value) return Number.isFinite(value) ? value : String(value);
+	return value;
+};
+/**
+* Escape the reserved XML characters so a plain string is safe to embed in an
+* attribute value or a text node.
+*/
+const getEscapedXml = (text) => {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+};
+/**
+* Build the raw <c> (cell) XML for a single spreadsheet cell.
+*
+* Numbers use the <v> value element; strings are written as an inline string so
+* there is no shared-strings table to maintain.
+*
+* styleAttr must be either empty or a pre-formatted attribute such as ` s="3"`.
+*/
+const buildCellXml = (ref, value, styleAttr) => {
+	if ("number" === typeof value) return `<c r="${ref}"${styleAttr}><v>${value}</v></c>`;
+	return `<c r="${ref}"${styleAttr} t="inlineStr"><is><t>${getEscapedXml(String(value))}</t></is></c>`;
+};
+/**
+* Insert a <c> snippet into raw row XML, keeping the cells in ascending column
+* order. If a cell with a higher column number already exists the new cell goes
+* before it, otherwise it is appended.
+*/
+const insertCellInRow = (rowContent, ref, cellXml) => {
+	const newCol = getCellColNum(ref);
+	const cellPat = /<c r="([A-Z]+\d+)"(?:[^>]*\/>|[^>]*>[\s\S]*?<\/c>)/g;
+	const cells = [];
+	let match;
+	while (null !== (match = cellPat.exec(rowContent))) cells.push({
+		full: match[0],
+		col: getCellColNum(match[1])
+	});
+	const cellAfter = cells.find((cell) => {
+		return cell.col > newCol;
+	});
+	if (cellAfter) return rowContent.replace(cellAfter.full, () => {
+		return `${cellXml}${cellAfter.full}`;
+	});
+	return rowContent + cellXml;
+};
+/**
+* Set a cell value in raw worksheet XML.
+*
+* - If the cell exists, its content is replaced and its style attribute (s="N")
+*   is preserved, so a template's formatting survives.
+* - If the row exists but the cell does not, the cell is inserted in column order.
+* - If neither exists, a new row is appended before </sheetData>.
+*/
+const setCell = (xml, row, col, value) => {
+	const ref = `${require_xlsx__shared_column.getColumLetter(col)}${row}`;
+	const cellPat = new RegExp(`<c r="${ref}"([^>]*?)(?:\\s*/>|>[\\s\\S]*?<\\/c>)`);
+	const cellMatch = cellPat.exec(xml);
+	if (cellMatch) {
+		const style = /\bs="(\d+)"/.exec(cellMatch[1]);
+		const cellXml = buildCellXml(ref, value, style ? ` s="${style[1]}"` : "");
+		return xml.replace(cellPat, () => {
+			return cellXml;
+		});
+	}
+	const rowPat = new RegExp(`(<row[^>]+r="${row}"[^>]*>)([\\s\\S]*?)(<\/row>)`);
+	const rowMatch = rowPat.exec(xml);
+	if (rowMatch) {
+		const content = insertCellInRow(rowMatch[2], ref, buildCellXml(ref, value, ""));
+		return xml.replace(rowPat, () => {
+			return `${rowMatch[1]}${content}${rowMatch[3]}`;
+		});
+	}
+	const newRow = `<row r="${row}">${buildCellXml(ref, value, "")}</row>`;
+	return xml.replace("</sheetData>", () => {
+		return `${newRow}</sheetData>`;
+	});
+};
+//#endregion
+exports.buildCellXml = buildCellXml;
+exports.getCellColNum = getCellColNum;
+exports.getCellValue = getCellValue;
+exports.getEscapedXml = getEscapedXml;
+exports.setCell = setCell;

package/dist/xlsx/_shared/cell.d.cts

@@ -0,0 +1,37 @@
+//#region src/xlsx/_shared/cell.d.ts
+export type XlsxCellValue = string | number | null | undefined;
+/**
+ * Parse the 1-based column number out of an Excel cell reference.
+ *
+ * Examples: "A1" → 1, "B3" → 2, "AA1" → 27.
+ */
+export declare const getCellColNum: (ref: string) => number;
+/**
+ * Excel only understands finite numbers inside a <v> element — NaN or Infinity
+ * produce a file it offers to "repair". Those fall back to text instead.
+ */
+export declare const getCellValue: (value: XlsxCellValue) => string | number;
+/**
+ * Escape the reserved XML characters so a plain string is safe to embed in an
+ * attribute value or a text node.
+ */
+export declare const getEscapedXml: (text: string) => string;
+/**
+ * Build the raw <c> (cell) XML for a single spreadsheet cell.
+ *
+ * Numbers use the <v> value element; strings are written as an inline string so
+ * there is no shared-strings table to maintain.
+ *
+ * styleAttr must be either empty or a pre-formatted attribute such as ` s="3"`.
+ */
+export declare const buildCellXml: (ref: string, value: string | number, styleAttr: string) => string;
+/**
+ * Set a cell value in raw worksheet XML.
+ *
+ * - If the cell exists, its content is replaced and its style attribute (s="N")
+ *   is preserved, so a template's formatting survives.
+ * - If the row exists but the cell does not, the cell is inserted in column order.
+ * - If neither exists, a new row is appended before </sheetData>.
+ */
+export declare const setCell: (xml: string, row: number, col: number, value: string | number) => string;
+//#endregion

package/dist/xlsx/_shared/cell.d.mts

@@ -0,0 +1,37 @@
+//#region src/xlsx/_shared/cell.d.ts
+export type XlsxCellValue = string | number | null | undefined;
+/**
+ * Parse the 1-based column number out of an Excel cell reference.
+ *
+ * Examples: "A1" → 1, "B3" → 2, "AA1" → 27.
+ */
+export declare const getCellColNum: (ref: string) => number;
+/**
+ * Excel only understands finite numbers inside a <v> element — NaN or Infinity
+ * produce a file it offers to "repair". Those fall back to text instead.
+ */
+export declare const getCellValue: (value: XlsxCellValue) => string | number;
+/**
+ * Escape the reserved XML characters so a plain string is safe to embed in an
+ * attribute value or a text node.
+ */
+export declare const getEscapedXml: (text: string) => string;
+/**
+ * Build the raw <c> (cell) XML for a single spreadsheet cell.
+ *
+ * Numbers use the <v> value element; strings are written as an inline string so
+ * there is no shared-strings table to maintain.
+ *
+ * styleAttr must be either empty or a pre-formatted attribute such as ` s="3"`.
+ */
+export declare const buildCellXml: (ref: string, value: string | number, styleAttr: string) => string;
+/**
+ * Set a cell value in raw worksheet XML.
+ *
+ * - If the cell exists, its content is replaced and its style attribute (s="N")
+ *   is preserved, so a template's formatting survives.
+ * - If the row exists but the cell does not, the cell is inserted in column order.
+ * - If neither exists, a new row is appended before </sheetData>.
+ */
+export declare const setCell: (xml: string, row: number, col: number, value: string | number) => string;
+//#endregion

package/dist/xlsx/_shared/cell.mjs

@@ -0,0 +1,97 @@
+import { getColumLetter } from "./column.mjs";
+//#region src/xlsx/_shared/cell.ts
+/**
+* Parse the 1-based column number out of an Excel cell reference.
+*
+* Examples: "A1" → 1, "B3" → 2, "AA1" → 27.
+*/
+const getCellColNum = (ref) => {
+	const letters = ref.match(/^([A-Z]+)/)?.[1] ?? "A";
+	let colNum = 0;
+	for (const char of letters) colNum = colNum * 26 + (char.charCodeAt(0) - 64);
+	return colNum;
+};
+/**
+* Excel only understands finite numbers inside a <v> element — NaN or Infinity
+* produce a file it offers to "repair". Those fall back to text instead.
+*/
+const getCellValue = (value) => {
+	if (null === value || void 0 === value) return "";
+	if ("number" === typeof value) return Number.isFinite(value) ? value : String(value);
+	return value;
+};
+/**
+* Escape the reserved XML characters so a plain string is safe to embed in an
+* attribute value or a text node.
+*/
+const getEscapedXml = (text) => {
+	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+};
+/**
+* Build the raw <c> (cell) XML for a single spreadsheet cell.
+*
+* Numbers use the <v> value element; strings are written as an inline string so
+* there is no shared-strings table to maintain.
+*
+* styleAttr must be either empty or a pre-formatted attribute such as ` s="3"`.
+*/
+const buildCellXml = (ref, value, styleAttr) => {
+	if ("number" === typeof value) return `<c r="${ref}"${styleAttr}><v>${value}</v></c>`;
+	return `<c r="${ref}"${styleAttr} t="inlineStr"><is><t>${getEscapedXml(String(value))}</t></is></c>`;
+};
+/**
+* Insert a <c> snippet into raw row XML, keeping the cells in ascending column
+* order. If a cell with a higher column number already exists the new cell goes
+* before it, otherwise it is appended.
+*/
+const insertCellInRow = (rowContent, ref, cellXml) => {
+	const newCol = getCellColNum(ref);
+	const cellPat = /<c r="([A-Z]+\d+)"(?:[^>]*\/>|[^>]*>[\s\S]*?<\/c>)/g;
+	const cells = [];
+	let match;
+	while (null !== (match = cellPat.exec(rowContent))) cells.push({
+		full: match[0],
+		col: getCellColNum(match[1])
+	});
+	const cellAfter = cells.find((cell) => {
+		return cell.col > newCol;
+	});
+	if (cellAfter) return rowContent.replace(cellAfter.full, () => {
+		return `${cellXml}${cellAfter.full}`;
+	});
+	return rowContent + cellXml;
+};
+/**
+* Set a cell value in raw worksheet XML.
+*
+* - If the cell exists, its content is replaced and its style attribute (s="N")
+*   is preserved, so a template's formatting survives.
+* - If the row exists but the cell does not, the cell is inserted in column order.
+* - If neither exists, a new row is appended before </sheetData>.
+*/
+const setCell = (xml, row, col, value) => {
+	const ref = `${getColumLetter(col)}${row}`;
+	const cellPat = new RegExp(`<c r="${ref}"([^>]*?)(?:\\s*/>|>[\\s\\S]*?<\\/c>)`);
+	const cellMatch = cellPat.exec(xml);
+	if (cellMatch) {
+		const style = /\bs="(\d+)"/.exec(cellMatch[1]);
+		const cellXml = buildCellXml(ref, value, style ? ` s="${style[1]}"` : "");
+		return xml.replace(cellPat, () => {
+			return cellXml;
+		});
+	}
+	const rowPat = new RegExp(`(<row[^>]+r="${row}"[^>]*>)([\\s\\S]*?)(<\/row>)`);
+	const rowMatch = rowPat.exec(xml);
+	if (rowMatch) {
+		const content = insertCellInRow(rowMatch[2], ref, buildCellXml(ref, value, ""));
+		return xml.replace(rowPat, () => {
+			return `${rowMatch[1]}${content}${rowMatch[3]}`;
+		});
+	}
+	const newRow = `<row r="${row}">${buildCellXml(ref, value, "")}</row>`;
+	return xml.replace("</sheetData>", () => {
+		return `${newRow}</sheetData>`;
+	});
+};
+//#endregion
+export { buildCellXml, getCellColNum, getCellValue, getEscapedXml, setCell };

package/dist/xlsx/_shared/column.cjs

@@ -0,0 +1,37 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_xlsx__shared_cell = require("./cell.cjs");
+//#region src/xlsx/_shared/column.ts
+/** Bounds for widths derived from content, so nothing is cramped or absurd. */
+const COLUMN_WIDTH_MIN = 10;
+const COLUMN_WIDTH_MAX = 60;
+/**
+* Convert a 1-based column number to an Excel column letter string.
+*
+* Examples: 1 → "A", 2 → "B", 26 → "Z", 27 → "AA", 28 → "AB".
+*/
+const getColumLetter = (colNum) => {
+	let result = "";
+	let remaining = colNum;
+	while (remaining > 0) {
+		remaining--;
+		result = String.fromCharCode(65 + remaining % 26) + result;
+		remaining = Math.floor(remaining / 26);
+	}
+	return result;
+};
+/**
+* Width in Excel character units, taken from the widest value in the column
+* (header included) and clamped. Heading lines are excluded on purpose: they sit
+* in column A and overflow into the empty cells beside them, so letting them
+* drive the width would stretch the first column for no benefit.
+*/
+const getColumnWidth = (column, data) => {
+	if (column?.width) return column.width;
+	const longest = data.reduce((widest, row) => {
+		return Math.max(widest, String(require_xlsx__shared_cell.getCellValue(row?.[column.id])).length);
+	}, column.displayName.length);
+	return Math.min(COLUMN_WIDTH_MAX, Math.max(COLUMN_WIDTH_MIN, longest + 2));
+};
+//#endregion
+exports.getColumLetter = getColumLetter;
+exports.getColumnWidth = getColumnWidth;

package/dist/xlsx/_shared/column.d.cts

@@ -0,0 +1,22 @@
+import { XlsxCellValue } from "./cell.cjs";
+//#region src/xlsx/_shared/column.d.ts
+export type XlsxColumn = {
+  id: string;
+  displayName: string;
+  /** Column width in Excel character units. Derived from the content when omitted. */
+  width?: number;
+};
+/**
+ * Convert a 1-based column number to an Excel column letter string.
+ *
+ * Examples: 1 → "A", 2 → "B", 26 → "Z", 27 → "AA", 28 → "AB".
+ */
+export declare const getColumLetter: (colNum: number) => string;
+/**
+ * Width in Excel character units, taken from the widest value in the column
+ * (header included) and clamped. Heading lines are excluded on purpose: they sit
+ * in column A and overflow into the empty cells beside them, so letting them
+ * drive the width would stretch the first column for no benefit.
+ */
+export declare const getColumnWidth: (column: XlsxColumn, data: Record<string, XlsxCellValue>[]) => number;
+//#endregion

package/dist/xlsx/_shared/column.d.mts

@@ -0,0 +1,22 @@
+import { XlsxCellValue } from "./cell.mjs";
+//#region src/xlsx/_shared/column.d.ts
+export type XlsxColumn = {
+  id: string;
+  displayName: string;
+  /** Column width in Excel character units. Derived from the content when omitted. */
+  width?: number;
+};
+/**
+ * Convert a 1-based column number to an Excel column letter string.
+ *
+ * Examples: 1 → "A", 2 → "B", 26 → "Z", 27 → "AA", 28 → "AB".
+ */
+export declare const getColumLetter: (colNum: number) => string;
+/**
+ * Width in Excel character units, taken from the widest value in the column
+ * (header included) and clamped. Heading lines are excluded on purpose: they sit
+ * in column A and overflow into the empty cells beside them, so letting them
+ * drive the width would stretch the first column for no benefit.
+ */
+export declare const getColumnWidth: (column: XlsxColumn, data: Record<string, XlsxCellValue>[]) => number;
+//#endregion

package/dist/xlsx/_shared/column.mjs

@@ -0,0 +1,35 @@
+import { getCellValue } from "./cell.mjs";
+//#region src/xlsx/_shared/column.ts
+/** Bounds for widths derived from content, so nothing is cramped or absurd. */
+const COLUMN_WIDTH_MIN = 10;
+const COLUMN_WIDTH_MAX = 60;
+/**
+* Convert a 1-based column number to an Excel column letter string.
+*
+* Examples: 1 → "A", 2 → "B", 26 → "Z", 27 → "AA", 28 → "AB".
+*/
+const getColumLetter = (colNum) => {
+	let result = "";
+	let remaining = colNum;
+	while (remaining > 0) {
+		remaining--;
+		result = String.fromCharCode(65 + remaining % 26) + result;
+		remaining = Math.floor(remaining / 26);
+	}
+	return result;
+};
+/**
+* Width in Excel character units, taken from the widest value in the column
+* (header included) and clamped. Heading lines are excluded on purpose: they sit
+* in column A and overflow into the empty cells beside them, so letting them
+* drive the width would stretch the first column for no benefit.
+*/
+const getColumnWidth = (column, data) => {
+	if (column?.width) return column.width;
+	const longest = data.reduce((widest, row) => {
+		return Math.max(widest, String(getCellValue(row?.[column.id])).length);
+	}, column.displayName.length);
+	return Math.min(COLUMN_WIDTH_MAX, Math.max(COLUMN_WIDTH_MIN, longest + 2));
+};
+//#endregion
+export { getColumLetter, getColumnWidth };

package/dist/xlsx/_shared/createXlsx.cjs

@@ -0,0 +1,138 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_xlsx__shared_column = require("./column.cjs");
+const require_xlsx__shared_cell = require("./cell.cjs");
+const require_xlsx__shared_sheet = require("./sheet.cjs");
+//#region src/xlsx/_shared/createXlsx.ts
+/**
+* Builds a complete .xlsx workbook from scratch, using jszip and hand-written
+* OOXML rather than a spreadsheet library.
+*
+* Nothing here touches `fs`, so it runs in the browser as happily as on the
+* server — a page can turn data it has already loaded straight into a download.
+*
+* jszip is an optional peer dependency imported dynamically, so consumers that
+* never build a workbook neither install it nor pay for it in their bundle.
+*/
+/** Style index of the bold row within the cellXfs list built by buildStylesXml. */
+const HEADER_STYLE_INDEX = 1;
+const XML_DECLARATION = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>`;
+const CONTENT_TYPE = {
+	SHEET: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml",
+	STYLES: "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml",
+	WORKSHEET: "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"
+};
+const REL_TYPE = {
+	OFFICE_DOCUMENT: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument",
+	STYLES: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles",
+	WORKSHEET: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet"
+};
+const NAMESPACES = {
+	MAIN: "http://schemas.openxmlformats.org/spreadsheetml/2006/main",
+	RELATIONSHIP: "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+	PACKAGE_REL: "http://schemas.openxmlformats.org/package/2006/relationships",
+	CONTENT_TYPES: "http://schemas.openxmlformats.org/package/2006/content-types"
+};
+/**
+* Minimal but valid styles part. Excel requires at least one border, one
+* cellStyleXf and two fills (index 0 "none", index 1 "gray125") even when
+* nothing references them. cellXfs index 1 is the bold header.
+*/
+const buildStylesXml = () => {
+	return XML_DECLARATION + `<styleSheet xmlns="${NAMESPACES.MAIN}"><fonts count="2"><font><sz val="11"/><name val="Calibri"/></font><font><b/><sz val="11"/><name val="Calibri"/></font></fonts><fills count="2"><fill><patternFill patternType="none"/></fill><fill><patternFill patternType="gray125"/></fill></fills><borders count="1"><border><left/><right/><top/><bottom/><diagonal/></border></borders><cellStyleXfs count="1"><xf numFmtId="0" fontId="0" fillId="0" borderId="0"/></cellStyleXfs><cellXfs count="2"><xf numFmtId="0" fontId="0" fillId="0" borderId="0" xfId="0"/><xf numFmtId="0" fontId="1" fillId="0" borderId="0" xfId="0" applyFont="1"/></cellXfs><cellStyles count="1"><cellStyle name="Normal" xfId="0" builtinId="0"/></cellStyles></styleSheet>`;
+};
+/**
+* One worksheet part: column widths, an optional heading block, a bold header row
+* from the column display names, then one row per data object in column order.
+*
+* <cols> must precede <sheetData> or Excel treats the file as corrupt.
+*/
+const buildWorksheetXml = (sheet) => {
+	const heading = sheet?.heading || [];
+	const headerRow = 0 === heading.length ? 1 : heading.length + 2;
+	const colsXml = sheet.columns.map((column, index) => {
+		const position = index + 1;
+		return `<col min="${position}" max="${position}" width="${require_xlsx__shared_column.getColumnWidth(column, sheet.data)}" customWidth="1"/>`;
+	}).join("");
+	const headingXml = heading.map((line, index) => {
+		const styleAttr = 0 === index ? ` s="${HEADER_STYLE_INDEX}"` : "";
+		return `<row r="${index + 1}">${require_xlsx__shared_cell.buildCellXml(`A${index + 1}`, line, styleAttr)}</row>`;
+	}).join("");
+	const headerXml = sheet.columns.map((column, index) => {
+		return require_xlsx__shared_cell.buildCellXml(`${require_xlsx__shared_column.getColumLetter(index + 1)}${headerRow}`, column.displayName, ` s="${HEADER_STYLE_INDEX}"`);
+	}).join("");
+	const rowsXml = sheet.data.map((row, rowIndex) => {
+		const rowNumber = headerRow + rowIndex + 1;
+		return `<row r="${rowNumber}">${sheet.columns.map((column, columnIndex) => {
+			return require_xlsx__shared_cell.buildCellXml(`${require_xlsx__shared_column.getColumLetter(columnIndex + 1)}${rowNumber}`, require_xlsx__shared_cell.getCellValue(row?.[column.id]), "");
+		}).join("")}</row>`;
+	}).join("");
+	return XML_DECLARATION + `<worksheet xmlns="${NAMESPACES.MAIN}">` + (colsXml ? `<cols>${colsXml}</cols>` : "") + `<sheetData>${headingXml}<row r="${headerRow}">${headerXml}</row>${rowsXml}</sheetData></worksheet>`;
+};
+const buildContentTypesXml = (sheetCount) => {
+	const overrides = Array.from({ length: sheetCount }, (unused, index) => {
+		return `<Override PartName="/xl/worksheets/sheet${index + 1}.xml" ContentType="${CONTENT_TYPE.WORKSHEET}"/>`;
+	}).join("");
+	return XML_DECLARATION + `<Types xmlns="${NAMESPACES.CONTENT_TYPES}"><Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/><Default Extension="xml" ContentType="application/xml"/><Override PartName="/xl/workbook.xml" ContentType="${CONTENT_TYPE.SHEET}"/><Override PartName="/xl/styles.xml" ContentType="${CONTENT_TYPE.STYLES}"/>` + overrides + `</Types>`;
+};
+const buildWorkbookXml = (sheetNames) => {
+	const sheetsXml = sheetNames.map((name, index) => {
+		return `<sheet name="${require_xlsx__shared_cell.getEscapedXml(name)}" sheetId="${index + 1}" r:id="rId${index + 1}"/>`;
+	}).join("");
+	return XML_DECLARATION + `<workbook xmlns="${NAMESPACES.MAIN}" xmlns:r="${NAMESPACES.RELATIONSHIP}"><sheets>${sheetsXml}</sheets></workbook>`;
+};
+const buildWorkbookRelsXml = (sheetCount) => {
+	const sheetRels = Array.from({ length: sheetCount }, (unused, index) => {
+		return `<Relationship Id="rId${index + 1}" Type="${REL_TYPE.WORKSHEET}" Target="worksheets/sheet${index + 1}.xml"/>`;
+	}).join("");
+	return XML_DECLARATION + `<Relationships xmlns="${NAMESPACES.PACKAGE_REL}">` + sheetRels + `<Relationship Id="rId${sheetCount + 1}" Type="${REL_TYPE.STYLES}" Target="styles.xml"/></Relationships>`;
+};
+const buildPackageRelsXml = () => {
+	return XML_DECLARATION + `<Relationships xmlns="${NAMESPACES.PACKAGE_REL}"><Relationship Id="rId1" Type="${REL_TYPE.OFFICE_DOCUMENT}" Target="xl/workbook.xml"/></Relationships>`;
+};
+/**
+* Assemble the workbook parts. Shared by the Blob and byte-array entry points so
+* the two can never drift.
+*/
+const buildWorkbook = async (sheets) => {
+	if (0 === sheets.length) throw new Error("createXlsx requires at least one sheet.");
+	const JSZip = (await import("jszip")).default;
+	const zip = new JSZip();
+	const names = require_xlsx__shared_sheet.getUniqueSheetNames(sheets);
+	zip.file("[Content_Types].xml", buildContentTypesXml(sheets.length));
+	zip.file("_rels/.rels", buildPackageRelsXml());
+	zip.file("xl/workbook.xml", buildWorkbookXml(names));
+	zip.file("xl/_rels/workbook.xml.rels", buildWorkbookRelsXml(sheets.length));
+	zip.file("xl/styles.xml", buildStylesXml());
+	sheets.forEach((sheet, index) => {
+		zip.file(`xl/worksheets/sheet${index + 1}.xml`, buildWorksheetXml(sheet));
+	});
+	return zip;
+};
+/**
+* Build an .xlsx workbook with one worksheet per entry in `sheets`, returned as a
+* Blob ready to hand to a browser download.
+*
+* Every sheet gets a bold header row from its column display names, and each data
+* row reads values by column `id` — so key order in the source objects does not
+* matter and a missing key becomes an empty cell.
+*/
+const createXlsx = async (sheets) => {
+	return (await buildWorkbook(sheets)).generateAsync({
+		type: "blob",
+		compression: "DEFLATE",
+		mimeType: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+	});
+};
+/**
+* As createXlsx, but returns raw bytes instead of a Blob — for server-side
+* callers that need to stream or write the workbook rather than download it.
+*/
+const createXlsxBytes = async (sheets) => {
+	return (await buildWorkbook(sheets)).generateAsync({
+		type: "uint8array",
+		compression: "DEFLATE"
+	});
+};
+//#endregion
+exports.createXlsx = createXlsx;
+exports.createXlsxBytes = createXlsxBytes;

package/dist/xlsx/_shared/createXlsx.d.cts

@@ -0,0 +1,17 @@
+import { XlsxSheet } from "./sheet.cjs";
+//#region src/xlsx/_shared/createXlsx.d.ts
+/**
+ * Build an .xlsx workbook with one worksheet per entry in `sheets`, returned as a
+ * Blob ready to hand to a browser download.
+ *
+ * Every sheet gets a bold header row from its column display names, and each data
+ * row reads values by column `id` — so key order in the source objects does not
+ * matter and a missing key becomes an empty cell.
+ */
+export declare const createXlsx: (sheets: XlsxSheet[]) => Promise<Blob>;
+/**
+ * As createXlsx, but returns raw bytes instead of a Blob — for server-side
+ * callers that need to stream or write the workbook rather than download it.
+ */
+export declare const createXlsxBytes: (sheets: XlsxSheet[]) => Promise<Uint8Array>;
+//#endregion

package/dist/xlsx/_shared/createXlsx.d.mts

@@ -0,0 +1,17 @@
+import { XlsxSheet } from "./sheet.mjs";
+//#region src/xlsx/_shared/createXlsx.d.ts
+/**
+ * Build an .xlsx workbook with one worksheet per entry in `sheets`, returned as a
+ * Blob ready to hand to a browser download.
+ *
+ * Every sheet gets a bold header row from its column display names, and each data
+ * row reads values by column `id` — so key order in the source objects does not
+ * matter and a missing key becomes an empty cell.
+ */
+export declare const createXlsx: (sheets: XlsxSheet[]) => Promise<Blob>;
+/**
+ * As createXlsx, but returns raw bytes instead of a Blob — for server-side
+ * callers that need to stream or write the workbook rather than download it.
+ */
+export declare const createXlsxBytes: (sheets: XlsxSheet[]) => Promise<Uint8Array>;
+//#endregion