@sheetxl/react 0.7.28-beta.4 → 0.8.0-beta.2

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 (84) hide show
  1. package/browser/cjs/index.cjs +21 -15
  2. package/browser/esm/{BdJpSdwyWuh-Te5p.mjs → Dsn3z1hmkv-bWGVr.mjs} +1 -1
  3. package/browser/esm/index.mjs +8117 -5883
  4. package/node/esm/{Ban9guHVB-Vxa-tq.mjs → CyU4sKDpHyc6kF7j.mjs} +1 -1
  5. package/node/esm/index.mjs +8234 -5978
  6. package/package.json +6 -6
  7. package/resources/locales/de/movable.cmd.json +86 -0
  8. package/resources/locales/de/selection.cmd.json +8 -0
  9. package/resources/locales/de/sheet.cmd.json +170 -7
  10. package/resources/locales/de/ui.msg.json +48 -3
  11. package/resources/locales/de/workbook.cmd.json +9 -6
  12. package/resources/locales/en/movable.cmd.json +86 -0
  13. package/resources/locales/en/selection.cmd.json +8 -0
  14. package/resources/locales/en/sheet.cmd.json +171 -7
  15. package/resources/locales/en/ui.msg.json +48 -3
  16. package/resources/locales/en/workbook.cmd.json +10 -7
  17. package/types/src/autoFill/AutoFillPresets.d.ts +14 -0
  18. package/types/src/autoFill/FillMenu.d.ts +36 -0
  19. package/types/src/autoFill/FillSeries.d.ts +38 -0
  20. package/types/src/autoFill/index.d.ts +4 -0
  21. package/types/src/border/StaticBorderRenderer.d.ts +2 -2
  22. package/types/src/border/useBorders.d.ts +7 -7
  23. package/types/src/cell/FormulaCellRenderer.d.ts +1 -1
  24. package/types/src/cell/SheetCellRenderer.d.ts +15 -0
  25. package/types/src/cell/StaticCellRenderer.d.ts +57 -0
  26. package/types/src/cell/index.d.ts +1 -0
  27. package/types/src/cell/useFormulaViewAnchor.d.ts +1 -1
  28. package/types/src/checklist/ValueChecklist.d.ts +71 -0
  29. package/types/src/checklist/index.d.ts +2 -0
  30. package/types/src/conditionalFormat/index.d.ts +1 -0
  31. package/types/src/editor/FunctionPreviewPanel.d.ts +14 -0
  32. package/types/src/editor/NamedItemLabel.d.ts +29 -0
  33. package/types/src/editor/NamedItemsPanel.d.ts +13 -2
  34. package/types/src/editor/SheetCellEditorLayer.d.ts +8 -4
  35. package/types/src/editor/SheetCellInput.d.ts +12 -2
  36. package/types/src/editor/SheetEditable.d.ts +8 -2
  37. package/types/src/editor/formulaCaret.d.ts +39 -10
  38. package/types/src/editor/formulaEval.d.ts +9 -5
  39. package/types/src/editor/formulaLint.d.ts +36 -0
  40. package/types/src/editor/formulaPresentation.d.ts +7 -0
  41. package/types/src/editor/formulaText.d.ts +17 -5
  42. package/types/src/editor/functionArgs.d.ts +20 -0
  43. package/types/src/editor/index.d.ts +2 -1
  44. package/types/src/editor/pickedReference.d.ts +76 -0
  45. package/types/src/editor/useEditRejectedNotice.d.ts +32 -0
  46. package/types/src/editor/useFormulaHints.d.ts +93 -3
  47. package/types/src/editor/useFormulaInput.d.ts +15 -1
  48. package/types/src/editor/useReferenceMode.d.ts +12 -0
  49. package/types/src/externalLink/ExternalLinksPaneArgs.d.ts +23 -0
  50. package/types/src/externalLink/index.d.ts +2 -0
  51. package/types/src/form/FormulaInput.d.ts +13 -0
  52. package/types/src/form/FormulaInputParts.d.ts +10 -1
  53. package/types/src/frame/CommandContext.d.ts +147 -5
  54. package/types/src/index.d.ts +5 -0
  55. package/types/src/io/WorkbookIO.d.ts +2 -0
  56. package/types/src/layer/CellErrorLayer.d.ts +10 -3
  57. package/types/src/layer/ProtectionLayer.d.ts +52 -0
  58. package/types/src/layer/ValidationDropdownLayer.d.ts +61 -0
  59. package/types/src/layer/ValidationIndicatorLayer.d.ts +14 -21
  60. package/types/src/layer/ValidationPromptLayer.d.ts +46 -0
  61. package/types/src/layer/index.d.ts +4 -0
  62. package/types/src/layer/useValidationPicker.d.ts +54 -0
  63. package/types/src/layer/validationMark.d.ts +63 -0
  64. package/types/src/movable/MovableLayer.d.ts +1 -5
  65. package/types/src/picker/PickerPanel.d.ts +52 -0
  66. package/types/src/picker/cellPickerOpen.d.ts +6 -0
  67. package/types/src/picker/index.d.ts +4 -0
  68. package/types/src/picker/useCellPicker.d.ts +93 -0
  69. package/types/src/protection/ProtectionPaneArgs.d.ts +31 -0
  70. package/types/src/protection/index.d.ts +3 -0
  71. package/types/src/protection/unlockProtectedRanges.d.ts +23 -0
  72. package/types/src/selection/SheetSelectionLayer.d.ts +10 -0
  73. package/types/src/sheet/ISheetElement.d.ts +7 -0
  74. package/types/src/sheet/SheetCommands.d.ts +3 -3
  75. package/types/src/sheet/circularReferences.d.ts +9 -1
  76. package/types/src/sheet/index.d.ts +1 -1
  77. package/types/src/sheet/useCycleHighlight.d.ts +21 -0
  78. package/types/src/taskPane/ITaskPane.d.ts +12 -1
  79. package/types/src/workbook/IWorkbookElement.d.ts +5 -0
  80. package/types/src/workbook/WorkbookCommands.d.ts +0 -2
  81. package/types/src/workbook/_followOrigin.d.ts +9 -0
  82. package/types/src/workbook/useWorkbookFormat.d.ts +3 -3
  83. package/types/src/editor/useProtectedEditNotice.d.ts +0 -14
  84. /package/types/src/{sheet → conditionalFormat}/ConditionalFormatPresets.d.ts +0 -0
