@sheetxl/react 0.7.28-beta.3 → 0.8.0-beta.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (30) hide show
  1. package/browser/cjs/index.cjs +13 -11
  2. package/browser/esm/{DOpVczcEx-CkZUxD.mjs → SJMJzBwlXTJ9QIO5.mjs} +1 -1
  3. package/browser/esm/index.mjs +4233 -3681
  4. package/node/esm/{CZvaQUM2sezrZ_Yy.mjs → DAE_NG8D9uT50zUH.mjs} +1 -1
  5. package/node/esm/index.mjs +4279 -3722
  6. package/package.json +6 -6
  7. package/resources/locales/de/ui.msg.json +5 -0
  8. package/resources/locales/de/workbook.cmd.json +16 -0
  9. package/resources/locales/en/ui.msg.json +5 -0
  10. package/resources/locales/en/workbook.cmd.json +16 -0
  11. package/types/src/cell/SheetCellRenderer.d.ts +15 -0
  12. package/types/src/conditionalFormat/IconSetGlyphs.d.ts +38 -0
  13. package/types/src/conditionalFormat/index.d.ts +2 -0
  14. package/types/src/index.d.ts +2 -0
  15. package/types/src/layer/CellErrorLayer.d.ts +23 -6
  16. package/types/src/layer/CircularIndicatorLayer.d.ts +34 -0
  17. package/types/src/layer/ConditionalBarLayer.d.ts +2 -1
  18. package/types/src/layer/ConditionalIcons.d.ts +66 -1
  19. package/types/src/layer/ConditionalIconsLayer.d.ts +3 -1
  20. package/types/src/layer/ValidationDropdownLayer.d.ts +51 -0
  21. package/types/src/layer/ValidationIndicatorLayer.d.ts +9 -22
  22. package/types/src/layer/index.d.ts +4 -0
  23. package/types/src/layer/useValidationPicker.d.ts +54 -0
  24. package/types/src/layer/validationList.d.ts +84 -0
  25. package/types/src/list/SheetValueList.d.ts +93 -0
  26. package/types/src/list/index.d.ts +2 -0
  27. package/types/src/sheet/ConditionalFormatPresets.d.ts +43 -6
  28. package/types/src/sheet/ISheetElement.d.ts +10 -0
  29. package/types/src/sheet/circularReferences.d.ts +26 -0
  30. package/types/src/sheet/index.d.ts +1 -0
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@sheetxl/react",
3
3
  "description": "React - React components needed to build advanced grid and spreadsheet UIs.",
4
- "version": "0.7.28-beta.3",
4
+ "version": "0.8.0-beta.1",
5
5
  "license": "SEE LICENSE IN <LICENSE>",
6
6
  "type": "module",
7
7
  "exports": {
@@ -48,11 +48,11 @@
48
48
  "@dnd-kit/modifiers": "^9.0.0",
49
49
  "@dnd-kit/sortable": "^10.0.0",
50
50
  "@dnd-kit/utilities": "^3.2.2",
51
- "@sheetxl/grid-react": "^0.7.28-beta.3",
52
- "@sheetxl/io": "^0.7.28-beta.3",
53
- "@sheetxl/sdk": "^0.7.28-beta.3",
54
- "@sheetxl/utils": "^0.7.28-beta.3",
55
- "@sheetxl/utils-react": "^0.7.28-beta.3",
51
+ "@sheetxl/grid-react": "^0.8.0-beta.1",
52
+ "@sheetxl/io": "^0.8.0-beta.1",
53
+ "@sheetxl/sdk": "^0.8.0-beta.1",
54
+ "@sheetxl/utils": "^0.8.0-beta.1",
55
+ "@sheetxl/utils-react": "^0.8.0-beta.1",
56
56
  "clsx": "^2.1.1",
57
57
  "react-merge-refs": "^3.0.2",
58
58
  "react-moveable": "^0.56.0",
@@ -23,6 +23,11 @@
23
23
  "chart.type.scatterLinesMarkersSmooth": "Punktdiagramm mit Datenpunkten und interpolierten Linien",
24
24
  "chart.type.scatterLinesSmooth": "Punktdiagramm mit interpolierten Linien",
25
25
  "chart.type.scatterMarkers": "Punktdiagramm mit Datenpunkten",
26
+ "circular.converged": "{count, plural, one {Konvergiert nach # Iteration} other {Konvergiert nach # Iterationen}}",
27
+ "circular.reads": "Liest einen Zirkelbezug in",
28
+ "circular.title": "Zirkelbezug",
29
+ "circular.unconverged": "{count, plural, one {Nicht konvergiert nach # Iteration} other {Nicht konvergiert nach # Iterationen}} (letzte Änderung {change})",
30
+ "circular.unconvergedNoChange": "{count, plural, one {Nicht konvergiert nach # Iteration} other {Nicht konvergiert nach # Iterationen}}",
26
31
  "clipboard.pasting": "Wird eingefügt...",
27
32
  "dialog.activate": "Aktivieren",
28
33
  "dialog.activateTask.inputLabel": "Aufgabenname",
@@ -222,6 +222,22 @@
222
222
  "icon": "Calculate",
223
223
  "shortcut": "ctrl+alt+F9"
224
224
  },
