@fileverse-dev/dsheet 2.1.5 → 3.0.1-formula-1

package/dist/editor/components/smart-contract/use-modal-outside-click.d.ts

@@ -0,0 +1,18 @@
+import { MutableRefObject } from 'react';
+
+interface UseFetchUrlModalProps {
+    onClose?: () => void;
+    setInputAddress?: React.Dispatch<React.SetStateAction<string>>;
+    shouldPreventClose?: MutableRefObject<boolean>;
+}
+export declare const useModalOutsideClick: ({ onClose, setInputAddress, shouldPreventClose, }?: UseFetchUrlModalProps) => {
+    rowCount: number;
+    setRowCount: import('react').Dispatch<import('react').SetStateAction<number>>;
+    includeHeaders: boolean;
+    setIncludeHeaders: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    abortCall: boolean;
+    modalDivRef: import('react').RefObject<HTMLDivElement>;
+    resetModalState: () => void;
+    handleClose: () => void;
+};
+export {};

package/dist/editor/components/smart-contract/use-smart-contract-modal.d.ts

@@ -0,0 +1,38 @@
+import { Hex } from 'viem';
+import { ContractConfig, SupportedChain } from '../../types/smart-contract';
+
+export declare function useSmartContractModal({ onSaveContract, setShowSmartContractModal, registryMapRef, }: {
+    onSaveContract: (address: Hex, chain: SupportedChain, abi: string, smartContractName: string) => Promise<void>;
+    setShowSmartContractModal: (show: boolean) => void;
+    registryMapRef: React.MutableRefObject<Record<string, ContractConfig>>;
+}): {
+    inputAddress: string;
+    setInputAddress: import('react').Dispatch<import('react').SetStateAction<string>>;
+    selectedChain: SupportedChain;
+    setSelectedChain: import('react').Dispatch<import('react').SetStateAction<SupportedChain>>;
+    formStep: number;
+    setFormStep: import('react').Dispatch<import('react').SetStateAction<number>>;
+    abiCode: string;
+    setAbiCode: import('react').Dispatch<import('react').SetStateAction<string>>;
+    uploadedFile: any;
+    setUploadedFile: import('react').Dispatch<any>;
+    uploadProgress: number;
+    setUploadProgress: import('react').Dispatch<import('react').SetStateAction<number>>;
+    isUploading: boolean;
+    setIsUploading: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    fileInputRef: import('react').MutableRefObject<any>;
+    smartContractName: string;
+    setSmartContractName: import('react').Dispatch<import('react').SetStateAction<string>>;
+    isImportingRef: import('react').MutableRefObject<boolean>;
+    modalDivRef: import('react').RefObject<HTMLDivElement>;
+    handleFileInputChange: (e: any) => void;
+    handleUploadAreaClick: () => void;
+    handleRemoveFile: () => void;
+    handleAddressInputChange: (url: string) => void;
+    onClickProceed: (abi?: any) => Promise<void>;
+    isValidAddress: boolean;
+    registryMapRef: import('react').MutableRefObject<Record<string, ContractConfig>>;
+    errorState: {
+        message: string;
+    } | null;
+};

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

@@ -1,7 +1,12 @@
 import { default as React } from 'react';
 import { LiveQueryData, Sheet, WorkbookInstance } from '../../sheet-engine/react';
 import { IndexeddbPersistence } from 'y-indexeddb';
-import { DataBlockApiKeyHandlerType, SheetUpdateData } from '../types';
+import { SheetUpdateData, DataBlockEvent } from '../types';
+import { CommentsConfig } from '../types/comments';
+import { ApiKeyStorage } from '../utils/api-key-storage';
+import { OpenApiKeyModalFn } from '../utils/data-block-error-handler';
+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';
 
