@calcifer-design/ui 0.8.0 → 0.9.0

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 (152) hide show
  1. package/dist/components/Alert/Alert.module.js +5 -5
  2. package/dist/components/Alert/Alert_module.css +14 -14
  3. package/dist/components/Avatar/Avatar.module.js +3 -3
  4. package/dist/components/Avatar/Avatar_module.css +15 -15
  5. package/dist/components/AvatarGroup/AvatarGroup.module.js +4 -4
  6. package/dist/components/AvatarGroup/AvatarGroup_module.css +10 -10
  7. package/dist/components/Breadcrumb/Breadcrumb.module.js +6 -6
  8. package/dist/components/Breadcrumb/Breadcrumb_module.css +7 -7
  9. package/dist/components/Button/Button.module.js +6 -6
  10. package/dist/components/Button/Button_module.css +32 -32
  11. package/dist/components/Card/Card.module.js +5 -5
  12. package/dist/components/Card/Card_module.css +7 -7
  13. package/dist/components/CardList/CardList.module.js +3 -3
  14. package/dist/components/CardList/CardList_module.css +3 -3
  15. package/dist/components/Checkbox/Checkbox.module.js +2 -2
  16. package/dist/components/Checkbox/Checkbox_module.css +3 -3
  17. package/dist/components/ChoiceCard/ChoiceCard.module.js +8 -8
  18. package/dist/components/ChoiceCard/ChoiceCard_module.css +25 -25
  19. package/dist/components/Collapsible/Collapsible.module.js +6 -6
  20. package/dist/components/Collapsible/Collapsible_module.css +11 -11
  21. package/dist/components/DataGrid/DataGrid.d.ts +1 -1
  22. package/dist/components/DataGrid/DataGrid.js +149 -64
  23. package/dist/components/DataGrid/DataGrid.module.js +45 -32
  24. package/dist/components/DataGrid/DataGrid_module.css +202 -70
  25. package/dist/components/DataGrid/GridCardHeader.d.ts +40 -4
  26. package/dist/components/DataGrid/GridCardHeader.js +79 -11
  27. package/dist/components/DataGrid/GridChoiceFilter.d.ts +21 -0
  28. package/dist/components/DataGrid/GridChoiceFilter.js +157 -0
  29. package/dist/components/DataGrid/GridFilterRow.d.ts +22 -0
  30. package/dist/components/DataGrid/GridFilterRow.js +66 -0
  31. package/dist/components/DataGrid/GridHeaderCell.d.ts +5 -2
  32. package/dist/components/DataGrid/GridHeaderCell.js +4 -3
  33. package/dist/components/DataGrid/GridHeaderRow.d.ts +3 -1
  34. package/dist/components/DataGrid/GridHeaderRow.js +2 -1
  35. package/dist/components/DataGrid/GridRow.d.ts +8 -4
  36. package/dist/components/DataGrid/GridRow.js +4 -4
  37. package/dist/components/DataGrid/GridSearch.d.ts +19 -0
  38. package/dist/components/DataGrid/GridSearch.js +32 -0
  39. package/dist/components/DataGrid/GridStateRows.d.ts +36 -9
  40. package/dist/components/DataGrid/GridStateRows.js +34 -18
  41. package/dist/components/DataGrid/GridTextFilter.d.ts +14 -0
  42. package/dist/components/DataGrid/GridTextFilter.js +21 -0
  43. package/dist/components/DataGrid/columns.d.ts +31 -8
  44. package/dist/components/DataGrid/labels.d.ts +24 -0
  45. package/dist/components/DataGrid/labels.js +14 -0
  46. package/dist/components/DataGrid/query.d.ts +40 -0
  47. package/dist/components/DataGrid/query.js +128 -0
  48. package/dist/components/DataGrid/types.d.ts +52 -7
  49. package/dist/components/DataGrid/useDebouncedDraft.d.ts +20 -0
  50. package/dist/components/DataGrid/useDebouncedDraft.js +71 -0
  51. package/dist/components/DataGrid/useGridEntries.d.ts +3 -2
  52. package/dist/components/DataGrid/useGridKeyboard.d.ts +17 -7
  53. package/dist/components/DataGrid/useGridKeyboard.js +18 -8
  54. package/dist/components/DataGrid/useGridMetrics.d.ts +4 -1
  55. package/dist/components/DataGrid/useGridMetrics.js +4 -0
  56. package/dist/components/DataGrid/useGridQuery.d.ts +48 -0
  57. package/dist/components/DataGrid/useGridQuery.js +71 -0
  58. package/dist/components/DataTable/DataTable.module.js +9 -9
  59. package/dist/components/DataTable/DataTable_module.css +19 -19
  60. package/dist/components/DatePicker/DatePicker.module.js +10 -10
  61. package/dist/components/DatePicker/DatePicker_module.css +18 -18
  62. package/dist/components/Descriptions/Descriptions.module.js +4 -4
  63. package/dist/components/Descriptions/Descriptions_module.css +8 -8
  64. package/dist/components/Dialog/Dialog.module.js +8 -8
  65. package/dist/components/Dialog/Dialog_module.css +15 -15
  66. package/dist/components/EmptyState/EmptyState.module.js +5 -5
  67. package/dist/components/EmptyState/EmptyState_module.css +10 -10
  68. package/dist/components/ErrorBoundary/ErrorBoundary.module.js +1 -1
  69. package/dist/components/ErrorBoundary/ErrorBoundary_module.css +1 -1
  70. package/dist/components/Field/PickerField.module.js +4 -4
  71. package/dist/components/Field/PickerField_module.css +7 -7
  72. package/dist/components/FilterBar/FilterBar.module.js +9 -9
  73. package/dist/components/FilterBar/FilterBar_module.css +13 -13
  74. package/dist/components/Form/Form.module.js +1 -1
  75. package/dist/components/Form/Form_module.css +1 -1
  76. package/dist/components/IconButton/IconButton.d.ts +12 -1
  77. package/dist/components/IconButton/IconButton.js +19 -9
  78. package/dist/components/IconButton/IconButton.module.js +3 -2
  79. package/dist/components/IconButton/IconButton_module.css +68 -14
  80. package/dist/components/Menu/Menu.module.js +2 -2
  81. package/dist/components/Menu/Menu_module.css +4 -4
  82. package/dist/components/NavMenu/NavMenu.module.js +6 -6
  83. package/dist/components/NavMenu/NavMenu_module.css +12 -12
  84. package/dist/components/PageHeading/PageHeading.module.js +3 -3
  85. package/dist/components/PageHeading/PageHeading_module.css +8 -8
  86. package/dist/components/PageShell/PageShell.module.js +5 -5
  87. package/dist/components/PageShell/PageShell_module.css +9 -9
  88. package/dist/components/Popover/Popover.module.js +2 -2
  89. package/dist/components/Popover/Popover_module.css +2 -2
  90. package/dist/components/ProgressBar/ProgressBar.module.js +8 -8
  91. package/dist/components/ProgressBar/ProgressBar_module.css +19 -19
  92. package/dist/components/RadioGroup/RadioGroup.module.js +2 -2
  93. package/dist/components/RadioGroup/RadioGroup_module.css +2 -2
  94. package/dist/components/SearchField/SearchField.module.js +4 -4
  95. package/dist/components/SearchField/SearchField_module.css +7 -7
  96. package/dist/components/Segmented/Segmented.module.js +4 -4
  97. package/dist/components/Segmented/Segmented_module.css +13 -13
  98. package/dist/components/Select/Select.module.js +5 -5
  99. package/dist/components/Select/Select_module.css +11 -11
  100. package/dist/components/Skeleton/Skeleton.module.js +3 -3
  101. package/dist/components/Skeleton/Skeleton_module.css +7 -7
  102. package/dist/components/SkipLink/SkipLink.module.js +1 -1
  103. package/dist/components/SkipLink/SkipLink_module.css +2 -2
  104. package/dist/components/Spinner/Spinner.module.js +3 -3
  105. package/dist/components/Spinner/Spinner_module.css +7 -7
  106. package/dist/components/StatusDot/StatusDot.module.js +5 -5
  107. package/dist/components/StatusDot/StatusDot_module.css +11 -11
  108. package/dist/components/Steps/Steps.module.js +6 -6
  109. package/dist/components/Steps/Steps_module.css +19 -19
  110. package/dist/components/Switch/Switch.module.js +2 -2
  111. package/dist/components/Switch/Switch_module.css +5 -5
  112. package/dist/components/TabBar/TabBar.module.js +7 -7
  113. package/dist/components/TabBar/TabBar_module.css +13 -13
  114. package/dist/components/Tabs/Tabs.module.js +4 -4
  115. package/dist/components/Tabs/Tabs_module.css +6 -6
  116. package/dist/components/Tag/Tag.module.js +1 -1
  117. package/dist/components/Tag/Tag_module.css +2 -2
  118. package/dist/components/TextArea/TextArea.module.js +1 -1
  119. package/dist/components/TextArea/TextArea_module.css +3 -3
  120. package/dist/components/ThemeScope/ThemeScope.module.js +2 -2
  121. package/dist/components/ThemeScope/ThemeScope_module.css +2 -2
  122. package/dist/components/Timeline/Timeline.module.js +8 -8
  123. package/dist/components/Timeline/Timeline_module.css +13 -13
  124. package/dist/components/ToastRegion/ToastRegion.module.js +6 -6
  125. package/dist/components/ToastRegion/ToastRegion_module.css +15 -15
  126. package/dist/components/ToggleChip/ToggleChip.module.js +5 -5
  127. package/dist/components/ToggleChip/ToggleChip_module.css +14 -14
  128. package/dist/components/Toolbar/Toolbar.module.js +3 -3
  129. package/dist/components/Toolbar/Toolbar_module.css +5 -5
  130. package/dist/components/Tree/Tree.module.js +8 -8
  131. package/dist/components/Tree/Tree_module.css +20 -20
  132. package/dist/components/TreeSelect/TreeSelect.module.js +3 -3
  133. package/dist/components/TreeSelect/TreeSelect_module.css +4 -4
  134. package/dist/components/Upload/Upload.module.js +8 -8
  135. package/dist/components/Upload/Upload_module.css +16 -16
  136. package/dist/components/ViewField/ViewField.module.js +2 -2
  137. package/dist/components/ViewField/ViewField_module.css +3 -3
  138. package/dist/icons/FilterIcon.d.ts +6 -0
  139. package/dist/icons/FilterIcon.js +17 -0
  140. package/dist/index.d.ts +2 -1
  141. package/dist/index.js +1 -0
  142. package/dist/styles/a11y.module.js +1 -1
  143. package/dist/styles/a11y_module.css +1 -1
  144. package/dist/styles/closeCircle.module.js +1 -1
  145. package/dist/styles/closeCircle_module.css +2 -2
  146. package/dist/styles/field.module.js +14 -14
  147. package/dist/styles/field_module.css +33 -33
  148. package/dist/styles/pair.module.js +2 -2
  149. package/dist/styles/pair_module.css +3 -3
  150. package/dist/styles/popup.module.js +5 -5
  151. package/dist/styles/popup_module.css +17 -17
  152. package/package.json +1 -1
