@8ms/helpers 3.0.23 → 3.0.24

package/dist/xlsx/createXlsx.mjs

@@ -0,0 +1,136 @@
+import { getColumLetter, getColumnWidth } from "./column.mjs";
+import { buildCellXml, getCellValue, getEscapedXml } from "./cell.mjs";
+import { getUniqueSheetNames } from "./sheet.mjs";
+//#region src/xlsx/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="${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}">${buildCellXml(`A${index + 1}`, line, styleAttr)}</row>`;
+	}).join("");
+	const headerXml = sheet.columns.map((column, index) => {
+		return buildCellXml(`${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 buildCellXml(`${getColumLetter(columnIndex + 1)}${rowNumber}`, 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="${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 = 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
+export { createXlsx, createXlsxBytes };

package/dist/xlsx/index.cjs

@@ -0,0 +1,18 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_xlsx_column = require("./column.cjs");
+const require_xlsx_cell = require("./cell.cjs");
+const require_xlsx_sheet = require("./sheet.cjs");
+const require_xlsx_createXlsx = require("./createXlsx.cjs");
+const require_xlsx_modifyXlsx = require("./modifyXlsx.cjs");
+exports.buildCellXml = require_xlsx_cell.buildCellXml;
+exports.createXlsx = require_xlsx_createXlsx.createXlsx;
+exports.createXlsxBytes = require_xlsx_createXlsx.createXlsxBytes;
+exports.getCellColNum = require_xlsx_cell.getCellColNum;
+exports.getCellValue = require_xlsx_cell.getCellValue;
+exports.getColumLetter = require_xlsx_column.getColumLetter;
+exports.getColumnWidth = require_xlsx_column.getColumnWidth;
+exports.getEscapedXml = require_xlsx_cell.getEscapedXml;
+exports.getSanitisedSheetName = require_xlsx_sheet.getSanitisedSheetName;
+exports.getUniqueSheetNames = require_xlsx_sheet.getUniqueSheetNames;
+exports.modifyXlsx = require_xlsx_modifyXlsx.modifyXlsx;
+exports.setCell = require_xlsx_cell.setCell;

package/dist/xlsx/index.d.cts

@@ -0,0 +1,6 @@
+import { XlsxCellValue, buildCellXml, getCellColNum, getCellValue, getEscapedXml, setCell } from "./cell.cjs";
+import { XlsxColumn, getColumLetter, getColumnWidth } from "./column.cjs";
+import { XlsxSheet, getSanitisedSheetName, getUniqueSheetNames } from "./sheet.cjs";
+import { createXlsx, createXlsxBytes } from "./createXlsx.cjs";
+import { XlsxSheetModifier, modifyXlsx } from "./modifyXlsx.cjs";
+export { XlsxCellValue, XlsxColumn, XlsxSheet, XlsxSheetModifier, buildCellXml, createXlsx, createXlsxBytes, getCellColNum, getCellValue, getColumLetter, getColumnWidth, getEscapedXml, getSanitisedSheetName, getUniqueSheetNames, modifyXlsx, setCell };

package/dist/xlsx/index.d.mts

@@ -0,0 +1,6 @@
+import { XlsxCellValue, buildCellXml, getCellColNum, getCellValue, getEscapedXml, setCell } from "./cell.mjs";
+import { XlsxColumn, getColumLetter, getColumnWidth } from "./column.mjs";
+import { XlsxSheet, getSanitisedSheetName, getUniqueSheetNames } from "./sheet.mjs";
+import { createXlsx, createXlsxBytes } from "./createXlsx.mjs";
+import { XlsxSheetModifier, modifyXlsx } from "./modifyXlsx.mjs";
+export { XlsxCellValue, XlsxColumn, XlsxSheet, XlsxSheetModifier, buildCellXml, createXlsx, createXlsxBytes, getCellColNum, getCellValue, getColumLetter, getColumnWidth, getEscapedXml, getSanitisedSheetName, getUniqueSheetNames, modifyXlsx, setCell };

package/dist/xlsx/index.mjs

@@ -0,0 +1,6 @@
+import { getColumLetter, getColumnWidth } from "./column.mjs";
+import { buildCellXml, getCellColNum, getCellValue, getEscapedXml, setCell } from "./cell.mjs";
+import { getSanitisedSheetName, getUniqueSheetNames } from "./sheet.mjs";
+import { createXlsx, createXlsxBytes } from "./createXlsx.mjs";
+import { modifyXlsx } from "./modifyXlsx.mjs";
+export { buildCellXml, createXlsx, createXlsxBytes, getCellColNum, getCellValue, getColumLetter, getColumnWidth, getEscapedXml, getSanitisedSheetName, getUniqueSheetNames, modifyXlsx, setCell };

package/dist/xlsx/modifyXlsx.cjs

@@ -0,0 +1,125 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_xlsx_cell = require("./cell.cjs");
+//#region src/xlsx/modifyXlsx.ts
+/**
+* Patches an existing .xlsx template: apply per-sheet XML transformations, add
+* sheets that are not in the template, and optionally embed a logo image.
+*
+* Takes and returns bytes rather than file paths, so it has no filesystem
+* dependency and runs anywhere. Callers that work from disk read the template
+* themselves and hand over the buffer.
+*
+* Use this when the output must keep a branded template's styling; use
+* `createXlsx` when building a workbook from nothing.
+*/
+/** 1 screen pixel at 96 DPI equals 9525 English Metric Units in OOXML. */
+const PX_TO_EMU = 9525;
+/** Default logo box, sized for a typical wide wordmark. */
+const LOGO_WIDTH_PX = 500;
+const LOGO_HEIGHT_PX = 77;
+const DRAWING_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
+const IMAGE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+const WORKSHEET_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
+const DRAWING_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawing+xml";
+/**
+* Minimal valid worksheet XML used when `createIfMissing` adds a sheet.
+*
+* <sheetData></sheetData> must not be self-closing: setCell's new-row path
+* searches for the literal closing tag.
+*/
+const EMPTY_SHEET_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\"><sheetData></sheetData></worksheet>";
+/**
+* Drawing XML for one embedded image, anchored to cell B2 so it sits just below
+* the header row.
+*
+* The image relationship is assumed to be registered as "rId1" in the sibling
+* .rels file.
+*/
+const buildDrawingXml = (widthEmu, heightEmu) => {
+	return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><xdr:oneCellAnchor><xdr:from><xdr:col>1</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>1</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from><xdr:ext cx="${widthEmu}" cy="${heightEmu}"/><xdr:pic><xdr:nvPicPr><xdr:cNvPr id="2" name="Logo"/><xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr></xdr:nvPicPr><xdr:blipFill><a:blip r:embed="rId1"/><a:stretch><a:fillRect/></a:stretch></xdr:blipFill><xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${widthEmu}" cy="${heightEmu}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr></xdr:pic><xdr:clientData/></xdr:oneCellAnchor></xdr:wsDr>`;
+};
+/**
+* Apply per-sheet transformations to a template workbook.
+*
+* @param template The .xlsx template as raw bytes.
+* @param sheets   One entry per sheet to touch, keyed by its 1-indexed position.
+* @param logo     Optional PNG bytes, embedded into sheets with `addLogo`.
+*/
+const modifyXlsx = async (template, sheets, logo) => {
+	const zip = await (await import("jszip")).default.loadAsync(template);
+	if (logo) {
+		zip.file("xl/media/image1.png", logo);
+		const contentTypesFile = zip.file("[Content_Types].xml");
+		if (contentTypesFile) {
+			let contentTypesXml = await contentTypesFile.async("string");
+			if (!contentTypesXml.includes(`Extension="png"`)) contentTypesXml = contentTypesXml.replace("</Types>", () => {
+				return `<Default Extension="png" ContentType="image/png"/></Types>`;
+			});
+			zip.file("[Content_Types].xml", contentTypesXml);
+		}
+	}
+	let drawingCounter = 0;
+	for (const sheet of sheets) {
+		const filename = `xl/worksheets/sheet${sheet.index}.xml`;
+		let existing = zip.file(filename);
+		if (!existing && sheet.createIfMissing) {
+			const name = sheet.sheetName ?? `Sheet${sheet.index}`;
+			const rId = `rId${sheet.index + 10}`;
+			const workbookFile = zip.file("xl/workbook.xml");
+			if (workbookFile) {
+				const workbookXml = await workbookFile.async("string");
+				zip.file("xl/workbook.xml", workbookXml.replace("</sheets>", () => {
+					return `<sheet name="${require_xlsx_cell.getEscapedXml(name)}" sheetId="${sheet.index}" r:id="${rId}"/></sheets>`;
+				}));
+			}
+			const relsFile = zip.file("xl/_rels/workbook.xml.rels");
+			if (relsFile) {
+				const relsXml = await relsFile.async("string");
+				zip.file("xl/_rels/workbook.xml.rels", relsXml.replace("</Relationships>", () => {
+					return `<Relationship Id="${rId}" Type="${WORKSHEET_REL_TYPE}" Target="worksheets/sheet${sheet.index}.xml"/></Relationships>`;
+				}));
+			}
+			zip.file(filename, EMPTY_SHEET_XML);
+			existing = zip.file(filename);
+		}
+		if (!existing) continue;
+		let xml = sheet.modify(await existing.async("string"));
+		if (sheet.addLogo && logo) {
+			drawingCounter++;
+			const drawingNum = drawingCounter;
+			const logoWidthEmu = Math.round((sheet.logoWidthPx ?? LOGO_WIDTH_PX) * PX_TO_EMU);
+			const logoHeightEmu = Math.round((sheet.logoHeightPx ?? LOGO_HEIGHT_PX) * PX_TO_EMU);
+			const drawingRId = `rIdLogo${drawingNum}`;
+			zip.file(`xl/drawings/drawing${drawingNum}.xml`, buildDrawingXml(logoWidthEmu, logoHeightEmu));
+			zip.file(`xl/drawings/_rels/drawing${drawingNum}.xml.rels`, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="${IMAGE_REL_TYPE}" Target="../media/image1.png"/></Relationships>`);
+			const contentTypesFile = zip.file("[Content_Types].xml");
+			if (contentTypesFile) {
+				let contentTypesXml = await contentTypesFile.async("string");
+				const drawingPart = `/xl/drawings/drawing${drawingNum}.xml`;
+				if (!contentTypesXml.includes(drawingPart)) contentTypesXml = contentTypesXml.replace("</Types>", () => {
+					return `<Override PartName="${drawingPart}" ContentType="${DRAWING_CONTENT_TYPE}"/></Types>`;
+				});
+				zip.file("[Content_Types].xml", contentTypesXml);
+			}
+			const sheetRelsPath = `xl/worksheets/_rels/sheet${sheet.index}.xml.rels`;
+			const sheetRelsFile = zip.file(sheetRelsPath);
+			if (sheetRelsFile) {
+				const relsXml = await sheetRelsFile.async("string");
+				zip.file(sheetRelsPath, relsXml.replace("</Relationships>", () => {
+					return `<Relationship Id="${drawingRId}" Type="${DRAWING_REL_TYPE}" Target="../drawings/drawing${drawingNum}.xml"/></Relationships>`;
+				}));
+			} else zip.file(sheetRelsPath, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="${drawingRId}" Type="${DRAWING_REL_TYPE}" Target="../drawings/drawing${drawingNum}.xml"/></Relationships>`);
+			if (!xml.includes("xmlns:r=")) xml = xml.replace("<worksheet ", `<worksheet xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" `);
+			xml = xml.replace("</worksheet>", () => {
+				return `<drawing r:id="${drawingRId}"/></worksheet>`;
+			});
+		}
+		zip.file(filename, xml);
+	}
+	return zip.generateAsync({
+		type: "uint8array",
+		compression: "DEFLATE"
+	});
+};
+//#endregion
+exports.modifyXlsx = modifyXlsx;

package/dist/xlsx/modifyXlsx.d.cts

@@ -0,0 +1,24 @@
+//#region src/xlsx/modifyXlsx.d.ts
+type XlsxSheetModifier = {
+  /** 1-indexed sheet number inside the ZIP (sheet1.xml, sheet2.xml, …). */
+  index: number;
+  modify: (xml: string) => string;
+  /** Create a blank sheet when the template does not contain this index. */
+  createIfMissing?: boolean;
+  /** Sheet name used when createIfMissing creates the sheet. */
+  sheetName?: string;
+  /** Embed the logo into this sheet. Requires a logo to be passed to modifyXlsx. */
+  addLogo?: boolean;
+  logoHeightPx?: number;
+  logoWidthPx?: number;
+};
+/**
+ * Apply per-sheet transformations to a template workbook.
+ *
+ * @param template The .xlsx template as raw bytes.
+ * @param sheets   One entry per sheet to touch, keyed by its 1-indexed position.
+ * @param logo     Optional PNG bytes, embedded into sheets with `addLogo`.
+ */
+declare const modifyXlsx: (template: Uint8Array, sheets: XlsxSheetModifier[], logo?: Uint8Array) => Promise<Uint8Array>;
+//#endregion
+export { XlsxSheetModifier, modifyXlsx };

package/dist/xlsx/modifyXlsx.d.mts

@@ -0,0 +1,24 @@
+//#region src/xlsx/modifyXlsx.d.ts
+type XlsxSheetModifier = {
+  /** 1-indexed sheet number inside the ZIP (sheet1.xml, sheet2.xml, …). */
+  index: number;
+  modify: (xml: string) => string;
+  /** Create a blank sheet when the template does not contain this index. */
+  createIfMissing?: boolean;
+  /** Sheet name used when createIfMissing creates the sheet. */
+  sheetName?: string;
+  /** Embed the logo into this sheet. Requires a logo to be passed to modifyXlsx. */
+  addLogo?: boolean;
+  logoHeightPx?: number;
+  logoWidthPx?: number;
+};
+/**
+ * Apply per-sheet transformations to a template workbook.
+ *
+ * @param template The .xlsx template as raw bytes.
+ * @param sheets   One entry per sheet to touch, keyed by its 1-indexed position.
+ * @param logo     Optional PNG bytes, embedded into sheets with `addLogo`.
+ */
+declare const modifyXlsx: (template: Uint8Array, sheets: XlsxSheetModifier[], logo?: Uint8Array) => Promise<Uint8Array>;
+//#endregion
+export { XlsxSheetModifier, modifyXlsx };

package/dist/xlsx/modifyXlsx.mjs

@@ -0,0 +1,124 @@
+import { getEscapedXml } from "./cell.mjs";
+//#region src/xlsx/modifyXlsx.ts
+/**
+* Patches an existing .xlsx template: apply per-sheet XML transformations, add
+* sheets that are not in the template, and optionally embed a logo image.
+*
+* Takes and returns bytes rather than file paths, so it has no filesystem
+* dependency and runs anywhere. Callers that work from disk read the template
+* themselves and hand over the buffer.
+*
+* Use this when the output must keep a branded template's styling; use
+* `createXlsx` when building a workbook from nothing.
+*/
+/** 1 screen pixel at 96 DPI equals 9525 English Metric Units in OOXML. */
+const PX_TO_EMU = 9525;
+/** Default logo box, sized for a typical wide wordmark. */
+const LOGO_WIDTH_PX = 500;
+const LOGO_HEIGHT_PX = 77;
+const DRAWING_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
+const IMAGE_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
+const WORKSHEET_REL_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
+const DRAWING_CONTENT_TYPE = "application/vnd.openxmlformats-officedocument.drawing+xml";
+/**
+* Minimal valid worksheet XML used when `createIfMissing` adds a sheet.
+*
+* <sheetData></sheetData> must not be self-closing: setCell's new-row path
+* searches for the literal closing tag.
+*/
+const EMPTY_SHEET_XML = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?><worksheet xmlns=\"http://schemas.openxmlformats.org/spreadsheetml/2006/main\"><sheetData></sheetData></worksheet>";
+/**
+* Drawing XML for one embedded image, anchored to cell B2 so it sits just below
+* the header row.
+*
+* The image relationship is assumed to be registered as "rId1" in the sibling
+* .rels file.
+*/
+const buildDrawingXml = (widthEmu, heightEmu) => {
+	return `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><xdr:wsDr xmlns:xdr="http://schemas.openxmlformats.org/drawingml/2006/spreadsheetDrawing" xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships"><xdr:oneCellAnchor><xdr:from><xdr:col>1</xdr:col><xdr:colOff>0</xdr:colOff><xdr:row>1</xdr:row><xdr:rowOff>0</xdr:rowOff></xdr:from><xdr:ext cx="${widthEmu}" cy="${heightEmu}"/><xdr:pic><xdr:nvPicPr><xdr:cNvPr id="2" name="Logo"/><xdr:cNvPicPr><a:picLocks noChangeAspect="1"/></xdr:cNvPicPr></xdr:nvPicPr><xdr:blipFill><a:blip r:embed="rId1"/><a:stretch><a:fillRect/></a:stretch></xdr:blipFill><xdr:spPr><a:xfrm><a:off x="0" y="0"/><a:ext cx="${widthEmu}" cy="${heightEmu}"/></a:xfrm><a:prstGeom prst="rect"><a:avLst/></a:prstGeom></xdr:spPr></xdr:pic><xdr:clientData/></xdr:oneCellAnchor></xdr:wsDr>`;
+};
+/**
+* Apply per-sheet transformations to a template workbook.
+*
+* @param template The .xlsx template as raw bytes.
+* @param sheets   One entry per sheet to touch, keyed by its 1-indexed position.
+* @param logo     Optional PNG bytes, embedded into sheets with `addLogo`.
+*/
+const modifyXlsx = async (template, sheets, logo) => {
+	const zip = await (await import("jszip")).default.loadAsync(template);
+	if (logo) {
+		zip.file("xl/media/image1.png", logo);
+		const contentTypesFile = zip.file("[Content_Types].xml");
+		if (contentTypesFile) {
+			let contentTypesXml = await contentTypesFile.async("string");
+			if (!contentTypesXml.includes(`Extension="png"`)) contentTypesXml = contentTypesXml.replace("</Types>", () => {
+				return `<Default Extension="png" ContentType="image/png"/></Types>`;
+			});
+			zip.file("[Content_Types].xml", contentTypesXml);
+		}
+	}
+	let drawingCounter = 0;
+	for (const sheet of sheets) {
+		const filename = `xl/worksheets/sheet${sheet.index}.xml`;
+		let existing = zip.file(filename);
+		if (!existing && sheet.createIfMissing) {
+			const name = sheet.sheetName ?? `Sheet${sheet.index}`;
+			const rId = `rId${sheet.index + 10}`;
+			const workbookFile = zip.file("xl/workbook.xml");
+			if (workbookFile) {
+				const workbookXml = await workbookFile.async("string");
+				zip.file("xl/workbook.xml", workbookXml.replace("</sheets>", () => {
+					return `<sheet name="${getEscapedXml(name)}" sheetId="${sheet.index}" r:id="${rId}"/></sheets>`;
+				}));
+			}
+			const relsFile = zip.file("xl/_rels/workbook.xml.rels");
+			if (relsFile) {
+				const relsXml = await relsFile.async("string");
+				zip.file("xl/_rels/workbook.xml.rels", relsXml.replace("</Relationships>", () => {
+					return `<Relationship Id="${rId}" Type="${WORKSHEET_REL_TYPE}" Target="worksheets/sheet${sheet.index}.xml"/></Relationships>`;
+				}));
+			}
+			zip.file(filename, EMPTY_SHEET_XML);
+			existing = zip.file(filename);
+		}
+		if (!existing) continue;
+		let xml = sheet.modify(await existing.async("string"));
+		if (sheet.addLogo && logo) {
+			drawingCounter++;
+			const drawingNum = drawingCounter;
+			const logoWidthEmu = Math.round((sheet.logoWidthPx ?? LOGO_WIDTH_PX) * PX_TO_EMU);
+			const logoHeightEmu = Math.round((sheet.logoHeightPx ?? LOGO_HEIGHT_PX) * PX_TO_EMU);
+			const drawingRId = `rIdLogo${drawingNum}`;
+			zip.file(`xl/drawings/drawing${drawingNum}.xml`, buildDrawingXml(logoWidthEmu, logoHeightEmu));
+			zip.file(`xl/drawings/_rels/drawing${drawingNum}.xml.rels`, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" Type="${IMAGE_REL_TYPE}" Target="../media/image1.png"/></Relationships>`);
+			const contentTypesFile = zip.file("[Content_Types].xml");
+			if (contentTypesFile) {
+				let contentTypesXml = await contentTypesFile.async("string");
+				const drawingPart = `/xl/drawings/drawing${drawingNum}.xml`;
+				if (!contentTypesXml.includes(drawingPart)) contentTypesXml = contentTypesXml.replace("</Types>", () => {
+					return `<Override PartName="${drawingPart}" ContentType="${DRAWING_CONTENT_TYPE}"/></Types>`;
+				});
+				zip.file("[Content_Types].xml", contentTypesXml);
+			}
+			const sheetRelsPath = `xl/worksheets/_rels/sheet${sheet.index}.xml.rels`;
+			const sheetRelsFile = zip.file(sheetRelsPath);
+			if (sheetRelsFile) {
+				const relsXml = await sheetRelsFile.async("string");
+				zip.file(sheetRelsPath, relsXml.replace("</Relationships>", () => {
+					return `<Relationship Id="${drawingRId}" Type="${DRAWING_REL_TYPE}" Target="../drawings/drawing${drawingNum}.xml"/></Relationships>`;
+				}));
+			} else zip.file(sheetRelsPath, `<?xml version="1.0" encoding="UTF-8" standalone="yes"?><Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships"><Relationship Id="${drawingRId}" Type="${DRAWING_REL_TYPE}" Target="../drawings/drawing${drawingNum}.xml"/></Relationships>`);
+			if (!xml.includes("xmlns:r=")) xml = xml.replace("<worksheet ", `<worksheet xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships" `);
+			xml = xml.replace("</worksheet>", () => {
+				return `<drawing r:id="${drawingRId}"/></worksheet>`;
+			});
+		}
+		zip.file(filename, xml);
+	}
+	return zip.generateAsync({
+		type: "uint8array",
+		compression: "DEFLATE"
+	});
+};
+//#endregion
+export { modifyXlsx };

package/dist/xlsx/sheet.cjs

@@ -0,0 +1,36 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/xlsx/sheet.ts
+/** Excel refuses to open a workbook whose sheet name exceeds 31 characters. */
+const SHEET_NAME_MAX_LENGTH = 31;
+/**
+* Coerce a sheet name into something Excel will accept: no []:*?/\ characters,
+* no wrapping apostrophes, at most 31 characters, and never empty.
+*
+* Uniqueness is handled separately, since that needs the whole set.
+*/
+const getSanitisedSheetName = (name) => {
+	const cleaned = (name || "").replace(/[[\]:*?/\\]/g, "_").replace(/^'+|'+$/g, "").trim().slice(0, SHEET_NAME_MAX_LENGTH);
+	return "" === cleaned ? "Sheet" : cleaned;
+};
+/**
+* Sanitise every sheet name and break collisions with _2, _3, … while staying
+* inside the 31 character limit. Excel rejects duplicate names outright, so this
+* cannot be left to chance once sheets are generated from data.
+*/
+const getUniqueSheetNames = (sheets) => {
+	const used = {};
+	return sheets.map((sheet) => {
+		const base = getSanitisedSheetName(sheet.name);
+		const key = base.toLowerCase();
+		if (!(key in used)) {
+			used[key] = 1;
+			return base;
+		}
+		used[key] += 1;
+		const suffix = `_${used[key]}`;
+		return base.slice(0, SHEET_NAME_MAX_LENGTH - suffix.length) + suffix;
+	});
+};
+//#endregion
+exports.getSanitisedSheetName = getSanitisedSheetName;
+exports.getUniqueSheetNames = getUniqueSheetNames;

package/dist/xlsx/sheet.d.cts

@@ -0,0 +1,29 @@
+import { XlsxCellValue } from "./cell.cjs";
+import { XlsxColumn } from "./column.cjs";
+//#region src/xlsx/sheet.d.ts
+type XlsxSheet = {
+  name: string;
+  columns: XlsxColumn[];
+  data: Record<string, XlsxCellValue>[];
+  /**
+   * Optional lines written above the table — typically a client name and a
+   * reporting period. The first line is bold, the rest are plain, and a blank
+   * row separates them from the column headers.
+   */
+  heading?: string[];
+};
+/**
+ * Coerce a sheet name into something Excel will accept: no []:*?/\ characters,
+ * no wrapping apostrophes, at most 31 characters, and never empty.
+ *
+ * Uniqueness is handled separately, since that needs the whole set.
+ */
+declare const getSanitisedSheetName: (name: string) => string;
+/**
+ * Sanitise every sheet name and break collisions with _2, _3, … while staying
+ * inside the 31 character limit. Excel rejects duplicate names outright, so this
+ * cannot be left to chance once sheets are generated from data.
+ */
+declare const getUniqueSheetNames: (sheets: XlsxSheet[]) => string[];
+//#endregion
+export { XlsxSheet, getSanitisedSheetName, getUniqueSheetNames };

package/dist/xlsx/sheet.d.mts

@@ -0,0 +1,29 @@
+import { XlsxCellValue } from "./cell.mjs";
+import { XlsxColumn } from "./column.mjs";
+//#region src/xlsx/sheet.d.ts
+type XlsxSheet = {
+  name: string;
+  columns: XlsxColumn[];
+  data: Record<string, XlsxCellValue>[];
+  /**
+   * Optional lines written above the table — typically a client name and a
+   * reporting period. The first line is bold, the rest are plain, and a blank
+   * row separates them from the column headers.
+   */
+  heading?: string[];
+};
+/**
+ * Coerce a sheet name into something Excel will accept: no []:*?/\ characters,
+ * no wrapping apostrophes, at most 31 characters, and never empty.
+ *
+ * Uniqueness is handled separately, since that needs the whole set.
+ */
+declare const getSanitisedSheetName: (name: string) => string;
+/**
+ * Sanitise every sheet name and break collisions with _2, _3, … while staying
+ * inside the 31 character limit. Excel rejects duplicate names outright, so this
+ * cannot be left to chance once sheets are generated from data.
+ */
+declare const getUniqueSheetNames: (sheets: XlsxSheet[]) => string[];
+//#endregion
+export { XlsxSheet, getSanitisedSheetName, getUniqueSheetNames };

package/dist/xlsx/sheet.mjs

@@ -0,0 +1,34 @@
+//#region src/xlsx/sheet.ts
+/** Excel refuses to open a workbook whose sheet name exceeds 31 characters. */
+const SHEET_NAME_MAX_LENGTH = 31;
+/**
+* Coerce a sheet name into something Excel will accept: no []:*?/\ characters,
+* no wrapping apostrophes, at most 31 characters, and never empty.
+*
+* Uniqueness is handled separately, since that needs the whole set.
+*/
+const getSanitisedSheetName = (name) => {
+	const cleaned = (name || "").replace(/[[\]:*?/\\]/g, "_").replace(/^'+|'+$/g, "").trim().slice(0, SHEET_NAME_MAX_LENGTH);
+	return "" === cleaned ? "Sheet" : cleaned;
+};
+/**
+* Sanitise every sheet name and break collisions with _2, _3, … while staying
+* inside the 31 character limit. Excel rejects duplicate names outright, so this
+* cannot be left to chance once sheets are generated from data.
+*/
+const getUniqueSheetNames = (sheets) => {
+	const used = {};
+	return sheets.map((sheet) => {
+		const base = getSanitisedSheetName(sheet.name);
+		const key = base.toLowerCase();
+		if (!(key in used)) {
+			used[key] = 1;
+			return base;
+		}
+		used[key] += 1;
+		const suffix = `_${used[key]}`;
+		return base.slice(0, SHEET_NAME_MAX_LENGTH - suffix.length) + suffix;
+	});
+};
+//#endregion
+export { getSanitisedSheetName, getUniqueSheetNames };