@@ -0,0 +1,71 @@
1
+ import { default as React } from 'react';
2
+ import { Scalar } from '@sheetxl/sdk';
3
+ import { CheckboxListProps } from '@sheetxl/grid-react';
4
+ /** One value the checklist offers. */
5
+ export interface ValueChecklistItem {
6
+ /** The value as shown, and the identity a check is kept by. */
7
+ text: string;
8
+ /** The value the text stands for, when a host needs it back (a filter writes it). */
9
+ value?: Scalar;
10
+ /** How many cells hold it, when the host knows. */
11
+ count?: number;
12
+ }
13
+ /**
14
+ * Props for {@link ValueChecklist}.
15
+ */
16
+ export interface ValueChecklistProps {
17
+ /** The values, in the order shown. */
18
+ items: readonly ValueChecklistItem[];
19
+ /** The checked values, by `text`. */
20
+ checked: ReadonlySet<string>;
21
+ /**
22
+ * `texts` were set to `checked` — one on a click, the highlighted rows on Space, every row in
23
+ * view on Select All. Rows out of the view (narrowed away by the search) are never named, so
24
+ * they keep their state.
25
+ */
26
+ onCheckedChange: (texts: readonly string[], checked: boolean) => void;
27
+ /** Whether a `(Blanks)` row is offered, first in the list. */
28
+ hasBlanks?: boolean;
29
+ /** Whether the blanks row is checked. */
30
+ blanksChecked?: boolean;
31
+ /** The blanks row was set. Select All names it through this, not through `onCheckedChange`. */
32
+ onBlanksChange?: (checked: boolean) => void;
33
+ /** The host stopped listing values at its cap: a notice says so under the list. */
34
+ truncated?: boolean;
35
+ /** A search field above the list. @defaultValue true */
36
+ search?: boolean;
37
+ /** Enter in the search field: the host applies. */
38
+ onApply?: () => void;
39
+ /** Escape with no search text to clear: the host closes. */
40
+ onClose?: () => void;
41
+ /** Take the focus on mount (the search field, or the list without one). @defaultValue true */
42
+ autoFocus?: boolean;
43
+ /** See `CheckboxListProps.renderCheckbox`: a styled control (MUI) in place of the native one. */
44
+ renderCheckbox?: CheckboxListProps['renderCheckbox'];
45
+ /** Render a value row's label. @defaultValue the text */
46
+ renderItem?: (item: ValueChecklistItem) => React.ReactNode;
47
+ /** Uniform row height in px. @defaultValue 24 */
48
+ itemHeight?: number;
49
+ /** Class for the root. */
50
+ className?: string;
51
+ /** Style for the root. */
52
+ style?: React.CSSProperties;
53
+ /** See `ListSurfaceProps.viewport`. */
54
+ viewport?: CheckboxListProps['viewport'];
55
+ }
56
+ /**
57
+ * A searchable **checklist of values** with a tri-state Select All, a `(Blanks)` row and a count
58
+ * line — the filter dropdown's Values body, and any other "which of these" choice.
59
+ *
60
+ * @remarks
61
+ * Reads no cells: the host supplies the items and owns the checked set (by text). The search
62
+ * narrows the VIEW only: Select All acts on the rows in view, rows narrowed away keep their state,
63
+ * and what the host applies is the whole set (Sheets' rule, not Excel's replace-with-results).
64
+ * The search field keeps the focus; Up/Down move the list's highlight, Space toggles the
65
+ * highlighted rows, Enter applies, Escape clears the search and then closes.
66
+ *
67
+ * The root wears the grid's surface and mode, so the list looks like the cells it stands for even
68
+ * inside chrome of another color.
69
+ */
70
+ export declare const ValueChecklist: React.FC<ValueChecklistProps>;
71
+ //# sourceMappingURL=ValueChecklist.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * from './ValueChecklist';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -1,2 +1,3 @@
1
1
  export * from './IconSetGlyphs';