225
+ "calcModeAutomatic": {
226
+ "label": "Automatisch",
227
+ "description": "Formeln neu berechnen, sobald sich ihre Eingaben ändern."
228
+ },
229
+ "calcModeAutomaticExceptTables": {
230
+ "label": "Automatisch außer bei Datentabellen",
231
+ "description": "Formeln neu berechnen, sobald sich ihre Eingaben ändern, mit Ausnahme von Was-wäre-wenn-Datentabellen. Ohne Datentabellen entspricht dies „Automatisch“."
232
+ },
233
+ "calcModeManual": {
234
+ "label": "Manuell",
235
+ "description": "Nur auf Anforderung neu berechnen (F9). Bis dahin bleiben abhängige Formeln nach einer Änderung veraltet."
236
+ },
237
+ "calcIterativeToggle": {
238
+ "label": "Iterative Berechnung aktivieren",
239
+ "description": "Zirkelbezüge durch wiederholtes Neuberechnen auflösen, bis sie sich stabilisieren oder die maximale Iterationszahl erreicht ist. Ausgeschaltet ergibt ein Zirkelbezug 0."
240
+ },
225
241
  "selectDirectPrecedents": {
226
242
  "label": "Direkte Vorgänger auswählen",
227
243
  "description": "Die Zellen auswählen, auf die die Formeln in der Auswahl direkt verweisen.",
@@ -23,6 +23,11 @@
23
23
  "chart.type.scatterLinesMarkersSmooth": "Scatter Chart with Markers and Smooth Lines",
24
24
  "chart.type.scatterLinesSmooth": "Scatter Chart with Smooth Lines",
25
25
  "chart.type.scatterMarkers": "Scatter Chart with Markers",
26
+ "circular.converged": "{count, plural, one {Converged after # iteration} other {Converged after # iterations}}",
27
+ "circular.reads": "Reads a circular reference at",
28
+ "circular.title": "Circular reference",
29
+ "circular.unconverged": "{count, plural, one {Did not converge after # iteration} other {Did not converge after # iterations}} (last change {change})",
30
+ "circular.unconvergedNoChange": "{count, plural, one {Did not converge after # iteration} other {Did not converge after # iterations}}",
26
31
  "clipboard.pasting": "Pasting...",
27
32
  "dialog.activate": "Activate",
28
33
  "dialog.activateTask.inputLabel": "Task Name",
@@ -222,6 +222,22 @@
222
222
  "icon": "Calculate",
223
223
  "shortcut": "ctrl+alt+F9"
224
224
  },
