@fileverse-dev/dsheet 4.0.4 → 4.0.5-edit-mode-1

package/dist/editor/components/sidebar/use-right-panels.d.ts

@@ -1,4 +1,4 @@
-export type BuiltInPanelType = 'templates' | 'comments' | 'functions' | 'data-verification' | 'conditional-format';
+export type BuiltInPanelType = 'templates' | 'comments' | 'functions' | 'data-verification' | 'conditional-format' | 'named-ranges';
 export type PanelId = BuiltInPanelType | string;
 interface UseRightPanelsReturn {
     activePanel: PanelId | null;

package/dist/editor/components/sidebars/named-ranges.d.ts

@@ -0,0 +1,2 @@
+declare const NamedRanges: () => import("react/jsx-runtime").JSX.Element;
+export { NamedRanges };

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';
@@ -11,7 +11,7 @@ import { CollaborationProps, CollabState, CollabUser } from '../../sync-local/ty
 import { Awareness } from 'y-protocols/awareness';
 import { DSheetContentSnapshot } from '../../persistence';
 
-import * as Y from 'yjs';
+import * as Y from "yjs";
 export interface EditorContextType {
     setIsDataLoaded: React.Dispatch<React.SetStateAction<boolean>>;
     handleOnChangePortalUpdate: () => void;
@@ -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[];
@@ -43,8 +44,9 @@ export interface EditorContextType {
     loading: boolean;
     forceSheetRender: number;
     setForceSheetRender: React.Dispatch<React.SetStateAction<number>>;
-    syncStatus: 'initializing' | 'syncing' | 'synced' | 'error';
+    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;
@@ -94,7 +101,8 @@ interface EditorProviderProps {
     apiKeyStorage?: ApiKeyStorage;
     onDataBlockEvent?: (event: DataBlockEvent) => void;
     smartContracts?: SmartContractConfig;
-    onContentSyncStatusChange?: (status: 'initializing' | 'syncing' | 'synced' | 'error') => void;
+    onContentSyncStatusChange?: (status: "initializing" | "syncing" | "synced" | "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,30 @@
+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 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-celldata-compaction.d.ts

@@ -15,9 +15,8 @@ type UseCelldataCompactionArgs = {
     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.
+ * One-shot background compaction (celldata + borderInfo). Completion is stored
+ * on the anchor sheet's config in Yjs so it syncs across devices.
  */
 export declare function useCelldataCompaction({ dsheetId, ydocRef, sheetEditorRef, currentDataRef, handleOnChangePortalUpdate, syncStatus, isDataLoaded, isReadOnly, remoteUpdateRef, collabSyncing, }: UseCelldataCompactionArgs): void;
 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) => {
+import * as Y from "yjs";
+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

@@ -8,7 +8,7 @@ import { ApiKeyStorage } from './utils/api-key-storage';
 import { ThemeKey } from '../sheet-engine/core/theme';
 import { DSheetContentSnapshot } from '../persistence';
 
-import * as Y from 'yjs';
+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';
@@ -22,6 +22,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: {
@@ -40,7 +49,7 @@ export type OnboardingHandlerType = (params: {
     row: number;
     column: number;
 };
-export type DataBlockEventType = 'success' | 'error' | 'api-key-required' | 'api-key-saved' | 'retry';
+export type DataBlockEventType = "success" | "error" | "api-key-required" | "api-key-saved" | "retry";
 export interface DataBlockEvent {
     type: DataBlockEventType;
     functionName?: string;
@@ -67,6 +76,9 @@ 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;
@@ -80,9 +92,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. */
@@ -92,7 +103,7 @@ export interface DsheetProps {
     /** Fires whenever local content-sync status changes. Host apps should gate
      * 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;
+    onContentSyncStatusChange?: (status: "initializing" | "syncing" | "synced" | "error") => void;
     editorStateRef?: React.MutableRefObject<{
         refreshIndexedDB: () => Promise<void>;
         getContentSnapshot: () => DSheetContentSnapshot;

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

@@ -1,15 +1,19 @@
 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 = {
+/** Celldata + borderInfo compaction; bump when rules change. */
+export declare const SHEET_COMPACTION_REV = 2;
+export declare const SHEET_COMPACTION_CONFIG_KEY = "sheetCompactionRev";
+export type SheetCompactionResult = {
     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;
+export declare function readSheetCompactionRev(config: unknown): number;
+export declare function getAnchorSheet(sheets: Sheet[] | null | undefined): Sheet | null;
+export declare function hasSheetCompactionCompleted(ydoc: Y.Doc, dsheetId: string): boolean;
+export declare function buildCompactionRevChange(ydoc: Y.Doc, dsheetId: string): SheetChangePath | null;
+export declare function markCompactionRevInMemory(sheets: Sheet[] | null | undefined): 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[];
@@ -21,8 +25,5 @@ export declare function compactSheetCelldataArray(celldata: 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;
+/** Scan Y.Doc for committed ghosts. Does not mutate — caller applies `changes`. */
+export declare function planYdocCompaction(ydoc: Y.Doc, dsheetId: string): SheetCompactionResult;

package/dist/editor/utils/defined-names-ydoc.d.ts

@@ -0,0 +1,31 @@
+import { WorkbookInstance } from '../../sheet-engine/react';
+import { DefinedName } from '../../sheet-engine/core/types';
+import { RefObject } from 'react';
+
+import * as Y from 'yjs';
+/** Sibling share key on the same Y.Doc as the sheet array. */
+export declare function getDefinedNamesMapKey(dsheetId: string): string;
+export declare function getDefinedNamesYMap(ydoc: Y.Doc, dsheetId: string): Y.Map<DefinedName>;
+/** Read workbook-level named ranges from Yjs (stable name order). */
+export declare function readDefinedNamesFromYdoc(ydoc: Y.Doc, dsheetId: string): DefinedName[];
+/**
+ * Prefer the sheet `Y.Array` share key when a doc has sibling maps
+ * (e.g. `${dsheetId}:definedNames`).
+ */
+export declare function resolveSheetArrayShareKey(doc: Y.Doc, preferredKey?: string): string | null;
+/**
+ * Diff Context definedNames against the Y.Map and apply set/delete by id.
+ */
+export declare function syncDefinedNamesToYdoc({ ydoc, dsheetId, definedNames, handleContentPortal, }: {
+    ydoc: Y.Doc;
+    dsheetId: string;
+    definedNames: DefinedName[];
+    handleContentPortal?: () => void;
+}): void;
+/** Push current workbook definedNames into Yjs (editor hook target). */
+export declare const definedNamesYdocUpdate: ({ sheetEditorRef, ydocRef, dsheetId, handleContentPortal, }: {
+    sheetEditorRef: RefObject<WorkbookInstance | null>;
+    ydocRef: RefObject<Y.Doc | null>;
+    dsheetId: string;
+    handleContentPortal?: () => void;
+}) => void;

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 {};

package/dist/editor/utils/import-compaction.d.ts

@@ -0,0 +1,25 @@
+import { Sheet } from '../../sheet-engine/react';
+
+/**
+ * XLSX imports (Google Sheets exports especially) materialize every
+ * styled-but-empty cell. Move those into config.cellFormatRanges — the same
+ * sparse representation the editor uses — so they never inflate celldata/Yjs.
+ * Cells with content, merges, hyperlinks, notes or masks are kept verbatim.
+ */
+export declare function compactImportedSheetFormatting(sheet: Sheet): void;
+/**
+ * Imported validations repeat the full option list + per-option color string
+ * on every covered cell (whole-column dropdowns → thousands of copies). Store
+ * each unique entry once in dataVerificationDefs and keep numeric refs in the
+ * per-cell map; expandSheetDataVerification restores objects for the engine.
+ */
+export declare function internImportedDataVerification(sheet: Sheet): void;
+/**
+ * Resolve interned dataVerification refs back to shared entry objects before
+ * the sheet reaches the engine or the XLSX exporter. No-op (and no mutation)
+ * when the map already holds objects, so live workbook sheets pass through.
+ */
+export declare function expandSheetDataVerification<T extends {
+    dataVerification?: unknown;
+    dataVerificationDefs?: unknown;
+}>(sheet: T): T;

package/dist/editor/utils/xlsx-defined-names.d.ts

@@ -0,0 +1,41 @@
+import { DefinedName } from '../../sheet-engine/core/types';
+
+export type ExcelDefinedNameEntry = {
+    name: string;
+    ranges: string[];
+    localSheetId?: number;
+};
+export declare function isExcelSystemDefinedName(name: string): boolean;
+/** Build Excel loc string: `Sheet1!$A$1:$C$2` (or single cell). */
+export declare function encodeDefinedNameExcelRef(sheetName: string, range: DefinedName['range']): string;
+/**
+ * Parse `Sheet1!$A$1:$B$2` / `'My Sheet'!$A$1` into sheet name + 0-based range.
+ */
+export declare function parseExcelDefinedNameRef(ref: string): {
+    sheetName: string;
+    range: {
+        row: [number, number];
+        column: [number, number];
+    };
+} | null;
+/**
+ * Convert Excel defined-name entries into our DefinedName list.
+ * `sheets` must already have stable ids and names (Excel order).
+ */
+export declare function excelEntriesToDefinedNames(entries: ExcelDefinedNameEntry[], sheets: Array<{
+    id?: string;
+    name?: string;
+}>): DefinedName[];
+/** Write defined names onto an ExcelJS workbook (Pass 2). */
+export declare function applyDefinedNamesToExcelWorkbook(excelWorkbook: {
+    definedNames: {
+        add: (loc: string, name: string) => void;
+    };
+}, definedNames: DefinedName[] | undefined, sheets: Array<{
+    id?: string;
+    name?: string;
+}>): void;
+/**
+ * Parse `<definedNames>` from xl/workbook.xml (keeps localSheetId).
+ */
+export declare function parseDefinedNamesFromXlsxBuffer(arrayBuffer: ArrayBuffer): Promise<ExcelDefinedNameEntry[]>;

package/dist/editor/utils/xlsx-import-pipeline.d.ts

@@ -0,0 +1,28 @@
+import { Sheet } from '../../sheet-engine/react';
+import { ExcelDefinedNameEntry } from './xlsx-defined-names';
+
+export declare function generateImportSheetId(): string;
+export type XlsxImportWarning = {
+    code: 'tables-unsupported';
+} | {
+    code: 'filters-unsupported';
+};
+export type XlsxParseSettings = {
+    /** Workbook default column width in px (from the live workbook settings, if any). */
+    workbookDefaultColWidth?: number;
+    /** Workbook default row height in px (from the live workbook settings, if any). */
+    workbookDefaultRowHeight?: number;
+};
+export type XlsxParsedWorkbook = {
+    /** Decorated + compacted sheets, ready for the ydoc write. */
+    sheets: Sheet[];
+    /** Workbook name from luckyexcel info (extension not yet stripped). */
+    workbookName: string;
+    /** UI warnings to replay on the main thread (toasts/onWarning). */
+    warnings: XlsxImportWarning[];
+    /** Sheet ids this pipeline generated — the caller may remap them with a custom generator. */
+    generatedSheetIds: string[];
+    /** Named ranges from xl/workbook.xml — synced to Yjs on the main thread. */
+    definedNameEntries: ExcelDefinedNameEntry[];
+};
+export declare function parseXlsxWorkbook(file: File, settings?: XlsxParseSettings): Promise<XlsxParsedWorkbook>;