@sheetxl/react 0.8.0-beta.1 → 0.8.0-beta.10

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 (248) hide show
  1. package/browser/esm/BHjeSMaycUkS5dVL.mjs +66 -0
  2. package/browser/esm/BZcQ-KYwS62Ut45c.mjs +20 -0
  3. package/browser/esm/Bow9CzRJrYxak2i5.mjs +318 -0
  4. package/browser/esm/BuvXl14hs-1CvjeA.mjs +2706 -0
  5. package/browser/esm/BwRduT8FTrk5n72r.mjs +32 -0
  6. package/browser/esm/C6urN77szrYwODXF.mjs +134 -0
  7. package/browser/esm/CYMRbtPIr6SklGpp.mjs +775 -0
  8. package/browser/esm/CYoUd5KIl7W3AsxH.mjs +196 -0
  9. package/browser/esm/Cfe0kofqVKGxLqO6.mjs +31 -0
  10. package/browser/esm/CiRN-woJZWYOgTn4.mjs +36 -0
  11. package/browser/esm/Dd-ZybXAgoq9pgGv.mjs +45 -0
  12. package/browser/esm/DjiBz4H74I6nPUY6.mjs +79 -0
  13. package/browser/esm/DyU9UInRnfkPYYlR.mjs +63 -0
  14. package/browser/esm/J8cPagZBeXz86Lnd.mjs +777 -0
  15. package/browser/esm/Sp6PJavGKpF8SJzA.mjs +75 -0
  16. package/browser/esm/cYjYjqEsyd63x8t4.mjs +67 -0
  17. package/browser/esm/chart.mjs +60 -0
  18. package/browser/esm/control.mjs +216 -0
  19. package/browser/esm/group.mjs +123 -0
  20. package/browser/esm/index.mjs +14070 -9138
  21. package/browser/esm/note.mjs +86 -0
  22. package/browser/esm/picture.mjs +86 -0
  23. package/{node/esm/DAE_NG8D9uT50zUH.mjs → browser/esm/shape.mjs} +2 -4
  24. package/browser/esm/slicer.mjs +276 -0
  25. package/licenses/dependencies.txt +6 -599
  26. package/node/esm/BJ7ZZm63j5O6cvrB.mjs +134 -0
  27. package/node/esm/BfRn5S5V4X8xIAEa.mjs +20 -0
  28. package/node/esm/BpwE3HqTnrLLzE3C.mjs +775 -0
  29. package/node/esm/Buw-VKYJy3y5dbaJ.mjs +197 -0
  30. package/node/esm/CFFlJxNwgyInjEnh.mjs +45 -0
  31. package/node/esm/CM5BT7h-hMtST2bE.mjs +2706 -0
  32. package/node/esm/CV3bT3Hql74GcHoU.mjs +37 -0
  33. package/node/esm/C_ANM4feA1xV-pri.mjs +32 -0
  34. package/node/esm/D3YXHeOyFp00Xk3m.mjs +323 -0
  35. package/node/esm/DPN0n6MGYQ9vZ2KO.mjs +80 -0
  36. package/node/esm/DYosMUJKp-3MSO4q.mjs +76 -0
  37. package/node/esm/DhSq680c5tgMFFbj.mjs +68 -0
  38. package/node/esm/Dxbm6ryIDCEi26RO.mjs +66 -0
  39. package/node/esm/GkmuxU7OwRZtm2Rf.mjs +63 -0
  40. package/node/esm/chart.mjs +60 -0
  41. package/node/esm/control.mjs +216 -0
  42. package/node/esm/group.mjs +123 -0
  43. package/node/esm/index.mjs +16618 -11534
  44. package/node/esm/note.mjs +87 -0
  45. package/node/esm/picture.mjs +86 -0
  46. package/node/esm/shape.mjs +783 -0
  47. package/node/esm/slicer.mjs +278 -0
  48. package/package.json +53 -14
  49. package/resources/contents.json +18 -0
  50. package/resources/locales/contents.json +42 -0
  51. package/resources/locales/de/movable.cmd.json +154 -0
  52. package/resources/locales/de/picture.cmd.json +31 -0
  53. package/resources/locales/de/selection.cmd.json +8 -0
  54. package/resources/locales/de/shape.cmd.json +17 -0
  55. package/resources/locales/de/sheet.cmd.json +328 -21
  56. package/resources/locales/de/slicer.cmd.json +17 -0
  57. package/resources/locales/de/table.cmd.json +9 -1
  58. package/resources/locales/de/ui.msg.json +309 -3
  59. package/resources/locales/de/workbook.cmd.json +10 -6
  60. package/resources/locales/en/movable.cmd.json +154 -0
  61. package/resources/locales/en/picture.cmd.json +31 -0
  62. package/resources/locales/en/selection.cmd.json +8 -0
  63. package/resources/locales/en/shape.cmd.json +17 -0
  64. package/resources/locales/en/sheet.cmd.json +342 -22
  65. package/resources/locales/en/slicer.cmd.json +17 -0
  66. package/resources/locales/en/table.cmd.json +9 -1
  67. package/resources/locales/en/ui.msg.json +309 -3
  68. package/resources/locales/en/workbook.cmd.json +11 -7
  69. package/types/chart.d.ts +2 -0
  70. package/types/control.d.ts +2 -0
  71. package/types/group.d.ts +2 -0
  72. package/types/note.d.ts +2 -0
  73. package/types/picture.d.ts +2 -0
  74. package/types/shape.d.ts +2 -0
  75. package/types/slicer.d.ts +2 -0
  76. package/types/src/annotation/RangeAnnotations.d.ts +119 -0
  77. package/types/src/annotation/index.d.ts +2 -0
  78. package/types/src/autoFill/AutoFillPresets.d.ts +14 -0
  79. package/types/src/autoFill/FillMenu.d.ts +36 -0
  80. package/types/src/autoFill/FillSeries.d.ts +38 -0
  81. package/types/src/autoFill/index.d.ts +4 -0
  82. package/types/src/border/StaticBorderRenderer.d.ts +2 -2
  83. package/types/src/border/useBorders.d.ts +7 -7
  84. package/types/src/cell/CornerTriangle.d.ts +6 -0
  85. package/types/src/cell/FormulaCellRenderer.d.ts +1 -1
  86. package/types/src/cell/OutlineButton.d.ts +123 -0
  87. package/types/src/cell/SheetCellRenderer.d.ts +2 -2
  88. package/types/src/cell/SheetHeaderRenderer.d.ts +5 -0
  89. package/types/src/cell/StaticCellRenderer.d.ts +57 -0
  90. package/types/src/cell/index.d.ts +2 -0
  91. package/types/src/cell/useFormulaViewAnchor.d.ts +1 -1
  92. package/types/src/chart/index.d.ts +0 -1
  93. package/types/src/checklist/ValueChecklist.d.ts +112 -0
  94. package/types/src/checklist/index.d.ts +2 -0
  95. package/types/src/commands/ContextualToolbar.d.ts +19 -0
  96. package/types/src/commands/createTransactionalMiddleware.d.ts +4 -1
  97. package/types/src/commands/index.d.ts +1 -0
  98. package/types/src/comment/CommentCardRequest.d.ts +94 -0
  99. package/types/src/comment/CommentUtils.d.ts +43 -0
  100. package/types/src/comment/NoteEditor.d.ts +20 -0
  101. package/types/src/comment/index.d.ts +5 -0
  102. package/types/src/comment/useCommentThread.d.ts +37 -0
  103. package/types/src/comment/useSheetComments.d.ts +28 -0
  104. package/types/src/{sheet → conditionalFormat}/ConditionalFormatPresets.d.ts +6 -6
  105. package/types/src/conditionalFormat/index.d.ts +1 -0
  106. package/types/src/control/FormControlRenderers.d.ts +22 -0
  107. package/types/src/editor/FunctionPreviewPanel.d.ts +15 -1
  108. package/types/src/editor/NamedItemLabel.d.ts +29 -0
  109. package/types/src/editor/NamedItemsPanel.d.ts +13 -2
  110. package/types/src/editor/SheetCellEditorLayer.d.ts +3 -7
  111. package/types/src/editor/SheetCellEditorStartLayer.d.ts +44 -0
  112. package/types/src/editor/SheetCellInput.d.ts +26 -2
  113. package/types/src/editor/SheetEditable.d.ts +8 -2
  114. package/types/src/editor/formulaCaret.d.ts +39 -10
  115. package/types/src/editor/formulaEval.d.ts +9 -5
  116. package/types/src/editor/formulaLint.d.ts +36 -0
  117. package/types/src/editor/formulaPresentation.d.ts +7 -0
  118. package/types/src/editor/formulaText.d.ts +17 -5
  119. package/types/src/editor/functionArgs.d.ts +20 -0
  120. package/types/src/editor/index.d.ts +4 -1
  121. package/types/src/editor/pickedReference.d.ts +76 -0
  122. package/types/src/editor/useEditRejectedNotice.d.ts +32 -0
  123. package/types/src/editor/useFormulaHints.d.ts +93 -3
  124. package/types/src/editor/useFormulaInput.d.ts +30 -4
  125. package/types/src/editor/useReferenceMode.d.ts +12 -0
  126. package/types/src/editor/validationAlert.d.ts +24 -0
  127. package/types/src/externalLink/ExternalLinksPaneArgs.d.ts +23 -0
  128. package/types/src/externalLink/index.d.ts +2 -0
  129. package/types/src/form/FormulaInput.d.ts +18 -2
  130. package/types/src/form/FormulaInputParts.d.ts +10 -1
  131. package/types/src/form/useEditCommit.d.ts +23 -3
  132. package/types/src/form/useInputField.d.ts +2 -3
  133. package/types/src/frame/CommandContext.d.ts +188 -6
  134. package/types/src/group/GroupEditor.d.ts +25 -0
  135. package/types/src/index.d.ts +12 -2
  136. package/types/src/io/WorkbookIO.d.ts +2 -0
  137. package/types/src/layer/CellErrorLayer.d.ts +24 -7
  138. package/types/src/layer/CommentCardLayer.d.ts +43 -0
  139. package/types/src/layer/CommentsLayer.d.ts +35 -0
  140. package/types/src/layer/ConditionalIcons.d.ts +4 -4
  141. package/types/src/layer/FreezeDragLines.d.ts +17 -0
  142. package/types/src/layer/GridFreezeLayer.d.ts +11 -0
  143. package/types/src/layer/HeaderFreezeLayer.d.ts +12 -0
  144. package/types/src/layer/HeaderResizerLayer.d.ts +2 -1
  145. package/types/src/layer/HyperlinkLayer.d.ts +109 -0
  146. package/types/src/layer/MovableKindScope.d.ts +17 -0
  147. package/types/src/layer/ProtectionLayer.d.ts +52 -0
  148. package/types/src/layer/RangeAnnotationLayer.d.ts +71 -0
  149. package/types/src/layer/ResizeIndicator.d.ts +9 -8
  150. package/types/src/layer/ResizeTooltip.d.ts +13 -0
  151. package/types/src/layer/SheetHeaderCellLayer.d.ts +10 -1
  152. package/types/src/layer/SheetOutlineLayer.d.ts +40 -0
  153. package/types/src/layer/TableLayer.d.ts +5 -4
  154. package/types/src/layer/TableToolbar.d.ts +42 -0
  155. package/types/src/layer/ValidationDropdownLayer.d.ts +15 -5
  156. package/types/src/layer/ValidationIndicatorLayer.d.ts +9 -3
  157. package/types/src/layer/ValidationPromptLayer.d.ts +64 -0
  158. package/types/src/layer/_tableColor.d.ts +4 -0
  159. package/types/src/layer/cellTip.d.ts +13 -0
  160. package/types/src/layer/freezeDragState.d.ts +21 -0
  161. package/types/src/layer/index.d.ts +12 -1
  162. package/types/src/layer/resizeIndicatorState.d.ts +3 -1
  163. package/types/src/layer/useFreezeDrag.d.ts +22 -0
  164. package/types/src/layer/useValidationPicker.d.ts +35 -35
  165. package/types/src/layer/validationMark.d.ts +63 -0
  166. package/types/src/listener/useModelListener.d.ts +4 -4
  167. package/types/src/movable/ConnectionSites.d.ts +18 -0
  168. package/types/src/movable/IMovableArea.d.ts +56 -0
  169. package/types/src/movable/MovableAdornment.d.ts +26 -0
  170. package/types/src/movable/MovableCommandGroups.d.ts +40 -0
  171. package/types/src/movable/MovableCommands.d.ts +6 -1
  172. package/types/src/movable/MovableControl.d.ts +78 -0
  173. package/types/src/movable/MovableEdit.d.ts +22 -0
  174. package/types/src/movable/MovableFrame.d.ts +16 -13
  175. package/types/src/movable/MovableLayer.d.ts +25 -7
  176. package/types/src/movable/MovableRenderers.d.ts +210 -0
  177. package/types/src/movable/PlaceholderFrames.d.ts +11 -0
  178. package/types/src/movable/RotateHandle.d.ts +37 -0
  179. package/types/src/movable/TextBox.d.ts +34 -0
  180. package/types/src/movable/connect.d.ts +16 -0
  181. package/types/src/movable/framePlacement.d.ts +72 -0
  182. package/types/src/movable/geometry.d.ts +61 -0
  183. package/types/src/movable/index.d.ts +10 -0
  184. package/types/src/movable/pressTarget.d.ts +20 -0
  185. package/types/src/picker/PickerPanel.d.ts +52 -0
  186. package/types/src/picker/cellPickerOpen.d.ts +6 -0
  187. package/types/src/picker/index.d.ts +4 -0
  188. package/types/src/picker/useCellPicker.d.ts +95 -0
  189. package/types/src/picture/PictureCommands.d.ts +12 -0
  190. package/types/src/picture/PictureKind.d.ts +7 -0
  191. package/types/src/picture/index.d.ts +0 -1
  192. package/types/src/protection/ProtectionPaneArgs.d.ts +31 -0
  193. package/types/src/protection/index.d.ts +3 -0
  194. package/types/src/protection/unlockProtectedRanges.d.ts +23 -0
  195. package/types/src/richText/RichTextEditor.d.ts +41 -0
  196. package/types/src/richText/index.d.ts +2 -0
  197. package/types/src/selection/SheetSelectionLayer.d.ts +14 -10
  198. package/types/src/shape/ConnectorControl.d.ts +46 -0
  199. package/types/src/shape/ShapeCommands.d.ts +11 -0
  200. package/types/src/shape/ShapeControl.d.ts +8 -0
  201. package/types/src/shape/ShapeEditor.d.ts +15 -2
  202. package/types/src/shape/ShapeGallery.d.ts +31 -0
  203. package/types/src/shape/ShapeHandles.d.ts +28 -0
  204. package/types/src/shape/ShapeKind.d.ts +7 -0
  205. package/types/src/shape/ShapeSVG.d.ts +22 -0
  206. package/types/src/shape/ShapeText.d.ts +17 -0
  207. package/types/src/shape/icons/ShapeIcons.d.ts +16 -0
  208. package/types/src/shape/icons/_ShapeIconPack.d.ts +4 -0
  209. package/types/src/shape/index.d.ts +3 -1
  210. package/types/src/shape/shapeFrame.d.ts +50 -0
  211. package/types/src/shape/shapeStyle.d.ts +82 -0
  212. package/types/src/sheet/ISheetElement.d.ts +62 -65
  213. package/types/src/sheet/SheetCommandProvider.d.ts +9 -4
  214. package/types/src/sheet/SheetCommands.d.ts +21 -6
  215. package/types/src/sheet/SheetOutlineElement.d.ts +70 -0
  216. package/types/src/sheet/SheetScrollbar.d.ts +1 -10
  217. package/types/src/sheet/_freezeAt.d.ts +10 -0
  218. package/types/src/sheet/_useHeaderMetrics.d.ts +11 -0
  219. package/types/src/sheet/circularReferences.d.ts +9 -1
  220. package/types/src/sheet/index.d.ts +1 -1
  221. package/types/src/sheet/useCycleHighlight.d.ts +21 -0
  222. package/types/src/slicer/SlicerCommands.d.ts +10 -0
  223. package/types/src/slicer/SlicerEditor.d.ts +8 -2
  224. package/types/src/slicer/SlicerKind.d.ts +7 -0
  225. package/types/src/slicer/SlicerStylePreview.d.ts +18 -0
  226. package/types/src/slicer/index.d.ts +2 -1
  227. package/types/src/slicer/slicerStyles.d.ts +32 -0
  228. package/types/src/tabStrip/TabStrip.d.ts +7 -0
  229. package/types/src/taskPane/ITaskPane.d.ts +12 -1
  230. package/types/src/taskPane/MovablePane.d.ts +17 -0
  231. package/types/src/taskPane/index.d.ts +1 -0
  232. package/types/src/theme/ThemeState.d.ts +14 -1
  233. package/types/src/theme/useGridColorScheme.d.ts +1 -1
  234. package/types/src/workbook/DefaultMovableRenderers.d.ts +20 -0
  235. package/types/src/workbook/IWorkbookElement.d.ts +24 -0
  236. package/types/src/workbook/WorkbookCommands.d.ts +2 -4
  237. package/types/src/workbook/WorkbookStrip.d.ts +9 -0
  238. package/types/src/workbook/_followOrigin.d.ts +9 -0
  239. package/types/src/workbook/useWorkbookFormat.d.ts +3 -3
  240. package/browser/cjs/Bo9Kx3L_XQkGPBJ5.cjs +0 -1
  241. package/browser/cjs/Pl04-kDEQSO8_qFU.cjs +0 -156
  242. package/browser/cjs/index.cjs +0 -35
  243. package/browser/esm/SJMJzBwlXTJ9QIO5.mjs +0 -6286
  244. package/types/src/editor/useProtectedEditNotice.d.ts +0 -14
  245. package/types/src/layer/validationList.d.ts +0 -84
  246. package/types/src/list/SheetValueList.d.ts +0 -93
  247. package/types/src/list/index.d.ts +0 -2
  248. package/types/src/movable/MoveableBundle.d.ts +0 -4
