@rowsncolumns/y-spreadsheet 14.0.32

package/dist/cjs/use-yspreadsheet-v2.js

@@ -0,0 +1,980 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useYSpreadsheetV2 = void 0;
+var tslib_1 = require("tslib");
+var spreadsheet_1 = require("@rowsncolumns/spreadsheet");
+var utils_1 = require("@rowsncolumns/utils");
+var ui_1 = require("@rowsncolumns/ui");
+var react_1 = require("react");
+var react_dom_1 = require("react-dom");
+var Y = tslib_1.__importStar(require("yjs"));
+var helpers_1 = require("./helpers");
+/**
+ * Convert Y.js events to SheetDataEvent format for incremental processing
+ */
+var convertToSheetDataEvents = function (events) {
+    return events.map(function (event) {
+        var isYArrayEvent = event instanceof Y.YArrayEvent;
+        return {
+            path: event.path,
+            delta: isYArrayEvent
+                ? event.changes.delta
+                : undefined,
+            isYArrayEvent: isYArrayEvent,
+        };
+    });
+};
+/**
+ * Read user entered value directly from Y.js data to avoid race conditions
+ * with React state updates. This is used when recalcCells observer fires
+ * before sheetData observer has updated React state.
+ */
+var getUserEnteredValueFromYDoc = function (ySheetData, sheetId, rowIndex, columnIndex) {
+    var sheet = ySheetData.get(String(sheetId));
+    if (!sheet || rowIndex >= sheet.length)
+        return undefined;
+    var row = sheet.get(rowIndex);
+    if (!row)
+        return undefined;
+    var values = row.get("values");
+    if (!values || columnIndex >= values.length)
+        return undefined;
+    var cell = values.get(columnIndex);
+    // Extract value from ExtendedValue, matching SheetCell.getUserEnteredValue() logic
+    // ue is the abbreviated form of userEnteredValue
+    var userEnteredValue = (0, utils_1.getCellUserEnteredValue)(cell);
+    return (0, utils_1.getExtendedValueFormula)(userEnteredValue);
+};
+/**
+ * Read user entered value from V3 Y.js data structure
+ */
+var getUserEnteredValueFromYDocV3 = function (ySheetDataV3, sheetId, rowIndex, columnIndex) {
+    var cellKey = (0, helpers_1.createCellKeyV3)(sheetId, rowIndex, columnIndex);
+    var cellDataV3 = ySheetDataV3.get(cellKey);
+    return (0, utils_1.getExtendedValueFormula)((0, utils_1.getCellUserEnteredValue)(cellDataV3 === null || cellDataV3 === void 0 ? void 0 : cellDataV3.value));
+};
+var observables_1 = require("./observables");
+// Add a single null entry to the YSheetData
+var origin = "local";
+var useYSpreadsheetV2 = function (_a) {
+    var onChangeSheetData = _a.onChangeSheetData, onChangeSheets = _a.onChangeSheets, onChangeTables = _a.onChangeTables, onChangeCharts = _a.onChangeCharts, onChangeEmbeds = _a.onChangeEmbeds, onChangeConditionalFormats = _a.onChangeConditionalFormats, onChangeDataValidations = _a.onChangeDataValidations, onChangeCitations = _a.onChangeCitations, onAfterBroadcastPatch = _a.onAfterBroadcastPatch, recalcCellsMaxEntries = _a.recalcCellsMaxEntries, onChangeNamedRanges = _a.onChangeNamedRanges, onChangeProtectedRanges = _a.onChangeProtectedRanges, onChangePivotTables = _a.onChangePivotTables, enqueueCalculation = _a.enqueueCalculation, enqueueGraphOperation = _a.enqueueGraphOperation, reevaluateDerivationsForCells = _a.reevaluateDerivationsForCells, onChangeCellXfs = _a.onChangeCellXfs, onChangeSharedStrings = _a.onChangeSharedStrings, calculateNow = _a.calculateNow, onChangeActiveSheet = _a.onChangeActiveSheet, clientOnlyFunctionPattern = _a.clientOnlyFunctionPattern, initialSheets = _a.initialSheets, awarenessScopeId = _a.awarenessScopeId, userId = _a.userId, title = _a.title, sheetId = _a.sheetId, activeCell = _a.activeCell, kind = _a.kind, agentInitiator = _a.agentInitiator, selections = _a.selections, doc = _a.doc, provider = _a.provider, _b = _a.useV3, useV3 = _b === void 0 ? false : _b, _c = _a.sheetDataVersion, sheetDataVersion = _c === void 0 ? "v2" : _c, onMigrationComplete = _a.onMigrationComplete, _d = _a.deleteV2AfterMigration, deleteV2AfterMigration = _d === void 0 ? false : _d, _e = _a.skipInitialSync, skipInitialSync = _e === void 0 ? false : _e, _f = _a.supportLegacySharedStringsArray, supportLegacySharedStringsArray = _f === void 0 ? false : _f;
+    var _g = tslib_1.__read((0, react_1.useState)(false), 2), synced = _g[0], setSynced = _g[1];
+    var _h = tslib_1.__read((0, react_1.useState)([]), 2), users = _h[0], setUsers = _h[1];
+    var _j = tslib_1.__read((0, react_1.useState)(false), 2), isLeader = _j[0], setIsLeader = _j[1];
+    var isLeaderRef = (0, react_1.useRef)(false);
+    var resolvedAwarenessScopeId = awarenessScopeId;
+    // Listen to awareness
+    var awareness = provider === null || provider === void 0 ? void 0 : provider.awareness;
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (!awareness)
+            return;
+        var updateLeader = function () {
+            var entries = Array.from(awareness.getStates().entries());
+            var docStates = resolvedAwarenessScopeId
+                ? entries.filter(function (_a) {
+                    var _b = tslib_1.__read(_a, 2), _ = _b[0], state = _b[1];
+                    return (state === null || state === void 0 ? void 0 : state.docGuid) === resolvedAwarenessScopeId;
+                })
+                : entries;
+            if (!docStates.length) {
+                setIsLeader(false);
+                return;
+            }
+            var states = docStates.map(function (_a) {
+                var _b = tslib_1.__read(_a, 1), clientId = _b[0];
+                return clientId;
+            });
+            var minId = Math.min.apply(Math, tslib_1.__spreadArray([], tslib_1.__read(states), false));
+            // Always include self in the elec
+            setIsLeader(doc.clientID === minId);
+        };
+        awareness.on("change", updateLeader);
+        updateLeader(); // Initial check
+        return function () { return awareness.off("change", updateLeader); };
+    }, [awareness, doc, resolvedAwarenessScopeId]);
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        isLeaderRef.current = isLeader;
+    }, [isLeader]);
+    var ySheetDataV2 = (0, react_1.useMemo)(function () { return doc.getMap("sheetDataV2"); }, [doc]);
+    // V3: Flat map structure - Map<cellKey, CellDataV3>
+    // cellKey format: `${sheetId}!${A1Address}` (e.g., "1!A1", "2!B5")
+    var ySheetDataV3 = (0, react_1.useMemo)(function () { return doc.getMap("sheetDataV3"); }, [doc]);
+    // Doc metadata - used as fallback for version when prop is undefined
+    var yDocMeta = (0, react_1.useMemo)(function () { return doc.getMap("docMeta"); }, [doc]);
+    var yDisableRecalc = (0, react_1.useMemo)(function () { return doc.getMap("disableRecalc"); }, [doc]);
+    // Recalc cells
+    var yRecalcCells = (0, react_1.useMemo)(function () { return doc.getArray("recalcCells"); }, [doc]);
+    // Make sure initialSheets is always filled
+    var getInitialSheets = (0, react_1.useCallback)(function () {
+        if (initialSheets.length) {
+            return initialSheets;
+        }
+        return [(0, spreadsheet_1.createNewSheet)(1, "Sheet1")];
+    }, [initialSheets]);
+    // cellxfs
+    var yCellXfs = (0, react_1.useMemo)(function () { return doc.getMap("cellXfs"); }, [doc]);
+    // Shared strings - always use Map for new storage, Array kept for migration
+    var ySharedStringsArray = (0, react_1.useMemo)(function () { return doc.getArray("sharedStrings"); }, [doc]);
+    var ySharedStringsMap = (0, react_1.useMemo)(function () { return doc.getMap("sharedStringsMap"); }, [doc]);
+    // Track if initial sync has changed active sheet
+    var isActiveSheetChanged = (0, react_1.useRef)(false);
+    /**
+     * Handle shared strings updates from the Y.Map (new format).
+     * Merges incoming Map entries into the current shared strings state.
+     * Used for documents that store shared strings in the Map format.
+     */
+    var handleSharedStringsMapChange = (0, react_1.useCallback)(function (value) {
+        onChangeSharedStrings === null || onChangeSharedStrings === void 0 ? void 0 : onChangeSharedStrings(function (currentMap) {
+            var e_1, _a;
+            var newMap = new Map(currentMap);
+            try {
+                for (var value_1 = tslib_1.__values(value), value_1_1 = value_1.next(); !value_1_1.done; value_1_1 = value_1.next()) {
+                    var _b = tslib_1.__read(value_1_1.value, 2), key = _b[0], val = _b[1];
+                    newMap.set(key, val);
+                }
+            }
+            catch (e_1_1) { e_1 = { error: e_1_1 }; }
+            finally {
+                try {
+                    if (value_1_1 && !value_1_1.done && (_a = value_1.return)) _a.call(value_1);
+                }
+                finally { if (e_1) throw e_1.error; }
+            }
+            return newMap;
+        });
+    }, [onChangeSharedStrings]);
+    /**
+     * Handle shared strings updates from the Y.Array (legacy format).
+     * Converts array indices to string keys and merges into current state.
+     * Provides backwards compatibility for older documents using array storage.
+     */
+    var handleSharedStringsArrayChange = (0, react_1.useCallback)(function (value) {
+        onChangeSharedStrings === null || onChangeSharedStrings === void 0 ? void 0 : onChangeSharedStrings(function (currentMap) {
+            var newMap = new Map(currentMap);
+            value.forEach(function (v, index) {
+                newMap.set(String(index), v);
+            });
+            return newMap;
+        });
+    }, [onChangeSharedStrings]);
+    var documentMap = (0, react_1.useMemo)(function () {
+        var entries = tslib_1.__spreadArray([
+            ["sheets", [doc.getArray("sheets"), onChangeSheets]],
+            ["tables", [doc.getArray("tables"), onChangeTables]],
+            [
+                "embeds",
+                [doc.getArray("embeds"), onChangeEmbeds],
+            ],
+            [
+                "charts",
+                [doc.getArray("charts"), onChangeCharts],
+            ],
+            [
+                "conditionalFormats",
+                [
+                    doc.getArray("conditionalFormats"),
+                    onChangeConditionalFormats,
+                ],
+            ],
+            [
+                "dataValidations",
+                [
+                    doc.getArray("dataValidations"),
+                    onChangeDataValidations,
+                ],
+            ],
+            [
+                "pivotTables",
+                [doc.getArray("pivotTables"), onChangePivotTables],
+            ],
+            [
+                "namedRanges",
+                [doc.getArray("namedRanges"), onChangeNamedRanges],
+            ],
+            [
+                "protectedRanges",
+                [
+                    doc.getArray("protectedRanges"),
+                    onChangeProtectedRanges,
+                ],
+            ],
+            [
+                "citations",
+                [doc.getArray("citations"), onChangeCitations],
+            ],
+            [
+                "sharedStrings",
+                [ySharedStringsMap, handleSharedStringsMapChange],
+            ]
+        ], tslib_1.__read((supportLegacySharedStringsArray
+            ? [
+                [
+                    "sharedStringsArray",
+                    [ySharedStringsArray, handleSharedStringsArrayChange],
+                ],
+            ]
+            : [])), false);
+        return new Map(entries);
+    }, [
+        doc,
+        onChangeSheets,
+        onChangeTables,
+        onChangeEmbeds,
+        onChangeCharts,
+        onChangeConditionalFormats,
+        onChangeDataValidations,
+        onChangePivotTables,
+        onChangeNamedRanges,
+        onChangeProtectedRanges,
+        onChangeCitations,
+        ySharedStringsMap,
+        handleSharedStringsMapChange,
+        supportLegacySharedStringsArray,
+        ySharedStringsArray,
+        handleSharedStringsArrayChange,
+    ]);
+    // Get backlog of recalc cells from backend
+    var getBacklog = (0, react_1.useCallback)(function () {
+        return yRecalcCells
+            .toArray()
+            .flatMap(function (entry) { return entry.patches; })
+            .filter(function (_a) {
+            var _b = tslib_1.__read(_a, 3), source = _b[2];
+            return source === "backend" || source === "agent";
+        });
+    }, [yRecalcCells]);
+    // Trigger cell recalcs
+    var syncRecalcCells = (0, react_1.useCallback)(function (recalcCells, origin) {
+        var e_2, _a;
+        try {
+            for (var recalcCells_1 = tslib_1.__values(recalcCells), recalcCells_1_1 = recalcCells_1.next(); !recalcCells_1_1.done; recalcCells_1_1 = recalcCells_1.next()) {
+                var _b = tslib_1.__read(recalcCells_1_1.value, 3), _1 = _b[0], position = _b[1], source = _b[2];
+                // backend will calculate results
+                var isAgent = source === "agent"; // Agent already does the calculation
+                // Read directly from Y.js to avoid race condition where recalcCells
+                // observer fires before sheetData observer has updated React state
+                var formulaValue = useV3
+                    ? getUserEnteredValueFromYDocV3(ySheetDataV3, position.sheetId, position.rowIndex, position.columnIndex)
+                    : getUserEnteredValueFromYDoc(ySheetDataV2, position.sheetId, position.rowIndex, position.columnIndex);
+                // Was this from a changeBatch event in the back-end?
+                // To support client functions to run only
+                var isChangeBatch = position.force && isAgent;
+                var isClientOnly = !(0, utils_1.isNil)(formulaValue) &&
+                    !(0, utils_1.isNil)(clientOnlyFunctionPattern) &&
+                    (0, utils_1.isAFormula)(formulaValue)
+                    ? clientOnlyFunctionPattern.test(String(formulaValue))
+                    : false;
+                /**
+                 * Determines whether to force immediate execution of the operation.
+                 *
+                 * Force execution is allowed only for leaders and under these conditions:
+                 * - No source specified (backwards compatibility - treats as force exec)
+                 * - Source is "backend" (backend-initiated changes)
+                 * - Client-only mode with change batch (batch operations need immediate execution)
+                 *
+                 * Note: Agent sources never force execution since they've pre-calculated results.
+                 */
+                var forceExecution = isLeaderRef.current &&
+                    (!source || // backwards compatible: no source means force exec for leader
+                        source === "backend" ||
+                        (isClientOnly && isChangeBatch));
+                var enqueue = forceExecution
+                    ? enqueueCalculation
+                    : enqueueGraphOperation;
+                /**
+                 * Selects the appropriate queue function for the operation.
+                 *
+                 * - enqueueCalculation: Used when forcing execution (immediate formula evaluation)
+                 * - enqueueGraphOperation: Used for normal graph operations (no formula evaluation)
+                 */
+                enqueue === null || enqueue === void 0 ? void 0 : enqueue({
+                    type: "add",
+                    position: position,
+                    source: source,
+                    force: forceExecution,
+                });
+            }
+        }
+        catch (e_2_1) { e_2 = { error: e_2_1 }; }
+        finally {
+            try {
+                if (recalcCells_1_1 && !recalcCells_1_1.done && (_a = recalcCells_1.return)) _a.call(recalcCells_1);
+            }
+            finally { if (e_2) throw e_2.error; }
+        }
+        // The agent/backend pre-computes cell VALUES (hence the graph-only
+        // enqueues above), but conditional-format / data-validation RESULTS
+        // are derived on the client — re-evaluate them for the changed cells
+        // so their paint tracks the new values.
+        if (recalcCells.length) {
+            reevaluateDerivationsForCells === null || reevaluateDerivationsForCells === void 0 ? void 0 : reevaluateDerivationsForCells(recalcCells.map(function (_a) {
+                var _b = tslib_1.__read(_a, 2), position = _b[1];
+                return ({
+                    sheetId: position.sheetId,
+                    rowIndex: position.rowIndex,
+                    columnIndex: position.columnIndex,
+                });
+            }));
+        }
+    }, [
+        synced,
+        clientOnlyFunctionPattern,
+        ySheetDataV2,
+        ySheetDataV3,
+        useV3,
+        reevaluateDerivationsForCells,
+    ]);
+    // Setup initial sync
+    var setupInitialSync = (0, react_1.useCallback)(function () {
+        var e_3, _a;
+        var _b;
+        // Migration from sharedStrings (Array) to sharedStringsMap (Map) is disabled.
+        // Both formats are now supported simultaneously via handleSharedStringsMapChange
+        // and handleSharedStringsArrayChange callbacks.
+        var arrayData = ySharedStringsArray.toArray();
+        var mapData = ySharedStringsMap.toJSON();
+        var hasArrayData = arrayData.length > 0;
+        var isMapEmpty = Object.keys(mapData).length === 0;
+        // Migrate if array has data and map is empty
+        if (!supportLegacySharedStringsArray && hasArrayData && isMapEmpty) {
+            doc.transact(function () {
+                // Convert array to map with string keys
+                arrayData.forEach(function (value, index) {
+                    ySharedStringsMap.set(String(index), value);
+                });
+                // Optional: Clear the old array to save space
+                // Uncomment if you want to remove old data after migration
+                // ySharedStringsArray.delete(0, ySharedStringsArray.length);
+            }, "migration");
+        }
+        try {
+            for (var _c = tslib_1.__values(documentMap.entries()), _d = _c.next(); !_d.done; _d = _c.next()) {
+                var _e = tslib_1.__read(_d.value, 2), mappingKey = _e[0], _f = tslib_1.__read(_e[1], 2), ydoc = _f[0], callback = _f[1];
+                var value = ydoc.toJSON();
+                if (mappingKey === "sheets") {
+                    var sheets = (Array.isArray(value) && value.length
+                        ? (0, helpers_1.validateSheets)(value)
+                        : getInitialSheets());
+                    callback === null || callback === void 0 ? void 0 : callback(sheets);
+                    // Set active sheet id
+                    if (sheets.length && !isActiveSheetChanged.current) {
+                        onChangeActiveSheet === null || onChangeActiveSheet === void 0 ? void 0 : onChangeActiveSheet((0, utils_1.sortSheetsByIndex)(sheets)[0].sheetId);
+                        isActiveSheetChanged.current = true;
+                    }
+                }
+                else if (mappingKey === "sharedStrings") {
+                    // Convert Map object to Map instance for shared strings
+                    var sharedStringsMap = new Map(Object.entries(value !== null && value !== void 0 ? value : {}));
+                    callback === null || callback === void 0 ? void 0 : callback(sharedStringsMap);
+                }
+                else {
+                    callback === null || callback === void 0 ? void 0 : callback(value);
+                }
+            }
+        }
+        catch (e_3_1) { e_3 = { error: e_3_1 }; }
+        finally {
+            try {
+                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+            }
+            finally { if (e_3) throw e_3.error; }
+        }
+        // Load sheet data based on V2 or V3 mode
+        if (useV3) {
+            // Check if we need to migrate from V2 to V3
+            // Use prop if provided, otherwise fall back to yDocMeta for backwards compatibility
+            var resolvedVersion = sheetDataVersion !== null && sheetDataVersion !== void 0 ? sheetDataVersion : yDocMeta.get("sheetDataVersion");
+            if (resolvedVersion !== "v3") {
+                var v2Data_1 = ySheetDataV2.toJSON();
+                var hasV2Data = Object.keys(v2Data_1).length > 0;
+                if (hasV2Data) {
+                    // Migrate V2 data to V3
+                    doc.transact(function () {
+                        var e_4, _a, e_5, _b;
+                        var v3Data = (0, helpers_1.sheetDataV2ToV3)(v2Data_1);
+                        try {
+                            // Add all V3 entries to the Y.Map
+                            for (var _c = tslib_1.__values(v3Data.entries()), _d = _c.next(); !_d.done; _d = _c.next()) {
+                                var _e = tslib_1.__read(_d.value, 2), key = _e[0], cellData = _e[1];
+                                ySheetDataV3.set(key, cellData);
+                            }
+                        }
+                        catch (e_4_1) { e_4 = { error: e_4_1 }; }
+                        finally {
+                            try {
+                                if (_d && !_d.done && (_a = _c.return)) _a.call(_c);
+                            }
+                            finally { if (e_4) throw e_4.error; }
+                        }
+                        // Optionally clear V2 data after migration
+                        if (deleteV2AfterMigration) {
+                            try {
+                                for (var _f = tslib_1.__values(ySheetDataV2.keys()), _g = _f.next(); !_g.done; _g = _f.next()) {
+                                    var sheetId_1 = _g.value;
+                                    ySheetDataV2.delete(sheetId_1);
+                                }
+                            }
+                            catch (e_5_1) { e_5 = { error: e_5_1 }; }
+                            finally {
+                                try {
+                                    if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+                                }
+                                finally { if (e_5) throw e_5.error; }
+                            }
+                        }
+                    }, "migrate-v2-to-v3");
+                    // Notify backend that migration completed
+                    onMigrationComplete === null || onMigrationComplete === void 0 ? void 0 : onMigrationComplete("v3");
+                }
+                else {
+                    // No V2 data, notify backend of version
+                    onMigrationComplete === null || onMigrationComplete === void 0 ? void 0 : onMigrationComplete("v3");
+                }
+            }
+            // V3: Convert flat map to V2 format for React state
+            var v3Data = ySheetDataV3.toJSON();
+            var v3Map = new Map(Object.entries(v3Data));
+            onChangeSheetData === null || onChangeSheetData === void 0 ? void 0 : onChangeSheetData((0, helpers_1.sheetDataV3ToV2)(v3Map));
+        }
+        else {
+            onChangeSheetData === null || onChangeSheetData === void 0 ? void 0 : onChangeSheetData(ySheetDataV2.toJSON());
+        }
+        // Cellxfs
+        var cellXfs = new Map(Object.entries((_b = yCellXfs.toJSON()) !== null && _b !== void 0 ? _b : {}));
+        onChangeCellXfs === null || onChangeCellXfs === void 0 ? void 0 : onChangeCellXfs(cellXfs);
+    }, [
+        documentMap,
+        onChangeCellXfs,
+        onChangeSheetData,
+        ySheetDataV2,
+        ySheetDataV3,
+        yDocMeta,
+        yCellXfs,
+        getInitialSheets,
+        onChangeActiveSheet,
+        ySharedStringsArray,
+        ySharedStringsMap,
+        doc,
+        useV3,
+        sheetDataVersion,
+        onMigrationComplete,
+        deleteV2AfterMigration,
+    ]);
+    // Synced
+    var onSynced = (0, react_1.useCallback)(function () {
+        if (!synced) {
+            if (!skipInitialSync) {
+                // Use flushSync to ensure React state is updated before continuing
+                // This guarantees sheetData is available when syncRecalcCells runs
+                (0, react_dom_1.flushSync)(function () {
+                    setupInitialSync();
+                });
+                // Build dependency graph, then sync backlog cells
+                requestAnimationFrame(function () { return tslib_1.__awaiter(void 0, void 0, void 0, function () {
+                    var backlog;
+                    return tslib_1.__generator(this, function (_a) {
+                        switch (_a.label) {
+                            case 0: return [4 /*yield*/, calculateNow({
+                                    disableEvaluation: true,
+                                    shouldResetCellDependencyGraph: true,
+                                })];
+                            case 1:
+                                _a.sent();
+                                backlog = getBacklog();
+                                if (backlog.length) {
+                                    syncRecalcCells(backlog, "backend");
+                                    // Clear processed backlog entries from yRecalcCells
+                                    doc.transact(function () {
+                                        yRecalcCells.delete(0, yRecalcCells.length);
+                                    }, origin);
+                                }
+                                return [2 /*return*/];
+                        }
+                    });
+                }); });
+            }
+            setSynced(true);
+        }
+    }, [
+        calculateNow,
+        setupInitialSync,
+        synced,
+        syncRecalcCells,
+        getBacklog,
+        doc,
+        yRecalcCells,
+        skipInitialSync,
+    ]);
+    // Sync state
+    if ((provider === null || provider === void 0 ? void 0 : provider.synced) && !synced) {
+        onSynced();
+    }
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        provider === null || provider === void 0 ? void 0 : provider.on("synced", onSynced);
+        return function () {
+            provider === null || provider === void 0 ? void 0 : provider.off("synced", onSynced);
+        };
+    }, [provider]);
+    // Only for sheet Data (V2 mode)
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (useV3)
+            return; // Skip V2 observer in V3 mode
+        // Subscribe to sheet data
+        var subscription = (0, observables_1.createSheetDataObservable)(ySheetDataV2).subscribe(function (events) {
+            var _a, _b;
+            /**
+             * Disable recalc is a flag that is set ONLY locally
+             * when a calculation completes
+             *
+             * This is to prevent yjs from observing sheetdata
+             * and updating it, which is not necessary
+             */
+            if (events.length) {
+                var origin_1 = (_b = (_a = events === null || events === void 0 ? void 0 : events[0]) === null || _a === void 0 ? void 0 : _a.transaction) === null || _b === void 0 ? void 0 : _b.origin;
+                if (origin_1 !== "local") {
+                    // Convert Y.js events to SheetDataEvent format and apply incremental updates
+                    var sheetDataEvents_1 = convertToSheetDataEvents(events);
+                    onChangeSheetData(function (prevSheetData) {
+                        var result = (0, helpers_1.processSheetDataEvents)(sheetDataEvents_1, prevSheetData, ySheetDataV2);
+                        // Fall back to full serialization only if incremental update fails
+                        return result !== null && result !== void 0 ? result : ySheetDataV2.toJSON();
+                    });
+                }
+            }
+        });
+        return function () {
+            subscription.unsubscribe();
+        };
+    }, [onChangeSheetData, ySheetDataV2, useV3]);
+    // Only for sheet Data (V3 mode)
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (!useV3)
+            return; // Skip V3 observer in V2 mode
+        // Subscribe to V3 sheet data (flat Map)
+        var callback = function (event) {
+            if (event.transaction.origin !== "local") {
+                // Extract changes synchronously - Yjs requires accessing event.changes
+                // within the event handler, not in a deferred callback like setState
+                var changedKeys_1 = new Map();
+                event.changes.keys.forEach(function (change, key) {
+                    changedKeys_1.set(key, { action: change.action });
+                });
+                // Now we can safely use the extracted data in the async setState callback
+                onChangeSheetData(function (prevSheetData) {
+                    var result = (0, helpers_1.processSheetDataEventsV3)(changedKeys_1, prevSheetData, ySheetDataV3);
+                    if (result) {
+                        return result;
+                    }
+                    // Fall back to full conversion
+                    var v3Data = ySheetDataV3.toJSON();
+                    var v3Map = new Map(Object.entries(v3Data));
+                    return (0, helpers_1.sheetDataV3ToV2)(v3Map);
+                });
+            }
+        };
+        ySheetDataV3.observe(callback);
+        return function () {
+            ySheetDataV3.unobserve(callback);
+        };
+    }, [onChangeSheetData, ySheetDataV3, useV3]);
+    // CellXfs
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        // Subscribe to sheet data
+        var callback = function (event) {
+            var _a;
+            if (event.transaction.origin !== "local") {
+                var cellXfs = new Map(Object.entries((_a = yCellXfs.toJSON()) !== null && _a !== void 0 ? _a : {}));
+                onChangeCellXfs === null || onChangeCellXfs === void 0 ? void 0 : onChangeCellXfs(cellXfs);
+            }
+        };
+        yCellXfs.observe(callback);
+        return function () {
+            yCellXfs.unobserve(callback);
+        };
+    }, [onChangeCellXfs, yCellXfs]);
+    // All others
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        var e_6, _a;
+        var subs = [];
+        var _loop_1 = function (mappingKey, ydoc, callback) {
+            // Only observe Arrays (shared strings Map is handled separately if needed)
+            if (ydoc instanceof Y.Array) {
+                var subscription = (0, observables_1.createDeepObservable)(ydoc).subscribe(function (events) {
+                    var e_7, _a;
+                    var _b;
+                    try {
+                        for (var events_1 = (e_7 = void 0, tslib_1.__values(events)), events_1_1 = events_1.next(); !events_1_1.done; events_1_1 = events_1.next()) {
+                            var event_1 = events_1_1.value;
+                            if (event_1.transaction.origin !== "local") {
+                                var json = ydoc.toJSON();
+                                if (Array.isArray(json) &&
+                                    json.length &&
+                                    ((_b = json[0]) === null || _b === void 0 ? void 0 : _b.userId)) {
+                                    continue;
+                                }
+                                callback === null || callback === void 0 ? void 0 : callback(json);
+                            }
+                        }
+                    }
+                    catch (e_7_1) { e_7 = { error: e_7_1 }; }
+                    finally {
+                        try {
+                            if (events_1_1 && !events_1_1.done && (_a = events_1.return)) _a.call(events_1);
+                        }
+                        finally { if (e_7) throw e_7.error; }
+                    }
+                });
+                subs.push(subscription);
+            }
+            else if (ydoc instanceof Y.Map && mappingKey === "sharedStrings") {
+                // Handle shared strings Map observation
+                var callback_map_1 = function (event) {
+                    if (event.transaction.origin !== "local") {
+                        var json = ydoc.toJSON();
+                        var sharedStringsMap = new Map(Object.entries(json !== null && json !== void 0 ? json : {}));
+                        callback === null || callback === void 0 ? void 0 : callback(sharedStringsMap);
+                    }
+                };
+                ydoc.observe(callback_map_1);
+                subs.push({
+                    unsubscribe: function () { return ydoc.unobserve(callback_map_1); },
+                });
+            }
+        };
+        try {
+            for (var _b = tslib_1.__values(documentMap.entries()), _c = _b.next(); !_c.done; _c = _b.next()) {
+                var _d = tslib_1.__read(_c.value, 2), mappingKey = _d[0], _e = tslib_1.__read(_d[1], 2), ydoc = _e[0], callback = _e[1];
+                _loop_1(mappingKey, ydoc, callback);
+            }
+        }
+        catch (e_6_1) { e_6 = { error: e_6_1 }; }
+        finally {
+            try {
+                if (_c && !_c.done && (_a = _b.return)) _a.call(_b);
+            }
+            finally { if (e_6) throw e_6.error; }
+        }
+        return function () {
+            subs.forEach(function (sub) { return sub.unsubscribe(); });
+        };
+    }, [documentMap]);
+    // Only for recalc cells
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (!synced) {
+            return;
+        }
+        // Sync all cells that are updated in the backend
+        // // Observe recalc cells separat
+        var onRecalcCellsChange = function (event) {
+            var patches = (0, observables_1.getPatchDeltasFromEvent)(event);
+            var origin = event.transaction.origin;
+            if (origin !== "local") {
+                requestAnimationFrame(function () {
+                    syncRecalcCells(patches, origin);
+                });
+            }
+        };
+        // Skip the first recalc cells change
+        var sub = (0, observables_1.createObservable)(yRecalcCells).subscribe(onRecalcCellsChange);
+        return function () { return sub.unsubscribe(); };
+    }, [syncRecalcCells, recalcCellsMaxEntries, synced, yRecalcCells]);
+    // Broadcast patch
+    var onBroadcastPatch = (0, react_1.useCallback)(function (patches) {
+        var e_8, _a, e_9, _b;
+        var _c;
+        // Ignore push flag
+        var disableRecalc = Boolean(patches.find(function (_a) {
+            var _b = tslib_1.__read(_a, 1), patch = _b[0];
+            return patch === null || patch === void 0 ? void 0 : patch.disableRecalc;
+        }));
+        // Check if this is a full recalc
+        var isFullRecalc = Boolean(patches.find(function (_a) {
+            var _b = tslib_1.__read(_a, 1), patch = _b[0];
+            return patch === null || patch === void 0 ? void 0 : patch.isFullRecalc;
+        }));
+        var disableSync = isFullRecalc ? false : disableRecalc && !isLeader;
+        // Only leader can broadcast recalc patches. Error effective values are
+        // the exception: async custom-function failures (#VALUE!, #NAME?, …)
+        // only exist as disableRecalc calc-result patches, and the leader's
+        // write is deferred/lossy — if non-leaders drop them too, the error
+        // paints during the live session but the cell is blank after reload.
+        // Sync just the error-bearing cell patches; ordinary recalc results
+        // stay leader-gated so N clients don't all write identical results.
+        if (disableSync) {
+            var errorCellPatches = [];
+            try {
+                for (var patches_1 = tslib_1.__values(patches), patches_1_1 = patches_1.next(); !patches_1_1.done; patches_1_1 = patches_1.next()) {
+                    var _d = tslib_1.__read(patches_1_1.value, 2), patch = _d[0], _e = _d[1], type = _e === void 0 ? "redo" : _e;
+                    if (!(patch === null || patch === void 0 ? void 0 : patch.sheetData)) {
+                        continue;
+                    }
+                    type = type !== null && type !== void 0 ? type : "redo";
+                    var patchKey = type === "redo" ? "patches" : "inversePatches";
+                    var sheetDataPatches = patch.sheetData[patchKey];
+                    if (sheetDataPatches === null || sheetDataPatches === void 0 ? void 0 : sheetDataPatches.length) {
+                        errorCellPatches.push.apply(errorCellPatches, tslib_1.__spreadArray([], tslib_1.__read((0, helpers_1.filterErrorCellPatches)(sheetDataPatches)), false));
+                    }
+                }
+            }
+            catch (e_8_1) { e_8 = { error: e_8_1 }; }
+            finally {
+                try {
+                    if (patches_1_1 && !patches_1_1.done && (_a = patches_1.return)) _a.call(patches_1);
+                }
+                finally { if (e_8) throw e_8.error; }
+            }
+            // Containment for this non-leader write path: an error may only
+            // fill a cell with no effective value (the blank-after-reload case)
+            // or replace an existing error — never a non-error result; a cell
+            // whose formula (ue) changed since the calculation started is
+            // skipped; identical persisted errors are skipped so concurrent
+            // non-leaders don't append redundant Y.js updates; and a proceeding
+            // write merges ONLY the error effective value into the existing doc
+            // cell, preserving every other persisted field.
+            var persistableErrorCellPatches_1 = [];
+            try {
+                for (var errorCellPatches_1 = tslib_1.__values(errorCellPatches), errorCellPatches_1_1 = errorCellPatches_1.next(); !errorCellPatches_1_1.done; errorCellPatches_1_1 = errorCellPatches_1.next()) {
+                    var errorPatch = errorCellPatches_1_1.value;
+                    var _f = tslib_1.__read(errorPatch.path, 4), patchSheetId = _f[0], rowIndex = _f[1], columnIndex = _f[3];
+                    var currentCellData = useV3
+                        ? (_c = ySheetDataV3.get((0, helpers_1.createCellKeyV3)(Number(patchSheetId), Number(rowIndex), Number(columnIndex)))) === null || _c === void 0 ? void 0 : _c.value
+                        : (0, helpers_1.getCellDataFromYSheetData)(ySheetDataV2, patchSheetId, Number(rowIndex), Number(columnIndex));
+                    var incomingCellData = errorPatch.value;
+                    if (!(0, helpers_1.shouldPersistErrorCellPatch)(currentCellData, incomingCellData)) {
+                        continue;
+                    }
+                    persistableErrorCellPatches_1.push(tslib_1.__assign(tslib_1.__assign({}, errorPatch), { value: (0, helpers_1.mergeErrorEffectiveValueIntoCellData)(currentCellData, incomingCellData) }));
+                }
+            }
+            catch (e_9_1) { e_9 = { error: e_9_1 }; }
+            finally {
+                try {
+                    if (errorCellPatches_1_1 && !errorCellPatches_1_1.done && (_b = errorCellPatches_1.return)) _b.call(errorCellPatches_1);
+                }
+                finally { if (e_9) throw e_9.error; }
+            }
+            if (persistableErrorCellPatches_1.length) {
+                doc.transact(function () {
+                    if (useV3) {
+                        (0, helpers_1.addSheetDataPatchesV3)(ySheetDataV3, persistableErrorCellPatches_1);
+                    }
+                    else {
+                        (0, helpers_1.addSheetDataPatches)(ySheetDataV2, persistableErrorCellPatches_1);
+                    }
+                }, origin);
+            }
+            return;
+        }
+        doc.transact(function () {
+            var e_10, _a, e_11, _b;
+            var _c, _d, _e, _f;
+            try {
+                for (var patches_2 = tslib_1.__values(patches), patches_2_1 = patches_2.next(); !patches_2_1.done; patches_2_1 = patches_2.next()) {
+                    var _g = tslib_1.__read(patches_2_1.value, 2), patch = _g[0], _h = _g[1], type = _h === void 0 ? "redo" : _h;
+                    // Check for existence of patch
+                    // Investigate when when importing csv, it create a [undefined, undefined] patch object
+                    // todo @Vinay
+                    if (!patch) {
+                        continue;
+                    }
+                    type = type !== null && type !== void 0 ? type : "redo";
+                    var patchKey = type === "redo" ? "patches" : "inversePatches";
+                    if (patch.sheetData) {
+                        var patches_3 = (_c = patch.sheetData) === null || _c === void 0 ? void 0 : _c[patchKey];
+                        if (useV3) {
+                            (0, helpers_1.addSheetDataPatchesV3)(ySheetDataV3, patches_3);
+                        }
+                        else {
+                            (0, helpers_1.addSheetDataPatches)(ySheetDataV2, patches_3);
+                        }
+                    }
+                    if (patch.cellXfs) {
+                        var patches_4 = (_d = patch.cellXfs) === null || _d === void 0 ? void 0 : _d[patchKey];
+                        (0, helpers_1.applyMapPatches)(yCellXfs, patches_4);
+                    }
+                    try {
+                        for (var _j = (e_11 = void 0, tslib_1.__values(documentMap.entries())), _k = _j.next(); !_k.done; _k = _j.next()) {
+                            var _l = tslib_1.__read(_k.value, 2), mappingKey = _l[0], _m = tslib_1.__read(_l[1], 1), ydoc = _m[0];
+                            if (patch === null || patch === void 0 ? void 0 : patch[mappingKey]) {
+                                var patches_5 = (_e = patch[mappingKey]) === null || _e === void 0 ? void 0 : _e[patchKey];
+                                // Handle shared strings Map (always use Map now)
+                                if (mappingKey === "sharedStrings" && ydoc instanceof Y.Map) {
+                                    (0, helpers_1.applyMapPatches)(ydoc, patches_5);
+                                }
+                                else if (ydoc instanceof Y.Array) {
+                                    // Check if we are updating sheets
+                                    if (mappingKey === "sheets" && ydoc.length === 0) {
+                                        // Add initial sheets
+                                        ydoc.insert(0, getInitialSheets());
+                                    }
+                                    (0, helpers_1.updateArrayType)(ydoc, patches_5);
+                                }
+                            }
+                        }
+                    }
+                    catch (e_11_1) { e_11 = { error: e_11_1 }; }
+                    finally {
+                        try {
+                            if (_k && !_k.done && (_b = _j.return)) _b.call(_j);
+                        }
+                        finally { if (e_11) throw e_11.error; }
+                    }
+                    // Recalc cells
+                    if ((_f = patch.recalcCells) === null || _f === void 0 ? void 0 : _f[type]) {
+                        if (isLeader) {
+                            // Remove old cells
+                            yRecalcCells.delete(0, yRecalcCells.length);
+                        }
+                        yRecalcCells.push([
+                            {
+                                userId: userId,
+                                patches: Array.from(patch.recalcCells[type]),
+                            },
+                        ]);
+                    }
+                }
+            }
+            catch (e_10_1) { e_10 = { error: e_10_1 }; }
+            finally {
+                try {
+                    if (patches_2_1 && !patches_2_1.done && (_a = patches_2.return)) _a.call(patches_2);
+                }
+                finally { if (e_10) throw e_10.error; }
+            }
+        }, origin);
+        onAfterBroadcastPatch === null || onAfterBroadcastPatch === void 0 ? void 0 : onAfterBroadcastPatch(patches, doc);
+    }, [
+        onAfterBroadcastPatch,
+        documentMap,
+        yRecalcCells,
+        doc,
+        userId,
+        yDisableRecalc,
+        ySheetDataV2,
+        ySheetDataV3,
+        isLeader,
+        recalcCellsMaxEntries,
+        useV3,
+    ]);
+    // Listen to active cell change
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (activeCell) {
+            awareness === null || awareness === void 0 ? void 0 : awareness.setLocalStateField("activeCell", activeCell);
+        }
+    }, [awareness, activeCell]);
+    // Listen to sheet change
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        awareness === null || awareness === void 0 ? void 0 : awareness.setLocalStateField("sheetId", sheetId);
+    }, [awareness, sheetId]);
+    // Listen to selection range change
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (selections && selections.length > 0) {
+            awareness === null || awareness === void 0 ? void 0 : awareness.setLocalStateField("selections", selections);
+        }
+    }, [awareness, selections]);
+    // Awareness
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        var onChangeAwareness = function () {
+            var e_12, _a;
+            var _b, _c, _d, _e, _f;
+            if (awareness) {
+                var collaborators = [];
+                try {
+                    for (var _g = tslib_1.__values(awareness.getStates().entries()), _h = _g.next(); !_h.done; _h = _g.next()) {
+                        var _j = tslib_1.__read(_h.value, 2), _2 = _j[0], value = _j[1];
+                        if (!value)
+                            continue;
+                        // States with no docGuid are accepted as a wildcard so REST
+                        // writers or pre-scoped clients still appear as collaborators.
+                        var docMatches = !resolvedAwarenessScopeId ||
+                            !value.docGuid ||
+                            value.docGuid === resolvedAwarenessScopeId;
+                        if (!docMatches)
+                            continue;
+                        // Canonical shape is the nested `state.user = { kind, name, userId,
+                        // agentInitiator? }` used by Olympus, pptx-studio, and the keryx
+                        // agentTask helper. Fall back to legacy flat fields for one
+                        // release so callers can migrate at their own pace.
+                        var userBlock = ((_b = value.user) !== null && _b !== void 0 ? _b : null);
+                        var resolvedUserId = (_c = userBlock === null || userBlock === void 0 ? void 0 : userBlock.userId) !== null && _c !== void 0 ? _c : value.userId;
+                        var resolvedTitle = (_d = userBlock === null || userBlock === void 0 ? void 0 : userBlock.name) !== null && _d !== void 0 ? _d : value.title;
+                        var resolvedKind = (_e = userBlock === null || userBlock === void 0 ? void 0 : userBlock.kind) !== null && _e !== void 0 ? _e : value.kind;
+                        var resolvedAgentInitiator = (_f = userBlock === null || userBlock === void 0 ? void 0 : userBlock.agentInitiator) !== null && _f !== void 0 ? _f : value.agentInitiator;
+                        if (!resolvedUserId)
+                            continue;
+                        if (!value.activeCell && !value.selections)
+                            continue;
+                        collaborators.push({
+                            activeCell: value.activeCell,
+                            title: (resolvedTitle !== null && resolvedTitle !== void 0 ? resolvedTitle : ""),
+                            userId: resolvedUserId,
+                            sheetId: value.sheetId,
+                            kind: resolvedKind,
+                            agentInitiator: resolvedAgentInitiator,
+                            selections: value.selections,
+                        });
+                    }
+                }
+                catch (e_12_1) { e_12 = { error: e_12_1 }; }
+                finally {
+                    try {
+                        if (_h && !_h.done && (_a = _g.return)) _a.call(_g);
+                    }
+                    finally { if (e_12) throw e_12.error; }
+                }
+                setUsers(collaborators);
+            }
+        };
+        // Listen to awareness
+        awareness === null || awareness === void 0 ? void 0 : awareness.on("change", onChangeAwareness);
+        return function () {
+            awareness === null || awareness === void 0 ? void 0 : awareness.off("change", onChangeAwareness);
+        };
+    }, [awareness, resolvedAwarenessScopeId]);
+    // Set local awareness state.
+    //
+    // Use setLocalStateField for each field individually so sibling consumers
+    // (Olympus's unified presence layer, agent-task helpers, etc.) can compose
+    // their own fields on the same awareness state without us clobbering them.
+    (0, ui_1.useIsomorphicLayoutEffect)(function () {
+        if (!awareness)
+            return;
+        awareness.setLocalStateField("userId", userId);
+        awareness.setLocalStateField("title", title);
+        awareness.setLocalStateField("sheetId", sheetId);
+        if (resolvedAwarenessScopeId) {
+            awareness.setLocalStateField("docGuid", resolvedAwarenessScopeId);
+        }
+        // Mirror the canonical nested shape so other Athena editors can read
+        // state.user.* without falling back to the legacy flat fields.
+        var userBlock = {
+            userId: userId,
+            name: title,
+        };
+        if (kind)
+            userBlock.kind = kind;
+        if (agentInitiator)
+            userBlock.agentInitiator = agentInitiator;
+        awareness.setLocalStateField("user", userBlock);
+        if (kind)
+            awareness.setLocalStateField("kind", kind);
+        if (agentInitiator)
+            awareness.setLocalStateField("agentInitiator", agentInitiator);
+    }, [
+        awareness,
+        resolvedAwarenessScopeId,
+        userId,
+        title,
+        sheetId,
+        kind,
+        agentInitiator,
+    ]);
+    return {
+        synced: synced,
+        users: users,
+        onBroadcastPatch: onBroadcastPatch,
+        isLeader: isLeader,
+        setupInitialSync: setupInitialSync,
+    };
+};
+exports.useYSpreadsheetV2 = useYSpreadsheetV2;