@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
@@ -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
@@ -102,7 +102,8 @@ export interface UseFormulaInputOptions {
102
102
  * Default `false` (single range; a pick replaces). Named to match the picker tier's `allowMulti`
103
103
  * (`useSelectionPointer` / `RangesPickerLayer`) — it rides the bus state to gate the grid gesture.
104
104
  *
105
- * `'reference'` grammar only; a `'formula'` field always allows every reference its expression holds.
105
+ * A `'formula'` field defaults to `true` and gates only the pick: `false` makes Ctrl+click replace
106
+ * rather than add a reference, while a typed expression may still hold any number of them.
106
107
  */
107
108
  allowMulti?: boolean;
108
109
  /**
@@ -161,6 +162,19 @@ export interface UseFormulaInputOptions {
161
162
  * whoever reads it — and the table-resize shape (Excel's `$A$3:$D$9`).
162
163
  */
163
164
  pickAs?: 'absolute' | 'relative';
165
+ /**
166
+ * Whether a pick that is exactly a dynamic array's spill writes the anchor plus `#` (`D2#`) instead
167
+ * of its address. Default `false`.
168
+ *
169
+ * @remarks
170
+ * `D2#` follows the spill as it grows or shrinks; `D2:E4` stays the extent it was picked at. The
171
+ * formula bar and in-grid editor always write `#`; Excel's range fields (conditional formatting,
172
+ * defined names, dialogs) do not, which is the default here. A name defined over the same extent
173
+ * does not win here the way it does in the cell editor — fields never write names for a pick. A
174
+ * single cell, an array-entered block and a blocked spill always write an address. The `$` style
175
+ * follows {@link pickAs} and re-scoping as for an address, on the anchor (`$D$2#`).
176
+ */
177
+ pickSpills?: boolean;
164
178
  /**
165
179
  * The COMMIT channel: fires with the final parsed value at each commit point — a done key
166
180
  * (Enter/Tab/Escape, from the field or the GRID), the explicit {@link FormulaInputApi.commit}
@@ -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,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`.
@@ -54,6 +55,12 @@ export interface FormulaInputProps extends Omit<React.InputHTMLAttributes<HTMLIn
54
55
  * table-resize shape. See `UseFormulaInputOptions.pickAs`.
55
56
  */
56
57
  pickAs?: 'absolute' | 'relative';
58
+ /**
59
+ * Whether a pick that is exactly a dynamic array's spill writes `D2#` instead of its address.
60
+ * Default `false`, as Excel's range fields; the cell editor always does. See
61
+ * `UseFormulaInputOptions.pickSpills`.
62
+ */
63
+ pickSpills?: boolean;
57
64
  /**
58
65
  * Allow a comma-separated multi-range reference (typed, or Ctrl+click-picked). Default `false`.
59
66
  * `'reference'` grammar only — a `'formula'` field always allows every reference its expression holds.
@@ -66,6 +73,12 @@ export interface FormulaInputProps extends Omit<React.InputHTMLAttributes<HTMLIn
66
73
  * `UseFormulaInputOptions.allowCrossSheet`; independent of {@link allowMulti}.
67
74
  */
68
75
  allowCrossSheet?: boolean;
76
+ /**
77
+ * The call argument this field's whole text is — the Function Arguments form's rows. An empty field
78
+ * then offers, in its hint popup, the values the parameter is limited to. See
79
+ * `UseFormulaHintsOptions.getArgument`.
80
+ */
81
+ argument?: FormulaArgument | null;
69
82
  }
70
83
  /**
71
84
  * 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. */
@@ -1,4 +1,4 @@
1
- import { IRange, ICell, ICellRanges, ICellRange, IColor, ITable, INamedCollection, IStyleCollection, IStyle, IBorder, ITheme, IThemeCollection, IFunction, IFunctionCollection, IWorkbook } from '@sheetxl/sdk';
1
+ import { IRange, ICell, ICellRanges, ICellRange, IColor, ITable, INamedCollection, IStyleCollection, IStyle, IBorders, ITheme, IThemeCollection, IFunction, IFunctionCollection, IWorkbook } from '@sheetxl/sdk';
2
2
  /**
3
3
  * For providing Adjustable Color Commands additional rendering capabilities.
4
4
  *
@@ -18,11 +18,11 @@ export interface Color {
18
18
  }
19
19
  export interface Border {
20
20
  readonly autoColor: IColor;
21
- readonly autoStyle: IBorder.StrokeStyle;
22
- readonly quickBorder?: Partial<IBorder.Properties>;
21
+ readonly autoStyle: IBorders.StrokeStyle;
22
+ readonly quickBorder?: Partial<IBorders.Properties>;
23
23
  readonly schemeLookup: IColor.SchemeLookup;
24
- createBorder: (update: IBorder.Properties) => IBorder;
25
- onBorderSelect: (border: Partial<IBorder.Properties>) => void;
24
+ createBorder: (update: IBorders.Properties) => IBorders;
25
+ onBorderSelect: (border: Partial<IBorders.Properties>) => void;
26
26
  }
27
27
  export interface NamedStyle {
28
28
  readonly named: () => IStyle.INamed;
@@ -77,11 +77,153 @@ export interface ResizeHeaderContext {
77
77
  export interface NewTable {
78
78
  ranges: ICellRanges;
79
79
  hasHeader?: boolean;
80
+ /** The table's name. When omitted the next free default name is used. */
81
+ name?: string;
80
82
  }
