@macrostrat/data-sheet 4.0.0-dev3 → 4.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (212) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/README.md +44 -0
  3. package/dist/actions/builtin.cjs +36 -5
  4. package/dist/actions/builtin.cjs.map +1 -1
  5. package/dist/actions/builtin.d.ts +3 -2
  6. package/dist/actions/builtin.js +36 -5
  7. package/dist/actions/builtin.js.map +1 -1
  8. package/dist/actions/column-controls.cjs +149 -0
  9. package/dist/actions/column-controls.cjs.map +1 -0
  10. package/dist/actions/column-controls.d.ts +11 -0
  11. package/dist/actions/column-controls.js +147 -0
  12. package/dist/actions/column-controls.js.map +1 -0
  13. package/dist/actions/column-filter.cjs +68 -0
  14. package/dist/actions/column-filter.cjs.map +1 -0
  15. package/dist/actions/column-filter.d.ts +11 -0
  16. package/dist/actions/column-filter.js +66 -0
  17. package/dist/actions/column-filter.js.map +1 -0
  18. package/dist/actions/edit-actions.cjs +42 -0
  19. package/dist/actions/edit-actions.cjs.map +1 -0
  20. package/dist/actions/edit-actions.d.ts +14 -0
  21. package/dist/actions/edit-actions.js +42 -0
  22. package/dist/actions/edit-actions.js.map +1 -0
  23. package/dist/actions/filters.cjs +39 -23
  24. package/dist/actions/filters.cjs.map +1 -1
  25. package/dist/actions/filters.d.ts +6 -3
  26. package/dist/actions/filters.js +41 -25
  27. package/dist/actions/filters.js.map +1 -1
  28. package/dist/actions/index.d.ts +4 -0
  29. package/dist/actions/selection.cjs +51 -32
  30. package/dist/actions/selection.cjs.map +1 -1
  31. package/dist/actions/selection.d.ts +3 -7
  32. package/dist/actions/selection.js +51 -32
  33. package/dist/actions/selection.js.map +1 -1
  34. package/dist/actions/table-controls.cjs +41 -0
  35. package/dist/actions/table-controls.cjs.map +1 -0
  36. package/dist/actions/table-controls.d.ts +4 -0
  37. package/dist/actions/table-controls.js +39 -0
  38. package/dist/actions/table-controls.js.map +1 -0
  39. package/dist/actions/toolbar.cjs +69 -10
  40. package/dist/actions/toolbar.cjs.map +1 -1
  41. package/dist/actions/toolbar.d.ts +9 -6
  42. package/dist/actions/toolbar.js +69 -10
  43. package/dist/actions/toolbar.js.map +1 -1
  44. package/dist/actions/toolbar.module.sass.cjs +12 -7
  45. package/dist/actions/toolbar.module.sass.cjs.map +1 -1
  46. package/dist/actions/toolbar.module.sass.js +12 -7
  47. package/dist/actions/toolbar.module.sass.js.map +1 -1
  48. package/dist/actions/types.d.ts +49 -4
  49. package/dist/cell-renderer.cjs +150 -14
  50. package/dist/cell-renderer.cjs.map +1 -1
  51. package/dist/cell-renderer.d.ts +1 -1
  52. package/dist/cell-renderer.js +151 -15
  53. package/dist/cell-renderer.js.map +1 -1
  54. package/dist/components/cell-detail.cjs +24 -0
  55. package/dist/components/cell-detail.cjs.map +1 -0
  56. package/dist/components/cell-detail.d.ts +12 -0
  57. package/dist/components/cell-detail.js +24 -0
  58. package/dist/components/cell-detail.js.map +1 -0
  59. package/dist/components/editor-popup.cjs +28 -24
  60. package/dist/components/editor-popup.cjs.map +1 -1
  61. package/dist/components/editor-popup.js +29 -25
  62. package/dist/components/editor-popup.js.map +1 -1
  63. package/dist/components/index.d.ts +2 -2
  64. package/dist/components/text-areas.cjs +51 -7
  65. package/dist/components/text-areas.cjs.map +1 -1
  66. package/dist/components/text-areas.d.ts +4 -1
  67. package/dist/components/text-areas.js +51 -7
  68. package/dist/components/text-areas.js.map +1 -1
  69. package/dist/components/view-info.cjs +46 -9
  70. package/dist/components/view-info.cjs.map +1 -1
  71. package/dist/components/view-info.d.ts +5 -1
  72. package/dist/components/view-info.js +47 -10
  73. package/dist/components/view-info.js.map +1 -1
  74. package/dist/core.cjs +167 -73
  75. package/dist/core.cjs.map +1 -1
  76. package/dist/core.d.ts +53 -6
  77. package/dist/core.js +169 -75
  78. package/dist/core.js.map +1 -1
  79. package/dist/data-sheet.css +72 -123
  80. package/dist/filters/operators.cjs +91 -0
  81. package/dist/filters/operators.cjs.map +1 -0
  82. package/dist/filters/operators.d.ts +17 -0
  83. package/dist/filters/operators.js +91 -0
  84. package/dist/filters/operators.js.map +1 -0
  85. package/dist/index.cjs +38 -10
  86. package/dist/index.cjs.map +1 -1
  87. package/dist/index.d.ts +2 -0
  88. package/dist/index.js +44 -16
  89. package/dist/index.js.map +1 -1
  90. package/dist/main.module.sass.cjs +13 -12
  91. package/dist/main.module.sass.cjs.map +1 -1
  92. package/dist/main.module.sass.js +13 -12
  93. package/dist/main.module.sass.js.map +1 -1
  94. package/dist/postgrest-table/data-loaders.cjs +255 -146
  95. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  96. package/dist/postgrest-table/data-loaders.d.ts +144 -46
  97. package/dist/postgrest-table/data-loaders.js +259 -150
  98. package/dist/postgrest-table/data-loaders.js.map +1 -1
  99. package/dist/postgrest-table/index.cjs +58 -169
  100. package/dist/postgrest-table/index.cjs.map +1 -1
  101. package/dist/postgrest-table/index.d.ts +5 -2
  102. package/dist/postgrest-table/index.js +63 -174
  103. package/dist/postgrest-table/index.js.map +1 -1
  104. package/dist/postgrest-table/loading-utils.cjs +0 -4
  105. package/dist/postgrest-table/loading-utils.cjs.map +1 -1
  106. package/dist/postgrest-table/loading-utils.js +1 -5
  107. package/dist/postgrest-table/loading-utils.js.map +1 -1
  108. package/dist/postgrest-table/main.module.sass.cjs +14 -13
  109. package/dist/postgrest-table/main.module.sass.cjs.map +1 -1
  110. package/dist/postgrest-table/main.module.sass.js +14 -13
  111. package/dist/postgrest-table/main.module.sass.js.map +1 -1
  112. package/dist/provider.cjs +68 -11
  113. package/dist/provider.cjs.map +1 -1
  114. package/dist/provider.d.ts +25 -0
  115. package/dist/provider.js +68 -11
  116. package/dist/provider.js.map +1 -1
  117. package/dist/renderers/column-header-cell.cjs +95 -75
  118. package/dist/renderers/column-header-cell.cjs.map +1 -1
  119. package/dist/renderers/column-header-cell.d.ts +3 -18
  120. package/dist/renderers/column-header-cell.js +98 -78
  121. package/dist/renderers/column-header-cell.js.map +1 -1
  122. package/dist/renderers/index.d.ts +0 -1
  123. package/dist/types.cjs +2 -0
  124. package/dist/types.cjs.map +1 -1
  125. package/dist/types.d.ts +84 -1
  126. package/dist/types.js +2 -0
  127. package/dist/types.js.map +1 -1
  128. package/dist/utils/column-spec.cjs.map +1 -1
  129. package/dist/utils/column-spec.d.ts +101 -1
  130. package/dist/utils/column-spec.js.map +1 -1
  131. package/dist/utils/debug-overlay.cjs +24 -0
  132. package/dist/utils/debug-overlay.cjs.map +1 -0
  133. package/dist/utils/debug-overlay.d.ts +4 -0
  134. package/dist/utils/debug-overlay.js +24 -0
  135. package/dist/utils/debug-overlay.js.map +1 -0
  136. package/dist/utils/index.cjs.map +1 -1
  137. package/dist/utils/index.d.ts +2 -0
  138. package/dist/utils/index.js.map +1 -1
  139. package/dist/utils/key-handling.cjs +52 -6
  140. package/dist/utils/key-handling.cjs.map +1 -1
  141. package/dist/utils/key-handling.js +52 -6
  142. package/dist/utils/key-handling.js.map +1 -1
  143. package/dist/utils/validation.cjs +41 -0
  144. package/dist/utils/validation.cjs.map +1 -0
  145. package/dist/utils/validation.d.ts +26 -0
  146. package/dist/utils/validation.js +41 -0
  147. package/dist/utils/validation.js.map +1 -0
  148. package/dist/zustand-store.cjs +119 -61
  149. package/dist/zustand-store.cjs.map +1 -1
  150. package/dist/zustand-store.js +121 -63
  151. package/dist/zustand-store.js.map +1 -1
  152. package/package.json +3 -3
  153. package/src/actions/builtin.ts +62 -7
  154. package/src/actions/column-controls.ts +185 -0
  155. package/src/actions/column-filter.ts +104 -0
  156. package/src/actions/edit-actions.ts +67 -0
  157. package/src/actions/filters.ts +54 -28
  158. package/src/actions/index.ts +4 -0
  159. package/src/actions/selection.ts +73 -54
  160. package/src/actions/table-controls.ts +46 -0
  161. package/src/actions/toolbar.module.sass +22 -2
  162. package/src/actions/toolbar.ts +113 -16
  163. package/src/actions/types.ts +49 -4
  164. package/src/cell-renderer.ts +211 -16
  165. package/src/components/cell-detail.ts +30 -0
  166. package/src/components/editor-popup.ts +39 -25
  167. package/src/components/index.ts +2 -2
  168. package/src/components/text-areas.ts +80 -16
  169. package/src/components/view-info.ts +63 -4
  170. package/src/core.ts +321 -103
  171. package/src/filters/operators.ts +127 -0
  172. package/src/index.ts +2 -0
  173. package/src/main.module.sass +6 -0
  174. package/src/postgrest-table/data-loaders.ts +459 -209
  175. package/src/postgrest-table/index.ts +81 -254
  176. package/src/postgrest-table/main.module.sass +11 -0
  177. package/src/provider.ts +109 -12
  178. package/src/renderers/column-header-cell.ts +60 -272
  179. package/src/renderers/index.ts +0 -1
  180. package/src/types.ts +76 -2
  181. package/src/utils/column-spec.ts +112 -1
  182. package/src/utils/debug-overlay.ts +22 -0
  183. package/src/utils/index.ts +2 -0
  184. package/src/utils/key-handling.ts +70 -6
  185. package/src/utils/validation.ts +72 -0
  186. package/src/zustand-store.ts +167 -60
  187. package/dist/components/actions.cjs +0 -12
  188. package/dist/components/actions.cjs.map +0 -1
  189. package/dist/components/actions.d.ts +0 -2
  190. package/dist/components/actions.js +0 -12
  191. package/dist/components/actions.js.map +0 -1
  192. package/dist/components/actions.module.sass.cjs +0 -12
  193. package/dist/components/actions.module.sass.cjs.map +0 -1
  194. package/dist/components/actions.module.sass.js +0 -11
  195. package/dist/components/actions.module.sass.js.map +0 -1
  196. package/dist/postgrest-table/lazy-loader-table.cjs +0 -27
  197. package/dist/postgrest-table/lazy-loader-table.cjs.map +0 -1
  198. package/dist/postgrest-table/lazy-loader-table.d.ts +0 -3
  199. package/dist/postgrest-table/lazy-loader-table.js +0 -27
  200. package/dist/postgrest-table/lazy-loader-table.js.map +0 -1
  201. package/dist/renderers/column-header-cell-postgrest.cjs +0 -216
  202. package/dist/renderers/column-header-cell-postgrest.cjs.map +0 -1
  203. package/dist/renderers/column-header-cell-postgrest.d.ts +0 -13
  204. package/dist/renderers/column-header-cell-postgrest.js +0 -216
  205. package/dist/renderers/column-header-cell-postgrest.js.map +0 -1
  206. package/dist/renderers/column-header-cell-postgrest.module.sass.cjs +0 -23
  207. package/dist/renderers/column-header-cell-postgrest.module.sass.cjs.map +0 -1
  208. package/dist/renderers/column-header-cell-postgrest.module.sass.js +0 -22
  209. package/dist/renderers/column-header-cell-postgrest.module.sass.js.map +0 -1
  210. package/src/components/actions.ts +0 -9
  211. package/src/postgrest-table/lazy-loader-table.ts +0 -25
  212. package/src/renderers/column-header-cell-postgrest.ts +0 -282
