@fileverse-dev/dsheet 2.0.7 → 2.0.8-formulaInteraction-1

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

@@ -7,7 +7,7 @@ export { defaultSettings } from './settings';
 export type { Settings, Hooks } from './settings';
 export { handleCopy, handleGlobalKeyDown, handlePaste, handlePasteByClick, fixPositionOnFrozenCells, handleCellAreaMouseDown, handleCellAreaDoubleClick, handleContextMenu, mouseRender, handleOverlayMouseMove, handleOverlayMouseUp, handleRowHeaderMouseDown, handleColumnHeaderMouseDown, handleColSizeHandleMouseDown, handleColSizeHandleDoubleClick, handleRowSizeHandleMouseDown, handleColFreezeHandleMouseDown, handleRowFreezeHandleMouseDown, } from './events';
 export * from './locale';
-export { getBorderInfoComputeRange, getBorderInfoCompute, normalizedCellAttr, normalizedAttr, getCellValue, setCellValue, getRealCellValue, mergeBorder, cancelNormalSelected, updateCell, getRangetxt, getRangeByTxt, getInlineStringHTML, applyLinkToSelection, getHyperlinksFromInlineSegments, getUniformLinkFromWindowSelectionInEditor, getHyperlinkAtCaretInContentEditable, getStyleByCell, clearSelectedCellFormat, clearRowsCellsFormat, clearColumnsCellsFormat, clipboard, moveToEnd, getRangeRectsByCharacterOffset, update, is_date, valueShowEs, FormulaCache, groupValuesRefresh, execFunctionGroup, setCaretPosition, getrangeseleciton, getFormulaEditorOwner, rangeHightlightselected, handleFormulaInput, israngeseleciton, createRangeHightlight, maybeRecoverDirtyRangeSelection, getFormulaRangeIndexAtCaret, isCaretAtValidFormulaRangeInsertionPoint, isLegacyFormulaRangeMode, markRangeSelectionDirty, setFormulaEditorOwner, functionHTMLGenerate, suppressFormulaRangeSelectionForInitialEdit, rangeSetValue, getFormulaRangeIndexForKeyboardSync, createFormulaRangeSelect, isFormulaReferenceInputMode, seedFormulaFuncSelectedRangeFromLastSelection, initFreeze, isInlineStringCell, getInlineStringNoStyle, rowLocation, rowLocationByIndex, colLocation, colLocationByIndex, insertRowCol, deleteRowCol, hideSelected, showSelected, isShowHidenCR, scrollToHighlightCell, selectTitlesMap, selectTitlesRange, normalizeSelection, syncPrimaryCellActiveFromSelection, setPrimaryCellActive, advancePrimaryCellInLastMultiSelection, snapSheetSelectionFocusToCellPreserveMultiRange, moveHighlightCell, deleteSelectedCellText, selectAll, fixRowStyleOverflowInFreeze, fixColumnStyleOverflowInFreeze, calcSelectionInfo, addSheet, deleteSheet, editSheetName, changeSheet, updateFormat, autoSelectionFormula, handleBold, handleItalic, handleStrikeThrough, handleUnderline, handleHorizontalAlign, handleVerticalAlign, handleTextColor, handleTextBackground, handleBorder, handleMerge, handleSort, handleFreeze, handleTextSize, handleSum, handleLink, captureLinkEditorOpenSnapshot, toolbarItemClickHandler, toolbarItemSelectedFunc, handleScreenShot, insertImage, showImgChooser, drawArrow, setEditingComment, removeEditingComment, newComment, editComment, deleteComment, showComments, showHideComment, showHideAllComments, onCommentBoxMoveStart, removeActiveImage, cancelActiveImgItem, onImageMoveStart, onImageResizeStart, createDropCellRange, sortSelection, searchAll, searchNext, replace, replaceAll, getSearchIndexArr, getSearchIndexArrAsync, getFindRangeOnCurrentSheet, getQuickSearchIndexArr, getQuickSearchHiddenConfig, getCellHyperlinks, getHyperlinkDisplayTextInCell, getInlineLinkPlainRange, getUniformLinkCoveringPlainRange, getUniformLinkAtPlainOffset, removeHyperlinkForLink, updateHyperlinkForLink, syncLinkCardAfterHyperlinkChange, expandCellRectForMerge, shouldQuickSearchUseAsync, runQuickSearchIndexArrAsync, QUICK_SEARCH_ASYNC_ROW_THRESHOLD, parseRangeText, getCellRowColumn, getCellHyperlink, saveHyperlink, removeHyperlink, showLinkCard, goToLink, isLinkValid, createFilterOptions, clearFilter, createFilter, getFilterColumnValues, getFilterColumnColors, orderbydatafiler, saveFilter, onCellsMoveStart, cfSplitRange, updateMoreCell, getRegStr, getDataArr, applyLocation, getOptionValue, getSelectRange, getDropdownList, setDropdownValue, confirmMessage, setConditionRules, handleOverlayTouchStart, handleOverlayTouchEnd, MAX_ZOOM_RATIO, MIN_ZOOM_RATIO, handleKeydownForZoom, jfrefreshgrid, sanitizeDuneUrl, insertDuneChart, onIframeMoveStart, onIframeResizeStart, onIframeMove, onIframeMoveEnd, onIframeResize, onIframeResizeEnd, setCellError, clearCellError, isdatatypemulti, diff, isdatetime, isRealNull, isRealNum, isNumericCellType, iscelldata, getcellrange, cancelFunctionrangeSelected, seletedHighlistByindex, spillSortResult, execfunction, insertUpdateFunctionGroup, remapFormulaReferencesByMap, checkCF, getComputeMap, cancelPaintModel, hideCRCount, getdatabyselection, } from './modules';
+export { getBorderInfoComputeRange, getBorderInfoCompute, normalizedCellAttr, normalizedAttr, getCellValue, setCellValue, getRealCellValue, mergeBorder, cancelNormalSelected, updateCell, getRangetxt, getRangeByTxt, getInlineStringHTML, applyLinkToSelection, getHyperlinksFromInlineSegments, getUniformLinkFromWindowSelectionInEditor, getHyperlinkAtCaretInContentEditable, getStyleByCell, clearSelectedCellFormat, clearRowsCellsFormat, clearColumnsCellsFormat, clipboard, moveToEnd, getRangeRectsByCharacterOffset, update, is_date, valueShowEs, isTypedCurrencyDisplayFormat, isCurrencyLikeNumberFormat, FormulaCache, groupValuesRefresh, execFunctionGroup, setCaretPosition, getrangeseleciton, getFormulaEditorOwner, rangeHightlightselected, handleFormulaInput, israngeseleciton, createRangeHightlight, maybeRecoverDirtyRangeSelection, getFormulaRangeIndexAtCaret, isCaretAtValidFormulaRangeInsertionPoint, isLegacyFormulaRangeMode, markRangeSelectionDirty, setFormulaEditorOwner, functionHTMLGenerate, suppressFormulaRangeSelectionForInitialEdit, rangeSetValue, getFormulaRangeIndexForKeyboardSync, createFormulaRangeSelect, isFormulaReferenceInputMode, seedFormulaFuncSelectedRangeFromLastSelection, initFreeze, isInlineStringCell, getInlineStringNoStyle, rowLocation, rowLocationByIndex, colLocation, colLocationByIndex, insertRowCol, deleteRowCol, hideSelected, showSelected, isShowHidenCR, scrollToHighlightCell, selectTitlesMap, selectTitlesRange, normalizeSelection, syncPrimaryCellActiveFromSelection, selectionIsExactlyOneMergeBlock, setPrimaryCellActive, advancePrimaryCellInLastMultiSelection, snapSheetSelectionFocusToCellPreserveMultiRange, moveHighlightCell, deleteSelectedCellText, selectAll, fixRowStyleOverflowInFreeze, fixColumnStyleOverflowInFreeze, calcSelectionInfo, addSheet, deleteSheet, editSheetName, changeSheet, updateFormat, autoSelectionFormula, handleBold, handleItalic, handleStrikeThrough, handleUnderline, handleHorizontalAlign, handleVerticalAlign, handleTextColor, handleTextBackground, handleBorder, handleMerge, mergeSelectionHasValues, handleSort, handleFreeze, handleTextSize, handleSum, handleLink, captureLinkEditorOpenSnapshot, isHyperlinkCreationBlocked, toolbarItemClickHandler, toolbarItemSelectedFunc, handleScreenShot, insertImage, showImgChooser, drawArrow, setEditingComment, removeEditingComment, newComment, editComment, deleteComment, showComments, showHideComment, showHideAllComments, onCommentBoxMoveStart, removeActiveImage, cancelActiveImgItem, onImageMoveStart, onImageResizeStart, createDropCellRange, sortSelection, searchAll, searchNext, replace, replaceAll, getSearchIndexArr, getSearchIndexArrAsync, getFindRangeOnCurrentSheet, getQuickSearchIndexArr, getQuickSearchHiddenConfig, getCellHyperlinks, getHyperlinkDisplayTextInCell, getInlineLinkPlainRange, getUniformLinkCoveringPlainRange, getUniformLinkAtPlainOffset, removeHyperlinkForLink, updateHyperlinkForLink, syncLinkCardAfterHyperlinkChange, expandCellRectForMerge, shouldQuickSearchUseAsync, runQuickSearchIndexArrAsync, QUICK_SEARCH_ASYNC_ROW_THRESHOLD, parseRangeText, getCellRowColumn, getCellHyperlink, saveHyperlink, removeHyperlink, showLinkCard, goToLink, isLinkValid, createFilterOptions, clearFilter, createFilter, getFilterColumnValues, getFilterColumnColors, orderbydatafiler, saveFilter, onCellsMoveStart, cfSplitRange, updateMoreCell, getRegStr, getDataArr, applyLocation, getOptionValue, getSelectRange, getDropdownList, setDropdownValue, confirmMessage, setConditionRules, handleOverlayTouchStart, handleOverlayTouchEnd, MAX_ZOOM_RATIO, MIN_ZOOM_RATIO, handleKeydownForZoom, jfrefreshgrid, sanitizeDuneUrl, insertDuneChart, onIframeMoveStart, onIframeResizeStart, onIframeMove, onIframeMoveEnd, onIframeResize, onIframeResizeEnd, setCellError, clearCellError, isdatatypemulti, diff, isdatetime, isRealNull, isRealNum, isNumericCellType, iscelldata, getcellrange, cancelFunctionrangeSelected, seletedHighlistByindex, spillSortResult, execfunction, insertUpdateFunctionGroup, remapFormulaReferencesByMap, checkCF, getComputeMap, cancelPaintModel, hideCRCount, getdatabyselection, } from './modules';
 export type { FilterDate, FilterValue, FilterColor } from './modules';
 export { getFreezeState, toggleFreeze, indexToColumnChar, escapeScriptTag, escapeHTMLTag, getSheetIndex, replaceHtml, isAllowEdit, isAllowEditReadOnly, filterPatch, patchToOp, opToPatch, inverseRowColOptions, } from './utils';
 export type { PatchOptions, ChangedSheet } from './utils';