@@ -34,14 +34,14 @@ export declare const isFormulaText: (value: string) => boolean;
34
34
  export declare const formulaPrefixLen: (value: string) => number;
35
35
  /**
36
36
  * Syntax color for a formula token, or `undefined` to inherit the cell's font color (operators, parens,
37
- * separators, whitespace). Reference-literal tokens (`token.isReference` — cells AND the range operators
38
- * that bind them, e.g. `:`) rotate through `PICKER_COLORS` by `referenceIndex`, so co-referenced ranges
37
+ * separators, whitespace). Reference-literal tokens (those carrying a `referenceIndex` — cells AND the
38
+ * range operators that bind them, e.g. `:`) rotate through `PICKER_COLORS` by that index, so co-referenced ranges
39
39
  * share a hue — LITERALLY the same color expressions the range picker draws its rectangles with, so text
40
40
  * and on-grid rectangle always match, both follow light/dark for free, AND a field OUTSIDE any themed
41
41
  * workbook surface (a standalone dialog/panel — no `--sxl-color-series-*` definitions in scope) still
42
42
  * colors through the palette's built-in literal fallbacks. (A bare `var()` with no fallback computes to
43
43
  * *nothing* there — references silently rendered in the plain text color.) Keying off the SDK's
44
- * `isReference` (not a hardcoded type list) keeps the whole span, operators included, one color while a
44
+ * `referenceIndex` (not a hardcoded type list) keeps the whole span, operators included, one color while a
45
45
  * function that merely returns a reference stays function-colored.
46
46
  */
