@xlvane/compat 1.0.1 → 1.1.0

package/README.md

@@ -57,8 +57,8 @@ The full list, with the exceljs source of each behaviour, is in [docs/exceljs-co
 
 - **Not offered:** row and column operations on a streamed worksheet (`insertRow(s)`, `spliceRows`, `duplicateRow`, `spliceColumns`; exceljs's streaming worksheet does not have them either) throw an `XlvError` with code `XLV_E_NOT_SUPPORTED` and the name of the method. Deep imports of exceljs internals (`exceljs/lib/...`) do not resolve; `exceljs/dist/es5` and the `exceljs/dist/exceljs*.js` files do. Nothing is dropped silently.
 - **CSV:** text that starts with `=`, `+`, `-`, `@`, a tab, CR or LF is written with a leading `'`, so spreadsheet applications do not run it as a formula. `formulaInjection: "off"` writes it unchanged, as exceljs does.
-- **Sheet ids:** the file gets `sheetId` 1, 2, 3… in sheet order, and a loaded workbook numbers its sheets 1, 2, 3… in file order. After removing a sheet, `getWorksheet(id)` can give another sheet than with exceljs; look sheets up by name.
-- **Views:** only the first view of a worksheet is written; a split view is written without its `topLeftCell`.
+- **Sheet ids:** `worksheet.id` is written as `sheetId` and kept on loading, as in exceljs; an id outside 1 to 65534 is written as the lowest unused one, and the streaming `WorkbookReader` numbers worksheets 1, 2, 3… in file order.
+- **Views:** only the first view of a worksheet is written; a frozen view always gets the cell right of and below the panes as `topLeftCell`.
 - **Notes:** `protection.locked` and `lockText` read back as `'True'`/`'False'`, the values Excel writes.
 - **Module object:** it is frozen, so adding or replacing its properties (monkey-patching) has no effect.
 - **Streaming writer speed:** `stream.xlsx.WorkbookWriter` compresses in JavaScript (fflate) and took about twice as long as exceljs, which uses Node.js zlib (300 000 rows: 6.1 s against 2.8 s).

package/dist/index.d.ts

@@ -295,6 +295,8 @@ export declare class Workbook {
   get nextId(): number;
   /** Adds a worksheet. Names follow exceljs rules (31 characters at most; longer names are cut). */
   addWorksheet(name?: string, options?: WorksheetOptions): Worksheet;
+  /** @internal Adds a worksheet with a given id (a loaded file's sheetId, a model's id; D-F03). */
+  _addWorksheetWithId(id: number, name?: string, options?: WorksheetOptions): Worksheet;
   removeWorksheet(id: number | string): void;
   /** Removes a worksheet by id or name, as `removeWorksheet` (lib/doc/workbook.js L77). */
   removeWorksheetEx(worksheet: Worksheet): void;

package/dist/index.js

@@ -1228,9 +1228,10 @@ function noteBoxOut(box) {
 * The first exceljs view and the tab colour (X4-11, X4-12). xlvane writes one view: frozen panes
 * (`xSplit`/`ySplit` in columns and rows) or a split window (`xSplit`/`ySplit` in 1/20 point, as
 * exceljs), plus `zoomScale`, `showGridLines`, `showRowColHeaders`, `rightToLeft` and `style`.
-* `activeCell` is written for every view; `topLeftCell` only for a normal view (a split view's
-* exceljs `topLeftCell` is `pane@topLeftCell`, which the core does not write); `activePane`
-* follows from the panes.
+* `activeCell` is written for every view; `topLeftCell` for a normal view as
+* `sheetView@topLeftCell` and for a split view as `pane@topLeftCell`, as exceljs writes them
+* (sheet-view-xform.js L72-85; D-F02); a frozen view's `topLeftCell` follows from the panes;
+* `activePane` follows from the panes.
 */
 function layoutIn(ws) {
 	const v = ws.views[0];
@@ -1251,10 +1252,14 @@ function layoutIn(ws) {
 			rows: v.ySplit ?? 0,
 			cols: v.xSplit ?? 0
 		};
-		else if (v.state === "split" && ((v.xSplit ?? 0) > 0 || (v.ySplit ?? 0) > 0)) view.split = {
-			x: (v.xSplit ?? 0) / 20,
-			y: (v.ySplit ?? 0) / 20
-		};
+		else if (v.state === "split" && ((v.xSplit ?? 0) > 0 || (v.ySplit ?? 0) > 0)) {
+			const corner = typeof v["topLeftCell"] === "string" && v["topLeftCell"] !== "" ? { topLeftCell: v["topLeftCell"] } : {};
+			view.split = {
+				x: (v.xSplit ?? 0) / 20,
+				y: (v.ySplit ?? 0) / 20,
+				...corner
+			};
+		}
 	}
 	let tab = ws.properties["tabColor"];
 	if (tab && typeof tab.argb === "string" && /^[0-9A-Fa-f]{7}$/.test(tab.argb)) tab = {
@@ -1356,7 +1361,10 @@ function toNewWorkbook(sheets, date1904, meta = {}) {
 	if (meta.views && meta.views.length > 0) book.views(bookViewsIn(meta.views));
 	if (meta.calcProperties?.["fullCalcOnLoad"]) book.calculation({ fullCalcOnLoad: true });
 	for (const ws of sheets) at(ws.name, void 0, () => {
-		const sheet = book.addSheet(ws.name, { state: ws.state });
+		const sheet = book.addSheet(ws.name, {
+			state: ws.state,
+			...sheetIdOf(ws.id)
+		});
 		const useStyles = meta.useStyles !== false;
 		const sharedRanges = sharedFormulaRanges(ws);
 		const props = sheetPropertiesIn(ws.properties);
@@ -1487,8 +1495,9 @@ function fontOut(f) {
 /**
 * An exceljs view from the view read by xlvane, shaped as exceljs reads one (sheet-view-xform.js
 * L145–192; X4-11): a missing `zoomScaleNormal` reads as 100; a frozen view gets the default
-* `topLeftCell`; a split view gets `xSplit`/`ySplit` in 1/20 point and the active pane xlvane
-* writes; a normal view has no `topLeftCell`, as in exceljs.
+* `topLeftCell`; a split view gets `xSplit`/`ySplit` in 1/20 point, `pane@topLeftCell` as
+* `topLeftCell` (sheet-view-xform.js L118-124) and the active pane xlvane writes; a normal view
+* has no `topLeftCell`, as in exceljs.
 */
 function viewOut(view, freeze) {
 	const common = {
@@ -1516,14 +1525,14 @@ function viewOut(view, freeze) {
 	}
 	const active = view.activeCell !== null ? { activeCell: view.activeCell } : {};
 	if (view.split) {
-		const { x, y } = view.split;
+		const { x, y, topLeftCell } = view.split;
 		const activePane = x > 0 && y > 0 ? "bottomRight" : y > 0 ? "bottomLeft" : "topRight";
 		return {
 			...common,
 			state: "split",
 			xSplit: Math.round(x * 20),
 			ySplit: Math.round(y * 20),
-			topLeftCell: void 0,
+			topLeftCell,
 			activePane,
 			...active,
 			...style
@@ -1665,6 +1674,10 @@ function styleOut(s, numFmt) {
 function readBytes(bytes) {
 	return readWorkbook(bytes);
 }
+/** `{ sheetId }` for a worksheet id that Office accepts (1 to 65534, W2-20), otherwise nothing (D-F03). */
+function sheetIdOf(id) {
+	return Number.isInteger(id) && id >= 1 && id <= 65534 ? { sheetId: id } : {};
+}
 // src/sheet-rules.ts
 const MAX_ROW = 1048576;
 const MAX_COL = 16384;
@@ -5844,7 +5857,10 @@ var Workbook = class {
 	}
 	/** Adds a worksheet. Names follow exceljs rules (31 characters at most; longer names are cut). */
 	addWorksheet(name, options) {
-		const id = this.nextId;
+		return this._addWorksheetWithId(this.nextId, name, options);
+	}
+	/** @internal Adds a worksheet with a given id (a loaded file's sheetId, a model's id; D-F03). */
+	_addWorksheetWithId(id, name, options) {
 		const sheet = new Worksheet(this, id, name, options);
 		sheet.orderNo = this._sheets.reduce((acc, ws) => ws?.orderNo !== void 0 && ws.orderNo > acc ? ws.orderNo : acc, 0) + 1;
 		this._sheets[id] = sheet;
@@ -5916,8 +5932,10 @@ var Workbook = class {
 		this.views = Array.isArray(value["views"]) ? [...value["views"]] : [];
 		this._media = Array.isArray(value["media"]) ? [...value["media"]] : [];
 		for (const ws of this.worksheets) this.removeWorksheet(ws.id);
-		for (const m of Array.isArray(value["worksheets"]) ? value["worksheets"] : []) {
-			const ws = this.addWorksheet(String(m["name"] ?? ""), { state: m["state"] ?? "visible" });
+		const models = Array.isArray(value["worksheets"]) ? value["worksheets"] : [];
+		const ids = freeIds(models.map((m) => m["id"]));
+		for (const [i, m] of models.entries()) {
+			const ws = this._addWorksheetWithId(ids[i] ?? this.nextId, String(m["name"] ?? ""), { state: m["state"] ?? "visible" });
 			ws.model = m;
 		}
 		this._definedNames.model = Array.isArray(value["definedNames"]) ? value["definedNames"] : [];
@@ -6030,9 +6048,10 @@ var Workbook = class {
 			name: d.name,
 			ranges: extractRanges(d.refersTo)
 		}));
+		const ids = freeIds(read.sheets.map((s) => s.kind === "worksheet" ? s.sheetId : void 0));
 		for (const [position, s] of read.sheets.entries()) {
 			if (s.kind !== "worksheet") continue;
-			const ws = this.addWorksheet(s.name, { state: s.state });
+			const ws = this._addWorksheetWithId(ids[position] ?? this.nextId, s.name, { state: s.state });
 			ws.orderNo = position;
 			for (const c of use("cols") ? s.columns : []) {
 				const last = Math.min(c.max, 16384);
@@ -6123,6 +6142,30 @@ var Workbook = class {
 		}
 	}
 };
+/**
+* Worksheet ids for a list of wanted ids: each whole number from 1 to 65534 (the sheet ids Office
+* uses, W2-20) that is not wanted by an earlier entry is kept; other entries (missing, invalid,
+* larger or repeated ids) get the lowest ids no entry wants, in order. The limit keeps the
+* `_sheets` array small: an id from an untrusted file such as 4294967295 is not an array index and
+* 20000000 makes every scan of the array slow (found by review, D-F03). `undefined` entries
+* (sheets that are not worksheets) get no id.
+*/
+function freeIds(wanted) {
+	const taken = /* @__PURE__ */ new Set();
+	const kept = wanted.map((w) => {
+		if (typeof w !== "number" || !Number.isInteger(w) || w < 1 || w > 65534 || taken.has(w)) return null;
+		taken.add(w);
+		return w;
+	});
+	let next = 1;
+	return kept.map((k, i) => {
+		if (wanted[i] === void 0) return void 0;
+		if (k !== null) return k;
+		while (taken.has(next)) next++;
+		taken.add(next);
+		return next;
+	});
+}
 // src/stream.ts
 /**
 * A cell value for the streaming writer. Rows are written as they are committed, before later
@@ -6284,6 +6327,7 @@ var WorksheetWriter = class extends Worksheet {
 		return {
 			name: this.name,
 			state: this.state,
+			...sheetIdOf(this.id),
 			columns: trimTrailing(this.columns.map((c) => columnIn(c, this.writer._useStyles))),
 			...layout.freeze ? { freeze: layout.freeze } : {},
 			...Object.keys(layout.view).length > 0 ? { view: layout.view } : {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xlvane/compat",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "The commonly used exceljs 4.4.0 API on top of xlvane, for switching with one line in package.json.",
   "keywords": [
     "xlsx",
@@ -72,7 +72,7 @@
     "build": "tsdown"
   },
   "dependencies": {
-    "xlvane": "^1.0.1"
+    "xlvane": "^1.1.0"
   },
   "publishConfig": {
     "access": "public",