package/dist/sheet-engine/core/modules/format.d.ts

@@ -1,7 +1,66 @@
-import { CellMatrix } from '../types';
+import { Cell, CellMatrix } from '../types';
 
+/** Below this absolute value, never use automatic scientific (Sheets-like). */
+export declare const GS_PLAIN_MAX_ABS = 999999999999997;
+/** Smallest 16-digit positive integer — use plain / text, not E-notation. */
+export declare const GS_SIXTEEN_DIGIT_MIN_ABS = 1000000000000000;
+/** Scientific only in (GS_PLAIN_MAX_ABS, 1e15) — 999…997 itself stays plain. */
+export declare function gsAllowsScientificMagnitude(av: number): boolean;
+/** Integer string (optional `-`, optional `,`) with ≥16 digits — store literally under General/Auto. */
+export declare function isSixteenPlusDigitIntegerString(value: unknown): boolean;
+/**
+ * Display string for a JS number when `toString()` may use `e` notation.
+ * Applies Sheets-like rules: no E below GS_PLAIN_MAX_ABS or at/above 16-digit scale.
+ */
+export declare function formatMForNumericCellAvoidingGsRules(v: number): string;
+/**
+ * Numeric safety gate for formula-computed numbers:
+ * - integer beyond MAX_SAFE_INTEGER => scientific
+ * - significant digits > 15 => scientific
+ */
+export declare function shouldUseScientificForComputedNumber(v: number): boolean;
+export declare function formatScientificForComputedNumber(v: number): string;
+export declare function formatCompactScientific(v: number, fractionDigits?: number): string;
+/**
+ * Sheets-like Auto decimal display:
+ * keep about 10 visible digits total (integer digits + decimal digits), with rounding.
+ * Examples:
+ * - 999999999.478 -> 999999999.5
+ * - 123456.123456 -> 123456.1235
+ */
+export declare function formatGeneralAutoDecimalWithTenDigitRule(v: number): string | null;
 export declare function datenum_local(v: Date, date1904?: number): number;
 export declare function genarate(value: string | number | boolean): any[] | null;
