@rowsncolumns/y-spreadsheet 14.0.32

package/dist/cjs/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./use-yspreadsheet";
+export * from "./use-yspreadsheet-v2";
+export * from "./helpers";
+export * from "./observables";
+export * from "./types";
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC;AAC9B,cAAc,SAAS,CAAC"}

package/dist/cjs/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./use-yspreadsheet"), exports);
+tslib_1.__exportStar(require("./use-yspreadsheet-v2"), exports);
+tslib_1.__exportStar(require("./helpers"), exports);
+tslib_1.__exportStar(require("./observables"), exports);
+tslib_1.__exportStar(require("./types"), exports);

package/dist/cjs/observables.d.ts

@@ -0,0 +1,10 @@
+import type { Patch } from "immer";
+import { Observable } from "rxjs";
+import type * as Y from "yjs";
+import type { PatchCoordinate, PatchDocument } from "./types";
+import type { YSheetData } from "./use-yspreadsheet-v2";
+export declare const createSheetDataObservable: (ySheetData: Y.Map<YSheetData>) => Observable<Y.YEvent<any>[]>;
+export declare const getPatchDeltasFromEvent: <S extends PatchCoordinate | Patch, T extends PatchDocument<S>>(event: Y.YArrayEvent<T>) => S[];
+export declare const createObservable: <T = PatchDocument>(yArr: Y.Array<T>) => Observable<Y.YArrayEvent<T>>;
+export declare const createDeepObservable: (yArr: Y.Array<any>) => Observable<Y.YEvent<any>[]>;
+//# sourceMappingURL=observables.d.ts.map

package/dist/cjs/observables.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observables.d.ts","sourceRoot":"","sources":["../../observables.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAClC,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAE9B,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD,eAAO,MAAM,yBAAyB,GAAI,YAAY,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,gCAYtE,CAAC;AAEF,eAAO,MAAM,uBAAuB,GAClC,CAAC,SAAS,eAAe,GAAG,KAAK,EACjC,CAAC,SAAS,aAAa,CAAC,CAAC,CAAC,EAE1B,OAAO,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,QAiBxB,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,CAAC,GAAG,aAAa,EAAE,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,iCAYnE,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,gCAYtD,CAAC"}

package/dist/cjs/observables.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeepObservable = exports.createObservable = exports.getPatchDeltasFromEvent = exports.createSheetDataObservable = void 0;
+var tslib_1 = require("tslib");
+var rxjs_1 = require("rxjs");
+var createSheetDataObservable = function (ySheetData) {
+    return new rxjs_1.Observable(function (observer) {
+        var callback = function (events) {
+            observer.next(events);
+        };
+        ySheetData.observeDeep(callback);
+        return function () {
+            ySheetData.unobserveDeep(callback);
+        };
+    });
+};
+exports.createSheetDataObservable = createSheetDataObservable;
+var getPatchDeltasFromEvent = function (event) {
+    var e_1, _a, e_2, _b, e_3, _c;
+    var patches = [];
+    if (event.transaction.origin !== "local") {
+        try {
+            for (var _d = tslib_1.__values(event.changes.delta), _e = _d.next(); !_e.done; _e = _d.next()) {
+                var changes = _e.value;
+                for (var type in changes) {
+                    if (type === "insert" && changes[type] !== undefined) {
+                        try {
+                            for (var _f = (e_2 = void 0, tslib_1.__values(changes[type])), _g = _f.next(); !_g.done; _g = _f.next()) {
+                                var userPatches = _g.value.patches;
+                                try {
+                                    for (var _h = (e_3 = void 0, tslib_1.__values(userPatches)), _j = _h.next(); !_j.done; _j = _h.next()) {
+                                        var patch = _j.value;
+                                        patches.push(patch);
+                                    }
+                                }
+                                catch (e_3_1) { e_3 = { error: e_3_1 }; }
+                                finally {
+                                    try {
+                                        if (_j && !_j.done && (_c = _h.return)) _c.call(_h);
+                                    }
+                                    finally { if (e_3) throw e_3.error; }
+                                }
+                            }
+                        }
+                        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+                        finally {
+                            try {
+                                if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+                            }
+                            finally { if (e_2) throw e_2.error; }
+                        }
+                    }
+                }
+            }
+        }
+        catch (e_1_1) { e_1 = { error: e_1_1 }; }
+        finally {
+            try {
+                if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+            }
+            finally { if (e_1) throw e_1.error; }
+        }
+    }
+    return patches;
+};
+exports.getPatchDeltasFromEvent = getPatchDeltasFromEvent;
+var createObservable = function (yArr) {
+    return new rxjs_1.Observable(function (observer) {
+        var callback = function (event) {
+            observer.next(event);
+        };
+        yArr.observe(callback);
+        return function () {
+            yArr.unobserve(callback);
+        };
+    });
+};
+exports.createObservable = createObservable;
+var createDeepObservable = function (yArr) {
+    return new rxjs_1.Observable(function (observer) {
+        var callback = function (event) {
+            observer.next(event);
+        };
+        yArr.observeDeep(callback);
+        return function () {
+            yArr.unobserveDeep(callback);
+        };
+    });
+};
+exports.createDeepObservable = createDeepObservable;