2
+ export * from './ConditionalFormatPresets';
2
3
  //# sourceMappingURL=index.d.ts.map
@@ -17,6 +17,18 @@ export interface FunctionHint {
17
17
  argIndex: number;
18
18
  /** The function's declared parameters, in order (name / optional / rest). */
19
19
  params: readonly IFunction.IParameterType[];
20
+ /**
21
+ * The argument the caret is in holds a literal outside the values its parameter is limited to
22
+ * (`findEnumLints`). Shown under that argument's description while it is the one lit.
23
+ */
24
+ warning?: {
25
+ /** The argument, as {@link argIndex} counts. */
26
+ argIndex: number;
27
+ /** The literal as written. */
28
+ value: string;
29
+ /** The values it could be, as literals, joined for display. */
30
+ values: string;
31
+ };
20
32
  }
21
33
  /**
22
34
  * The function's self-describing text, loaded lazily (async) from `getDescriptor()`. Keyed by `name`
@@ -31,6 +43,8 @@ export interface FunctionDescriptor {
31
43
  params: Readonly<Record<string, {
32
44
  description?: string;
33
45
  }>>;
46
+ /** The copy for each enum a parameter is limited to, keyed by enum id — see `IFunction.IDescriptor.getEnums`. */
47
+ enums?: Readonly<Record<string, IFunction.IEnumDescription>>;
34
48
  }
35
49
  export declare const argTypeKey: (param: IFunction.IParameterType) => string;