+/** Crypto tickers for typed prefix (e.g. BTC123) — keep aligned with toolbar CRYPTO_OPTIONS. */
+export declare const TYPED_CRYPTO_CURRENCY_PREFIXES: readonly ["BTC", "ETH", "SOL"];
+/**
+ * True when `fa` matches formats produced by typed currency/crypto prefix (or the same shape).
+ * Used so the format dropdown shows "Currency" instead of mislabeling `#,##0` masks as "Number".
+ */
+export declare function isTypedCurrencyDisplayFormat(fa: string | undefined, currencyDetail: unknown): boolean;
+/**
+ * True for currency / accounting / crypto number formats where we should keep `fa` when the user
+ * types plain text, so a later numeric entry still formats like Google Sheets.
+ */
+export declare function isCurrencyLikeNumberFormat(fa: string | undefined, currencyDetail: unknown): boolean;
+/**
+ * If the user types a known currency/crypto prefix immediately followed by a parseable number
+ * (e.g. `$1,234.5`, `€100`, `BTC1.5`), return numeric cell value + matching currency format.
+ * Uses locale `currencyDetail` (fiat symbols); object-shaped locales yield no fiat prefixes.
+ */
+export declare function parseCurrencyPrefixedInput(raw: string, currencyDetail: unknown): [string, {
+    fa: string;
+    t: string;
+}, number] | null;
+export declare function genarateOrCurrencyPrefixed(vupdateStr: string, vupdate: any, currencyDetail: unknown): ReturnType<typeof genarate>;
 export declare function update(fmt: string, v: any): string;