@@ -48,11 +53,19 @@ export interface EditorContextType {
     terminateSession?: () => void;
     onCollaboratorsChange?: (collaborators: CollabUser[]) => void;
     handleLiveQuery: (subsheetIndex: number, data: LiveQueryData) => void;
+    apiKeyStorage: ApiKeyStorage;
+    onDataBlockEvent?: (event: DataBlockEvent) => void;
+    openApiKeyModal: OpenApiKeyModalFn;
+    apiKeyModalState: {
+        open: boolean;
+        apiKeyName: string;
+        onSave: (key: string) => void;
+        onClose: () => void;
+    } | null;
+    smartContract: UseSmartContractReturn;
 }
 interface EditorProviderProps {
-    allowComments?: boolean;
     setSelectedTemplate?: React.Dispatch<React.SetStateAction<string>>;
-    setShowSmartContractModal?: React.Dispatch<React.SetStateAction<boolean>>;
     getDocumentTitle?: (dsheetId: string) => Promise<string>;
     updateDocumentTitle?: (title: string) => void;
     isAuthorized: boolean;
@@ -65,7 +78,7 @@ interface EditorProviderProps {
     onChange?: (data: SheetUpdateData, encodedUpdate?: string) => void;
     collaboration?: CollaborationProps;
     externalEditorRef?: React.MutableRefObject<WorkbookInstance | null>;
-    commentData?: object;
+    commentsConfig?: CommentsConfig;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
         terminateSession?: () => void;
@@ -74,7 +87,9 @@ interface EditorProviderProps {
     } | null>;
     enableLiveQuery?: boolean;
     liveQueryRefreshRate?: number;
-    dataBlockApiKeyHandler?: DataBlockApiKeyHandlerType;
+    apiKeyStorage?: ApiKeyStorage;
+    onDataBlockEvent?: (event: DataBlockEvent) => void;
+    smartContracts?: SmartContractConfig;
     onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
 }
 export declare const EditorProvider: React.FC<EditorProviderProps>;

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, allowComments, renderNavbar, enableIndexeddbSync, dsheetId, portalContent, onChange, username, selectedTemplate, toggleTemplateSidebar, isTemplateOpen, onboardingComplete, onboardingCompleteLocalStorageKey, onboardingHandler, commentData, getCommentCellUI, dataBlockApiKeyHandler, setFetchingURLData, setShowFetchURLModal, setInputFetchURLDataBlock, sheetEditorRef: externalSheetEditorRef, storeApiKey, onDuneChartEmbed, onSheetCountChange, onDataBlockApiResponse, isAuthorized, getDocumentTitle, updateDocumentTitle, setShowSmartContractModal, editorStateRef, handleSmartContractQuery, setSelectedTemplate, isNewSheet, liveQueryRefreshRate, enableLiveQuery, collaboration, onContentSyncStatusChange, }: DsheetProps) => JSX.Element;
+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;
 export default SpreadsheetEditor;

package/dist/editor/hooks/live-query/use-live-query.d.ts

@@ -1,8 +1,10 @@
 import { LiveQueryData, Sheet, WorkbookInstance } from '../../../sheet-engine/react';
-import { DataBlockApiKeyHandlerType } from '../../types';
+import { ApiKeyStorage } from '../../utils/api-key-storage';
+import { OpenApiKeyModalFn } from '../../utils/data-block-error-handler';
+import { DataBlockEvent } from '../../types';
 
 export declare const LIVE_QUERY_ERROR = "LIVE_QUERY_ERROR";
