@cj-tech-master/excelts 9.5.8 → 9.5.9

package/dist/iife/excelts.iife.js

@@ -1,5 +1,5 @@
 /*!
-* @cj-tech-master/excelts v9.5.8
+* @cj-tech-master/excelts v9.5.9
 * Zero-dependency TypeScript toolkit — Excel (XLSX), PDF, CSV, Markdown, XML, ZIP/TAR, and streaming.
 * (c) 2026 cjnoname
 * Released under the MIT License
@@ -9509,7 +9509,7 @@ var ExcelTS = (function(exports) {
 				let l2;
 				let l3;
 				let n = 1;
-				if (level >= 4) throw new ColumnOutOfBoundsError(level, "Excel supports columns from 1 to 16384");
+				if (level >= 4) throw new Error(`colCache._fill: invariant violated — level ${level} exceeds the 3-letter cap; callers must validate before invoking _fill`);
 				if (this._l2nFill < 1 && level >= 1) {
 					while (n <= 26) {
 						c = this._dictionary[n - 1];
@@ -9548,7 +9548,10 @@ var ExcelTS = (function(exports) {
 				}
 			},
 			l2n(l) {
-				if (!this._l2n[l]) this._fill(l.length);
+				if (!this._l2n[l]) {
+					if (l.length > 3) throw new ColumnOutOfBoundsError(l, "Excel supports columns from 1 to 16384");
+					this._fill(l.length);
+				}
 				if (!this._l2n[l]) throw new ColumnOutOfBoundsError(l, `Invalid column letter: ${l}`);
 				return this._l2n[l];
 			},
@@ -10679,7 +10682,7 @@ var ExcelTS = (function(exports) {
 	* @example quoteSheetName("It's Fine") // "'It''s Fine'"
 	* @example quoteSheetName("2023 Data") // "'2023 Data'" (leading digit → quoted)
 	*/
-	function quoteSheetName(sheetName) {
+	function quoteSheetName$1(sheetName) {
 		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(sheetName)) return `'${sheetName.replace(/'/g, "''")}'`;
 		return sheetName;
 	}