225
+ "calcModeAutomatic": {
226
+ "label": "Automatic",
227
+ "description": "Recalculate formulas whenever their inputs change."
228
+ },
229
+ "calcModeAutomaticExceptTables": {
230
+ "label": "Automatic Except for Data Tables",
231
+ "description": "Recalculate formulas whenever their inputs change, except what-if data tables. Without data tables this is the same as Automatic."
232
+ },
233
+ "calcModeManual": {
234
+ "label": "Manual",
235
+ "description": "Recalculate only when you ask (F9). Edits leave dependent formulas out of date until then."
236
+ },
237
+ "calcIterativeToggle": {
238
+ "label": "Enable Iterative Calculation",
239
+ "description": "Resolve circular references by recalculating them repeatedly until they settle or the maximum iterations is reached. Off, a circular reference evaluates to 0."
240
+ },
225
241
  "selectDirectPrecedents": {
226
242
  "label": "Select Direct Precedents",
227
243
  "description": "Select the cells directly referenced by the formulas in the selection.",
@@ -10,6 +10,21 @@ export interface SheetCellRendererProps extends CellRendererProps<ICell> {
10
10
  * If true, show zero values
11
11
  */
12
12
  showZeros?: boolean;
13
+ /**
14
+ * Allow text that does not fit to paint over its empty neighbors, as it does in a sheet.
15
+ *
16
+ * @defaultValue true
17
+ *
18
+ * @remarks
19
+ * Set `false` when the cell is being drawn somewhere its own sheet's geometry does not apply — a
20
+ * list or menu built from real cells. The extrusion the SDK reports (`ICell.getTextOverflow`) is
21
+ * measured against the SOURCE column's width and ITS neighbors, so away from the sheet it places
22
+ * text against a geometry the surrounding pixels do not have. With this off the renderer lays out
23
+ * purely in the bounds it is given, and text that does not fit is clipped.
24
+ *
25
+ * Only text can extrude — a number or date that does not fit is replaced by `#` either way.
26
+ */
27
+ allowTextOverflow?: boolean;
13
28
  /**
14
29
  * Ability to query the theme colors.
15
30
  * Note - There are also css variables that can be used to style using doc theme colors
@@ -0,0 +1,38 @@
1
+ import { default as React } from 'react';
2
+ import { ConditionalIconSpec } from '../layer/ConditionalIcons';
3
+ export interface IconSetGlyphsProps extends React.HTMLAttributes<HTMLDivElement> {
4
+ /**
5
+ * The icons to draw, lowest band first — `resolveIconSetIcons` or `getConditionalIconSet`.
6
+ * A `null` is a band that draws nothing; it keeps its slot so the row still reads as the set.
7
+ */
8
+ icons: readonly (ConditionalIconSpec | null)[];
9
+ /**
10
+ * `'ascending'` draws the lowest band first, the way the editor's threshold rows read;
11
+ * `'descending'` draws the highest first, the way Excel's gallery shows a set (up, side, down).
12
+ *
13
+ * @defaultValue 'ascending'
14
+ */
15
+ order?: 'ascending' | 'descending';
16
+ /**
17
+ * Glyph size in px.
18
+ *
19
+ * @defaultValue 16
20
+ */
21
+ size?: number;
22
+ /**
23
+ * Gap between glyphs in px.
24
+ *
25
+ * @defaultValue 4
26
+ */
27
+ gap?: number;
28
+ }
29
+ /**
30
+ * A rule's icons in a row — the picture of an icon set wherever one is shown.
31
+ *
32
+ * @remarks
33
+ * Plain DOM: the same row serves the task pane, the menu gallery, the rule preview and any host
34
+ * without a UI kit. It draws from the table the sheet paints from, so what is shown here is what
35
+ * lands in the cells.
36
+ */
37
+ export declare const IconSetGlyphs: React.NamedExoticComponent<IconSetGlyphsProps>;
38
+ //# sourceMappingURL=IconSetGlyphs.d.ts.map
@@ -0,0 +1,2 @@
1
+ export * from './IconSetGlyphs';
2
+ //# sourceMappingURL=index.d.ts.map
@@ -2,6 +2,7 @@ export { LicenseManager, type LicenseDetails } from '@sheetxl/sdk';
2
2
  export * from './context';
3
3
  export * from './cell';
4
4
  export * from './editor';
5
+ export * from './list';
5
6
  export * from './selection';
6
7
  export * from './border';
7
8
  export * from './sheet';
@@ -15,6 +16,7 @@ export * from './editableLabel';
15
16
  export * from './tabStrip';
16
17
  export * from './icons';
17
18
  export * from './layer/ConditionalIcons';
19
+ export * from './conditionalFormat';
18
20
  export * from './clipboard';
19
21
  export * from './commands';
20
22
  export * from './undo';
@@ -1,9 +1,9 @@
1
1
  import { default as React } from 'react';
2
2
  import { RangeCoords } from '@sheetxl/utils';
3
- import { ISheet } from '@sheetxl/sdk';
3
+ import { ICalculation, IRange, ISheet } from '@sheetxl/sdk';
4
4
  import { StickyState, GridPlacement, LayerProps } from '@sheetxl/grid-react';
5
5
  /** The kind of annotation a cell carries (drives the default tip styling). */
6
- export type CellErrorKind = 'error' | 'warning';
6
+ export type CellErrorKind = 'error' | 'warning' | 'circular';
7
7
  /** The active hovered annotation passed to a custom {@link CellErrorLayerProps.renderTip}. */
8
8
  export interface CellErrorTip {
9
9
  /** The hovered cell as a range (the tip's anchor). */
@@ -14,6 +14,15 @@ export interface CellErrorTip {
14
14
  kind: CellErrorKind;
15
15
  /** The resolved sticky state (e.g. `state.scrollIntoView()` to reveal the cell). */
16
16
  state: StickyState;
17
+ /** The reference cycle the hovered cell is in, or downstream of. `kind === 'circular'` only. */
18
+ cycle?: ICalculation.ICircularReference;
19
+ /**
20
+ * The cycle as a walk of reads from the hovered cell back to itself (`[A1, B1]` for
21
+ * A1 → B1 → A1) — empty when the cell only READS the cycle. `kind === 'circular'` only.
22
+ */
23
+ path?: readonly IRange.CellCoords[];
24
+ /** The cycle's representative — where a downstream cell is pointed. `kind === 'circular'` only. */
25
+ representative?: IRange.CellCoords | null;
17
26
  }
18
27
  /**
19
28
  * Props for {@link CellErrorLayer}.
@@ -21,7 +30,7 @@ export interface CellErrorTip {
21
30
  export interface CellErrorLayerProps extends Omit<LayerProps, 'children'> {
22
31
  /** Class forwarded to the inner layer's host box (devtools identification). */
23
32
  className?: string;
24
- /** The sheet whose cells are probed for `getErrors()` / `getWarnings()`. */
33
+ /** The sheet whose cells are probed for `getErrors()` / `getCircularReference()` / `getWarnings()`. */
25
34
  sheet: ISheet;
26
35
  /** Which side of the cell the tip attaches to. @defaultValue `{ side: 'r', align: 'start' }` */
27
36
  placement?: GridPlacement;
@@ -41,9 +50,17 @@ export interface CellErrorLayerProps extends Omit<LayerProps, 'children'> {
41
50
  }
42
51
  /**
43
52
  * A grid layer that shows a **hover tooltip on cells carrying errors / warnings**. A thin
44
- * {@link HoverTipLayer} whose probe asks the sheet (`sheet.getCell(coords).getErrors()` /
45
- * `.getWarnings()`) and anchors on the cell's own range; the tip stays open while hovered. `getComments()`
46
- * is not yet wired (unimplemented in the model).
53
+ * {@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).
56
+ *
57
+ * @remarks
58
+ * A cell in a reference cycle, or downstream of one, is a third source (`kind: 'circular'`)
59
+ * rather than a second tip layer — two layers would both open on one cell. A cycle has no
60
+ * start, so a member's tip tells it from the hovered cell (`A1 → B1 → A1`, the engine's own read
61
+ * order via `getPath`); a downstream cell's says which cycle it reads. Every OTHER cell in the
62
+ * tip is a link that selects it — the same affordance from every cell, member or reader. A
63
+ * custom `renderTip` gets the cycle object, the path and the representative.
47
64
  */
48
65
  export declare const CellErrorLayer: React.MemoExoticComponent<(props: CellErrorLayerProps) => React.JSX.Element>;
49
66
  //# sourceMappingURL=CellErrorLayer.d.ts.map
@@ -0,0 +1,34 @@
1
+ import { default as React } from 'react';
2
+ import { ISheet } from '@sheetxl/sdk';
3
+ import { LayerProps } from '@sheetxl/grid-react';
4
+ export interface CircularIndicatorLayerProps extends LayerProps {
5
+ /** Class for the layer (devtools identification). */
6
+ className?: string;
7
+ /** Style for the indicators host box. */
8
+ style?: React.CSSProperties;
9
+ /** The sheet whose circular references are marked. */
10
+ sheet: ISheet;
11
+ /** Size (px, unzoomed) of the corner glyph. @defaultValue 9 */
12
+ markSize?: number;
13
+ /** Inset (px, unzoomed) of the glyph from the cell's top-left corner. @defaultValue 1 */
14
+ inset?: number;
15
+ }
16
+ /**
17
+ * The sheet's **circular-reference marks** — a circle-arrow on every cell that is IN a reference
18
+ * cycle.
19
+ *
20
+ * @remarks
21
+ * A {@link CellTileDiv} fed the sheet's `Feature.Circular` regions (engine-merged blocks: a
22
+ * 28K-cell block downstream of one cycle is one region, not 28K nodes), so a sheet with no cycles
23
+ * costs one lookup per frame. Members only get the glyph — a downstream cell is `0` for the same
24
+ * reason (DESIGN-CIRCULAR-CALC.md §2.1) but the fix is never there, and a column of glyphs reads
25
+ * as a column of problems. The tooltip (`CellErrorLayer`) still answers for downstream cells.
26
+ *
27
+ * The glyph shows in every state; an unresolved cycle — iterative calculation off, or capped
28
+ * before converging — takes the error tone on top. Excel marks nothing on the cell and names
29
+ * one representative in its status bar; the glyph is metadata beside the value, which stays `0`.
30
+ *
31
+ * Passive paint below the selection (`pointerEvents: none`).
32
+ */
33
+ export declare const CircularIndicatorLayer: React.MemoExoticComponent<(props: CircularIndicatorLayerProps) => React.JSX.Element | null>;
34
+ //# sourceMappingURL=CircularIndicatorLayer.d.ts.map
@@ -30,7 +30,8 @@ export interface ConditionalBarLayerProps extends LayerProps {
30
30
  *
31
31
  * It mounts only when a bar is actually in view. {@link useSheetVisibleDecorations} answers that
32
32
  * from the SDK's spatial index before touching a cell, so a sheet with no conditional formatting
33
- * pays a single lookup per frame and renders nothing.
33
+ * pays a single lookup per frame and renders nothing; the same source feeds the
34
+ * {@link CellTileDiv} that snapshots the bars.
34
35
  *
35
36
  * Every number it draws with is resolved by the model
36
37
  * (`ICell.getConditionalDecorations`): the value already sits on its track and zero already
@@ -1,4 +1,4 @@
1
- import { IStyle } from '@sheetxl/sdk';
1
+ import { IStyle, IConditionalFormat } from '@sheetxl/sdk';
2
2
  /**
3
3
  * One icon of a conditional-format icon set: which shape to draw and what to tint it.
4
4
  */
@@ -16,6 +16,27 @@ export interface ConditionalIconSpec {
16
16
  */
17
17
  color: string;
18
18
  }
19
+ /**
20
+ * The tones Excel's built-in sets are drawn in.
21
+ *
22
+ * @remarks
23
+ * Values live in `ConditionalIconsLayer.module.css`, which defaults them to Excel's own colors —
24
+ * a workbook should look like itself before a host says otherwise. Override `--sxl-cf-icon-<tone>`
25
+ * to retint every set at once without touching the sets themselves.
26
+ */
27
+ declare const Tone: {
28
+ readonly bad: "var(--sxl-cf-icon-bad)";
29
+ /** The orange of every arrow between the red and the green in the four- and five-arrow sets. */
30
+ readonly lightBad: "var(--sxl-cf-icon-light-bad)";
31
+ readonly neutral: "var(--sxl-cf-icon-neutral)";
32
+ readonly good: "var(--sxl-cf-icon-good)";
33
+ readonly purple: "var(--sxl-cf-icon-purple)";
34
+ readonly gold: "var(--sxl-cf-icon-gold)";
35
+ readonly gray: "var(--sxl-cf-icon-gray)";
36
+ readonly black: "var(--sxl-cf-icon-black)";
37
+ };
38
+ /** The tone names of {@link ConditionalIconSpec.color}, for naming an icon. */
39
+ export type ConditionalIconTone = keyof typeof Tone;
19
40
  /**
20
41
  * Returns the icon a band of a built-in set draws, or `null` if the band is out of range.
21
42
  *
@@ -31,4 +52,48 @@ export declare const getConditionalIcon: (set: IStyle.IconSet, index: number) =>
31
52
  * Returns every icon of a built-in set, band 0 first — for a picker previewing the set.
32
53
  */
33
54
  export declare const getConditionalIconSet: (set: IStyle.IconSet) => readonly ConditionalIconSpec[];
55
+ /**
56
+ * The icon each band of a rule draws — the set's own, or the band's override — lowest band first.
57
+ *
58
+ * @remarks
59
+ * This is the lookup the sheet performs per cell (`ConditionalFormat._prepareIconSet`), lifted to
60
+ * the whole rule so an editor previews exactly what the grid paints: `reverse` turns the band
61
+ * before the override is read, and an override naming a set the table does not hold, or a slot
62
+ * past its end (Excel's "No Cell Icon"), is `null` — a band that draws nothing.
63
+ *
64
+ * The result is indexed by **threshold row** (`stops[i]`), so it lines up with the editor's rows
65
+ * as authored; reverse it for the way a gallery shows a set (highest first).
66
+ */
67
+ export declare const resolveIconSetIcons: (scale: IConditionalFormat.IconSet) => (ConditionalIconSpec | null)[];
68
+ /**
69
+ * The two halves of an icon's name — its shape (the glyph key without the pack prefix,
70
+ * `arrowUp`) and its tone (`good`) — for a tooltip or a reader to compose "Green Up Arrow" from.
71
+ */
72
+ export declare const describeConditionalIcon: (spec: ConditionalIconSpec) => {
73
+ shape: string;
74
+ tone: ConditionalIconTone;
75
+ };
76
+ /**
77
+ * One icon a band may draw, with the address a rule stores for it.
78
+ */
79
+ export interface ConditionalIconCatalogEntry {
80
+ /** The set the icon is borrowed from — what `IConditionalFormat.IconSet.icon` holds. */
81
+ set: IStyle.IconSet;
82
+ /** The icon's index within that set. */
83
+ id: number;
84
+ spec: ConditionalIconSpec;
85
+ }
86
+ /**
87
+ * Every distinct icon the built-in sets draw, in one list — Excel's fifty-two custom-icon choices,
88
+ * plus one: under the Excel Online palette the five-arrow set's side arrow is orange while the
89
+ * three-arrow set's is yellow.
90
+ *
91
+ * @remarks
92
+ * Derived, not authored: the sets are walked in gallery order, each highest band first (the way
93
+ * a set is pictured), and an icon is listed the first time its shape-and-tint pair appears, under
94
+ * the first set that draws it. Any set that draws the glyph is a valid address on the wire, so
95
+ * the first is as good as another. A test pins the count so a table edit is noticed.
96
+ */
97
+ export declare const ICON_CATALOG: readonly ConditionalIconCatalogEntry[];
98
+ export {};
34
99
  //# sourceMappingURL=ConditionalIcons.d.ts.map
@@ -20,7 +20,9 @@ export interface ConditionalIconsLayerProps extends LayerProps {
20
20
  * telling them to.
21
21
  *
22
22
  * It mounts only when an icon is actually in view; see {@link useSheetVisibleDecorations} for how
23
- * that is answered without touching a cell.
23
+ * that is answered without touching a cell. The same source feeds the {@link CellTileDiv} that
24
+ * snapshots the icons — a cached tile is a reused element, not a frozen picture, so the hover
25
+ * growth still runs on it.
24
26
  *
25
27
  * Which glyph a band draws is a lookup, not a sprite: the model reports the band and the set, and
26
28
  * `getConditionalIcon` maps that onto a shape from the `cf` icon pack plus a tint. The shapes are
@@ -0,0 +1,51 @@
1
+ import { default as React } from 'react';
2
+ import { CellCoords } from '@sheetxl/utils';
3
+ import { ISheet, IDataValidation, IRange } from '@sheetxl/sdk';
4
+ import { LayerProps } from '@sheetxl/grid-react';
5
+ /** What the probe hands the button: the validation to open, and the cell it belongs to. */
6
+ export interface ValidationDropdown {
7
+ /** The list validation the button opens a picker for. */
8
+ dataValidation: IDataValidation;
9
+ /** The cell holding it — the anchor cell when the validation sits on a merge. */
10
+ cell: CellCoords;
11
+ /** The merge that cell anchors, when it anchors one. */
12
+ merge?: IRange.Coords;
13
+ }
14
+ export interface ValidationDropdownLayerProps extends Omit<LayerProps, 'children'> {
15
+ /** Class for the floated button container. */
16
+ className?: string;
17
+ /** Style for the floated button container. */
18
+ style?: React.CSSProperties;
19
+ /** The sheet whose selection is followed. */
20
+ sheet: ISheet;
21
+ /** Width (px, unzoomed) of the button. @defaultValue 17 */
22
+ dropdownWidth?: number;
23
+ /**
24
+ * Intercept the press instead of opening the built-in picker.
25
+ *
26
+ * @remarks
27
+ * By default the button opens the shared list picker ({@link useValidationPicker}). Supply this to
28
+ * take the press over entirely — the built-in picker is then never opened, and presenting the list
29
+ * is yours.
30
+ */
31
+ onOpenDropdown?: (cell: CellCoords, dataValidation: IDataValidation) => void;
32
+ }
33
+ /**
34
+ * The **list-validation dropdown** on the selected cell — a {@link RangeFloatLayer} activated by the
35
+ * selection.
36
+ *
37
+ * @remarks
38
+ * Deliberately a separate layer from `ValidationIndicatorLayer`, because the two marks answer
39
+ * different questions and so are drawn by different mechanisms. The invalid-value mark is a property
40
+ * of a cell's VALUE: it belongs wherever one is in view, as cached tile snapshots that survive scroll.
41
+ * The dropdown appears on the ACTIVE CELL ALONE — which is the expensive predicate, since it would
42
+ * dirty a tile on every selection move — and it hugs the OUTSIDE of the cell's right edge (covering
43
+ * the neighbor, as Excel does) so it has to escape the pane clip. Tile and float; they share a sheet
44
+ * and nothing else.
45
+ *
46
+ * On a **merge** the affordance belongs to the merge, not to its anchor corner cell: the button hugs
47
+ * the MERGE's right edge, but keeps the ANCHOR ROW's height pinned to the top — stretching it to fit
48
+ * would turn a tall merge into a full-height bar.
49
+ */
50
+ export declare const ValidationDropdownLayer: React.MemoExoticComponent<(props: ValidationDropdownLayerProps) => React.JSX.Element>;
51
+ //# sourceMappingURL=ValidationDropdownLayer.d.ts.map
@@ -1,6 +1,5 @@
1
1
  import { default as React } from 'react';
2
- import { CellCoords } from '@sheetxl/utils';
3
- import { ISheet, IDataValidation } from '@sheetxl/sdk';
2
+ import { ISheet } from '@sheetxl/sdk';
4
3
  import { LayerProps } from '@sheetxl/grid-react';
5
4
  export interface ValidationIndicatorLayerProps extends LayerProps {
6
5
  /** Class for the layer (devtools identification). */
@@ -11,31 +10,19 @@ export interface ValidationIndicatorLayerProps extends LayerProps {
11
10
  sheet: ISheet;
12
11
  /** Size (px, unzoomed) of the invalid-value corner mark. @defaultValue 7 */
13
12
  markSize?: number;
14
- /** Width (px, unzoomed) of the list dropdown button. @defaultValue 17 */
15
- dropdownWidth?: number;
16
- /**
17
- * Called when the selected cell's list dropdown is pressed.
18
- *
19
- * @remarks
20
- * The layer draws the affordance but owns no picker — the list UI is a host concern (it needs
21
- * the float stack and the editor). Omit and the button is inert.
22
- */
23
- onOpenDropdown?: (cell: CellCoords, dataValidation: IDataValidation) => void;
24
13
  }
25
14
  /**
26
- * The sheet's **data-validation indicators** — the mark on a cell holding a value its rule rejects,
27
- * and the dropdown on a selected list cell.
15
+ * The sheet's **invalid-value marks** — the corner mark on every in-view cell holding a value its
16
+ * validation rule rejects.
28
17
  *
29
18
  * @remarks
30
- * Both used to be drawn by the cell renderer, which meant every cached tile probed the validation
31
- * model whether or not the sheet had any validations, and neither mark could have a hover or press
32
- * state (a tile is an immutable snapshot). As a layer they are live, they cost nothing on a sheet
33
- * with no validations, and the cells layer no longer knows validation exists.
19
+ * A layer of its own rather than part of the cell renderer, so the cells layer never probes the
20
+ * validation model and a sheet with no validations costs one index lookup per frame.
34
21
  *
35
- * The two marks answer different questions and so are scoped differently. The invalid mark is a
36
- * property of a cell's VALUE, so it is drawn wherever one is in view. The dropdown is an
37
- * affordance for editing, so — as in Excel — it appears on the selected cell alone; a column of
38
- * list cells would otherwise be a column of buttons.
22
+ * The mark is a property of a cell's VALUE, so it belongs wherever one is in view and is drawn as
23
+ * {@link CellTileDiv} snapshots that survive scroll — nothing here depends on the selection, which is
24
+ * what keeps the tile cache alive across cursor movement. The list DROPDOWN is the opposite predicate
25
+ * ("the active cell alone") and lives in `ValidationDropdownLayer`; they share a sheet and nothing else.
39
26
  */
40
27
  export declare const ValidationIndicatorLayer: React.MemoExoticComponent<(props: ValidationIndicatorLayerProps) => React.JSX.Element | null>;
41
28
  //# sourceMappingURL=ValidationIndicatorLayer.d.ts.map
@@ -18,6 +18,10 @@ export * from './ConditionalIcons';
18
18
  export * from './ConditionalBarLayer';
19
19
  export * from './ConditionalIconsLayer';
20
20
  export * from './ValidationIndicatorLayer';
21
+ export * from './ValidationDropdownLayer';
22
+ export * from './useValidationPicker';
23
+ export * from './validationList';
24
+ export * from './CircularIndicatorLayer';
21
25
  export * from './HeaderSelectionLayer';
22
26
  export * from './HeaderResizerLayer';
23
27
  export * from './ResizeIndicator';
@@ -0,0 +1,54 @@
1
+ import { default as React } from 'react';
2
+ import { CellCoords } from '@sheetxl/utils';
3
+ import { ISheet, IDataValidation } from '@sheetxl/sdk';
4
+ /**
5
+ * What the picker needs. Deliberately only an anchor + a validation + where to write: the picker does
6
+ * **not** care who opened it, so the Excel-mode float button and the Sheets-mode in-cell triangle open
7
+ * the identical component.
8
+ */
9
+ export interface ValidationPickerOptions {
10
+ /** The sheet the chosen value is written to. */
11
+ sheet: ISheet;
12
+ /** The validation whose list is offered (`null` closes / offers nothing). */
13
+ dataValidation: IDataValidation | null;
14
+ /** The cell that receives the chosen value. */
15
+ cell: CellCoords | null;
16
+ /**
17
+ * What the menu drops under — the **cell / merge** rect, not the button. Excel anchors the list to
18
+ * the cell, and it is what both modes can supply (the Sheets-mode triangle has no float to anchor
19
+ * to). A Floating UI virtual element; `StickyState.reference` is one.
20
+ */
21
+ anchor: unknown;
22
+ /**
23
+ * The anchored cell / merge width (px). Excel makes the list **at least** as wide as the cell — a
24
+ * floor, not a cap: a long value still widens it past the column.
25
+ */
26
+ minWidth?: number;
27
+ }
28
+ /** The picker, ready to drop into JSX and drive. */
29
+ export interface ValidationPicker {
30
+ /** Render this. */
31
+ component: React.ReactNode;
32
+ /** Open the menu. */
33
+ open: () => void;
34
+ /** Close it. */
35
+ close: () => void;
36
+ /** Whether it is currently open (reactive). */
37
+ isOpen: boolean;
38
+ }
39
+ /**
40
+ * The **list-validation picker** — a `FloatPopper` menu (through the shared float stack, so it gets
41
+ * the portal, stacking, light-dismiss and Escape every other popup in the app has) anchored to the
42
+ * cell it edits.
43
+ *
44
+ * @remarks
45
+ * The split is deliberate: `RangeFloatLayer` places the *button* against the grid (pane ownership,
46
+ * freeze, boundary fit); the float stack owns the *menu*. Neither does the other's job.
47
+ *
48
+ * The offered values come from {@link resolveListRange} as a RANGE of real cells, and are drawn by
49
+ * `SheetValueList` — so a date reads as a date and a currency as currency, because the rows are
50
+ * cells. A reference-backed source is not resolvable yet; the menu shows clearly-marked placeholders
51
+ * in that case and refuses to write one back.
52
+ */
53
+ export declare const useValidationPicker: (options: ValidationPickerOptions) => ValidationPicker;
54
+ //# sourceMappingURL=useValidationPicker.d.ts.map
@@ -0,0 +1,84 @@
1
+ import { ICellRange, IDataValidation, ISheet, Scalar } from '@sheetxl/sdk';
2
+ /**
3
+ * The values a list validation offers, plus whether they are real.
4
+ */
5
+ export interface ResolvedList {
6
+ /** The offered values. */
7
+ items: readonly Scalar[];
8
+ /**
9
+ * `true` when {@link items} is **placeholder data** — the source exists but this build cannot
10
+ * resolve it (see {@link resolveListItems}). Never let placeholder values reach the model or read
11
+ * as real in the UI.
12
+ */
13
+ placeholder: boolean;
14
+ }
15
+ /**
16
+ * The values a list validation offers.
17
+ *
18
+ * @remarks
19
+ * A list source is stored as **formula text**, verbatim, so the round-trip is lossless — see
20
+ * `io-xlsx`'s `toCondition`, which sets `param` to the raw `<formula1>`. Three forms reach here:
21
+ *
22
+ * - a `Scalar[]` under `param.items` — the programmatic form, used directly;
23
+ * - a quoted literal (`"a,b,c"`) — parsed here;
24
+ * - a reference or formula (`$A$1:$A$5`, a name, a cross-sheet ref) — **not resolvable in this
25
+ * build**. `ICondition.IContext.resolveFormula` returns a single `Scalar`, not an array, and
26
+ * `InSetOperator` carries the matching TODO: resolving a source to a list needs a formula→array
27
+ * evaluation that does not exist yet. Until it does, this returns PLACEHOLDER values with
28
+ * `placeholder: true` so the picker UI can be exercised — the caller must surface that, and must
29
+ * never write one back to the model.
30
+ *
31
+ * Note the same gap makes such a validation inert as a *predicate* too (`InSetOperator` drops a
32
+ * non-array `items`), so this is one missing capability, not a picker-only problem.
33
+ */
34
+ export declare const resolveListItems: (dataValidation: IDataValidation | null | undefined) => ResolvedList;
35
+ /**
36
+ * Options for {@link resolveListRange}.
37
+ */
38
+ export interface ResolveListRangeOptions {
39
+ /**
40
+ * The sheet the validation belongs to.
41
+ *
42
+ * @remarks
43
+ * Its {@link IStyleCollection} is SHARED with the scratch sheet, so the offered values render in
44
+ * the document's theme and `Normal` style instead of the defaults. Sharing is safe only because
45
+ * the scratch sheet sets values and never a style — writing one would reach the host's collection.
46
+ */
47
+ host?: ISheet;
48
+ }
49
+ /**
50
+ * A list validation's values, as a **range**.
51
+ */
52
+ export interface ResolvedListRange {
53
+ /** The values to offer, or `null` when the validation offers none. */
54
+ range: ICellRange | null;
55
+ /**
56
+ * The width (px) the values need — already measured, so a caller sizing a menu does not measure
57
+ * again. `0` when there is no range.
58
+ */
59
+ contentWidth: number;
60
+ /**
61
+ * `true` when {@link range} holds **placeholder data** — the source exists but this build cannot
62
+ * resolve it. Never let a placeholder reach the model or read as real in the UI.
63
+ */
64
+ placeholder: boolean;
65
+ /**
66
+ * Release the scratch sheet this materialized. A no-op for a source that was already a real range,
67
+ * which is never ours to close.
68
+ */
69
+ close: () => void;
70
+ }
71
+ /**
72
+ * The values a list validation offers, as a **range of real cells** — which is what a UI needs, since
73
+ * only a cell knows how its value becomes text (a date is a date, a currency is a currency).
74
+ *
75
+ * @remarks
76
+ * A literal source (`"a,b,c"`) is materialized onto a scratch sheet. A reference source
77
+ * (`$A$1:$A$5`) will one day return that range directly, live, with no copy — the consumer does not
78
+ * change when it does, which is the point of taking a range. Until the SDK can resolve a formula to
79
+ * an array it returns marked placeholders; see {@link resolveListItems}.
80
+ *
81
+ * The caller MUST {@link ResolvedListRange.close} the result when it is done with it.
82
+ */
83
+ export declare const resolveListRange: (dataValidation: IDataValidation | null | undefined, options?: ResolveListRangeOptions) => ResolvedListRange;
84
+ //# sourceMappingURL=validationList.d.ts.map