@fileverse-dev/dsheet 4.0.6 → 4.1.1-edit-mode-14

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

@@ -0,0 +1,11 @@
+interface WorkbookControlItemsInput {
+    isReadOnly: boolean;
+    allowComments: boolean;
+    isRTCActive: boolean;
+}
+export declare const getWorkbookControlItems: ({ isReadOnly, allowComments, }: WorkbookControlItemsInput) => {
+    cellContextMenu: string[];
+    headerContextMenu: string[];
+    toolbarItems: string[];
+};
+export {};

package/dist/editor/components/editor-workbook-controls.test.d.ts

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

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

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { SidebarPortalRegistryHandle, SidebarPortalRenderer } from '../../sheet-engine/react';
 import { ThemeKey } from '../../sheet-engine/core/theme';
-import { OnboardingHandlerType } from '../types';
+import { OnboardingHandlerType, DSheetPermissionMode } from '../types';
 import { CommentsConfig } from '../types/comments';
 
 type OnboardingHandler = OnboardingHandlerType;
@@ -24,6 +24,10 @@ interface EditorWorkbookProps {
     sidebarActivePanel?: string | null;
     sidebarPortalRegistry?: SidebarPortalRegistryHandle | null;
     sidebarPortalRenderers?: Record<string, SidebarPortalRenderer>;
+    permissionMode?: DSheetPermissionMode | null;
+    onEnterEdit?: () => void;
+    onSignInToComment?: () => void;
+    onViewerModeChange?: (mode: 'comment' | 'view') => void;
     theme?: ThemeKey;
 }
 export declare const EditorWorkbook: React.NamedExoticComponent<EditorWorkbookProps>;

package/dist/editor/components/permission-chip-model.d.ts

@@ -0,0 +1,34 @@
+import { DSheetPermissionMode } from '../types';
+
+export declare const getPermissionChipConfig: (mode: DSheetPermissionMode) => {
+    readonly icon: "Eye";
+    readonly label: "View only";
+    readonly modifier: "view-only";
+} | {
+    readonly icon: "MessageSquareText";
+    readonly label: "View and comment";
+    readonly modifier: "comment";
+} | {
+    readonly icon: "Pencil";
+    readonly label: "Edit";
+    readonly modifier: "edit";
+};
+export declare const canShowEditElevation: ({ mode, onEnterEdit, }: {
+    mode: DSheetPermissionMode;
+    onEnterEdit?: () => void;
+}) => boolean;
+export declare const canShowViewerModeMenu: ({ mode, onViewerModeChange, }: {
+    mode: DSheetPermissionMode;
+    onViewerModeChange?: (mode: "comment" | "view") => void;
+}) => boolean;
+export declare const canShowCommentSignIn: ({ mode, onEnterEdit, onSignInToComment, onViewerModeChange, }: {
+    mode: DSheetPermissionMode;
+    onEnterEdit?: () => void;
+    onSignInToComment?: () => void;
+    onViewerModeChange?: (mode: "comment" | "view") => void;
+}) => boolean;
+export declare const resolvePermissionChipMode: ({ allowComments, isReadOnly, permissionMode, }: {
+    allowComments: boolean;
+    isReadOnly: boolean;
+    permissionMode?: DSheetPermissionMode;
+}) => DSheetPermissionMode | null;

package/dist/editor/components/permission-chip.d.ts

@@ -1,7 +1,11 @@
 import { default as React } from 'react';
+import { DSheetPermissionMode } from '../types';
 
 interface PermissionChipProps {
-    allowComments: boolean;
+    mode: DSheetPermissionMode;
+    onEnterEdit?: () => void;
+    onSignInToComment?: () => void;
+    onViewerModeChange?: (mode: 'comment' | 'view') => void;
 }
 export declare const PermissionChip: React.FC<PermissionChipProps>;
 export {};

package/dist/editor/components/permission-chip.test.d.ts

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

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

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 import { LiveQueryData, Sheet, WorkbookInstance } from '../../sheet-engine/react';
 import { IndexeddbPersistence } from 'y-indexeddb';
-import { SheetUpdateData, DataBlockEvent } from '../types';
+import { SheetUpdateData, DataBlockEvent, DSheetEditorHandle } from '../types';
 import { CommentsConfig } from '../types/comments';
 import { ApiKeyStorage } from '../utils/api-key-storage';
 import { OpenApiKeyModalFn } from '../utils/data-block-error-handler';
@@ -32,6 +32,7 @@ export interface EditorContextType {
     }>>;
     refreshIndexedDB: () => Promise<void>;
     sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>;
+    setSheetEditorRef: React.RefCallback<WorkbookInstance>;
     ydocRef: React.MutableRefObject<Y.Doc | null>;
     persistenceRef: React.MutableRefObject<IndexeddbPersistence | null>;
     sheetData: Sheet[];
