@rowsncolumns/y-spreadsheet 14.0.32

package/dist/esm/helpers.d.ts

@@ -0,0 +1,179 @@
+import { type CellData, type CellFormat, type Sheet } from "@rowsncolumns/spreadsheet";
+import { type HistoryType, type SheetData, type SpreadsheetPatch } from "@rowsncolumns/spreadsheet-state";
+import type { Patch } from "immer";
+import * as Y from "yjs";
+import type { YRowData, YSheetData } from "./use-yspreadsheet-v2";
+import type { CellKeyV3, CellDataV3, ParsedCellKeyV3 } from "./types";
+/**
+ * Simplified structure to pass event data synchronously
+ */
+export type SheetDataEvent = {
+    path: (string | number)[];
+    delta?: {
+        insert?: any[] | number | string;
+        delete?: number;
+        retain?: number;
+    }[];
+    isYArrayEvent: boolean;
+};
+/**
+ * Apply patches to yjs
+ * @param doc
+ * @param userId
+ * @param patches
+ * @param source
+ * @param sheetDataVersion - Version of sheet data format ("v2" or "v3"). Falls back to docMeta if undefined.
+ */
+export declare const applyPatchesToYDoc: (doc: Y.Doc, userId: string | number, patches: [patch: SpreadsheetPatch<Patch>, type?: HistoryType | undefined | null][], source?: "agent" | "user" | "backend", sheetDataVersion?: "v2" | "v3") => void;
+/**
+ * Add sheet data to a yjs map using immer patches
+ *
+ * Optimized for bulk operations (paste, import) by consolidating cell-level
+ * patches before applying to Y.js. This reduces overhead by:
+ * 1. Deduplicating patches targeting the same cell (later patches win)
+ * 2. Grouping updates by sheet/row for efficient batch application
+ */
+export declare const addSheetDataPatches: (ySheetData: Y.Map<YSheetData>, patches: Patch[]) => void;
+export declare const getSheetFromYSheetData: (ySheetData: Y.Map<YSheetData>, sheetId: string | number) => YSheetData;
+export declare const deleteSheetFromYSheetData: (ySheetData: Y.Map<YSheetData>, sheetId: string | number) => void;
+export declare const getRowDataFromSheet: (ysheet: Y.Array<YRowData | null>, rowIndex: number | string) => Y.Array<CellData | null>;
+export declare const setCellDataInRowData: (rowData: Y.Array<CellData | null>, columnIndex: number | string, cellData?: CellData | null) => void;
+export declare const removeRowData: (ysheet: Y.Array<YRowData | null>, rowIndex: number | string) => void;
+/**
+ * Read a cell's data from the V2 Y.js structure without creating any
+ * missing sheet/row/values containers (unlike getSheetFromYSheetData /
+ * getRowDataFromSheet, which lazily create them).
+ */
+export declare const getCellDataFromYSheetData: (ySheetData: Y.Map<YSheetData>, sheetId: string | number, rowIndex: number | string, columnIndex: number | string) => CellData | null | undefined;
+/**
+ * Extract the error effective value from cell data, if any.
+ * SheetCell.setErrorValue persists formula errors as
+ * `ev.ev = { type: "Error", name, message }` (legacy long form:
+ * `effectiveValue.errorValue`).
+ */
+export declare const getCellDataErrorValue: (cellData?: CellData | null) => Record<string, any> | undefined;
+/**
+ * Keep only the cell-level sheetData patches
+ * (`[sheetId, rowIndex, "values", columnIndex]`) whose new cell data carries
+ * an error effective value (#VALUE!, #NAME?, …). Used to let calc-result
+ * errors bypass the leader gate: errors must reach the Y.Doc even from
+ * non-leader clients, otherwise they render blank after reload.
+ */
+export declare const filterErrorCellPatches: (patches: Patch[]) => Patch[];
+/**
+ * Containment guard for the non-leader error-persistence path
+ * (use-yspreadsheet-v2 onBroadcastPatch, gated disableRecalc branch).
+ * A gated error cell patch may be written ONLY when all of these hold:
+ *
+ * 1. The incoming cell data carries an error effective value.
+ * 2. The current doc cell holds no effective value at all (the
+ *    blank-after-reload case) or its effective value is itself an error.
+ *    A non-error result (number/string/bool/formula result) is never
+ *    overwritten — a stale non-leader error must not clobber a newer
+ *    leader-written success.
+ * 3. If the doc cell exists, its user-entered value (`ue`, short or legacy
+ *    key shape) matches the incoming patch's — a cell edited after the
+ *    calculation started is never touched.
+ * 4. The persisted error differs from the incoming one (identical errors
+ *    are dropped so concurrent non-leaders don't append redundant
+ *    Y.js updates).
+ */
+export declare const shouldPersistErrorCellPatch: (currentCellData: CellData | null | undefined, incomingCellData: CellData | null | undefined) => boolean;
+/**
+ * Build the cell data to write for a gated error patch that passed
+ * shouldPersistErrorCellPatch. If the doc cell doesn't exist yet there is
+ * nothing to destroy and the incoming cell data is written as-is. If it
+ * does exist, ONLY the error effective value is merged in — every other
+ * field of the doc cell (ue, formats, notes, …) is preserved so this write
+ * path can never remove doc state it didn't produce. The effective value is
+ * written into whichever key shape(s) the doc cell already uses (short `ev`
+ * by default).
+ */
+export declare const mergeErrorEffectiveValueIntoCellData: (currentCellData: CellData | null | undefined, incomingCellData: CellData) => CellData;
+/**
+ * Update array type with immer patches
+ */
+export declare const updateArrayType: (yarray: Y.Array<any>, patches: Patch[]) => void;
+/**
+ * Validate and clean sheets data
+ */
+export declare const validateSheets: <S extends Sheet>(sheets: S[]) => S[];
+/**
+ * Map operations
+ */
+export declare const applyMapPatches: <T = CellFormat>(yMap: Y.Map<T>, patches: Patch[]) => void;
+/**
+ * Process events to find changes in sheet data
+ * Returns a new sheet data object with only the changes applied if possible, or null if a full reload is needed
+ */
+export declare const processSheetDataEvents: (events: SheetDataEvent[], currentSheetData: SheetData<any>, ySheetDataV2: Y.Map<YSheetData>) => SheetData<any> | null;
+/**
+ * Create a V3 cell key from sheet ID, row and column indices
+ * Format: `${sheetId}!${A1Address}` (e.g., "1!A1", "2!B5")
+ */
+export declare const createCellKeyV3: (sheetId: number, rowIndex: number, columnIndex: number) => CellKeyV3;
+/**
+ * Parse a V3 cell key to extract sheet ID and position information
+ * Example: parseCellKeyV3("1!A1") => { sheetId: 1, address: "A1", rowIndex: 1, columnIndex: 1 }
+ */
+export declare const parseCellKeyV3: (cellKey: CellKeyV3) => ParsedCellKeyV3 | null;
+/**
+ * Create a CellDataV3 object with position and sheetId
+ */
+export declare const createCellDataV3: <T extends CellData>(value: T, sheetId: number, rowIndex: number, columnIndex: number) => CellDataV3<T>;
+/**
+ * Type for Y.Map storing V3 cell data (flat structure)
+ * Key format: `${sheetId}!${A1Address}` (e.g., "1!A1", "2!B5")
+ */
+export type YSheetDataV3 = Y.Map<CellDataV3>;
+/**
+ * Convert V2 SheetData to V3 flat Map format
+ * V2: { sheetId: [rows with values arrays] }
+ * V3: Map<cellKey, CellDataV3>
+ */
+export declare const sheetDataV2ToV3: <T extends CellData>(v2Data: SheetData<T>) => Map<string, CellDataV3<T>>;
+/**
+ * Convert V3 flat Map format to V2 SheetData
+ * V3: Map<cellKey, CellDataV3>
+ * V2: { sheetId: [rows with values arrays] }
+ */
+export declare const sheetDataV3ToV2: <T extends CellData>(v3Data: Map<string, CellDataV3<T>>) => SheetData<T>;
+/**
+ * Get a cell from V3 flat structure
+ */
+export declare const getCellV3: (ySheetDataV3: YSheetDataV3, sheetId: number, rowIndex: number, columnIndex: number) => CellDataV3 | undefined;
+/**
+ * Set a cell in V3 flat structure
+ */
+export declare const setCellV3: (ySheetDataV3: YSheetDataV3, sheetId: number, rowIndex: number, columnIndex: number, value: CellData) => void;
+/**
+ * Delete a cell from V3 flat structure
+ */
+export declare const deleteCellV3: (ySheetDataV3: YSheetDataV3, sheetId: number, rowIndex: number, columnIndex: number) => void;
+/**
+ * Delete all cells for a sheet from V3 flat structure
+ */
+export declare const deleteSheetV3: (ySheetDataV3: YSheetDataV3, sheetId: number) => void;
+/**
+ * Get V3 sheet data map from Y.Doc
+ */
+export declare const getSheetDataV3: (doc: Y.Doc) => YSheetDataV3;
+/**
+ * Apply immer patches to V3 sheet data (flat map structure)
+ *
+ * Optimized for bulk operations (paste, import) by consolidating cell-level
+ * patches before applying to Y.js. This reduces overhead by:
+ * 1. Deduplicating patches targeting the same cell (later patches win)
+ * 2. Processing all cell updates in a single pass
+ */
+export declare const addSheetDataPatchesV3: (ySheetDataV3: YSheetDataV3, patches: Patch[]) => void;
+/**
+ * Process V3 events and return updated sheet data
+ * @param changedKeys - Pre-extracted changes from Yjs event
+ * @param currentSheetData - Current sheet data state
+ * @param ySheetDataV3 - The Y.Map for V3 data
+ */
+export declare const processSheetDataEventsV3: <T extends CellData>(changedKeys: Map<string, {
+    action: "add" | "update" | "delete";
+}>, currentSheetData: SheetData<T>, ySheetDataV3: YSheetDataV3) => SheetData<T> | null;
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../helpers.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,UAAU,EACf,KAAK,KAAK,EAEX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACtB,MAAM,iCAAiC,CAAC;AAWzC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AACnC,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;AAOzB,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,KAAK,EAEV,SAAS,EACT,UAAU,EACV,eAAe,EAChB,MAAM,SAAS,CAAC;AAEjB;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAC1B,KAAK,CAAC,EAAE;QACN,MAAM,CAAC,EAAE,GAAG,EAAE,GAAG,MAAM,GAAG,MAAM,CAAC;QACjC,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,EAAE,CAAC;IACJ,aAAa,EAAE,OAAO,CAAC;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAC7B,KAAK,CAAC,CAAC,GAAG,EACV,QAAQ,MAAM,GAAG,MAAM,EACvB,SAAS,CACP,KAAK,EAAE,gBAAgB,CAAC,KAAK,CAAC,EAC9B,IAAI,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,IAAI,CACtC,EAAE,EACH,SAAS,OAAO,GAAG,MAAM,GAAG,SAAS,EACrC,mBAAmB,IAAI,GAAG,IAAI,SAyG/B,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAC9B,YAAY,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAC7B,SAAS,KAAK,EAAE,SAmNjB,CAAC;AAEF,eAAO,MAAM,sBAAsB,GACjC,YAAY,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAC7B,SAAS,MAAM,GAAG,MAAM,KACvB,UAUF,CAAC;AAEF,eAAO,MAAM,yBAAyB,GACpC,YAAY,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAC7B,SAAS,MAAM,GAAG,MAAM,KACvB,IAGF,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC9B,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,EAChC,UAAU,MAAM,GAAG,MAAM,KACxB,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CA+CzB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,EACjC,aAAa,MAAM,GAAG,MAAM,EAC5B,WAAU,QAAQ,GAAG,IAAW,KAC/B,IAkBF,CAAC;AAEF,eAAO,MAAM,aAAa,GACxB,QAAQ,CAAC,CAAC,KAAK,CAAC,QAAQ,GAAG,IAAI,CAAC,EAChC,UAAU,MAAM,GAAG,MAAM,KACxB,IAQF,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,GACpC,YAAY,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,EAC7B,SAAS,MAAM,GAAG,MAAM,EACxB,UAAU,MAAM,GAAG,MAAM,EACzB,aAAa,MAAM,GAAG,MAAM,KAC3B,QAAQ,GAAG,IAAI,GAAG,SAapB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAChC,WAAW,QAAQ,GAAG,IAAI,KACzB,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,SAExB,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB,GAAI,SAAS,KAAK,EAAE,KAAG,KAAK,EAQ9D,CAAC;AAqCF;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,2BAA2B,GACtC,iBAAiB,QAAQ,GAAG,IAAI,GAAG,SAAS,EAC5C,kBAAkB,QAAQ,GAAG,IAAI,GAAG,SAAS,KAC5C,OA0BF,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,oCAAoC,GAC/C,iBAAiB,QAAQ,GAAG,IAAI,GAAG,SAAS,EAC5C,kBAAkB,QAAQ,KACzB,QAcF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAC1B,QAAQ,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,EACpB,SAAS,KAAK,EAAE,KACf,IAwGF,CAAC;AAsCF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,KAAK,EAAE,QAAQ,CAAC,EAAE,KAAG,CAAC,EAM9D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,GAAG,UAAU,EAC5C,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EACd,SAAS,KAAK,EAAE,SA4BjB,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,QAAQ,cAAc,EAAE,EACxB,kBAAkB,SAAS,CAAC,GAAG,CAAC,EAChC,cAAc,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,KAC9B,SAAS,CAAC,GAAG,CAAC,GAAG,IA8KnB,CAAC;AAiBF;;;GAGG;AACH,eAAO,MAAM,eAAe,GAC1B,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,SAKF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,cAAc,GAAI,SAAS,SAAS,KAAG,eAAe,GAAG,IAWrE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,QAAQ,EACjD,OAAO,CAAC,EACR,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,UAAU,CAAC,CAAC,CAKb,CAAC;AAEH;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,QAAQ,EAChD,QAAQ,SAAS,CAAC,CAAC,CAAC,KACnB,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAuB3B,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,QAAQ,EAChD,QAAQ,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC,KACjC,SAAS,CAAC,CAAC,CAgCb,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,cAAc,YAAY,EAC1B,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,UAAU,GAAG,SAGf,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,SAAS,GACpB,cAAc,YAAY,EAC1B,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,EACnB,OAAO,QAAQ,KACd,IAMF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,GACvB,cAAc,YAAY,EAC1B,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,aAAa,MAAM,KAClB,IAGF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GACxB,cAAc,YAAY,EAC1B,SAAS,MAAM,KACd,IAOF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,GAAI,KAAK,CAAC,CAAC,GAAG,KAAG,YAE3C,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,cAAc,YAAY,EAC1B,SAAS,KAAK,EAAE,SAwUjB,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,GAAI,CAAC,SAAS,QAAQ,EACzD,aAAa,GAAG,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,CAAA;CAAE,CAAC,EACjE,kBAAkB,SAAS,CAAC,CAAC,CAAC,EAC9B,cAAc,YAAY,KACzB,SAAS,CAAC,CAAC,CAAC,GAAG,IA4EjB,CAAC"}