@fileverse-dev/dsheet 3.0.2 → 3.0.3

package/README.md

@@ -80,6 +80,7 @@ function App() {
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
 | `onChange` | `(data: SheetUpdateData, encodedUpdate?: string) => void` | - | Callback when sheet data changes |
+| `onContentUpdate` | `() => void` | - | Cheap throttled callback that does not encode or reconstruct the sheet |
 | `portalContent` | `string` | - | Encoded initial sheet data |
 | `isReadOnly` | `boolean` | `false` | Enable read-only mode |
 | `allowComments` | `boolean` | `false` | Enable comments (requires `isReadOnly=true`) |

package/dist/{constants-Q8nzbvQO.js → constants-Cdz6oSCq.js}

@@ -1,13 +1,11 @@
-import { E as n, S as a } from "./crypto-constants-CqpCRs86.js";
-const E = n, d = a, f = [
+import { E as a, S as n } from "./crypto-constants-CqpCRs86.js";
+const E = a, d = n, f = [
   {
     id: "0",
     name: "Sheet1",
     celldata: [],
     config: {},
-    order: 0,
-    row: 500,
-    column: 26
+    order: 0
   }
 ], m = [
   "undo",

package/dist/constants.js

@@ -1,4 +1,4 @@
-import { a as R, c as _, E as C, S as a, p as s } from "./constants-Q8nzbvQO.js";
+import { a as R, c as _, E as C, S as a, p as s } from "./constants-Cdz6oSCq.js";
 export {
   R as COLLAB_PRESENCE_COLORS,
   _ as ENS_PRESENCE_COLOR,

package/dist/editor/components/editor-workbook-sync.d.ts

@@ -19,5 +19,5 @@ export declare const createAfterOrderChangesHandler: ({ sheetEditorRef, ydocRef,
 export declare const createAfterColorChangesHandler: ({ sheetEditorRef, ydocRef, dsheetId, handleOnChangePortalUpdate, }: SyncContext) => () => void;
 export declare const createAfterHideChangesHandler: ({ sheetEditorRef, ydocRef, dsheetId, handleOnChangePortalUpdate, }: SyncContext) => () => void;
 export declare const createAfterColRowChangesHandler: ({ sheetEditorRef, ydocRef, dsheetId, handleOnChangePortalUpdate, }: SyncContext) => () => void;
-export declare const updateAllCell: ({ sheetEditorRef, ydocRef, dsheetId, handleOnChangePortalUpdate, }: SyncContext, subSheetId: string) => void;
+export declare const updateAllCell: ({ sheetEditorRef, ydocRef, dsheetId, handleOnChangePortalUpdate, }: SyncContext, subSheetId: string, caller?: string) => void;
 export {};

package/dist/editor/constants/shared-constants.d.ts

@@ -8,8 +8,6 @@ export declare const DEFAULT_SHEET_DATA: {
     celldata: never[];
     config: {};
     order: number;
-    row: number;
-    column: number;
 }[];
 export declare const TOOL_BAR_ITEMS: string[];
 export declare const CELL_CONTEXT_MENU_ITEMS: string[];

package/dist/editor/contexts/editor-context.d.ts

@@ -9,6 +9,7 @@ import { SmartContractConfig } from '../types/smart-contract';
 import { UseSmartContractReturn } from '../hooks/use-smart-contract';
 import { CollaborationProps, CollabState, CollabUser } from '../../sync-local/types';
 import { Awareness } from 'y-protocols/awareness';
+import { DSheetContentSnapshot } from '../../persistence';
 
 import * as Y from 'yjs';
 export interface EditorContextType {
@@ -75,12 +76,15 @@ interface EditorProviderProps {
     portalContent?: string;
     enableIndexeddbSync?: boolean;
     isReadOnly?: boolean;
+    onContentUpdate?: () => void;
     onChange?: (data: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
     externalEditorRef?: React.MutableRefObject<WorkbookInstance | null>;
     commentsConfig?: CommentsConfig;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
+        getContentSnapshot: () => DSheetContentSnapshot;
+        mergeContent: (encodedState: string) => DSheetContentSnapshot;
         terminateSession?: () => void;
         updateCollaboratorName?: (name: string) => void;
         rehydrateAfterCollabSync?: (reason?: string) => boolean;

package/dist/editor/dsheet-editor.d.ts

@@ -7,5 +7,5 @@ import { DsheetProps } from './types';
  * @param props - Component properties
  * @returns The SpreadsheetEditor component
  */
-declare const SpreadsheetEditor: ({ isReadOnly, allowSheetDownload, renderNavbar, enableIndexeddbSync, dsheetId, portalContent, onChange, username, selectedTemplate, toggleTemplateSidebar, isTemplateOpen, onboardingComplete, onboardingCompleteLocalStorageKey, onboardingHandler, commentsConfig, setFetchingURLData, setShowFetchURLModal, setInputFetchURLDataBlock, sheetEditorRef: externalSheetEditorRef, onDuneChartEmbed, onSheetCountChange, isAuthorized, getDocumentTitle, updateDocumentTitle, editorStateRef, setSelectedTemplate, isNewSheet, liveQueryRefreshRate, enableLiveQuery, collaboration, customPanels, apiKeyStorage, onDataBlockEvent, smartContracts, theme, onContentSyncStatusChange, }: DsheetProps) => JSX.Element;
+declare const SpreadsheetEditor: ({ isReadOnly, allowSheetDownload, renderNavbar, enableIndexeddbSync, dsheetId, portalContent, onContentUpdate, onChange, username, selectedTemplate, toggleTemplateSidebar, isTemplateOpen, onboardingComplete, onboardingCompleteLocalStorageKey, onboardingHandler, commentsConfig, setFetchingURLData, setShowFetchURLModal, setInputFetchURLDataBlock, sheetEditorRef: externalSheetEditorRef, onDuneChartEmbed, onSheetCountChange, isAuthorized, getDocumentTitle, updateDocumentTitle, editorStateRef, setSelectedTemplate, isNewSheet, liveQueryRefreshRate, enableLiveQuery, collaboration, customPanels, apiKeyStorage, onDataBlockEvent, smartContracts, theme, onContentSyncStatusChange, }: DsheetProps) => JSX.Element;
 export default SpreadsheetEditor;

package/dist/editor/hooks/use-celldata-compaction.d.ts

@@ -0,0 +1,23 @@
+import { MutableRefObject, RefObject } from 'react';
+import { WorkbookInstance, Sheet } from '../../sheet-engine/react';
+
+import type * as Y from 'yjs';
+type UseCelldataCompactionArgs = {
+    dsheetId: string;
+    ydocRef: RefObject<Y.Doc | null>;
+    sheetEditorRef: RefObject<WorkbookInstance | null>;
+    currentDataRef: MutableRefObject<Sheet[]>;
+    handleOnChangePortalUpdate: () => void;
+    syncStatus: 'initializing' | 'syncing' | 'synced' | 'error';
+    isDataLoaded: boolean;
+    isReadOnly: boolean;
+    remoteUpdateRef: MutableRefObject<boolean>;
+    collabSyncing: boolean;
+};
+/**
+ * One-shot background compaction: remove committed celldata entries that copy/paste
+ * would never write (`shouldPersistCelldataCell` === false). Runs once per dsheetId
+ * after the editor is synced and idle so it does not compete with load or edits.
+ */
+export declare function useCelldataCompaction({ dsheetId, ydocRef, sheetEditorRef, currentDataRef, handleOnChangePortalUpdate, syncStatus, isDataLoaded, isReadOnly, remoteUpdateRef, collabSyncing, }: UseCelldataCompactionArgs): void;
+export {};

package/dist/editor/hooks/use-editor-sync.d.ts

@@ -7,6 +7,8 @@ export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boo
     syncStatus: "error" | "syncing" | "initializing" | "synced";
     isSyncedRef: import('react').MutableRefObject<boolean>;
     refreshIndexedDB: () => Promise<void>;
+    getContentSnapshot: () => import('../../persistence-utils').DSheetContentSnapshot;
+    mergeContent: (encodedState: string) => import('../../persistence-utils').DSheetContentSnapshot;
     collabState: import('../..').CollabState;
     isCollabReady: boolean;
     isCollabSyncing: boolean;

package/dist/editor/hooks/use-xlsx-import-impl.d.ts

@@ -11,6 +11,7 @@ export type XlsxImportRuntimeDeps = {
     updateDocumentTitle?: (title: string) => void;
     filterToastShown: boolean;
     setFilterToastShown: React.Dispatch<React.SetStateAction<boolean>>;
+    handleContentPortal?: () => void;
 };
 export type XlsxImportOptions = {
     headless?: boolean;
@@ -19,4 +20,4 @@ export type XlsxImportOptions = {
     generateSheetId?: () => string;
 };
 /** Full XLSX import pipeline; loaded only when user imports a file. */
-export declare function runXlsxFileUpload({ sheetEditorRef, ydocRef, setForceSheetRender, dsheetId, currentDataRef, updateDocumentTitle, filterToastShown, setFilterToastShown, }: XlsxImportRuntimeDeps, event: React.ChangeEvent<HTMLInputElement> | undefined, fileArg: File, importType?: 'new-dsheet' | 'merge-current-dsheet' | 'new-current-dsheet', options?: XlsxImportOptions): Promise<void>;
+export declare function runXlsxFileUpload({ sheetEditorRef, ydocRef, setForceSheetRender, dsheetId, currentDataRef, updateDocumentTitle, filterToastShown, setFilterToastShown, handleContentPortal, }: XlsxImportRuntimeDeps, event: React.ChangeEvent<HTMLInputElement> | undefined, fileArg: File, importType?: 'new-dsheet' | 'merge-current-dsheet' | 'new-current-dsheet', options?: XlsxImportOptions): Promise<void>;

package/dist/editor/hooks/use-xlsx-import.d.ts

@@ -7,13 +7,14 @@ type ImportType = 'new-dsheet' | 'merge-current-dsheet' | 'new-current-dsheet';
  * XLSX import: keeps ~100k+ LOC (SSF, hyperlink helpers, exceljs/luckyexcel orchestration)
  * in a separate chunk until the user actually imports a file.
  */
-export declare const useXLSXImport: ({ sheetEditorRef, ydocRef, setForceSheetRender, dsheetId, currentDataRef, updateDocumentTitle, }: {
+export declare const useXLSXImport: ({ sheetEditorRef, ydocRef, setForceSheetRender, dsheetId, currentDataRef, updateDocumentTitle, handleContentPortal, }: {
     sheetEditorRef: RefObject<WorkbookInstance | null>;
     ydocRef: RefObject<Y.Doc | null>;
     setForceSheetRender: Dispatch<SetStateAction<number>>;
     dsheetId: string;
     currentDataRef: MutableRefObject<object | null>;
     updateDocumentTitle?: (title: string) => void;
+    handleContentPortal?: () => void;
 }) => {
     handleXLSXUpload: (event: ChangeEvent<HTMLInputElement> | undefined, fileArg: File, importType?: ImportType) => Promise<void>;
 };

package/dist/editor/types.d.ts

@@ -6,6 +6,7 @@ import { CommentsConfig } from './types/comments';
 import { SmartContractConfig } from './types/smart-contract';
 import { ApiKeyStorage } from './utils/api-key-storage';
 import { ThemeKey } from '../sheet-engine/core/theme';
+import { DSheetContentSnapshot } from '../persistence';
 
 import * as Y from 'yjs';
 export type { ThemeKey } from '../sheet-engine/core/theme';
@@ -59,6 +60,11 @@ export interface DsheetProps {
     renderNavbar?: (editorValues?: EditorValues) => JSX.Element;
     enableIndexeddbSync?: boolean;
     dsheetId: string;
+    /**
+     * Cheap change signal for hosts that persist sheet bodies through Yjs.
+     * Unlike `onChange`, this does not build a plain sheet or encode the Y.Doc.
+     */
+    onContentUpdate?: () => void;
     onChange?: (updateData: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
     username?: string;
@@ -89,6 +95,8 @@ export interface DsheetProps {
     onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
+        getContentSnapshot: () => DSheetContentSnapshot;
+        mergeContent: (encodedState: string) => DSheetContentSnapshot;
     } | null>;
     /** Smart contract config: execution + UI in package; consumer owns persistence via callbacks. */
     smartContracts?: SmartContractConfig;

package/dist/editor/utils/apply-comment-markers.d.ts

@@ -0,0 +1,22 @@
+type CommentData = object | null | undefined;
+/**
+ * Stamps the in-cell comment marker (`cell.ps`) onto sheet data, derived from
+ * the consumer-provided `commentData`.
+ *
+ * `ps` is a per-client, permission-gated *view overlay* — it is NOT persisted in
+ * ydoc. Every path that rebuilds sheet data from ydoc (portal load, collab sync
+ * remount, remote cell edits) produces cells WITHOUT `ps`, so this must run on
+ * each such snapshot or the red-triangle indicator vanishes. Because it is
+ * gated on the local `allowComments` permission, it must never be written back
+ * to shared ydoc state — doing so would let one viewer wipe markers for all.
+ *
+ * Handles both shapes:
+ * - Dense `sheet.data` (the live active sheet in `luckysheetfile`).
+ * - Sparse `sheet.celldata` (plain snapshots from `ySheetArrayToPlain`, and
+ *   inactive sheets). `initSheetData()` converts celldata → data on activation,
+ *   so `ps` set on celldata carries through.
+ *
+ * Mutates in place and returns the same array.
+ */
+export declare const applyCommentMarkers: <T>(sheets: T | null | undefined, commentData: CommentData, allowComments: boolean | undefined) => T | null | undefined;
+export {};

package/dist/editor/utils/compact-committed-celldata.d.ts

@@ -0,0 +1,28 @@
+import { CellMatrix, CellWithRowAndCol, Sheet } from '../../sheet-engine/core/types';
+import { SheetChangePath } from './update-ydoc';
+import * as Y from 'yjs';
+export declare const CELLDATA_COMPACT_STORAGE_KEY_PREFIX = "dsheet-celldata-compact-v1:";
+export type CelldataCompactionResult = {
+    removedFromYdoc: number;
+    clearedInMemory: number;
+    changes: SheetChangePath[];
+};
+export declare function celldataCompactStorageKey(dsheetId: string): string;
+export declare function hasCelldataCompactionCompleted(dsheetId: string): boolean;
+export declare function markCelldataCompactionCompleted(dsheetId: string): void;
+/** Collect Yjs celldata keys that should not be persisted (format-only / empty ghosts). */
+export declare function collectStaleCelldataKeys(celldataMap: Y.Map<unknown> | Record<string, unknown> | null | undefined): string[];
+export declare function buildCelldataDeleteChanges(sheetId: string, keys: string[]): SheetChangePath[];
+/** Null out dense-grid cells that should not be persisted. */
+export declare function compactSheetDataMatrix(data: CellMatrix | null | undefined): number;
+/** Drop sparse celldata entries that should not be persisted. */
+export declare function compactSheetCelldataArray(celldata: CellWithRowAndCol[] | null | undefined): {
+    next: CellWithRowAndCol[];
+    removed: number;
+};
+export declare function compactInMemorySheets(sheets: Sheet[] | null | undefined): number;
+/**
+ * Scan Y.Doc for committed celldata ghosts. Does not mutate — caller applies
+ * `changes` via `updateYdocSheetData`.
+ */
+export declare function planYdocCelldataCompaction(ydoc: Y.Doc, dsheetId: string): CelldataCompactionResult;

package/dist/editor/utils/config-ydoc-update.d.ts

@@ -0,0 +1,20 @@
+import { WorkbookInstance } from '../../sheet-engine/react';
+import { SheetChangePath } from './update-ydoc';
+
+import * as Y from 'yjs';
+/** Diff top-level config sub-keys and emit granular Yjs updates. */
+export declare function buildConfigSubKeyChanges({ sheetId, oldConfig, newConfig, }: {
+    sheetId: string;
+    oldConfig: Record<string, any>;
+    newConfig: Record<string, any>;
+}): SheetChangePath[];
+/**
+ * Sync active sheet config sub-keys to Yjs (borderInfo, merge, rowlen, …).
+ * Replaces whole-config writes so only changed sub-keys are broadcast.
+ */
+export declare const configYdocUpdate: ({ sheetEditorRef, ydocRef, dsheetId, handleContentPortal, }: {
+    sheetEditorRef: React.RefObject<WorkbookInstance | null>;
+    ydocRef: React.RefObject<Y.Doc | null>;
+    dsheetId: string;
+    handleContentPortal?: any;
+}) => void;

package/dist/editor/utils/update-ydoc.d.ts

@@ -1,11 +1,21 @@
 import { Sheet } from '../../sheet-engine/react';
-import * as Y from 'yjs';
+import { CellFormatRange } from '../../sheet-engine/core/utils/range-format';
+import * as Y from "yjs";
 export type SheetChangePath = {
     sheetId: string;
     path: string[];
     key?: string;
     value: any;
-    type?: 'update' | 'delete';
+    type?: "update" | "delete";
+    /**
+     * Compaction deletes planned earlier may race with edits across idle chunks.
+     * When set, skip the delete if the live celldata entry is now persistable.
+     * Do not set on intentional clears — those must always remove the key.
+     */
+    skipIfPersistable?: boolean;
 };
-export declare const updateYdocSheetData: (ydoc: Y.Doc | null, dsheetId: string, changes: SheetChangePath[], handleContentPortal: any) => void;
+export declare const updateYdocSheetData: (ydoc: Y.Doc | null, dsheetId: string, changes: SheetChangePath[], handleContentPortal: any, onCellFormatRangesCommitted?: (commits: Array<{
+    sheetId: string;
+    ranges: CellFormatRange[];
+}>) => void) => void;
 export declare function ySheetArrayToPlain(sheetArray: Y.Array<Y.Map>): Sheet[];