+/** Max decimal places for toolbar +/- on General (Auto) without switching to a numeric `fa`. */
+export declare const MAX_GENERAL_AUTO_DP = 15;
+/**
+ * Recompute `m` for numeric cells with `fa === "General"`.
+ * When `ct.dp` is set (1..MAX), uses fixed decimals like Sheets Auto + decimal buttons.
+ * Otherwise uses the usual `genarate` General display.
+ */
+export declare function refreshGeneralNumericDisplay(cell: Cell): void;
 export declare function is_date(fmt: string, v?: any): boolean;
 export declare function valueShowEs(r: number, c: number, d: CellMatrix): any;

package/dist/sheet-engine/core/modules/formula.d.ts

@@ -30,6 +30,18 @@ export declare class FormulaCache {
     functionlistMap: any;
     execFunctionExist?: any[];
     execFunctionGlobalData: any;
+    /** Formula dependency graph: cell -> referenced cells. Key format: `${sheetId}:${r}:${c}` */
+    depsByCell: Map<string, Set<string>>;
+    /** Reverse dependency graph: referenced cell -> dependent formula cells. */
+    revDepsByCell: Map<string, Set<string>>;
+    /**
+     * Dependency collection state for the currently-parsed formula, set by `execfunction`.
+     * When null, dependency recording is disabled.
+     */
+    activeDepCollection: null | {
+        originKey: string;
+        deps: Set<string>;
+    };
     constructor();
     tryGetCellAsNumber(cell: Cell): string | number | boolean | undefined;
 }
@@ -52,7 +64,7 @@ export declare function createFormulaRangeSelect(ctx: Context, select: {
     rangeIndex: number;
 } & Rect): void;
 export declare function createRangeHightlight(ctx: Context, inputInnerHtmlStr: string, ignoreRangeIndex?: number): void;
-export declare function moveCursorToEnd(editableDiv: HTMLDivElement): void;
+export declare function moveCursorToEnd(editableDiv: HTMLDivElement | null | undefined): void;
 export declare function setCaretPosition(ctx: Context, textDom: HTMLElement, children: number, pos: number, parentTextDom?: HTMLElement): void;
 export declare function getrangeseleciton(): ParentNode | ChildNode | null | undefined;
 export declare function rangeHightlightselected(ctx: Context, $editor: HTMLDivElement): void;

package/dist/sheet-engine/core/modules/index.d.ts

