@rowsncolumns/rnc-engine 0.10.132

package/dist/esm/io.js

@@ -0,0 +1,318 @@
+import { WorkBook, createExcelFile, createODSFile, createRowDataFromCSVString, } from "@rowsncolumns/toolkit";
+import { RncEngine } from "./index";
+const PROCESS_CHUNK_ROWS = 1000;
+/**
+ * Inline-resolve every shared-string cell into a concrete value. The toolkit's XLSX parser emits a
+ * text cell as `{ ss: "<index>" }` with NO value field (the string lives only in the SST), but the
+ * engine has no shared-string table — so it would store such a cell empty. For each cell carrying an
+ * `ss` that resolves in `sharedStrings`, set `ue.sv` / `ev.sv` / `fv` to the string (mirrors
+ * `SheetCell.hydrateSharedStringValue`), then drop the now-redundant `ss`. Cells that already carry a
+ * value (numbers, formulas) are untouched. Mutates `sheetData` in place.
+ */
+function resolveSharedStrings(sheetData, sharedStrings) {
+    if (sharedStrings.size === 0)
+        return;
+    for (const rows of Object.values(sheetData)) {
+        for (const row of rows) {
+            const values = row?.values;
+            if (!values)
+                continue;
+            for (let c = 0; c < values.length; c++) {
+                const cell = values[c];
+                if (cell?.ss == null)
+                    continue;
+                const text = sharedStrings.get(String(cell.ss));
+                if (text === undefined)
+                    continue;
+                cell.ue = { ...cell.ue, sv: text };
+                cell.ev = { ...cell.ev, sv: text };
+                cell.fv ??= text;
+                delete cell.ss;
+            }
+        }
+    }
+}
+/**
+ * Parse an XLSX (or any format the toolkit's `WorkBook` plugin registry handles for the given file
+ * name — `.xlsx` / `.xlsm` …) buffer into the common `rnc-model` shape, WITHOUT touching the engine.
+ * Drives the toolkit `WorkBook` directly (Node-safe: it uses `@zip.js/zip.js` + `fast-xml-parser`,
+ * no browser/Worker APIs). Shared-string cells (which the plugin emits as a bare `ss` index) are
+ * resolved inline to their value via {@link resolveSharedStrings}, since the engine has no SST table.
+ */
+export async function parseWorkbook(buffer, fileName = "workbook.xlsx", options = {}) {
+    const workbook = new WorkBook();
+    await workbook.load(buffer, fileName);
+    try {
+        const [sheets, tables] = await workbook.getSheets(options.minRowCount, options.minColumnCount);
+        // Assemble SheetData from the chunked generator: each chunk's `rows[i]` belongs at
+        // `sheetData[sheetId][rowIndices[i]]` (the same placement the import hook uses).
+        const sheetData = {};
+        for await (const chunk of workbook.processSheetData(PROCESS_CHUNK_ROWS, true, true)) {
+            const rows = (sheetData[chunk.sheetId] ??= []);
+            for (let i = 0; i < chunk.rowIndices.length; i++) {
+                rows[chunk.rowIndices[i]] = chunk.rows[i];
+            }
+        }
+        // The plugin's SST is a `string[]` keyed by index; cells reference it by that index in `cell.ss`.
+        const sharedStrings = new Map();
+        (workbook.sharedStrings ?? []).forEach((value, index) => {
+            sharedStrings.set(String(index), value);
+        });
+        // A shared-string cell from the plugin carries ONLY `ss` (its SST index) — no value field. The
+        // engine has no shared-string table (and we make no Rust changes), so resolve each `ss` into an
+        // inline `ue.sv`/`ev.sv`/`fv` here, mirroring `SheetCell.hydrateSharedStringValue`. Otherwise the
+        // engine would store text cells with no value and `readWindow` would return them empty.
+        resolveSharedStrings(sheetData, sharedStrings);
+        const [conditionalFormats, dataValidations] = await Promise.all([
+            workbook.getConditionalFormatting(),
+            workbook.getDataValidations(),
+        ]);
+        return {
+            sheets,
+            sheetData,
+            sharedStrings,
+            tables,
+            conditionalFormats,
+            dataValidations,
+            namedRanges: workbook.getNamedRanges(),
+            commentThreads: await workbook.getCommentThreads(),
+        };
+    }
+    finally {
+        workbook.dispose();
+    }
+}
+/** Map a {@link ParsedWorkbook} to the engine's {@link LoadDocument} hydration shape. */
+function toLoadDocument(parsed) {
+    return {
+        sheets: parsed.sheets.map((sheet) => ({
+            sheetId: sheet.sheetId,
+            title: sheet.title,
+        })),
+        sheetData: parsed.sheetData,
+        conditionalFormats: parsed.conditionalFormats,
+        dataValidations: parsed.dataValidations,
+        tables: parsed.tables,
+        namedRanges: parsed.namedRanges,
+    };
+}
+/** Register every parsed sheet on the engine that isn't already present. */
+function ensureSheets(engine, parsed) {
+    const existing = new Set(engine.sheetIds());
+    for (const sheet of parsed.sheets) {
+        if (!existing.has(sheet.sheetId))
+            engine.addSheet(sheet.sheetId, sheet.title);
+    }
+}
+/**
+ * Import an XLSX buffer into the engine via the toolkit. Returns the engine the cells were loaded
+ * into (a fresh one when `engine` is omitted). Hydrates through {@link RncEngine.load}, so it
+ * delivers the full change-set to `onChanges` subscribers like every other load.
+ */
+export async function importXlsx(buffer, options = {}) {
+    const parsed = await parseWorkbook(buffer, options.fileName ?? "workbook.xlsx", options);
+    const engine = options.engine ?? (await RncEngine.create());
+    ensureSheets(engine, parsed);
+    engine.load(toLoadDocument(parsed));
+    return engine;
+}
+/** Import an ODS buffer into the engine. Same path as {@link importXlsx} with an `.ods` file name so
+ * the toolkit selects its ODS plugin. */
+export async function importOds(buffer, options = {}) {
+    return importXlsx(buffer, {
+        ...options,
+        fileName: options.fileName ?? "workbook.ods",
+    });
+}
+/**
+ * Stream a parsed workbook's cells into the engine's NDJSON hydration path instead of one big
+ * `loadDocument`, so a huge workbook is fed cell-by-cell (one `{"t":"cell",…}` record each) and never
+ * materialized whole on the engine side in a single call. The sheets are registered first (as
+ * `{"t":"sheet",…}` records). Pull the visible area with `readWindow` afterward.
+ *
+ * NOTE: document facets (CF / DV / tables / named ranges) are NOT carried by the NDJSON stream — load
+ * those separately if needed. Use this for value-heavy bulk imports; use {@link importXlsx} for the
+ * full-fidelity (facets included) path.
+ */
+export function streamWorkbookInto(engine, parsed) {
+    const encoder = new TextEncoder();
+    engine.streamBegin();
+    try {
+        for (const sheet of parsed.sheets) {
+            engine.streamWrite(encoder.encode(JSON.stringify({
+                t: "sheet",
+                sheetId: sheet.sheetId,
+                title: sheet.title,
+            }) + "\n"));
+        }
+        for (const [sheetIdKey, rows] of Object.entries(parsed.sheetData)) {
+            const sheetId = Number(sheetIdKey);
+            for (let rowIndex = 0; rowIndex < rows.length; rowIndex++) {
+                const values = rows[rowIndex]?.values;
+                if (!values)
+                    continue;
+                for (let columnIndex = 0; columnIndex < values.length; columnIndex++) {
+                    const cell = values[columnIndex];
+                    if (cell == null)
+                        continue;
+                    // `ue`/`uf`/`ev`/`fv`/`ss` are flattened onto the record alongside the `t`/coords (the
+                    // engine's `StreamRecord` `#[serde(flatten)] cell: CellData`).
+                    engine.streamWrite(encoder.encode(JSON.stringify({
+                        t: "cell",
+                        sheetId,
+                        rowIndex,
+                        columnIndex,
+                        ...cell,
+                    }) + "\n"));
+                }
+            }
+        }
+    }
+    finally {
+        engine.streamEnd();
+    }
+}
+/**
+ * Promote a CSV cell's INFERRED type into its user-entered value. The toolkit's CSV parser puts the
+ * raw text in `ue.sv` and the type-inferred value (e.g. `42`) in the EFFECTIVE value `ev.nv`/`ev.bv`.
+ * The engine, however, re-derives the effective value from `ue` on load and takes `ue.sv` verbatim as
+ * TEXT (it does not re-parse numeric strings, and the supplied `ev` is overwritten by recompute) — so
+ * an inferred number would come back as a string. Copy the inferred `nv`/`bv` onto `ue` so the engine
+ * stores it as the right type. Returns the cell unchanged when nothing was inferred.
+ */
+function csvCellToTypedInput(cell) {
+    const inferred = cell.ev;
+    if (!inferred || cell.ue?.nv != null || cell.ue?.fv != null)
+        return cell;
+    if (inferred.nv != null)
+        return { ...cell, ue: { ...cell.ue, nv: inferred.nv } };
+    if (inferred.bv != null)
+        return { ...cell, ue: { ...cell.ue, bv: inferred.bv } };
+    return cell;
+}
+/**
+ * Shift a 0-indexed `RowData[]` (rows AND columns from 0) into the engine's 1-indexed `SheetData`
+ * row list (index 0 reserved): row `i` moves to slot `i + 1`, and each cell at column `j` moves to
+ * `values[j + 1]`. The toolkit's CSV parser is the only 0-indexed producer here (the XLSX plugin is
+ * already 1-indexed), so this is CSV-only. Each cell's inferred type is promoted onto `ue` via
+ * {@link csvCellToTypedInput} so the engine stores numbers as numbers, not text.
+ */
+function toOneIndexed(rowData) {
+    const out = [null]; // index 0 reserved
+    for (const row of rowData) {
+        const src = row?.values;
+        if (!src) {
+            out.push(null);
+            continue;
+        }
+        const shifted = [null];
+        for (let c = 0; c < src.length; c++) {
+            const cell = src[c];
+            shifted[c + 1] = cell ? csvCellToTypedInput(cell) : null;
+        }
+        out.push({ values: shifted });
+    }
+    return out;
+}
+/**
+ * Import a CSV string (or `File`) into the engine via the toolkit's CSV parser. The CSV becomes a
+ * single sheet (`sheetId` / `title`, both defaultable). Returns the engine.
+ */
+export async function importCsv(csv, options = {}) {
+    const sheetId = options.sheetId ?? 1;
+    const title = options.title ?? "Sheet1";
+    // The toolkit's CSV parser emits 0-INDEXED rows AND columns (`rowData[i].values[j]` for the cell at
+    // row i / col j, both starting at 0). The engine's grid is 1-INDEXED with array index 0 reserved, so
+    // shift both axes up by one before loading (CSV row 0 → engine row 1, column 0 → engine column 1).
+    const rowData = await createRowDataFromCSVString(csv, true, options.locale);
+    const sheetData = { [sheetId]: toOneIndexed(rowData) };
+    const engine = options.engine ?? (await RncEngine.create());
+    const existing = new Set(engine.sheetIds());
+    if (!existing.has(sheetId))
+        engine.addSheet(sheetId, title);
+    engine.load({
+        sheets: [{ sheetId, title }],
+        sheetData,
+    });
+    return engine;
+}
+/**
+ * Build the toolkit-export `{ sheets, sheetData, … }` input by reading the engine back with
+ * `documentFacets` + `sheetExtents` + windowed `readWindow` reads (in `bandRows`-tall bands). Cell
+ * values come from the window (`number` → `ue.nv`, else `formatted` → `ue.sv`) and consolidated
+ * styles are folded onto each cell's `uf`. See the file header for the formula-source caveat.
+ */
+function readEngineForExport(engine, bandRows = 5000) {
+    const facets = engine.documentFacets();
+    const extents = new Map(engine
+        .sheetExtents()
+        .map(([sheetId, rows, cols]) => [sheetId, { rows, cols }]));
+    const sheets = [];
+    const sheetData = {};
+    for (const sheetId of engine.sheetIds()) {
+        sheets.push({ sheetId, title: `Sheet${sheetId}` });
+        const extent = extents.get(sheetId);
+        if (!extent || extent.rows < 1 || extent.cols < 1) {
+            sheetData[sheetId] = [];
+            continue;
+        }
+        const rows = [];
+        const rowAt = (rowIndex) => (rows[rowIndex] ??= { values: [] });
+        for (let bandStart = 1; bandStart <= extent.rows; bandStart += bandRows) {
+            const bandEnd = Math.min(bandStart + bandRows - 1, extent.rows);
+            const snapshot = engine.readWindow(sheetId, bandStart, 1, bandEnd, extent.cols);
+            for (const cell of snapshot.cells) {
+                const cellData = cell.number != null
+                    ? {
+                        ue: { nv: cell.number },
+                        ev: { nv: cell.number },
+                        fv: cell.formatted,
+                    }
+                    : {
+                        ue: { sv: cell.formatted },
+                        ev: { sv: cell.formatted },
+                        fv: cell.formatted,
+                    };
+                rowAt(cell.rowIndex).values[cell.columnIndex] = cellData;
+            }
+            // Fold consolidated styles onto the matching cell's `uf` (the format the exporter reads).
+            for (const style of snapshot.styles) {
+                if (!style.format)
+                    continue;
+                const values = rowAt(style.rowIndex).values;
+                const cellData = (values[style.columnIndex] ??= {});
+                cellData.uf = style.format;
+            }
+        }
+        sheetData[sheetId] = rows;
+    }
+    return {
+        sheets,
+        sheetData,
+        tables: facets.tables,
+        conditionalFormats: facets.conditionalFormats,
+        namedRanges: facets.namedRanges,
+    };
+}
+/**
+ * Export the engine's contents to an XLSX file (a `Uint8Array` of the .xlsx zip) via the toolkit's
+ * `createExcelFile`. Reads VALUES + styles from the engine (see the formula-source caveat in the file
+ * header). `bandRows` controls the row-band height of the windowed reads.
+ */
+export async function exportXlsx(engine, options = {}) {
+    const input = readEngineForExport(engine, options.bandRows);
+    return createExcelFile(input);
+}
+/** Export the engine's contents to an ODS file (a `Uint8Array`) via the toolkit's `createODSFile`
+ * (which returns a raw `ArrayBuffer` — wrapped here so both exporters return a `Uint8Array`). */
+export async function exportOds(engine, options = {}) {
+    const input = readEngineForExport(engine, options.bandRows);
+    return new Uint8Array(await createODSFile(input));
+}
+/**
+ * Export a sheet's display values as RFC-4180 CSV — a thin pass-through to the engine's native
+ * `exportCsv` (already a direct capability; re-exported here so all file I/O lives in one module).
+ */
+export function exportCsv(engine, sheetId) {
+    return engine.exportCsv(sheetId);
+}