47
47
  export declare const tokenColor: (token: ICalculation.FormulaToken) => string | undefined;
@@ -61,6 +61,18 @@ export declare const referenceSpan: (tokens: readonly ICalculation.FormulaToken[
61
61
  start: number;
62
62
  end: number;
63
63
  } | null;
64
+ /**
65
+ * Whether reference `refIndex` is written as a STRUCTURED reference (`Sales[Amount]`, `Sales[@Qty]`,
66
+ * or the bare table name) rather than an address.
67
+ *
68
+ * @remarks
69
+ * Read off the tokens, because the resolved coords cannot tell: a structured reference resolves to
70
+ * the region it names with every `$` flag set — the absolute form a table-to-range conversion wants,
71
+ * and exactly what a picker must NOT carry over. A structured reference has no `$` form of its own
72
+ * (which is also why F4 does nothing on one), so a pick that moves it off the table starts from the
73
+ * relative default instead of inheriting `$`s the user never wrote.
74
+ */
75
+ export declare const isStructuredReference: (tokens: readonly ICalculation.FormulaToken[], refIndex: number) => boolean;
64
76
  /**
65
77
  * F4 — cycle `$` (relative ⇄ absolute) on the reference under the caret, as a PURE text rewrite.
66
78
  * Tokenizes `value` (a formula string — `=`/`+`/`-` lead), reads the caret cell token's `refSide`
@@ -73,8 +85,8 @@ export declare const referenceSpan: (tokens: readonly ICalculation.FormulaToken[
73
85
  * Shared by the cell editor's caret handle (`SheetCellInput`) and the reference field
74
86
  * (`useFormulaInput`'s reference grammar, which runs it per comma-segment) so F4 behaves identically in both.
75
87
  */
76
- export declare const toggleReferenceInFormula: (calc: ICalculation, value: string, caret: number, home?: Partial<IRange.CellCoords>) => {
88
+ export declare const toggleReferenceInFormula: (calc: ICalculation, value: string, caret: number, home?: Partial<IRange.CellCoords>) => Promise<{
77
89
  value: string;
78
90
  caret: number;
79
- } | null;
91
+ } | null>;
80
92
  //# sourceMappingURL=formulaText.d.ts.map
@@ -75,6 +75,26 @@ export interface ArgRow {
75
75
  * shape today (every repeating group is the last parameter).
76
76
  */
77
77
  export declare const toArgRows: (params: readonly IFunction.IParameterType[], filled?: readonly string[]) => ArgRow[];
78
+ /** One argument of a call: the function, and the declared parameter the argument fills. */
79
+ export interface FormulaArgument {
80
+ /** The function called. */
81
+ fn: IFunction;
82
+ /** The declared parameter the argument fills — a group's SLOT (see {@link paramAtArg}), not the group. */
83
+ param: IFunction.IParameterType;
84
+ }
85
+ /**
86
+ * The declared parameter that the argument at `argIndex` fills, walking the parameters as a call
87
+ * spells them out: a plain parameter is one position, and a rest parameter or repeating group cycles
88
+ * through its slots from where it starts.
89
+ *
90
+ * @returns `null` for a negative index, or one past the last parameter of a declaration with no rest
91
+ * parameter or group.
92
+ *
93
+ * @remarks
94
+ * A parameter declared AFTER a group (`SWITCH`'s `default`) is never the answer: a position alone
95
+ * cannot say where the repetitions end, so the group keeps it — as the signature does.
96
+ */
97
+ export declare const paramAtArg: (params: readonly IFunction.IParameterType[], argIndex: number) => IFunction.IParameterType | null;
78
98
  /** Options for {@link assembleCall}. */
79
99
  export interface AssembleCallOptions {
80
100
  /**
@@ -1,4 +1,5 @@
1
1
  export * from './SheetEditable';
2
+ export * from './validationAlert';
2
3
  export * from './formulaText';
3
4
  export * from './formulaEval';
4
5
  export * from './useReferenceMode';
@@ -9,10 +10,12 @@ export * from './FunctionPreviewPanel';
9
10
  export * from './functionHint';
10
11
  export * from './functionArgs';
11
12
  export * from './NamedItemsPanel';
13
+ export * from './NamedItemLabel';
12
14
  export * from './NamedHintPanel';
13
15
  export * from './EditorCommands';
14
- export * from './useProtectedEditNotice';
16
+ export * from './useEditRejectedNotice';
15
17
  export * from './SheetCellEditorLayer';
18
+ export * from './SheetCellEditorStartLayer';
16
19
  export * from './SheetReferenceLayer';
17
20
  export * from './SheetReferenceHeaderLayer';
18
21
  //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1,76 @@
1
+ import { RangeCoords } from '@sheetxl/utils';
2
+ import { ICalculation, ICell, IRange, ISheet } from '@sheetxl/sdk';
3
+ /**
4
+ * The text a range picked on the grid writes into a formula edited at `cell` — shared by the cell
5
+ * editor's two picker write-backs (re-scope and insert) so a pick writes the same text however it
6
+ * was made. Precedence is Excel's: a name, then a spill, then an address.
7
+ */
8
+ /**
9
+ * The address text for a picked range, as it must appear **in the formula**.
10
+ *
11
+ * @remarks
12
+ * Bare (`A1:B2`) when the range lives on the edited cell's OWN sheet — Excel writes same-sheet references
13
+ * unqualified — and sheet-qualified (`Sheet2!A1:B2`) when it does not. The qualification is driven by the
14
+ * range's `scope`, which is the only thing that distinguishes "row 1, col 1 of the sheet I'm editing" from
15
+ * "row 1, col 1 of the sheet I picked on": without it a cross-sheet pick serializes bare and silently
16
+ * re-reads as a reference to the edited sheet. The sheet name is quoted by the SDK (`'My Sheet'!A1`).
17
+ */
18
+ export declare const scopedAddress: (cell: ICell, coords: IRange.Coords | IRange.FixableCoords, scope?: string | null) => string;
19
+ /**
20
+ * The NAME a picked range exactly is — `Sales`, `Sales[Amount]`, `Sales[[#All],[Amount]]` — or `null`
21
+ * when it is not any named thing.
22
+ *
23
+ * @remarks
24
+ * Excel writes structured references when you point inside a table, and names for a range that is
25
+ * one; this is that. Asked of the edited cell's SHEET (so only names a formula there can refer to are
26
+ * offered, and unqualified coords read on the right sheet), and always exact — a selection *inside*
27
+ * `Sales` is not `Sales`, so a partial pick still writes an address.
28
+ *
29
+ * Reference-index alignment is safe by construction rather than by a guard: a match has to coincide
30
+ * with the picked range, and the picked range is a single rectangle, so a multi-range name can never
31
+ * match one — the substituted text always holds exactly the one reference the address held.
32
+ *
33
+ * `$` flags are deliberately not carried: a name has no absolute/relative form to preserve, which is
34
+ * also why F4 does nothing on one (matching Excel).
35
+ */
36
+ export declare const namedReference: (cell: ICell, to: RangeCoords) => string | null;
37
+ /**
38
+ * Whether `range` is exactly a dynamic array's spill, so a pick of it can be written `D2#`.
39
+ *
40
+ * @remarks
41
+ * Not a single cell (a 1×1 spill is its anchor's address), an array-entered block or a blocked spill.
42
+ *
43
+ * @param sheet Any sheet of the workbook — resolves `range.scope` (its own sheet when unscoped).
44
+ */
45
+ export declare const isSpillExtent: (sheet: ISheet, range: RangeCoords) => boolean;
46
+ /**
47
+ * The spill reference (`D2#`) a picked range exactly is, or `null`.
48
+ *
49
+ * @remarks
50
+ * Only a dynamic array's spill: a legacy array-entered block (`fixed`) and a blocked spill (`error`)
51
+ * have no `#` form. A single cell is never one — a 1×1 spill is just its anchor's address. Exact, like
52
+ * {@link namedReference}: the pick must coincide with the whole extent, so its top-left is the anchor.
53
+ *
54
+ * The extent is computed state, so this matches the last calculation — which is also what the user
55
+ * sees on the grid while picking. {@link expandSpillAnchors} is the reverse.
56
+ *
57
+ * @param flags The `$` style to give the anchor, from its start corner (a re-scope keeps the
58
+ * reference's original style, as it does for an address).
59
+ */
60
+ export declare const spillReference: (cell: ICell, to: RangeCoords, flags?: IRange.FixableCoords) => string | null;
61
+ /**
62
+ * The highlight ranges of a parsed formula with every spill reference (`C1#`) widened from its anchor
63
+ * to the extent it reads.
64
+ *
65
+ * @remarks
66
+ * A formula's references report a spill reference as its anchor cell, so without this `C1#` lights up
67
+ * one cell, and a drag of the picked extent (which writes `C1#`) snaps back to it. Any live block
68
+ * widens, array-entered ones included, since `J1#` reads those too; an anchor with no block stays as
69
+ * it is (it evaluates `#REF!`).
70
+ *
71
+ * @param sheet Any sheet of the workbook — resolves each range's scope.
72
+ * @param tokens The formula's tokens; the `#` anchor token carries its reference's `referenceIndex`.
73
+ * @param ranges Index-aligned with `referenceIndex`. Returned as-is when nothing widens.
74
+ */
75
+ export declare const expandSpillAnchors: (sheet: ISheet, tokens: readonly ICalculation.FormulaToken[], ranges: (RangeCoords | null)[]) => (RangeCoords | null)[];
76
+ //# sourceMappingURL=pickedReference.d.ts.map
@@ -0,0 +1,32 @@
1
+ import { CellCoords } from '@sheetxl/utils';
2
+ import { ISheet } from '@sheetxl/sdk';
3
+ /**
4
+ * The callback a host invokes on each rejected edit attempt.
5
+ *
6
+ * @param coords The cell it tried to edit.
7
+ * @param retry Re-attempts the same edit. Invoked when the notice was able to clear the reason —
8
+ * the user unlocked a password-gated range — so the edit they asked for opens after all.
9
+ */
10
+ export type EditRejectedNotice = (coords?: CellCoords | null, retry?: () => void) => void;
11
+ /**
12
+ * The heads-up for a rejected edit attempt (`IEditable.startEdit` returning `false`). Returns the
13
+ * callback a host invokes on each rejection, with the cell it tried to edit. Three reasons are told
14
+ * apart:
15
+ *
16
+ * - **A password-gated unlocked range** — Excel's "Unlock Range": the password is asked for right
17
+ * there, and on a match the edit is re-attempted (`retry`), so typing into the cell is the way to
18
+ * unlock it. Shown every time, since each refusal is a concrete action to answer.
19
+ * - **Protected sheet** — Excel-style, shown once per **visit** to `sheet` (Excel re-warns each time
20
+ * you come (back) to a tab, so the once-flag resets on a `sheet` identity change and naturally on
21
+ * remount).
22
+ * - **Part of an array-entered block** — "You can't change part of an array", shown every time: the
23
+ * edit opens only when the whole block is selected.
24
+ *
25
+ * Any other non-editable reason stays silent.
26
+ *
27
+ * One instance should serve one visit scope — `SheetElement` creates it and threads the callback to
28
+ * every consumer it hosts (its imperative `startEdit` and each pane's editor layer), so four frozen
29
+ * panes never warn four times.
30
+ */
31
+ export declare const useEditRejectedNotice: (sheet: ISheet) => EditRejectedNotice;
32
+ //# sourceMappingURL=useEditRejectedNotice.d.ts.map
@@ -1,6 +1,8 @@
1
1
  import { default as React } from 'react';
2
- import { ICalculation, INamedCollection } from '@sheetxl/sdk';
2
+ import { ICalculation, ICell, IFunction, INamedCollection } from '@sheetxl/sdk';
3
3
  import { NamedItem } from './NamedItemsPanel';
4
+ import { FunctionCaretContext } from './formulaCaret';
5
+ import { FormulaArgument } from './functionArgs';
4
6
  /**
5
7
  * The autocomplete rows for a typed `prefix` — the whole list, from all three sources, in the order
6
8
  * they are shown.
@@ -18,7 +20,10 @@ import { NamedItem } from './NamedItemsPanel';
18
20
  * Pass the SHEET's (`ISheet.getNames()`), which already holds exactly what a formula written there
19
21
  * can refer to, shadowing resolved — the workbook's would offer other sheets' private names.
20
22
  * Deliberately NOT localized: a defined name is the user's own text, spelled the same in every
21
- * language.
23
+ * language. A name whose body is `LAMBDA(…)` is offered as `'lambda'`, completed like a function.
24
+ * - **`LET` / `LAMBDA` names** — `bound`, the names in scope at the caret (the caret token's
25
+ * `FormulaTokenContext.bound`). One
26
+ * shadows a defined name or table spelled the same, as it does when the formula binds.
22
27
  *
23
28
  * A name colliding with a FUNCTION name is pathological but possible; the function wins, because that
24
29
  * is what the compiler binds a bare identifier to — completing to the name would insert text that
@@ -26,7 +31,74 @@ import { NamedItem } from './NamedItemsPanel';
26
31
  *
27
32
  * Pure and total: either source failing costs only its own rows, never the list.
28
33
  */
29
- export declare const buildMatches: (calc: ICalculation, prefix: string, names: INamedCollection | null) => NamedItem[];
34
+ export declare const buildMatches: (calc: ICalculation, prefix: string, names: INamedCollection | null, bound?: readonly ICalculation.BoundName[]) => NamedItem[];
35
+ /** A `LET` name's lambda — {@link ICalculation.BoundName.params} with its parameters. */
36
+ type BoundLambda = ICalculation.BoundName & Required<Pick<ICalculation.BoundName, 'params'>>;
37
+ /**
38
+ * Whose signature a call at the caret shows, resolved as the binder resolves the call: a built-in
39
+ * function wins outright, then a `LET` / `LAMBDA` name in scope, then a named lambda.
40
+ *
41
+ * @returns `null` when nothing describes the call — an unknown name, or a name in scope that is not
42
+ * bound to a literal `LAMBDA` (the call applies that name, whose parameters are unknown).
43
+ */
44
+ export declare const resolveCallTarget: (calc: ICalculation, ctx: FunctionCaretContext) => {
45
+ fn: IFunction;
46
+ } | {
47
+ bound: BoundLambda;
48
+ } | null;
49
+ /**
50
+ * An `'enum'` row, carrying which member it is, so its label can follow the function's descriptor
51
+ * once that arrives.
52
+ */
53
+ export type EnumMatch = NamedItem & {
54
+ enumOf: {
55
+ fn: string;
56
+ id: string;
57
+ member: string;
58
+ };
59
+ };
60
+ /**
61
+ * The rows for an EMPTY argument whose parameter is limited to an enum (`SUBTOTAL(` → `AVERAGE 1`,
62
+ * `COUNT 2`, …), in declaration order, or `[]` when the caret is anywhere else.
63
+ *
64
+ * The rows themselves are {@link buildParamEnumMatches}'s. Only an empty argument offers the list: once
65
+ * anything is typed there — a reference, an expression, a literal — the argument is the user's, which
66
+ * is always legal in the slot.
67
+ */
68
+ export declare const buildEnumMatches: (calc: ICalculation, tokens: readonly ICalculation.FormulaToken[], caret: number, base: number, locale: string | null) => EnumMatch[];
69
+ /**
70
+ * One row per value `param` of `fn` offers, in declaration order — `[]` for a parameter with no
71
+ * enum. A `@deprecated` member is in the set but not offered.
72
+ *
73
+ * A row reads as its member's name, then the literal accepting it inserts (`detail` and `insert`) —
74
+ * in the workbook `locale`'s decimal, and a string quoted. An unnamed union's members are named by
75
+ * their values, so theirs is the literal alone. The localized label and the member's description
76
+ * come from the function's descriptor (`getEnums()`), which the hook applies when it arrives.
77
+ */
78
+ export declare const buildParamEnumMatches: (fn: IFunction, param: IFunction.IParameterType, locale: string | null) => EnumMatch[];
79
+ /** Where a table's parts are being typed — see {@link buildTableMatches}. */
80
+ export interface TablePartSite {
81
+ /** The cell the formula is written in, when there is one. */
82
+ home?: ICell | null;
83
+ /** The part is an item of a bracketed list (`Sales[[#Headers],[Co`), where `@` is not written. */
84
+ nested?: boolean;
85
+ }
86
+ /**
87
+ * The autocomplete rows inside a table's brackets (`Sales[Co`), in Excel's order: this row first, then
88
+ * the table's columns in table order, then the section specifiers `#All`, `#Data`, `#Headers`,
89
+ * `#Totals`. Each row's `detail` is the region it designates.
90
+ *
91
+ * - `part` is the unfinished part's token value: its `table` is found by name in `names` (the sheet's
92
+ * collection, as for {@link buildMatches}), and its `partial` says whether columns, specifiers or both
93
+ * may finish it. An unqualified reference (`table` `''`) or an unknown table offers nothing.
94
+ * - This row is `@ - This Row` and inserts `@`, as Excel offers it; in a bracketed list, where `@`
95
+ * cannot stand, it is `#This Row`.
96
+ * - A formula inside the table (`site.home`) is offered no section but this row.
97
+ * - Specifiers are spelled in the active language and match on that spelling or the canonical English
98
+ * one.
99
+ * - Matching is a case-insensitive prefix match on what was typed.
100
+ */
101
+ export declare const buildTableMatches: (prefix: string, names: INamedCollection | null, part: ICalculation.TablePartRef, site?: TablePartSite) => NamedItem[];
30
102
  /**
31
103
  * Start offset (after the leading prefix — `base`) of the INNERMOST function call that is still OPEN at
32
104
  * `caret` — the offset of that call's *name token* — or `null` when the caret isn't inside an open call.
@@ -71,6 +143,12 @@ export interface UseFormulaHintsOptions {
71
143
  * offer another sheet's private names, which complete to expressions that do not resolve.
72
144
  */
73
145
  getNames?(): INamedCollection | null;
146
+ /**
147
+ * The cell the formula is written in. Inside a table's brackets it decides which rows are offered
148
+ * (a formula inside the table is offered no section but this row) and how their regions are shown.
149
+ * Omit for a host with no cell.
150
+ */
151
+ getCell?(): ICell | null;
74
152
  /** Workbook locale (drives the argument-separator shown in the signature). `null` → `'en'`. */
75
153
  getLocale(): string | null;
76
154
  /**
@@ -83,6 +161,17 @@ export interface UseFormulaHintsOptions {
83
161
  * signature preview. Pass the live value (it participates in the panel identity).
84
162
  */
85
163
  hoveredTokenIndex?: number | null;
164
+ /**
165
+ * The argument the WHOLE text is, for a field that edits one argument of a call rather than a
166
+ * formula containing it — the Function Arguments form. While such a field is empty, it offers the
167
+ * values its parameter is limited to, the same rows an empty argument offers in the cell editor.
168
+ *
169
+ * @remarks
170
+ * Offered with nothing highlighted: a form is walked with Tab, and Tab past an optional field must
171
+ * leave it empty rather than fill in the first value. An arrow key picks a row, and only then do
172
+ * Enter and Tab accept it.
173
+ */
174
+ getArgument?(): FormulaArgument | null;
86
175
  }
87
176
  /** What {@link useFormulaHints} hands the hosting chrome. */
88
177
  export interface FormulaHintsApi {
@@ -123,4 +212,5 @@ export interface FormulaHintsApi {
123
212
  * box), the open/close policy, and when {@link FormulaHintsApi.update} runs.
124
213
  */
125
214
  export declare const useFormulaHints: (options: UseFormulaHintsOptions) => FormulaHintsApi;
215
+ export {};
126
216
  //# sourceMappingURL=useFormulaHints.d.ts.map
@@ -31,7 +31,8 @@ export type FormulaInputGrammar = 'formula' | 'reference';
31
31
  * - `'literal'` — the `=` DECIDES: text with a leading `=` is a formula (parsed, colored, validated),
32
32
  * text without one is a literal that is never parsed and never an error — Excel's own cellIs/DV
33
33
  * operand box. A committed string value displays verbatim; the `=` is the one discriminator, so
34
- * the field adds none and strips none.
34
+ * the field adds none and strips none. Pointing follows it too: the field arms for grid picks
35
+ * only while its text starts with `=`, so Escape back to a literal (or to nothing) disarms.
35
36
  */
36
37
  export type FormulaInputEquals = 'optional' | 'required' | 'bare' | 'literal';
37
38
  export declare const splitReferenceSegments: (text: string) => {
@@ -94,7 +95,8 @@ export interface UseFormulaInputOptions {
94
95
  * still runs — error state, picker sync), `'done'` makes Enter the FIELD's commit point rather than
95
96
  * a key the host form sees (the shared policy — see `useEditCommit`) — plus one grammar-specific
96
97
  * 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
+ * where a `'live'` one points for its whole engagement (the RefEdit contract). A field's ✓/✗
99
+ * adornments follow it too: `'done'` only.
98
100
  */
99
101
  changeOn?: 'live' | 'done';
100
102
  /**
@@ -102,7 +104,8 @@ export interface UseFormulaInputOptions {
102
104
  * Default `false` (single range; a pick replaces). Named to match the picker tier's `allowMulti`
103
105
  * (`useSelectionPointer` / `RangesPickerLayer`) — it rides the bus state to gate the grid gesture.
104
106
  *
105
- * `'reference'` grammar only; a `'formula'` field always allows every reference its expression holds.
107
+ * A `'formula'` field defaults to `true` and gates only the pick: `false` makes Ctrl+click replace
108
+ * rather than add a reference, while a typed expression may still hold any number of them.
106
109
  */
107
110
  allowMulti?: boolean;
108
111
  /**
@@ -122,6 +125,15 @@ export interface UseFormulaInputOptions {
122
125
  * for anything that genuinely spans sheets, e.g. chart series.
123
126
  */
124
127
  allowCrossSheet?: boolean;
128
+ /**
129
+ * Whether the field must hold a value. Default `false`: empty text is the CLEARED value (`null`),
130
+ * emitted and committed like any other.
131
+ *
132
+ * `true` makes empty text an ERROR instead, so it can never be committed — for a host whose
133
+ * model has no empty state (the ranges an item is anchored to). A field that MOUNTS empty shows
134
+ * no error until it is edited.
135
+ */
136
+ required?: boolean;
125
137
  /** Disabled: never engages the bus; the text is read-only at the host's discretion. */
126
138
  disabled?: boolean;
127
139
  /** Resolution context. Defaults to the enclosing `WorkbookContext`. */
@@ -161,6 +173,19 @@ export interface UseFormulaInputOptions {
161
173
  * whoever reads it — and the table-resize shape (Excel's `$A$3:$D$9`).
162
174
  */
163
175
  pickAs?: 'absolute' | 'relative';
176
+ /**
177
+ * Whether a pick that is exactly a dynamic array's spill writes the anchor plus `#` (`D2#`) instead
178
+ * of its address. Default `false`.
179
+ *
180
+ * @remarks
181
+ * `D2#` follows the spill as it grows or shrinks; `D2:E4` stays the extent it was picked at. The
182
+ * formula bar and in-grid editor always write `#`; Excel's range fields (conditional formatting,
183
+ * defined names, dialogs) do not, which is the default here. A name defined over the same extent
184
+ * does not win here the way it does in the cell editor — fields never write names for a pick. A
185
+ * single cell, an array-entered block and a blocked spill always write an address. The `$` style
186
+ * follows {@link pickAs} and re-scoping as for an address, on the anchor (`$D$2#`).
187
+ */
188
+ pickSpills?: boolean;
164
189
  /**
165
190
  * The COMMIT channel: fires with the final parsed value at each commit point — a done key
166
191
  * (Enter/Tab/Escape, from the field or the GRID), the explicit {@link FormulaInputApi.commit}
@@ -239,7 +264,8 @@ export interface FormulaInputApi {
239
264
  * - `'formula'` — armed by CARET CONTEXT (the cell editor's model): an operand expected at the
240
265
  * caret, or the caret on a reference token. Elsewhere (a function name, a number) the caret does
241
266
  * 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.
267
+ * drag-to-re-scope) while fresh grid gestures don't splice into the middle of a token. A
268
+ * `'literal'` field is armed only while its text starts with `=`: empty or bare, nothing points.
243
269
  */
244
270
  pointArmed: boolean;
245
271
  /** Arm/disarm picking without focus (the adornment toggle). */
@@ -82,6 +82,18 @@ export interface ReferenceModeState {
82
82
  * all on this sheet, and the existing per-pane scope filter already drops everything else.)
83
83
  */
84
84
  scope?: string;
85
+ /**
86
+ * Show the ranges and nothing else — no move, no resize grips, no grid-draw.
87
+ *
88
+ * @remarks
89
+ * Declared by the PRODUCER, like {@link allowMulti} and {@link scope}, because it is a property of
90
+ * what is being shown: these ranges are an ANNOTATION rather than a pick. A hovered cell's
91
+ * reference cycle is the case it exists for — there is no text behind it for a drag to write back
92
+ * to, so an outline the user can grab would be an edit gesture with nowhere to go. `'show'` on its
93
+ * own still allows the drag (that is how a chart's series is re-homed); this is the narrower
94
+ * disposition. Absent ⇒ interactive, the existing default.
95
+ */
96
+ readOnly?: boolean;
85
97
  /**
86
98
  * `true` while a reference rectangle is actively being dragged/resized/drawn on the grid. Published by the
87
99
  * reference layer (from the picker's drag lifecycle) so a consumer — e.g. the formula editor — can react to
@@ -0,0 +1,24 @@
1
+ import { CellCoords } from '@sheetxl/utils';
2
+ import { ISheet, IDataValidation } from '@sheetxl/sdk';
3
+ /**
4
+ * The alert a typed entry raised: the rule it failed, and the cell it was typed into.
5
+ */
6
+ export interface ValidationAlert {
7
+ /** The sheet the entry was typed on. */
8
+ sheet: ISheet;
9
+ /** The cell the entry was typed into, as the edit session names it: with its sheet scope. */
10
+ coords: CellCoords;
11
+ /** The text that was typed. A Warning accepts the same text entered again. */
12
+ dirty: string;
13
+ /** The rule that refused it. */
14
+ dataValidation: IDataValidation;
15
+ /** The rule's alert style. */
16
+ style: IDataValidation.AlertStyle;
17
+ }
18
+ /** Raise `alert`, or (`null`) clear the one showing. */
19
+ export declare const setValidationAlert: (alert: ValidationAlert | null) => void;
20
+ /** The alert showing, on any sheet. */
21
+ export declare const getValidationAlert: () => ValidationAlert | null;
22
+ /** The alert showing on `sheet` (reactive). */
23
+ export declare const useValidationAlert: (sheet: ISheet) => ValidationAlert | null;
24
+ //# sourceMappingURL=validationAlert.d.ts.map
@@ -0,0 +1,23 @@
1
+ /**
2
+ * The activation argument the **Workbook Links** pane understands.
3
+ *
4
+ * @remarks
5
+ * Lives with the feature rather than with the task-pane primitives: `taskPane` is the generic host
6
+ * and knows nothing about what any particular pane shows — the same arrangement
7
+ * `ProtectionPaneArgs` uses.
8
+ *
9
+ * Absent ⇒ the pane keeps whichever tab it is on (`links` on a fresh open). It is scoped to ONE
10
+ * activation, like every `args` payload — see `TaskPaneProps.args`.
11
+ */
12
+ export interface ExternalLinksPaneArgs {
13
+ /** Which tab to show. */
14
+ tab?: ExternalLinksPaneArgs.Tab;
15
+ }
16
+ export declare namespace ExternalLinksPaneArgs {
17
+ /**
18
+ * `links` is the list of linked books; `settings` is the workbook's `updateLinks` policy, which
19
+ * is about every link at once rather than about any one of them.
20
+ */
21
+ type Tab = 'links' | 'settings';
22
+ }
23
+ //# sourceMappingURL=ExternalLinksPaneArgs.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * from './ExternalLinksPaneArgs';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -2,6 +2,7 @@ import { default as React } from 'react';
2
2
  import { ICalculation, ICellRanges, IRange, IWorkbook } from '@sheetxl/sdk';
3
3
  import { FormulaInputApi, FormulaInputGrammar, FormulaInputEquals } from '../editor/useFormulaInput';
4
4
  import { ReferenceDoneArgs } from '../editor/useReferenceMode';
5
+ import { FormulaArgument } from '../editor/functionArgs';
5
6
  /**
6
7
  * Props for the plain-DOM {@link FormulaInput} — the UI-kit-free field whose value is an
7
8
  * `ICalculation.IFormula`.
@@ -25,13 +26,16 @@ export interface FormulaInputProps extends Omit<React.InputHTMLAttributes<HTMLIn
25
26
  onChangeText?: (text: string) => void;
26
27
  /** The commit channel. See `UseFormulaInputOptions.onDone`. */
27
28
  onDone?: (value: ICalculation.IFormula | null, args: ReferenceDoneArgs) => void;
28
- /** `'done'` suppresses the live notifications — the host hears only `onDone`. Default `'live'`. */
29
+ /**
30
+ * `'done'` suppresses the live notifications — the host hears only `onDone` — and shows the ✓/✗
31
+ * while the text differs from the committed value. Default `'live'`. See `UseFormulaInputOptions.changeOn`.
32
+ */
29
33
  changeOn?: 'live' | 'done';
30
34
  /** Resolution/picking context. Defaults to the enclosing `WorkbookContext`. */
31
35
  workbook?: IWorkbook | null;
32
36
  /** The headless field API, for host-driven commit points (a dialog's OK → `apiRef.current?.commit()`). */
33
37
  apiRef?: React.Ref<FormulaInputApi>;
34
- /** Hide the adornment cluster (✓/✗ while engaged in modal mode; the select-current action). */
38
+ /** Hide the adornment cluster (✓/✗ while editing in `'done'` mode; the select-current action). */
35
39
  hideAdornment?: boolean;
36
40
  /** Hide the error line under the field (hosts that surface `api.error` themselves). */
37
41
  hideError?: boolean;
@@ -54,6 +58,12 @@ export interface FormulaInputProps extends Omit<React.InputHTMLAttributes<HTMLIn
54
58
  * table-resize shape. See `UseFormulaInputOptions.pickAs`.
55
59
  */
56
60
  pickAs?: 'absolute' | 'relative';
61
+ /**
62
+ * Whether a pick that is exactly a dynamic array's spill writes `D2#` instead of its address.
63
+ * Default `false`, as Excel's range fields; the cell editor always does. See
64
+ * `UseFormulaInputOptions.pickSpills`.
65
+ */
66
+ pickSpills?: boolean;
57
67
  /**
58
68
  * Allow a comma-separated multi-range reference (typed, or Ctrl+click-picked). Default `false`.
59
69
  * `'reference'` grammar only — a `'formula'` field always allows every reference its expression holds.
@@ -66,6 +76,12 @@ export interface FormulaInputProps extends Omit<React.InputHTMLAttributes<HTMLIn
66
76
  * `UseFormulaInputOptions.allowCrossSheet`; independent of {@link allowMulti}.
67
77
  */
68
78
  allowCrossSheet?: boolean;
79
+ /**
80
+ * The call argument this field's whole text is — the Function Arguments form's rows. An empty field
81
+ * then offers, in its hint popup, the values the parameter is limited to. See
82
+ * `UseFormulaHintsOptions.getArgument`.
83
+ */
84
+ argument?: FormulaArgument | null;
69
85
  }
70
86
  /**
71
87
  * The **formula field** — the plain-DOM (UI-kit-free) input whose value is an
@@ -1,5 +1,6 @@
1
1
  import { default as React } from 'react';
2
2
  import { IRange, IWorkbook } from '@sheetxl/sdk';
3
+ import { FormulaArgument } from '../editor/functionArgs';
3
4
  import { FormulaInputApi, FormulaInputGrammar } from '../editor/useFormulaInput';
4
5
  export interface UseFormulaInputPartsOptions {
5
6
  /** The headless field API driving this chrome (`useFormulaInput`). */
@@ -15,6 +16,11 @@ export interface UseFormulaInputPartsOptions {
15
16
  workbook?: IWorkbook | null;
16
17
  /** The formula's HOME anchor (`'formula'` grammar) — bare references evaluate against it. */
17
18
  home?: Partial<IRange.CellCoords>;
19
+ /**
20
+ * The call argument the field's whole text is — see `UseFormulaHintsOptions.getArgument`. An
21
+ * empty field then offers the values its parameter is limited to.
22
+ */
23
+ argument?: FormulaArgument | null;
18
24
  }
19
25
  /**
20
26
  * What {@link useFormulaInputParts} hands a field chrome. Wire the three refs (the positioned
@@ -43,6 +49,8 @@ export interface FormulaInputParts {
43
49
  onSelect: (e: React.SyntheticEvent) => void;
44
50
  /** Clicking back into the field re-summons a dismissed hint popup (Excel-style). */
45
51
  onPointerDown: (e: React.PointerEvent) => void;
52
+ /** A press on the field means "select", never "move the text" — see `useTextSelectionDrag`. */
53
+ onDragStart: (e: React.DragEvent) => void;
46
54
  };
47
55
  /**
48
56
  * The shared parts' keyboard: the hint popup's (autocomplete list nav; Escape dismisses an open
@@ -56,7 +64,8 @@ export interface FormulaInputParts {
56
64
  * `'formula'` grammar, while engaged: an operand is expected at the caret (the "input expected"
57
65
  * marker is showing — trailing `=A1+|`, or a cleared argument `=SUM(|,A1:C3)`). The user is 99%
58
66
  * mid-typing — chromes should NOT present `api.error` as "invalid" while this holds (the commit
59
- * gate still blocks an incomplete accept).
67
+ * gate still blocks an incomplete accept). Only while the input has focus: text left that way is
68
+ * an error, even though a blur while pointing keeps the field engaged.
60
69
  */
61
70
  inputExpected: boolean;
62
71
  /** The measured coloring overlay (`null` while inactive/unmeasured). Render inside the container. */
@@ -51,7 +51,10 @@ export interface UseEditCommitOptions<V> {
51
51
  /**
52
52
  * `'done'` suppresses the live {@link onChange} notifications entirely (parsing still runs, so the
53
53
  * error state and the commit-channel value stay current) and makes Enter the field's OWN commit
54
- * point rather than a key the host form gets to see. Default `'live'`.
54
+ * point rather than a key the host form gets to see. A field's ✓/✗ adornments follow it: shown only
55
+ * in `'done'`, while the text differs from the committed value. Default `'live'`.
56
+ *
57
+ * It does not change when {@link onDone} fires — that is the same in both.
55
58
  */
56
59
  changeOn?: 'live' | 'done';
57
60
  /** The live PREVIEW channel — every valid text state. */
@@ -114,8 +117,17 @@ export interface EditCommitApi<V> {
114
117
  revertToCommitted(): void;
115
118
  /** Restore the session-start text (a cancel) and re-parse it. */
116
119
  revertToBaseline(): void;
117
- /** Adopt `next` as the committed text (an outside value change): clean, unerrored, revert target. */
118
- resetCommitted(next: string, value?: V | null): void;
120
+ /**
121
+ * Adopt `next` as the committed text (an outside value change): clean, unerrored, revert target.
122
+ *
123
+ * While the user is EDITING (a session open and touched) the text is theirs: `next` becomes the
124
+ * committed text but the display keeps what they typed, and the next accept shows `next` — see the
125
+ * module doc.
126
+ *
127
+ * @returns `false` when the display was left alone for that reason — its error state is still the
128
+ * typed text's, so the host must not overwrite it with `next`'s.
129
+ */
130
+ resetCommitted(next: string, value?: V | null): boolean;
119
131
  /** A session is starting: the CURRENT text becomes the cancel baseline. */
120
132
  beginSession(): void;
121
133
  /**
@@ -147,6 +159,9 @@ export interface EditCommitApi<V> {
147
159
  *
148
160
  * The rules it owns, once, for every field:
149
161
  *
162
+ * - **Two channels, one mode.** `onChange` is the value while it is edited; `onDone` is the edit
163
+ * ending. `changeOn` governs only the first (and who owns Enter): an edit ENDS the same way in
164
+ * both modes — Enter, Tab, a blur to another input, the ✓/✗, `commit()`/`cancel()`, Escape.
150
165
  * - **Two baselines.** `committedText` is the last ACCEPTED value; `baselineText` is the text when the
151
166
  * current session started. They differ because the live-change model applies every intermediate
152
167
  * change — "the value before" can then only mean before-the-session, not before-the-last-change.
@@ -161,6 +176,11 @@ export interface EditCommitApi<V> {
161
176
  * CANCELS instead of committing, so focus never advances carrying an error.
162
177
  * - **Invalid never commits** on any accept path; **blur commits only when dirty**; and a done key
163
178
  * plus the blur it causes are ONE gesture, delivered once (the one-shot guard).
179
+ * - **The text is the user's while they edit.** A live host echoes each change back as its value, and
180
+ * the echo is often the value NORMALIZED (`09` → `9`, `9/2` → `9/2/2026`). Rewriting the display
181
+ * with it would retype the field under the caret, so an outside value that lands mid-edit only
182
+ * becomes the committed text; the accept that ends the edit shows it. An untouched field follows
183
+ * outside changes at once.
164
184
  * - **The input owns its text keys.** Delete / caret motion / the native chords are consumed
165
185
  * ({@link EditCommitApi.handleTextKeys}) so they never reach the app's command dispatch.
166
186
  *