package/src/core.ts CHANGED
@@ -1,10 +1,4 @@
1
- import {
2
- Button,
3
- HotkeysProvider,
4
- InputGroup,
5
- OverlaysProvider,
6
- useHotkeys,
7
- } from "@blueprintjs/core";
1
+ import { useHotkeys } from "@blueprintjs/core";
8
2
  import {
9
3
  Column,
10
4
  Region,
@@ -14,41 +8,49 @@ import {
14
8
  TableProps,
15
9
  } from "@blueprintjs/table";
16
10
  import "@blueprintjs/table/lib/css/table.css";
17
- import {
18
- ReactNode,
19
- useCallback,
20
- useEffect,
21
- useMemo,
22
- useRef,
23
- useState,
24
- } from "react";
25
- import { DataSheetAction, InfoBar } from "./components";
26
- import {
27
- autoFilterId,
28
- renderColumnHeaderCell,
29
- SortFilterBar,
30
- } from "./renderers";
11
+ import { ReactNode, useCallback, useEffect, useMemo, useRef } from "react";
12
+ import { LoadProgressIndicator } from "./components";
13
+ import { renderColumnHeaderCell } from "./renderers";
31
14
  import h from "./main.module.sass";
32
15
  import {
33
16
  columnSpecAtom,
17
+ ctx,
34
18
  DataSheetProvider,
35
19
  storeAtom,
20
+ tableActionsAtom,
36
21
  useSelector,
37
22
  useStoreAPI,
38
- ctx,
39
- tableActionsAtom,
40
23
  } from "./provider";
41
24
  import { atom } from "jotai";
42
25
  import {
43
26
  DataSheetProviderProps,
27
+ EditEvent,
44
28
  TableElementStatus,
45
29
  VisibleCells,
46
30
  } from "./types.ts";
47
31
  import { basicCellRenderer } from "./cell-renderer.ts";
48
- import { tableHotkeysAtom } from "./utils";
49
- import { clipboardActions, TableAction, TableFilter } from "./actions";
50
- import { ActionsToolbar, FilterBar } from "./actions";
51
- import { useScrollHandler } from "./postgrest-table";
32
+ import { CellRendererDebugOverlay, tableHotkeysAtom } from "./utils";
33
+ import {
34
+ ActionsToolbar,
35
+ clipboardActions,
36
+ columnControlActions,
37
+ createSaveAction,
38
+ FilterBar,
39
+ resetChangesAction,
40
+ TableAction,
41
+ TableActionContext,
42
+ TableFilter,
43
+ } from "./actions";
44
+ import {
45
+ createLocalProvider,
46
+ dataRefreshTokenAtom,
47
+ FetchData,
48
+ FetchDataOptions,
49
+ tableFooterAtom,
50
+ TableDataProvider,
51
+ useScrollHandler,
52
+ useDataLoader,
53
+ } from "./postgrest-table";
52
54
 
53
55
  // More on component templates: https://storybook.js.org/docs/react/writing-stories/introduction#using-args
54
56
 
@@ -61,18 +63,72 @@ export enum DataSheetDensity {
61
63
  LOW = "low",
62
64
  }
63
65
 
64
- interface DataSheetInternalProps<T> extends TableProps {
66
+ /** Approximate column-header + scrollbar allowance, used to size the table to
67
+ * its content in paged mode. */
68
+ const COLUMN_HEADER_HEIGHT = 34;
69
+
70
+ /**
71
+ * How selecting a cell activates its surface (an editor, or a read-only detail
72
+ * panel):
73
+ * - `"auto"` (default when `autoFocusEditor` is `true`): open the surface on
74
+ * selection and, for editors, focus it. Editors relinquish focus at their
75
+ * edges — arrow past the start/end of a text cell, or press Escape, and focus
76
+ * returns to the table — so the keyboard stays operable without the mouse.
77
+ * Pressing Escape drops into navigation mode (surfaces stop auto-opening)
78
+ * until the next click.
79
+ * - `"manual"` (default when `autoFocusEditor` is `false`): the surface stays
80
+ * closed until the cell is clicked; arrow keys always navigate the table.
81
+ */
82
+ export type CellInteraction = "auto" | "manual";
83
+
84
+ interface DataSheetInternalProps<T> extends TableProps, FetchDataOptions {
85
+ /** In-memory rows. Internally wrapped in a local `TableDataProvider` and
86
+ * driven through the same loader as any other source. */
87
+ data?: T[];
88
+ // function to fetch a chunk of data (the read side of a data provider)
89
+ fetchData?: FetchData<T>;
90
+ /** A data provider instantiated separately and passed in — bundles the read
91
+ * side (`fetchData` + `identity`) and, optionally, the persistence side
92
+ * (`saveRows` / `deleteRows` / `insertRow`) that drives the Save action. An
93
+ * explicit alternative to the loose `data` / `fetchData` / `identity` props;
94
+ * takes precedence when given. */
95
+ provider?: TableDataProvider<T>;
96
+ // An optional table name that will be used in toolbars if given
97
+ name?: string;
65
98
  onVisibleCellsChange?: (visibleCells: VisibleCells) => void;
66
- onSaveData?: (updatedData: any[], data: T[]) => void;
67
99
  onUpdateData?: (updatedData: any[], data: T[]) => void;
100
+ /** Observer called for every user edit as a structured `EditEvent`
101
+ * (Workstream A). Additive: the built-in `updatedData` overlay still
102
+ * applies. */
103
+ onEdit?: (event: EditEvent<T>) => void;
104
+ /** Controlled edited-cell overlay (Workstream A). When provided, it is
105
+ * synced into the store as the source of truth for edited values — pair with
106
+ * `onEdit` to own edit state externally (e.g. an ops model). Optimistic
107
+ * in-table edits are superseded by the next value you pass back. */
108
+ updatedData?: T[];
109
+ /** Controlled row-status overlay (edited / added / deleted), the companion
110
+ * to `updatedData`. */
111
+ rowStatus?: TableElementStatus[];
112
+ /** Row identity for the edit overlay — stable across a provider re-sort (a
113
+ * data provider supplies its own; defaults to `(row) => row?.id`). Lets edits
114
+ * survive a re-ordered re-fetch. */
115
+ identity?: (row: T) => string | number | null | undefined;
116
+ /** Persistence handler for the built-in Save action. When provided, a Save
117
+ * control is added to the toolbar (always visible, disabled when there are
118
+ * no pending changes). */
119
+ onSave?: (ctx: TableActionContext<T>) => void | Promise<void>;
68
120
  onDeleteRows?: (selection: Region[]) => void;
69
121
  verbose?: boolean;
70
122
  enableColumnReordering?: boolean;
71
123
  enableClipboard?: boolean;
72
124
  enableFocusedCell?: boolean;
73
- dataSheetActions?: ReactNode | null;
74
125
  editable?: boolean;
126
+ /** @deprecated Prefer `cellInteraction`. `true` maps to `"auto"`,
127
+ * `false` to `"manual"`. */
75
128
  autoFocusEditor?: boolean;
129
+ /** How selecting a cell activates its surface (editor or detail panel).
130
+ * Defaults from `autoFocusEditor` for backward compatibility. */
131
+ cellInteraction?: CellInteraction;
76
132
  density?: DataSheetDensity;
77
133
  /** Configurable table actions shown in a selection-aware toolbar.
78
134
  * When provided, the actions toolbar renders alongside the existing
@@ -117,6 +173,7 @@ export function DataSheet<T>(props: DataSheetProps<T>) {
117
173
  },
118
174
  h(_DataSheet<any>, {
119
175
  ...rest,
176
+ data: data ?? emptyData,
120
177
  children,
121
178
  editable,
122
179
  enableColumnReordering,
@@ -130,17 +187,67 @@ const deletedRowHeaderStyle = {
130
187
  textDecoration: "line-through",
131
188
  };
132
189
 
190
+ /** Persist all pending changes through a data provider: added rows via
191
+ * `insertRow`, edited rows via `saveRows`, deleted rows via `deleteRows`
192
+ * (addressed by `provider.identity`). Used by the built-in Save action when an
193
+ * explicit provider owns persistence. */
194
+ async function persistViaProvider<T>(
195
+ provider: TableDataProvider<T>,
196
+ ctx: TableActionContext<T>,
197
+ ): Promise<void> {
198
+ const base = (ctx.data ?? []) as any[];
199
+ const updates = (ctx.updatedData ?? []) as any[];
200
+ const status = (ctx.rowStatus ?? []) as any[];
201
+ const n = Math.max(base.length, updates.length, status.length);
202
+ const toSave: T[] = [];
203
+ const toInsert: T[] = [];
204
+ const toDelete: Array<string | number> = [];
205
+ for (let i = 0; i < n; i++) {
206
+ if (status[i] === TableElementStatus.DELETED) {
207
+ const id = provider.identity(base[i]);
208
+ if (id != null) toDelete.push(id);
209
+ continue;
210
+ }
211
+ const upd = updates[i];
212
+ const hasEdit =
213
+ upd != null && typeof upd === "object" && Object.keys(upd).length > 0;
214
+ if (status[i] === TableElementStatus.ADDED) {
215
+ toInsert.push({ ...base[i], ...upd } as T);
216
+ } else if (hasEdit) {
217
+ toSave.push({ ...base[i], ...upd } as T);
218
+ }
219
+ }
220
+ if (toDelete.length > 0 && provider.deleteRows != null) {
221
+ await provider.deleteRows(toDelete);
222
+ }
223
+ for (const row of toInsert) {
224
+ if (provider.insertRow != null) await provider.insertRow(row);
225
+ }
226
+ if (toSave.length > 0 && provider.saveRows != null) {
227
+ await provider.saveRows(toSave);
228
+ }
229
+ }
230
+
133
231
  function _DataSheet<T>({
232
+ data: sourceData,
233
+ fetchData,
234
+ provider,
235
+ pageSize,
236
+ fetchMode,
134
237
  onVisibleCellsChange,
135
- onSaveData,
136
238
  onUpdateData,
239
+ onEdit,
240
+ onSave,
241
+ updatedData: updatedDataProp,
242
+ rowStatus: rowStatusProp,
243
+ identity,
137
244
  onDeleteRows,
245
+ name,
138
246
  verbose = false,
139
- dataSheetActions = null,
140
247
  enableFocusedCell,
141
248
  autoFocusEditor = true,
249
+ cellInteraction,
142
250
  enableClipboard = true,
143
- showInfoBar = false,
144
251
  density = DataSheetDensity.HIGH,
145
252
  selectionModes,
146
253
  actions,
@@ -158,17 +265,70 @@ function _DataSheet<T>({
158
265
  // Turn on debug features
159
266
  const debugMode = false;
160
267
 
161
- // Sync table actions to atom
162
- const _actions: TableAction[] = useMemo(() => {
163
- const _actions = [];
164
- if (actions != null) {
165
- _actions.push(...actions);
268
+ const editable = useSelector((state) => state.editable);
269
+
270
+ // Resolve the active data provider: an explicit `provider` prop wins; else a
271
+ // loose `fetchData` (+ identity) is wrapped as one; else in-memory `data`
272
+ // becomes a local provider. Local and remote thus share one path, and the
273
+ // provider is an explicit contract rather than a set of scattered props.
274
+ const isLocalProvider = provider == null && fetchData == null;
275
+ const activeProvider = useMemo<TableDataProvider<any> | null>(() => {
276
+ if (provider != null) return provider;
277
+ if (fetchData != null) {
278
+ return { fetchData, identity: identity ?? ((r: any) => r?.id) };
166
279
  }
167
- if (enableClipboard) {
168
- _actions.push(...clipboardActions);
280
+ if (sourceData != null && sourceData.length > 0) {
281
+ return createLocalProvider(
282
+ sourceData,
283
+ identity != null ? { identity } : undefined,
284
+ );
285
+ }
286
+ return null;
287
+ // eslint-disable-next-line react-hooks/exhaustive-deps
288
+ }, [provider, fetchData, sourceData, identity]);
289
+
290
+ // When an explicit provider owns persistence, its methods drive the built-in
291
+ // Save (batch: edits→saveRows, added→insertRow, deleted→deleteRows), then a
292
+ // refresh. Otherwise the loose `onSave` handler is used.
293
+ const bumpRefresh = ctx.useSet(dataRefreshTokenAtom);
294
+ const providerSave = useMemo(() => {
295
+ const p = provider;
296
+ if (
297
+ p == null ||
298
+ (p.saveRows == null && p.deleteRows == null && p.insertRow == null)
299
+ ) {
300
+ return null;
301
+ }
302
+ return async (actionCtx: TableActionContext<T>) => {
303
+ await persistViaProvider(p, actionCtx);
304
+ bumpRefresh((v) => v + 1);
305
+ };
306
+ }, [provider, bumpRefresh]);
307
+ const saveHandler = onSave ?? providerSave;
308
+
309
+ // Sync table actions to atom. Consumer actions come first (they override a
310
+ // built-in by reusing its id); the built-in column controls (sort/filter)
311
+ // fill in the rest — so both the toolbar and the header dropdown source from
312
+ // one registry. Built-ins self-gate (single sortable/filterable column).
313
+ const _actions: TableAction[] = useMemo(() => {
314
+ const _actions: TableAction[] = [];
315
+ const add = (list: TableAction[]) => {
316
+ for (const a of list) {
317
+ if (!_actions.some((x) => x.id === a.id)) _actions.push(a);
318
+ }
319
+ };
320
+ if (actions != null) add(actions);
321
+ add(columnControlActions);
322
+ if (enableClipboard) add(clipboardActions);
323
+ // Save/reset last — they're the most significant actions — and present for
324
+ // every cardinality (editable), so the toolbar stays mounted regardless of
325
+ // selection.
326
+ if (editable) {
327
+ if (saveHandler != null) add([createSaveAction(saveHandler)]);
328
+ add([resetChangesAction]);
169
329
  }
170
330
  return _actions;
171
- }, [actions, enableClipboard]);
331
+ }, [actions, enableClipboard, editable, saveHandler]);
172
332
 
173
333
  ctx.useSync(tableActionsAtom, _actions);
174
334
 
@@ -180,7 +340,6 @@ function _DataSheet<T>({
180
340
  const selectedRegions = useSelector<T>((state) => state.selection ?? []);
181
341
 
182
342
  const data = useSelector((state) => state.data);
183
- const editable = useSelector((state) => state.editable);
184
343
 
185
344
  const rowStatus = useSelector((state) => state.rowStatus);
186
345
 
@@ -239,19 +398,84 @@ function _DataSheet<T>({
239
398
 
240
399
  const { rowHeight, style } = styleParamsForDensity(density);
241
400
 
401
+ // In paged mode the row count is small and fixed, so let the table size to
402
+ // its content (header + rows) instead of filling the viewport.
403
+ const footerInfo = ctx.useValue(tableFooterAtom);
404
+ const holderStyle =
405
+ footerInfo.mode === "paged"
406
+ ? {
407
+ flex: "0 0 auto" as const,
408
+ height: numRows * rowHeight + COLUMN_HEADER_HEIGHT,
409
+ }
410
+ : undefined;
411
+
242
412
  const onColumnsReordered = useSelector((state) => state.onColumnsReordered);
243
413
 
244
414
  // Auto-detect if any columns have sortable/filterable set.
245
415
  // If so and no explicit columnHeaderCellRenderer was provided,
246
416
  // use the built-in client-side sort/filter header.
247
417
  const hasSortableOrFilterable = useMemo(
248
- () => columnSpec.some((col) => col.sortable || col.filterable),
418
+ () =>
419
+ columnSpec.some(
420
+ (col) =>
421
+ col.sortable ||
422
+ col.filterable ||
423
+ (Array.isArray(col.filters) && col.filters.length > 0),
424
+ ),
249
425
  [columnSpec],
250
426
  );
251
427
 
252
428
  const columnSorts = useSelector((state) => state.columnSorts);
253
429
  const activeFilters = useSelector((state) => state.activeFilters);
254
430
 
431
+ // Cell activation mode, defaulting from the legacy `autoFocusEditor` boolean
432
+ // so existing consumers are unaffected. Synced into the store so the cell
433
+ // renderer, editors, and key handlers all read it consistently.
434
+ const cellInteractionMode: CellInteraction =
435
+ cellInteraction ?? (autoFocusEditor ? "auto" : "manual");
436
+
437
+ const storeState = storeAPI;
438
+ useEffect(() => {
439
+ storeState.setState({ cellInteraction: cellInteractionMode });
440
+ }, [storeState, cellInteractionMode]);
441
+
442
+ useEffect(() => {
443
+ // Give the store a handle to the focusable holder so editors can return
444
+ // keyboard focus to the table when the cursor leaves them.
445
+ storeState.setState({ tableElement: tableElementRef.current });
446
+ }, [storeState]);
447
+
448
+ useEffect(() => {
449
+ storeState.setState({ onEdit });
450
+ }, [storeState, onEdit]);
451
+
452
+ useEffect(() => {
453
+ // Controlled overlay: mirror the caller's edited state into the store as
454
+ // the source of truth. Optimistic in-table edits are superseded on the
455
+ // next render when the caller passes an updated value back. When the caller
456
+ // controls it, the loader-boundary identity remap steps aside.
457
+ const controlled =
458
+ updatedDataProp !== undefined || rowStatusProp !== undefined;
459
+ const patch: Record<string, unknown> = { controlledOverlay: controlled };
460
+ if (updatedDataProp !== undefined) patch.updatedData = updatedDataProp;
461
+ if (rowStatusProp !== undefined) patch.rowStatus = rowStatusProp;
462
+ storeState.setState(patch);
463
+ }, [storeState, updatedDataProp, rowStatusProp]);
464
+
465
+ // The active provider supplies the row identity for the edit overlay.
466
+ useEffect(() => {
467
+ const id = activeProvider?.identity ?? identity;
468
+ if (id != null) storeState.setState({ identity: id });
469
+ }, [storeState, activeProvider, identity]);
470
+
471
+ // Row deletion is a provider capability: an explicit `provider` without
472
+ // `deleteRows` disables deletion entirely. (Local / loose sources keep the
473
+ // local delete overlay.)
474
+ useEffect(() => {
475
+ const canDeleteRows = provider == null || provider.deleteRows != null;
476
+ storeState.setState({ canDeleteRows });
477
+ }, [storeState, provider]);
478
+
255
479
  const realizedColumns = useMemo(() => {
256
480
  return columnSpec.map((col, colIndex) => {
257
481
  let fn =
@@ -263,11 +487,14 @@ function _DataSheet<T>({
263
487
  if (col.sortable) {
264
488
  activeSort = columnSorts?.find((s) => s.key === col.key);
265
489
  }
266
- if (col.filterable) {
267
- // The autoFilterID implementation is too complicated
268
- activeFilter =
269
- activeFilters?.get(col.key) ??
270
- activeFilters?.get(autoFilterId(col.key));
490
+ // The active filter for this column is whichever active filter targets
491
+ // it (a rich `col.filters` filter or the generic operator filter) — match
492
+ // by columnKey rather than a fixed id.
493
+ for (const entry of activeFilters?.values() ?? []) {
494
+ if ((entry as any)?.filter?.columnKey === col.key) {
495
+ activeFilter = entry;
496
+ break;
497
+ }
271
498
  }
272
499
 
273
500
  const _columnHeaderCellRenderer = (colIndex) => {
@@ -290,7 +517,6 @@ function _DataSheet<T>({
290
517
  colIndex,
291
518
  col,
292
519
  state,
293
- autoFocusEditor,
294
520
  filteredRowIndices,
295
521
  );
296
522
  },
@@ -301,7 +527,6 @@ function _DataSheet<T>({
301
527
  columnSorts,
302
528
  activeFilters,
303
529
  storeAPI,
304
- autoFocusEditor,
305
530
  filteredRowIndices,
306
531
  columnHeaderCellRenderer,
307
532
  ]);
@@ -349,11 +574,35 @@ function _DataSheet<T>({
349
574
  filteredRowIndices,
350
575
  ];
351
576
 
577
+ // Drive the table from the active provider's `fetchData`. A local (in-memory)
578
+ // provider loads the whole array at once; a remote one uses the `pageSize` /
579
+ // `fetchMode` props and shows load progress.
580
+ let _showLoadProgress: boolean = false;
581
+ let dataLoader: ReactNode = null;
582
+ if (activeProvider != null) {
583
+ _showLoadProgress = !isLocalProvider;
584
+ dataLoader = h(_DataLoaderManager, {
585
+ key: "__data_loader",
586
+ fetchData: activeProvider.fetchData,
587
+ pageSize: isLocalProvider
588
+ ? Math.max(sourceData?.length ?? 1, 1)
589
+ : pageSize,
590
+ fetchMode: isLocalProvider ? undefined : fetchMode,
591
+ });
592
+ }
593
+ const showFilterBar =
594
+ (filters != null && filters.length > 0) || hasSortableOrFilterable;
595
+
596
+ let filterStatus: ReactNode = null;
597
+ if (showFilterBar) {
598
+ filterStatus = h(FilterBar, { filters: filters ?? [] });
599
+ }
600
+
352
601
  return h("div.data-sheet-container", { className, style }, [
353
- h.if(actions != null)(ActionsToolbar, { actions }),
354
- h.if(filters != null && filters.length > 0)(FilterBar, { filters }),
355
- h.if(hasSortableOrFilterable)(SortFilterBar),
356
- dataSheetActions,
602
+ // The actions/tools toolbar (selection-modal). Table-scoped controls like
603
+ // scroll-to-row / full-text search live here as ordinary actions.
604
+ h(ActionsToolbar, { actions: _actions, tableName: name }),
605
+ dataLoader,
357
606
  children,
358
607
  h(
359
608
  "div.data-sheet-holder",
@@ -362,6 +611,7 @@ function _DataSheet<T>({
362
611
  onKeyDown: handleKeyDown,
363
612
  onKeyUp: handleKeyUp,
364
613
  ref: tableElementRef,
614
+ style: holderStyle,
365
615
  },
366
616
  h(
367
617
  Table,
@@ -392,7 +642,11 @@ function _DataSheet<T>({
392
642
  realizedColumns,
393
643
  ),
394
644
  ),
395
- h.if(showInfoBar)(InfoBar),
645
+ h("div.status-bar", [
646
+ filterStatus,
647
+ h("div.spacer"),
648
+ h.if(_showLoadProgress)(LoadProgressIndicator),
649
+ ]),
396
650
  h.if(debugMode)(CellRendererDebugOverlay, {
397
651
  cellRendererDependencies,
398
652
  names: [
@@ -416,54 +670,6 @@ const columnWidthsAtom = atom((get) => {
416
670
  );
417
671
  });
418
672
 
419
- function CellRendererDebugOverlay({ cellRendererDependencies, names }) {
420
- /** Debug overlay for cell renderer dependencies */
421
- const lastRenderDependencies = useRef<any[]>(cellRendererDependencies);
422
- useEffect(() => {
423
- let changeDepNames = [];
424
- for (const [i, dep] of cellRendererDependencies.entries()) {
425
- if (dep !== lastRenderDependencies.current[i]) {
426
- changeDepNames.push(names[i]);
427
- }
428
- }
429
- if (changeDepNames.length > 0) {
430
- console.log(
431
- "Cell renderer dependencies changed:",
432
- changeDepNames.join(", "),
433
- );
434
- }
435
- lastRenderDependencies.current = cellRendererDependencies;
436
- }, cellRendererDependencies);
437
- return null;
438
- }
439
-
440
- export function ScrollToRowControl() {
441
- const [value, setValue] = useState("");
442
- const scrollToRow = useSelector((state) => state.scrollToRow);
443
-
444
- return h(DataSheetAction, [
445
- h(InputGroup, {
446
- type: "number",
447
- placeholder: "Row number",
448
- value,
449
- onValueChange(value) {
450
- setValue(value);
451
- },
452
- }),
453
- h(
454
- Button,
455
- {
456
- icon: "arrow-right",
457
- onClick() {
458
- const row = parseInt(value);
459
- scrollToRow(row - 1);
460
- },
461
- },
462
- "Scroll to row",
463
- ),
464
- ]);
465
- }
466
-
467
673
  function styleParamsForDensity(density: DataSheetDensity) {
468
674
  switch (density) {
469
675
  case DataSheetDensity.MEDIUM:
@@ -494,6 +700,18 @@ function styleParamsForDensity(density: DataSheetDensity) {
494
700
  }
495
701
  }
496
702
 
703
+ /** Convenience component: runs `useChunkLoader` from inside a `DataSheet`.
704
+ * Render as a child of `DataSheet` (it renders nothing itself). */
705
+ function _DataLoaderManager<T = any>({
706
+ fetchData,
707
+ ...rest
708
+ }: {
709
+ fetchData: FetchData<T>;
710
+ } & FetchDataOptions) {
711
+ useDataLoader(fetchData, rest);
712
+ return null;
713
+ }
714
+
497
715
  export function getRowsToDelete(selection) {
498
716
  let rowIndices: number[] = [];
499
717
  for (const sel of selection) {
@@ -0,0 +1,127 @@
1
+ /**
2
+ * The canonical column-filter operator vocabulary, shared by the client-side
3
+ * predicate (in-memory tables) and the server-side descriptor (a provider
4
+ * translates it to a query). Promoted to core from the PostgREST column header,
5
+ * so there is one operator model, not two.
6
+ */
7
+ import type { ColumnSpec } from "../utils/column-spec";
8
+
9
+ /** Column-filter operators. A superset that covers both in-memory comparison
10
+ * and common backend query operators (PostgREST maps onto these names). */
11
+ export type FilterOperator =
12
+ | "eq"
13
+ | "neq"
14
+ | "like"
15
+ | "ilike"
16
+ | "gt"
17
+ | "lt"
18
+ | "gte"
19
+ | "lte"
20
+ | "is";
21
+
22
+ /** Human-readable operator labels for menus and active-filter tags. */
23
+ export const OPERATOR_LABELS: Record<FilterOperator, string> = {
24
+ eq: "=",
25
+ neq: "≠",
26
+ like: "like",
27
+ ilike: "contains",
28
+ gt: ">",
29
+ lt: "<",
30
+ gte: "≥",
31
+ lte: "≤",
32
+ is: "is",
33
+ };
34
+
35
+ const STRING_OPERATORS: FilterOperator[] = ["eq", "neq", "ilike"];
36
+ const NUMERIC_OPERATORS: FilterOperator[] = [
37
+ "eq",
38
+ "neq",
39
+ "gt",
40
+ "lt",
41
+ "gte",
42
+ "lte",
43
+ ];
44
+ const BOOLEAN_OPERATORS: FilterOperator[] = ["eq", "neq"];
45
+
46
+ /** Fallback when the column has no type information. */
47
+ export const DEFAULT_FILTER_OPERATORS: FilterOperator[] = [
48
+ "eq",
49
+ "neq",
50
+ "ilike",
51
+ "gt",
52
+ "lt",
53
+ "gte",
54
+ "lte",
55
+ ];
56
+
57
+ const OPERATORS_BY_TYPE: Record<string, FilterOperator[]> = {
58
+ string: STRING_OPERATORS,
59
+ number: NUMERIC_OPERATORS,
60
+ integer: NUMERIC_OPERATORS,
61
+ boolean: BOOLEAN_OPERATORS,
62
+ };
63
+
64
+ /** Resolve the operators offered for a column: explicit `filterable.operators`
65
+ * first, else inferred from `dataType`, else the defaults. */
66
+ export function getOperatorsForColumn(col: ColumnSpec): FilterOperator[] {
67
+ if (typeof col.filterable === "object" && col.filterable.operators?.length) {
68
+ return col.filterable.operators as FilterOperator[];
69
+ }
70
+ if (col.dataType != null) {
71
+ return OPERATORS_BY_TYPE[col.dataType] ?? DEFAULT_FILTER_OPERATORS;
72
+ }
73
+ return DEFAULT_FILTER_OPERATORS;
74
+ }
75
+
76
+ function looseEq(a: any, b: any): boolean {
77
+ if (a == null) return b == null || b === "";
78
+ // Compare numerically when both look numeric, else as strings.
79
+ const an = Number(a);
80
+ const bn = Number(b);
81
+ if (!Number.isNaN(an) && !Number.isNaN(bn) && String(a).trim() !== "") {
82
+ return an === bn;
83
+ }
84
+ return String(a).toLowerCase() === String(b).toLowerCase();
85
+ }
86
+
87
+ /**
88
+ * The client-side predicate for a `{ operator, value }` column filter — the
89
+ * in-memory equivalent of what a backend applies server-side. An empty filter
90
+ * value is treated as "no constraint" (matches everything).
91
+ */
92
+ export function testFilterOperator(
93
+ cellValue: any,
94
+ operator: FilterOperator,
95
+ filterValue: any,
96
+ ): boolean {
97
+ if (filterValue === "" || filterValue == null) return true;
98
+ switch (operator) {
99
+ case "eq":
100
+ return looseEq(cellValue, filterValue);
101
+ case "neq":
102
+ return !looseEq(cellValue, filterValue);
103
+ case "gt":
104
+ return Number(cellValue) > Number(filterValue);
105
+ case "lt":
106
+ return Number(cellValue) < Number(filterValue);
107
+ case "gte":
108
+ return Number(cellValue) >= Number(filterValue);
109
+ case "lte":
110
+ return Number(cellValue) <= Number(filterValue);
111
+ case "like":
112
+ return String(cellValue ?? "").includes(String(filterValue));
113
+ case "ilike":
114
+ return String(cellValue ?? "")
115
+ .toLowerCase()
116
+ .includes(String(filterValue).toLowerCase());
117
+ case "is": {
118
+ const v = String(filterValue).toLowerCase();
119
+ if (v === "null") return cellValue == null;
120
+ if (v === "true") return cellValue === true;
121
+ if (v === "false") return cellValue === false;
122
+ return looseEq(cellValue, filterValue);
123
+ }
124
+ default:
125
+ return true;
126
+ }
127
+ }