@@ -2,20 +2,20 @@ export { getBorderInfoComputeRange, getBorderInfoCompute } from './border';
 export { normalizedCellAttr, normalizedAttr, getCellValue, setCellValue, getRealCellValue, mergeBorder, cancelNormalSelected, updateCell, getRangetxt, getRangeByTxt, getInlineStringHTML, getStyleByCell, clearSelectedCellFormat, clearRowsCellsFormat, clearColumnsCellsFormat, cancelFunctionrangeSelected, } from './cell';
 export { default as clipboard } from './clipboard';
 export { moveToEnd, getRangeRectsByCharacterOffset } from './cursor';
-export { update, is_date, valueShowEs } from './format';
+export { update, is_date, valueShowEs, isTypedCurrencyDisplayFormat, isCurrencyLikeNumberFormat, } from './format';
 export { FormulaCache, groupValuesRefresh, setCaretPosition, getrangeseleciton, getFormulaEditorOwner, rangeHightlightselected, handleFormulaInput, israngeseleciton, createRangeHightlight, createFormulaRangeSelect, maybeRecoverDirtyRangeSelection, delFunctionGroup, functionHTMLGenerate, onFormulaRangeDragEnd, rangeDrag, rangeSetValue, remapFormulaReferencesByMap, getFormulaRangeIndexAtCaret, isCaretAtValidFormulaRangeInsertionPoint, isLegacyFormulaRangeMode, markRangeSelectionDirty, getFormulaRangeIndexForKeyboardSync, isFormulaReferenceInputMode, seedFormulaFuncSelectedRangeFromLastSelection, functionStrChange, setFormulaEditorOwner, getAllFunctionGroup, suppressFormulaRangeSelectionForInitialEdit, } from './formula';
 export { initFreeze } from './freeze';
 export { isInlineStringCell, getInlineStringNoStyle, applyLinkToSelection, getHyperlinksFromInlineSegments, getUniformLinkFromWindowSelectionInEditor, getHyperlinkAtCaretInContentEditable, } from './inline-string';
 export { rowLocation, rowLocationByIndex, colLocation, colLocationByIndex, } from './location';
 export { insertRowCol, deleteRowCol, hideSelected, showSelected, isShowHidenCR, hideCRCount, } from './rowcol';
-export { scrollToHighlightCell, seletedHighlistByindex, selectTitlesMap, selectTitlesRange, normalizeSelection, syncPrimaryCellActiveFromSelection, setPrimaryCellActive, advancePrimaryCellInLastMultiSelection, snapSheetSelectionFocusToCellPreserveMultiRange, moveHighlightCell, deleteSelectedCellText, selectAll, fixRowStyleOverflowInFreeze, fixColumnStyleOverflowInFreeze, calcSelectionInfo, rangeValueToHtml, } from './selection';
+export { scrollToHighlightCell, seletedHighlistByindex, selectTitlesMap, selectTitlesRange, normalizeSelection, syncPrimaryCellActiveFromSelection, selectionIsExactlyOneMergeBlock, setPrimaryCellActive, advancePrimaryCellInLastMultiSelection, snapSheetSelectionFocusToCellPreserveMultiRange, moveHighlightCell, deleteSelectedCellText, selectAll, fixRowStyleOverflowInFreeze, fixColumnStyleOverflowInFreeze, calcSelectionInfo, rangeValueToHtml, } from './selection';
 export { addSheet, deleteSheet, editSheetName, changeSheet, updateSheet, } from './sheet';
-export { updateFormat, autoSelectionFormula, handleBold, handleItalic, handleStrikeThrough, handleUnderline, handleHorizontalAlign, handleVerticalAlign, handleTextColor, handleTextBackground, handleBorder, handleMerge, handleSort, handleFreeze, handleTextSize, handleSum, handleLink, captureLinkEditorOpenSnapshot, toolbarItemClickHandler, toolbarItemSelectedFunc, updateFormatCell, cancelPaintModel, } from './toolbar';
+export { updateFormat, autoSelectionFormula, handleBold, handleItalic, handleStrikeThrough, handleUnderline, handleHorizontalAlign, handleVerticalAlign, handleTextColor, handleTextBackground, handleBorder, handleMerge, handleSort, handleFreeze, handleTextSize, handleSum, handleLink, captureLinkEditorOpenSnapshot, isHyperlinkCreationBlocked, toolbarItemClickHandler, toolbarItemSelectedFunc, updateFormatCell, cancelPaintModel, } from './toolbar';
 export { handleScreenShot } from './screenshot';
 export { drawArrow, setEditingComment, removeEditingComment, newComment, editComment, deleteComment, showComments, showHideComment, showHideAllComments, onCommentBoxMoveStart, onCommentBoxMove, onCommentBoxMoveEnd, onCommentBoxResize, onCommentBoxResizeEnd, removeOverShowComment, } from './comment';
 export { showImgChooser, insertImage, removeActiveImage, cancelActiveImgItem, onImageMoveStart, onImageResizeStart, onImageMove, onImageMoveEnd, onImageResize, onImageResizeEnd, } from './image';
 export { createDropCellRange, dropCellCache, getTypeItemHide, updateDropCell, } from './dropCell';