@@ -45,6 +46,7 @@ export interface EditorContextType {
     setForceSheetRender: React.Dispatch<React.SetStateAction<number>>;
     syncStatus: 'initializing' | 'syncing' | 'synced' | 'error';
     collabEnabled?: boolean;
+    isLiveCollabSession: boolean;
     collabIsOwner?: boolean;
     collabState?: CollabState;
     isCollabReady?: boolean;
@@ -79,7 +81,8 @@ interface EditorProviderProps {
     onContentUpdate?: () => void;
     onChange?: (data: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
-    externalEditorRef?: React.MutableRefObject<WorkbookInstance | null>;
+    externalEditorRef?: React.Ref<DSheetEditorHandle>;
+    legacyEditorRef?: React.Ref<DSheetEditorHandle>;
     commentsConfig?: CommentsConfig;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
@@ -87,6 +90,10 @@ interface EditorProviderProps {
         mergeContent: (encodedState: string) => DSheetContentSnapshot;
         terminateSession?: () => void;
         updateCollaboratorName?: (name: string) => void;
+        updateSessionTitle?: (args: {
+            encryptedTitle: string;
+            documentTitle: string;
+        }) => void;
         rehydrateAfterCollabSync?: (reason?: string) => boolean;
     } | null>;
     enableLiveQuery?: boolean;
@@ -95,6 +102,8 @@ interface EditorProviderProps {
     onDataBlockEvent?: (event: DataBlockEvent) => void;
     smartContracts?: SmartContractConfig;
     onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
+    onCollaborationInitializationComplete?: (result: 'ready' | 'error') => void;
+    onIndexedDbError?: (error: Error) => void;
 }
 export declare const EditorProvider: React.FC<EditorProviderProps>;
 export declare const useEditor: () => EditorContextType;

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

@@ -1,4 +1,5 @@
-import { DsheetProps } from './types';
+import { default as React } from 'react';
+import { DSheetEditorHandle, DsheetProps } from './types';
 
 /**
  * SpreadsheetEditor component that provides a collaborative spreadsheet interface
@@ -7,5 +8,5 @@ import { DsheetProps } from './types';
  * @param props - Component properties
  * @returns The SpreadsheetEditor component
  */
-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;
+declare const SpreadsheetEditor: React.ForwardRefExoticComponent<DsheetProps & React.RefAttributes<DSheetEditorHandle>>;
 export default SpreadsheetEditor;

package/dist/editor/hooks/collaboration-lifecycle.d.ts

@@ -0,0 +1,35 @@
+import { CollabConnectionConfig, CollaborationProps } from '../../sync-local/types';
+
+export declare const COLLAB_WARM_MS = 30000;
+export declare const shouldKeepCollaborationSocketAlive: (connection: CollabConnectionConfig) => boolean;
+export declare const isLiveCollaborationSession: (collaboration?: CollaborationProps) => boolean;
+export declare const isQualifyingCollaborationEdit: (origin: unknown, indexeddbOrigin: unknown, isBootstrapReady: boolean) => boolean;
+export declare const shouldRenderBootstrappedWorkbook: (collabEnabled: boolean, sheetCount: number) => boolean;
+export declare const shouldInitializeDefaultWorkbook: (syncStatus: string | undefined, collabEnabled: boolean, collabStatus: string | undefined) => boolean;
+export declare const getWorkbookHydrationReason: (status: string | undefined, previousStatus: string | undefined, hasHydratedReadyState: boolean) => "initial" | "reconnect" | null;
+export declare const shouldRehydrateWorkbookOnReady: ({ reason, isOwner, hasUnmergedPeerUpdates, }: {
+    reason: "initial" | "reconnect";
+    isOwner: boolean;
+    hasUnmergedPeerUpdates: boolean;
+}) => boolean;
+export interface CollaborationConnectionController {
+    onYdocUpdate: (update: Uint8Array, origin: unknown) => void;
+    dispose: () => void;
+}
+export declare const createCollaborationConnectionController: (args: {
+    connection: CollabConnectionConfig;
+    isSocketConnectedRef: {
+        current: boolean;
+    };
+    getIndexeddbOrigin: () => unknown;
+    isBootstrapReady: boolean;
+    connect: (connection: CollabConnectionConfig) => void;
+    disconnect: () => void;
+}) => CollaborationConnectionController;
+/**
+ * Merge the published artifact into the editor's one durable Y.Doc before
+ * IndexedDB replay and collaboration hydration. The `self` origin prevents a
+ * late package listener from treating the host seed as a live user edit;
+ * SyncManager's state-vector diff still sees it when the room is hydrated.
+ */
+export declare const mergePublishedContentIntoYdoc: (ydoc: import('yjs').Doc, encodedContent?: string) => boolean;

package/dist/editor/hooks/collaboration-lifecycle.test.d.ts

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

package/dist/editor/hooks/use-collab-awareness.d.ts

@@ -1,17 +1,14 @@
 import { Awareness } from 'y-protocols/awareness';
 import { WorkbookInstance } from '../../sheet-engine/react';
-import { CollabUser } from '../../sync-local/types';
 
 /**
  * Reads remote cursor positions from Yjs awareness and keeps Fortune sheet's
  * native presence list in sync. Fortune renders colored cell borders + username
  * labels automatically via context.presences[].
  *
- * Also emits the full collaborator list (including the local user) via
- * `onCollaboratorsChange` so host apps can render navbar chips. This mirrors
- * ddoc's editor-layer awareness handler, which maps awareness.states →
- * `{ clientId, ...user }` and fires on every awareness update + once on mount.
+ * The host collaborator roster is emitted by SocketClient from the
+ * authoritative server room-members list. This hook owns only cell cursors.
  */
-export declare const useCollabAwareness: (awareness: Awareness | null | undefined, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, onCollaboratorsChange?: (collaborators: CollabUser[]) => void) => {
+export declare const useCollabAwareness: (awareness: Awareness | null | undefined, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>) => {
     localColor: "#30bced" | "#6eeb83" | "#fa69d1" | "#ecd444" | "#ee6352" | "#db3041" | "#0ad7f2" | "#1bff39";
 };

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

@@ -8,7 +8,7 @@ import * as Y from 'yjs';
  * Hook for managing sheet data
  * Handles initialization, updates, and persistence of sheet data
  */
-export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | null>, dsheetId: string, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>, portalContent?: string, isReadOnly?: boolean, onChange?: (data: Sheet[]) => void, syncStatus?: "initializing" | "syncing" | "synced" | "error", commentData?: object, dataBlockCalcFunction?: {
+export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | null>, dsheetId: string, sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>, isReadOnly?: boolean, onChange?: (data: Sheet[]) => void, syncStatus?: "initializing" | "syncing" | "synced" | "error", isContentBootstrapReady?: boolean, commentData?: object, dataBlockCalcFunction?: {
     [key: string]: {
         [key: string]: any;
     };
@@ -16,7 +16,7 @@ export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | nul
     [key: string]: {
         [key: string]: any;
     };
-}>>, enableLiveQuery?: boolean, liveQueryRefreshRate?: number, apiKeyStorage?: ApiKeyStorage, openApiKeyModal?: OpenApiKeyModalFn, onDataBlockEvent?: (event: DataBlockEvent) => void, allowComments?: boolean, hasCollabContentInitialised?: boolean, collabEnabled?: boolean) => {
+}>>, enableLiveQuery?: boolean, liveQueryRefreshRate?: number, apiKeyStorage?: ApiKeyStorage, openApiKeyModal?: OpenApiKeyModalFn, onDataBlockEvent?: (event: DataBlockEvent) => void, allowComments?: boolean, collabEnabled?: boolean) => {
     sheetData: Sheet[];
     setSheetData: import('react').Dispatch<import('react').SetStateAction<Sheet[]>>;
     currentDataRef: import('react').MutableRefObject<Sheet[]>;

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

@@ -1,11 +1,11 @@
 import { IndexeddbPersistence } from 'y-indexeddb';
 import { CollaborationProps } from '../../sync-local/types';
 import * as Y from 'yjs';
-export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boolean, isReadOnly?: boolean, collaboration?: CollaborationProps, onCollabUpdate?: (fullState: string, updateChunk: string) => void) => {
+export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boolean, isReadOnly?: boolean, portalContent?: string, collaboration?: CollaborationProps, onCollabUpdate?: (fullState: string, updateChunk: string) => void, onIndexedDbError?: (error: Error) => void) => {
     ydocRef: import('react').MutableRefObject<Y.Doc | null>;
     persistenceRef: import('react').MutableRefObject<IndexeddbPersistence | null>;
     syncStatus: "error" | "syncing" | "initializing" | "synced";
-    isSyncedRef: import('react').MutableRefObject<boolean>;
+    isContentBootstrapReady: boolean;
     refreshIndexedDB: () => Promise<void>;
     getContentSnapshot: () => import('../../persistence-utils').DSheetContentSnapshot;
     mergeContent: (encodedState: string) => import('../../persistence-utils').DSheetContentSnapshot;
@@ -13,6 +13,10 @@ export declare const useEditorSync: (dsheetId: string, enableIndexeddbSync?: boo
     isCollabReady: boolean;
     isCollabSyncing: boolean;
     terminateSession: () => void;
+    updateTitle: (args: {
+        encryptedTitle: string;
+        documentTitle: string;
+    }) => void;
     awareness: import('y-protocols/awareness.js').Awareness | null;
     hasCollabContentInitialised: boolean;
 };

package/dist/editor/types.d.ts

@@ -10,6 +10,7 @@ import { DSheetContentSnapshot } from '../persistence';
 
 import * as Y from 'yjs';
 export type { ThemeKey } from '../sheet-engine/core/theme';
+export type DSheetPermissionMode = 'view' | 'comment' | 'edit';
 export type { CommentThread, CommentReply, CommentActionParams, CommentsConfig, } from './types/comments';
 export { CommentAction } from './types/comments';
 export interface SheetUpdateData {
@@ -22,6 +23,15 @@ export interface EditorValues {
     openPanel: (panelId: string) => void;
     closePanel: () => void;
 }
+export type DSheetEditorHandle = WorkbookInstance & {
+    refreshIndexedDB: () => Promise<void>;
+    terminateSession: () => void;
+    updateCollaboratorName: (name: string) => void;
+    updateSessionTitle: (args: {
+        encryptedTitle: string;
+        documentTitle: string;
+    }) => void;
+};
 export interface PanelConfig {
     id: string;
     header: {
@@ -67,9 +77,23 @@ export interface DsheetProps {
     onContentUpdate?: () => void;
     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. */
+    onIndexedDbError?: (error: Error) => void;
     username?: string;
     portalContent?: string;
     isReadOnly?: boolean;
+    /** Permission status displayed above the toolbar. When omitted, read-only
+     * sheets retain the existing View/View-and-comment behavior. */
+    permissionMode?: DSheetPermissionMode;
+    /** Called when a read-only consumer asks to elevate to edit mode. The host
+     * owns access proof, loading, errors, and the resulting mode transition. */
+    onEnterEdit?: () => void;
+    /** Called when an invited commenter needs to authenticate before the host can
+     * recover comment capability. */
+    onSignInToComment?: () => void;
+    /** Lets the host toggle a recovered commenter between comment and view mode. */
+    onViewerModeChange?: (mode: 'comment' | 'view') => void;
     allowSheetDownload?: boolean;
     isTemplateOpen?: boolean;
     selectedTemplate?: string;
@@ -80,9 +104,8 @@ export interface DsheetProps {
     setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>;
     commentsConfig?: CommentsConfig;
     toggleTemplateSidebar?: () => void;
-    sheetEditorRef?: RefObject<WorkbookInstance & {
-        refreshIndexedDB: () => Promise<void>;
-    }>;
+    /** Legacy ref prop. Standard React refs are also supported. */
+    sheetEditorRef?: React.Ref<DSheetEditorHandle>;
     /** Override where datablock API keys are stored (default: localStorage). */
     apiKeyStorage?: ApiKeyStorage;
     /** Optional lifecycle events for analytics / side-effects. */
@@ -93,6 +116,9 @@ export interface DsheetProps {
      * collab start/resume on 'synced' — starting before local content is fully
      * synced is what let the RTC layer bind to a stale doc in the past. */
     onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
+    /** Fires once the first collaboration sync has been reconciled with the
+     * workbook, or when that reconciliation fails. */
+    onCollaborationInitializationComplete?: (result: 'ready' | 'error') => void;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
         getContentSnapshot: () => DSheetContentSnapshot;

package/dist/editor/utils/detach-workbook-data.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Creates a private data snapshot for the workbook. The workbook deep-freezes
+ * its input when storing it in Immer state, so passing currentDataRef directly
+ * would also freeze the Yjs-derived collaboration data. Later sync and comment
+ * marker updates would then throw when mutating that shared source. Cloning here
+ * keeps workbook state immutable while collaboration data remains mutable.
+ */
+export declare const detachWorkbookData: <T>(data: T) => T;

package/dist/editor/utils/detach-workbook-data.test.d.ts

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

package/dist/editor/utils/editor-handle.d.ts

@@ -0,0 +1,11 @@
+import { Ref } from 'react';
+import { WorkbookInstance } from '../../sheet-engine/react';
+import { DSheetEditorHandle } from '../types';
+
+export type DSheetEditorMethods = Pick<DSheetEditorHandle, "refreshIndexedDB" | "terminateSession" | "updateCollaboratorName" | "updateSessionTitle">;
+/**
+ * Compose Fortune's regenerated imperative handle with dSheet lifecycle methods.
+ * React callback refs invoke this again after every Workbook remount, so both
+ * standard forwarded refs and the legacy sheetEditorRef prop stay current.
+ */
+export declare const attachDSheetEditorHandle: (workbook: WorkbookInstance | null, methods: DSheetEditorMethods, refs: Array<Ref<DSheetEditorHandle> | undefined>) => DSheetEditorHandle | null;

package/dist/editor/utils/editor-handle.test.d.ts

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