-export declare const useLiveQuery: (sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, dataBlockApiKeyHandler?: DataBlockApiKeyHandlerType, enableLiveQuery?: boolean, refreshRate?: number) => {
+export declare const useLiveQuery: (sheetEditorRef: React.MutableRefObject<WorkbookInstance | null>, apiKeyStorage?: ApiKeyStorage, openApiKeyModal?: OpenApiKeyModalFn, onDataBlockEvent?: (event: DataBlockEvent) => void, enableLiveQuery?: boolean, refreshRate?: number) => {
     handleLiveQuery: (subsheetIndex: number, queryData: LiveQueryData) => void;
     initialiseLiveQueryData: (sheets: Sheet[]) => void;
 };

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-data.d.ts

@@ -1,5 +1,7 @@
 import { Sheet, WorkbookInstance } from '../../sheet-engine/react';
-import { DataBlockApiKeyHandlerType } from '../types';
+import { ApiKeyStorage } from '../utils/api-key-storage';
+import { OpenApiKeyModalFn } from '../utils/data-block-error-handler';
+import { DataBlockEvent } from '../types';
 
 import * as Y from 'yjs';
 /**
@@ -14,7 +16,7 @@ export declare const useEditorData: (ydocRef: React.MutableRefObject<Y.Doc | nul
     [key: string]: {
         [key: string]: any;
     };
-}>>, enableLiveQuery?: boolean, liveQueryRefreshRate?: number, dataBlockApiKeyHandler?: DataBlockApiKeyHandlerType, allowComments?: boolean, hasCollabContentInitialised?: boolean, collabEnabled?: boolean) => {
+}>>, enableLiveQuery?: boolean, liveQueryRefreshRate?: number, apiKeyStorage?: ApiKeyStorage, openApiKeyModal?: OpenApiKeyModalFn, onDataBlockEvent?: (event: DataBlockEvent) => void, allowComments?: boolean, hasCollabContentInitialised?: boolean, collabEnabled?: boolean) => {
     sheetData: Sheet[];
     setSheetData: import('react').Dispatch<import('react').SetStateAction<Sheet[]>>;
     currentDataRef: import('react').MutableRefObject<Sheet[]>;

package/dist/editor/hooks/use-smart-contract.d.ts

@@ -0,0 +1,26 @@
+import { Abi, Hex } from 'viem';
+import { ContractConfig, ContractRegistry, SmartContractConfig, SupportedChain } from '../types/smart-contract';
+import { SmartContractQueryHandler } from '../utils/after-update-cell';
+
+export declare const useSmartContract: (config?: SmartContractConfig) => {
+    enabled: boolean;
+    showSmartContractModal: boolean;
+    setShowSmartContractModal: import('react').Dispatch<import('react').SetStateAction<boolean>>;
+    userSmartContracts: ContractConfig[];
+    allUserContracts: ContractConfig[];
+    registryMapRef: import('react').MutableRefObject<ContractRegistry>;
+    handleSmartContractQuery: SmartContractQueryHandler | undefined;
+    onImportContract: (address: Hex, network: SupportedChain, abiJson: string, smartContractName: string) => Promise<void>;
+    onDelete: (name: string) => Promise<void>;
+    handleSearch: (searchText: string) => void;
+    smartContractReadingError: {
+        hasError: boolean;
+        errorMessage: string;
+    };
+    setSmartContractReadingError: import('react').Dispatch<import('react').SetStateAction<{
+        hasError: boolean;
+        errorMessage: string;
+    }>>;
+    fetchContractAbi: (contract: ContractConfig) => Promise<Abi>;
+};
+export type UseSmartContractReturn = ReturnType<typeof useSmartContract>;

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

@@ -11,6 +11,13 @@ export type XlsxImportRuntimeDeps = {
     updateDocumentTitle?: (title: string) => void;
     filterToastShown: boolean;
     setFilterToastShown: React.Dispatch<React.SetStateAction<boolean>>;
+    handleContentPortal?: () => void;
+};
+export type XlsxImportOptions = {
+    headless?: boolean;
+    suppressUiWarnings?: boolean;
+    onWarning?: (warning: string) => void;
+    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'): 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/comments.d.ts

@@ -0,0 +1,134 @@
+import { default as React } from 'react';
+
+export interface CommentThread {
+    id: string;
+    key: string;
+    dsheetId: string;
+    username: string;
+    content: string;
+    createdAt: string;
+    commentIndex: number;
+    cellContent?: string;
+    replies: CommentReply[];
+    isResolved?: boolean;
+    isDeleted?: boolean;
+}
+export interface CommentReply {
+    id: string;
+    username: string;
+    content: string;
+    createdAt: string;
+    commentIndex: number;
+    isResolved?: boolean;
+    isDeleted?: boolean;
+}
+export declare enum CommentAction {
+    RESOLVE = "resolve",
+    UNRESOLVE = "unresolve",
+    DELETE = "delete"
+}
+export interface CommentActionParams {
+    action: CommentAction;
+    commentId: string;
+    dsheetId: string;
+    commentKey: string;
+    isReply?: boolean;
+    parentCommentId?: string;
+    row: number;
+    col: number;
+}
+export interface CommentsConfig {
+    commentsData: Record<string, CommentThread>;
+    onSendComment: (key: string, textareaId: string) => void;
+    onCommentAction: (action: CommentActionParams) => void;
+    userName?: string;
+    ownerAddress?: string;
+    currentUserAddress?: string;
+    isOwner?: boolean;
+    isAuthenticated?: boolean;
+    unauthenticatedFallback?: React.ReactNode;
+    ensResolutionUrl?: string;
+    disabled?: boolean;
+}
+export interface CellPosition {
+    row: number;
+    col: number;
+    sheetId?: string;
+}
+export interface SheetEditorRef {
+    scroll: (o: {
+        scrollLeft?: number;
+        scrollTop?: number;
+        targetRow?: number;
+        targetColumn?: number;
+    }) => void;
+    setSelection: (s: Array<{
+        row: number[];
+        column: number[];
+    }>) => void;
+}
+export interface CommentInputProps {
+    id: string;
+    onSend: (textareaId: string) => void;
+    placeholder?: string;
+    autoFocus?: boolean;
+    className?: string;
+    backgroundColor?: string;
+    inCellComment?: boolean;
+    cancelComment?: () => void;
+    onBlur?: () => void;
+    isStaticButton?: boolean;
+    removeCancelButton?: boolean;
+    focusTrap?: boolean;
+    disabled?: boolean;
+}
+export interface CommentItemProps {
+    comment: CommentThread;
+    showAvatar?: boolean;
+    avatarSize?: 'sm' | 'md' | 'lg';
+    className?: string;
+    isHovered?: boolean;
+    sheetName?: string;
+    cellReference?: string;
+    onAction?: (a: CommentActionParams) => void;
+    ownerAddress?: string;
+    currentUserAddress?: string;
+    isOwner?: boolean;
+    currentUserName?: string;
+    contentClassName?: string;
+    isCellPopup?: boolean;
+    shouldShowActions?: boolean;
+    row?: number;
+    col?: number;
+}
+export interface CommentCellUIProps {
+    row: number;
+    col: number;
+    sheetId: string;
+    comment?: CommentThread;
+    onSendComment: (commentKey: string, textareaId: string) => void;
+    onAction?: (a: CommentActionParams) => void;
+    ownerAddress?: string;
+    currentUserAddress?: string;
+    isOwner?: boolean;
+    sheetEditorRef?: React.RefObject<SheetEditorRef>;
+    currentUserName?: string;
+    removeCommentFromCell: (row: number, col: number) => void;
+    closePopup?: () => void;
+    dragHandler: (e: React.MouseEvent<HTMLDivElement, MouseEvent>) => void;
+    isHover?: boolean;
+    disabled?: boolean;
+}
+export interface CommentsContentProps {
+    sheetEditorRef: React.RefObject<SheetEditorRef>;
+    userName: string | undefined;
+    commentsData: Record<string, CommentThread>;
+    onSendComment: (commentKey: string, textareaId: string) => void;
+    onCommentAction?: (a: CommentActionParams) => void;
+    ownerAddress?: string;
+    currentUserAddress?: string;
+    isOwner?: boolean;
+    disabled?: boolean;
+    isAuthenticated?: boolean;
+    unauthenticatedFallback?: React.ReactNode;
+}

package/dist/editor/types/smart-contract.d.ts

@@ -0,0 +1,88 @@
+import { Abi, Hex } from 'viem';
+import { default as React } from 'react';
+
+export declare enum SupportedChain {
+    Ethereum = "Ethereum",
+    Sepolia = "Sepolia",
+    Gnosis = "Gnosis",
+    Base = "Base"
+}
+export interface ContractConfig {
+    address: Hex;
+    abiHash: string;
+    network: SupportedChain;
+    name: string;
+}
+export type ContractRegistry = Record<string, ContractConfig>;
+export interface NewContractInput {
+    name: string;
+    address: Hex;
+    network: SupportedChain;
+    abi: Abi;
+}
+export type SmartContractEventType = 'query-success' | 'query-error' | 'contract-added' | 'contract-deleted';
+export interface SmartContractEvent {
+    type: SmartContractEventType;
+    contractName?: string;
+    functionName?: string;
+    chainName?: string;
+    errorMessage?: string;
+}
+export interface SmartContractConfig {
+    /** User's persisted private contracts from consumer keystore. Defaults to []. */
+    contracts?: ContractConfig[];
+    /** RPC URL per chain. Falls back to bundled defaults when omitted. */
+    rpcConfig?: Partial<Record<SupportedChain, string>>;
+    /** Resolve ABI from stored reference (e.g. IPFS hash). Required for user-saved contracts with abiHash. */
+    resolveAbi?: (abiHash: string) => Promise<Abi>;
+    /** Persist a new contract. When omitted, package keeps it in session memory only. */
+    onAddContract?: (input: NewContractInput) => Promise<void>;
+    /** Remove a persisted contract. When omitted, package removes from session memory only. */
+    onDeleteContract?: (contractName: string) => Promise<void>;
+    validateAddress?: (address: string, chain: SupportedChain) => boolean | Promise<boolean>;
+    onSmartContractEvent?: (event: SmartContractEvent) => void;
+}
+export interface CallerParams {
+    abi: Abi;
+    contractAddress: Hex;
+    chain: import('viem').Chain;
+    functionName?: string;
+    args?: unknown[];
+}
+export interface FetchAbiParams {
+    contractAddress: Hex;
+    chain: import('viem').Chain;
+    ipfsHash?: string;
+}
+export type ParsedFunction = {
+    functionName: string;
+    output: string;
+};
+export interface SmartContractListViewProps {
+    userSmartContracts: ContractConfig[];
+    onDelete: (name: string) => void;
+    handleSearch: (searchText: string) => void;
+    onOpenImportModal: () => void;
+    fetchContractAbi: (contract: ContractConfig) => Promise<Abi>;
+    isAuthorized: boolean;
+}
+export interface MyContractsProps {
+    contracts: ContractConfig[];
+    onDelete: (name: string) => void;
+    fetchContractAbi: (contract: ContractConfig) => Promise<Abi>;
+    setActiveTab?: React.Dispatch<React.SetStateAction<string>>;
+}
+export interface PopularContractsProps {
+    contracts: ContractConfig[];
+    onInsert: (name: string) => void;
+    fetchContractAbi: (contract: ContractConfig) => Promise<Abi>;
+}
+export interface CodeBlockProps {
+    code: React.ReactNode;
+    copyText: string;
+}
+export interface ParameterDescriptionProps {
+    paramName: string;
+    description: string;
+    optional?: boolean;
+}