36
50
  export interface FunctionArgIconsProps {
@@ -0,0 +1,29 @@
1
+ import { default as React } from 'react';
2
+ import { NamedItem } from './NamedItemsPanel';
3
+ export interface NamedItemLabelProps {
4
+ /** What the row shows: its name, its kind (the glyph) and an optional trailing category. */
5
+ item: NamedItem;
6
+ /** A dimmed line under the name, shown when given. */
7
+ summary?: string | null;
8
+ /**
9
+ * Let the summary wrap.
10
+ *
11
+ * @defaultValue `false` — one clipped line (with the full text as a tooltip), so a floating list
12
+ * does not change height as its selection moves.
13
+ */
14
+ wrapSummary?: boolean;
15
+ /** Height of the name line, in px. @defaultValue `22` */
16
+ rowHeight?: number;
17
+ }
18
+ /**
19
+ * The content of one row in a list of functions, names and tables — the kind glyph, the name, an
20
+ * optional trailing category and an optional summary under it.
21
+ *
22
+ * @remarks
23
+ * Shared so an item reads the same wherever it is listed: the formula autocomplete
24
+ * ({@link NamedItemsPanel}) and the Insert Function dialog. Presentational only — the host owns the
25
+ * row element, its selection styling and its events. The name carries the class `named-item-name`,
26
+ * for a host that styles it (the dialog sets it in the monospace font).
27
+ */
28
+ export declare const NamedItemLabel: React.FC<NamedItemLabelProps>;
29
+ //# sourceMappingURL=NamedItemLabel.d.ts.map
@@ -4,9 +4,16 @@
4
4
  * @remarks
5
5
  * `'named'` covers every non-table entry of the workbook's `INamedCollection` (a named range, a named
6
6
  * constant, a named formula): they differ in what they resolve to, but not in how they are completed —
7
- * the name goes in bare and stands on its own.
7
+ * the name goes in bare and stands on its own. `'parameter'` is a `LET`/`LAMBDA` name in scope at the
8
+ * caret — completed the same way, but it lives in the formula rather than the workbook. `'lambda'` is a
9
+ * name bound to a literal `LAMBDA(…)` — a defined name whose body is one, or a `LET` name whose value is
10
+ * one: a name, but completed like a function, with its paren.
11
+ * `'column'` and `'specifier'` (`#Data`, `@ - This Row`) are offered inside a table's brackets; the
12
+ * bracket is left for the user to close.
13
+ * `'enum'` is one value an argument is limited to, offered in an empty argument of that type; its
14
+ * name is the literal a formula spells (`1`, `"osversion"`), and it goes in as written.
8
15
  */
9
- export type NamedItemKind = 'function' | 'named' | 'table';
16
+ export type NamedItemKind = 'function' | 'named' | 'lambda' | 'table' | 'parameter' | 'column' | 'specifier' | 'enum';
10
17
  /**
11
18
  * One row in the formula autocomplete list. Deliberately minimal — the presentational panel needs a
12
19
  * display `name`, its {@link NamedItemKind}, and optionally a `category` / an `iconKey` override. The
@@ -17,6 +24,10 @@ export interface NamedItem {
17
24
  name: string;
18
25
  /** What the row is. Defaults to `'function'`, which is what an omitted kind meant before names joined the list. */
19
26
  kind?: NamedItemKind;
27
+ /** Optional text shown right after the name, unemphasized — an `'enum'` label's value (`AVERAGE 1`). */
28
+ detail?: string;
29
+ /** What choosing the row inserts, when that is not `name` — an `'enum'` label inserts its value. */
30
+ insert?: string;
20
31
  /** Optional category (e.g. `Math & Trig`), shown dimmed at the row's trailing edge. */
21
32
  category?: string;
22
33
  /** Optional icon-pack key for the leading glyph; overrides the {@link NamedItemKind} default. */
@@ -2,6 +2,7 @@ import { default as React } from 'react';
2
2
  import { ISheet } from '@sheetxl/sdk';
3
3
  import { EditorAlignment, VirtualDivProps } from '@sheetxl/grid-react';
4
4
  import { SheetEditable } from './SheetEditable';