package/dist/esm/keys.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Cell-address key helpers — wasm-free so both the engine wrapper and the pure fold reducers can use
+ * them without pulling in the wasm module. The consolidated style-map key MUST match the UI's
+ * `useSheetProperties` `getEffectiveFormat` lookup (`"<sheetId>!<A1>"`).
+ */
+/** 1-indexed column number → A1 column label (`1` → `"A"`, `27` → `"AA"`). */
+export declare function columnLabel(column: number): string;
+/** Consolidated style-map key: `"<sheetId>!<A1>"`, e.g. `(1, 3, 2)` → `"1!B3"`. */
+export declare function cellKey(sheetId: number, row: number, column: number): string;
+/** 1-based column number for an A1 column label (`"A"` → 1, `"AA"` → 27). Inverse of
+ * {@link columnLabel}. */
+export declare function columnNumberFromLabel(label: string): number;
+/** Inverse of {@link cellKey}: `"1!B3"` → `{ sheetId: 1, rowIndex: 3, columnIndex: 2 }`. Returns
+ * `null` for anything that isn't a well-formed key, so callers can skip it rather than guess. */
+export declare function parseCellKey(key: string): {
+    sheetId: number;
+    rowIndex: number;
+    columnIndex: number;
+} | null;
+//# sourceMappingURL=keys.d.ts.map