81
83
  export interface SelectedRange {
82
84
  range: ICellRange;
83
85
  cell?: ICell.Address;
84
86
  }
87
+ /**
88
+ * What the Series dialog produces — a {@link IAutoFill.Preset} named by id, the direction it runs,
89
+ * and the fields the chosen type declares.
90
+ *
91
+ * @remarks
92
+ * The preset is named rather than passed because this crosses a command boundary: the id survives
93
+ * into a transaction's operation params and back, where a filler instance would not.
94
+ */
95
+ export interface FillSeriesOptions {
96
+ /** {@link IAutoFill.Preset.id} of the chosen fill type. */
97
+ presetId: string;
98
+ /** Which way the series runs through the selection. Always `Down` or `Right` from a selection. */
99
+ direction: IRange.Direction;
100
+ /** Fit the series to the values rather than stepping from them. */
101
+ trend?: boolean;
102
+ /** {@link IAutoFill.Options.stepValue} — meaningless, and hidden, unless the type declares it. */
103
+ stepValue?: number;
104
+ /** {@link IAutoFill.Options.stopValue} */
105
+ stopValue?: number;
106
+ }
107
+ /**
108
+ * The two ranges a fill actually runs over — what it reads, and what it writes.
109
+ *
110
+ * @remarks
111
+ * Worth showing, because they are not the selection and not obvious from it: the template is the
112
+ * selection's leading CONTENTFUL part, so typing a second seed value changes what the fill reads.
113
+ * Excel keeps this hidden and always seeds from the first cell, which is why nobody can tell what
114
+ * its dialog is about to do.
115
+ */
116
+ export interface FillSeriesRanges {
117
+ /** Address of the cells the series is read from. */
118
+ template: string;
119
+ /** Address of the cells the fill covers — the selection. */
120
+ destination: string;
121
+ /** How many cells deep the template is along the fill direction. */
122
+ templateSize: number;
123
+ /** How many cells deep the destination is — the template included. */
124
+ size: number;
125
+ }
126
+ /**
127
+ * Everything the Series dialog needs to offer, preview and describe a fill, without reaching into
128
+ * the model itself.
129
+ *
130
+ * @remarks
131
+ * The dialog is presentation: which types apply, what a setting would produce, and where the fill
132
+ * would land are all questions about the sheet, and they are answered here so the dialog does not
133
+ * have to iterate cells to ask them.
134
+ */
135
+ export interface FillSeries {
136
+ /** The selection the fill runs over — the dialog shows its address. */
137
+ readonly range: ICellRange;
138
+ /**
139
+ * The direction the selection's own shape implies, and the dialog's initial value.
140
+ *
141
+ * @remarks
142
+ * A single column runs down and a single row runs across; a block is ambiguous and Excel's own
143
+ * default (down) is taken, which is why the dialog still offers the choice.
144
+ */
145
+ readonly direction: IRange.Direction;
146
+ /**
147
+ * The preset ids that can be offered for `direction`, in registry order.
148
+ *
149
+ * @remarks
150
+ * A preset applies when it applies to ANY line of the selection — a selection holding a column of
151
+ * dates beside a column of numbers offers the date fills, and the numeric column falls back to a
152
+ * copy rather than the entry being greyed for both.
153
+ */
154
+ offered: (direction: IRange.Direction) => readonly string[];
155
+ /**
156
+ * The addresses a fill in `direction` would read and write, or `null` where there is nothing to
157
+ * fill — which is also how a surface knows a direction is not on offer at all.
158
+ */
159
+ resolve: (direction: IRange.Direction) => FillSeriesRanges | null;
160
+ /**
161
+ * A projection of what `options` would fill, or `null` where there is nothing to fill.
162
+ *
163
+ * @remarks
164
+ * Nothing is committed and no undo entry is created; the cells are computed on demand, so reading
165
+ * the handful the dialog shows costs that handful. See {@link ICellRange.AutoFillOptions.preview}.
166
+ */
167
+ preview: (options: FillSeriesOptions) => ICellRange | null;
168
+ }
169
+ /**
170
+ * A fill the fill menu can run — a chosen entry, as data.
171
+ *
172
+ * @remarks
173
+ * The entries are presets plus a content selector: *Copy Cells* is the `copy` preset, *Fill
174
+ * Formatting Only* is `Formats` with no preset (no series is read), *Fill Without Formatting* is
175
+ * the `series` preset with `Values`.
176
+ */
177
+ export interface FillMenuOptions {
178
+ /**
179
+ * {@link IAutoFill.Preset.id} of the fill type. Omit for a formatting-only fill, which reads no
180
+ * series at all.
181
+ */
182
+ presetId?: string;
183
+ /**
184
+ * {@link ICellRange.AutoFillOptions.type} — `Formats` for *Fill Formatting Only*, `Values` for
185
+ * *Fill Without Formatting*; omitted for everything.
186
+ */
187
+ type?: ICell.Content;
188
+ }
189
+ /**
190
+ * Everything the fill menu — the right-drag of the fill handle — needs to offer and run a fill.
191
+ *
192
+ * @remarks
193
+ * The drag has already decided what is read, what is covered and which way, so unlike
194
+ * {@link FillSeries} nothing here is asked per direction. The menu is presentation: it lists the
195
+ * entries it wants in the order it wants, greys those not in `offered`, and calls back.
196
+ */
197
+ export interface FillMenu {
198
+ /** The cells the fill reads — the selection the handle was dragged from. */
199
+ readonly template: ICellRange;
200
+ /** The cells the fill covers, the template included — where the handle was released. */
201
+ readonly destination: ICellRange;
202
+ /** Which way the drag went. */
203
+ readonly direction: IRange.Direction;
204
+ /**
205
+ * The {@link IAutoFill.Preset.id}s that can be offered for the template, in registry order — see
206
+ * {@link IAutoFill.DefaultCriteria.offered}. Empty for a template with nothing in it.
207
+ */
208
+ readonly offered: readonly string[];
209
+ /**
210
+ * Run the chosen fill and select the destination, as a left-drag would. A refused fill (a merge
211
+ * the destination cannot hold) is reported, not thrown.
212
+ */
213
+ fill: (options: FillMenuOptions) => Promise<void>;
214
+ /** Open the Series dialog on the drag's template, destination and direction. */
215
+ series: () => void;
216
+ /**
217
+ * The menu closed without choosing — the drag is over and nothing is filled.
218
+ *
219
+ * @remarks
220
+ * The grid keeps the drag's dashed preview up while a choice is pending, since it shows which
221
+ * cells the menu is about; this is what lets it go. A no-op once {@link fill} or {@link series}
222
+ * was called — those settle the drag themselves, the dialog included — so a menu can call it
223
+ * from every close path without caring which one it was.
224
+ */
225
+ cancel: () => void;
226
+ }
85
227
  /**
86
228
  * The function-discovery context the `insertFunction` command carries — everything a picker (the
87
229
  * category menus, and the Insert Function dialog) needs to browse the workbook's functions, built-in
@@ -15,7 +15,12 @@ export * from './editableLabel';
15
15
  export * from './tabStrip';
16
16
  export * from './icons';
17
17
  export * from './layer/ConditionalIcons';
18
+ export * from './picker';
19
+ export * from './checklist';
18
20
  export * from './conditionalFormat';
21
+ export * from './autoFill';
22
+ export * from './protection';
23
+ export * from './externalLink';
19
24
  export * from './clipboard';
20
25
  export * from './commands';
21
26
  export * from './undo';
@@ -42,6 +42,8 @@ export declare class _WorkbookIO implements IWorkbookIO {
42
42
  addListeners(listeners: IWorkbookIO.Listeners, _options?: IListener.Options): IListener.Remove;
43
43
  /** @inheritdoc IWorkbookIO.addCommitListener */