@@ -1,34 +1,50 @@
1
1
  import { jsx, jsxs } from "react/jsx-runtime";
2
2
  import { Button } from "../Button/Button.js";
3
+ import { EmptyState } from "../EmptyState/EmptyState.js";
3
4
  import { Spinner } from "../Spinner/Spinner.js";
4
5
  import DataGrid_module from "./DataGrid.module.js";
5
- function GridStateRow({ kind, label, emptyState, columnCount }) {
6
+ function GridStateRow({ kind, label, replacement, clearFilters, headingLevel, columnCount, firstEntryRow }) {
7
+ let content;
8
+ content = 'loading' === kind ? /*#__PURE__*/ jsxs("div", {
9
+ className: DataGrid_module.state,
10
+ "aria-hidden": "true",
11
+ children: [
12
+ /*#__PURE__*/ jsx(Spinner, {
13
+ size: "md"
14
+ }),
15
+ label
16
+ ]
17
+ }) : 'empty' === kind ? replacement ?? /*#__PURE__*/ jsx("div", {
18
+ className: DataGrid_module.state,
19
+ "aria-hidden": "true",
20
+ children: label
21
+ }) : replacement ?? /*#__PURE__*/ jsx(EmptyState, {
22
+ heading: label,
23
+ headingLevel: headingLevel,
24
+ className: DataGrid_module.filteredEmpty,
25
+ actions: clearFilters ? /*#__PURE__*/ jsx(Button, {
26
+ variant: "secondary",
27
+ size: "sm",
28
+ onClick: clearFilters.onClick,
29
+ children: clearFilters.label
30
+ }) : void 0
31
+ });
6
32
  return /*#__PURE__*/ jsx("tr", {
7
- "aria-rowindex": 2,
33
+ "aria-rowindex": firstEntryRow + 1,
8
34
  children: /*#__PURE__*/ jsx("td", {
9
35
  role: "gridcell",
10
36
  className: DataGrid_module.stateCell,
11
37
  colSpan: columnCount,
12
38
  "aria-colindex": 1,
13
- children: 'loading' === kind ? /*#__PURE__*/ jsxs("div", {
14
- className: DataGrid_module.state,
15
- "aria-hidden": "true",
16
- children: [
17
- /*#__PURE__*/ jsx(Spinner, {
18
- size: "md"
19
- }),
20
- label
21
- ]
22
- }) : emptyState ?? /*#__PURE__*/ jsx("div", {
23
- className: DataGrid_module.state,
24
- "aria-hidden": "true",
25
- children: label
39
+ children: /*#__PURE__*/ jsx("div", {
40
+ className: DataGrid_module.inView,
41
+ children: content
26
42
  })
27
43
  })
28
44
  });
29
45
  }
30
- function GridErrorRow({ entryIndex, columnCount, message, retryLabel, onRetry, getCellProps }) {
31
- const rowIndex = entryIndex + 1;
46
+ function GridErrorRow({ entryIndex, firstEntryRow, columnCount, message, retryLabel, onRetry, getCellProps }) {
47
+ const rowIndex = entryIndex + firstEntryRow;
32
48
  return /*#__PURE__*/ jsx("tr", {
33
49
  "data-index": entryIndex,
34
50
  "aria-rowindex": rowIndex + 1,
@@ -39,7 +55,7 @@ function GridErrorRow({ entryIndex, columnCount, message, retryLabel, onRetry, g
39
55
  "aria-colindex": 1,
40
56
  ...getCellProps(rowIndex, 0, columnCount),
41
57
  children: /*#__PURE__*/ jsxs("div", {
42
- className: DataGrid_module.errorContent,
58
+ className: `${DataGrid_module.inView} ${DataGrid_module.errorContent}`,
43
59
  children: [
44
60
  /*#__PURE__*/ jsx("span", {
45
61
  role: "alert",
@@ -0,0 +1,14 @@
1
+ export interface GridTextFilterProps {
2
+ /** "Filter by <column>". */
3
+ label: string;
4
+ /** The filter's value in the query. */
5
+ value: string;
6
+ /** Called once typing pauses, on Enter, and when focus leaves the field with a change pending. */
7
+ onValueChange: (value: string) => void;
8
+ }
9
+ /**
10
+ * A column's text filter in the filter strip: what is typed applies 300ms after typing stops, or at
11
+ * once on Enter. Leaving the field applies a pending change too, so that a click elsewhere, such as
12
+ * on Clear filters, acts on the query with it, and the typed text never comes back afterwards.
13
+ */
14
+ export declare function GridTextFilter({ label, value, onValueChange }: GridTextFilterProps): import("react").JSX.Element;
@@ -0,0 +1,21 @@
1
+ import { jsx } from "react/jsx-runtime";
2
+ import { TextInput } from "../TextInput/TextInput.js";
3
+ import { useDebouncedDraft } from "./useDebouncedDraft.js";
4
+ const textFilterDelayMs = 300;
5
+ function GridTextFilter({ label, value, onValueChange }) {
6
+ const { draft, change, flush } = useDebouncedDraft(value, onValueChange, textFilterDelayMs);
7
+ return /*#__PURE__*/ jsx(TextInput, {
8
+ type: "search",
9
+ "aria-label": label,
10
+ size: 1,
11
+ value: draft,
12
+ onValueChange: change,
13
+ onKeyDown: (event)=>{
14
+ if ('Enter' !== event.key) return;
15
+ event.preventDefault();
16
+ flush();
17
+ },
18
+ onBlur: flush
19
+ });
20
+ }
21
+ export { GridTextFilter };
@@ -10,26 +10,49 @@ export declare const dataGridFeatures: {
10
10
  datetime: import("@tanstack/react-table").CreatedSortFn<any, any>;
11
11
  };
12
12
  };
13
- export interface TextValueOption<Row extends RowData> {
14
- /** Plain text for a cell: the row label, compact-density titles, and later search and export. */
13
+ export interface DataGridFilterOption {
14
+ /** Compared with the column's text value for a row. */
15
+ value: string;
16
+ label: string;
17
+ }
18
+ /**
19
+ * A column's filter in the filter strip. Keep a choice filter's `options` the same array across
20
+ * renders, as the columns themselves must be: a new array rebuilds the list, and a select then
21
+ * drops the text the user is typing in it.
22
+ */
23
+ export type DataGridColumnFilter = {
24
+ type: 'text';
25
+ } | {
26
+ type: 'select';
27
+ options: readonly DataGridFilterOption[];
28
+ } | {
29
+ type: 'multiSelect';
30
+ options: readonly DataGridFilterOption[];
31
+ };
32
+ export interface DataGridColumnOptions<Row extends RowData> {
33
+ /** Plain text for a cell: the row label, compact titles, filtering, search and later export. */
15
34
  textValue?: (row: Row) => string;
35
+ /** The column's filter in the filter strip. Without one, the column has no filter. */
36
+ filter?: DataGridColumnFilter;
37
+ /** Whether search reads this column. Defaults to true; a column with no text is never matched. */
38
+ searchable?: boolean;
16
39
  }
17
- export type DataGridColumnDef<Row extends RowData, Value = unknown> = TanStackColumnDef<typeof dataGridFeatures, Row, Value> & TextValueOption<Row>;
40
+ export type DataGridColumnDef<Row extends RowData, Value = unknown> = TanStackColumnDef<typeof dataGridFeatures, Row, Value> & DataGridColumnOptions<Row>;
18
41
  export type DataGridFeatures = typeof dataGridFeatures;
19
42
  type Features = DataGridFeatures;
20
43
  export interface DataGridColumnHelper<Row extends RowData> {
21
- accessor: <Accessor extends AccessorFn<Row> | DeepKeys<Row>, Value extends (Accessor extends AccessorFn<Row, infer Returned> ? Returned : Accessor extends DeepKeys<Row> ? DeepValue<Row, Accessor> : never)>(accessor: Accessor, column: (Accessor extends AccessorFn<Row> ? DisplayColumnDef<Features, Row, Value> : IdentifiedColumnDef<Features, Row, Value>) & TextValueOption<Row>) => (Accessor extends AccessorFn<Row> ? AccessorFnColumnDef<Features, Row, Value> : AccessorKeyColumnDef<Features, Row, Value>) & TextValueOption<Row>;
44
+ accessor: <Accessor extends AccessorFn<Row> | DeepKeys<Row>, Value extends (Accessor extends AccessorFn<Row, infer Returned> ? Returned : Accessor extends DeepKeys<Row> ? DeepValue<Row, Accessor> : never)>(accessor: Accessor, column: (Accessor extends AccessorFn<Row> ? DisplayColumnDef<Features, Row, Value> : IdentifiedColumnDef<Features, Row, Value>) & DataGridColumnOptions<Row>) => (Accessor extends AccessorFn<Row> ? AccessorFnColumnDef<Features, Row, Value> : AccessorKeyColumnDef<Features, Row, Value>) & DataGridColumnOptions<Row>;
22
45
  /**
23
46
  * Wrap the array in this, not a plain literal: it keeps each column's own value type. The
24
47
  * `any` is TanStack's own signature for the same helper.
25
48
  */
26
49
  columns: <Columns extends ReadonlyArray<DataGridColumnDef<Row, any>>>(columns: [...Columns]) => Array<DataGridColumnDef<Row, any>> & [...Columns];
27
- display: (column: DisplayColumnDef<Features, Row> & TextValueOption<Row>) => DisplayColumnDef<Features, Row, unknown> & TextValueOption<Row>;
50
+ display: (column: DisplayColumnDef<Features, Row> & DataGridColumnOptions<Row>) => DisplayColumnDef<Features, Row, unknown> & DataGridColumnOptions<Row>;
28
51
  }
29
52
  /**
30
- * The TanStack v9 column helper, typed to the grid's feature set, with one extra column option:
31
- * `textValue`. At runtime TanStack's helper only returns the definition objects it is given, so
32
- * the extra option passes straight through.
53
+ * The TanStack v9 column helper, typed to the grid's feature set, with extra column options:
54
+ * `textValue`, `filter` and `searchable`. At runtime TanStack's helper only returns the definition
55
+ * objects it is given, so the extra options pass straight through.
33
56
  */
34
57
  export declare function createDataGridColumnHelper<Row extends RowData>(): DataGridColumnHelper<Row>;
35
58
  /**
@@ -1,13 +1,37 @@
1
1
  export interface DataGridLabels {
2
2
  toolbar: string;
3
3
  refresh: string;
4
+ /** The search button's name; it is pressed while the search field shows. */
5
+ search: string;
6
+ /** The search field's name. */
7
+ searchField: string;
8
+ /** The search field's clear button. */
9
+ clearSearch: string;
10
+ /** The filters button's name; the count of active filters and search is in it from 1 up. */
11
+ filters: (activeCount: number) => string;
12
+ /** Names the All / Any switch that says how the column filters combine. */
13
+ matchMode: string;
14
+ matchAll: string;
15
+ matchAny: string;
16
+ /** Names a column's control in the filter strip. */
17
+ filterBy: (columnName: string) => string;
18
+ /** The choice filters' first item, which clears the filter, and their text with nothing chosen. */
19
+ filterAll: string;
20
+ /** A multi-select filter's text with more than one option chosen. */
21
+ filterSelectedCount: (count: number) => string;
22
+ /** A choice filter's list when what is typed matches no option. */
23
+ filterNoOptions: string;
4
24
  rowCount: (count: number) => string;
5
25
  loadedRowCount: (loaded: number, total: number) => string;
26
+ /** Client mode while filters or search are active: the rows shown of every row. */
27
+ filteredRowCount: (shown: number, total: number) => string;
6
28
  selectedCount: (count: number) => string;
7
29
  loading: string;
8
30
  loadingMore: string;
9
31
  retry: string;
10
32
  empty: string;
33
+ filteredEmpty: string;
34
+ clearFilters: string;
11
35
  selectAll: string;
12
36
  selectRow: (rowLabel: string) => string;
13
37
  /** The expand column's header, which shows nothing but needs a name. */
@@ -2,13 +2,27 @@ const numberFormat = new Intl.NumberFormat('en-US');
2
2
  const defaultDataGridLabels = {
3
3
  toolbar: 'Grid tools',
4
4
  refresh: 'Refresh',
5
+ search: 'Search',
6
+ searchField: 'Search rows',
7
+ clearSearch: 'Clear search',
8
+ filters: (activeCount)=>0 === activeCount ? 'Filters' : `Filters, ${activeCount} active`,
9
+ matchMode: 'Match filters',
10
+ matchAll: 'All',
11
+ matchAny: 'Any',
12
+ filterBy: (columnName)=>`Filter by ${columnName}`,
13
+ filterAll: 'All',
14
+ filterSelectedCount: (count)=>`${numberFormat.format(count)} selected`,
15
+ filterNoOptions: 'No matching options',
5
16
  rowCount: (count)=>`${numberFormat.format(count)} ${1 === count ? 'row' : 'rows'}`,
6
17
  loadedRowCount: (loaded, total)=>`Showing ${numberFormat.format(loaded)} of ${numberFormat.format(total)} rows`,
18
+ filteredRowCount: (shown, total)=>`${numberFormat.format(shown)} of ${numberFormat.format(total)} ${1 === total ? 'row' : 'rows'}`,
7
19
  selectedCount: (count)=>`${numberFormat.format(count)} selected`,
8
20
  loading: 'Loading rows…',
9
21
  loadingMore: 'Loading more rows…',
10
22
  retry: 'Try again',
11
23
  empty: 'No rows to show.',
24
+ filteredEmpty: 'No rows match the search or filters.',
25
+ clearFilters: 'Clear filters',
12
26
  selectAll: 'Select all rows',
13
27
  selectRow: (rowLabel)=>`Select ${rowLabel}`,
14
28
  expandColumn: 'Details',
@@ -0,0 +1,40 @@
1
+ import type { RowData } from '@tanstack/react-table';
2
+ import { type DataGridColumnDef } from './columns.js';
3
+ import type { DataGridQuery } from './types.js';
4
+ /**
5
+ * The id TanStack gives a column definition: `id`, else `accessorKey` with every `.` replaced by
6
+ * `_`, else a string `header`. Written out here because the definition is all the query has.
7
+ */
8
+ export declare function columnIdOf<Row extends RowData, Value = unknown>(column: DataGridColumnDef<Row, Value>): string | undefined;
9
+ /** The column's header when it is a string, else its id: the name in "Filter by <name>". */
10
+ export declare function columnNameOf<Row extends RowData, Value = unknown>(column: DataGridColumnDef<Row, Value>): string;
11
+ /**
12
+ * A search term as a case-insensitive, unanchored RegExp: `*` is any run of characters, `?` is one
13
+ * character (a new line or a code point of two units too), everything else is literal. The term
14
+ * is trimmed; an empty term gives null. A term of only stars matches every text, the empty one
15
+ * included. It is a JavaScript RegExp (a capturing lookahead, a backreference, `[^]` and the `u`
16
+ * flag), so a JavaScript server matches with it exactly as client mode does; its `source` is not
17
+ * portable to other engines, such as a database's.
18
+ */
19
+ export declare function dataGridSearchPattern(term: string): RegExp | null;
20
+ /** No sort, filter or search. Frozen: grids and tests share it, so nothing may change it in place. */
21
+ export declare const emptyDataGridQuery: DataGridQuery;
22
+ /**
23
+ * A full query from a partial one, keeping only what can apply: text values and the search
24
+ * trimmed, empty values dropped, and filters dropped whose column is unknown, has no filter, or
25
+ * whose value has the wrong shape (a string for `text` and `select`, a non-empty string array for
26
+ * `multiSelect`).
27
+ *
28
+ * `useDebouncedDraft` tells the echo of its own commit from a reset elsewhere by this trimming
29
+ * alone ("hex " comes back as "hex"): a change to how text is normalised here must change it too.
30
+ */
31
+ export declare function normaliseQuery<Row extends RowData>(query: Partial<DataGridQuery> | undefined, columns: readonly DataGridColumnDef<Row, unknown>[]): DataGridQuery;
32
+ /** Active column filters plus one for a search: the filter button's badge. */
33
+ export declare function countActiveCriteria(query: DataGridQuery): number;
34
+ /** Whether two queries are the same, value for value; a multi-select's values in any order. */
35
+ export declare function isSameQuery(first: DataGridQuery, second: DataGridQuery): boolean;
36
+ /**
37
+ * A predicate for rows that match a normalised query, or null when the query has no filters and
38
+ * no search. Search and the filters combine with AND; the filters with each other by `matchMode`.
39
+ */
40
+ export declare function createQueryMatcher<Row extends RowData>(columns: readonly DataGridColumnDef<Row, unknown>[], query: DataGridQuery): ((row: Row) => boolean) | null;
@@ -0,0 +1,128 @@
1
+ import { textValueOf } from "./columns.js";
2
+ function columnIdOf(column) {
3
+ if (void 0 !== column.id) return column.id;
4
+ if ('accessorKey' in column && void 0 !== column.accessorKey) return String(column.accessorKey).replaceAll('.', '_');
5
+ return 'string' == typeof column.header ? column.header : void 0;
6
+ }
7
+ function columnNameOf(column) {
8
+ return 'string' == typeof column.header ? column.header : columnIdOf(column) ?? '';
9
+ }
10
+ function dataGridSearchPattern(term) {
11
+ const trimmed = term.trim();
12
+ if ('' === trimmed) return null;
13
+ const segments = trimmed.split(/\*+/).filter((segment)=>'' !== segment).map((segment)=>segment.replace(/[.+?^${}()|[\]\\]/g, (character)=>'?' === character ? '.' : `\\${character}`));
14
+ const [first = '', ...rest] = segments;
15
+ const source = rest.reduce((pattern, segment, index)=>`${pattern}(?=([^]*?${segment}))\\${index + 1}`, first);
16
+ return new RegExp(source, 'isu');
17
+ }
18
+ const emptyDataGridQuery = {
19
+ sorting: [],
20
+ filters: {},
21
+ matchMode: 'all',
22
+ search: ''
23
+ };
24
+ Object.freeze(emptyDataGridQuery.sorting);
25
+ Object.freeze(emptyDataGridQuery.filters);
26
+ Object.freeze(emptyDataGridQuery);
27
+ function columnsById(columns) {
28
+ const byId = new Map();
29
+ for (const column of columns){
30
+ const id = columnIdOf(column);
31
+ if (void 0 !== id && !byId.has(id)) byId.set(id, column);
32
+ }
33
+ return byId;
34
+ }
35
+ function isStringArray(value) {
36
+ return Array.isArray(value) && value.every((item)=>'string' == typeof item);
37
+ }
38
+ function usableFilterValue(column, value) {
39
+ if (!column?.filter) return;
40
+ if ('multiSelect' === column.filter.type) return isStringArray(value) && value.length > 0 ? [
41
+ ...value
42
+ ] : void 0;
43
+ if ('string' != typeof value) return;
44
+ const trimmed = value.trim();
45
+ return '' === trimmed ? void 0 : trimmed;
46
+ }
47
+ function normaliseQuery(query, columns) {
48
+ const byId = columnsById(columns);
49
+ const filters = {};
50
+ for (const [columnId, value] of Object.entries(query?.filters ?? {})){
51
+ const usable = usableFilterValue(byId.get(columnId), value);
52
+ if (void 0 !== usable) filters[columnId] = usable;
53
+ }
54
+ return {
55
+ sorting: query?.sorting ?? [],
56
+ filters,
57
+ matchMode: query?.matchMode ?? 'all',
58
+ search: (query?.search ?? '').trim()
59
+ };
60
+ }
61
+ function countActiveCriteria(query) {
62
+ return Object.keys(query.filters).length + ('' === query.search.trim() ? 0 : 1);
63
+ }
64
+ function isSameFilterValue(first, second) {
65
+ if ('string' == typeof first || 'string' == typeof second) return first === second;
66
+ if (first.length !== second.length) return false;
67
+ const sortedSecond = [
68
+ ...second
69
+ ].sort();
70
+ return [
71
+ ...first
72
+ ].sort().every((item, index)=>item === sortedSecond[index]);
73
+ }
74
+ function isSameQuery(first, second) {
75
+ if (first.matchMode !== second.matchMode || first.search !== second.search) return false;
76
+ const sameSorting = first.sorting.length === second.sorting.length && first.sorting.every((sort, index)=>sort.id === second.sorting[index]?.id && sort.desc === second.sorting[index]?.desc);
77
+ if (!sameSorting) return false;
78
+ const firstIds = Object.keys(first.filters);
79
+ if (firstIds.length !== Object.keys(second.filters).length) return false;
80
+ return firstIds.every((columnId)=>{
81
+ const secondValue = second.filters[columnId];
82
+ return void 0 !== secondValue && isSameFilterValue(first.filters[columnId] ?? '', secondValue);
83
+ });
84
+ }
85
+ function createFilterTest(column, value) {
86
+ const textOf = (row)=>textValueOf(column, row);
87
+ switch(column.filter?.type){
88
+ case 'text':
89
+ {
90
+ if ('string' != typeof value) return null;
91
+ const needle = value.toLowerCase();
92
+ return (row)=>textOf(row)?.toLowerCase().includes(needle) ?? false;
93
+ }
94
+ case 'select':
95
+ if ('string' != typeof value) return null;
96
+ return (row)=>textOf(row) === value;
97
+ case 'multiSelect':
98
+ {
99
+ if ('string' == typeof value) return null;
100
+ const accepted = new Set(value);
101
+ return (row)=>{
102
+ const text = textOf(row);
103
+ return void 0 !== text && accepted.has(text);
104
+ };
105
+ }
106
+ default:
107
+ return null;
108
+ }
109
+ }
110
+ function createQueryMatcher(columns, query) {
111
+ const byId = columnsById(columns);
112
+ const filterTests = [];
113
+ for (const [columnId, value] of Object.entries(query.filters)){
114
+ const column = byId.get(columnId);
115
+ const test = column && createFilterTest(column, value);
116
+ if (test) filterTests.push(test);
117
+ }
118
+ const pattern = dataGridSearchPattern(query.search);
119
+ if (0 === filterTests.length && !pattern) return null;
120
+ const searchColumns = columns.filter((column)=>false !== column.searchable);
121
+ const matchesFilters = (row)=>0 === filterTests.length || ('any' === query.matchMode ? filterTests.some((test)=>test(row)) : filterTests.every((test)=>test(row)));
122
+ const matchesSearch = (row)=>null === pattern || searchColumns.some((column)=>{
123
+ const text = textValueOf(column, row);
124
+ return void 0 !== text && pattern.test(text);
125
+ });
126
+ return (row)=>matchesFilters(row) && matchesSearch(row);
127
+ }
128
+ export { columnIdOf, columnNameOf, countActiveCriteria, createQueryMatcher, dataGridSearchPattern, emptyDataGridQuery, isSameQuery, normaliseQuery };
@@ -15,11 +15,16 @@ export type DataGridRowEvent = MouseEvent<HTMLElement> | KeyboardEvent<HTMLEleme
15
15
  export interface DataGridProps<Row extends RowData> {
16
16
  gridId: string;
17
17
  heading: string;
18
+ /**
19
+ * The card heading's level; 2 by default. The filtered-empty state's heading goes one level
20
+ * below an h2, and is an h4 under any other level: the empty state takes levels 2 to 4 only.
21
+ */
18
22
  headingLevel?: 2 | 3 | 4 | 5 | 6;
19
23
  /**
20
24
  * In server mode, pass a new array only when your data changes: after a query change the grid
21
25
  * waits for a new `rows` array before it asks for more, so a copy made on every render would
22
- * end that wait early.
26
+ * end that wait early. A query that comes back to the one the rows answer, before new rows
27
+ * arrive, ends the wait too, so a cache may answer it with the same array.
23
28
  */
24
29
  rows: Row[];
25
30
  /** Build with `createDataGridColumnHelper<Row>().columns([...])`, not a plain array literal. */
@@ -29,8 +34,9 @@ export interface DataGridProps<Row extends RowData> {
29
34
  getRowLabel?: (row: Row) => string;
30
35
  actions?: ReactNode;
31
36
  /**
32
- * `'client'` (the default) sorts the given rows itself. `'server'` leaves sorting to the app and
33
- * asks for rows page by page; there, headers sort only when `onQueryChange` is given.
37
+ * `'client'` (the default) sorts, filters and searches the given rows itself. `'server'` leaves
38
+ * the query to the app and asks for rows page by page; there, sorting, filters and search are
39
+ * available only when `onQueryChange` is given.
34
40
  */
35
41
  mode?: DataGridMode;
36
42
  totalRowCount?: number;
@@ -39,15 +45,46 @@ export interface DataGridProps<Row extends RowData> {
39
45
  loadError?: string;
40
46
  onLoadMore?: () => void;
41
47
  /**
42
- * Server mode: the user changed the sort, so load the first page of rows for this query. Without
43
- * it, server mode's headers are not sortable and carry no `aria-sort`.
48
+ * The user changed the query: the sort, a filter, the match mode or the search. In client mode it
49
+ * reports the query for the app to keep, for example in the URL; in server mode it is the cue to
50
+ * load the first page of rows for this query. Without it, server mode and a controlled `query`
51
+ * offer no sorting, filters or search; server-mode headers carry no `aria-sort`. A text filter
52
+ * still waiting out its delay when the grid unmounts is committed then, and reported here.
44
53
  */
45
54
  onQueryChange?: (query: DataGridQuery) => void;
46
55
  /**
47
- * The sort the grid starts with. The planned `initialQuery` prop will win over it when both are
48
- * given.
56
+ * The query the grid starts with: filters, sort, match mode and search, as a "view all" link
57
+ * would set them. Its `sorting` wins over `initialSorting`. Read once, on mount; filters the grid
58
+ * cannot apply (an unknown column, one without a filter, a value of the wrong shape) are dropped.
59
+ * In server mode its filters and search apply only with `onQueryChange`. The grid does not call
60
+ * `onQueryChange` on mount, so a server-mode app's first fetch must use this same query.
61
+ */
62
+ initialQuery?: Partial<DataGridQuery>;
63
+ /**
64
+ * Makes the query controlled: the grid shows this query and reports every change through
65
+ * `onQueryChange`, for an app whose own search field or tabs sit outside the grid. Normalised
66
+ * against `columns` on every render. Without it the grid keeps its own query.
67
+ *
68
+ * Adopt a change synchronously, in the handler: once the grid renders again it builds the next
69
+ * change on the query it shows, so a second change made before an asynchronous adoption lands
70
+ * can drop the first. To reject a change, render the grid again with the old query; until it
71
+ * renders, the next change builds on the rejected one. Without `onQueryChange` the query is
72
+ * read-only: its sort, filters and search apply, and the headers report the sort in `aria-sort`,
73
+ * but the headers do not sort, and the grid offers no search, no filters button or strip, and no
74
+ * Clear filters button. In server mode the app sorts, so there the headers claim no sort.
75
+ */
76
+ query?: DataGridQuery;
77
+ /**
78
+ * The sort the grid starts with, unless `initialQuery` gives one or `query` makes the query
79
+ * controlled. Read once, on mount.
49
80
  */
50
81
  initialSorting?: SortingState;
82
+ /**
83
+ * Adds the search button to the toolbar. It opens a search field before the toolbar, which an
84
+ * active search (`initialQuery.search`, say) keeps open. Like the filters, it needs
85
+ * `onQueryChange` in server mode, and it is not offered for a read-only `query`.
86
+ */
87
+ enableSearch?: boolean;
51
88
  enableSorting?: boolean;
52
89
  multiSort?: boolean;
53
90
  loading?: boolean;
@@ -56,6 +93,14 @@ export interface DataGridProps<Row extends RowData> {
56
93
  * this node, so set `labels.empty` to match your message.
57
94
  */
58
95
  emptyState?: ReactNode;
96
+ /**
97
+ * Replaces the message shown when filters or search match nothing (by default an `EmptyState`
98
+ * headed `labels.filteredEmpty`, with a Clear filters button). It receives the grid's "clear
99
+ * filters and search" action. The grid announces `labels.filteredEmpty`. A read-only query (a
100
+ * controlled `query` without `onQueryChange`) cannot be cleared, so the action does nothing
101
+ * there: offer no button for it then, as the default does not.
102
+ */
103
+ filteredEmptyState?: (clearFilters: () => void) => ReactNode;
59
104
  density?: DataGridDensity;
60
105
  /**
61
106
  * The tallest the scrolling body grows before it scrolls, as a CSS length. Defaults to the
@@ -0,0 +1,20 @@
1
+ export interface DebouncedDraft {
2
+ draft: string;
3
+ /** Sets the draft and commits it after the delay. */
4
+ change: (value: string) => void;
5
+ /** Commits a pending change now, cancelling its timer. Does nothing when none is pending. */
6
+ flush: () => void;
7
+ /** Sets the draft and commits it now. */
8
+ commitNow: (value: string) => void;
9
+ }
10
+ /**
11
+ * A typed value that commits after `delayMs` of quiet. When `committed` changes to something this
12
+ * hook did not commit (the query was reset elsewhere), the pending commit is cancelled and the draft
13
+ * takes the new value. A pending commit is flushed on unmount.
14
+ *
15
+ * What this hook committed may come back changed: the grid's query holds text trimmed, so "hex "
16
+ * comes back as "hex". That echo leaves the draft alone, or the space the user just typed would
17
+ * vanish under their cursor. Trimming is all `normaliseQuery` does to text; if it ever does more,
18
+ * the echo rule here must follow.
19
+ */
20
+ export declare function useDebouncedDraft(committed: string, commit: (value: string) => void, delayMs: number): DebouncedDraft;
@@ -0,0 +1,71 @@
1
+ import { useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
2
+ import { useLatest } from "./useLatest.js";
3
+ function useDebouncedDraft(committed, commit, delayMs) {
4
+ const [draft, setDraft] = useState(committed);
5
+ const pendingRef = useRef(null);
6
+ const lastCommittedRef = useRef(committed);
7
+ const commitRef = useLatest(commit);
8
+ const cancelPending = useCallback(()=>{
9
+ if (pendingRef.current) clearTimeout(pendingRef.current.timer);
10
+ pendingRef.current = null;
11
+ }, []);
12
+ const commitValue = useCallback((value)=>{
13
+ lastCommittedRef.current = value;
14
+ commitRef.current(value);
15
+ }, [
16
+ commitRef
17
+ ]);
18
+ useLayoutEffect(()=>{
19
+ const lastCommitted = lastCommittedRef.current;
20
+ if (committed === lastCommitted || committed === lastCommitted.trim()) return;
21
+ cancelPending();
22
+ lastCommittedRef.current = committed;
23
+ setDraft(committed);
24
+ }, [
25
+ committed,
26
+ cancelPending
27
+ ]);
28
+ const change = useCallback((value)=>{
29
+ setDraft(value);
30
+ cancelPending();
31
+ const timer = setTimeout(()=>{
32
+ pendingRef.current = null;
33
+ commitValue(value);
34
+ }, delayMs);
35
+ pendingRef.current = {
36
+ value,
37
+ timer
38
+ };
39
+ }, [
40
+ cancelPending,
41
+ commitValue,
42
+ delayMs
43
+ ]);
44
+ const flush = useCallback(()=>{
45
+ const pending = pendingRef.current;
46
+ if (!pending) return;
47
+ cancelPending();
48
+ commitValue(pending.value);
49
+ }, [
50
+ cancelPending,
51
+ commitValue
52
+ ]);
53
+ useEffect(()=>flush, [
54
+ flush
55
+ ]);
56
+ const commitNow = useCallback((value)=>{
57
+ setDraft(value);
58
+ cancelPending();
59
+ commitValue(value);
60
+ }, [
61
+ cancelPending,
62
+ commitValue
63
+ ]);
64
+ return {
65
+ draft,
66
+ change,
67
+ flush,
68
+ commitNow
69
+ };
70
+ }
71
+ export { useDebouncedDraft };
@@ -9,8 +9,9 @@ export type GridEntry<Row> = {
9
9
  };
10
10
  /**
11
11
  * Flattens rows and the detail panels of expanded rows into the one list the virtualiser walks.
12
- * `aria-rowindex` of an entry is 2 plus its position here (row 1 is the header). A row gets a panel
13
- * when its id is in `expandedIds` and `canExpand` allows it.
12
+ * `aria-rowindex` of an entry is its position here plus one more than the head rows (the header,
13
+ * and the filter strip while it shows). A row gets a panel when its id is in `expandedIds` and
14
+ * `canExpand` allows it.
14
15
  */
15
16
  export declare function useGridEntries<Row extends {
16
17
  id: string;