@restio/ui 0.2.1-20260901160735 → 0.2.1-20261007123729

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.
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  import * as React$1 from 'react';
2
- import React__default, { ReactNode, UIEventHandler, Ref } from 'react';
2
+ import React__default, { RefObject, ReactNode, UIEventHandler, Ref } from 'react';
3
3
 
4
4
  /**
5
5
  * OTP Component Props
@@ -314,12 +314,8 @@ declare const OverlayPanelHeader: React__default.FC<OverlayPanelHeaderProps>;
314
314
  /** OverlayPanelPosition defines the possible positions for the OverlayPanel. */
315
315
  type OverlayPanelPosition = "center" | "left" | "right" | "top" | "bottom";
316
316
  /**
317
- * OverlayPanelVariant defines the visual and behavioral variant for the OverlayPanel.
318
- * - "modal": Center modal with backdrop, traps focus, blocks interaction.
319
- * - "dialog": Center dialog, lighter backdrop, may allow outside click to close.
320
- * - "sidepanel": Left/right slide-in panel, typically with backdrop.
321
- * - "drawer": Mobile-friendly drawer, usually slides from bottom or side.
322
- * - "popover": Light overlay, anchored to element, minimal/no backdrop.
317
+ * Visual and behavioral variant: "modal", "dialog", "sidepanel", "drawer", or
318
+ * "popover" (light, anchored, minimal backdrop).
323
319
  */
324
320
  type OverlayPanelVariant = "modal" | "dialog" | "sidepanel" | "drawer" | "popover";
325
321
  /** Props for the OverlayPanel component.*/
