@sheetxl/react 0.7.27 → 0.7.28-beta.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/browser/cjs/Bo9Kx3L_XQkGPBJ5.cjs +1 -0
- package/browser/cjs/Pl04-kDEQSO8_qFU.cjs +156 -0
- package/browser/cjs/index.cjs +24 -24
- package/browser/esm/D_suN0U6XvrHxTak.mjs +6286 -0
- package/browser/esm/index.mjs +19258 -4911
- package/licenses/dependencies.txt +42 -214
- package/node/esm/CH084kteEgVy0a8H.mjs +9 -0
- package/node/esm/index.mjs +17035 -3691
- package/package.json +10 -11
- package/resources/contents.json +60 -0
- package/resources/locales/contents.json +114 -0
- package/resources/locales/de/clipboard.cmd.json +36 -0
- package/resources/locales/de/editor.cmd.json +128 -0
- package/resources/locales/de/movable.cmd.json +123 -0
- package/resources/locales/de/selection.cmd.json +373 -0
- package/resources/locales/de/sheet.cmd.json +1563 -0
- package/resources/locales/de/table.cmd.json +83 -0
- package/resources/locales/de/ui.msg.json +166 -0
- package/resources/locales/de/workbook.cmd.json +282 -0
- package/resources/locales/en/clipboard.cmd.json +36 -0
- package/resources/locales/en/editor.cmd.json +128 -0
- package/resources/locales/en/movable.cmd.json +123 -0
- package/resources/locales/en/selection.cmd.json +373 -0
- package/resources/locales/en/sheet.cmd.json +1563 -0
- package/resources/locales/en/table.cmd.json +83 -0
- package/resources/locales/en/ui.msg.json +166 -0
- package/resources/locales/en/workbook.cmd.json +282 -0
- package/types/index.d.ts +2 -1767
- package/types/src/border/StaticBorderRenderer.d.ts +32 -0
- package/types/src/border/StyledStrokePath.d.ts +14 -0
- package/types/src/border/index.d.ts +4 -0
- package/types/src/border/useBorders.d.ts +87 -0
- package/types/src/cell/ColumnButton.d.ts +45 -0
- package/types/src/cell/CornerTriangle.d.ts +27 -0
- package/types/src/cell/FormulaCellRenderer.d.ts +34 -0
- package/types/src/cell/SheetCellRenderer.d.ts +52 -0
- package/types/src/cell/SheetHeaderRenderer.d.ts +37 -0
- package/types/src/cell/index.d.ts +7 -0
- package/types/src/cell/useFormulaViewAnchor.d.ts +42 -0
- package/types/src/chart/ChartEditor.d.ts +17 -0
- package/types/src/chart/PresetChartTypeDescriptors.d.ts +35 -0
- package/types/src/chart/index.d.ts +3 -0
- package/types/src/chart/templates/area-stacked-percent-template.json.d.ts +10 -0
- package/types/src/chart/templates/area-stacked-template.json.d.ts +10 -0
- package/types/src/chart/templates/area-template.json.d.ts +9 -0
- package/types/src/chart/templates/bar-stacked-percent-template.json.d.ts +10 -0
- package/types/src/chart/templates/bar-stacked-template.json.d.ts +10 -0
- package/types/src/chart/templates/bar-template.json.d.ts +9 -0
- package/types/src/chart/templates/column-stacked-percent-template.json.d.ts +10 -0
- package/types/src/chart/templates/column-stacked-template.json.d.ts +10 -0
- package/types/src/chart/templates/column-template.json.d.ts +9 -0
- package/types/src/chart/templates/line-markers-template.json.d.ts +10 -0
- package/types/src/chart/templates/line-stacked-markers-template.json.d.ts +11 -0
- package/types/src/chart/templates/line-stacked-percent-markers-template.json.d.ts +11 -0
- package/types/src/chart/templates/line-stacked-percent-template.json.d.ts +10 -0
- package/types/src/chart/templates/line-stacked-template.json.d.ts +10 -0
- package/types/src/chart/templates/line-template.json.d.ts +9 -0
- package/types/src/chart/templates/pie-doughnut-template.json.d.ts +10 -0
- package/types/src/chart/templates/pie-template.json.d.ts +9 -0
- package/types/src/chart/templates/scatter-lines-markers-smooth-template.json.d.ts +10 -0
- package/types/src/chart/templates/scatter-lines-markers-template.json.d.ts +10 -0
- package/types/src/chart/templates/scatter-lines-smooth-template.json.d.ts +10 -0
- package/types/src/chart/templates/scatter-lines-template.json.d.ts +10 -0
- package/types/src/chart/templates/scatter-markers-template.json.d.ts +10 -0
- package/types/src/clipboard/ClipboardCommands.d.ts +68 -0
- package/types/src/clipboard/SheetClipboardLayer.d.ts +22 -0
- package/types/src/clipboard/index.d.ts +3 -0
- package/types/src/commands/Catalog.d.ts +8 -0
- package/types/src/commands/CommandRootProvider.d.ts +36 -0
- package/types/src/commands/InputClipboardCommands.d.ts +41 -0
- package/types/src/commands/InputClipboardInjector.d.ts +16 -0
- package/types/src/commands/MainFocusContext.d.ts +13 -0
- package/types/src/commands/PaneScopeProvider.d.ts +40 -0
- package/types/src/commands/createTransactionalMiddleware.d.ts +49 -0
- package/types/src/commands/index.d.ts +7 -0
- package/types/src/context/SheetContext.d.ts +18 -0
- package/types/src/context/WorkbookContext.d.ts +20 -0
- package/types/src/context/index.d.ts +3 -0
- package/types/src/editableLabel/EditableLabel.d.ts +28 -0
- package/types/src/editableLabel/index.d.ts +2 -0
- package/types/src/editor/EditorCommands.d.ts +98 -0
- package/types/src/editor/FunctionPreviewPanel.d.ts +166 -0
- package/types/src/editor/NamedHintPanel.d.ts +38 -0
- package/types/src/editor/NamedItemsPanel.d.ts +59 -0
- package/types/src/editor/SheetCellEditorLayer.d.ts +40 -0
- package/types/src/editor/SheetCellInput.d.ts +99 -0
- package/types/src/editor/SheetEditable.d.ts +53 -0
- package/types/src/editor/SheetReferenceHeaderLayer.d.ts +46 -0
- package/types/src/editor/SheetReferenceLayer.d.ts +55 -0
- package/types/src/editor/formulaCaret.d.ts +84 -0
- package/types/src/editor/formulaEval.d.ts +202 -0
- package/types/src/editor/formulaPresentation.d.ts +136 -0
- package/types/src/editor/formulaText.d.ts +80 -0
- package/types/src/editor/functionArgs.d.ts +111 -0
- package/types/src/editor/functionHint.d.ts +37 -0
- package/types/src/editor/index.d.ts +18 -0
- package/types/src/editor/referencePointNav.d.ts +39 -0
- package/types/src/editor/useFormulaHints.d.ts +126 -0
- package/types/src/editor/useFormulaInput.d.ts +326 -0
- package/types/src/editor/useProtectedEditNotice.d.ts +14 -0
- package/types/src/editor/useReferenceMode.d.ts +177 -0
- package/types/src/form/FormulaInput.d.ts +86 -0
- package/types/src/form/FormulaInputParts.d.ts +94 -0
- package/types/src/form/index.d.ts +5 -0
- package/types/src/form/useEditCommit.d.ts +174 -0
- package/types/src/form/useInputField.d.ts +86 -0
- package/types/src/frame/CommandContext.d.ts +179 -0
- package/types/src/frame/IFrame.d.ts +17 -0
- package/types/src/frame/index.d.ts +3 -0
- package/types/src/icons/LogoNoPaddingIcon.d.ts +3 -0
- package/types/src/icons/LogoTextNoPaddingIcon.d.ts +4 -0
- package/types/src/icons/WaterMark.d.ts +12 -0
- package/types/src/icons/chart/ChartAreaIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartAreaStackedIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartAreaStackedPercentIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartBarIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartBarStackedIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartBarStackedPercentIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartBubble3DIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartBubbleIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartColumnIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartColumnStackedIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartColumnStackedPercentIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartLineIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartLineMarkersIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartLineStackedIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartLineStackedMarkersIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartLineStackedPercentIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartLineStackedPercentMarkersIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartPieDoughnutIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartPieIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartScatterLinesIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartScatterLinesMarkersIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartScatterLinesMarkersSmoothIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartScatterLinesSmoothIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartScatterMarkersIcon.d.ts +5 -0
- package/types/src/icons/chart/ChartWaterfallIcon.d.ts +5 -0
- package/types/src/icons/chart/ThemedChartIcon.d.ts +20 -0
- package/types/src/icons/chart/index.d.ts +50 -0
- package/types/src/icons/index.d.ts +4 -0
- package/types/src/index.d.ts +27 -0
- package/types/src/io/WorkbookIO.d.ts +50 -0
- package/types/src/io/index.d.ts +2 -0
- package/types/src/layer/BorderLayer.d.ts +14 -0
- package/types/src/layer/CellErrorLayer.d.ts +49 -0
- package/types/src/layer/CellFillLayer.d.ts +15 -0
- package/types/src/layer/ConditionalBarLayer.d.ts +41 -0
- package/types/src/layer/ConditionalIcons.d.ts +34 -0
- package/types/src/layer/ConditionalIconsLayer.d.ts +31 -0
- package/types/src/layer/ContextMenuLayer.d.ts +27 -0
- package/types/src/layer/HeaderResizerLayer.d.ts +28 -0
- package/types/src/layer/HeaderSelectionLayer.d.ts +89 -0
- package/types/src/layer/ResizeIndicator.d.ts +19 -0
- package/types/src/layer/SheetBackgroundLayer.d.ts +22 -0
- package/types/src/layer/SheetCellLayer.d.ts +49 -0
- package/types/src/layer/SheetColumnButtonLayer.d.ts +23 -0
- package/types/src/layer/SheetGridLineLayer.d.ts +22 -0
- package/types/src/layer/SheetHeaderCellLayer.d.ts +30 -0
- package/types/src/layer/SheetMovableLayer.d.ts +26 -0
- package/types/src/layer/SheetTableCommandLayer.d.ts +16 -0
- package/types/src/layer/SpillLayer.d.ts +22 -0
- package/types/src/layer/TableLayer.d.ts +22 -0
- package/types/src/layer/ValidationIndicatorLayer.d.ts +41 -0
- package/types/src/layer/index.d.ts +25 -0
- package/types/src/layer/resizeIndicatorState.d.ts +26 -0
- package/types/src/layer/useSheetFeatureRegions.d.ts +21 -0
- package/types/src/layer/useSheetVisibleCells.d.ts +60 -0
- package/types/src/layer/useSheetVisibleDecorations.d.ts +42 -0
- package/types/src/layer/useTableHeaderCells.d.ts +22 -0
- package/types/src/layer/useVisibleTables.d.ts +27 -0
- package/types/src/listener/index.d.ts +3 -0
- package/types/src/listener/useModelListener.d.ts +67 -0
- package/types/src/listener/useRangeListener.d.ts +15 -0
- package/types/src/movable/EmptyFrame.d.ts +16 -0
- package/types/src/movable/IMovableArea.d.ts +34 -0
- package/types/src/movable/MovableCommands.d.ts +22 -0
- package/types/src/movable/MovableFrame.d.ts +48 -0
- package/types/src/movable/MovableLayer.d.ts +77 -0
- package/types/src/movable/MoveableBundle.d.ts +4 -0
- package/types/src/movable/index.d.ts +4 -0
- package/types/src/picture/IPictureEditor.d.ts +39 -0
- package/types/src/picture/PictureEditor.d.ts +4 -0
- package/types/src/picture/index.d.ts +3 -0
- package/types/src/selection/SelectionCommands.d.ts +23 -0
- package/types/src/selection/SheetSelection.d.ts +53 -0
- package/types/src/selection/SheetSelectionLayer.d.ts +30 -0
- package/types/src/selection/index.d.ts +4 -0
- package/types/src/shape/ShapeEditor.d.ts +16 -0
- package/types/src/shape/index.d.ts +2 -0
- package/types/src/sheet/ConditionalFormatPresets.d.ts +56 -0
- package/types/src/sheet/ISheetElement.d.ts +233 -0
- package/types/src/sheet/ISheetHeaderElement.d.ts +138 -0
- package/types/src/sheet/NotImplemented.d.ts +3 -0
- package/types/src/sheet/SheetCommandProvider.d.ts +57 -0
- package/types/src/sheet/SheetCommands.d.ts +75 -0
- package/types/src/sheet/SheetElement.d.ts +15 -0
- package/types/src/sheet/SheetHeaderElement.d.ts +4 -0
- package/types/src/sheet/SheetScrollbar.d.ts +28 -0
- package/types/src/sheet/TopLeftCorner.d.ts +17 -0
- package/types/src/sheet/index.d.ts +7 -0
- package/types/src/slicer/SlicerEditor.d.ts +16 -0
- package/types/src/slicer/index.d.ts +2 -0
- package/types/src/tabStrip/SheetTab.d.ts +41 -0
- package/types/src/tabStrip/Sortable.d.ts +66 -0
- package/types/src/tabStrip/Tab.d.ts +19 -0
- package/types/src/tabStrip/TabStrip.d.ts +41 -0
- package/types/src/tabStrip/TabStripItem.d.ts +36 -0
- package/types/src/tabStrip/TabStripRow.d.ts +9 -0
- package/types/src/tabStrip/index.d.ts +7 -0
- package/types/src/table/TableCommands.d.ts +16 -0
- package/types/src/taskPane/ITaskPane.d.ts +72 -0
- package/types/src/taskPane/TaskPaneArea.d.ts +144 -0
- package/types/src/taskPane/TaskPaneFrame.d.ts +48 -0
- package/types/src/taskPane/TaskPaneRegistry.d.ts +108 -0
- package/types/src/taskPane/TaskPaneStrip.d.ts +33 -0
- package/types/src/taskPane/TaskPaneTitle.d.ts +24 -0
- package/types/src/taskPane/index.d.ts +7 -0
- package/types/src/taskPane/useTaskPane.d.ts +29 -0
- package/types/src/theme/DocThemesContext.d.ts +3 -0
- package/types/src/theme/DocThemesProvider.d.ts +15 -0
- package/types/src/theme/ThemeState.d.ts +19 -0
- package/types/src/theme/buildDocThemeCSS.d.ts +16 -0
- package/types/src/theme/buildOOXMLThemeCSS.d.ts +13 -0
- package/types/src/theme/createCSSSystemLookup.d.ts +51 -0
- package/types/src/theme/index.d.ts +11 -0
- package/types/src/theme/useAppColorScheme.d.ts +15 -0
- package/types/src/theme/useDocThemes.d.ts +3 -0
- package/types/src/theme/useGridColorScheme.d.ts +20 -0
- package/types/src/theme/useSystemColors.d.ts +44 -0
- package/types/src/undo/UndoCommands.d.ts +28 -0
- package/types/src/undo/UndoManagerContext.d.ts +14 -0
- package/types/src/undo/index.d.ts +3 -0
- package/types/src/workbook/DefaultRenderers.d.ts +14 -0
- package/types/src/workbook/GlobalWorkbookElement.d.ts +10 -0
- package/types/src/workbook/IWorkbookElement.d.ts +178 -0
- package/types/src/workbook/WindowChrome.d.ts +61 -0
- package/types/src/workbook/WorkbookCommandContributor.d.ts +24 -0
- package/types/src/workbook/WorkbookCommands.d.ts +97 -0
- package/types/src/workbook/WorkbookElement.d.ts +9 -0
- package/types/src/workbook/WorkbookStrip.d.ts +73 -0
- package/types/src/workbook/index.d.ts +17 -0
- package/types/src/workbook/resolveWorkbookInput.d.ts +27 -0
- package/types/src/workbook/useResolvedWorkbook.d.ts +31 -0
- package/types/src/workbook/useWindowChrome.d.ts +24 -0
- package/types/src/workbook/useWorkbookApp.d.ts +47 -0
- package/types/src/workbook/useWorkbookEncrypted.d.ts +15 -0
- package/types/src/workbook/useWorkbookFormat.d.ts +18 -0
- package/types/src/workbook/useWorkbookName.d.ts +13 -0
- package/types/src/workbook/useWorkbookSaveState.d.ts +29 -0
- package/browser/cjs/DNki9dGbSn_gUfd3.cjs +0 -7
- package/browser/cjs/Da611GSWMp5ncOGO.cjs +0 -16
- package/browser/cjs/F8ZECny0CwW2OV5X.cjs +0 -161
- package/browser/esm/BYGSBjns_83FWXAx.mjs +0 -3905
- package/browser/esm/CmObbQiLq9AAM7-q.mjs +0 -394
- package/browser/esm/Daa2g2QALCIHFgqP.mjs +0 -1377
- package/node/assets/style.css +0 -1
- package/node/esm/Bu9xI_rgkuupQ2AO.mjs +0 -11
|
@@ -0,0 +1,126 @@
|
|
|
1
|
+
import { default as React } from 'react';
|
|
2
|
+
import { ICalculation, INamedCollection } from '@sheetxl/sdk';
|
|
3
|
+
import { NamedItem } from './NamedItemsPanel';
|
|
4
|
+
/**
|
|
5
|
+
* The autocomplete rows for a typed `prefix` — the whole list, from all three sources, in the order
|
|
6
|
+
* they are shown.
|
|
7
|
+
*
|
|
8
|
+
* Excel's list is ONE alphabetical run rather than a run per kind: a user typing `SU` is reaching for
|
|
9
|
+
* a name, not for a category, so functions, defined names and tables interleave and the leading glyph
|
|
10
|
+
* carries the distinction.
|
|
11
|
+
*
|
|
12
|
+
* Sources and their asymmetries:
|
|
13
|
+
* - **Functions** — matched on the LOCALIZED name a user of the active language types and sees
|
|
14
|
+
* (`SUMME`) *or* its canonical English (English is always accepted; see I18N-DESIGN.md Plane 3). The
|
|
15
|
+
* localized name is what gets inserted, and that is correct: the editing compiler binds it back to
|
|
16
|
+
* canonical and storage stays canonical. Capped at {@link MAX_FUNCTION_RESULTS} *before* the merge.
|
|
17
|
+
* - **Names and tables** — one collection (a table is an `INamed` whose `getType()` is `'table'`).
|
|
18
|
+
* Pass the SHEET's (`ISheet.getNames()`), which already holds exactly what a formula written there
|
|
19
|
+
* can refer to, shadowing resolved — the workbook's would offer other sheets' private names.
|
|
20
|
+
* Deliberately NOT localized: a defined name is the user's own text, spelled the same in every
|
|
21
|
+
* language.
|
|
22
|
+
*
|
|
23
|
+
* A name colliding with a FUNCTION name is pathological but possible; the function wins, because that
|
|
24
|
+
* is what the compiler binds a bare identifier to — completing to the name would insert text that
|
|
25
|
+
* reads back as the function. Matching is case-insensitive throughout, as names are.
|
|
26
|
+
*
|
|
27
|
+
* Pure and total: either source failing costs only its own rows, never the list.
|
|
28
|
+
*/
|
|
29
|
+
export declare const buildMatches: (calc: ICalculation, prefix: string, names: INamedCollection | null) => NamedItem[];
|
|
30
|
+
/**
|
|
31
|
+
* Start offset (after the leading prefix — `base`) of the INNERMOST function call that is still OPEN at
|
|
32
|
+
* `caret` — the offset of that call's *name token* — or `null` when the caret isn't inside an open call.
|
|
33
|
+
* "Open" = the caret sits between the call's `(` and its matching `)` (which may not exist yet while the
|
|
34
|
+
* formula is being typed). This both anchors the hint popup to the function name (so it holds still as the
|
|
35
|
+
* caret moves through the arguments) and gates the preview (shown ⇔ non-null).
|
|
36
|
+
*
|
|
37
|
+
* A stack walk over the tokens BEFORE the caret: a `function` token arms a name-start that the next `(`
|
|
38
|
+
* pushes; `)` pops; a grouping `(` (no preceding `function`) pushes `-1` so a bare group `(A1+A2)` doesn't
|
|
39
|
+
* count. The innermost `function` entry still on the stack at the caret is the answer.
|
|
40
|
+
*
|
|
41
|
+
* Deliberately paren-balance, NOT the `evalIndex` climb the hover-eval tip uses. The tip is token-specific
|
|
42
|
+
* (hover a token → eval its subtree); the caret preview instead asks "which call am I INSIDE?", and that
|
|
43
|
+
* can't be read from `evalIndex`/`context`: `=sum(3)+` and `=sum(sum(3)+` end in the same `SUM#-1`,
|
|
44
|
+
* `evalIndex:undefined` trailing token yet want opposite results (none vs. the still-open outer). Only the
|
|
45
|
+
* paren balance separates a closed call from an open one.
|
|
46
|
+
*/
|
|
47
|
+
export declare const enclosingOpenFunctionStart: (tokens: readonly ICalculation.FormulaToken[], caret: number, base: number) => number | null;
|
|
48
|
+
export interface UseFormulaHintsOptions {
|
|
49
|
+
/** The live editor/field text. */
|
|
50
|
+
text: string;
|
|
51
|
+
/**
|
|
52
|
+
* The LIVE parse's tokens (a getter — some hosts declare their parse after this hook), or `null` —
|
|
53
|
+
* no hints derive without tokens. Offsets are text offsets past the leading prefix (the hook
|
|
54
|
+
* derives the prefix length from {@link text}).
|
|
55
|
+
*/
|
|
56
|
+
getTokens(): readonly ICalculation.FormulaToken[] | null;
|
|
57
|
+
/** Whether the host is actively editing (focused / engaged) — hints derive only while `true`. */
|
|
58
|
+
active: boolean;
|
|
59
|
+
/** The LIVE caret position (read at derivation time, not render time). */
|
|
60
|
+
getCaret(): number;
|
|
61
|
+
/** Resolution context — the calculation whose function registry backs the list + signatures. */
|
|
62
|
+
getCalculation(): ICalculation | null;
|
|
63
|
+
/**
|
|
64
|
+
* The named items — defined names AND tables — offered in the autocomplete list beside the
|
|
65
|
+
* functions, as Excel does. Omit (or return `null`) for a host with no workbook behind it; the list
|
|
66
|
+
* then holds functions only, exactly as before.
|
|
67
|
+
*
|
|
68
|
+
* @remarks
|
|
69
|
+
* Must be the SHEET's collection (`ISheet.getNames()`), not the workbook's: that one holds exactly
|
|
70
|
+
* what a formula on that sheet can refer to, so no scoping is needed here. The workbook's would
|
|
71
|
+
* offer another sheet's private names, which complete to expressions that do not resolve.
|
|
72
|
+
*/
|
|
73
|
+
getNames?(): INamedCollection | null;
|
|
74
|
+
/** Workbook locale (drives the argument-separator shown in the signature). `null` → `'en'`. */
|
|
75
|
+
getLocale(): string | null;
|
|
76
|
+
/**
|
|
77
|
+
* Apply an accepted completion: replace the WHOLE text and park the caret at `caret`. The editor
|
|
78
|
+
* routes this through its dirty-change; a field through its headless `replaceText`.
|
|
79
|
+
*/
|
|
80
|
+
applyText(next: string, caret: number): void;
|
|
81
|
+
/**
|
|
82
|
+
* The hovered token index (the eval tip's), or `null` — emphasizes the hovered ARGUMENT in the
|
|
83
|
+
* signature preview. Pass the live value (it participates in the panel identity).
|
|
84
|
+
*/
|
|
85
|
+
hoveredTokenIndex?: number | null;
|
|
86
|
+
}
|
|
87
|
+
/** What {@link useFormulaHints} hands the hosting chrome. */
|
|
88
|
+
export interface FormulaHintsApi {
|
|
89
|
+
/** Something to show — the autocomplete list has matches, or a signature preview resolved. */
|
|
90
|
+
active: boolean;
|
|
91
|
+
/**
|
|
92
|
+
* Re-derive the hint + matches from the current text/caret. Call whenever the text, caret, or
|
|
93
|
+
* active state changes (the same sync point that projects references).
|
|
94
|
+
*/
|
|
95
|
+
update(): void;
|
|
96
|
+
/**
|
|
97
|
+
* Autocomplete list keyboard nav (Up/Down move the highlight, Enter/Tab accept, Escape dismisses
|
|
98
|
+
* the LIST without cancelling the edit). Call FIRST in the host keymap; `true` = consumed.
|
|
99
|
+
*/
|
|
100
|
+
handleKeyDown(e: React.KeyboardEvent): boolean;
|
|
101
|
+
/** Drop the list + preview immediately (host-driven — e.g. leaving the edit). */
|
|
102
|
+
dismiss(): void;
|
|
103
|
+
/**
|
|
104
|
+
* Anchor offset (a character index) for a caret-rect anchored host: the START of the caret-owning
|
|
105
|
+
* token (the name being typed / the innermost open call's name), falling back to the caret.
|
|
106
|
+
*/
|
|
107
|
+
getAnchorOffset(): number;
|
|
108
|
+
/**
|
|
109
|
+
* STABLE-identity panel renderer for `useFloatStack.createPopupPanel` — the autocomplete list when
|
|
110
|
+
* it has matches, else the signature preview. Returns `null` when there is nothing to show.
|
|
111
|
+
*/
|
|
112
|
+
renderPanel(): React.ReactNode;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* The **formula hints** state machine — function autocomplete (`=SU` → SUM, SUMIF…) and the
|
|
116
|
+
* caret-context signature preview (current argument emphasized, self-describing summary/param text
|
|
117
|
+
* loaded lazily), extracted from the cell editor so every formula-hosting input shares ONE
|
|
118
|
+
* implementation: the session stack's `SheetCellInput` and the session-less field widgets
|
|
119
|
+
* (`useFormulaInputParts` → `FormulaInput` / the MUI `FormulaField`).
|
|
120
|
+
*
|
|
121
|
+
* Headless: derivation + keyboard + the panel's content only. The HOST owns the float (each chrome
|
|
122
|
+
* anchors a `useFloatStack` where it wants — the editor at the caret rect, a field under its input
|
|
123
|
+
* box), the open/close policy, and when {@link FormulaHintsApi.update} runs.
|
|
124
|
+
*/
|
|
125
|
+
export declare const useFormulaHints: (options: UseFormulaHintsOptions) => FormulaHintsApi;
|
|
126
|
+
//# sourceMappingURL=useFormulaHints.d.ts.map
|
|
@@ -0,0 +1,326 @@
|
|
|
1
|
+
import { ICalculation, ICellRanges, IRange, IWorkbook } from '@sheetxl/sdk';
|
|
2
|
+
import { ReferenceDoneArgs } from './useReferenceMode';
|
|
3
|
+
/**
|
|
4
|
+
* The two grammars a formula-backed field can enforce.
|
|
5
|
+
*
|
|
6
|
+
* - `'formula'` — any formula expression (`=SUM(A1:A5)*2`). The field text is one expression; the
|
|
7
|
+
* picker projects the expression's REFERENCES (per token) and a pick re-scopes the caret's
|
|
8
|
+
* reference or splices a new one at the caret — the formula editor's point model.
|
|
9
|
+
* - `'reference'` — a pure reference list (`Sheet1!A1:B2, Sheet2!C1`). The field text is comma-joined
|
|
10
|
+
* reference segments; the picker projects the SEGMENTS (segment index = picker range index) and a
|
|
11
|
+
* pick re-scopes/appends a segment. Function calls and computed expressions are invalid — the field
|
|
12
|
+
* accepts only what {@link ICalculation.IFormula.isReferenceOnly} holds for (Excel's RefEdit
|
|
13
|
+
* contract: OFFSET/INDIRECT-style computed references are not accepted; those belong in a
|
|
14
|
+
* `'formula'` field, e.g. a name's refers-to).
|
|
15
|
+
*/
|
|
16
|
+
export type FormulaInputGrammar = 'formula' | 'reference';
|
|
17
|
+
/**
|
|
18
|
+
* Leading-`=` policy for a `'formula'` field (a `'reference'` field never takes one — a typed `=` is
|
|
19
|
+
* an invalid character there, part of its "limit input" contract).
|
|
20
|
+
*
|
|
21
|
+
* Two facets in one policy — what the user may TYPE, and how a committed value DISPLAYS (see
|
|
22
|
+
* `formulaDisplayText`):
|
|
23
|
+
*
|
|
24
|
+
* - `'optional'` (default) — `=SUM(A1)` and `SUM(A1)` mean the same formula; the text stays as typed
|
|
25
|
+
* while typing. A committed value displays `=`-prefixed.
|
|
26
|
+
* - `'required'` — text without a leading `=` reads as an error. For fields where the `=` is part of
|
|
27
|
+
* the contract (a name's refers-to) rather than a convenience. Displays `=`-prefixed.
|
|
28
|
+
* - `'bare'` — the field READS bare: a committed value displays WITHOUT the `=` (a typed one is still
|
|
29
|
+
* accepted, and the next re-derive drops it). For fields whose stored expression carries no `=` on
|
|
30
|
+
* the wire — a conditional format's scale stop or `expression` param.
|
|
31
|
+
* - `'literal'` — the `=` DECIDES: text with a leading `=` is a formula (parsed, colored, validated),
|
|
32
|
+
* text without one is a literal that is never parsed and never an error — Excel's own cellIs/DV
|
|
33
|
+
* operand box. A committed string value displays verbatim; the `=` is the one discriminator, so
|
|
34
|
+
* the field adds none and strips none.
|
|
35
|
+
*/
|
|
36
|
+
export type FormulaInputEquals = 'optional' | 'required' | 'bare' | 'literal';
|
|
37
|
+
export declare const splitReferenceSegments: (text: string) => {
|
|
38
|
+
text: string;
|
|
39
|
+
start: number;
|
|
40
|
+
end: number;
|
|
41
|
+
}[];
|
|
42
|
+
/**
|
|
43
|
+
* One comma-segment of a `'reference'` field's text — the unit the host chrome colors and hit-tests.
|
|
44
|
+
* The SAME split the picker sync uses ({@link splitReferenceSegments}), so segment index `i` IS picker
|
|
45
|
+
* range index `i`: coloring segment `i` with the picker palette (`PICKER_COLORS[i % n]`) matches its
|
|
46
|
+
* on-grid rectangle exactly. (A `'formula'` field colors by TOKEN instead — see
|
|
47
|
+
* {@link FormulaInputApi.tokens}.)
|
|
48
|
+
*/
|
|
49
|
+
export interface ReferenceSegmentInfo {
|
|
50
|
+
/** The raw segment text (surrounding whitespace included; the `,` separators excluded). */
|
|
51
|
+
text: string;
|
|
52
|
+
/** Start of the segment's span in the field text (inclusive). */
|
|
53
|
+
start: number;
|
|
54
|
+
/** End of the segment's span in the field text (exclusive). */
|
|
55
|
+
end: number;
|
|
56
|
+
/** Whether the segment parses to a single range — colored + evaluable when `true`. */
|
|
57
|
+
valid: boolean;
|
|
58
|
+
}
|
|
59
|
+
export interface UseFormulaInputOptions {
|
|
60
|
+
/**
|
|
61
|
+
* The committed value. Display text re-derives whenever it changes (see the serialization policy
|
|
62
|
+
* per grammar). {@link ICellRanges} and `string` are accepted for DX — a host holding ranges (a
|
|
63
|
+
* table's range, a sheet selection) passes them straight in — and the emitted values are still
|
|
64
|
+
* {@link ICalculation.IFormula}.
|
|
65
|
+
*
|
|
66
|
+
* @remarks
|
|
67
|
+
* A ranges value is addressed by the SDK, never re-serialized here. With a {@link home} the address
|
|
68
|
+
* is localized to it (bare there, qualified elsewhere); WITHOUT one the value's own scoping decides
|
|
69
|
+
* what the field shows — a SHEET-scoped set reads bare (`$B$2:$D$5`), a WORKBOOK-scoped one
|
|
70
|
+
* sheet-qualified (`Sheet1!$B$2:$D$5`). See {@link ICellRanges.getAddress}.
|
|
71
|
+
*
|
|
72
|
+
* Treat as an IMMUTABLE snapshot: pass a new instance (or string) to change the field; mutating a
|
|
73
|
+
* held `IFormula` / `ICellRanges` in place is not observed.
|
|
74
|
+
*/
|
|
75
|
+
value: ICalculation.IFormula | ICellRanges | string | null;
|
|
76
|
+
/**
|
|
77
|
+
* Live change notification — fires on every VALID text state (typed or picked), `null` for cleared.
|
|
78
|
+
* Invalid in-progress text sets {@link FormulaInputApi.error} instead and does not fire.
|
|
79
|
+
*
|
|
80
|
+
* A PREVIEW channel: hosts that mutate the model per change (resize a table, re-source a chart)
|
|
81
|
+
* should act on {@link onDone} instead and treat this as optional live feedback.
|
|
82
|
+
*/
|
|
83
|
+
onChange?: (value: ICalculation.IFormula | null) => void;
|
|
84
|
+
/**
|
|
85
|
+
* The raw TEXT channel: every display-text change the user causes (typed, picked, F4'd, reverted) —
|
|
86
|
+
* INVALID states included, and regardless of {@link changeOn}. For hosts that persist authored text
|
|
87
|
+
* rather than a parsed value (a name's refers-to written through to a draft that validates at save):
|
|
88
|
+
* {@link onChange} would leave them holding the last VALID text while the field shows something
|
|
89
|
+
* else. An outside `value` change does not fire it.
|
|
90
|
+
*/
|
|
91
|
+
onChangeText?: (text: string) => void;
|
|
92
|
+
/**
|
|
93
|
+
* The field's CHANGE MODEL. Default `'live'`. Beyond suppressing the live {@link onChange} (parsing
|
|
94
|
+
* still runs — error state, picker sync), `'done'` makes Enter the FIELD's commit point rather than
|
|
95
|
+
* a key the host form sees (the shared policy — see `useEditCommit`) — plus one grammar-specific
|
|
96
|
+
* effect here: a `'done'` reference field drops to caret-edit while the user TYPES (a pick re-arms),
|
|
97
|
+
* where a `'live'` one points for its whole engagement (the RefEdit contract).
|
|
98
|
+
*/
|
|
99
|
+
changeOn?: 'live' | 'done';
|
|
100
|
+
/**
|
|
101
|
+
* Allow a comma-separated multi-range reference — typed or picked (Ctrl+click on the grid appends).
|
|
102
|
+
* Default `false` (single range; a pick replaces). Named to match the picker tier's `allowMulti`
|
|
103
|
+
* (`useSelectionPointer` / `RangesPickerLayer`) — it rides the bus state to gate the grid gesture.
|
|
104
|
+
*
|
|
105
|
+
* `'reference'` grammar only; a `'formula'` field always allows every reference its expression holds.
|
|
106
|
+
*/
|
|
107
|
+
allowMulti?: boolean;
|
|
108
|
+
/**
|
|
109
|
+
* Whether references may reach OTHER sheets. Default `true`. The sheet-count gate, sibling to
|
|
110
|
+
* {@link allowMulti}'s range-count gate — both are declared by the producer because both are
|
|
111
|
+
* properties of what is being picked, and both ride the bus to gate the grid gesture.
|
|
112
|
+
*
|
|
113
|
+
* `false` confines the field to ONE sheet — {@link home}'s (falling back to the selected sheet when
|
|
114
|
+
* there is no home, which is why a confined field should always pass one):
|
|
115
|
+
*
|
|
116
|
+
* - a typed cross-sheet reference (`Sheet2!A1`) is an ERROR, not a value;
|
|
117
|
+
* - the grid refuses picks on any other sheet's pane (`ReferenceModeState.scope`);
|
|
118
|
+
* - addresses display BARE, since every reference means the one sheet (see {@link addressForHome}).
|
|
119
|
+
*
|
|
120
|
+
* Excel's single-sheet inputs are exactly this shape: a table's range, conditional formatting's
|
|
121
|
+
* "Applies to" (multi-range but one sheet — `allowMulti` and this are independent). Leave it `true`
|
|
122
|
+
* for anything that genuinely spans sheets, e.g. chart series.
|
|
123
|
+
*/
|
|
124
|
+
allowCrossSheet?: boolean;
|
|
125
|
+
/** Disabled: never engages the bus; the text is read-only at the host's discretion. */
|
|
126
|
+
disabled?: boolean;
|
|
127
|
+
/** Resolution context. Defaults to the enclosing `WorkbookContext`. */
|
|
128
|
+
workbook?: IWorkbook | null;
|
|
129
|
+
/**
|
|
130
|
+
* The field's HOME anchor — the coords (with `scope`) a bare reference (`A1`) resolves against and
|
|
131
|
+
* serializes bare for. A host that HAS an anchor (a table's sheet, a conditional-format rule's
|
|
132
|
+
* cell, the cell an inserted function lands in) should pass it.
|
|
133
|
+
*
|
|
134
|
+
* @remarks
|
|
135
|
+
* BOTH grammars honor it, and in both a field with NO home has no bare form at all: its text stays
|
|
136
|
+
* fully qualified, and a pick made on the visible tab still carries that tab's name. That is what a
|
|
137
|
+
* host with no sheet of its own means — a defined name's refers-to is read from wherever the name is
|
|
138
|
+
* USED, so a bare address left in it names nothing once the field is gone. (Resolving text the user
|
|
139
|
+
* TYPED still falls back to the selected sheet; there is no other sheet a bare `A1` could mean.)
|
|
140
|
+
* With a home, references on that sheet read bare and only cross-sheet ones carry a sheet name. Only
|
|
141
|
+
* `scope` matters to a `'reference'` field; the cell coords additionally anchor a `'formula'` field's
|
|
142
|
+
* relative references.
|
|
143
|
+
*/
|
|
144
|
+
home?: Partial<IRange.CellCoords>;
|
|
145
|
+
/** Leading-`=` policy (`'formula'` grammar only). Default `'optional'`. */
|
|
146
|
+
equals?: FormulaInputEquals;
|
|
147
|
+
/**
|
|
148
|
+
* What a NEW reference lands as when the picker writes one — `'absolute'` (`$A$1:$B$2`) or
|
|
149
|
+
* `'relative'` (`A1:B2`). Default `'relative'`, the cell editor's behavior (a formula that is copied
|
|
150
|
+
* should move with it).
|
|
151
|
+
*
|
|
152
|
+
* Scoped deliberately narrowly — it decides ONLY the references a pick CREATES:
|
|
153
|
+
*
|
|
154
|
+
* - RE-SCOPING an existing reference (dragging its rectangle, arrow point-nav, select-current on
|
|
155
|
+
* it) keeps THAT reference's own `$` flags, including partial ones (`$A1`, `A$1:B$9`). A pick
|
|
156
|
+
* moves where a reference points; it does not restyle it.
|
|
157
|
+
* - a value handed in keeps whatever fixability it came with — this never rewrites it;
|
|
158
|
+
* - typing reaches either form, and F4 still cycles the `$` on the caret's reference.
|
|
159
|
+
*
|
|
160
|
+
* `'absolute'` is the *defined name* shape — a name denotes a fixed region, not one relative to
|
|
161
|
+
* whoever reads it — and the table-resize shape (Excel's `$A$3:$D$9`).
|
|
162
|
+
*/
|
|
163
|
+
pickAs?: 'absolute' | 'relative';
|
|
164
|
+
/**
|
|
165
|
+
* The COMMIT channel: fires with the final parsed value at each commit point — a done key
|
|
166
|
+
* (Enter/Tab/Escape, from the field or the GRID), the explicit {@link FormulaInputApi.commit}
|
|
167
|
+
* (the adornment ✓ / a dialog's OK), or blur to another field. Picker gestures do NOT commit —
|
|
168
|
+
* drags update only the text; the user finishes explicitly. `args.reason` distinguishes accept
|
|
169
|
+
* from cancel (a cancel delivers the reverted session baseline). NOT fired on an accept while the
|
|
170
|
+
* text is invalid — the error stays shown instead.
|
|
171
|
+
*/
|
|
172
|
+
onDone?: (value: ICalculation.IFormula | null, args: ReferenceDoneArgs) => void;
|
|
173
|
+
}
|
|
174
|
+
/** What {@link useFormulaInput} hands the host input component. */
|
|
175
|
+
export interface FormulaInputApi {
|
|
176
|
+
/** Spread onto the `<input>`/`<textarea>`: value + handlers + element ref. */
|
|
177
|
+
inputProps: {
|
|
178
|
+
/**
|
|
179
|
+
* What the ELEMENT holds — {@link FormulaInputApi.text} until it is
|
|
180
|
+
* {@link FormulaInputApi.overLength}, a clamped head of it after. Read {@link text} for the
|
|
181
|
+
* whole value.
|
|
182
|
+
*/
|
|
183
|
+
value: string;
|
|
184
|
+
/** `true` when the text is over the limit (see {@link FormulaInputApi.overLength}). */
|
|
185
|
+
readOnly: boolean;
|
|
186
|
+
onChange: (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
|
|
187
|
+
onKeyDown: (e: React.KeyboardEvent) => void;
|
|
188
|
+
onFocus: (e: React.FocusEvent) => void;
|
|
189
|
+
onBlur: (e: React.FocusEvent) => void;
|
|
190
|
+
onMouseDown: (e: React.MouseEvent) => void;
|
|
191
|
+
/** Caret/selection moved — re-projects which reference/segment the next pick targets. */
|
|
192
|
+
onSelect: (e: React.SyntheticEvent) => void;
|
|
193
|
+
ref: (el: HTMLInputElement | HTMLTextAreaElement | null) => void;
|
|
194
|
+
};
|
|
195
|
+
/** The live display text, whole — {@link inputProps.value} is what the element holds. */
|
|
196
|
+
text: string;
|
|
197
|
+
/**
|
|
198
|
+
* `true` when {@link text} is longer than {@link ICalculation.MAX_EXPRESSION_LENGTH}.
|
|
199
|
+
*
|
|
200
|
+
* @remarks
|
|
201
|
+
* A rule's applies-to renders one address per area, so a striped rule reaches millions of
|
|
202
|
+
* characters from ordinary edits. Three things follow, and all three are needed:
|
|
203
|
+
*
|
|
204
|
+
* - Text this long is never parsed — not whole, not segment-by-segment — so the chrome has
|
|
205
|
+
* nothing to color ({@link tokens} `null`, {@link segments} empty) and the field cannot engage
|
|
206
|
+
* as the reference producer.
|
|
207
|
+
* - {@link inputProps.value} is clamped, because a single-line input holding millions of
|
|
208
|
+
* characters is what exhausts the renderer even with no parsing and no overlay.
|
|
209
|
+
* - The input is read-only, so the clamped view can never be committed back over the whole one.
|
|
210
|
+
*/
|
|
211
|
+
overLength: boolean;
|
|
212
|
+
/**
|
|
213
|
+
* `'reference'` grammar: the text split into reference segments (see {@link ReferenceSegmentInfo})
|
|
214
|
+
* — the chrome's coloring/hover model. Empty for blank text, with no workbook, or in `'formula'`
|
|
215
|
+
* grammar (color by {@link tokens} there).
|
|
216
|
+
*/
|
|
217
|
+
segments: readonly ReferenceSegmentInfo[];
|
|
218
|
+
/**
|
|
219
|
+
* `'formula'` grammar: the live parse's tokens WHEN they reproduce the text exactly (so span
|
|
220
|
+
* offsets line up 1:1 for a coloring overlay), else `null` — render plain text. Offsets start at
|
|
221
|
+
* {@link tokenBase}. Always `null` in `'reference'` grammar.
|
|
222
|
+
*/
|
|
223
|
+
tokens: readonly ICalculation.FormulaToken[] | null;
|
|
224
|
+
/** Offset of the first token in the text (1 past a leading `=`; 0 otherwise). */
|
|
225
|
+
tokenBase: number;
|
|
226
|
+
/** Parse error for the current text (`null` when valid). */
|
|
227
|
+
error: string | null;
|
|
228
|
+
/** `true` when the text differs from the committed value's text. */
|
|
229
|
+
dirty: boolean;
|
|
230
|
+
/** `true` while this field is the reference-mode producer (grid/header/keyboard picks write here). */
|
|
231
|
+
engaged: boolean;
|
|
232
|
+
/**
|
|
233
|
+
* `true` while arrow keys PICK (point) rather than move the text caret (caret-edit). F2 remains a
|
|
234
|
+
* manual toggle; a pick always re-arms. Per grammar:
|
|
235
|
+
*
|
|
236
|
+
* - `'reference'` — armed on engage (RefEdit): a `'live'` field stays armed for its whole
|
|
237
|
+
* engagement; a `'done'` field drops to caret-edit while typing. Grid MOUSE picks work whenever
|
|
238
|
+
* the field is engaged, regardless.
|
|
239
|
+
* - `'formula'` — armed by CARET CONTEXT (the cell editor's model): an operand expected at the
|
|
240
|
+
* caret, or the caret on a reference token. Elsewhere (a function name, a number) the caret does
|
|
241
|
+
* text work — and the bus drops to `'show'`, so the references stay displayed (rectangles still
|
|
242
|
+
* drag-to-re-scope) while fresh grid gestures don't splice into the middle of a token.
|
|
243
|
+
*/
|
|
244
|
+
pointArmed: boolean;
|
|
245
|
+
/** Arm/disarm picking without focus (the adornment toggle). */
|
|
246
|
+
togglePoint(): void;
|
|
247
|
+
/**
|
|
248
|
+
* Engage the reference-mode bus explicitly (idempotent — a no-op while already engaged): begins
|
|
249
|
+
* the field's pick session exactly as the first focus or keystroke would. For hosts that hand the
|
|
250
|
+
* field focus programmatically: `.focus()` engages only through the focus EVENT, and a hand-off
|
|
251
|
+
* racing other focus work (a closing menu) may never fire one — leaving the field focused but
|
|
252
|
+
* idle. Does not itself move focus.
|
|
253
|
+
*/
|
|
254
|
+
engage(): void;
|
|
255
|
+
/**
|
|
256
|
+
* Replace the field's WHOLE text programmatically (an accepted autocomplete row, a host template)
|
|
257
|
+
* and optionally park the caret — runs the same live-parse/emit pipeline as typing, engaging first
|
|
258
|
+
* when idle (the edit starts a session exactly like a keystroke would).
|
|
259
|
+
*/
|
|
260
|
+
replaceText(next: string, caret?: number): void;
|
|
261
|
+
/** Replace the reference with the displayed sheet's current selection (the adornment action). */
|
|
262
|
+
selectCurrent(): void;
|
|
263
|
+
/**
|
|
264
|
+
* Whether {@link selectCurrent} has a valid landing RIGHT NOW. Always `true` in `'reference'`
|
|
265
|
+
* grammar (the action replaces/appends the whole value). `'formula'` grammar: `true` when the
|
|
266
|
+
* caret sits where a reference can land — on a reference token (re-scope) or where an operand is
|
|
267
|
+
* expected (splice); `false` mid-token (`SU|M`), where the chrome should disable the action —
|
|
268
|
+
* without this the selection spliced into random caret spots.
|
|
269
|
+
*/
|
|
270
|
+
canSelectCurrent: boolean;
|
|
271
|
+
/** Restore the committed value's text (the field-level Escape). */
|
|
272
|
+
revert(): void;
|
|
273
|
+
/**
|
|
274
|
+
* Explicit accept — the host-driven commit point (a dialog's OK, the adornment ✓). Engaged: ends
|
|
275
|
+
* the pick session through the same path as a done key; idle: delivers the field's current value
|
|
276
|
+
* on the commit channel.
|
|
277
|
+
*/
|
|
278
|
+
commit(): void;
|
|
279
|
+
/**
|
|
280
|
+
* Explicit cancel (a dialog's Cancel, the adornment ✗). Engaged: cancels the pick session
|
|
281
|
+
* (reverts to the session baseline); idle: reverts to the committed value. Either way the commit
|
|
282
|
+
* channel hears `reason: 'cancel'`.
|
|
283
|
+
*/
|
|
284
|
+
cancel(): void;
|
|
285
|
+
/**
|
|
286
|
+
* The last successfully parsed value's references — a convenience over
|
|
287
|
+
* `value.getReferences()` for hosts that consume ranges (dialogs sizing a table). `null` when the
|
|
288
|
+
* current value is `null` or (in `'formula'` grammar) when the expression holds no references.
|
|
289
|
+
*/
|
|
290
|
+
getRanges(): ICellRanges | null;
|
|
291
|
+
/**
|
|
292
|
+
* Evaluate segment `index`'s reference and format it for a hover tip — the formula editor's
|
|
293
|
+
* eval-tip formatting (`formatEvalValue`: an array literal up to a small cap, else its
|
|
294
|
+
* `{rows×cols}` shape). Resolves `null` when the segment is invalid/empty, there is no workbook,
|
|
295
|
+
* or evaluation fails — show no tip. (`'reference'` grammar; a `'formula'` field's chrome
|
|
296
|
+
* evaluates token segments via `evalSegmentAt` + `createFormula` directly.)
|
|
297
|
+
*/
|
|
298
|
+
evaluateSegment(index: number): Promise<string | null>;
|
|
299
|
+
}
|
|
300
|
+
/**
|
|
301
|
+
* The **headless formula input** — everything a formula-backed field does except its chrome:
|
|
302
|
+
* text ⟷ {@link ICalculation.IFormula} parsing, acting as the reference-mode bus PRODUCER while
|
|
303
|
+
* focused (grid drags, header picks and keyboard point-nav all write into the field through the same
|
|
304
|
+
* machinery the cell editor uses), done-key handling (`onDone` returns focus to the FIELD, never the
|
|
305
|
+
* sheet), and keyboard pointing armed WITHOUT F2 — per grammar: a `'reference'` field arms on engage
|
|
306
|
+
* (the Excel RefEdit contract — `'live'` for the whole engagement, `'done'` until typing); a
|
|
307
|
+
* `'formula'` field arms by CARET CONTEXT (operand expected, or the caret on a reference token — the
|
|
308
|
+
* cell editor's model), showing its references without picking everywhere else. A pick re-arms; F2
|
|
309
|
+
* stays as a manual toggle (the inline grid editor's convention).
|
|
310
|
+
*
|
|
311
|
+
* Two grammars share this one hook (see {@link FormulaInputGrammar}); `'formula'` is the default.
|
|
312
|
+
* The grammar decides how text maps to picker ranges (tokens vs segments), how a pick writes back,
|
|
313
|
+
* and what validates — everything else (engagement, commit channels, key semantics) is identical by
|
|
314
|
+
* construction.
|
|
315
|
+
*
|
|
316
|
+
* @remarks
|
|
317
|
+
* Framework-free on purpose (chromes are thin wrappers — a plain-DOM one ships in this package, the
|
|
318
|
+
* MUI one in `studio-mui`). Session-less: no `IEditable` involved; the bus state carries its own
|
|
319
|
+
* `onDone`. While POINTING, blur DISENGAGES only when focus lands in another text input (another
|
|
320
|
+
* dialog field) — focus moving to the grid, headers, or sheet tabs is a pick in progress and keeps
|
|
321
|
+
* the engagement, exactly like the editor's active-input claim persisting through a picker-drag
|
|
322
|
+
* blur. While merely SHOWING (formula grammar, not armed) there is no gesture to protect: ANY blur
|
|
323
|
+
* releases the bus and the displayed ranges clear — the highlight follows the active editor.
|
|
324
|
+
*/
|
|
325
|
+
export declare const useFormulaInput: (options: UseFormulaInputOptions, grammar?: FormulaInputGrammar) => FormulaInputApi;
|
|
326
|
+
//# sourceMappingURL=useFormulaInput.d.ts.map
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
import { ISheet } from '@sheetxl/sdk';
|
|
2
|
+
/**
|
|
3
|
+
* The Excel-style "sheet is protected" heads-up for a rejected edit attempt (`IEditable.startEdit`
|
|
4
|
+
* returning `false`). Returns the callback a host invokes on each rejection; the notice shows once
|
|
5
|
+
* per **visit** to `sheet` — Excel re-warns each time you come (back) to a tab, so the once-flag
|
|
6
|
+
* resets on a `sheet` identity change (and naturally on remount). The `isLocked()` guard keeps the
|
|
7
|
+
* message protection-specific: any other non-editable reason stays silent.
|
|
8
|
+
*
|
|
9
|
+
* One instance should serve one visit scope — `SheetElement` creates it and threads the callback to
|
|
10
|
+
* every consumer it hosts (its imperative `startEdit` and each pane's editor layer), so four frozen
|
|
11
|
+
* panes never warn four times.
|
|
12
|
+
*/
|
|
13
|
+
export declare const useProtectedEditNotice: (sheet: ISheet) => (() => void);
|
|
14
|
+
//# sourceMappingURL=useProtectedEditNotice.d.ts.map
|
|
@@ -0,0 +1,177 @@
|
|
|
1
|
+
import { IRangeSelection } from '@sheetxl/sdk';
|
|
2
|
+
import { IInputHandle } from '@sheetxl/grid-react';
|
|
3
|
+
/**
|
|
4
|
+
* A caret-owning input that participates in **reference (point) mode** — grid-react's generic
|
|
5
|
+
* {@link IInputHandle} plus the reference-specific caret ops that only make sense over a spreadsheet.
|
|
6
|
+
* Implemented by the cell formula editor and (later) standalone reference inputs (a chart series / dialog
|
|
7
|
+
* range field). Kept in `@sheetxl/react` so grid-react stays spreadsheet-agnostic.
|
|
8
|
+
*/
|
|
9
|
+
export interface IReferenceInputHandle extends IInputHandle {
|
|
10
|
+
/** F4 — cycle `$` (relative ⇄ absolute) on the reference under this input's caret. No-op off a reference. */
|
|
11
|
+
toggleReferences(): void;
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* The two states of the **reference (point) dimension** — orthogonal to the edit dimension
|
|
15
|
+
* (`EditorMode` `'enter' | 'edit'`). A cell formula edit or a selected chart can be in one of these
|
|
16
|
+
* while (independently) being in an edit mode or not.
|
|
17
|
+
*
|
|
18
|
+
* - `'show'` — the reference ranges are **displayed** (and their rectangles drag/resize to re-scope an
|
|
19
|
+
* existing reference). A formula edit not armed for point, or a selected chart showing its source data.
|
|
20
|
+
* - `'point'` — **active picking**: a grid drag draws/re-scopes the active reference, headers pick full
|
|
21
|
+
* rows/columns. The armed state.
|
|
22
|
+
*/
|
|
23
|
+
export type ReferenceMode = 'show' | 'point';
|
|
24
|
+
/**
|
|
25
|
+
* How a reference pick was finished: `'accept'` (Enter / Tab — keep the picked ranges) or `'cancel'`
|
|
26
|
+
* (Escape — abandon them). Deliberately pick-vocabulary, not edit-vocabulary: what accepting *means*
|
|
27
|
+
* (commit an edit session, close a dialog range field, ...) is the producer's business. The triggering
|
|
28
|
+
* key + modifiers ride along for producers that distinguish — e.g. a dialog treating Tab as
|
|
29
|
+
* accept-and-move-to-the-next-field (Shift reversing) while Enter accepts-and-closes.
|
|
30
|
+
*/
|
|
31
|
+
export interface ReferenceDoneArgs {
|
|
32
|
+
reason: 'accept' | 'cancel';
|
|
33
|
+
/** The done key that triggered this, when keyboard-driven. */
|
|
34
|
+
key?: 'Enter' | 'Tab' | 'Escape';
|
|
35
|
+
/** Shift held on the done key (e.g. reverse traverse/field direction). */
|
|
36
|
+
shiftKey?: boolean;
|
|
37
|
+
/** Alt held on the done key. */
|
|
38
|
+
altKey?: boolean;
|
|
39
|
+
}
|
|
40
|
+
/**
|
|
41
|
+
* The app-wide reference-mode state — "what ranges are being shown/picked, and who (if anyone) drives".
|
|
42
|
+
* Held on its own bus ({@link useReferenceMode}) because the reference dimension is independent of
|
|
43
|
+
* editing: a selected chart shows ranges with **no active input**, and a formula edit shows/points while
|
|
44
|
+
* *also* being an edit session.
|
|
45
|
+
*/
|
|
46
|
+
export interface ReferenceModeState {
|
|
47
|
+
/** {@inheritDoc ReferenceMode} */
|
|
48
|
+
mode: ReferenceMode;
|
|
49
|
+
/**
|
|
50
|
+
* The ranges to render — the sdk {@link IRangeSelection} (the consumer wraps it for the grid layer).
|
|
51
|
+
* Can be multi-sheet (a formula referencing more than one sheet): every range, and `selection`'s own
|
|
52
|
+
* active `cell`, carries its own `scope` (a sheet name) — there is deliberately no separate top-level
|
|
53
|
+
* "origin sheet" field here; a consumer reads scope straight off the coords it's already holding, same
|
|
54
|
+
* as everywhere else in this pipeline. A pane-level consumer (`SheetReferenceLayer`) filters to just
|
|
55
|
+
* its own sheet's ranges, but while `'point'` is armed it takes the gesture on ANY pane (Excel: tab to
|
|
56
|
+
* another sheet and drag) — {@link scope} is the only thing that narrows that.
|
|
57
|
+
*/
|
|
58
|
+
selection: IRangeSelection;
|
|
59
|
+
/**
|
|
60
|
+
* The input currently driving point-mode gestures (the caret owner). `null` in `'show'` with no
|
|
61
|
+
* editor — e.g. a selected chart that only displays its ranges. Point gestures route here when set.
|
|
62
|
+
*/
|
|
63
|
+
activeInput: IReferenceInputHandle | null;
|
|
64
|
+
/**
|
|
65
|
+
* Whether this pick allows **multiple ranges** — Ctrl/Cmd+click on the grid then APPENDS a brand-new
|
|
66
|
+
* reference (which a text-backed consumer joins with a `,` separator). Declared by the PRODUCER,
|
|
67
|
+
* because it is a property of what's being picked: a formula edit allows it, a single-rectangle
|
|
68
|
+
* field (a chart series / table range) does not. Consumed by `SheetReferenceLayer`, which forwards
|
|
69
|
+
* it to the picker's `allowMulti`. Absent ⇒ allowed (the formula-edit default).
|
|
70
|
+
*/
|
|
71
|
+
allowMulti?: boolean;
|
|
72
|
+
/**
|
|
73
|
+
* Confines this pick to ONE sheet, by name — the sheet-count gate, sibling to {@link allowMulti}'s
|
|
74
|
+
* range-count gate. Declared by the PRODUCER, because (like `allowMulti`) it is a property of what
|
|
75
|
+
* is being picked: a table's range and conditional formatting's "Applies to" live on a single sheet,
|
|
76
|
+
* while a chart's series and a formula edit span the workbook. Absent ⇒ unconfined (the formula-edit
|
|
77
|
+
* default).
|
|
78
|
+
*
|
|
79
|
+
* Consumed by `SheetReferenceLayer`: a pane whose sheet is not this one refuses the gesture outright
|
|
80
|
+
* — no draw, no re-scope, no point-nav — so the cross-sheet pick Excel offers by tabbing to another
|
|
81
|
+
* sheet simply isn't available. (Rendering needs no extra filter: a confined producer's ranges are
|
|
82
|
+
* all on this sheet, and the existing per-pane scope filter already drops everything else.)
|
|
83
|
+
*/
|
|
84
|
+
scope?: string;
|
|
85
|
+
/**
|
|
86
|
+
* `true` while a reference rectangle is actively being dragged/resized/drawn on the grid. Published by the
|
|
87
|
+
* reference layer (from the picker's drag lifecycle) so a consumer — e.g. the formula editor — can react to
|
|
88
|
+
* the gesture directly: hide its hint popup for the duration, or later render differently mid-drag. It is a
|
|
89
|
+
* transient GESTURE flag, distinct from `mode` (which is the armed/display disposition).
|
|
90
|
+
*/
|
|
91
|
+
dragging?: boolean;
|
|
92
|
+
/**
|
|
93
|
+
* The reference INDEX being moved/resized while {@link dragging} — so a consumer can highlight exactly that
|
|
94
|
+
* reference (its token span in the text), in EVERY editor sharing this bus, not just the one that owns the
|
|
95
|
+
* write-back. `undefined` for a DRAW (a new range, no existing index) or when not dragging. Same ordering as
|
|
96
|
+
* a formula token's `referenceIndex`, so it maps straight onto the text.
|
|
97
|
+
*/
|
|
98
|
+
draggingIndex?: number;
|
|
99
|
+
/**
|
|
100
|
+
* Finish the pick — invoked with `'accept'` (Enter) / `'cancel'` (Escape) by a reference LAYER when
|
|
101
|
+
* a done key lands on the **grid** while `'point'` is armed (the case where no input has focus — a
|
|
102
|
+
* cross-sheet pick, where the grid holds focus and a focused editor would otherwise be the one
|
|
103
|
+
* consuming these keys). Supplied by the PRODUCER of this state, which is what keeps the layer
|
|
104
|
+
* producer-agnostic: the formula-edit producer maps it onto the edit *session*
|
|
105
|
+
* (`editable.commit()`/`.cancel()`), a session-less picker (a table-range / named-reference field)
|
|
106
|
+
* closes itself and returns focus to its own widget. When absent the layer does not consume the
|
|
107
|
+
* keys at all — they fall through to the grid as usual.
|
|
108
|
+
*/
|
|
109
|
+
onDone?: (args: ReferenceDoneArgs) => void;
|
|
110
|
+
}
|
|
111
|
+
/** The imperative handle {@link useReferenceMode} returns — mirrors `useEditMode`'s `getMode`/`setMode`. */
|
|
112
|
+
export interface ReferenceModeHandler {
|
|
113
|
+
getMode(): ReferenceModeState | null;
|
|
114
|
+
setMode(next: ReferenceModeState | null | ((prev: ReferenceModeState | null) => ReferenceModeState | null)): void;
|
|
115
|
+
}
|
|
116
|
+
/**
|
|
117
|
+
* A reference-mode **bus instance** — one shared point/show state and its subscribers. The store is a
|
|
118
|
+
* first-class value (not a module global) so a client can mount its OWN bus above a subtree via
|
|
119
|
+
* {@link ReferenceModeProvider}: their custom picker widget and the Studio/Workbook under the same
|
|
120
|
+
* provider share *that* instance, making a third-party producer first-class with no Studio
|
|
121
|
+
* involvement. Everything below the provider — layers, header layers, inputs, the keymap hosts —
|
|
122
|
+
* resolves the store through {@link useReferenceMode}/{@link useReferenceModeStore}.
|
|
123
|
+
*/
|
|
124
|
+
export interface ReferenceModeStore extends ReferenceModeHandler {
|
|
125
|
+
/** Subscribe to any state change. Returns the remover. */
|
|
126
|
+
subscribe(listener: () => void): () => void;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Create an isolated reference-mode store — a plain observable (deliberately not `singletonHook`, so
|
|
130
|
+
* there's no container dependency and reads are always fresh; no captured-value stale-closure trap).
|
|
131
|
+
*/
|
|
132
|
+
export declare const createReferenceModeStore: () => ReferenceModeStore;
|
|
133
|
+
/** The current reference-mode state, read from the DEFAULT store — see {@link setReferenceMode}. */
|
|
134
|
+
export declare const getReferenceMode: () => ReferenceModeState | null;
|
|
135
|
+
/**
|
|
136
|
+
* Publish (or clear) the reference-mode state on the **DEFAULT store** — write-only, **non-hook** so a
|
|
137
|
+
* non-component owner (a chart, the formula edit's producer) can drive it from anywhere. Mirrors
|
|
138
|
+
* `setEditMode`. A producer that may live under a custom {@link ReferenceModeProvider} should instead
|
|
139
|
+
* write through the store it was handed (a component: `useReferenceMode().setMode`; model-side wiring:
|
|
140
|
+
* the store passed to it — see `createEditable`).
|
|
141
|
+
*/
|
|
142
|
+
export declare const setReferenceMode: ReferenceModeHandler['setMode'];
|
|
143
|
+
/**
|
|
144
|
+
* The provider seam: a subtree-scoped bus instance. Absent ⇒ the default store (zero-config behavior
|
|
145
|
+
* unchanged).
|
|
146
|
+
*/
|
|
147
|
+
export declare const ReferenceModeContext: import('react').Context<ReferenceModeStore | null>;
|
|
148
|
+
export interface ReferenceModeProviderProps {
|
|
149
|
+
/** The bus instance to share. Omit to mint a fresh isolated one for this subtree. */
|
|
150
|
+
store?: ReferenceModeStore;
|
|
151
|
+
children?: React.ReactNode;
|
|
152
|
+
}
|
|
153
|
+
/**
|
|
154
|
+
* Share one reference-mode bus with a subtree. Mount ABOVE both a custom picker widget and the
|
|
155
|
+
* Studio/Workbook to let the widget participate in grid/header/keyboard picking as a first-class
|
|
156
|
+
* producer; or around a second workbook to isolate its picking from the first. With no `store` prop a
|
|
157
|
+
* fresh instance is created (stable for the provider's lifetime).
|
|
158
|
+
*/
|
|
159
|
+
export declare const ReferenceModeProvider: (props: ReferenceModeProviderProps) => React.ReactElement;
|
|
160
|
+
/**
|
|
161
|
+
* Resolve the enclosing bus **instance**: the nearest {@link ReferenceModeProvider}'s store, else the
|
|
162
|
+
* default. Non-reactive (no re-render on state change) — for handing the store onward (e.g. into
|
|
163
|
+
* `createEditable`) or for imperative read/write; use {@link useReferenceMode} to also re-render.
|
|
164
|
+
*/
|
|
165
|
+
export declare const useReferenceModeStore: () => ReferenceModeStore;
|
|
166
|
+
/**
|
|
167
|
+
* Access the enclosing **reference-mode bus** — the point/show dimension, the sibling of
|
|
168
|
+
* `useEditMode`. Reading re-renders on change; writing goes through the returned `setMode` (which
|
|
169
|
+
* targets the same resolved store — never the module-level {@link setReferenceMode} from a component,
|
|
170
|
+
* which always hits the default store).
|
|
171
|
+
*
|
|
172
|
+
* @remarks
|
|
173
|
+
* The reference layer renders whenever a state is present, regardless of `mode` or `activeInput`; point
|
|
174
|
+
* gestures route to {@link ReferenceModeState.activeInput} when non-null.
|
|
175
|
+
*/
|
|
176
|
+
export declare const useReferenceMode: () => ReferenceModeHandler;
|
|
177
|
+
//# sourceMappingURL=useReferenceMode.d.ts.map
|