44
44
  addCommitListener(listener: ITransaction.ICommitSource.IListeners): IListener.Remove;
45
+ /** {@inheritDoc IWorkbookIO.isIWorkbookIO} */
46
+ get isIWorkbookIO(): true;
45
47
  }
46
48
  /**
47
49
  * A Singleton instance that lazy wraps '@sheetxl/io/WorkbookIO'.
@@ -2,8 +2,9 @@ import { default as React } from 'react';
2
2
  import { RangeCoords } from '@sheetxl/utils';
3
3
  import { ICalculation, IRange, ISheet } from '@sheetxl/sdk';
4
4
  import { StickyState, GridPlacement, LayerProps } from '@sheetxl/grid-react';
5
+ import { ValidationMark } from './validationMark';
5
6
  /** The kind of annotation a cell carries (drives the default tip styling). */
6
- export type CellErrorKind = 'error' | 'warning' | 'circular';
7
+ export type CellErrorKind = 'error' | 'warning' | 'circular' | 'validation';
7
8
  /** The active hovered annotation passed to a custom {@link CellErrorLayerProps.renderTip}. */
8
9
  export interface CellErrorTip {
9
10
  /** The hovered cell as a range (the tip's anchor). */
@@ -23,6 +24,11 @@ export interface CellErrorTip {
23
24
  path?: readonly IRange.CellCoords[];
24
25
  /** The cycle's representative — where a downstream cell is pointed. `kind === 'circular'` only. */
25
26
  representative?: IRange.CellCoords | null;
27
+ /**
28
+ * How the value fails its data validations, the mark this tip explains. `kind === 'validation'`
29
+ * only; `message` is then the answering rule's alert, or its description when it has none.
30
+ */
31
+ validation?: ValidationMark;
26
32
  }
27
33
  /**
28
34
  * Props for {@link CellErrorLayer}.
@@ -51,8 +57,9 @@ export interface CellErrorLayerProps extends Omit<LayerProps, 'children'> {
51
57
  /**
52
58
  * A grid layer that shows a **hover tooltip on cells carrying errors / warnings**. A thin
53
59
  * {@link HoverTipLayer} whose probe asks the sheet — `getErrors()`, then
54
- * `getCircularReference()`, then `getWarnings()` — and anchors on the cell's own range; the tip
55
- * stays open while hovered. `getComments()` is not yet wired (unimplemented in the model).
60
+ * `getCircularReference()`, then the data validations the value fails, then `getWarnings()` — and
61
+ * anchors on the cell's own range; the tip stays open while hovered. `getComments()` is not yet
62
+ * wired (unimplemented in the model).
56
63
  *
57
64
  * @remarks
58
65
  * A cell in a reference cycle, or downstream of one, is a third source (`kind: 'circular'`)
@@ -0,0 +1,52 @@
1
+ import { default as React } from 'react';
2
+ import { RangeCoordValue } from '@sheetxl/utils';
3
+ import { ICellRegion, ISheet, ISheetView } from '@sheetxl/sdk';
4
+ import { LayerProps } from '@sheetxl/grid-react';
5
+ /**
6
+ * The regions to punch out of the hatch, coalesced by appearance.
7
+ *
8
+ * @internal Exported for its unit test; not part of the package's API.
9
+ *
10
+ * @remarks
11
+ * What the engine hands over is already a partition of the QUERIED range — clipped to it, with
12
+ * same-identity fragments merged into maximal rectangles. Two things it deliberately does NOT do,
13
+ * because they are questions about rendering rather than about the model:
14
+ *
15
+ * - **Adjacent blocks with different identities stay apart.** Two unlocked ranges side by side are
16
+ * two regions; so are the three strips an overlapping pair partitions into (A-only, A∩B, B-only).
17
+ * Placed as-is that draws outlines on seams that are not boundaries of anything a user drew.
18
+ * - So they are merged **by appearance**, not by identity — see {@link appearanceOf}.
19
+ *
20
+ * There is nothing to clip here: `getRegions` bounds its result to the range it was asked about,
21
+ * which is this pane's visible range. (Pinned by `sdk/__tests__/anchored/protectedRange.regions.test.ts`,
22
+ * because this layer would otherwise place a rect as tall as the sheet.)
23
+ */
24
+ export declare const visibleHoles: (regions: readonly ICellRegion[]) => RangeCoordValue[];
25
+ export interface ProtectionLayerProps extends LayerProps {
26
+ /** Class for the layer (devtools identification). */
27
+ className?: string;
28
+ /** The sheet whose locked area is hatched. */
29
+ sheet: ISheet;
30
+ /** The view carrying `isShowLockedShading()` — the toggle this layer draws for. */
31
+ sheetView: ISheetView;
32
+ }
33
+ /**
34
+ * The **locked-cell hatch** — the sheet's protected area, with the unlocked ranges cut out of it.
35
+ *
36
+ * @remarks
37
+ * Not an Excel feature; Google Sheets' *View › Show › Protected ranges* is the precedent.
38
+ *
39
+ * Drawn only on a sheet that is actually ENFORCING — not one that is unprotected, and not one that
40
+ * is paused. The hatch answers "what can't I edit right now?", and on both of those the answer is
41
+ * nothing; a paused sheet that kept its hatch would look locked while every cell takes an edit.
42
+ * (The pane's paused banner, not this layer, is what says the lock is still configured.)
43
+ *
44
+ * One `<pattern>` fill over the whole pane with a `<mask>` punching out the unlocked regions from
45
+ * {@link ICellRange.Feature.Unlock}, plus a thin outline on each hole — NOT a rect per cell. One
46
+ * pattern over one box is also what keeps the hatch CONTINUOUS: tiling it per region would restart
47
+ * the pattern's origin at every rect, and the diagonals would step at each boundary.
48
+ *
49
+ * Passive paint (`pointerEvents: none`), below the selection.
50
+ */
51
+ export declare const ProtectionLayer: React.MemoExoticComponent<(props: ProtectionLayerProps) => React.JSX.Element | null>;
52
+ //# sourceMappingURL=ProtectionLayer.d.ts.map
@@ -0,0 +1,61 @@
1
+ import { default as React } from 'react';
2
+ import { CellCoords } from '@sheetxl/utils';
3
+ import { ISheet, IDataValidation, IRange } from '@sheetxl/sdk';
4
+ import { IEditable, LayerProps } from '@sheetxl/grid-react';
5
+ /** What the probe hands the button: the validations to offer, and the cell they belong to. */
6
+ export interface ValidationDropdown {
7
+ /** The list validation the button opens a picker for: the first covering one, by priority. */
8
+ dataValidation: IDataValidation;
9
+ /**
10
+ * Every list validation covering the cell, in priority order. The picker offers the first one's
11
+ * items, intersected with the others' when there are several.
12
+ */
13
+ dataValidations: readonly IDataValidation[];
14
+ /** The cell holding it — the anchor cell when the validation sits on a merge. */
15
+ cell: CellCoords;
16
+ /** The merge that cell anchors, when it anchors one. */
17
+ merge?: IRange.Coords;
18
+ }
19
+ export interface ValidationDropdownLayerProps extends Omit<LayerProps, 'children'> {
20
+ /** Class for the floated button container. */
21
+ className?: string;
22
+ /** Style for the floated button container. */
23
+ style?: React.CSSProperties;
24
+ /** The sheet whose selection is followed. */
25
+ sheet: ISheet;
26
+ /**
27
+ * The editable a pick is entered through — the sheet's shared one, so a pick is a typed entry:
28
+ * coerced, formatted and checked as one. Without it the button opens nothing.
29
+ */
30
+ editable: IEditable<any, string, any> | null;
31
+ /** Width (px, unzoomed) of the button. @defaultValue 17 */
32
+ dropdownWidth?: number;
33
+ /**
34
+ * Intercept the press instead of opening the built-in picker.
35
+ *
36
+ * @remarks
37
+ * By default the button opens the shared list picker ({@link useValidationPicker}). Supply this to
38
+ * take the press over entirely — the built-in picker is then never opened, and presenting the list
39
+ * is yours.
40
+ */
41
+ onOpenDropdown?: (cell: CellCoords, dataValidation: IDataValidation) => void;
42
+ }
43
+ /**
44
+ * The **list-validation dropdown** on the selected cell — a {@link RangeFloatLayer} activated by the
45
+ * selection.
46
+ *
47
+ * @remarks
48
+ * Deliberately a separate layer from `ValidationIndicatorLayer`, because the two marks answer
49
+ * different questions and so are drawn by different mechanisms. The invalid-value mark is a property
50
+ * of a cell's VALUE: it belongs wherever one is in view, as cached tile snapshots that survive scroll.
51
+ * The dropdown appears on the ACTIVE CELL ALONE — which is the expensive predicate, since it would
52
+ * dirty a tile on every selection move — and it hugs the OUTSIDE of the cell's right edge (covering
53
+ * the neighbor, as Excel does) so it has to escape the pane clip. Tile and float; they share a sheet
54
+ * and nothing else.
55
+ *
56
+ * On a **merge** the affordance belongs to the merge, not to its anchor corner cell: the button hugs
57
+ * the MERGE's right edge, centered on it. It is a fixed square whatever the row or merge height —
58
+ * stretching it to fit would turn a tall merge into a full-height bar.
59
+ */
60
+ export declare const ValidationDropdownLayer: React.MemoExoticComponent<(props: ValidationDropdownLayerProps) => React.JSX.Element>;
61
+ //# sourceMappingURL=ValidationDropdownLayer.d.ts.map