@@ -411,6 +407,20 @@ interface IconProps {
411
407
 
412
408
  declare const Icon: React__default.FC<IconProps>;
413
409
 
410
+ interface InputProps {
411
+ error?: string;
412
+ disabled?: boolean;
413
+ size?: Size;
414
+ leadingIcon?: string;
415
+ trailingIcon?: string;
416
+ autoFocus?: boolean;
417
+ className?: string;
418
+ children: (props: InputChildProps) => React.ReactNode;
419
+ }
420
+ interface InputChildProps {
421
+ id: string;
422
+ disabled?: boolean;
423
+ }
414
424
  interface sharedInputProps {
415
425
  autoFocus?: boolean;
416
426
  placeholder?: string;
@@ -435,6 +445,185 @@ interface NumberInputProps extends sharedInputProps {
435
445
 
436
446
  declare const NumberInput: React__default.FC<NumberInputProps>;
437
447
 
448
+ declare const Input: React__default.FC<InputProps>;
449
+
450
+ interface TextInputProps extends sharedInputProps {
451
+ value: string | undefined;
452
+ onChange: (value: string | undefined) => void;
453
+ }
454
+
455
+ declare const TextInput: React__default.FC<TextInputProps>;
456
+
457
+ interface SelectTemplateProps {
458
+ options: Option[];
459
+ value: string | string[];
460
+ multiple: boolean;
461
+ onChange: (value: string | string[]) => void;
462
+ onClose: () => void;
463
+ }
464
+
465
+ /** Select template types supported out of the box. */
466
+ type SelectType = "list" | "grid" | "preview-dialog";
467
+ interface SelectBaseProps {
468
+ /** Active value of the select: `string` for single, `string[]` for multiple. */
469
+ value: string | string[];
470
+ /** List of possible options. */
471
+ options: Option[];
472
+ /** Label shown above the field. */
473
+ label?: string;
474
+ /** Helper text shown below the field. */
475
+ helperText?: string;
476
+ /** Disables the select trigger. */
477
+ disabled?: boolean;
478
+ /** Whether the select is read-only. */
479
+ readOnly?: boolean;
480
+ /** Size of the select trigger button. */
481
+ size?: Size;
482
+ /** Enables multiselection. */
483
+ multiple?: boolean;
484
+ /** Called when the selection changes. Receives `string` (single) or `string[]` (multiple). */
485
+ onChange?: (value: string | string[]) => void;
486
+ /** Controlled open state. When provided, the dropdown is controlled externally. */
487
+ open?: boolean;
488
+ /** Notifies open/close changes. Only meaningful when `open` is provided. */
489
+ onOpenChange?: (open: boolean) => void;
490
+ }
491
+ interface SelectProps extends SelectBaseProps {
492
+ /** Built-in template kind. Defaults to `"list"` when omitted. */
493
+ type?: SelectType;
494
+ /** Dialog title (`type="preview-dialog"`). */
495
+ title?: string;
496
+ /** Renders the live preview of drafted selections (`type="preview-dialog"`). */
497
+ renderPreview?: (selected: Option[]) => React.ReactNode;
498
+ /** Custom inline dropdown content (replaces built-in templates). */
499
+ renderList?: (props: SelectTemplateProps) => React.ReactNode;
500
+ /** Custom dialog content (opens an OverlayPanel instead of a dropdown). */
501
+ renderDialog?: (props: SelectTemplateProps) => React.ReactNode;
502
+ }
503
+
504
+ declare const Select: React__default.FC<SelectProps>;
505
+
506
+ interface TextareaProps {
507
+ /**
508
+ * Value of the textarea field
509
+ */
510
+ value: string;
511
+ /**
512
+ * Leading icon to display before the textarea
513
+ */
514
+ leadingIcon?: string;
515
+ /**
516
+ * Trailing icon to display after the textarea
517
+ */
518
+ trailingIcon?: string;
519
+ /**
520
+ * Placeholder text for the textarea
521
+ */
522
+ placeholder?: string;
523
+ /**
524
+ * ARIA label for the textarea
525
+ */
526
+ ariaLabel?: string;
527
+ /**
528
+ * Callback triggered when the textarea value changes
529
+ * @param value - The current value of the textarea
530
+ */
531
+ onChange?: (value: string) => void;
532
+ onKeyDown?: (e: React.KeyboardEvent<HTMLTextAreaElement>) => void;
533
+ onBlur?: () => void;
534
+ /**
535
+ * Label for the field
536
+ */
537
+ label?: string;
538
+ /**
539
+ * Helper text displayed below the field
540
+ */
541
+ helperText?: string;
542
+ /**
543
+ * Ref for the textarea element
544
+ */
545
+ ref?: RefObject<HTMLTextAreaElement | null>;
546
+ /**
547
+ * Disabled state
548
+ */
549
+ disabled?: boolean;
550
+ /**
551
+ * Autofocus the textarea on mount
552
+ */
553
+ autoFocus?: boolean;
554
+ /**
555
+ * Error message shown below the field (danger state)
556
+ */
557
+ error?: string;
558
+ /** Size of the textarea */
559
+ size?: Size;
560
+ /** Number of rows (default 3) */
561
+ rows?: number;
562
+ /** Number of cols ( default 1 ) */
563
+ cols?: number;
564
+ }
565
+
566
+ declare const Textarea: React__default.FC<TextareaProps>;
567
+
568
+ interface BaseTypographyProps {
569
+ /**
570
+ * Prefer children when rendering rich/nested content
571
+ */
572
+ children?: React__default.ReactNode;
573
+ variant: TypographyVariant;
574
+ /**
575
+ * Flag to indicate if the component is disabled.
576
+ * @optional
577
+ */
578
+ disabled?: boolean;
579
+ /**
580
+ * Optional color string i can pass to the text
581
+ * @optional
582
+ */
583
+ color?: string;
584
+ /**
585
+ * Font weight applied to the text.
586
+ * @optional
587
+ */
588
+ fontWeight?: string | number;
589
+ /**
590
+ * Font style applied to the text.
591
+ * @optional
592
+ */
593
+ fontStyle?: string;
594
+ /**
595
+ * Text decoration applied to the text.
596
+ * @optional
597
+ */
598
+ textDecoration?: string;
599
+ }
600
+ type TypographyProps<T extends TypographyVariant> = BaseTypographyProps & {
601
+ variant: T;
602
+ } & React__default.ComponentPropsWithoutRef<VariantToElement<T>>;
603
+ type TypographyVariant = "display" | "heading" | "body" | "label" | "code" | "subtitle" | "title" | "caption" | "article-h1" | "article-h2" | "article-h3" | "article-h4" | "article-body" | "article-code" | "article-quote" | "article-caption" | "article-list";
604
+ declare const variantToComponent: {
605
+ readonly display: "h1";
606
+ readonly heading: "h2";
607
+ readonly title: "h3";
608
+ readonly subtitle: "h4";
609
+ readonly body: "p";
610
+ readonly label: "label";
611
+ readonly code: "code";
612
+ readonly caption: "span";
613
+ readonly "article-h1": "h1";
614
+ readonly "article-h2": "h2";
615
+ readonly "article-h3": "h3";
616
+ readonly "article-h4": "h4";
617
+ readonly "article-body": "p";
618
+ readonly "article-code": "code";
619
+ readonly "article-quote": "blockquote";
620
+ readonly "article-caption": "figcaption";
621
+ readonly "article-list": "li";
622
+ };
623
+ type VariantToElement<T extends TypographyVariant> = (typeof variantToComponent)[T];
624
+
625
+ declare const Typography: <T extends TypographyVariant>({ variant, children, color, disabled, className, fontWeight, fontStyle, textDecoration, ...htmlProps }: TypographyProps<T>) => React$1.JSX.Element;
626
+
438
627
  type DatePickerMode = "day" | "month" | "quarter" | "year";
439
628
  interface DateRange {
440
629
  from: Date | undefined;
@@ -475,8 +664,7 @@ declare const DatePicker: React__default.FC<DatePickerProps>;
475
664
 
476
665
  /**
477
666
  * Date range picker supporting day, month, quarter, and year modes.
478
- * Shows two calendars side-by-side for range selection.
479
- * Clicking once sets the start date; clicking again sets the end date.
667
+ * Two calendars select the range: the first click sets the start, the second the end.
480
668
  */
481
669
  declare const DateRangePicker: React__default.FC<DateRangePickerProps>;
482
670
 
@@ -654,29 +842,8 @@ interface ShortcutProviderProps {
654
842
  readonly children: React__default.ReactNode;
655
843
  }
656
844
  /**
657
- * ShortcutProvider manages global keyboard shortcuts and displays visual feedback tooltips.
658
- *
659
- * Features:
660
- * - Global and component-scoped shortcuts
661
- * - Visual feedback with tooltips appearing near cursor
662
- * - Hold-to-execute shortcuts with progress indicators (3s default)
663
- * - Automatic cleanup of component-scoped shortcuts
664
- * - Key release detection for cancelling hold shortcuts
665
- *
666
- * How it works:
667
- * 1. Maintains a map of registered shortcuts with their configurations
668
- * 2. Tracks active components for scoping validation
669
- * 3. Listens for keyboard events and matches against registered shortcuts
670
- * 4. Shows tooltip with shortcut keys and function name near cursor
671
- * 5. Executes actions only after full hold duration (for hold shortcuts)
672
- * 6. Cancels hold shortcuts when any key is released
673
- *
674
- * Component Scoping:
675
- * - Global shortcuts (no componentId) always available
676
- * - Component shortcuts only trigger when their component is registered as active
677
- * - Components auto-register/unregister through useShortcut hook focus/hover handlers
678
- *
679
- * @param children - Child components that will have access to shortcut context
845
+ * Manages global and per-component keyboard shortcuts and shows the cursor-anchored
846
+ * feedback tooltip, including progress for hold-to-execute shortcuts (3s default).
680
847
  */
681
848
  declare const ShortcutProvider: React__default.FC<ShortcutProviderProps>;
682
849
 
@@ -696,9 +863,7 @@ interface ShortcutConfig {
696
863
  */
697
864
  interface UseShortcutOptions {
698
865
  /**
699
- * Scope of the shortcuts:
700
- * - 'component': Shortcuts only work when this component is focused or hovered
701
- * - 'global': Shortcuts work globally across the application
866
+ * Scope of the shortcuts: 'global' works app-wide, 'component' only when focused or hovered.
702
867
  */
703
868
  scope?: 'global' | 'component';
704
869
  /** Whether shortcuts are enabled */
@@ -738,9 +903,8 @@ interface UseDynamicVirtualListOptions {
738
903
  /** Fallback height used for items that have not been measured yet */
739
904
  estimatedItemHeight?: number;
740
905
  /**
741
- * Extra items rendered above and below the visible viewport.
742
- * A larger value makes scrolling smoother at the cost of slightly more DOM nodes.
743
- * Defaults to 10.
906
+ * Extra items rendered above and below the viewport. Higher values scroll more
907
+ * smoothly at the cost of more DOM nodes. Defaults to 10.
744
908
  */
745
909
  overscan?: number;
746
910
  }
@@ -770,14 +934,10 @@ interface UseDynamicVirtualListResult {
770
934
  scrollTop: number;
771
935
  }
772
936
  /**
773
- * A dynamic-height virtual list hook inspired by TanStack Virtual.
937
+ * Dynamic-height virtual list hook: measures every rendered item with a ResizeObserver
938
+ * and falls back to `estimatedItemHeight`, so variable-height rows scroll correctly.
774
939
  *
775
- * Unlike fixed-height virtualizers, this hook uses a ResizeObserver to measure
776
- * each rendered item's actual height and falls back to `estimatedItemHeight` for
777
- * items that have not yet been rendered. This allows rows with variable content
778
- * (wrapped text, expandable cells, group headers) to scroll correctly.
779
- *
780
- * Usage:
940
+ * @example
781
941
  * ```tsx
782
942
  * const { virtualItems, totalSize, containerRef, onScroll, measureElement } =
783
943
  * useDynamicVirtualList({ count: rows.length, estimatedItemHeight: 40, overscan: 10 });
@@ -798,101 +958,76 @@ interface UseDynamicVirtualListResult {
798
958
  * </div>
799
959
  * );
800
960
  * ```
801
- *
802
- * For table usage, pair with padding `<tr>` spacers at the top and bottom of
803
- * `<tbody>` and attach `measureElement` to each `<tr>` via a ref callback.
804
961
  */
805
962
  declare function useDynamicVirtualList({ count, estimatedItemHeight, overscan, }: UseDynamicVirtualListOptions): UseDynamicVirtualListResult;
806
963
 
964
+ /** Horizontal alignment: main axis for flex, inside the cell for grid */
807
965
  type alignX = 'start' | 'center' | 'end' | 'space-between' | 'space-around';
966
+ /** Vertical alignment: cross axis for flex, inside the cell for grid */
808
967
  type alignY = 'start' | 'center' | 'end' | 'stretch';
809
- /** Layout block node */
968
+ /** Leaf node: renders content through `renderBlock(fieldId)` */
810
969
  type BlockNode = {
811
970
  type: 'block';
812
- /** The field/column identifier that the consumer maps to a Cell */
971
+ /** Identifier passed to `renderBlock` to resolve this block's content */
813
972
  fieldId: string;
814
973
  };
815
- /** Grid child node */
974
+ /** A child placed on a grid cell, with its position, span and content alignment */
816
975
  type GridChild = {
817
976
  node: LayoutNode$1;
977
+ /** Column to start at (1-based) */
818
978
  col: number;
979
+ /** Row to start at (1-based) */
819
980
  row: number;
981
+ /** Number of columns to span */
820
982
  w: number;
983
+ /** Number of rows to span */
821
984
  h: number;
822
- /** Horizontal alignment of content within the grid cell */
985
+ /** Alignment of the content inside the cell */
823
986
  alignX?: alignX;
824
- /** Vertical alignment of content within the grid cell */
987
+ /** Alignment of the content inside the cell */
825
988
  alignY?: alignY;
826
989
  };
827
- /** Grid container node */
990
+ /** Grid container: positions children on a column/row matrix */
828
991
  type GridContainer = {
829
992
  type: 'grid';
993
+ /** Number of equal-width columns */
830
994
  columns: number;
995
+ /** Number of rows; omit to size rows automatically */
831
996
  rows?: number;
997
+ /** Space between children, in units of 0.25rem (`8` = 2rem) */
832
998
  gap?: number;
833
999
  children: GridChild[];
834
1000
  };
835
- /** Flex container node */
1001
+ /** Flex container: lays children out along one axis */
836
1002
  type FlexContainer = {
837
1003
  type: 'flex';
1004
+ /** Main axis; defaults to `row` */
838
1005
  direction?: 'row' | 'column';
1006
+ /** Space between children, in units of 0.25rem (`8` = 2rem) */
839
1007
  gap?: number;
1008
+ /** Alignment along the main axis */
840
1009
  alignX?: alignX;
1010
+ /** Alignment along the cross axis */
841
1011
  alignY?: alignY;
842
1012
  children: LayoutNode$1[];
843
1013
  };
844
- /** Union of all node types */
1014
+ /** Any node in a layout tree */
845
1015
  type LayoutNode$1 = BlockNode | GridContainer | FlexContainer;
846
- /** Responsive layout mapping breakpoints to layout trees */
1016
+ /** One layout tree per breakpoint; every breakpoint is required, with no fallback between them */
847
1017
  type ResponsiveLayout = {
848
1018
  [K in Breakpoint]: LayoutNode$1;
849
1019
  };
850
1020
  /** Layout component props */
851
1021
  type LayoutProps = {
852
- /** Responsive layout tree */
1022
+ /** The tree rendered for the current breakpoint */
853
1023
  layout: ResponsiveLayout;
854
- /** Callback that renders a Block node given its fieldId */
1024
+ /** Resolves a block's `fieldId` to its content; keep it pure and deterministic */
855
1025
  renderBlock: (fieldId: string) => ReactNode;
856
1026
  };
857
1027
 
858
- interface BaseTypographyProps {
859
- /**
860
- * Prefer children when rendering rich/nested content
861
- */
862
- children?: React__default.ReactNode;
863
- variant: TypographyVariant;
864
- /**
865
- * Flag to indicate if the component is disabled.
866
- * @optional
867
- */
868
- disabled?: boolean;
869
- /**
870
- * Optional color string i can pass to the text
871
- * @optional
872
- */
873
- color?: string;
874
- /**
875
- * Font weight applied to the text.
876
- * @optional
877
- */
878
- fontWeight?: string | number;
879
- /**
880
- * Font style applied to the text.
881
- * @optional
882
- */
883
- fontStyle?: string;
884
- /**
885
- * Text decoration applied to the text.
886
- * @optional
887
- */
888
- textDecoration?: string;
889
- }
890
- type TypographyVariant = "display" | "heading" | "body" | "label" | "code" | "subtitle" | "title" | "caption" | "article-h1" | "article-h2" | "article-h3" | "article-h4" | "article-body" | "article-code" | "article-quote" | "article-caption" | "article-list";
891
-
892
1028
  /**
893
- * Maps each CellType to the component-specific props that can be passed
894
- * via `uiVariant` in a rule. TypeScript enforces that you only pass props
895
- * the underlying component actually understands.
1029
+ * Maps each CellType to the component props accepted by `uiVariant`, so TypeScript
1030
+ * only allows props the underlying component understands.
896
1031
  */
897
1032
  type CellUIVariantMap = {
898
1033
  [K in CellType]: K extends "IMAGE" ? Partial<Omit<IconProps, "src">> : K extends "TAG" ? Partial<{
@@ -922,10 +1057,8 @@ type LookupCellType<TData, TColumns extends readonly DataStructureColumn<TData>[
922
1057
  /** Comparison operators for AST-like UI rules */
923
1058
  type UIRuleOperator = "==" | "!=" | ">" | ">=" | "<" | "<=" | "includes" | "startsWith" | "endsWith" | "isEmpty" | "isNotEmpty";
924
1059
  /**
925
- * A single declarative styling rule evaluated against a row.
926
- * Rules are compiled once into fast evaluators — no runtime functions.
927
- *
928
- * When `field` and `op` are omitted, the rule always matches (static styling).
1060
+ * A declarative styling rule evaluated against a row, compiled once into a fast
1061
+ * evaluator. Omitting `field` and `op` makes it a static rule that always matches.
929
1062
  *
930
1063
  * @example conditional
931
1064
  * { field: "price", op: ">", value: 100, uiVariant: { color: "var(--rst-color-success)", fontWeight: "bold" } }
@@ -1010,17 +1143,13 @@ interface DataStructureColumn<TData, TValue = TData[keyof TData]> {
1010
1143
  /** Helper text shown below the field (e.g. "Opzionale", "Usa +/− per il segno"). */
1011
1144
  helperText?: string;
1012
1145
  /**
1013
- * Generic column-level configuration for the target component.
1014
- * Mirrors the uiConfig pattern: carries the props of the component
1015
- * referenced by `cellType` (e.g. ChartProps for CHART, TableGridProps for TABLE_GRID).
1016
- * `data` and `columns` are excluded — they come from the cell value and schema.
1146
+ * Column-level config for the component named by `cellType` (e.g. ChartProps for
1147
+ * CHART). `data` and `columns` are excluded — they come from the cell value and schema.
1017
1148
  */
1018
1149
  columnConfig?: Record<string, unknown>;
1019
1150
  /**
1020
- * Called when an interactive cell (e.g. BUTTON, IMAGE click) fires an action.
1021
- * The cell handler decides when to invoke it; the first argument is the
1022
- * action id (for BUTTON = `option.value`). Works in any data-component
1023
- * that renders Cell in display mode (CardList, TableGrid, …).
1151
+ * Called when an interactive cell (e.g. BUTTON) fires an action; the first argument
1152
+ * is the action id (for BUTTON, `option.value`).
1024
1153
  */
1025
1154
  onCellClick?: (actionId: string, rowData: TData, column: DataStructureColumn<TData, TValue>) => void;
1026
1155
  }
@@ -1067,10 +1196,8 @@ declare namespace Card {
1067
1196
  }
1068
1197
 
1069
1198
  /**
1070
- * Per-series row of the composed-series matrix.
1071
- * `column` references a Y-axis data column by id/accessor;
1072
- * `type` decides which cartesian primitive (line/bar/area/scatter) renders;
1073
- * `color` is optional — falls back to the chart palette when omitted.
1199
+ * Per-series row of the composed matrix: `column` names the Y-axis data column,
1200
+ * `type` the cartesian primitive, `color` an optional override for the palette.
1074
1201
  */
1075
1202
  interface ChartSeriesConfig<TData = Record<string, unknown>> {
1076
1203
  column: keyof TData | string;
@@ -1078,11 +1205,8 @@ interface ChartSeriesConfig<TData = Record<string, unknown>> {
1078
1205
  color?: string;
1079
1206
  }
1080
1207
  /**
1081
- * Configuration for Sankey charts.
1082
- * stageColumns: ordered list of columns that define the flow stages (min 2).
1083
- * - Null/undefined/empty values in a row are skipped, creating a direct link
1084
- * between the nearest non-empty columns on both sides.
1085
- * valueColumn: numeric column used as the flow weight.
1208
+ * Sankey chart config. `stageColumns` lists the ordered flow stages (min 2); empty
1209
+ * values are skipped, linking the nearest non-empty stages on either side.
1086
1210
  *
1087
1211
  * @example 2-level (source → target)
1088
1212
  * { stageColumns: ["from", "to"], valueColumn: "amount" }
@@ -1095,11 +1219,8 @@ interface SankeyConfig<TData> {
1095
1219
  valueColumn: keyof TData;
1096
1220
  }
1097
1221
  /**
1098
- * Configuration for Geo charts.
1099
- * geoJson: GeoJSON FeatureCollection with MultiPolygon geometry.
1100
- * regionColumn: column in TData that maps to the "name" property in geoJson features.
1101
- * valueColumn: numeric column used for the choropleth color scale.
1102
- * colorRange: [minColor, maxColor] — two CSS color strings for the gradient.
1222
+ * Geo (choropleth) chart config: GeoJSON features matched to `regionColumn`,
1223
+ * with `valueColumn` driving the colour scale and `colorRange` as its endpoints.
1103
1224
  */
1104
1225
  interface GeoConfig<TData> {
1105
1226
  geoJson: {
@@ -1135,11 +1256,8 @@ interface ChartSpecificProps<TData> {
1135
1256
  /** Custom colors for chart series */
1136
1257
  colors?: string[];
1137
1258
  /**
1138
- * Per-series matrix used when type === "composed" (Cartesian-only mixes:
1139
- * line + bar + area + scatter). For the single-type cartesian types
1140
- * (line/bar/area/scatter), the matrix is derived from yAxisColumns and
1141
- * every entry adopts `type` — so the prop form only needs to manage one
1142
- * matrix for all cartesian charts. Ignored for pie/sankey/sparkline/geo.
1259
+ * Per-series matrix for "composed" cartesian charts (line + bar + area + scatter).
1260
+ * Single-type cartesian charts derive it from `yAxisColumns`; ignored for pie/sankey/sparkline/geo.
1143
1261
  */
1144
1262
  series?: ChartSeriesConfig<TData>[];
1145
1263
  /** Show/hide chart elements */
@@ -1241,20 +1359,13 @@ interface ChatMessage {
1241
1359
 
1242
1360
  type GanttView = "year" | "month" | "week" | "day";
1243
1361
  /**
1244
- * Relation types:
1245
- * - FS (Finish-to-Start): arrow from end of predecessor to start of successor
1246
- * - SS (Start-to-Start): arrow from start of predecessor to start of successor
1247
- * - FF (Finish-to-Finish): arrow from end of predecessor to end of successor
1248
- * - SF (Start-to-Finish): arrow from start of predecessor to end of successor
1362
+ * Dependency relation types: FS (finish→start), SS (start→start), FF (finish→finish)
1363
+ * and SF (start→finish).
1249
1364
  */
1250
1365
  type GanttRelationType = "FS" | "SS" | "FF" | "SF";
1251
1366
  /**
1252
- * A single dependency descriptor.
1253
- * The `dependencyColumnId` field on each row can resolve to:
1254
- * - `string` — single dependency ID (defaults to "FS")
1255
- * - `string[]` — multiple dependency IDs (all default to "FS")
1256
- * - `GanttDependency` — single dependency with explicit type
1257
- * - `GanttDependency[]` — multiple dependencies with explicit types
1367
+ * A single dependency descriptor. A row's `dependencyColumnId` may resolve to a string,
1368
+ * string[], `GanttDependency`, or `GanttDependency[]` (strings default to "FS").
1258
1369
  */
1259
1370
  interface GanttDependency {
1260
1371
  id: string;
@@ -1318,10 +1429,8 @@ interface PivotValueField {
1318
1429
  label?: string;
1319
1430
  }
1320
1431
  /**
1321
- * Configuration for pivot mode.
1322
- * rowFields: column IDs whose values form the row groups.
1323
- * columnFields: column IDs whose unique values become dynamic columns.
1324
- * valueFields: numeric fields to aggregate at each row × column intersection.
1432
+ * Pivot config: `rowFields` form the row groups, `columnFields` become dynamic columns,
1433
+ * and `valueFields` are aggregated at each intersection.
1325
1434
  */
1326
1435
  interface PivotConfig {
1327
1436
  rowFields: string[];
@@ -1408,6 +1517,92 @@ interface OperatorOption {
1408
1517
  label: string;
1409
1518
  }
1410
1519
 
1520
+ /**
1521
+ * Row model switch and feature-by-model registry: single source of truth binding each grid
1522
+ * feature to the models that support it (client, server, server-only, dual, blocked-on-server).
1523
+ */
1524
+ /** All row models the grid supports. */
1525
+ declare const TableRowModel: {
1526
+ readonly client: "client";
1527
+ readonly server: "server";
1528
+ };
1529
+ type TableRowModel = (typeof TableRowModel)[keyof typeof TableRowModel];
1530
+ /** Where a dual feature executes. */
1531
+ declare const TableSortingMode: {
1532
+ readonly client: "client";
1533
+ readonly server: "server";
1534
+ };
1535
+ type TableSortingMode = (typeof TableSortingMode)[keyof typeof TableSortingMode];
1536
+ /** How one feature relates to the row models. */
1537
+ type FeatureSupport = "client" | "server" | "server-only" | "dual" | "blocked-on-server";
1538
+ /** Feature registry — keep in sync with the matrix in `table-grid-row-models.md`. */
1539
+ declare const TABLE_MODEL_FEATURES: {
1540
+ /** Client: applyFilter on full data. Server: app filters inside getRows. */
1541
+ readonly filtering: "server-only";
1542
+ /** Client: groupData on full data. Server: app returns group rows. */
1543
+ readonly grouping: "server-only";
1544
+ /** Server model: server by default, sortingMode="client" sorts loaded rows. */
1545
+ readonly sorting: "dual";
1546
+ /** Pivot needs the whole dataset in memory — blocked on server. */
1547
+ readonly pivot: "blocked-on-server";
1548
+ /** Local in both; over loaded rows only on server. */
1549
+ readonly cellEditing: "dual";
1550
+ /** Local in both; rendered rows only on server. */
1551
+ readonly rowSelection: "dual";
1552
+ /** Tree data is unsupported with rowModel="server" (v1). */
1553
+ readonly treeData: "blocked-on-server";
1554
+ /** Model-agnostic; on server the scrollbar total is totalRowCount. */
1555
+ readonly virtualization: "dual";
1556
+ /** Pagination runs on top of the non-virtualized render in both models:
1557
+ * client = local slice, server = per-page fetch. */
1558
+ readonly pagination: "dual";
1559
+ };
1560
+ type TableModelFeature = keyof typeof TABLE_MODEL_FEATURES;
1561
+
1562
+ /** Request the grid sends to the app datasource (server model only). */
1563
+ interface ServerRowRequest {
1564
+ /** Inclusive/exclusive window of flat rows the grid currently needs. */
1565
+ range: {
1566
+ start: number;
1567
+ end: number;
1568
+ };
1569
+ /** Active sort: [{ id, desc }] — same shape as client SortingState. */
1570
+ sorting: SortingState;
1571
+ /** Active filter tree, or null. Same FilterGroup consumed by the filter panel. */
1572
+ filtering: FilterGroup | null;
1573
+ /** Ordered group-by column ids. */
1574
+ grouping: string[];
1575
+ /** Ids (derived paths) of expanded group rows — see ServerGroupRow.id. */
1576
+ expandedGroups: string[];
1577
+ }
1578
+ /** A group row returned by the server (server model only). */
1579
+ interface ServerGroupRow {
1580
+ kind: "group";
1581
+ /** Grouped values from root to this node, e.g. ["IT", "Milan"]. */
1582
+ path: string[];
1583
+ /** Depth = path.length - 1 (root groups = 0). */
1584
+ depth: number;
1585
+ /** Total leaf rows in the group — shown in the group banner/count. */
1586
+ childCount: number;
1587
+ }
1588
+ /** Response the app datasource returns. */
1589
+ interface ServerRowResponse<TData> {
1590
+ /**
1591
+ * Flat sequence of rows for the requested window, in final display order.
1592
+ * Data rows are raw TData; group rows are wrapped in {@link ServerGroupRow}.
1593
+ */
1594
+ rows: Array<TData | ServerGroupRow>;
1595
+ /** Total rows matching the query (data + group rows), for the scrollbar size. */
1596
+ totalRowCount: number;
1597
+ }
1598
+ /**
1599
+ * Datasource contract for `rowModel: "server"`. The app implements `getRows`
1600
+ * and owns filtering, sorting and grouping server-side.
1601
+ */
1602
+ interface ServerDatasource<TData> {
1603
+ getRows(request: ServerRowRequest): Promise<ServerRowResponse<TData>>;
1604
+ }
1605
+
1411
1606
  type TableGridDisplayMode = "tree" | "table" | "table-tree";
1412
1607
  /** Which grid lines (cell borders) are visible. */
1413
1608
  type TableGridShowGrid = ShowGridLines;
@@ -1442,8 +1637,11 @@ interface TableGridSpecificProps<TData> {
1442
1637
  enableVirtualization?: boolean;
1443
1638
  /** Height of each row in pixels (required for virtualization) */
1444
1639
  virtualizedRowHeight?: number;
1445
- /** Height of the scrollable container in pixels (required for virtualization) */
1446
- virtualizedContainerHeight?: number;
1640
+ /**
1641
+ * Scrollable container height in pixels. Required with virtualization; otherwise the
1642
+ * container grows with its content (fill mode in a flex parent).
1643
+ */
1644
+ containerHeight?: number;
1447
1645
  /** When true, cells keep a fixed single-line height; overflowing content is clipped. */
1448
1646
  oneLine?: boolean;
1449
1647
  /** Which grid lines (cell borders) are visible. Defaults to "both". */
@@ -1461,9 +1659,8 @@ interface TableGridSpecificProps<TData> {
1461
1659
  /** Enable the formula builder — shows the formula icon in the right toolbar */
1462
1660
  enableFormulaBuilder?: boolean;
1463
1661
  /**
1464
- * Controls how column widths are calculated.
1465
- * - `"auto"` (default): columns share the available width; `size` is ignored.
1466
- * - `"fixed"`: each column uses its `size` value; the table scrolls horizontally when the total exceeds the container.
1662
+ * How column widths are calculated: "auto" shares the available width (ignoring `size`),
1663
+ * "fixed" uses each column's `size` and scrolls horizontally when the total overflows.
1467
1664
  */
1468
1665
  columnSizing?: "auto" | "fixed";
1469
1666
  /** Show loading skeleton state while data is being fetched */
@@ -1483,25 +1680,42 @@ interface TableGridSpecificProps<TData> {
1483
1680
  /** Pre-configured action buttons shown in the AI chat panel for one-click commands */
1484
1681
  aiQuickActions?: AIQuickAction[];
1485
1682
  /**
1486
- * Called whenever a new formula column is created (via the builder or AI).
1487
- * Use this to persist the column definition on your server so it can be
1488
- * re-supplied via the `columns` prop on the next load.
1683
+ * Called when a new formula column is created (builder or AI). Persist the definition
1684
+ * on your server so it can be re-supplied via `columns` on the next load.
1489
1685
  */
1490
1686
  onFormulaColumnAdd?: (col: ColumnDef<TData>) => void;
1491
1687
  /**
1492
- * Forwarded to the inner scroll container (`rst-table-container`).
1493
- * Allows an external component to react to scroll events from the table body.
1494
- * Works for both virtualized and non-virtualized modes.
1688
+ * Forwarded to the inner scroll container (`rst-table-container`), so an external
1689
+ * component can react to scroll events. Works in both row models.
1495
1690
  */
1496
1691
  onScroll?: UIEventHandler<HTMLDivElement>;
1497
1692
  /**
1498
- * Ref forwarded to the inner scroll container (`rst-table-container`).
1499
- * Allows an external component to programmatically read or set `scrollTop`.
1500
- * Works for both virtualized and non-virtualized modes.
1693
+ * Ref to the inner scroll container (`rst-table-container`), so an external component
1694
+ * can read or set `scrollTop`. Works in both row models.
1501
1695
  */
1502
1696
  scrollContainerRef?: Ref<HTMLDivElement>;
1503
1697
  }
1504
- type TableGridProps<TData> = DataStructureComponent<TData> & TableGridSpecificProps<TData>;
1698
+ /** Props that only apply when `rowModel` is "server". See table-model-registry. */
1699
+ interface TableGridServerModelProps<TData> {
1700
+ /** Datasource — required when rowModel="server", ignored otherwise. */
1701
+ datasource?: ServerDatasource<TData>;
1702
+ /** Server model only: where sorting executes (default "server"). */
1703
+ sortingMode?: TableSortingMode;
1704
+ }
1705
+ /** Pagination config — only honored when virtualization is disabled. */
1706
+ interface TableGridPagination {
1707
+ /** Rows per page. */
1708
+ readonly pageSize: number;
1709
+ }
1710
+ type TableGridProps<TData> = DataStructureComponent<TData> & TableGridSpecificProps<TData> & {
1711
+ /** Global row-model switch — decides where each data-pipeline feature runs. Default "client". See `TableRowModel`. */
1712
+ rowModel?: TableRowModel;
1713
+ /**
1714
+ * Pagination — orthogonal to the row model: client pages slice in-memory data, server
1715
+ * pages fetch a window. Honored only when virtualization is off. Defaults to off.
1716
+ */
1717
+ pagination?: TableGridPagination;
1718
+ } & TableGridServerModelProps<TData>;
1505
1719
  interface ColumnDef<TData, TValue = TData[keyof TData]> extends DataStructureColumn<TData, TValue> {
1506
1720
  /** Column width */
1507
1721
  size?: number;
@@ -1575,7 +1789,7 @@ type SortingState = {
1575
1789
  desc: boolean;
1576
1790
  }[];
1577
1791
 
1578
- declare function TableGrid<TData>({ data, columns, getSubRows, onDataChange, onSelectionChange, enableSorting, enableSelection, enableEditing, enableGrouping, enableVirtualization, stickyHeader, stickyFooter, columnSizing, enableColumnReorder, enableColumnVisibility, enableFiltering, enableAIAssistant, aiProvider, onFormulaColumnAdd: externalOnFormulaColumnAdd, loading, uiConfig, oneLine, showGrid, ...toolPassThrough }: TableGridProps<TData>): React$1.JSX.Element;
1792
+ declare function TableGrid<TData>({ data, columns, getSubRows, onDataChange, onSelectionChange, enableSorting, enableSelection, enableEditing, enableGrouping, enableVirtualization, stickyHeader, stickyFooter, columnSizing, enableColumnReorder, enableColumnVisibility, enableFiltering, enableAIAssistant, enablePivot, aiProvider, onFormulaColumnAdd: externalOnFormulaColumnAdd, loading, uiConfig, oneLine, showGrid, rowModel, datasource, sortingMode, pagination, ...toolPassThrough }: TableGridProps<TData>): React$1.JSX.Element;
1579
1793
 
1580
1794
  /**
1581
1795
  * Read a CSV/TSV/custom-delimited file and convert it into
@@ -1667,12 +1881,8 @@ interface FormColumnDelta<TData> {
1667
1881
  column: FormColumn<TData>;
1668
1882
  }
1669
1883
  /**
1670
- * Server response to a field change.
1671
- * Only the changed pieces are returned — the form merges them with existing state.
1672
- *
1673
- * - `data`: partial data to merge (e.g. reset dependent fields to null)
1674
- * - `columns`: delta operations on columns (add new dependent fields, update options, remove fields)
1675
- * - `layout`: optional new layout. If omitted, the form recalculates from current columns.
1884
+ * Server response to a field change. Only the changed pieces are returned; the form
1885
+ * merges `data` (partial rows), `columns` (add/update/remove deltas) and optional `layout`.
1676
1886
  */
1677
1887
  interface FormChangeResponse<TData> {
1678
1888
  /** Partial data delta — merged with current formData */
@@ -1698,18 +1908,9 @@ interface FormSpecificProps<TData> {
1698
1908
  /** Custom action buttons rendered in the form footer.*/
1699
1909
  actions?: ButtonProps[];
1700
1910
  /**
1701
- * Server-driven callback invoked on every field change.
1702
- *
1703
- * The server receives the current form state and the changed field,
1704
- * and returns a **partial delta** — only the pieces that changed.
1705
- * The form merges the delta into its state and re-renders only
1706
- * the affected fields.
1911
+ * Server-driven callback invoked on every field change: it receives the form state
1912
+ * and the changed field, and returns the partial delta to merge. Unresolved fields show skeletons.
1707
1913
  *
1708
- * Fields not yet resolved (loading) show a skeleton placeholder.
1709
- *
1710
- * @param formData - Current complete form data
1711
- * @param changedField - The accessorKey of the field that changed
1712
- * @param newValue - The new value of the changed field
1713
1914
  * @returns A partial delta with data, column operations, and optional layout
1714
1915
  */
1715
1916
  onFormChange?: (formData: TData, changedField: keyof TData, newValue: TData[keyof TData]) => Promise<FormChangeResponse<TData>>;
@@ -1910,11 +2111,8 @@ type KPIProps<TData> = Omit<DataStructureComponent<TData>, "data"> & KPISpecific
1910
2111
  declare function KPI<TData>({ data, columns, layout, slotMap, className, uiConfig, onClick }: KPIProps<TData>): React$1.JSX.Element;
1911
2112
 
1912
2113
  /**
1913
- * Shared finance layouts, usable by any component that accepts a
1914
- * `ResponsiveLayout` (Card, KPI, CardList).
1915
- *
1916
- * Field IDs are intentionally generic so they work with any dataset that
1917
- * follows the KPI shape: `label`, `value`, `delta`, `trend`, `icon`.
2114
+ * Shared finance layouts for any component taking a `ResponsiveLayout` (Card, KPI,
2115
+ * CardList). Field IDs are generic: `label`, `value`, `delta`, `trend`, `icon`.
1918
2116
  */
1919
2117
  /**
1920
2118
  * Compact KPI layout: label on top, big value in the middle, delta/trend
@@ -1937,14 +2135,8 @@ interface CardLayoutPreset {
1937
2135
  layout: ResponsiveLayout;
1938
2136
  }
1939
2137
  /**
1940
- * Card layout: icon on the left, name + type next to it, actions right-aligned.
1941
- *
2138
+ * Card layout: icon left, name + type beside it, actions right-aligned.
1942
2139
  * Field IDs: `icon`, `name`, `type`, `actions`.
1943
- *
1944
- * ┌──────────────────────────────────────┐
1945
- * │ icon name actions │
1946
- * │ type │
1947
- * └──────────────────────────────────────┘
1948
2140
  */
1949
2141
  declare const cardLayoutWithIcon: ResponsiveLayout;
1950
2142
  /** Maps a preset id to its `ResponsiveLayout`. Falls back to `undefined`. */
@@ -1958,12 +2150,8 @@ declare const cardLayoutPresetOptions: {
1958
2150
  }[];
1959
2151
 
1960
2152
  /**
1961
- * A registered KPI layout preset.
1962
- *
1963
- * `id` is the value stored in the widget config (and resolved back to a
1964
- * `ResponsiveLayout` at render time by the Switcher). `label` / `description`
1965
- * drive the selector UI; `layout` is the actual tree rendered in the preview
1966
- * and passed to the `KPI` component.
2153
+ * A registered KPI layout preset: `id` is stored in the widget config and resolved
2154
+ * back to a `ResponsiveLayout`; `label` / `description` drive the selector UI.
1967
2155
  */
1968
2156
  interface KpiLayoutPreset {
1969
2157
  id: string;
@@ -2001,14 +2189,8 @@ type ComponentSpecificPropsMap<TData> = {
2001
2189
  "kpi": KPISpecificProps<TData>;
2002
2190
  };
2003
2191
  /**
2004
- * Props for the Switcher component.
2005
- * Accepts the shared DataStructureComponent props plus an optional initial component.
2006
- *
2007
- * Two modes:
2008
- * - **Uncontrolled**: provide `initialComponent` / `initialComponentProps`. Switcher manages its own state.
2009
- * - **Controlled**: provide `activeComponent` / `componentProps`. The parent manages state,
2010
- * and the Switcher reflects changes immediately. Use this when an external configurator
2011
- * (e.g. DashboardBuilder) drives the configuration.
2192
+ * Props for the Switcher, which wraps a data-component and manages its specific props.
2193
+ * Uncontrolled: `initialComponent` / `initialComponentProps`; controlled: `activeComponent` / `componentProps`.
2012
2194
  */
2013
2195
  interface SwitcherProps<TData> extends DataStructureComponent<TData> {
2014
2196
  /** Initial active component. Defaults to "table-grid". (Uncontrolled mode) */
@@ -2028,22 +2210,14 @@ interface SwitcherProps<TData> extends DataStructureComponent<TData> {
2028
2210
  }
2029
2211
 
2030
2212
  /**
2031
- * Switcher — wraps a data-component
2032
- * Shared props (data, columns, uiConfig, getSubRows) are passed to every component.
2033
- * Specific props are managed per-component via the config overlay.
2034
- *
2035
- * Two modes:
2036
- * - **Uncontrolled**: provide `initialComponent` / `initialComponentProps`
2037
- * - **Controlled**: provide `activeComponent` / `componentProps` (external configurator drives state)
2213
+ * Wraps a data-component: shared props (data, columns, uiConfig, getSubRows) go to every
2214
+ * component, specific props are managed via the config overlay. Uncontrolled or controlled.
2038
2215
  */
2039
2216
  declare const Switcher: <TData extends object>({ data, columns, getSubRows, uiConfig, initialComponent, initialComponentProps, activeComponent: controlledComponent, componentProps: controlledProps, showConfigurator, onComponentChange, onComponentPropsChange, }: SwitcherProps<TData>) => React__default.JSX.Element;
2040
2217
 
2041
2218
  /**
2042
- * Where a prop field is configurable.
2043
- * - `"all"`: visible in both Switcher and Dashboard configurator
2044
- * - `"switcher"`: visible only in the Switcher panel
2045
- * - `"dashboard"`: visible only in the Dashboard configurator
2046
- * - `"none"`: not configurable via UI (callbacks, complex objects, etc.)
2219
+ * Where a prop field is configurable: "all" (both), "switcher", "dashboard",
2220
+ * or "none" (not configurable via UI).
2047
2221
  */
2048
2222
  type PropFieldScope = "all" | "switcher" | "dashboard" | "none";
2049
2223
  /**
@@ -2086,11 +2260,8 @@ interface PropFieldDescriptor {
2086
2260
  type PropSchemaRegistry = Record<string, PropFieldDescriptor[]>;
2087
2261
 
2088
2262
  /**
2089
- * Props for the shared DataComponentConfigurator.
2090
- *
2091
- * This component is used in two contexts:
2092
- * 1. **Switcher** — shows the component selector + prop form (scope: "switcher")
2093
- * 2. **Dashboard widget configurator** — shows only the prop form (scope: "dashboard")
2263
+ * Props for the shared DataComponentConfigurator, used by the Switcher (selector +
2264
+ * form, scope "switcher") and the Dashboard widget configurator (form only).
2094
2265
  */
2095
2266
  interface DataComponentConfiguratorProps {
2096
2267
  /** Schema for the active component's configurable fields. */
@@ -2119,15 +2290,8 @@ interface DataComponentConfiguratorProps {
2119
2290
  }
2120
2291
 
2121
2292
  /**
2122
- * Shared configurator for data-components.
2123
- *
2124
- * Renders:
2125
- * - An optional **component selector** (when `componentMetaList` is provided)
2126
- * - A **dynamic prop form** filtered by the given scope
2127
- *
2128
- * Used by:
2129
- * - **Switcher** — full configurator with component selector + all props
2130
- * - **Dashboard widget configurator** — prop form only (scope: "dashboard")
2293
+ * Shared configurator for data-components: an optional component selector
2294
+ * (`componentMetaList`) plus a dynamic prop form filtered by `scope`.
2131
2295
  */
2132
2296
  declare const DataComponentConfigurator: {
2133
2297
  ({ schema, values, onChange, columns, scope, componentId, onComponentChange, componentMetaList, }: DataComponentConfiguratorProps): React__default.JSX.Element;
@@ -2174,6 +2338,13 @@ interface BreadcrumbsProps extends React.HTMLAttributes<HTMLDivElement> {
2174
2338
 
2175
2339
  declare const Breadcrumbs: React__default.FC<BreadcrumbsProps>;
2176
2340
 
2341
+ interface DrawerProps {
2342
+ children: ReactNode;
2343
+ side?: Extract<OverlayPanelPosition, "left" | "right">;
2344
+ }
2345
+
2346
+ declare const Drawer: React__default.FC<DrawerProps>;
2347
+
2177
2348
  type SidebarLogoProps = {
2178
2349
  logo: string;
2179
2350
  /** Called when the logo button is clicked (e.g. to navigate home). */
@@ -2216,9 +2387,8 @@ interface StepperProps extends React.HTMLAttributes<HTMLElement> {
2216
2387
  }
2217
2388
 
2218
2389
  /**
2219
- * Horizontal stepper that renders ordered steps with idle/active/done states.
2220
- * Steps before `current` are automatically marked as done. Each step renders
2221
- * as a `Tag` whose state changes with the step status.
2390
+ * Horizontal stepper rendering ordered steps with idle/active/done states, each as a
2391
+ * `Tag`. Steps before `current` are marked done automatically.
2222
2392
  */
2223
2393
  declare const Stepper: React__default.FC<StepperProps>;
2224
2394
 
@@ -2305,10 +2475,8 @@ declare const BlankSlate: React__default.FC<BlankSlateProps> & {
2305
2475
  };
2306
2476
 
2307
2477
  /**
2308
- * Derives `FilterFieldProp[]` from column definitions.
2309
- *
2310
- * Columns without a resolvable ID or header are skipped.
2311
- * SELECT / BUTTON_GROUP columns populate `availableOptions` from `col.options`.
2478
+ * Derives `FilterFieldProp[]` from column definitions, skipping columns without a
2479
+ * resolvable ID or header and populating options from SELECT / BUTTON_GROUP columns.
2312
2480
  */
2313
2481
  declare function fieldOptionsFromColumns<TData>(columns: DataStructureColumn<TData>[]): FilterFieldProp[];
2314
2482
  /** Returns the available operator options for a given column type. */
@@ -2341,18 +2509,19 @@ declare function mergeFilters<TData>(global: FilterGroup | null, section: Filter
2341
2509
  * Empty groups do not count.
2342
2510
  */
2343
2511
  declare function countTopLevelFilters(filter: FilterGroup | null): number;
2512
+ /**
2513
+ * Counts ACTIVE conditions per `field.id` across the whole tree. Fields with zero active conditions are omitted. */
2514
+ declare function countActiveConditionsByField(filter: FilterGroup | null): Map<string, number>;
2515
+ /** Removes every condition with the given `field.id`, pruning groups left empty by the removal. Immutable — returns a new tree. */
2516
+ declare function removeFieldFilters(root: FilterGroup, fieldId: string): FilterGroup;
2344
2517
  /**
2345
2518
  * Counts active top-level filters across a map of per-data-source filter groups.
2346
2519
  */
2347
2520
  declare function countTopLevelFiltersMap(filters: Record<string, FilterGroup | null> | null): number;
2348
2521
 
2349
2522
  /**
2350
- * Filters `data` rows using the provided `FilterGroup` AST.
2351
- *
2352
- * - Returns the original `data` array reference unchanged when `filter` is
2353
- * `null` or contains no active conditions (avoids unnecessary re-renders).
2354
- * - Works with any `DataStructureComponent`-compatible column definition,
2355
- * resolving values via `accessorFn` or `accessorKey`.
2523
+ * Filters `data` with a `FilterGroup` AST, returning the same array reference when
2524
+ * the filter is null or empty. Values resolve via `accessorFn` or `accessorKey`.
2356
2525
  *
2357
2526
  * @example
2358
2527
  * const visible = applyFilter(data, filterGroup, columns);
@@ -2380,17 +2549,8 @@ interface FilterConditionEditorProps {
2380
2549
  readonly onGuidedComplete?: () => void;
2381
2550
  }
2382
2551
  /**
2383
- * Shared row-level filter condition editor: field → operator → value.
2384
- *
2385
- * Reused by both `FilterBuilder` (panel rows inside groups) and `FilterField`
2386
- * (inline chips in edit-in-place mode). This is the single place where field /
2387
- * operator / value input switching logic lives.
2388
- *
2389
- * Each piece (field, operator, value, delete) can be individually locked via
2390
- * `condition.readOnly` or the `readOnly` prop.
2391
- *
2392
- * When `guided` is `true`, the editor walks the user through the three steps,
2393
- * auto-opening the dropdown / focusing the input of the current step.
2552
+ * Shared row-level filter editor (field → operator → value), used by both `FilterBuilder`
2553
+ * and `FilterField`. Each piece can be locked, and `guided` walks the user through the steps.
2394
2554
  */
2395
2555
  declare const FilterConditionEditor: React.FC<FilterConditionEditorProps>;
2396
2556
 
@@ -2410,21 +2570,13 @@ interface FilterFieldProps {
2410
2570
  declare const FilterField: React.FC<FilterFieldProps>;
2411
2571
 
2412
2572
  /**
2413
- * Props for the Dashboard orchestrator component.
2414
- *
2415
- * Dashboard provides global filters to all child DashboardWidget instances
2416
- * and arranges them using the responsive Layout system.
2417
- *
2418
- * Global filters are organised per data source: each entry in `filters` is
2419
- * keyed by the data source id (e.g. "transactions", "budgets") and contains
2420
- * the filter tree specific to that source. Widgets pick the entry matching
2421
- * their own data source via context.
2573
+ * Props for the Dashboard orchestrator, which feeds global filters (keyed by data
2574
+ * source id) to every child DashboardWidget and lays them out with the Layout system.
2422
2575
  */
2423
2576
  interface DashboardProps {
2424
2577
  /**
2425
- * Global filter trees keyed by data source id.
2426
- * Each widget receives the entry whose key matches its data source,
2427
- * then merges it with its own per-section filters.
2578
+ * Global filter trees keyed by data source id. Each widget merges the entry matching
2579
+ * its own data source with its per-section filters.
2428
2580
  */
2429
2581
  filters: Record<string, FilterGroup | null> | null;
2430
2582
  /** Called when a data-source filter tree changes (key + new tree) */
@@ -2432,9 +2584,8 @@ interface DashboardProps {
2432
2584
  /** Responsive layout configuration (mobile / tablet / desktop breakpoints) */
2433
2585
  layout: ResponsiveLayout;
2434
2586
  /**
2435
- * Field definitions for the FilterBuilder, keyed by data source id.
2436
- * Each entry is shown as a separate tab/section inside the global filter
2437
- * overlay. Required when `enableFilter` is true.
2587
+ * FilterBuilder fields keyed by data source id, each shown as its own tab in the global
2588
+ * filter overlay. Required when `enableFilter` is true.
2438
2589
  */
2439
2590
  fieldOptions?: Record<string, FilterFieldProp[]>;
2440
2591
  /** Show a filter button that opens the FilterBuilder overlay */
@@ -2455,23 +2606,14 @@ interface DashboardContextValue {
2455
2606
  }
2456
2607
 
2457
2608
  /**
2458
- * Dashboard is the top-level orchestrator for a page of data widgets.
2459
- *
2460
- * It provides global filters to all child DashboardWidget instances via
2461
- * context, keyed by data source id, and arranges widgets using the
2462
- * responsive Layout system.
2463
- *
2464
- * When `enableFilter` is set, a filter button opens the FilterBuilder
2465
- * overlay where the user picks a data source and edits its filter tree.
2466
- * The button shows the total number of active top-level filters across
2467
- * all data sources.
2609
+ * Top-level orchestrator for a page of data widgets: shares global filters with every
2610
+ * child DashboardWidget (keyed by data source id) and arranges them with the Layout system.
2468
2611
  */
2469
2612
  declare const Dashboard: React__default.FC<DashboardProps>;
2470
2613
 
2471
2614
  /**
2472
- * Hook to consume the DashboardContext.
2473
- * Returns the current filters and onFilterChange callback.
2474
- * Returns null when used outside a Dashboard.
2615
+ * Reads the DashboardContext, returning the current filters and `onFilterChange`,
2616
+ * or null outside a Dashboard.
2475
2617
  */
2476
2618
  declare function useDashboard(): DashboardContextValue | null;
2477
2619
 
@@ -2483,14 +2625,8 @@ interface DashboardWidgetRenderPayload<TData> {
2483
2625
  data: TData[];
2484
2626
  }
2485
2627
  /**
2486
- * Props for the DashboardWidget component.
2487
- *
2488
- * Three modes are supported, depending on which props you provide:
2489
- *
2490
- * - **Passthrough mode**: provide only `data`. The data is used as-is —
2491
- * the server already prepared it. Zero frontend processing.
2492
- * - **Legacy mode**: provide `data` + `columns`. Global dashboard filters
2493
- * are applied client-side via `applyFilter()`.
2628
+ * Props for DashboardWidget. Passthrough mode takes only `data` and uses it as-is;
2629
+ * legacy mode takes `data` + `columns` and applies global filters client-side.
2494
2630
  */
2495
2631
  interface DashboardWidgetProps<TData> {
2496
2632
  /** Unique identifier for this widget (used as Layout block key) */
@@ -2498,9 +2634,8 @@ interface DashboardWidgetProps<TData> {
2498
2634
  /** Widget title displayed in the Section header */
2499
2635
  title: string;
2500
2636
  /**
2501
- * Data source identifier used to pick this widget's entry from the
2502
- * dashboard's per-source global filter map. Required to receive
2503
- * global filters (otherwise only the per-section filter applies).
2637
+ * Data source id that picks this widget's entry from the dashboard's per-source
2638
+ * filter map. Required to receive global filters.
2504
2639
  */
2505
2640
  dataSourceId?: string;
2506
2641
  /** Optional subtitle displayed below the title */
@@ -2508,10 +2643,8 @@ interface DashboardWidgetProps<TData> {
2508
2643
  /** Optional icon name (bundled SVG) shown before the title in the Section header */
2509
2644
  icon?: string;
2510
2645
  /**
2511
- * Data for this widget.
2512
- *
2513
- * - **Passthrough**: provide `data` alone → used as-is (server-ready).
2514
- * - **Legacy**: provide `data` + `columns` → global filters applied.
2646
+ * Data for this widget: alone it is used as-is (passthrough); with `columns`,
2647
+ * global filters are applied client-side.
2515
2648
  */
2516
2649
  data?: TData[];
2517
2650
  /**
@@ -2544,14 +2677,8 @@ interface DashboardWidgetProps<TData> {
2544
2677
  }
2545
2678
 
2546
2679
  /**
2547
- * DashboardWidget is a self-contained widget that:
2548
- * 1. Receives its own data (raw, pre-filtered, or engine-backed)
2549
- * 2. Renders a Section with a toolbar of actions (export, screenshot, expand)
2550
- * 3. Passes data to the render prop
2551
- *
2552
- * Three modes:
2553
- * - **Passthrough**: provide only `data` → used as-is (server-ready, zero processing)
2554
- * - **Legacy**: provide `data` + `columns` → global filters applied via `applyFilter()`
2680
+ * Self-contained widget that takes its own data (raw, pre-filtered, or engine-backed),
2681
+ * renders a Section with an action toolbar, and passes the data to the render prop.
2555
2682
  */
2556
2683
  declare const DashboardWidget: {
2557
2684
  <TData extends object>({ title, subtitle, icon, data, columns, children, enableExport, enableScreenshot, enableExpand, enableFilter, fieldOptions, filters, onFilterChange, ignoreGlobalFilters, dataSourceId, className, }: DashboardWidgetProps<TData>): React__default.JSX.Element;
@@ -3120,5 +3247,5 @@ interface AIChatPanelProps {
3120
3247
 
3121
3248
  declare function AIChatPanel({ aiProvider, toolDefinitions, schema, tableContext, onExecute, onValidate, emptyStateText, requiresConfirmation, quickActions, }: AIChatPanelProps): React$1.JSX.Element;
3122
3249
 
3123
- export { AIChatPanel, AnchoredOverlay, AppBar, Banner, BlankSlate, Breadcrumbs, Button, ButtonDropdown, ButtonGroup, Calendar, Card, CardList, Cell, CellType, Chart, Checkbox, CheckboxGroup, Dashboard, DashboardWidget, DataComponentConfigurator, DatePicker, DateRangePicker, FileUpload, FilterBuilder, FilterConditionEditor, FilterField, Form, Gantt, Icon, KPI, Kbd, Label, Layout, Markdown, Menu, MindTree, NumberInput, OTPComponent as OTP, OverlayPanel, ProgressBar, Radio, RadioGroup, Scaffold, Section, SelectionGrid, ShortcutProvider, Sidebar, Stack, Stepper, Switcher, TableGrid, Tag, Timeline, Tree, TreeCard, Workflow, WorkflowPanel, WorkflowToolbar, addNodeAtPath, applyFilter, cardLayoutPresetOptions, cardLayoutWithIcon, countTopLevelFilters, countTopLevelFiltersMap, createDataStructureFromFile, emptyCondition, emptyFilterGroup, fieldOptionsFromColumns, financeKpiLayout, financeKpiLayoutWithIcon, getDefaultOperator, getOperatorsForType, getReachableNodes, getTopologicalOrder, isFilterActive, kpiLayoutPresetOptions, mergeFilters, removeNodeAtPath, resolveCardLayoutPreset, resolveKpiLayoutPreset, stripByFields, updateNodeAtPath, useDashboard, useDynamicVirtualList, useScaffold, useShortcut, validateWorkflow };
3124
- export type { AIChatPanelProps, AIProvider, AIQuickAction, AIResponse, AITableContext, AnchoredOverlayProps, ApiAction, ApiActionConfig, AppBarActionsProps, AppBarMenuButtonProps, AppBarProps, AppBarTitleProps, BannerProps, BlankSlateAction, BlankSlateActionsProps, BlankSlateDescriptionProps, BlankSlateGraphicProps, BlankSlateHeadingProps, BlankSlatePreset, BlankSlateProps, BlockNode, BooleanOperator, BreadcrumbItem, BreadcrumbsProps, Breakpoint, ButtonDropdownProps, ButtonGroupProps, ButtonProps, CalendarProps, CardLayoutPreset, CardListProps, CardProps, CellProps, ChartProps, ChartType, ChatMessage, CheckboxGroupProps, CheckboxOption, CheckboxProps, ColumnDef, ColumnSchema, ComponentSpecificPropsMap, ComputedPivotData, ConditionAction, ConditionActionConfig, ConditionReadOnly, ConnectionPoint, DashboardProps, DashboardWidgetProps, DashboardWidgetRenderPayload, DataComponentConfiguratorProps, DataComponentId, DataStructureColumn, DataStructureComponent, DataStructureUIColumn, DataStructureUIConfig, DataStructureUIContainer, DataStructureUIRule, DateOperator, DatePickerMode, DatePickerProps, DateRange, DateRangePickerProps, DynamicVirtualItem, ExecutionResult, FilterBuilderProps, FilterColumnType, FilterCondition, FilterConditionEditorProps, FilterFieldProp, FilterFieldProps, FilterGroup, FilterNode, FilterOperator, FilterValue, FlexContainer, FormChangeResponse, FormColumn, FormColumnDelta, FormProps, GanttDependency, GanttProps, GanttRelationType, GanttView, GeoConfig, GridChild, GridContainer, IconProps, KPIProps, KPISpecificProps, KbdProps, KpiLayoutPreset, LabelProps, LayoutNode, LayoutProps, ListItemVariant, MarkdownProps, MenuItem, MenuProps, MenuSubmenuProps, MindTreeProps, NotificationAction, NotificationActionConfig, NumberInputProps, NumberOperator, OTPProps, OperatorOption, Option, OverlayPanelFooterProps, OverlayPanelHeaderProps, OverlayPanelPosition, OverlayPanelProps, OverlayPanelVariant, PivotAggregation, PivotConfig, PivotValueField, PositionedNode, ProgressBarProps, PropFieldDescriptor, PropFieldScope, PropSchemaRegistry, RadioGroupProps, RadioOption, RadioProps, ReingoldTilfordConfig, ResolvedCellUI, ResponsiveLayout, SankeyConfig, ScaffoldContextValue, ScaffoldProps, SectionProps, SelectionGridProps, ShortcutConfig, SidebarProps, SectionProps$1 as SidebarSectionProps, Size, StackProps, State, StepperItem, StepperProps, StepperStepState, StringOperator, SwitcherProps, TableGridProps, TableRow, TableState, TagProps, TimelineProps, ToolCall, ToolDefinition, TransformAction, TransformActionConfig, TreeCardProps, TreeDropPayload, TreeDropPosition, TreeHandle, TreeLayout, TreeNode, TreeProps, TreeRowScope, TreeRowState, UIRuleOperator, UseDynamicVirtualListOptions, UseDynamicVirtualListResult, UseShortcutOptions, UserProps, ValidationError, ValidationResult, ValidationWarning, WaitAction, WaitActionConfig, WorkflowAction, WorkflowActionType, WorkflowCondition, WorkflowContext, WorkflowEdge, WorkflowEdgeType, WorkflowLayout, WorkflowMode, WorkflowNode, WorkflowNodeProps, WorkflowNodeType, WorkflowPanelProps, WorkflowProps, WorkflowToolbarProps };
3250
+ export { AIChatPanel, AnchoredOverlay, AppBar, Banner, BlankSlate, Breadcrumbs, Button, ButtonDropdown, ButtonGroup, Calendar, Card, CardList, Cell, CellType, Chart, Checkbox, CheckboxGroup, Dashboard, DashboardWidget, DataComponentConfigurator, DatePicker, DateRangePicker, Drawer, FileUpload, FilterBuilder, FilterConditionEditor, FilterField, Form, Gantt, Icon, Input, KPI, Kbd, Label, Layout, Markdown, Menu, MindTree, NumberInput, OTPComponent as OTP, OverlayPanel, ProgressBar, Radio, RadioGroup, Scaffold, Section, Select, SelectionGrid, ShortcutProvider, Sidebar, Stack, Stepper, Switcher, TableGrid, TableRowModel, TableSortingMode, Tag, TextInput, Textarea, Timeline, Tree, TreeCard, Typography, Workflow, WorkflowPanel, WorkflowToolbar, addNodeAtPath, applyFilter, cardLayoutPresetOptions, cardLayoutWithIcon, countActiveConditionsByField, countTopLevelFilters, countTopLevelFiltersMap, createDataStructureFromFile, emptyCondition, emptyFilterGroup, fieldOptionsFromColumns, financeKpiLayout, financeKpiLayoutWithIcon, getDefaultOperator, getOperatorsForType, getReachableNodes, getTopologicalOrder, isFilterActive, kpiLayoutPresetOptions, mergeFilters, removeFieldFilters, removeNodeAtPath, resolveCardLayoutPreset, resolveKpiLayoutPreset, stripByFields, updateNodeAtPath, useDashboard, useDynamicVirtualList, useScaffold, useShortcut, validateWorkflow };
3251
+ export type { AIChatPanelProps, AIProvider, AIQuickAction, AIResponse, AITableContext, AnchoredOverlayProps, ApiAction, ApiActionConfig, AppBarActionsProps, AppBarMenuButtonProps, AppBarProps, AppBarTitleProps, BannerProps, BlankSlateAction, BlankSlateActionsProps, BlankSlateDescriptionProps, BlankSlateGraphicProps, BlankSlateHeadingProps, BlankSlatePreset, BlankSlateProps, BlockNode, BooleanOperator, BreadcrumbItem, BreadcrumbsProps, Breakpoint, ButtonDropdownProps, ButtonGroupProps, ButtonProps, CalendarProps, CardLayoutPreset, CardListProps, CardProps, CellProps, ChartProps, ChartType, ChatMessage, CheckboxGroupProps, CheckboxOption, CheckboxProps, ColumnDef, ColumnSchema, ComponentSpecificPropsMap, ComputedPivotData, ConditionAction, ConditionActionConfig, ConditionReadOnly, ConnectionPoint, DashboardProps, DashboardWidgetProps, DashboardWidgetRenderPayload, DataComponentConfiguratorProps, DataComponentId, DataStructureColumn, DataStructureComponent, DataStructureUIColumn, DataStructureUIConfig, DataStructureUIContainer, DataStructureUIRule, DateOperator, DatePickerMode, DatePickerProps, DateRange, DateRangePickerProps, DrawerProps, DynamicVirtualItem, ExecutionResult, FeatureSupport, FilterBuilderProps, FilterColumnType, FilterCondition, FilterConditionEditorProps, FilterFieldProp, FilterFieldProps, FilterGroup, FilterNode, FilterOperator, FilterValue, FlexContainer, FormChangeResponse, FormColumn, FormColumnDelta, FormProps, GanttDependency, GanttProps, GanttRelationType, GanttView, GeoConfig, GridChild, GridContainer, IconProps, InputProps, KPIProps, KPISpecificProps, KbdProps, KpiLayoutPreset, LabelProps, LayoutNode, LayoutProps, ListItemVariant, MarkdownProps, MenuItem, MenuProps, MenuSubmenuProps, MindTreeProps, NotificationAction, NotificationActionConfig, NumberInputProps, NumberOperator, OTPProps, OperatorOption, Option, OverlayPanelFooterProps, OverlayPanelHeaderProps, OverlayPanelPosition, OverlayPanelProps, OverlayPanelVariant, PivotAggregation, PivotConfig, PivotValueField, PositionedNode, ProgressBarProps, PropFieldDescriptor, PropFieldScope, PropSchemaRegistry, RadioGroupProps, RadioOption, RadioProps, ReingoldTilfordConfig, ResolvedCellUI, ResponsiveLayout, SankeyConfig, ScaffoldContextValue, ScaffoldProps, SectionProps, SelectProps, SelectionGridProps, ServerDatasource, ServerGroupRow, ServerRowRequest, ServerRowResponse, ShortcutConfig, SidebarProps, SectionProps$1 as SidebarSectionProps, Size, StackProps, State, StepperItem, StepperProps, StepperStepState, StringOperator, SwitcherProps, TableGridProps, TableModelFeature, TableRow, TableState, TagProps, TextInputProps, TextareaProps, TimelineProps, ToolCall, ToolDefinition, TransformAction, TransformActionConfig, TreeCardProps, TreeDropPayload, TreeDropPosition, TreeHandle, TreeLayout, TreeNode, TreeProps, TreeRowScope, TreeRowState, TypographyProps, TypographyVariant, UIRuleOperator, UseDynamicVirtualListOptions, UseDynamicVirtualListResult, UseShortcutOptions, UserProps, ValidationError, ValidationResult, ValidationWarning, WaitAction, WaitActionConfig, WorkflowAction, WorkflowActionType, WorkflowCondition, WorkflowContext, WorkflowEdge, WorkflowEdgeType, WorkflowLayout, WorkflowMode, WorkflowNode, WorkflowNodeProps, WorkflowNodeType, WorkflowPanelProps, WorkflowProps, WorkflowToolbarProps };