@fileverse-dev/dsheet 4.1.23-stabilise-package-1 → 4.1.23-stabilise-package-3

package/README.md

@@ -86,6 +86,7 @@ function App() {
 | `isCollaborative` | `boolean` | `false` | Enable collaborative features |
 | `enableWebrtc` | `boolean` | `true` | Enable WebRTC for P2P collaboration |
 | `enableIndexeddbSync` | `boolean` | `true` | Enable local IndexedDB persistence |
+| `onIndexedDbError` | `(error: Error) => void` | - | Called when local persistence fails, or when the first read of the local store does not finish within 15 s. The editor continues with the in-memory document; call `rebuildLocalStore()` to recreate the store |
 | `isTemplateOpen` | `boolean` | - | Template sidebar state |
 | `selectedTemplate` | `string` | - | Selected template identifier |
 | `onboardingComplete` | `boolean` | - | Onboarding completion status |
@@ -115,6 +116,15 @@ function App() {
 | `setInputFetchURLDataBlock` | `Dispatch<SetStateAction<string>>` | URL input state setter |
 | `setForceSheetRender` | `Dispatch<SetStateAction<number>>` | Force re-render trigger |
 
+### Editor handle methods
+
+`sheetEditorRef` is a `DSheetEditorHandle`: the workbook instance plus these methods.
+
+| Method | Description |
+|--------|-------------|
+| `rebuildLocalStore()` | `Promise<void>`. Deletes this sheet's IndexedDB database and rewrites it from the live document, so local edits are kept. A no-op when read-only or when `enableIndexeddbSync` is off. Rejects if the rebuild fails, the new store does not sync within 15 s, or a refresh or unmount supersedes it. Concurrent calls share one rebuild. |
+| `getContentFingerprint()` | `string \| null`. Changes on every document change, deletes included; compare with `===` only. `null` until local persistence has synced. |
+
 ## Examples
 
 ### Read-Only Viewer

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

@@ -43,6 +43,8 @@ export interface EditorContextType {
     setSheetData: React.Dispatch<React.SetStateAction<Sheet[]>>;
     currentDataRef: React.MutableRefObject<Sheet[]>;
     remoteUpdateRef: React.MutableRefObject<boolean>;
+    /** True while a peer's structural edit waits to remount the grid. */
+    structuralRemountPendingRef: React.MutableRefObject<boolean>;
     handleChange: (data: Sheet[]) => void;
     initialiseLiveQueryData: (data: Sheet[]) => void;
     loading: boolean;

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

@@ -21,6 +21,7 @@ export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | nul
     setSheetData: import('react').Dispatch<import('react').SetStateAction<Sheet[]>>;
     currentDataRef: import('react').MutableRefObject<Sheet[]>;
     remoteUpdateRef: import('react').MutableRefObject<boolean>;
+    structuralRemountPendingRef: import('react').MutableRefObject<boolean>;
     isDataLoaded: boolean;
     setIsDataLoaded: import('react').Dispatch<import('react').SetStateAction<boolean>>;
     handleChange: (_data: Sheet[]) => void;

package/dist/editor/types.d.ts

@@ -33,7 +33,13 @@ export type DSheetEditorHandle = WorkbookInstance & {
      * document (same Y.Doc, never replaced), so local edits are kept. Resolves
      * once the new store has synced. Resolves as a no-op when the editor is
      * read-only, local persistence is disabled or there is no sheet id. Rejects
-     * if the rebuild fails or a refresh/unmount supersedes it. Concurrent calls share one rebuild.
+     * if the rebuild fails, if the new store does not sync within 15 s, or if a
+     * refresh/unmount supersedes it. Concurrent calls share one rebuild.
+     *
+     * A bootstrap that is still waiting on an unreadable store (the case this
+     * heals) is abandoned after 3 s: the rebuild then finishes the bootstrap
+     * itself, merging the published content into the document, so the editor
+     * leaves "syncing" once the rebuild resolves.
      */
     rebuildLocalStore: () => Promise<void>;
     terminateSession: () => void;
@@ -111,12 +117,17 @@ export interface DsheetProps {
     /**
      * @deprecated Encodes the whole Y.Doc and rebuilds a plain workbook per
      * call. Use `onContentChange` and read full state on demand. Called at most
-     * once per second (trailing), flushed only on unload and unmount.
+     * once per second (trailing), flushed only on unload and unmount. The latest
+     * `onChange` you pass is the one called, so an inline function is safe: a new
+     * identity does not cancel a pending call.
      */
     onChange?: (updateData: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
     /** Called when local IndexedDB persistence fails. The editor and durable
-     * collaboration continue using the in-memory Y.Doc, matching dDoc. */
+     * collaboration continue using the in-memory Y.Doc, matching dDoc. Also
+     * called when the first read of the local store does not finish within 15 s
+     * (the editor then continues without local persistence, and
+     * `rebuildLocalStore()` can recreate the store). */
     onIndexedDbError?: (error: Error) => void;
     username?: string;
     portalContent?: string;

package/dist/editor/utils/after-update-cell.d.ts

@@ -50,9 +50,13 @@ interface AfterUpdateCellParams {
     collabEnabled?: boolean;
     collabIsOwner?: boolean;
     remoteUpdateRef?: React.MutableRefObject<boolean>;
+    /** True while a peer's structural edit waits to remount the grid. */
+    structuralRemountPendingRef?: React.MutableRefObject<boolean>;
     localUserEditRef?: React.MutableRefObject<boolean>;
     /** Sheet that held the cell at commit time; falls back to the current sheet. */
     sheetId?: string;
+    /** The caller writes the cell to Yjs itself (paste and fill batch writes). */
+    skipPersist?: boolean;
 }
 /** True when data-block formulas (API / smart contract) should run for this edit. */
 export declare const shouldExecuteDataBlocks: (params: {

package/dist/editor/utils/format-gate.d.ts

@@ -15,9 +15,13 @@ export declare function readFormatVersion(doc: Y.Doc, dsheetId: string): number;
  */
 export declare function isFormatLocked(doc: Y.Doc | null | undefined, dsheetId?: string): boolean;
 /**
- * Checks `meta.format` now and while the sheet is open. On the first value
- * above SUPPORTED_FORMAT the sheet is locked (write helpers return early) and
- * `onLocked` runs once per watcher with that value, even if the sheet was
- * already locked by an earlier watcher. Returns an unsubscribe function.
+ * Make the grid read-only in the same tick the lock is seen. The Yjs writers
+ * stop at once (isFormatLocked), but the grid became read-only only after the
+ * workbook data changed identity and the Workbook init effect ran: a commit in
+ * between showed in the grid, never reached Yjs, and was gone on reload.
+ * The Workbook init effect sets the same flag from the prop afterwards.
  */
+export declare function lockWorkbookReadOnly(workbook: {
+    getWorkbookSetContext?: () => unknown;
+} | null | undefined): boolean;
 export declare function watchFormatGate(doc: Y.Doc, dsheetId: string, onLocked: (format: number) => void): () => void;

package/dist/editor/utils/legacy-on-change.d.ts

@@ -0,0 +1,20 @@
+/** The legacy `onChange` argument pair: plain sheet data and the encoded doc. */
+export type LegacyOnChangeArgs = {
+    data: unknown;
+    update: string;
+};
+export declare const LEGACY_ON_CHANGE_WAIT_MS = 1000;
+/**
+ * Trailing-only throttle for the host's legacy `onChange`.
+ *
+ * The host's handler is read when the throttle fires, not when it is created.
+ * A host that passes a new inline `onChange` on every render must not rebuild
+ * this throttle: rebuilding cancels the pending call, so an edit followed
+ * within the wait by a re-render never reached the host's save.
+ * `buildArgs` runs only when there is a handler, because it encodes the whole
+ * document.
+ */
+export declare function createLegacyOnChangeThrottle<TData>(getOnChange: () => ((data: TData, update: string) => void) | undefined, buildArgs: () => {
+    data: TData;
+    update: string;
+} | null, waitMs?: number): any;

package/dist/editor/utils/legacy-on-change.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/editor/utils/rebuild-indexeddb-store.d.ts

@@ -8,5 +8,12 @@ import type * as Y from 'yjs';
  * fresh row. `onCreated` runs right after the new provider is constructed,
  * before it has synced, so the caller can track it and attach listeners. The Y.Doc is never replaced or cleared. Unlike delete-and-reopen
  * (heal), edits that exist only in the live doc are kept.
+ *
+ * The wait for the new provider is bounded: `whenSynced` never rejects, and a
+ * provider destroyed before its first read (a bootstrap restarting meanwhile)
+ * never syncs. It rejects on `timeoutMs` or once `isCurrent()` is false.
  */
-export declare function rebuildIndexedDbStore(dsheetId: string, doc: Y.Doc, current: IndexeddbPersistence | null, onCreated?: (provider: IndexeddbPersistence) => void): Promise<IndexeddbPersistence>;
+export declare function rebuildIndexedDbStore(dsheetId: string, doc: Y.Doc, current: IndexeddbPersistence | null, onCreated?: (provider: IndexeddbPersistence) => void, syncOptions?: {
+    timeoutMs?: number;
+    isCurrent?: () => boolean;
+}): Promise<IndexeddbPersistence>;

package/dist/editor/utils/remote-apply-guard.d.ts

@@ -11,6 +11,18 @@ export type RemoteApplyGuardRefs = {
     remoteApplyDepthRef: MutableRefObject<number>;
     remoteUpdateRef: MutableRefObject<boolean>;
 };
+/**
+ * True when an engine → Yjs echo hook (calcChain, conditional formats, ...)
+ * must stay quiet: a remote apply is running, or a structural remount is
+ * pending. While one is pending the engine still has the grid from before the
+ * peer's insert or delete, so a diff of its metadata against Yjs would write
+ * the old coordinates over the peer's (and delete the peer's calcChain
+ * entries). Cell commits are not echo hooks and are not held back by this.
+ */
+export declare function shouldSkipEchoWrite(refs: {
+    remoteUpdateRef: MutableRefObject<boolean>;
+    structuralRemountPendingRef?: MutableRefObject<boolean>;
+}): boolean;
 export declare function syncRemoteUpdateFlag(refs: RemoteApplyGuardRefs): void;
 export declare function beginRemoteApply(refs: RemoteApplyGuardRefs): void;
 export declare function endRemoteApply(refs: RemoteApplyGuardRefs): void;
@@ -25,9 +37,12 @@ export type StructuralRemountRefs = RemoteApplyGuardRefs & {
  * The guard is begun once, right before `run`, and ended after paint, so each
  * remount owns exactly one begin and one end. It is NOT held while the timer
  * is merely pending or deferred by a cell edit: `remoteUpdateRef` makes
- * handleChange, guardRemoteEcho and afterUpdateCell drop local writes, so
- * holding it across an edit would drop the user's commit. Events that land
- * while one is pending only re-arm its timer.
+ * handleChange and the data-block work in afterUpdateCell drop local work, so
+ * holding it across an edit would drop the user's typed edit. (The cell write
+ * in afterUpdateCell and the commit-time write do not check it.) What must not
+ * run while a remount is pending is the engine → Yjs echo hooks, which diff
+ * the old grid against Yjs: they check `shouldSkipEchoWrite`. Events that
+ * land while one is pending only re-arm its timer.
  *
  * While `isEditing()` is true at fire time the timer re-arms (250 ms) and the
  * pending flag is kept; the remount runs once the edit ends.
@@ -41,5 +56,12 @@ export declare const STRUCTURAL_REMOUNT_EDIT_RETRY_MS = 250;
  * to release here.
  */
 export declare function cancelStructuralRemount(refs: StructuralRemountRefs): void;
+/**
+ * Run `fn` under the guard and keep it until paint (a remount follows). If
+ * `fn` throws, the guard is ended at once and the error is rethrown: a begin
+ * with no matching end leaves the depth above zero, and `handleChange` then
+ * drops every local write until reload.
+ */
+export declare function runRemoteApplyUntilPaint<T>(refs: RemoteApplyGuardRefs, fn: () => T): T;
 /** End after Workbook remount hooks have flushed (2 rAF ≈ one paint). */
 export declare function endRemoteApplyAfterPaint(refs: RemoteApplyGuardRefs): void;

package/dist/editor/utils/wait-for-sync.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Waits for a y-indexeddb provider without trusting it to finish.
+ *
+ * In y-indexeddb 9.0.12 `whenSynced` resolves only on 'synced'. It has no
+ * reject path, and a provider that is destroyed before its first read, or whose
+ * first read never completes, never syncs. Awaiting it directly hangs the
+ * bootstrap, and a rebuild that waits for the bootstrap hangs with it.
+ */
+export declare const INDEXEDDB_SYNC_TIMEOUT_MS = 15000;
+/** How long a rebuild waits for a running bootstrap before it abandons it. */
+export declare const REBUILD_BOOTSTRAP_WAIT_MS = 3000;
+export declare class PersistenceSyncTimeoutError extends Error {
+    constructor(ms: number);
+}
+export declare class PersistenceSupersededError extends Error {
+    constructor();
+}
+/**
+ * Resolves when `whenSynced` does. Rejects with PersistenceSyncTimeoutError
+ * after `timeoutMs`, or with PersistenceSupersededError as soon as
+ * `isCurrent()` turns false (checked every 100 ms): a newer bootstrap or an
+ * unmount owns the provider then, and it may already be destroyed.
+ */
+export declare function waitForPersistenceSynced(persistence: {
+    whenSynced: Promise<unknown>;
+}, options?: {
+    timeoutMs?: number;
+    isCurrent?: () => boolean;
+}): Promise<void>;
+/**
+ * Waits for a running bootstrap for at most `ms`. 'stuck' means it has not
+ * settled; the caller then abandons it (bumps the generation) instead of
+ * waiting for a provider that may never sync.
+ */
+export declare function waitForBootstrapOrAbandon(bootstrap: Promise<unknown>, ms?: number): Promise<'settled' | 'stuck'>;

package/dist/editor/utils/wait-for-sync.test.d.ts

@@ -0,0 +1 @@
+export {};