@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.
Files changed (257) hide show
  1. package/browser/cjs/Bo9Kx3L_XQkGPBJ5.cjs +1 -0
  2. package/browser/cjs/Pl04-kDEQSO8_qFU.cjs +156 -0
  3. package/browser/cjs/index.cjs +24 -24
  4. package/browser/esm/D_suN0U6XvrHxTak.mjs +6286 -0
  5. package/browser/esm/index.mjs +19258 -4911
  6. package/licenses/dependencies.txt +42 -214
  7. package/node/esm/CH084kteEgVy0a8H.mjs +9 -0
  8. package/node/esm/index.mjs +17035 -3691
  9. package/package.json +10 -11
  10. package/resources/contents.json +60 -0
  11. package/resources/locales/contents.json +114 -0
  12. package/resources/locales/de/clipboard.cmd.json +36 -0
  13. package/resources/locales/de/editor.cmd.json +128 -0
  14. package/resources/locales/de/movable.cmd.json +123 -0
  15. package/resources/locales/de/selection.cmd.json +373 -0
  16. package/resources/locales/de/sheet.cmd.json +1563 -0
  17. package/resources/locales/de/table.cmd.json +83 -0
  18. package/resources/locales/de/ui.msg.json +166 -0
  19. package/resources/locales/de/workbook.cmd.json +282 -0
  20. package/resources/locales/en/clipboard.cmd.json +36 -0
  21. package/resources/locales/en/editor.cmd.json +128 -0
  22. package/resources/locales/en/movable.cmd.json +123 -0
  23. package/resources/locales/en/selection.cmd.json +373 -0
  24. package/resources/locales/en/sheet.cmd.json +1563 -0
  25. package/resources/locales/en/table.cmd.json +83 -0
  26. package/resources/locales/en/ui.msg.json +166 -0
  27. package/resources/locales/en/workbook.cmd.json +282 -0
  28. package/types/index.d.ts +2 -1767
  29. package/types/src/border/StaticBorderRenderer.d.ts +32 -0
  30. package/types/src/border/StyledStrokePath.d.ts +14 -0
  31. package/types/src/border/index.d.ts +4 -0
  32. package/types/src/border/useBorders.d.ts +87 -0
  33. package/types/src/cell/ColumnButton.d.ts +45 -0
  34. package/types/src/cell/CornerTriangle.d.ts +27 -0
  35. package/types/src/cell/FormulaCellRenderer.d.ts +34 -0
  36. package/types/src/cell/SheetCellRenderer.d.ts +52 -0
  37. package/types/src/cell/SheetHeaderRenderer.d.ts +37 -0
  38. package/types/src/cell/index.d.ts +7 -0
  39. package/types/src/cell/useFormulaViewAnchor.d.ts +42 -0
  40. package/types/src/chart/ChartEditor.d.ts +17 -0
  41. package/types/src/chart/PresetChartTypeDescriptors.d.ts +35 -0
  42. package/types/src/chart/index.d.ts +3 -0
  43. package/types/src/chart/templates/area-stacked-percent-template.json.d.ts +10 -0
  44. package/types/src/chart/templates/area-stacked-template.json.d.ts +10 -0
  45. package/types/src/chart/templates/area-template.json.d.ts +9 -0
  46. package/types/src/chart/templates/bar-stacked-percent-template.json.d.ts +10 -0
  47. package/types/src/chart/templates/bar-stacked-template.json.d.ts +10 -0
  48. package/types/src/chart/templates/bar-template.json.d.ts +9 -0
  49. package/types/src/chart/templates/column-stacked-percent-template.json.d.ts +10 -0
  50. package/types/src/chart/templates/column-stacked-template.json.d.ts +10 -0
  51. package/types/src/chart/templates/column-template.json.d.ts +9 -0
  52. package/types/src/chart/templates/line-markers-template.json.d.ts +10 -0
  53. package/types/src/chart/templates/line-stacked-markers-template.json.d.ts +11 -0
  54. package/types/src/chart/templates/line-stacked-percent-markers-template.json.d.ts +11 -0
  55. package/types/src/chart/templates/line-stacked-percent-template.json.d.ts +10 -0
  56. package/types/src/chart/templates/line-stacked-template.json.d.ts +10 -0
  57. package/types/src/chart/templates/line-template.json.d.ts +9 -0
  58. package/types/src/chart/templates/pie-doughnut-template.json.d.ts +10 -0
  59. package/types/src/chart/templates/pie-template.json.d.ts +9 -0
  60. package/types/src/chart/templates/scatter-lines-markers-smooth-template.json.d.ts +10 -0
  61. package/types/src/chart/templates/scatter-lines-markers-template.json.d.ts +10 -0
  62. package/types/src/chart/templates/scatter-lines-smooth-template.json.d.ts +10 -0
  63. package/types/src/chart/templates/scatter-lines-template.json.d.ts +10 -0
  64. package/types/src/chart/templates/scatter-markers-template.json.d.ts +10 -0
  65. package/types/src/clipboard/ClipboardCommands.d.ts +68 -0
  66. package/types/src/clipboard/SheetClipboardLayer.d.ts +22 -0
  67. package/types/src/clipboard/index.d.ts +3 -0
  68. package/types/src/commands/Catalog.d.ts +8 -0
  69. package/types/src/commands/CommandRootProvider.d.ts +36 -0
  70. package/types/src/commands/InputClipboardCommands.d.ts +41 -0
  71. package/types/src/commands/InputClipboardInjector.d.ts +16 -0
  72. package/types/src/commands/MainFocusContext.d.ts +13 -0
  73. package/types/src/commands/PaneScopeProvider.d.ts +40 -0
  74. package/types/src/commands/createTransactionalMiddleware.d.ts +49 -0
  75. package/types/src/commands/index.d.ts +7 -0
  76. package/types/src/context/SheetContext.d.ts +18 -0
  77. package/types/src/context/WorkbookContext.d.ts +20 -0
  78. package/types/src/context/index.d.ts +3 -0
  79. package/types/src/editableLabel/EditableLabel.d.ts +28 -0
  80. package/types/src/editableLabel/index.d.ts +2 -0
  81. package/types/src/editor/EditorCommands.d.ts +98 -0
  82. package/types/src/editor/FunctionPreviewPanel.d.ts +166 -0
  83. package/types/src/editor/NamedHintPanel.d.ts +38 -0
  84. package/types/src/editor/NamedItemsPanel.d.ts +59 -0
  85. package/types/src/editor/SheetCellEditorLayer.d.ts +40 -0
  86. package/types/src/editor/SheetCellInput.d.ts +99 -0
  87. package/types/src/editor/SheetEditable.d.ts +53 -0
  88. package/types/src/editor/SheetReferenceHeaderLayer.d.ts +46 -0
  89. package/types/src/editor/SheetReferenceLayer.d.ts +55 -0
  90. package/types/src/editor/formulaCaret.d.ts +84 -0
  91. package/types/src/editor/formulaEval.d.ts +202 -0
  92. package/types/src/editor/formulaPresentation.d.ts +136 -0
  93. package/types/src/editor/formulaText.d.ts +80 -0
  94. package/types/src/editor/functionArgs.d.ts +111 -0
  95. package/types/src/editor/functionHint.d.ts +37 -0
  96. package/types/src/editor/index.d.ts +18 -0
  97. package/types/src/editor/referencePointNav.d.ts +39 -0
  98. package/types/src/editor/useFormulaHints.d.ts +126 -0
  99. package/types/src/editor/useFormulaInput.d.ts +326 -0
  100. package/types/src/editor/useProtectedEditNotice.d.ts +14 -0
  101. package/types/src/editor/useReferenceMode.d.ts +177 -0
  102. package/types/src/form/FormulaInput.d.ts +86 -0
  103. package/types/src/form/FormulaInputParts.d.ts +94 -0
  104. package/types/src/form/index.d.ts +5 -0
  105. package/types/src/form/useEditCommit.d.ts +174 -0
  106. package/types/src/form/useInputField.d.ts +86 -0
  107. package/types/src/frame/CommandContext.d.ts +179 -0
  108. package/types/src/frame/IFrame.d.ts +17 -0
  109. package/types/src/frame/index.d.ts +3 -0
  110. package/types/src/icons/LogoNoPaddingIcon.d.ts +3 -0
  111. package/types/src/icons/LogoTextNoPaddingIcon.d.ts +4 -0
  112. package/types/src/icons/WaterMark.d.ts +12 -0
  113. package/types/src/icons/chart/ChartAreaIcon.d.ts +5 -0
  114. package/types/src/icons/chart/ChartAreaStackedIcon.d.ts +5 -0
  115. package/types/src/icons/chart/ChartAreaStackedPercentIcon.d.ts +5 -0
  116. package/types/src/icons/chart/ChartBarIcon.d.ts +5 -0
  117. package/types/src/icons/chart/ChartBarStackedIcon.d.ts +5 -0
  118. package/types/src/icons/chart/ChartBarStackedPercentIcon.d.ts +5 -0
  119. package/types/src/icons/chart/ChartBubble3DIcon.d.ts +5 -0
  120. package/types/src/icons/chart/ChartBubbleIcon.d.ts +5 -0
  121. package/types/src/icons/chart/ChartColumnIcon.d.ts +5 -0
  122. package/types/src/icons/chart/ChartColumnStackedIcon.d.ts +5 -0
  123. package/types/src/icons/chart/ChartColumnStackedPercentIcon.d.ts +5 -0
  124. package/types/src/icons/chart/ChartLineIcon.d.ts +5 -0
  125. package/types/src/icons/chart/ChartLineMarkersIcon.d.ts +5 -0
  126. package/types/src/icons/chart/ChartLineStackedIcon.d.ts +5 -0
  127. package/types/src/icons/chart/ChartLineStackedMarkersIcon.d.ts +5 -0
  128. package/types/src/icons/chart/ChartLineStackedPercentIcon.d.ts +5 -0
  129. package/types/src/icons/chart/ChartLineStackedPercentMarkersIcon.d.ts +5 -0
  130. package/types/src/icons/chart/ChartPieDoughnutIcon.d.ts +5 -0
  131. package/types/src/icons/chart/ChartPieIcon.d.ts +5 -0
  132. package/types/src/icons/chart/ChartScatterLinesIcon.d.ts +5 -0
  133. package/types/src/icons/chart/ChartScatterLinesMarkersIcon.d.ts +5 -0
  134. package/types/src/icons/chart/ChartScatterLinesMarkersSmoothIcon.d.ts +5 -0
  135. package/types/src/icons/chart/ChartScatterLinesSmoothIcon.d.ts +5 -0
  136. package/types/src/icons/chart/ChartScatterMarkersIcon.d.ts +5 -0
  137. package/types/src/icons/chart/ChartWaterfallIcon.d.ts +5 -0
  138. package/types/src/icons/chart/ThemedChartIcon.d.ts +20 -0
  139. package/types/src/icons/chart/index.d.ts +50 -0
  140. package/types/src/icons/index.d.ts +4 -0
  141. package/types/src/index.d.ts +27 -0
  142. package/types/src/io/WorkbookIO.d.ts +50 -0
  143. package/types/src/io/index.d.ts +2 -0
  144. package/types/src/layer/BorderLayer.d.ts +14 -0
  145. package/types/src/layer/CellErrorLayer.d.ts +49 -0
  146. package/types/src/layer/CellFillLayer.d.ts +15 -0
  147. package/types/src/layer/ConditionalBarLayer.d.ts +41 -0
  148. package/types/src/layer/ConditionalIcons.d.ts +34 -0
  149. package/types/src/layer/ConditionalIconsLayer.d.ts +31 -0
  150. package/types/src/layer/ContextMenuLayer.d.ts +27 -0
  151. package/types/src/layer/HeaderResizerLayer.d.ts +28 -0
  152. package/types/src/layer/HeaderSelectionLayer.d.ts +89 -0
  153. package/types/src/layer/ResizeIndicator.d.ts +19 -0
  154. package/types/src/layer/SheetBackgroundLayer.d.ts +22 -0
  155. package/types/src/layer/SheetCellLayer.d.ts +49 -0
  156. package/types/src/layer/SheetColumnButtonLayer.d.ts +23 -0
  157. package/types/src/layer/SheetGridLineLayer.d.ts +22 -0
  158. package/types/src/layer/SheetHeaderCellLayer.d.ts +30 -0
  159. package/types/src/layer/SheetMovableLayer.d.ts +26 -0
  160. package/types/src/layer/SheetTableCommandLayer.d.ts +16 -0
  161. package/types/src/layer/SpillLayer.d.ts +22 -0
  162. package/types/src/layer/TableLayer.d.ts +22 -0
  163. package/types/src/layer/ValidationIndicatorLayer.d.ts +41 -0
  164. package/types/src/layer/index.d.ts +25 -0
  165. package/types/src/layer/resizeIndicatorState.d.ts +26 -0
  166. package/types/src/layer/useSheetFeatureRegions.d.ts +21 -0
  167. package/types/src/layer/useSheetVisibleCells.d.ts +60 -0
  168. package/types/src/layer/useSheetVisibleDecorations.d.ts +42 -0
  169. package/types/src/layer/useTableHeaderCells.d.ts +22 -0
  170. package/types/src/layer/useVisibleTables.d.ts +27 -0
  171. package/types/src/listener/index.d.ts +3 -0
  172. package/types/src/listener/useModelListener.d.ts +67 -0
  173. package/types/src/listener/useRangeListener.d.ts +15 -0
  174. package/types/src/movable/EmptyFrame.d.ts +16 -0
  175. package/types/src/movable/IMovableArea.d.ts +34 -0
  176. package/types/src/movable/MovableCommands.d.ts +22 -0
  177. package/types/src/movable/MovableFrame.d.ts +48 -0
  178. package/types/src/movable/MovableLayer.d.ts +77 -0
  179. package/types/src/movable/MoveableBundle.d.ts +4 -0
  180. package/types/src/movable/index.d.ts +4 -0
  181. package/types/src/picture/IPictureEditor.d.ts +39 -0
  182. package/types/src/picture/PictureEditor.d.ts +4 -0
  183. package/types/src/picture/index.d.ts +3 -0
  184. package/types/src/selection/SelectionCommands.d.ts +23 -0
  185. package/types/src/selection/SheetSelection.d.ts +53 -0
  186. package/types/src/selection/SheetSelectionLayer.d.ts +30 -0
  187. package/types/src/selection/index.d.ts +4 -0
  188. package/types/src/shape/ShapeEditor.d.ts +16 -0
  189. package/types/src/shape/index.d.ts +2 -0
  190. package/types/src/sheet/ConditionalFormatPresets.d.ts +56 -0
  191. package/types/src/sheet/ISheetElement.d.ts +233 -0
  192. package/types/src/sheet/ISheetHeaderElement.d.ts +138 -0
  193. package/types/src/sheet/NotImplemented.d.ts +3 -0
  194. package/types/src/sheet/SheetCommandProvider.d.ts +57 -0
  195. package/types/src/sheet/SheetCommands.d.ts +75 -0
  196. package/types/src/sheet/SheetElement.d.ts +15 -0
  197. package/types/src/sheet/SheetHeaderElement.d.ts +4 -0
  198. package/types/src/sheet/SheetScrollbar.d.ts +28 -0
  199. package/types/src/sheet/TopLeftCorner.d.ts +17 -0
  200. package/types/src/sheet/index.d.ts +7 -0
  201. package/types/src/slicer/SlicerEditor.d.ts +16 -0
  202. package/types/src/slicer/index.d.ts +2 -0
  203. package/types/src/tabStrip/SheetTab.d.ts +41 -0
  204. package/types/src/tabStrip/Sortable.d.ts +66 -0
  205. package/types/src/tabStrip/Tab.d.ts +19 -0
  206. package/types/src/tabStrip/TabStrip.d.ts +41 -0
  207. package/types/src/tabStrip/TabStripItem.d.ts +36 -0
  208. package/types/src/tabStrip/TabStripRow.d.ts +9 -0
  209. package/types/src/tabStrip/index.d.ts +7 -0
  210. package/types/src/table/TableCommands.d.ts +16 -0
  211. package/types/src/taskPane/ITaskPane.d.ts +72 -0
  212. package/types/src/taskPane/TaskPaneArea.d.ts +144 -0
  213. package/types/src/taskPane/TaskPaneFrame.d.ts +48 -0
  214. package/types/src/taskPane/TaskPaneRegistry.d.ts +108 -0
  215. package/types/src/taskPane/TaskPaneStrip.d.ts +33 -0
  216. package/types/src/taskPane/TaskPaneTitle.d.ts +24 -0
  217. package/types/src/taskPane/index.d.ts +7 -0
  218. package/types/src/taskPane/useTaskPane.d.ts +29 -0
  219. package/types/src/theme/DocThemesContext.d.ts +3 -0
  220. package/types/src/theme/DocThemesProvider.d.ts +15 -0
  221. package/types/src/theme/ThemeState.d.ts +19 -0
  222. package/types/src/theme/buildDocThemeCSS.d.ts +16 -0
  223. package/types/src/theme/buildOOXMLThemeCSS.d.ts +13 -0
  224. package/types/src/theme/createCSSSystemLookup.d.ts +51 -0
  225. package/types/src/theme/index.d.ts +11 -0
  226. package/types/src/theme/useAppColorScheme.d.ts +15 -0
  227. package/types/src/theme/useDocThemes.d.ts +3 -0
  228. package/types/src/theme/useGridColorScheme.d.ts +20 -0
  229. package/types/src/theme/useSystemColors.d.ts +44 -0
  230. package/types/src/undo/UndoCommands.d.ts +28 -0
  231. package/types/src/undo/UndoManagerContext.d.ts +14 -0
  232. package/types/src/undo/index.d.ts +3 -0
  233. package/types/src/workbook/DefaultRenderers.d.ts +14 -0
  234. package/types/src/workbook/GlobalWorkbookElement.d.ts +10 -0
  235. package/types/src/workbook/IWorkbookElement.d.ts +178 -0
  236. package/types/src/workbook/WindowChrome.d.ts +61 -0
  237. package/types/src/workbook/WorkbookCommandContributor.d.ts +24 -0
  238. package/types/src/workbook/WorkbookCommands.d.ts +97 -0
  239. package/types/src/workbook/WorkbookElement.d.ts +9 -0
  240. package/types/src/workbook/WorkbookStrip.d.ts +73 -0
  241. package/types/src/workbook/index.d.ts +17 -0
  242. package/types/src/workbook/resolveWorkbookInput.d.ts +27 -0
  243. package/types/src/workbook/useResolvedWorkbook.d.ts +31 -0
  244. package/types/src/workbook/useWindowChrome.d.ts +24 -0
  245. package/types/src/workbook/useWorkbookApp.d.ts +47 -0
  246. package/types/src/workbook/useWorkbookEncrypted.d.ts +15 -0
  247. package/types/src/workbook/useWorkbookFormat.d.ts +18 -0
  248. package/types/src/workbook/useWorkbookName.d.ts +13 -0
  249. package/types/src/workbook/useWorkbookSaveState.d.ts +29 -0
  250. package/browser/cjs/DNki9dGbSn_gUfd3.cjs +0 -7
  251. package/browser/cjs/Da611GSWMp5ncOGO.cjs +0 -16
  252. package/browser/cjs/F8ZECny0CwW2OV5X.cjs +0 -161
  253. package/browser/esm/BYGSBjns_83FWXAx.mjs +0 -3905
  254. package/browser/esm/CmObbQiLq9AAM7-q.mjs +0 -394
  255. package/browser/esm/Daa2g2QALCIHFgqP.mjs +0 -1377
  256. package/node/assets/style.css +0 -1
  257. 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