package/dist/cjs/profiling/batch-profile.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=batch-profile.spec.d.ts.map

package/dist/cjs/profiling/batch-profile.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-profile.spec.d.ts","sourceRoot":"","sources":["../../../profiling/batch-profile.spec.ts"],"names":[],"mappings":""}

package/dist/cjs/profiling/batch-profile.spec.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+var tslib_1 = require("tslib");
+/* @vitest-environment jsdom */
+var react_1 = require("@testing-library/react");
+var vitest_1 = require("vitest");
+var Y = tslib_1.__importStar(require("yjs"));
+var use_yspreadsheet_v2_1 = require("../use-yspreadsheet-v2");
+vitest_1.vi.mock("@rowsncolumns/utils", function (importOriginal) { return tslib_1.__awaiter(void 0, void 0, void 0, function () {
+    var actual;
+    return tslib_1.__generator(this, function (_a) {
+        switch (_a.label) {
+            case 0: return [4 /*yield*/, importOriginal()];
+            case 1:
+                actual = _a.sent();
+                return [2 /*return*/, tslib_1.__assign(tslib_1.__assign({}, actual), { scheduleAfterPaint: function (callback) {
+                            if (typeof requestAnimationFrame === "function") {
+                                var frameId_1 = requestAnimationFrame(function () { return callback(); });
+                                return function () {
+                                    if (typeof cancelAnimationFrame === "function") {
+                                        cancelAnimationFrame(frameId_1);
+                                    }
+                                };
+                            }
+                            var timeoutId = setTimeout(callback, 0);
+                            return function () { return clearTimeout(timeoutId); };
+                        } })];
+        }
+    });
+}); });
+var parseEnvNumber = function (key, fallback) {
+    var value = Number(process.env[key]);
+    return Number.isFinite(value) ? value : fallback;
+};
+var testTimeoutMs = parseEnvNumber("PROFILE_TEST_TIMEOUT_MS", 30000);
+var now = function () {
+    return typeof performance !== "undefined" && typeof performance.now === "function"
+        ? performance.now()
+        : Date.now();
+};
+var createSheetDataPatchBatch = function (sheetId, startRow, rows, columns) {
+    var patches = [];
+    var _loop_1 = function (rowIndex) {
+        var absoluteRow = startRow + rowIndex;
+        var values = Array.from({ length: columns }, function (_, columnIndex) { return ({
+            value: "R".concat(absoluteRow, "C").concat(columnIndex),
+        }); });
+        patches.push([
+            {
+                sheetData: {
+                    patches: [
+                        {
+                            op: "add",
+                            path: [sheetId, absoluteRow],
+                            value: { values: values },
+                        },
+                    ],
+                    inversePatches: [],
+                },
+            },
+            undefined,
+        ]);
+    };
+    for (var rowIndex = 0; rowIndex < rows; rowIndex++) {
+        _loop_1(rowIndex);
+    }
+    return patches;
+};
+var waitForCondition = function (condition_1, timeoutMs_1) {
+    var args_1 = [];
+    for (var _i = 2; _i < arguments.length; _i++) {
+        args_1[_i - 2] = arguments[_i];
+    }
+    return tslib_1.__awaiter(void 0, tslib_1.__spreadArray([condition_1, timeoutMs_1], tslib_1.__read(args_1), false), void 0, function (condition, timeoutMs, intervalMs) {
+        var start;
+        if (intervalMs === void 0) { intervalMs = 25; }
+        return tslib_1.__generator(this, function (_a) {
+            switch (_a.label) {
+                case 0:
+                    start = Date.now();
+                    _a.label = 1;
+                case 1:
+                    if (!(Date.now() - start < timeoutMs)) return [3 /*break*/, 3];
+                    if (condition()) {
+                        return [2 /*return*/];
+                    }
+                    return [4 /*yield*/, new Promise(function (resolve) { return setTimeout(resolve, intervalMs); })];
+                case 2:
+                    _a.sent();
+                    return [3 /*break*/, 1];
+                case 3: throw new Error("Profiling timed out while waiting for condition.");
+            }
+        });
+    });
+};
+(0, vitest_1.describe)("profiling: staggered broadcast patches", function () {
+    (0, vitest_1.it)("profiles large batch updates without data loss", function () { return tslib_1.__awaiter(void 0, void 0, void 0, function () {
+        var sheetId, rowsPerCall, calls, columns, timeoutMs, totalRows, totalPatches, doc, transactSpy, result, memStart, enqueueStart, _loop_2, i, enqueueMs, applyStart, applyMs, sheetData, lastRow, lastValues, lastCell, memEnd, report;
+        var _a, _b;
+        return tslib_1.__generator(this, function (_c) {
+            switch (_c.label) {
+                case 0:
+                    vitest_1.vi.useRealTimers();
+                    sheetId = parseEnvNumber("PROFILE_SHEET_ID", 1);
+                    rowsPerCall = parseEnvNumber("PROFILE_ROWS_PER_CALL", 150);
+                    calls = parseEnvNumber("PROFILE_CALLS", 10);
+                    columns = parseEnvNumber("PROFILE_COLUMNS", 20);
+                    timeoutMs = parseEnvNumber("PROFILE_TIMEOUT_MS", 20000);
+                    totalRows = rowsPerCall * calls;
+                    totalPatches = totalRows;
+                    doc = new Y.Doc();
+                    transactSpy = vitest_1.vi.spyOn(doc, "transact");
+                    result = (0, react_1.renderHook)(function () {
+                        return (0, use_yspreadsheet_v2_1.useYSpreadsheetV2)({
+                            userId: "user-1",
+                            title: "Profiler",
+                            sheetId: sheetId,
+                            doc: doc,
+                            calculateNow: vitest_1.vi.fn(),
+                            initialSheets: [],
+                            onChangeSheetData: vitest_1.vi.fn(),
+                            onChangeSheets: vitest_1.vi.fn(),
+                            onChangeTables: vitest_1.vi.fn(),
+                            enqueueCalculation: vitest_1.vi.fn(),
+                            enqueueGraphOperation: vitest_1.vi.fn(),
+                        });
+                    }).result;
+                    memStart = (_a = process === null || process === void 0 ? void 0 : process.memoryUsage) === null || _a === void 0 ? void 0 : _a.call(process).heapUsed;
+                    enqueueStart = now();
+                    _loop_2 = function (i) {
+                        var batch = createSheetDataPatchBatch(sheetId, i * rowsPerCall, rowsPerCall, columns);
+                        (0, react_1.act)(function () {
+                            result.current.onBroadcastPatch(batch);
+                        });
+                    };
+                    for (i = 0; i < calls; i++) {
+                        _loop_2(i);
+                    }
+                    enqueueMs = now() - enqueueStart;
+                    applyStart = now();
+                    return [4 /*yield*/, waitForCondition(function () {
+                            var sheetData = doc.getMap("sheetDataV2").get(String(sheetId));
+                            return (sheetData === null || sheetData === void 0 ? void 0 : sheetData.length) === totalRows;
+                        }, timeoutMs)];
+                case 1:
+                    _c.sent();
+                    applyMs = now() - applyStart;
+                    sheetData = doc.getMap("sheetDataV2").get(String(sheetId));
+                    lastRow = sheetData === null || sheetData === void 0 ? void 0 : sheetData.get(totalRows - 1);
+                    lastValues = lastRow === null || lastRow === void 0 ? void 0 : lastRow.get("values");
+                    lastCell = lastValues === null || lastValues === void 0 ? void 0 : lastValues.get(columns - 1);
+                    if (!lastCell || lastCell.value !== "R".concat(totalRows - 1, "C").concat(columns - 1)) {
+                        throw new Error("Data loss detected: last cell value mismatch.");
+                    }
+                    memEnd = (_b = process === null || process === void 0 ? void 0 : process.memoryUsage) === null || _b === void 0 ? void 0 : _b.call(process).heapUsed;
+                    report = {
+                        sheetId: sheetId,
+                        calls: calls,
+                        rowsPerCall: rowsPerCall,
+                        columns: columns,
+                        totalRows: totalRows,
+                        totalPatches: totalPatches,
+                        enqueueMs: Math.round(enqueueMs),
+                        applyMs: Math.round(applyMs),
+                        transactBatches: transactSpy.mock.calls.length,
+                        heapDeltaMB: typeof memStart === "number" && typeof memEnd === "number"
+                            ? Math.round(((memEnd - memStart) / 1024 / 1024) * 100) / 100
+                            : "n/a",
+                    };
+                    console.table(report);
+                    return [2 /*return*/];
+            }
+        });
+    }); }, testTimeoutMs);
+});