5
+ import { EditRejectedNotice } from './useEditRejectedNotice';
5
6
  /**
6
7
  * Props for {@link SheetCellEditorLayer}.
7
8
  *
@@ -23,15 +24,18 @@ export interface SheetCellEditorLayerProps extends VirtualDivProps {
23
24
  * no flag.
24
25
  */
25
26
  darkMode?: boolean;
26
- /** Horizontal anchor used when the editor grows past its cell (Excel-style overflow). @defaultValue `'left'` */
27
+ /**
28
+ * Horizontal anchor used when the editor grows past its cell (Excel-style overflow). Overrides the
29
+ * default, which follows the edited cell's rendered alignment (formulas always grow to the right).
30
+ */
27
31
  alignment?: EditorAlignment;
28
32
  /**
29
33
  * Notified when a start-edit attempt is rejected (`startEdit` returned `false` — a non-editable
30
34
  * cell). The host that mounts one layer per pane (`SheetElement`) passes a SHARED callback
31
- * ({@link useProtectedEditNotice}) so all panes form one once-per-visit notice scope.
32
- * @defaultValue this layer's own {@link useProtectedEditNotice}
35
+ * ({@link useEditRejectedNotice}) so all panes form one notice scope; it receives the rejected cell.
36
+ * @defaultValue this layer's own {@link useEditRejectedNotice}
33
37
  */
34
- onEditRejected?: () => void;
38
+ onEditRejected?: EditRejectedNotice;
35
39
  }
36
40
  export declare function SheetCellEditorLayer(props: SheetCellEditorLayerProps): React.ReactElement;
