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

package/dist/sheet-engine/core/modules/structural-edit-prep.d.ts

@@ -0,0 +1,36 @@
+import { Context } from '../context';
+
+export type StructuralEditOp = {
+    insertRowColOp?: {
+        type: 'row' | 'column';
+        id: string;
+        index: number;
+        count: number;
+        direction: 'lefttop' | 'rightbottom';
+    };
+    deleteRowColOp?: {
+        type: 'row' | 'column';
+        id: string;
+        start: number;
+        end: number;
+    };
+};
+/**
+ * Indexes of the tabs that are not loaded (no dense `data`) and that the edit
+ * rewrites (K6). A tab counts when the rewrite itself would change one of its
+ * formulas, or when one names the edited tab. The first is the test the
+ * rewrite uses, so the two cannot disagree: the sheet-name regex reads
+ * `=C1-A!B5` as a tab called `C1-A` and finds no tab A (PR 466 N1).
+ */
+export declare function unloadedTabsRewrittenBy(ctx: Context, op: StructuralEditOp): number[];
+/**
+ * Load the tabs a structural edit will rewrite, before the edit and outside
+ * the change that history records (PR 466 N1, second review). The rewrite is
+ * then recorded as cell patches on `data`, which undo and redo replay for just
+ * the cells it touched: a peer's edits to the same tab are left alone, and the
+ * tab can be loaded or unloaded again at undo time (`handleUndo` loads it for
+ * `data` patches).
+ *
+ * Returns the same state object when nothing needs loading.
+ */
+export declare function loadTabsReadingSheet(ctx: Context, op: StructuralEditOp): Context;

package/dist/sheet-engine/core/modules/structural-edit-prep.test.d.ts

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

package/dist/sheet-engine/core/paste/paste-dep-graph.test.d.ts

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

package/dist/sheet-engine/core/paste-helpers/calculate-range-cell-size.d.ts

@@ -1,5 +1,18 @@
 import { Context } from '../context';
 
+type Measure2d = {
+    measureText(t: string): {
+        width: number;
+    };
+    font: string;
+};
+/** Drop cached widths, e.g. after web fonts load and change the metrics. */
+export declare function clearSingleLineCache(): void;
+/**
+ * Width of one line of text in `font`, from canvas measureText, cached by
+ * (font, text). No DOM layout is involved.
+ */
+export declare function measureSingleLine(font: string, text: string, ctx2d: Measure2d): number;
 export declare function calculateRangeCellSize(ctx: Context, sheetId: string, startRow: number, endRow: number, startCol: number, endCol: number, maxColumnWidth?: number): {
     rowMax: Record<number, number>;
     colMax: Record<number, number>;
@@ -9,3 +22,4 @@ export declare const updateSheetCellSizes: (ctx: Context, sheetIndex: number, me
     rowMax: Record<number, number>;
     colMax: Record<number, number>;
 }, maxColumnWidth?: number) => void;
+export {};

package/dist/sheet-engine/core/paste-helpers/calculate-range-cell-size.test.d.ts

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

package/dist/sheet-engine/core/settings.d.ts