package/dist/editor/types.d.ts

@@ -1,10 +1,16 @@
-import { Sheet, Workbook, WorkbookInstance, Cell } from '../sheet-engine/react';
-import { ComponentProps, RefObject } from 'react';
+import { Sheet, WorkbookInstance } from '../sheet-engine/react';
+import { RefObject } from 'react';
 import { ERROR_MESSAGES_FLAG } from './constants/shared-constants';
-import { SmartContractQueryHandler } from './utils/after-update-cell';
 import { CollaborationProps } from '../sync-local/types';
+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 * as Y from 'yjs';
+export type { ThemeKey } from '../sheet-engine/core/theme';
+export type { CommentThread, CommentReply, CommentActionParams, CommentsConfig, } from './types/comments';
+export { CommentAction } from './types/comments';
 export interface SheetUpdateData {
     data: Sheet[];
 }
@@ -12,7 +18,19 @@ export interface EditorValues {
     sheetEditorRef: RefObject<WorkbookInstance>;
     currentDataRef: React.MutableRefObject<Sheet[] | null>;
     ydocRef: React.RefObject<Y.Doc | null>;
+    openPanel: (panelId: string) => void;
+    closePanel: () => void;
 }
+export interface PanelConfig {
+    id: string;
+    header: {
+        title: string;
+        subtitle?: string;
+    };
+    width?: string;
+    content: React.ReactNode;
+}
+export type { PanelId, BuiltInPanelType, } from './components/sidebar/use-right-panels';
 export type OnboardingHandlerType = (params: {
     row: number;
     column: number;
@@ -21,31 +39,17 @@ export type OnboardingHandlerType = (params: {
     row: number;
     column: number;
 };
-export type DataBlockApiKeyHandlerType = (params: {
-    data: ErrorMessageHandlerReturnType;
-    sheetEditorRef: React.RefObject<WorkbookInstance | null>;
-    executeStringFunction: ({ functionCallString, sheetEditorRef, dataBlockRow, dataBlockColumn, handleSmartContractQuery, }: {
-        functionCallString: string;
-        sheetEditorRef: React.RefObject<WorkbookInstance | null>;
-        dataBlockRow: number;
-        dataBlockColumn: number;
-        handleSmartContractQuery: SmartContractQueryHandler;
-    }) => Promise<unknown>;
-    row: number;
-    column: number;
-    newValue: Cell;
-    formulaResponseUiSync: (params: {
-        row: number;
-        column: number;
-        newValue: Record<string, string>;
-        apiData: Array<Record<string, object>>;
-        sheetEditorRef: React.RefObject<WorkbookInstance | null>;
-    }) => void;
-}) => void;
+export type DataBlockEventType = 'success' | 'error' | 'api-key-required' | 'api-key-saved' | 'retry';
+export interface DataBlockEvent {
+    type: DataBlockEventType;
+    functionName?: string;
+    errorType?: string;
+    apiKeyName?: string;
+}
+export type { ApiKeyStorage } from './utils/api-key-storage';
 export interface DsheetProps {
     isNewSheet: boolean;
     setSelectedTemplate?: React.Dispatch<React.SetStateAction<string>>;
-    setShowSmartContractModal?: React.Dispatch<React.SetStateAction<boolean>>;
     getDocumentTitle?: (dsheetId: string) => Promise<string>;
     updateDocumentTitle?: (title: string) => void;
     isAuthorized: boolean;
@@ -67,17 +71,16 @@ export interface DsheetProps {
     /** When `onboardingComplete` is omitted, read `localStorage.getItem(key)==='true'` (default key `onboardingComplete`). */
     onboardingCompleteLocalStorageKey?: string;
     onboardingHandler?: OnboardingHandlerType;
-    dataBlockApiKeyHandler?: DataBlockApiKeyHandlerType;
     setForceSheetRender?: React.Dispatch<React.SetStateAction<number>>;
-    getCommentCellUI?: ComponentProps<typeof Workbook>['getCommentCellUI'];
-    commentData?: Object;
+    commentsConfig?: CommentsConfig;
     toggleTemplateSidebar?: () => void;
     sheetEditorRef?: RefObject<WorkbookInstance & {
         refreshIndexedDB: () => Promise<void>;
     }>;
-    storeApiKey?: (apiKeyName: string) => void;
-    allowComments?: boolean;
-    onDataBlockApiResponse?: (dataBlockName: string) => void;
+    /** Override where datablock API keys are stored (default: localStorage). */
+    apiKeyStorage?: ApiKeyStorage;
+    /** Optional lifecycle events for analytics / side-effects. */
+    onDataBlockEvent?: (event: DataBlockEvent) => void;
     onDuneChartEmbed?: () => void;
     onSheetCountChange?: (sheetCount: number) => void;
     /** Fires whenever local content-sync status changes. Host apps should gate
@@ -87,9 +90,13 @@ export interface DsheetProps {
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
     } | null>;
-    handleSmartContractQuery?: SmartContractQueryHandler;
+    /** Smart contract config: execution + UI in package; consumer owns persistence via callbacks. */
+    smartContracts?: SmartContractConfig;
     enableLiveQuery?: boolean;
     liveQueryRefreshRate?: number;
+    customPanels?: PanelConfig[];
+    /** Active theme; drives the canvas/grid palette (chrome themes via the <html> class). */
+    theme?: ThemeKey;
 }
 export type BaseError = {
     message: string;

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

@@ -1,7 +1,10 @@
 import { Cell, WorkbookInstance } from '../../sheet-engine/react';
-import { OnboardingHandlerType, DataBlockApiKeyHandlerType } from '../types';
+import { OnboardingHandlerType, DataBlockEvent } from '../types';
 import { LiveQueryData } from '../../sheet-engine/core';
+import { OpenApiKeyModalFn } from './data-block-error-handler';
+import { ApiKeyStorage } from './api-key-storage';
 
+import * as Y from 'yjs';
 export type SmartContractResponse = {
     callSignature: unknown[];
 };
@@ -22,15 +25,18 @@ interface AfterUpdateCellParams {
     oldValue?: Cell;
     newValue: Cell;
     sheetEditorRef: React.RefObject<WorkbookInstance | null>;
+    handleContentPortal?: () => void;
+    dsheetId?: string;
+    ydocRef?: React.MutableRefObject<Y.Doc | null>;
     onboardingComplete: boolean | undefined;
-    setFetchingURLData: (fetching: boolean) => void;
+    setFetchingURLData?: (fetching: boolean) => void;
     onboardingHandler: OnboardingHandlerType | undefined;
-    dataBlockApiKeyHandler: DataBlockApiKeyHandlerType | undefined;
+    apiKeyStorage: ApiKeyStorage;
+    openApiKeyModal: OpenApiKeyModalFn;
+    onDataBlockEvent?: (event: DataBlockEvent) => void;
     handleSmartContractQuery?: SmartContractQueryHandler | undefined;
     handleLiveQueryData?: (subsheetIndex: number, queryData: LiveQueryData) => void;
-    setInputFetchURLDataBlock: React.Dispatch<React.SetStateAction<string>> | undefined;
-    storeApiKey?: (apiKeyName: string) => void;
-    onDataBlockApiResponse?: (dataBlockName: string) => void;
+    setInputFetchURLDataBlock?: React.Dispatch<React.SetStateAction<string>> | undefined;
     setDataBlockCalcFunction?: React.Dispatch<React.SetStateAction<{
         [key: string]: {
             [key: string]: any;
@@ -54,7 +60,7 @@ export declare const shouldExecuteDataBlocks: (params: {
     localUserEditRef?: React.MutableRefObject<boolean>;
     sheetEditorRef: React.RefObject<WorkbookInstance | null>;
 }) => boolean;
-export declare const isDatablockError: (value: any) => boolean;
+export { isDatablockError } from './datablock-error-utils';
 /**
  * Handles logic after a cell is updated, including processing formula results
  *
@@ -62,4 +68,3 @@ export declare const isDatablockError: (value: any) => boolean;
  * @returns Promise that resolves when processing is complete
  */
 export declare const afterUpdateCell: (params: AfterUpdateCellParams) => Promise<void>;
-export {};

package/dist/editor/utils/api-key-storage.d.ts

@@ -0,0 +1,6 @@
+export interface ApiKeyStorage {
+    get: (name: string) => string | null;
+    set: (name: string, key: string) => void;
+    remove?: (name: string) => void;
+}
+export declare const defaultApiKeyStorage: ApiKeyStorage;