package/dist/esm/keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/keys.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CASlD;AAED,mFAAmF;AACnF,wBAAgB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;0BAC0B;AAC1B,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED;iGACiG;AACjG,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,GACV;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQnE"}

package/dist/esm/keys.js

@@ -0,0 +1,41 @@
+/**
+ * Cell-address key helpers — wasm-free so both the engine wrapper and the pure fold reducers can use
+ * them without pulling in the wasm module. The consolidated style-map key MUST match the UI's
+ * `useSheetProperties` `getEffectiveFormat` lookup (`"<sheetId>!<A1>"`).
+ */
+/** 1-indexed column number → A1 column label (`1` → `"A"`, `27` → `"AA"`). */
+export function columnLabel(column) {
+    let label = "";
+    let n = column;
+    while (n > 0) {
+        const rem = (n - 1) % 26;
+        label = String.fromCharCode(65 + rem) + label;
+        n = Math.floor((n - 1) / 26);
+    }
+    return label;
+}
+/** Consolidated style-map key: `"<sheetId>!<A1>"`, e.g. `(1, 3, 2)` → `"1!B3"`. */
+export function cellKey(sheetId, row, column) {
+    return `${sheetId}!${columnLabel(column)}${row}`;
+}
+/** 1-based column number for an A1 column label (`"A"` → 1, `"AA"` → 27). Inverse of
+ * {@link columnLabel}. */
+export function columnNumberFromLabel(label) {
+    let n = 0;
+    for (let i = 0; i < label.length; i++) {
+        n = n * 26 + (label.toUpperCase().charCodeAt(i) - 64);
+    }
+    return n;
+}
+/** Inverse of {@link cellKey}: `"1!B3"` → `{ sheetId: 1, rowIndex: 3, columnIndex: 2 }`. Returns
+ * `null` for anything that isn't a well-formed key, so callers can skip it rather than guess. */
+export function parseCellKey(key) {
+    const match = /^(\d+)!([A-Z]+)(\d+)$/.exec(key);
+    if (!match)
+        return null;
+    return {
+        sheetId: Number(match[1]),
+        columnIndex: columnNumberFromLabel(match[2]),
+        rowIndex: Number(match[3]),
+    };
+}