@@ -10720,7 +10723,7 @@ var ExcelTS = (function(exports) {
 	}
 	function buildPivotChartSourceName(pivotTable) {
 		const tableName = pivotTable.name ?? `PivotTable${pivotTable.tableNumber}`;
-		return pivotTable.worksheetName ? `${quoteSheetName(pivotTable.worksheetName)}!${tableName}` : tableName;
+		return pivotTable.worksheetName ? `${quoteSheetName$1(pivotTable.worksheetName)}!${tableName}` : tableName;
 	}
 	var DEFAULT_PIVOT_CHART_PIVOT_AREA_XML;
 	var init_pivot_chart = __esmMin((() => {
@@ -21826,8 +21829,244 @@ onmessage = async (ev) => {
 	}));
 	//#endregion
 	//#region src/modules/excel/xlsx/xform/book/workbook-xform.ts
-	var WorkbookXform;
+	/**
+	* Split a print-area string on its multi-range separators while honouring
+	* single-quoted sheet name segments.
+	*
+	* Used by both the writer (parsing user-supplied `printArea` values) and
+	* the reader (parsing the body of an OOXML `<definedName>` when the
+	* defined-name layer hands us the raw text). Recognises both:
+	*   - `,` — the OOXML / Excel-native separator
+	*   - `&&` — the legacy excelts convention preserved on the public API
+	*
+	* Quoted sheet names (`'Q1, Forecast'!A1:B5`) are skipped over: any `,`,
+	* `&`, or `'` inside a quoted name is preserved verbatim. A doubled
+	* apostrophe inside a quoted segment (`''`) is the OOXML escape for a
+	* literal apostrophe and does not terminate the quote.
+	*
+	* Empty / whitespace-only segments are dropped; the caller normalises
+	* each surviving segment further with `parsePrintReference`.
+	*/
+	function splitPrintAreaInput(input) {
+		const result = [];
+		let current = "";
+		let inQuote = false;
+		for (let i = 0; i < input.length; i++) {
+			const ch = input[i];
+			if (ch === "'") {
+				if (inQuote && input[i + 1] === "'") {
+					current += "''";
+					i++;
+					continue;
+				}
+				inQuote = !inQuote;
+				current += ch;
+				continue;
+			}
+			if (!inQuote) {
+				if (ch === ",") {
+					if (current.trim()) result.push(current);
+					current = "";
+					continue;
+				}
+				if (ch === "&" && input[i + 1] === "&") {
+					if (current.trim()) result.push(current);
+					current = "";
+					i++;
+					continue;
+				}
+			}
+			current += ch;
+		}
+		if (current.trim()) result.push(current);
+		return result;
+	}
+	/**
+	* Quote a sheet name for inclusion in an OOXML defined-name reference.
+	*
+	* Per ECMA-376 §18.17 sheet names that contain spaces or any character
+	* outside `[A-Za-z0-9_]` MUST be wrapped in single quotes; a literal
+	* apostrophe inside the name is doubled. We always quote — over-quoting
+	* is harmless (Excel parses both forms) and keeps the writer trivial.
+	*/
+	function quoteSheetName(sheetName) {
+		return `'${sheetName.replace(/'/g, "''")}'`;
+	}
+	/**
+	* Find the index of the first `!` that lies outside any single-quoted
+	* sheet-name segment, or `-1` if no unquoted `!` is present.
+	*
+	* Sheet names quoted with `'` may contain unbalanced characters, so we
+	* walk the string honouring quote toggles before declaring a `!` to be
+	* the sheet/address separator. Doubled apostrophes (`''`) inside a
+	* quoted name are treated as a literal apostrophe per OOXML.
+	*/
+	function findUnquotedExclamation(value) {
+		let inQuote = false;
+		for (let i = 0; i < value.length; i++) {
+			const ch = value[i];
+			if (ch === "'") {
+				if (inQuote && value[i + 1] === "'") {
+					i++;
+					continue;
+				}
+				inQuote = !inQuote;
+			} else if (ch === "!" && !inQuote) return i;
+		}
+		return -1;
+	}
+	/**
+	* Parse a row token (the digits portion of a cell reference, or a
+	* whole-row number) into a canonical integer string.
+	*
+	* Rejects:
+	*   - row 0 (Excel rows are 1-indexed; `$A$0` is never a valid Excel ref)
+	*   - rows beyond `EXCEL_MAX_ROW` (Excel hard limit)
+	*
+	* Normalises:
+	*   - leading zeros (`001` → `1`) — OOXML expects bare integers, and
+	*     `Number(...)` collapses any padding the user typed.
+	*/
+	function parseRowToken(token) {
+		const n = Number(token);
+		if (n < 1) throw new RowOutOfBoundsError(n, `Excel rows are 1-indexed; row ${token} is invalid`);
+		if (n > EXCEL_MAX_ROW$1) throw new RowOutOfBoundsError(n, `Excel supports rows from 1 to ${EXCEL_MAX_ROW$1}`);
+		return String(n);
+	}
+	/**
+	* Parse a single user- or OOXML-supplied print reference into one of
+	* Excel's four valid shapes (cell / range / row / column), discarding
+	* any sheet prefix the input carries. Both the writer and the reader
+	* route through this single parser so the two sides agree on what is
+	* accepted and how it is canonicalised.
+	*
+	* Accepts every form Excel itself accepts on input, regardless of which
+	* side calls it:
+	*   - cell: `A1`, `$A$1`, `Sheet1!$A$1`, `'Q,F'!$A$1`, `a1`
+	*   - range: `A1:B5`, `$A$1:$B$5`, `Sheet!A1:B5`, ` A1 : B5 `, `a1:b5`,
+	*     mixed `$A1:$B$5`, reversed `B5:A1` (canonicalised to `A1:B5`)
+	*   - whole row: `1:5`, `$1:$5`, `Sheet!$1:$5`, `5` (single row),
+	*     reversed `5:1` (canonicalised to `1:5`), padded `001:005`
+	*   - whole column: `A:C`, `$A:$C`, `Sheet!$A:$C`, `C` (single column),
+	*     `a:c`, reversed `C:A` (canonicalised to `A:C`)
+	*
+	* Returns `undefined` for inputs that do not match one of the four
+	* shapes — callers drop the entry rather than emit corrupt XML.
+	*
+	* **Throws**:
+	*   - `ColumnOutOfBoundsError` when the input parses as a valid shape
+	*     but references a column letter beyond Excel's XFD (16384) limit.
+	*   - `RowOutOfBoundsError` for row 0 (Excel rows are 1-indexed) or
+	*     rows beyond Excel's `1048576` limit.
+	*
+	* Both errors match what `getCell` and `colCache.l2n` already throw for
+	* the same inputs; surfacing them here means a user who hand-authors a
+	* malformed `printArea` finds out at write time rather than producing
+	* a workbook Excel silently rejects.
+	*
+	* Why a hand-rolled parser instead of `colCache.decodeEx`? `decodeEx`
+	* was designed for cell addresses and produces `NaN`-laced output for
+	* whole-row (`$1:$5`) and whole-column (`$A:$C`) references. Print
+	* areas and print titles legitimately use both, so we need a parser
+	* that recognises all four shapes uniformly *and* canonicalises
+	* reversed endpoints (which `decodeEx` does for cells but not for
+	* row/column references).
+	*/
+	function parsePrintReference(input) {
+		if (typeof input !== "string") return;
+		const trimmed = input.trim();
+		if (!trimmed) return;
+		const exclamation = findUnquotedExclamation(trimmed);
+		const cleaned = (exclamation === -1 ? trimmed : trimmed.slice(exclamation + 1)).replace(/[\s$]+/g, "").toUpperCase();
+		if (!cleaned) return;
+		const parts = cleaned.split(":");
+		if (parts.length > 2) return;
+		const startRaw = parts[0];
+		const endRaw = parts.length === 2 ? parts[1] : startRaw;
+		const cellRe = /^([A-Z]+)(\d+)$/;
+		const startCell = cellRe.exec(startRaw);
+		const endCell = cellRe.exec(endRaw);
+		if (startCell && endCell) {
+			const startColNum = colCache.l2n(startCell[1]);
+			const endColNum = colCache.l2n(endCell[1]);
+			const startRow = Number(parseRowToken(startCell[2]));
+			const endRow = Number(parseRowToken(endCell[2]));
+			const tlCol = startColNum <= endColNum ? startCell[1] : endCell[1];
+			const brCol = startColNum <= endColNum ? endCell[1] : startCell[1];
+			const tlRow = startRow <= endRow ? startRow : endRow;
+			const brRow = startRow <= endRow ? endRow : startRow;
+			if (parts.length === 1) return {
+				kind: "cell",
+				ooxml: `$${tlCol}$${tlRow}`,
+				dimensions: `${tlCol}${tlRow}`
+			};
+			return {
+				kind: "range",
+				ooxml: `$${tlCol}$${tlRow}:$${brCol}$${brRow}`,
+				dimensions: `${tlCol}${tlRow}:${brCol}${brRow}`
+			};
+		}
+		if (/^\d+$/.test(startRaw) && /^\d+$/.test(endRaw)) {
+			const startRow = Number(parseRowToken(startRaw));
+			const endRow = Number(parseRowToken(endRaw));
+			const tl = Math.min(startRow, endRow);
+			const br = Math.max(startRow, endRow);
+			return {
+				kind: "row",
+				ooxml: `$${tl}:$${br}`,
+				dimensions: `${tl}:${br}`
+			};
+		}
+		if (/^[A-Z]+$/.test(startRaw) && /^[A-Z]+$/.test(endRaw)) {
+			const startNum = colCache.l2n(startRaw);
+			const endNum = colCache.l2n(endRaw);
+			const tl = startNum <= endNum ? startRaw : endRaw;
+			const br = startNum <= endNum ? endRaw : startRaw;
+			return {
+				kind: "col",
+				ooxml: `$${tl}:$${br}`,
+				dimensions: `${tl}:${br}`
+			};
+		}
+	}
+	/**
+	* Normalise a user-supplied `printArea` value into the canonical OOXML
+	* `'Sheet'!<ref>` form. Returns `undefined` for malformed input so the
+	* caller drops the entry instead of emitting corrupt XML.
+	*
+	* `printArea` accepts cell, range, whole-row, and whole-column shapes —
+	* Excel itself supports all four (e.g. selecting entire columns A:C as
+	* the print area is a common UI gesture). Bare cell inputs are promoted
+	* to a degenerate range `$A$1:$A$1` because that is what Excel itself
+	* emits for a single-cell print area, and the worksheet API exposes
+	* `printArea` as a range string (single-cell entries surface as `A1:A1`).
+	*/
+	function normalisePrintAreaRange(input, sheetName) {
+		const ref = parsePrintReference(input);
+		if (!ref) return;
+		const ooxml = ref.kind === "cell" ? `${ref.ooxml}:${ref.ooxml}` : ref.ooxml;
+		return `${quoteSheetName(sheetName)}!${ooxml}`;
+	}
+	/**
+	* Normalise a user-supplied print-titles row or column expression into
+	* the canonical OOXML form `'Sheet'!$N:$N` (rows) or `'Sheet'!$L:$L`
+	* (columns).
+	*
+	* Long-standing excelts behaviour lets users put a column expression on
+	* `printTitlesRow` (and vice versa) — the OOXML reader has always
+	* re-classified the value onto the correct field on round-trip — so we
+	* honour that by letting the parser infer the actual axis from the
+	* input shape. Strict enforcement would silently drop print titles
+	* users have set successfully for years.
+	*/
+	function normalisePrintTitlesAxis(input, sheetName) {
+		const ref = parsePrintReference(input);
+		if (!ref || ref.kind !== "row" && ref.kind !== "col") return;
+		return `${quoteSheetName(sheetName)}!${ref.ooxml}`;
+	}
+	var WorkbookXform, EXCEL_MAX_ROW$1;
 	var init_workbook_xform = __esmMin((() => {
+		init_errors$4();
 		init_col_cache();
 		init_ooxml_paths();
 		init_base_xform();
@@ -21898,37 +22137,33 @@ onmessage = async (ev) => {
 				const printAreas = [];
 				let index = 0;
 				model.sheets.forEach((sheet) => {
-					if (sheet.pageSetup && sheet.pageSetup.printArea) sheet.pageSetup.printArea.split("&&").forEach((printArea) => {
-						const printAreaComponents = printArea.split(":");
-						const start = printAreaComponents[0];
-						const end = printAreaComponents[1] ?? start;
-						const definedName = {
+					if (sheet.pageSetup && sheet.pageSetup.printArea) {
+						const ranges = [];
+						for (const segment of splitPrintAreaInput(sheet.pageSetup.printArea)) {
+							const normalised = normalisePrintAreaRange(segment, sheet.name);
+							if (normalised) ranges.push(normalised);
+						}
+						if (ranges.length > 0) printAreas.push({
 							name: "_xlnm.Print_Area",
-							ranges: [`'${sheet.name}'!$${start}:$${end}`],
+							ranges,
 							localSheetId: index
-						};
-						printAreas.push(definedName);
-					});
+						});
+					}
 					if (sheet.pageSetup && (sheet.pageSetup.printTitlesRow || sheet.pageSetup.printTitlesColumn)) {
 						const ranges = [];
 						if (sheet.pageSetup.printTitlesColumn) {
-							const titlesColumns = sheet.pageSetup.printTitlesColumn.split(":");
-							const start = titlesColumns[0];
-							const end = titlesColumns[1] ?? start;
-							ranges.push(`'${sheet.name}'!$${start}:$${end}`);
+							const normalised = normalisePrintTitlesAxis(sheet.pageSetup.printTitlesColumn, sheet.name);
+							if (normalised) ranges.push(normalised);
 						}
 						if (sheet.pageSetup.printTitlesRow) {
-							const titlesRows = sheet.pageSetup.printTitlesRow.split(":");
-							const start = titlesRows[0];
-							const end = titlesRows[1] ?? start;
-							ranges.push(`'${sheet.name}'!$${start}:$${end}`);
+							const normalised = normalisePrintTitlesAxis(sheet.pageSetup.printTitlesRow, sheet.name);
+							if (normalised) ranges.push(normalised);
 						}
-						const definedName = {
+						if (ranges.length > 0) printAreas.push({
 							name: "_xlnm.Print_Titles",
 							ranges,
 							localSheetId: index
-						};
-						printAreas.push(definedName);
+						});
 					}
 					index++;
 				});
@@ -22053,13 +22288,26 @@ onmessage = async (ev) => {
 				if (Array.isArray(model.worksheets)) model.worksheets = model.worksheets.filter((ws) => ws && Number.isInteger(ws.id) && ws.id > 0);
 				const definedNames = [];
 				if (model.definedNames) model.definedNames.forEach((definedName) => {
-					const effectiveRanges = definedName.ranges?.length > 0 ? definedName.ranges : definedName.rawText ? [definedName.rawText] : [];
+					const effectiveRanges = definedName.ranges?.length > 0 ? definedName.ranges : definedName.rawText ? splitPrintAreaInput(definedName.rawText) : [];
 					if (definedName.name === "_xlnm.Print_Area") {
 						worksheet = worksheets[definedName.localSheetId];
 						if (worksheet && effectiveRanges.length > 0) {
 							if (!worksheet.pageSetup) worksheet.pageSetup = {};
-							const range = colCache.decodeEx(effectiveRanges[0]);
-							worksheet.pageSetup.printArea = worksheet.pageSetup.printArea ? `${worksheet.pageSetup.printArea}&&${range.dimensions}` : range.dimensions;
+							const decoded = [];
+							for (const rangeStr of effectiveRanges) {
+								let ref;
+								try {
+									ref = parsePrintReference(rangeStr);
+								} catch {
+									ref = void 0;
+								}
+								if (!ref) continue;
+								decoded.push(ref.kind === "cell" ? `${ref.dimensions}:${ref.dimensions}` : ref.dimensions);
+							}
+							if (decoded.length > 0) {
+								const joined = decoded.join("&&");
+								worksheet.pageSetup.printArea = worksheet.pageSetup.printArea ? `${worksheet.pageSetup.printArea}&&${joined}` : joined;
+							}
 						}
 					} else if (definedName.name === "_xlnm.Print_Titles") {
 						worksheet = worksheets[definedName.localSheetId];
@@ -22106,6 +22354,7 @@ onmessage = async (ev) => {
 				}) };
 			}
 		};
+		EXCEL_MAX_ROW$1 = 1048576;
 	}));
 	//#endregion
 	//#region src/modules/excel/xlsx/xform/core/metadata-xform.ts