37
41
  export declare namespace SheetCellEditorLayer {
@@ -29,6 +29,15 @@ export interface SheetCellInputOptions {
29
29
  */
30
30
  fillNone?: boolean;
31
31
  }
32
+ /**
33
+ * Project the cell's **edit string**: the formula (`=…`), else the formatted text, with the leading
34
+ * `'` restored for a quote-prefixed (text-forced) cell.
35
+ *
36
+ * @remarks
37
+ * Exported for the grid editor layer, which needs the same text the input will display to decide which way
38
+ * the box grows (a formula always grows to the right, whatever the cell's alignment).
39
+ */
40
+ export declare const editStringFromCell: (cell: ICell) => string;
32
41
  /**
33
42
  * The **ghost formula** for a spilled-INTO cell: the spill anchor's formula, as Excel greys it in the
34
43
  * formula bar. `null` for every other cell (including the anchor itself, which owns the formula and so
@@ -52,8 +61,9 @@ export declare const placeholderFromCell: (cell: ICell | null) => string | null;
52
61
  *
53
62
  * **Placement** is driven by {@link ICell.getTextPlacement} — the *same* SDK geometry the cell
54
63
  * renderer uses — so the editor's text sits exactly where the rendered cell's does. Insets define the
55
- * content box; the cell's line height sets the line rhythm; vertical alignment is flex `justifyContent`
56
- * within the content box. Horizontal overflow + wrap ride the `cellSize`/`onNaturalSize` seam: a
64
+ * content box horizontally; the placement's text block (Excel's baseline rules) bounds it vertically; the
65
+ * cell's line height sets the line rhythm; vertical alignment is flex `justifyContent` within that
66
+ * box. Horizontal overflow + wrap ride the `cellSize`/`onNaturalSize` seam: a
57
67
  * wrapped cell measures its own height (clip-proof) and reports width 0 so the layer grows the box
58
68
  * *down*; an unwrapped cell reports the shrink-to-content width so the layer grows it *across* columns.
59
69
  */
@@ -16,8 +16,10 @@ export declare const resolveCellBackground: (cell: ICell, sheet: ISheet, darkMod
16
16
  * @remarks
17
17
  * - **clean** is `() => ICell` — a *live* cell getter (not a captured value), so a cell-aware input
18
18
  * reads the cell's formula/format/style/fill through to the model even if the handle is replaced.
19
- * - **commit** writes the dirty string via `range.setValue(text, { autoFit })` — the SDK coerces the
20
- * string to a formula / number / date / text.
19
+ * - **commit** writes the dirty string via `range.setValue(text, { autoFit, autoSelectRestore })` — the SDK
20
+ * coerces the string to a formula / number / date / text. `autoSelectRestore` without `autoSelect`: the
21
+ * write leaves the selection as it is (a block typed into stays selected for Enter to move within),
22
+ * and an undo or a redo of it lands on the cell.
21
23
  * - **`null`** ⇒ the cell is not editable (protected / read-only), via {@link ICell.isEditAllowed}.
22
24
  * - **scope-aware**: `coords.scope` (a sheet name) picks the sheet to edit, via `workbook.getSheet`,
23
25
  * falling back to `sheet`. This is what makes a commit write back to the session's *origin* sheet even
@@ -26,6 +28,10 @@ export declare const resolveCellBackground: (cell: ICell, sheet: ISheet, darkMod
26
28
  *
27
29
  * Construct the editable with it: `new DefaultEditable(anchor, createSheetCreateEdit(sheet))` — or use
28
30
  * the {@link createEditable} factory, which wires both.
31
+ *
32
+ * A write the model REFUSES (an `ExpectedError` such as "You can't change part of an array") throws
33
+ * out of `commit`, which rejects it; the editable fans the error out to
34
+ * `IEditable.subscribeCommitError`, where the host shows it.
29
35
  */
30
36
  export declare const createSheetCreateEdit: (sheet: ISheet, workbook?: IWorkbook | null) => CreateEdit<() => ICell, string, EditCommitArgs>;
31
37
  /**
@@ -10,29 +10,47 @@ import { ICalculation } from '@sheetxl/sdk';
10
10
  export declare const caretOwnerToken: (tokens: readonly ICalculation.FormulaToken[], caret: number, base?: number) => {
11
11
  token: ICalculation.FormulaToken;
12
12
  start: number;
13
+ index: number;
13
14
  } | null;
14
15
  /**
15
- * The character span of the name being **completed** at the caret, or `null` when nothing is.
16
+ * Whether `token` names something the autocomplete list can offer: a function, a workbook name or
17
+ * table, a use of a `LET`/`LAMBDA` parameter, or the unfinished part of a structured reference. A
18
+ * partial identifier being typed is a `named` token too, even at the end of a formula that no longer
19
+ * parses.
16
20
  *
17
- * A candidate is an `isLookup` token (a function name, a named reference, or a partial identifier the
18
- * recoverer split off a broken tail) that is **not already a call** — i.e. no `(` immediately follows it
19
- * in `text`. That second half is the whole point: a name that already has its paren is finished work, and
20
- * clicking back into it (to read it, to fix an argument) is a navigation gesture, not a request to complete
21
- * it — re-popping the autocomplete list there covers the very formula you came back to look at. Excel
22
- * behaves the same way.
21
+ * A parameter's DECLARATION is not one — it introduces a new name, so there is nothing to complete.
22
+ * Nor is a table part the SDK has not marked `partial`: a finished part is not reopened.
23
+ */
24
+ export declare const isCompletionToken: (token: ICalculation.FormulaToken) => boolean;
25
+ /**
26
+ * The span of the name being **completed** at the caret, or `null` when nothing is. Offsets are text offsets
27
+ * past the leading formula prefix (`base`), like {@link caretOwnerToken}'s.
28
+ *
29
+ * A candidate is an {@link isCompletionToken} that is **not already a call** — no `(` token immediately follows
30
+ * a name, and no `[` follows a table name. That second half is the whole point: a name that already has its
31
+ * paren is finished work, and clicking back into it (to read it, to fix an argument) is a navigation gesture,
32
+ * not a request to complete it — re-popping the autocomplete list there covers the very formula you came back
33
+ * to look at. Excel behaves the same way.
23
34
  *
24
35
  * Typing is unaffected: `=SU` has no trailing paren, so the list still appears as you type, and accepting a
25
36
  * row parks the caret INSIDE the parens where the signature preview takes over.
26
37
  *
38
+ * What the list is built from comes off the token, as the SDK stated it:
39
+ * - `part` — the unfinished part of a structured reference (`Sales[Co`, or the empty part after `Sales[`):
40
+ * which table, and what may finish it (`TablePartRef.partial`); `nested` when it is an item of a
41
+ * bracketed list (`Sales[[#This Row],[Co`) rather than the reference's only part;
42
+ * - `bound` — otherwise, the `LET` / `LAMBDA` names in scope there (`FormulaTokenContext.bound`).
43
+ *
27
44
  * The editor shares this between the list and the signature preview so the two can never both claim the
28
45
  * caret — exactly one shows, and suppressing the list here is what lets the preview show the enclosing
29
46
  * call's signature instead.
30
- *
31
- * `text` is the full editor string and the returned offsets index into it (not into the token stream).
32
47
  */
33
- export declare const completionSpanAtCaret: (tokens: readonly ICalculation.FormulaToken[], caret: number, base: number, text: string) => {
48
+ export declare const completionSpanAtCaret: (tokens: readonly ICalculation.FormulaToken[], caret: number, base: number) => {
34
49
  start: number;
35
50
  end: number;
51
+ part?: ICalculation.TablePartRef;
52
+ nested?: true;
53
+ bound?: readonly ICalculation.BoundName[];
36
54
  } | null;
37
55
  /** The function + argument the caret is currently in. */
38
56
  export interface FunctionCaretContext {
@@ -40,7 +58,18 @@ export interface FunctionCaretContext {
40
58
  name: string;
41
59
  /** Zero-based index of the argument the caret is in. */
42
60
  argIndex: number;
61
+ /** The `LET` / `LAMBDA` names in scope at the call ({@link ICalculation.FormulaTokenContext.bound}), when any are. */
62
+ bound?: readonly ICalculation.BoundName[];
43
63
  }
64
+ /**
65
+ * Whether the argument the caret is in (`ctx`, from {@link resolveFunctionContext}) holds nothing yet:
66
+ * the caret sits right after the call's `(` or a separator, or in whitespace there, and only a
67
+ * separator, the call's `)` or the end of the text follows.
68
+ *
69
+ * Read off the `empty` token the SDK emits for an argument with no content. That token carries the
70
+ * argument's own context, so an empty argument of a nested call is never taken for this one's.
71
+ */
72
+ export declare const isEmptyArgumentAt: (tokens: readonly ICalculation.FormulaToken[], caret: number, base: number, ctx: FunctionCaretContext) => boolean;
44
73
  /**
45
74
  * Resolve which function + argument the caret sits in, from a formula's token stream.
46
75
  *
@@ -1,5 +1,6 @@
1
1
  import { CSSProperties } from 'react';
2
2
  import { ICalculation } from '@sheetxl/sdk';
3
+ import { TextSelectionPress } from '@sheetxl/utils-react';
3
4
  /** Gap (px) between the top of a hovered segment and the bottom of its eval tip. */
4
5
  export declare const EVAL_TIP_GAP = 6;
5
6
  /**
@@ -24,11 +25,14 @@ export interface SelectDrag {
24
25
  clientX: number;
25
26
  clientY: number;
26
27
  }) => boolean;
27
- /** Call from the input's `pointerdown`/`mousedown` — non-primary buttons are ignored. */
28
- begin: (e?: {
29
- button?: number;
30
- clientX?: number;
31
- clientY?: number;
28
+ /**
29
+ * Call from the input's `pointerdown` — non-primary buttons are ignored. Pass the WHOLE event: the
30
+ * selection drag reads its target and position to place the caret itself (`useTextSelectionDrag`).
31
+ */
32
+ begin: (e?: TextSelectionPress) => void;
33
+ /** Wire to the input's `dragstart`: a press on the field means "select", never "move the text". */
34
+ onDragStart: (e: {
35
+ preventDefault: () => void;
32
36
  }) => void;
33
37
  }
34
38
  /**
@@ -0,0 +1,36 @@
1
+ import { ICalculation } from '@sheetxl/sdk';
2
+ /** A value as a formula literal: a string quoted (`"` doubled), a number with the locale's decimal. */
3
+ export declare const enumLiteral: (value: number | string, decimal: string) => string;
4
+ /** A LITERAL argument outside the values its parameter is limited to — see {@link findEnumLints}. */
5
+ export interface EnumLint {
6
+ /** The called function, as the argument's tokens state it (`FormulaTokenContext.name`). */
7
+ name: string;
8
+ /** Which argument of the call. */
9
+ argIndex: number;
10
+ /** The literal's token indices — a negative number is the `-` and the number. */
11
+ tokens: readonly number[];
12
+ /** The literal as written (`5`, `-2`, `"xyz"`). */
13
+ text: string;
14
+ /** The text offsets the argument spans, from just past its opener to its closer — where a caret is "in" it. */
15
+ argStart: number;
16
+ argEnd: number;
17
+ /** The values the parameter offers, in declaration order — a `@deprecated` member is left out. */
18
+ values: readonly (number | string)[];
19
+ }
20
+ /**
21
+ * The literal arguments in `tokens` that fall outside their parameter's enum (`=MATCH(A1,B:B,5)`).
22
+ *
23
+ * A warning, never an error — nothing here stops a formula being committed — and deliberately
24
+ * narrow, so it is never wrong:
25
+ * - Only a LITERAL is judged: a number (or `-` and a number) or a string, alone in its argument. A
26
+ * reference, an expression or an array is the user's and is never second-guessed.
27
+ * - Only a literal of the enum's own type: `"1"` at a numeric slot may coerce to a member, so it is
28
+ * left alone. Strings compare case-insensitively, as the gate does.
29
+ * - Every enum counts — gated, `ReportType<E>` and `E | Scalar` alike. A gated slot answers `#VALUE!`
30
+ * anyway; at the others an out-of-set literal silently does something (`PMT`'s type `2` reads as 1),
31
+ * which is exactly when a warning helps.
32
+ *
33
+ * Offsets start after the leading formula prefix (`base`), as the other caret helpers' do.
34
+ */
35
+ export declare const findEnumLints: (calc: ICalculation, tokens: readonly ICalculation.FormulaToken[], base: number) => EnumLint[];
36
+ //# sourceMappingURL=formulaLint.d.ts.map
@@ -80,6 +80,13 @@ export declare const PAREN_EMPHASIS_SLOT: CSSProperties;
80
80
  export declare const parenEmphasisGlyph: (hue: string) => CSSProperties;
81
81
  /** An unbalanced paren (no partner) — reuses the reference red so it reads as an error. */
82
82
  export declare const PAREN_ERROR_COLOR = "var(--sxl-color-error, #d93025)";
83
+ /**
84
+ * A lint WARNING (`findEnumLints`) — amber, not the error red: the formula is legal and commits.
85
+ * The flagged token is underlined with it, and the signature preview's message is set in it.
86
+ */
87
+ export declare const LINT_WARNING_COLOR = "var(--sxl-color-warning, #b26a00)";
88
+ /** The style that marks a linted token: a wavy underline, leaving its syntax color alone. */
89
+ export declare const LINT_UNDERLINE_STYLE: CSSProperties;
83
90
  /** The paren pairing of a token stream — see {@link computeParenMatch}. */
84
91
  export interface ParenMatch {
85
92
  /** Pairs each `(`/`)` token index with its partner (both directions). */
@@ -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
  /**
@@ -9,9 +9,10 @@ export * from './FunctionPreviewPanel';
9
9
  export * from './functionHint';
10
10
  export * from './functionArgs';
11
11
  export * from './NamedItemsPanel';
12
+ export * from './NamedItemLabel';
12
13
  export * from './NamedHintPanel';
13
14
  export * from './EditorCommands';
14
- export * from './useProtectedEditNotice';
15
+ export * from './useEditRejectedNotice';
15
16
  export * from './SheetCellEditorLayer';
16
17
  export * from './SheetReferenceLayer';
17
18
  export * from './SheetReferenceHeaderLayer';
@@ -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