package/dist/cjs/tsconfig.cjs.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../../helpers.ts","../../index.ts","../../observables.ts","../../types.ts","../../use-yspreadsheet-v2.ts","../../use-yspreadsheet.ts","../../vitest.config.ts","../../profiling/batch-profile.spec.ts"],"version":"5.8.3"}

package/dist/cjs/types.d.ts

@@ -0,0 +1,62 @@
+import type { Patch } from "immer";
+import type { RecalcCellCoordinate } from "@rowsncolumns/spreadsheet-state";
+import type { CellData } from "@rowsncolumns/spreadsheet";
+export type PatchDocument<T = Patch> = {
+    userId: string | number;
+    patches: T[];
+};
+export type PatchRecalcCells = PatchDocument<PatchCoordinate>;
+export type PatchCoordinate = [
+    key: string,
+    position: RecalcCellCoordinate,
+    /**
+     * This is a temporary solution
+     * 1. If source is agent => Agent generates patches for cells that needs recalculation. The UI can recalculate the cells and its dependents
+     * 2. If source is backend => Agent sets effective value of a cell -> The UI recalculate its dependents | Back-end is only to update a formula result
+     * 3. If source is user => Nothing happens Business as usual
+     */
+    source?: "agent" | "user" | "backend"
+];
+/**
+ * V3 Data Structure Types
+ *
+ * V3 uses a flat Map structure for sheet data storage:
+ * - Key format: `${sheetId}!${A1Address}` (e.g., "1!A1", "2!B5")
+ * - Value: CellDataV3 containing cell data and position
+ *
+ * Benefits:
+ * - O(1) cell lookups by key
+ * - Sparse storage (no null padding for empty cells)
+ * - More efficient for large spreadsheets with sparse data
+ */
+/**
+ * V3 cell data structure containing value and flattened position
+ * - value: The cell data
+ * - sId: Sheet ID
+ * - r: Row index (1-based)
+ * - c: Column index (1-based)
+ */
+export type CellDataV3<T extends CellData = CellData> = {
+    value: T;
+    /** Sheet ID */
+    sId: number;
+    /** Row index (1-based) */
+    r: number;
+    /** Column index (1-based) */
+    c: number;
+};
+/**
+ * V3 cell key format: `${sheetId}!${A1Address}`
+ * Examples: "1!A1", "2!B5", "1!AA100"
+ */
+export type CellKeyV3 = string;
+/**
+ * Parsed cell key containing sheet ID and position information
+ */
+export type ParsedCellKeyV3 = {
+    sheetId: number;
+    address: string;
+    rowIndex: number;
+    columnIndex: number;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAC5E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAE1D,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,KAAK,IAAI;IACrC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;IACxB,OAAO,EAAE,CAAC,EAAE,CAAC;CACd,CAAC;AACF,MAAM,MAAM,gBAAgB,GAAG,aAAa,CAAC,eAAe,CAAC,CAAC;AAC9D,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,EAAE,MAAM;IACX,QAAQ,EAAE,oBAAoB;IAC9B;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS;CACtC,CAAC;AAEF;;;;;;;;;;;GAWG;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,QAAQ,GAAG,QAAQ,IAAI;IACtD,KAAK,EAAE,CAAC,CAAC;IACT,eAAe;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,0BAA0B;IAC1B,CAAC,EAAE,MAAM,CAAC;IACV,6BAA6B;IAC7B,CAAC,EAAE,MAAM,CAAC;CACX,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC;AAE/B;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC"}

package/dist/cjs/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/use-yspreadsheet-v2.d.ts

@@ -0,0 +1,152 @@
+import type { HocuspocusProvider } from "@hocuspocus/provider";
+import type { Citation } from "@rowsncolumns/common-types";
+import type { CellInterface, SelectionArea } from "@rowsncolumns/grid";
+import { PivotTable, type CellData, type Collaborator, type ConditionalFormatRule, type DataValidationRuleRecord, type EmbeddedChart, type EmbeddedObject, type NamedRange, type ProtectedRange, type Sheet, type TableView } from "@rowsncolumns/spreadsheet";
+import { type CalculateNowOptions, type CalculationOperation, type CellXfs, type HistoryType, type SheetData, type SharedStrings, type SpreadsheetPatch } from "@rowsncolumns/spreadsheet-state";
+import type { Patch } from "immer";
+import type { WebsocketProvider } from "y-websocket";
+import * as Y from "yjs";
+export type UseYSpreadsheetPropsV2<T extends CellData, S extends Sheet, C extends EmbeddedChart, O extends EmbeddedObject> = {
+    /**
+     * Scopes awareness updates to a single document.
+     *
+     * Multiple Athena editors (sheets, slides, docs) can share a single
+     * awareness channel by writing a `docGuid` field to their local state.
+     * When `awarenessScopeId` is set, this hook:
+     *   - emits `docGuid: awarenessScopeId` on the local state
+     *   - filters incoming states whose `docGuid` does not match
+     *   - states with **no** `docGuid` are treated as a wildcard and accepted
+     *     (so REST writers or older clients that don't set docGuid still
+     *     appear as collaborators)
+     *
+     * Olympus and pptx-studio set this to the asset id; keep the same
+     * convention to remain wire-compatible.
+     */
+    awarenessScopeId?: string;
+    userId: string | number;
+    title: string;
+    sheetId: number;
+    activeCell?: CellInterface;
+    /**
+     * Distinguishes human vs. agent presence. Surfaced on `Collaborator.kind`
+     * so renderers can style agent cursors differently.
+     */
+    kind?: "human" | "agent";
+    /**
+     * For `kind === "agent"`, identifies the human who initiated the agent run
+     * (e.g. "Brendon"). Used to deduplicate agent cursors by initiator and to
+     * label "Athena · Brendon's run" in presence stacks.
+     */
+    agentInitiator?: string;
+    /**
+     * Current selection range(s). When set, collaborators rendered in the grid
+     * receive a range-shaped highlight in addition to the activeCell pin —
+     * needed so agents touching A1:E10 don't appear to be sitting on A1.
+     */
+    selections?: SelectionArea[];
+    provider?: HocuspocusProvider | WebsocketProvider | any;
+    doc: Y.Doc;
+    calculateNow(options?: CalculateNowOptions): Promise<void>;
+    initialSheets: S[];
+    /**
+     * Enable V3 data structure (flat Map<cellKey, CellDataV3>)
+     * V3 uses a sparse map structure with keys like "1!A1" instead of nested arrays
+     * This provides better performance for sparse spreadsheets
+     */
+    useV3?: boolean;
+    /**
+     * Current data version stored in the document ("v2" or "v3")
+     * If using V3 but version is "v2" or undefined, migration will occur
+     * This should be provided by the backend/server
+     */
+    sheetDataVersion?: "v2" | "v3";
+    /**
+     * Called after migration completes so backend can persist the new version
+     */
+    onMigrationComplete?: (newVersion: "v3") => void;
+    /**
+     * Delete V2 data after migrating to V3
+     * Only applies when useV3 is true and migration occurs
+     * Default: false (keeps V2 data for rollback safety)
+     */
+    deleteV2AfterMigration?: boolean;
+    /**
+     * Skip the initial sync process
+     * When true, setupInitialSync will not be called on sync
+     * Useful when you want to handle initial state loading externally
+     * Default: false
+     */
+    skipInitialSync?: boolean;
+    /**
+     * Enable support for legacy shared strings stored as Y.Array.
+     * When enabled, observes both Y.Map (new format) and Y.Array (legacy format)
+     * and merges them into the shared strings state.
+     * Default: false (only observe Y.Map format)
+     */
+    supportLegacySharedStringsArray?: boolean;
+    /**
+     * Get user entered value of a cell
+     * @param sheetId
+     * @param rowIndex
+     * @param columnIndex
+     */
+    getUserEnteredValue?(sheetId: number, rowIndex: number, columnIndex: number): string | undefined | null;
+    /**
+     * Client only functions
+     */
+    clientOnlyFunctionPattern?: RegExp;
+    onChangeActiveSheet?(sheetId: number): void;
+    onChangeSheetData: React.Dispatch<React.SetStateAction<SheetData<T>>>;
+    onChangeTables: React.Dispatch<React.SetStateAction<TableView[]>>;
+    onChangeSheets: React.Dispatch<React.SetStateAction<S[]>>;
+    onChangeCharts?: React.Dispatch<React.SetStateAction<C[]>>;
+    onChangeEmbeds?: React.Dispatch<React.SetStateAction<O[]>>;
+    onChangeNamedRanges?: React.Dispatch<React.SetStateAction<NamedRange[]>>;
+    onChangePivotTables?: React.Dispatch<React.SetStateAction<PivotTable[]>>;
+    onChangeCellXfs?: React.Dispatch<React.SetStateAction<CellXfs | null | undefined>>;
+    onChangeSharedStrings?: React.Dispatch<React.SetStateAction<SharedStrings>>;
+    onChangeProtectedRanges?: React.Dispatch<React.SetStateAction<ProtectedRange[]>>;
+    onChangeConditionalFormats?: React.Dispatch<React.SetStateAction<ConditionalFormatRule[]>>;
+    onChangeDataValidations?: React.Dispatch<React.SetStateAction<DataValidationRuleRecord[]>>;
+    onChangeCitations?: React.Dispatch<React.SetStateAction<Citation[]>>;
+    /**
+     * Called synchronously right after a batch of local patches has been written to the
+     * shared document, inside `onBroadcastPatch` and before it returns to the caller. It
+     * receives the patches that were applied and the document. Purely observational: it
+     * does not alter the write or the patches. Useful for integrity checks, reconciliation,
+     * or telemetry that need to compare local state against the resulting document state at
+     * the moment a local edit is committed. Not called when the broadcast is skipped (e.g.
+     * a non-leader recalc patch). Default: no-op.
+     */
+    onAfterBroadcastPatch?: (patches: [
+        patch: SpreadsheetPatch<Patch>,
+        type?: HistoryType | undefined | null
+    ][], doc: Y.Doc) => void;
+    recalcCellsMaxEntries?: number;
+    enqueueCalculation: (operation: CalculationOperation) => void;
+    enqueueGraphOperation: (operation: CalculationOperation) => void;
+    /**
+     * Re-derives conditional-format / data-validation results for changed
+     * cells (`useSpreadsheetState.reevaluateDerivationsForCells`). Agent- and
+     * backend-sourced recalc patches carry PRE-COMPUTED cell values, so they
+     * only update the dependency graph (no evaluation) — but CF/DV results are
+     * client-owned and the backend never writes them, so without this the
+     * changed cells' conditional formatting stays stale until the user
+     * re-saves a rule in the dialog.
+     */
+    reevaluateDerivationsForCells?: (cells: Array<{
+        sheetId: number;
+        rowIndex: number;
+        columnIndex: number;
+    }>) => void;
+};
+export type YRowData = Y.Map<Y.Array<CellData | null>>;
+export type YSheetData = Y.Array<YRowData | null>;
+export declare const useYSpreadsheetV2: <T extends CellData, S extends Sheet, C extends EmbeddedChart, O extends EmbeddedObject>({ onChangeSheetData, onChangeSheets, onChangeTables, onChangeCharts, onChangeEmbeds, onChangeConditionalFormats, onChangeDataValidations, onChangeCitations, onAfterBroadcastPatch, recalcCellsMaxEntries, onChangeNamedRanges, onChangeProtectedRanges, onChangePivotTables, enqueueCalculation, enqueueGraphOperation, reevaluateDerivationsForCells, onChangeCellXfs, onChangeSharedStrings, calculateNow, onChangeActiveSheet, clientOnlyFunctionPattern, initialSheets, awarenessScopeId, userId, title, sheetId, activeCell, kind, agentInitiator, selections, doc, provider, useV3, sheetDataVersion, onMigrationComplete, deleteV2AfterMigration, skipInitialSync, supportLegacySharedStringsArray, }: UseYSpreadsheetPropsV2<T, S, C, O>) => {
+    synced: boolean;
+    users: Collaborator[];
+    onBroadcastPatch: (patches: [patch: SpreadsheetPatch<Patch>, type?: HistoryType | undefined | null][]) => void;
+    isLeader: boolean;
+    setupInitialSync: () => void;
+};
+//# sourceMappingURL=use-yspreadsheet-v2.d.ts.map

package/dist/cjs/use-yspreadsheet-v2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-yspreadsheet-v2.d.ts","sourceRoot":"","sources":["../../use-yspreadsheet-v2.ts"],"names":[],"mappings":"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"}