package/dist/esm/move-rescope.d.ts

@@ -0,0 +1,18 @@
+import type { GridRange } from "@rowsncolumns/common-types";
+import type { Command } from "@rowsncolumns/spreadsheet-state";
+import type { DocumentFacets } from "./index";
+/**
+ * Conditional-format and data-validation rules are range-scoped, and the
+ * engine's `move-range` relocates only cells (and tables) — it never
+ * re-scopes rules. Without a follow-up, a cell whose fill/dropdown comes from
+ * a rule loses it the moment it is dragged outside the rule's range, while
+ * its manual `userEnteredFormat` travels fine.
+ *
+ * Given the post-move facets, compute the `update-conditional-format` /
+ * `update-data-validation` follow-up commands that carry the touched rules to
+ * the destination (Excel/Sheets behavior — see {@link rescopeSheetRangesOnMove}
+ * for the exact contract). Untouched rules produce no command, so a move that
+ * grazes no rule emits no engine re-evaluation and no extra undo entry.
+ */
+export declare function rescopeRulesAfterMove(facets: Partial<Pick<DocumentFacets, "conditionalFormats" | "dataValidations">>, sheetId: number, from: GridRange, to: GridRange): Command[];
+//# sourceMappingURL=move-rescope.d.ts.map

package/dist/esm/move-rescope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"move-rescope.d.ts","sourceRoot":"","sources":["../../src/move-rescope.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AAG/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,OAAO,CAAC,IAAI,CAAC,cAAc,EAAE,oBAAoB,GAAG,iBAAiB,CAAC,CAAC,EAC/E,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,SAAS,EACf,EAAE,EAAE,SAAS,GACZ,OAAO,EAAE,CAiCX"}