-export { mergeCells } from './merge';
+export { mergeCells, mergeSelectionHasValues } from './merge';
 export { sortSelection, spillSortResult } from './sort';
 export { searchAll, searchNext, replace, replaceAll, getSearchIndexArr, getSearchIndexArrAsync, getFindRangeOnCurrentSheet, getQuickSearchIndexArr, getQuickSearchHiddenConfig, expandCellRectForMerge, shouldQuickSearchUseAsync, runQuickSearchIndexArrAsync, QUICK_SEARCH_ASYNC_ROW_THRESHOLD, parseRangeText, } from './searchReplace';
 export type { CheckModes, HyperlinkMap, FindSearchScope, SearchHiddenConfig, SearchNextResult, ReplaceAllResult, } from './searchReplace';

package/dist/sheet-engine/core/modules/merge.d.ts

@@ -1,4 +1,6 @@
 import { Context } from '../context';
 import { Range } from '../types';
 
+/** True if any cell in the current selection has content that merge would consider. */
+export declare function mergeSelectionHasValues(ctx: Context): boolean;
 export declare function mergeCells(ctx: Context, sheetId: string, ranges: Range, type: string): void;

package/dist/sheet-engine/core/modules/selection.d.ts

@@ -1,4 +1,4 @@
-import { Sheet as SheetType, Freezen, Range } from '../types';
+import { Sheet as SheetType, Freezen, Range, Selection } from '../types';
 import { Context } from '../context';
 
 export declare const selectionCache: {
@@ -12,6 +12,11 @@ export declare function seletedHighlistByindex(ctx: Context, r1: number, r2: num
     top: number;
     height: number;
 } | null;
+/**
+ * True when the selection rectangle is exactly one merged block (multi grid cells, one
+ * logical cell). Literal 1×1 is false here — callers use row/column span for that.
+ */
+export declare function selectionIsExactlyOneMergeBlock(ctx: Context, selection: Selection): boolean;
 /**
  * Updates `ctx.primaryCellActive` from a selection list (multi-cell → active focus cell;
  * else null). Pass `selection` explicitly when normalizing a **new** array that is not
@@ -38,7 +43,7 @@ export declare function setPrimaryCellActive(ctx: Context, r: number, c: number)
  * that range so Enter-primary navigation + typing do not collapse the yellow box.
  */
 export declare function snapSheetSelectionFocusToCellPreserveMultiRange(ctx: Context, r: number, c: number): void;
-export declare function normalizeSelection(ctx: Context, selection: SheetType["luckysheet_select_save"]): import('..').Selection[] | undefined;
+export declare function normalizeSelection(ctx: Context, selection: SheetType["luckysheet_select_save"]): Selection[] | undefined;
 export declare function selectTitlesMap(rangeMap: Record<string, number>, range1: number, range2: number): Record<string, number>;
 export declare function selectTitlesRange(map: Record<string, number>): number[][];
 export declare function pasteHandlerOfPaintModel(ctx: Context, copyRange: Context["luckysheet_copy_save"]): void;

package/dist/sheet-engine/core/modules/toolbar.d.ts

@@ -28,9 +28,10 @@ export declare function handleFreeze(ctx: Context, type: string): void;
 export declare function handleTextSize(ctx: Context, cellInput: HTMLDivElement, size: number, canvas?: CanvasRenderingContext2D): void;
 export declare function handleSum(ctx: Context, cellInput: HTMLDivElement, fxInput: HTMLDivElement | null | undefined, cache?: GlobalCache): void;
 /**
- * Records caret and selection offsets for the active cell editor into `cache`.
- * Call on toolbar link mousedown (before focus leaves the editor) and from selectionchange while editing.
+ * Hyperlink insert is not supported for formula cells or when the user is entering a formula
+ * (cell / formula bar content starts with `=`).
  */
+export declare function isHyperlinkCreationBlocked(ctx: Context, cellInput: HTMLDivElement | null | undefined): boolean;
 export declare function captureLinkEditorOpenSnapshot(ctx: Context, cellInput: HTMLDivElement | null | undefined, cache: GlobalCache | undefined): void;
 export declare function handleLink(ctx: Context, cellInput: HTMLDivElement | null | undefined, cache?: GlobalCache): void;
 export declare function toolbarItemClickHandler(name: string): ToolbarItemClickHandler;

package/dist/sheet-engine/core/modules/validation.d.ts

@@ -9,6 +9,7 @@ export declare const error: {
     nm: string;
     nl: string;
     sp: string;
+    circ: string;
 };
 export declare const errorMessagesFromValue: Record<string, string>;
 export declare function detectErrorFromValue(input: string): string;

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

@@ -43,11 +43,13 @@ export type Cell = {
         cs?: number;
     };
     f?: string;
+    /** `dp`: fixed decimal places for display when `fa` is General (Auto); does not change `fa`/`t`. */
     ct?: {
         fa?: string;
         t?: string;
         tb?: string;
         s?: any;
+        dp?: number;
     };
     qp?: number;
     spl?: any;
@@ -426,6 +428,8 @@ export type GlobalCache = {
         } | null;
         selectedPlain: string;
     };
