@fileverse-dev/dsheet 2.1.2 → 2.1.3-package-cleanup-1

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 { 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,27 +39,14 @@ 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>>;
@@ -67,17 +72,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;
     editorStateRef?: React.MutableRefObject<{
@@ -86,6 +90,9 @@ export interface DsheetProps {
     handleSmartContractQuery?: SmartContractQueryHandler;
     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;

package/dist/editor/utils/api-keys-local-storage.d.ts

@@ -0,0 +1,19 @@
+export declare const INVALID_KEY_MARKER = "_invalid";
+export declare const RATE_LIMITED_KEYS = "RATE_LIMITED_KEYS";
+export declare const DATABLOCK_API_KEYS: string[];
+export declare class ApiKeyStorageHelper {
+    static getApiKey(keyName: string): string;
+    static clearApiKeys(): void;
+    static saveApiKey(keyName: string, key: string): void;
+    static removeApiKey(keyName: string): void;
+    static getAllSupportedApiKeys(): Record<string, string>;
+    static getListOfRateLimitedKeys(): any;
+    static markKeyAsRateLimited(key: string): void;
+}
+export declare const getApiKey: (keyName: string) => string;
+export declare const clearApiKeys: () => void;
+export declare const saveApiKey: (keyName: string, key: string) => void;
+export declare const removeApiKey: (keyName: string) => void;
+export declare const getListOfRateLimitedKeys: () => any;
+export declare const getAllSupportedApiKeysInLs: () => Record<string, string>;
+export declare const markKeyAsRateLimited: (key: string) => void;

package/dist/editor/utils/cell-comment-marker.d.ts

@@ -0,0 +1,29 @@
+type SheetEditorRefLike = {
+    current: {
+        getWorkbookSetContext?: () => unknown;
+    } | null;
+} | null | undefined;
+/**
+ * Clears the comment indicator from a cell.
+ *
+ * - Hides the package-rendered marker DOM node immediately so the user sees
+ *   the change without waiting for a re-render.
+ * - Sets `cell.ps = undefined` in the workbook model so the dsheet package
+ *   stops drawing the marker on subsequent renders / persists.
+ *
+ * Used on top-level comment delete and on top-level comment resolve.
+ */
+export declare const hideCellCommentMarker: (sheetEditorRef: SheetEditorRefLike, row: number, col: number) => void;
+/**
+ * Restores the comment indicator on a cell.
+ *
+ * - Removes the inline `display: none` we set on hide so the package's marker
+ *   DOM node becomes visible again if it still exists.
+ * - Re-creates a minimal `cell.ps` stub in the workbook model so the package
+ *   redraws the marker on next render. Geometry fields are `null` so the
+ *   package recomputes them; the existing `ps` is preserved if already set.
+ *
+ * Used on top-level comment unresolve.
+ */
+export declare const showCellCommentMarker: (sheetEditorRef: SheetEditorRefLike, row: number, col: number, value?: string) => void;
+export {};

package/dist/editor/utils/comment-key-utils.d.ts

@@ -0,0 +1,7 @@
+import { CellPosition } from '../types/comments';
+
+export declare const parseCellKey: (key: string) => CellPosition | null;
+export declare const generateWithoutCellKey: (dataLength: number) => string;
+export declare const isCellComment: (key: string) => boolean;
+export declare const getCellReference: (row: number, col: number) => string;
+export declare const formatCommentDateTime: (dateString: string) => string;

package/dist/editor/utils/data-block-error-handler.d.ts

@@ -0,0 +1,21 @@
+import { Cell, WorkbookInstance } from '../../sheet-engine/react';
+import { DataBlockEvent, ErrorMessageHandlerReturnType } from '../types';
+import { ApiKeyStorage } from './api-key-storage';
+import { SmartContractQueryHandler } from './after-update-cell';
+
+export type OpenApiKeyModalFn = (apiKeyName: string, callbacks: {
+    onSave: (key: string) => void;
+    onClose: () => void;
+}) => void;
+export interface DataBlockErrorHandlerParams {
+    data: ErrorMessageHandlerReturnType;
+    sheetEditorRef: React.RefObject<WorkbookInstance | null>;
+    row: number;
+    column: number;
+    newValue: Cell;
+    apiKeyStorage: ApiKeyStorage;
+    openApiKeyModal: OpenApiKeyModalFn;
+    onDataBlockEvent?: (event: DataBlockEvent) => void;
+    handleSmartContractQuery?: SmartContractQueryHandler;
+}
+export declare const handleDataBlockError: ({ data, sheetEditorRef, row, column, newValue, apiKeyStorage, openApiKeyModal, onDataBlockEvent, handleSmartContractQuery, }: DataBlockErrorHandlerParams) => Promise<void>;

package/dist/editor/utils/datablock-error-utils.d.ts

@@ -0,0 +1 @@
+export declare const isDatablockError: (value: unknown) => boolean;

package/dist/editor/utils/sheet-editor-safe.d.ts

@@ -0,0 +1,26 @@
+import { RefObject } from 'react';
+import { SheetEditorRef } from '../types/comments';
+
+type SheetEditorRefLike = RefObject<SheetEditorRef | null> | null | undefined;
+type WorkbookSheetLike = {
+    id?: string;
+    order?: number;
+    name?: string;
+};
+export declare function isWorkbookReady(ref: SheetEditorRefLike): boolean;
+export declare function getCurrentSheetSafe(ref: SheetEditorRefLike): WorkbookSheetLike | null;
+export declare function getCurrentSheetOrderSafe(ref: SheetEditorRefLike): number;
+export declare function getCurrentSheetIdSafe(ref: SheetEditorRefLike): string;
+export declare function getAllSheetsSafe(ref: SheetEditorRefLike): WorkbookSheetLike[];
+export declare function buildSheetOrderNameMap(ref: SheetEditorRefLike): Map<number, string>;
+/**
+ * Returns a map keyed by BOTH the sheet's immutable id AND its numeric
+ * order-as-string so that both new (UUID) and legacy (order) comment keys
+ * resolve to the correct display name in a single lookup.
+ */
+export declare function buildSheetIdNameMap(ref: SheetEditorRefLike): Map<string, string>;
+export declare function findSheetById(ref: SheetEditorRefLike, id: string): WorkbookSheetLike | null;
+export declare function activateSheetById(ref: SheetEditorRefLike, id: string): boolean;
+export declare function findSheetByOrder(ref: SheetEditorRefLike, order: number): WorkbookSheetLike | null;
+export declare function activateSheetByOrder(ref: SheetEditorRefLike, order: number): boolean;
+export {};