package/dist/esm/move-rescope.js

@@ -0,0 +1,38 @@
+import { rescopeSheetRangesOnMove } from "@rowsncolumns/utils";
+/**
+ * Conditional-format and data-validation rules are range-scoped, and the
+ * engine's `move-range` relocates only cells (and tables) — it never
+ * re-scopes rules. Without a follow-up, a cell whose fill/dropdown comes from
+ * a rule loses it the moment it is dragged outside the rule's range, while
+ * its manual `userEnteredFormat` travels fine.
+ *
+ * Given the post-move facets, compute the `update-conditional-format` /
+ * `update-data-validation` follow-up commands that carry the touched rules to
+ * the destination (Excel/Sheets behavior — see {@link rescopeSheetRangesOnMove}
+ * for the exact contract). Untouched rules produce no command, so a move that
+ * grazes no rule emits no engine re-evaluation and no extra undo entry.
+ */
+export function rescopeRulesAfterMove(facets, sheetId, from, to) {
+    const commands = [];
+    for (const rule of facets.conditionalFormats ?? []) {
+        const ranges = rescopeSheetRangesOnMove(rule.ranges ?? [], sheetId, from, to);
+        if (ranges) {
+            commands.push({
+                command: "update-conditional-format",
+                ruleId: rule.id,
+                rule: { ranges },
+            });
+        }
+    }
+    for (const rule of facets.dataValidations ?? []) {
+        const ranges = rescopeSheetRangesOnMove(rule.ranges ?? [], sheetId, from, to);
+        if (ranges) {
+            commands.push({
+                command: "update-data-validation",
+                ruleId: rule.id,
+                rule: { ranges },
+            });
+        }
+    }
+    return commands;
+}