+    /** Injected by React: show modal when link insert is blocked (formula / = in editor). */
+    onHyperlinkInsertBlocked?: () => void;
     dragCellStartPos?: {
         x: number;
         y: number;

package/dist/sheet-engine/formula-parser/error.d.ts

@@ -20,3 +20,4 @@ export const ERROR_NULL: "NULL";
 export const ERROR_NUM: "NUM";
 export const ERROR_REF: "REF";
 export const ERROR_VALUE: "VALUE";
+export const CIRCULAR_REF_ERROR: "CIRC";

package/dist/sheet-engine/formula-parser/index.d.ts

@@ -1,6 +1,6 @@
 import { default as SUPPORTED_FORMULAS } from './supported-formulas';
-import { ERROR, ERROR_DIV_ZERO, ERROR_NAME, ERROR_NOT_AVAILABLE, ERROR_NULL, ERROR_NUM, ERROR_REF, ERROR_VALUE, default as error } from './error';
+import { ERROR, ERROR_DIV_ZERO, ERROR_NAME, ERROR_NOT_AVAILABLE, ERROR_NULL, ERROR_NUM, ERROR_REF, ERROR_VALUE, CIRCULAR_REF_ERROR, default as error } from './error';
 import { default as Parser } from './parser';
 import { extractLabel, toLabel, columnIndexToLabel, columnLabelToIndex, rowIndexToLabel, rowLabelToIndex } from './helper/cell';
 
-export { SUPPORTED_FORMULAS, ERROR, ERROR_DIV_ZERO, ERROR_NAME, ERROR_NOT_AVAILABLE, ERROR_NULL, ERROR_NUM, ERROR_REF, ERROR_VALUE, Parser, error, extractLabel, toLabel, columnIndexToLabel, columnLabelToIndex, rowIndexToLabel, rowLabelToIndex };
+export { SUPPORTED_FORMULAS, ERROR, ERROR_DIV_ZERO, ERROR_NAME, ERROR_NOT_AVAILABLE, ERROR_NULL, ERROR_NUM, ERROR_REF, ERROR_VALUE, CIRCULAR_REF_ERROR, Parser, error, extractLabel, toLabel, columnIndexToLabel, columnLabelToIndex, rowIndexToLabel, rowLabelToIndex };

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

@@ -21,8 +21,16 @@ export declare function buildFormulaSuggestionText(editableDiv: HTMLDivElement,
     caretOffset: number;
 };
 export declare function isLetterNumberPattern(str: string): boolean;
+export declare function isStrictFormulaEditorText(editor: HTMLDivElement | null): boolean;
 /** Same rule as InputBox/Fx onChange: show function list while typing a name after `=`. */
 export declare function shouldShowFormulaFunctionList(editor: HTMLDivElement | null): boolean;
+/**
+ * True when the formula looks complete at the caret:
+ * - strict first character '='
+ * - caret at end of editor text
+ * - parentheses are balanced (no negative depth; final depth 0)
+ */
+export declare function isFormulaCompleteAtCaret(editor: HTMLDivElement | null): boolean;
 /**
  * When the caret sits on a function name span or its opening-paren span, return
  * that function's name (uppercase). Used so nested formulas like `SUM(MIN(`