@@ -29,7 +29,17 @@ export type Hooks = {
     beforeUpdateCell?: (r: number, c: number, value: any) => boolean;
     /** Clears RTC remote-apply lock so local edits can run data-block formulas. */
     onLocalCellEdit?: () => void;
-    afterUpdateCell?: (row: number, column: number, oldValue: any, newValue: any) => void;
+    afterUpdateCell?: (row: number, column: number, oldValue: any, newValue: any, 
+    /** Sheet that held the cell when it was committed (updateCell only). */
+    sheetId?: string, 
+    /**
+     * `skipPersist`: the caller writes this cell to Yjs in its own batch (paste
+     * and fill), after the cell is final. Persisting here too wrote the
+     * pre-format value first, so every formula was written twice.
+     */
+    options?: {
+        skipPersist?: boolean;
+    }) => void;
     afterSelectionChange?: (sheetId: string, selection: Selection) => void;
     beforeRenderRowHeaderCell?: (rowNumber: string, rowIndex: number, top: number, width: number, height: number, ctx: CanvasRenderingContext2D) => boolean;
     afterRenderRowHeaderCell?: (rowNumber: string, rowIndex: number, top: number, width: number, height: number, ctx: CanvasRenderingContext2D) => void;

package/dist/sheet-engine/core/utils/ydoc-celldata-changes.d.ts

@@ -1,6 +1,17 @@
 import { Context } from '../context';
 import { Cell, CellWithRowAndCol } from '../types';
 
+/** Receives changes instead of the updateCellYdoc hook (see createYdocBatch). */
+export type YdocChangeSink = (changes: any[]) => void;
+/**
+ * Collect the Yjs changes of one structural edit and send them in a single
+ * updateCellYdoc call, so the edit is one transaction and one update for peers
+ * (an insert used to send four and a delete five).
+ */
+export declare function createYdocBatch(ctx: Context): {
+    sink: YdocChangeSink;
+    flush: () => void;
+};
 export type CelldataYdocChange = {
     sheetId: string;
     path: string[];
@@ -17,13 +28,29 @@ export declare function cellsEqualForYdocPersist(before: unknown, after: unknown
 export declare function snapshotPersistedCelldataInRange(data: unknown[][] | null | undefined, r1: number, r2: number, c1: number, c2: number, celldata?: CellWithRowAndCol[] | null): Map<string, Cell | string | number | boolean>;
 export declare function appendCelldataDiffChange(changes: CelldataYdocChange[], sheetId: string, r: number, c: number, cell: unknown, beforePersisted?: Map<string, Cell | string | number | boolean>): void;
 export declare function buildCelldataChangesForRange(sheetId: string, data: unknown[][], r1: number, r2: number, c1: number, c2: number, beforePersisted?: Map<string, Cell | string | number | boolean>): CelldataYdocChange[];
-export declare function emitCelldataRangeDiffToYdoc(ctx: Context, sheetId: string, data: unknown[][], r1: number, r2: number, c1: number, c2: number, beforePersisted?: Map<string, Cell | string | number | boolean>): void;
+export declare function emitCelldataRangeDiffToYdoc(ctx: Context, sheetId: string, data: unknown[][], r1: number, r2: number, c1: number, c2: number, beforePersisted?: Map<string, Cell | string | number | boolean>, sink?: YdocChangeSink): void;
+/** Formula text per tab and cell key, taken before a structural edit rewrites it. */
+export type FormulaTextSnapshot = Map<string, Map<string, string>>;
+/**
+ * Snapshot formula text on every hydrated tab. A row/column insert or delete
+ * rewrites formulas on all tabs, but only the edited tab's shifted range is
+ * diffed to Yjs, so the rest has to be found by comparing against this.
+ */
+export declare function snapshotFormulaTexts(ctx: Context): FormulaTextSnapshot;
+/**
+ * Emit cells whose formula text changed since `before`, so peers see the
+ * rewrite. On the edited tab, cells at or past (`editedFromR`, `editedFromC`)
+ * are skipped: the range diff already writes them. `before` keys are
+ * pre-edit coordinates, which equal post-edit ones for every cell outside
+ * that range.
+ */
+export declare function emitRewrittenFormulasToYdoc(ctx: Context, before: FormulaTextSnapshot, editedSheetId: string, editedFromR: number, editedFromC: number, sink?: YdocChangeSink): void;
 /**
  * After delete row/col, emit deletes for persisted keys that now sit past the
  * shrunken grid. Range diffs only visit coordinates still inside `data`, so
  * tail keys would otherwise resurrect on peers/reload.
  */
-export declare function emitCelldataDeletesBeyondGrid(ctx: Context, sheetId: string, beforePersisted: Map<string, Cell | string | number | boolean> | undefined, rowCount: number, colCount: number): void;
+export declare function emitCelldataDeletesBeyondGrid(ctx: Context, sheetId: string, beforePersisted: Map<string, Cell | string | number | boolean> | undefined, rowCount: number, colCount: number, sink?: YdocChangeSink): void;
 export type MergeBounds = {
     minR: number;
     minC: number;

package/dist/sheet-engine/react/components/ContextMenu/FilterMenu.d.ts

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 
-declare const FilterMenu: React.FC;
-export default FilterMenu;
+declare const _default: React.NamedExoticComponent<{}>;
+export default _default;

package/dist/sheet-engine/react/components/ContextMenu/SheetTab.d.ts

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 
-declare const SheetTabContextMenu: React.FC;
-export default SheetTabContextMenu;
+declare const _default: React.NamedExoticComponent<{}>;
+export default _default;

package/dist/sheet-engine/react/components/ContextMenu/index.d.ts

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 
-declare const ContextMenu: React.FC;
-export default ContextMenu;
+declare const _default: React.NamedExoticComponent<{}>;
+export default _default;

package/dist/sheet-engine/react/components/NotationBoxes/shown-comments.d.ts

@@ -0,0 +1,20 @@
+import { Cell } from '../../../core/types';
+
+export type ShownCommentCell = {
+    r: number;
+    c: number;
+    /** Position, size and text of the pinned box (see `shownCommentsKey`). */
+    sig: string;
+};
+/** Cells whose comment popup is pinned open (`ps.isShow`), in row-major order. */
+export declare function collectShownCommentCells(data: (Cell | null)[][]): ShownCommentCell[];
+/**
+ * Identity of a shown-comment set. NotationBoxes applies `showComments` only
+ * when this changes, so an edit that leaves the set alone costs no second
+ * context update. The sheet id is part of the key so that switching to a sheet
+ * with an equal (for example empty) set still replaces the previous sheet's
+ * boxes. Moving or resizing a pinned box, or a peer editing its text, writes
+ * `ps` but not `commentBoxes`, so each shown cell's `ps` position, size and
+ * text are part of the key too.
+ */
+export declare function shownCommentsKey(sheetId: string | undefined, cells: ShownCommentCell[]): string;

package/dist/sheet-engine/react/components/NotationBoxes/shown-comments.test.d.ts

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

package/dist/sheet-engine/react/components/SVGDefines.d.ts

@@ -1,6 +1,6 @@
 import { default as React } from 'react';
 
-declare const SVGDefines: React.FC<{
+declare const _default: React.NamedExoticComponent<{
     currency: string;
 }>;
-export default SVGDefines;
+export default _default;

package/dist/sheet-engine/react/components/SheetOverlay/editing-as-formula.d.ts

@@ -0,0 +1,7 @@
+/**
+ * True while a cell is being edited and either input holds a formula. The
+ * inputs' `innerText` is read only when `editing` is true (a read forces
+ * layout), and the formula bar is read only when the cell input did not
+ * already say yes.
+ */
+export declare function isEditingAsFormula(editing: boolean, readCellInputText: () => string | undefined, readFxInputText: () => string | undefined): boolean;

package/dist/sheet-engine/react/components/SheetOverlay/editing-as-formula.test.d.ts

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

package/dist/sheet-engine/react/components/SheetOverlay/hover-tracker.d.ts

@@ -0,0 +1,44 @@
+import { Context, GlobalCache } from '../../../core';
+
+export type HoverCell = {
+    row: number;
+    col: number;
+} | null;
+type Rect = {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+};
+type HoverTrackerOptions = {
+    /** Position of the cell area; read at most once per animation frame. */
+    getRect: () => Rect | undefined;
+    /** Cell under a page position, or null outside the cell area. */
+    locate: (pageX: number, pageY: number, rect: Rect | undefined) => HoverCell;
+    /** True while a drag, resize or popup needs every mouse move. */
+    isInteracting: () => boolean;
+    requestFrame: (cb: () => void) => void;
+};
+/**
+ * Decides whether a mouse move needs the full `setContext` pass. A move that
+ * stays in the same cell, with nothing being dragged or hovered, changes
+ * nothing, so it is skipped (E1).
+ */
+export declare function createHoverTracker({ getRect, locate, isInteracting, requestFrame, }: HoverTrackerOptions): {
+    shouldProcess(e: {
+        pageX: number;
+        pageY: number;
+    }): boolean;
+    reset(): void;
+};
+/**
+ * True when `handleOverlayMouseMove` or `overShowLinkCard` do something that
+ * depends on more than the hovered cell: a comment box, image, cell or dialog
+ * drag, a popup that must see the pointer leave it, or one of the drag states
+ * after which `handleOverlayMouseMove` runs `mouseRender` on every move
+ * (`luckysheet_scroll_status` is set by every drag start). Outside the grid
+ * every position maps to "no cell", so auto-scroll and the resize guide need
+ * each move.
+ */
+export declare function isHoverInteractionActive(ctx: Context, globalCache: GlobalCache): boolean;
+export {};

package/dist/sheet-engine/react/components/SheetOverlay/hover-tracker.test.d.ts

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

package/dist/sheet-engine/react/components/SheetTab/index.d.ts

@@ -1,4 +1,4 @@
 import { default as React } from 'react';
 
-declare const SheetTab: React.FC;
-export default SheetTab;
+declare const _default: React.NamedExoticComponent<{}>;
+export default _default;

package/dist/sheet-engine/react/components/Toolbar/FunctionList/group-functions.d.ts

@@ -0,0 +1,9 @@
+export type FunctionLocaleItem = {
+    n?: string;
+    t?: number | string;
+};
+/** Groups the locale's function list by category for the function picker. */
+export declare function groupFunctions(functionlist: FunctionLocaleItem[]): {
+    categories: ("Text" | "Date" | "Other" | "Logical" | "All" | "Array" | "Database" | "Engineering" | "Datablock" | "Financial" | "Lookup" | "Math" | "Operator" | "Parser" | "Statistical" | "Info")[];
+    getFunctions: (categoryKey: string) => string[];
+};

package/dist/sheet-engine/react/components/Toolbar/FunctionList/group-functions.test.d.ts

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

package/dist/sheet-engine/react/components/Toolbar/index.d.ts

@@ -7,11 +7,11 @@ export declare const CurrencySelector: ({ cell, defaultTextFormat, toolTipText,
     defaultTextFormat: string;
     toolTipText: string;
 }) => import("react/jsx-runtime").JSX.Element;
-declare const Toolbar: React.FC<{
+declare const _default: React.NamedExoticComponent<{
     setMoreItems: React.Dispatch<React.SetStateAction<React.ReactNode>>;
     moreItemsOpen: boolean;
     onMoreToolbarItemsClose?: () => void;
     moreToolbarItems?: React.ReactNode;
     trailingContent?: React.ReactNode;
 }>;
-export default Toolbar;
+export default _default;

package/dist/sheet-engine/react/components/Workbook/api.d.ts

@@ -31,6 +31,10 @@ export declare function generateAPIs(context: Context, setContext: (recipe: (ctx
     applyRemoteCellValue: (row: number, column: number, value: any, options?: api.CommonOptions & {
         type?: keyof Cell;
     }) => void;
+    /** Remote formula-list change, applied in place (A4). */
+    setSheetCalcChain: (calcChain: Sheet["calcChain"], options?: api.CommonOptions) => void;
+    /** Remote cell batch: one quiet update, off the local undo stack (A5). */
+    applyRemoteCells: (cells: api.RemoteCellChange[], options?: api.CommonOptions, onSkip?: (cell: api.RemoteCellChange, error: unknown) => void) => void;
     setCellError: (row: number, column: number, errorMessage: {
         title: string;
         message: string;

package/dist/sheet-engine/react/components/Workbook/denomination-scan.d.ts

@@ -0,0 +1,16 @@
+import { Cell } from '../../../core/types';
+
+/**
+ * True when any displayed value (`m`) contains BTC, ETH or SOL. Walks the grid
+ * in place and returns at the first hit; no intermediate cell list is built.
+ */
+export declare function hasDenominatedCell(data: (Cell | null)[][]): boolean;
+type BannerDoc = Pick<Document, 'getElementById' | 'getElementsByClassName'>;
+/**
+ * Show or hide the crypto-denomination banner and move the scrollbar and
+ * add-row bar to match. A no-op when the host has not mounted the banner
+ * element; call again later (for example on selection change) to retry.
+ * Returns true when the banner element was found.
+ */
+export declare function applyDenominationBanner(denominated: boolean, doc?: BannerDoc): boolean;
+export {};

package/dist/sheet-engine/react/components/Workbook/denomination-scan.test.d.ts

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

package/dist/sheet-engine/react/components/Workbook/index.d.ts

@@ -33,6 +33,8 @@ declare const Workbook: React.ForwardRefExoticComponent<Settings & AdditionalPro
     applyRemoteCellValue: (row: number, column: number, value: any, options?: api.CommonOptions & {
         type?: keyof import('../../../core').Cell;
     }) => void;
+    setSheetCalcChain: (calcChain: SheetType["calcChain"], options?: api.CommonOptions) => void;
+    applyRemoteCells: (cells: api.RemoteCellChange[], options?: api.CommonOptions, onSkip?: (cell: api.RemoteCellChange, error: unknown) => void) => void;
     setCellError: (row: number, column: number, errorMessage: {
         title: string;
         message: string;

package/dist/sheet-engine/react/components/Workbook/stable-handle.d.ts

@@ -0,0 +1,8 @@
+/**
+ * An object with the keys of `getLatest()` whose identity never changes. Each
+ * function member calls the function of the same name on the latest api, and
+ * each other member reads the latest value, so a host that keeps the handle
+ * across renders always sees current state (E3). The key set is taken from the
+ * first call and is expected to stay the same.
+ */
+export declare function createStableHandle<T extends object>(getLatest: () => T): T;

package/dist/sheet-engine/react/components/Workbook/stable-handle.test.d.ts

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

package/dist/sheet-engine/react/context/index.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { Context, Settings, GlobalCache, PatchOptions } from '../../core';
+import { WorkbookStore } from './workbook-store';
 
 export type RefValues = {
     globalCache: GlobalCache;
@@ -23,4 +24,18 @@ declare const WorkbookContext: React.Context<{
     handleUndo: () => void;
     handleRedo: () => void;
 }>;
+/**
+ * The parts of the workbook that rarely change (setters, settings, refs) plus
+ * the store holding the latest context. Components that must not render on
+ * every update read this instead of `WorkbookContext` (E2).
+ */
+export type WorkbookStable = {
+    store: WorkbookStore<Context>;
+    setContext: (recipe: (ctx: Context) => void, options?: SetContextOptions) => void;
+    settings: Required<Settings>;
+    refs: RefValues;
+    handleUndo: () => void;
+    handleRedo: () => void;
+};
+export declare const WorkbookStableContext: React.Context<WorkbookStable>;
 export default WorkbookContext;

package/dist/sheet-engine/react/context/use-workbook-store.d.ts

@@ -0,0 +1,30 @@
+import { Context } from '../../core';
+
+export declare function useWorkbookSelector<S>(selector: (ctx: Context) => S, isEqual?: (a: S, b: S) => boolean): S;
+/**
+ * Drop-in for `useContext(WorkbookContext)` in components that should not
+ * render on every context update: it returns the same shape, but the
+ * component renders again only when `equal` says the context changed in a way
+ * it cares about (or when its own props or state change). The returned
+ * `context` is always the latest one.
+ */
+export declare function useWorkbookContextWhen(equal: (previous: Context, next: Context) => boolean): {
+    context: Context;
+    setContext: (recipe: (ctx: Context) => void, options?: import('./index').SetContextOptions) => void;
+    settings: Required<import('../../core').Settings>;
+    refs: import('./index').RefValues;
+    handleUndo: () => void;
+    handleRedo: () => void;
+};
+/**
+ * `useContext(WorkbookContext)` for components that must not render when only
+ * the scroll position or the row and column offsets changed (E2).
+ */
+export declare function useWorkbookContextIgnoringScroll(): {
+    context: Context;
+    setContext: (recipe: (ctx: Context) => void, options?: import('./index').SetContextOptions) => void;
+    settings: Required<import('../../core').Settings>;
+    refs: import('./index').RefValues;
+    handleUndo: () => void;
+    handleRedo: () => void;
+};

package/dist/sheet-engine/react/context/workbook-store.d.ts

@@ -0,0 +1,30 @@
+export type WorkbookStore<T> = {
+    getState: () => T;
+    setState: (next: T) => void;
+    subscribe: (listener: () => void) => () => void;
+};
+/** A one-value store; Workbook sets the latest context after every commit (E2). */
+export declare function createWorkbookStore<T>(initial: T): WorkbookStore<T>;
+/**
+ * The snapshot logic behind `useWorkbookSelector`: `getSnapshot` returns the
+ * previously handed-out value while `isEqual` says the newly selected one is
+ * the same, so `useSyncExternalStore` sees no change and the component does
+ * not render. The selector runs once per state.
+ */
+export declare function createSelection<T, S>(store: WorkbookStore<T>, selector: (state: T) => S, isEqual?: (a: S, b: S) => boolean): {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot(): S;
+};
+/** True when two states differ only in the listed keys. */
+export declare function onlyIgnoredKeysChanged(ignored: readonly string[]): (a: object, b: object) => boolean;
+/**
+ * Context keys that change on scroll or when the row and column offsets are
+ * rebuilt after an edit, and that the components converted in E2 do not read:
+ * Toolbar and its popovers, SheetTab, ContextMenu, FilterMenu and
+ * SheetTabContextMenu. Checked with grep in those directories and in the
+ * helpers they call with the context (`updateCellsDecimalFormat`,
+ * `convertCellsToCrypto`, `isHyperlinkCreationBlocked`,
+ * `captureLinkEditorOpenSnapshot`).
+ */
+export declare const SCROLL_ONLY_KEYS: readonly ["scrollLeft", "scrollTop", "visibledatarow", "visibledatacolumn"];
+export declare const contextEqualIgnoringScroll: (a: object, b: object) => boolean;

package/dist/sheet-engine/react/context/workbook-store.test.d.ts

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