@macrostrat/data-sheet 4.2.0 → 4.3.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 (71) hide show
  1. package/CHANGELOG.md +95 -0
  2. package/dist/actions/types.d.ts +10 -0
  3. package/dist/components/indicators/filter-and-sort.cjs +47 -6
  4. package/dist/components/indicators/filter-and-sort.cjs.map +1 -1
  5. package/dist/components/indicators/filter-and-sort.d.ts +28 -6
  6. package/dist/components/indicators/filter-and-sort.js +48 -7
  7. package/dist/components/indicators/filter-and-sort.js.map +1 -1
  8. package/dist/components/indicators/filter-and-sort.module.sass.cjs +5 -3
  9. package/dist/components/indicators/filter-and-sort.module.sass.cjs.map +1 -1
  10. package/dist/components/indicators/filter-and-sort.module.sass.js +5 -3
  11. package/dist/components/indicators/filter-and-sort.module.sass.js.map +1 -1
  12. package/dist/components/indicators/unified-filters.cjs +36 -22
  13. package/dist/components/indicators/unified-filters.cjs.map +1 -1
  14. package/dist/components/indicators/unified-filters.d.ts +10 -8
  15. package/dist/components/indicators/unified-filters.js +37 -23
  16. package/dist/components/indicators/unified-filters.js.map +1 -1
  17. package/dist/components/indicators/view-info.cjs +11 -5
  18. package/dist/components/indicators/view-info.cjs.map +1 -1
  19. package/dist/components/indicators/view-info.d.ts +6 -1
  20. package/dist/components/indicators/view-info.js +12 -6
  21. package/dist/components/indicators/view-info.js.map +1 -1
  22. package/dist/components/toolbars/actions-toolbar.cjs +7 -1
  23. package/dist/components/toolbars/actions-toolbar.cjs.map +1 -1
  24. package/dist/components/toolbars/actions-toolbar.js +7 -1
  25. package/dist/components/toolbars/actions-toolbar.js.map +1 -1
  26. package/dist/data-panel.cjs +53 -8
  27. package/dist/data-panel.cjs.map +1 -1
  28. package/dist/data-panel.d.ts +1 -1
  29. package/dist/data-panel.js +54 -9
  30. package/dist/data-panel.js.map +1 -1
  31. package/dist/data-panel.module.sass.cjs +24 -21
  32. package/dist/data-panel.module.sass.cjs.map +1 -1
  33. package/dist/data-panel.module.sass.js +24 -21
  34. package/dist/data-panel.module.sass.js.map +1 -1
  35. package/dist/data-sheet.cjs +9 -2
  36. package/dist/data-sheet.cjs.map +1 -1
  37. package/dist/data-sheet.css +56 -35
  38. package/dist/data-sheet.d.ts +1 -1
  39. package/dist/data-sheet.js +9 -2
  40. package/dist/data-sheet.js.map +1 -1
  41. package/dist/index.cjs +2 -0
  42. package/dist/index.cjs.map +1 -1
  43. package/dist/index.js +3 -1
  44. package/dist/postgrest-table/data-loaders.cjs +20 -3
  45. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  46. package/dist/postgrest-table/data-loaders.d.ts +10 -0
  47. package/dist/postgrest-table/data-loaders.js +21 -4
  48. package/dist/postgrest-table/data-loaders.js.map +1 -1
  49. package/dist/provider/core.cjs +27 -56
  50. package/dist/provider/core.cjs.map +1 -1
  51. package/dist/provider/core.d.ts +7 -9
  52. package/dist/provider/core.js +19 -48
  53. package/dist/provider/core.js.map +1 -1
  54. package/dist/provider/interactions.d.ts +1 -1
  55. package/dist/provider/selection.d.ts +1 -1
  56. package/dist/types.cjs.map +1 -1
  57. package/dist/types.d.ts +4 -0
  58. package/dist/types.js.map +1 -1
  59. package/package.json +6 -7
  60. package/src/actions/types.ts +11 -0
  61. package/src/components/indicators/filter-and-sort.module.sass +7 -0
  62. package/src/components/indicators/filter-and-sort.ts +71 -11
  63. package/src/components/indicators/unified-filters.ts +66 -29
  64. package/src/components/indicators/view-info.ts +15 -5
  65. package/src/components/toolbars/actions-toolbar.ts +10 -1
  66. package/src/data-panel.module.sass +18 -1
  67. package/src/data-panel.ts +67 -8
  68. package/src/data-sheet.ts +18 -2
  69. package/src/postgrest-table/data-loaders.ts +40 -4
  70. package/src/provider/core.ts +29 -53
  71. package/src/types.ts +4 -0
@@ -2,6 +2,7 @@ import {
2
2
  ALL_CARDINALITIES,
3
3
  isColumnFilterable,
4
4
  TableAction,
5
+ TableFilter,
5
6
  } from "../../actions";
6
7
  import { ctx, storeAtom, useSelector } from "../../provider";
7
8
  import { useMemo } from "react";
@@ -10,33 +11,74 @@ import { Menu, Tag } from "@blueprintjs/core";
10
11
  import {
11
12
  ColumnFilterMenuItem,
12
13
  ColumnSortMenu,
14
+ InlineFilterControl,
13
15
  MenuDropdown,
16
+ MenuInlineFilterItem,
14
17
  resolveColumnFilter,
15
18
  } from "./filter-and-sort.ts";
16
19
  import { atom } from "jotai";
17
20
 
21
+ /** A filter to surface, plus the label to show for it. */
22
+ interface FilterEntry {
23
+ filter: TableFilter;
24
+ label: string;
25
+ }
26
+
18
27
  /**
19
- * Stand-in for the column-header dropdown the card list lacks: "Filter" and
20
- * "Sort" menus listing the column-declared `filterable` / `sortable` fields.
21
- * Each field reuses the *exact* data-sheet controls — `ColumnSortMenu`
22
- * (Ascending/Descending submenu) and `ColumnFilterMenuItem` (the operator form
23
- * in a submenu) — so sort/filter behave identically to the sheet and flow
24
- * through the same store + provider seam (the server applies them).
28
+ * Stand-in for the column-header dropdown the card list lacks. Surfaces every
29
+ * available filter (column-declared `filterable` + any table-level `filters`)
30
+ * and sort, honoring each filter's `presentation`:
31
+ * - `"inline"` → an always-visible toolbar control (its `filterForm` directly),
32
+ * - `"menu"` (default) → a "Filter" menu item that opens the form in a submenu,
33
+ * - `"menu-inline"` → the form rendered directly in the "Filter" menu.
34
+ * Every case reuses the *same* controls and store/provider seam — only
35
+ * placement changes. Sort still comes from the column-declared `sortable` set.
25
36
  */
26
- export function useDataPanelControls(): TableAction[] {
27
- const filterAction = useUnifiedFilterAction();
37
+ export function useDataPanelControls(
38
+ tableFilters: TableFilter[] = [],
39
+ ): TableAction[] {
40
+ const columnSpec = useSelector((s) => s.columnSpec);
28
41
 
29
- const actions: TableAction[] = [];
30
- if (filterAction != null) {
31
- actions.push(filterAction);
32
- }
42
+ // All filters, table-level first, then column-derived (each with a label).
43
+ const entries = useMemo<FilterEntry[]>(() => {
44
+ const fromColumns = columnSpec
45
+ .filter((c) => isColumnFilterable(c))
46
+ .map((c) => ({ filter: resolveColumnFilter(c), label: c.name }));
47
+ const fromTable = tableFilters.map((f) => ({ filter: f, label: f.name }));
48
+ return [...fromTable, ...fromColumns];
49
+ }, [columnSpec, tableFilters]);
50
+
51
+ const inlineEntries = entries.filter(
52
+ (e) => presentationOf(e.filter) === "inline",
53
+ );
54
+ const menuEntries = entries.filter(
55
+ (e) => presentationOf(e.filter) !== "inline",
56
+ );
57
+
58
+ // Hooks first (stable order), then assemble.
59
+ const filterMenuAction = useFilterMenuAction(menuEntries);
33
60
  const sortAction = useSortAction();
34
- if (sortAction != null) {
35
- actions.push(sortAction);
61
+
62
+ const actions: TableAction[] = [];
63
+ // Inline filters: one always-visible toolbar control each.
64
+ for (const { filter } of inlineEntries) {
65
+ actions.push({
66
+ id: `filter:${filter.id}`,
67
+ name: filter.name,
68
+ icon: filter.icon,
69
+ targets: ALL_CARDINALITIES,
70
+ render: () => h(InlineFilterControl, { filter }),
71
+ });
36
72
  }
73
+ if (filterMenuAction != null) actions.push(filterMenuAction);
74
+ if (sortAction != null) actions.push(sortAction);
37
75
  return actions;
38
76
  }
39
77
 
78
+ function presentationOf(filter: TableFilter): string {
79
+ return filter.presentation ?? "menu";
80
+ }
81
+
40
82
  function useDisplayIntent(atom) {
41
83
  const [hasActive, clearActive] = ctx.use(atom);
42
84
  const intent = hasActive ? "primary" : "none";
@@ -54,26 +96,21 @@ function useDisplayIntent(atom) {
54
96
  return { intent, rightIcon, onRemove, hasActive };
55
97
  }
56
98
 
57
- function useUnifiedFilterAction(): TableAction | null {
58
- const columnSpec = useSelector((s) => s.columnSpec);
59
- const filterableCols = useMemo(
60
- () => columnSpec.filter((c) => isColumnFilterable(c)),
61
- [columnSpec],
62
- );
63
-
99
+ function useFilterMenuAction(entries: FilterEntry[]): TableAction | null {
64
100
  const rest = useDisplayIntent(hasActiveFiltersAtom);
65
101
 
66
- if (filterableCols.length === 0) return null;
102
+ if (entries.length === 0) return null;
67
103
 
68
104
  const filterMenu = h(
69
105
  Menu,
70
- filterableCols.map((col) =>
71
- h(ColumnFilterMenuItem, {
72
- key: col.key,
73
- filter: resolveColumnFilter(col),
74
- label: col.name,
75
- }),
76
- ),
106
+ entries.map(({ filter, label }) => {
107
+ // A `menu-inline` filter renders its form directly in the menu (no
108
+ // submenu); the default `menu` presentation uses the submenu item.
109
+ if (presentationOf(filter) === "menu-inline") {
110
+ return h(MenuInlineFilterItem, { key: filter.id, filter, label });
111
+ }
112
+ return h(ColumnFilterMenuItem, { key: filter.id, filter, label });
113
+ }),
77
114
  );
78
115
 
79
116
  const filterIndicator = h(
@@ -7,21 +7,31 @@ import { Button, ButtonGroup, Icon, Spinner } from "@blueprintjs/core";
7
7
  * scroll mode: rows loaded, "of total" when known, and a status icon (spinner
8
8
  * loading / check complete / dots incomplete). In paged mode: prev/next page
9
9
  * controls with "Page X of Y". */
10
- export function LoadProgressIndicator() {
10
+ export function LoadProgressIndicator({ iconSize: size = 12, className }) {
11
11
  const footer = ctx.useValue(tableFooterAtom);
12
+
13
+ // A load error takes precedence over the normal progress display in every
14
+ // mode — a compact, non-crashing signal that the source failed.
15
+ if (footer.error != null) {
16
+ return h("div.load-progress.load-error", { className }, [
17
+ h(Icon, { icon: "error", size, intent: "danger" }),
18
+ h("span.load-progress-label", footer.error.message ?? "Failed to load"),
19
+ ]);
20
+ }
21
+
12
22
  if (footer.mode === "paged") return h(PageControl);
13
23
 
14
24
  const { loaded, total, loading } = footer;
15
25
  let status: any;
16
26
  if (loading) {
17
- status = h(Spinner, { size: 12 });
27
+ status = h(Spinner, { size });
18
28
  } else if (total != null && loaded >= total) {
19
- status = h(Icon, { icon: "tick", size: 12 });
29
+ status = h(Icon, { icon: "tick", size });
20
30
  } else {
21
- status = h(Icon, { icon: "more", size: 12 });
31
+ status = h(Icon, { icon: "more", size });
22
32
  }
23
33
 
24
- return h("div.load-progress", [h(LoadProgressLabel), status]);
34
+ return h("div.load-progress", { className }, [h(LoadProgressLabel), status]);
25
35
  }
26
36
 
27
37
  export function LoadProgressLabel() {
@@ -79,7 +79,10 @@ export function ActionsToolbar<T>({
79
79
  [actions, columnSpec],
80
80
  );
81
81
 
82
- if (!toolbarIsShown) {
82
+ // Render whenever there are displayable actions OR the consumer supplied
83
+ // custom toolbar chrome (`children`) — a facet-less panel (e.g. a card list
84
+ // with only a search box) still needs its toolbar slot to appear.
85
+ if (!toolbarIsShown && children == null) {
83
86
  return null;
84
87
  }
85
88
 
@@ -165,6 +168,10 @@ function RunActionButton<T>({ action }: { action: TableAction<T> }) {
165
168
  return h(
166
169
  Button,
167
170
  {
171
+ // Minimal + small to match the toolbar's other controls (scroll-to-row,
172
+ // sort/filter tags) — the compact, minimal house style.
173
+ minimal: true,
174
+ small: true,
168
175
  icon: action.icon,
169
176
  intent: action.intent,
170
177
  disabled: isDisabled,
@@ -230,6 +237,8 @@ function ActionButtonWithForm<T, S>({
230
237
  h(
231
238
  Button,
232
239
  {
240
+ minimal: true,
241
+ small: true,
233
242
  icon: action.icon,
234
243
  intent: action.intent,
235
244
  disabled: isDisabled,
@@ -53,9 +53,26 @@
53
53
  min-width: 0
54
54
 
55
55
  // The inline end-of-scroll region (default spinner sentinel, or an inline
56
- // footer). Sits in the scroll flow, so it's seen only at the bottom.
56
+ // footer). Sits in the scroll flow, so it's seen only at the bottom. A constant
57
+ // min-height keeps its content (spinner / "Load more" / end note) swapping in
58
+ // place instead of the footer pinging up into the list as pages append.
57
59
  .content-footer-holder
58
60
  flex: 0 0 auto
61
+ min-height: 44px
62
+ display: flex
63
+ align-items: center
64
+ justify-content: center
65
+
66
+ // Skeleton placeholder shown where a loading page's rows will land — sized like
67
+ // a card so the body height stays stable (no blank flash, no footer ping). The
68
+ // shimmer comes from Blueprint's `.bp6-skeleton`.
69
+ .data-panel-item-container.is-skeleton
70
+ pointer-events: none
71
+
72
+ .data-panel-skeleton
73
+ width: 100%
74
+ min-height: 3.25em
75
+ border-radius: 4px
59
76
 
60
77
  // Default layout body — a vertical list of cards. A custom `scrollBody`
61
78
  // replaces this element (e.g. with a CSS grid) but keeps the same scroll
package/src/data-panel.ts CHANGED
@@ -35,7 +35,7 @@ import {
35
35
  useRef,
36
36
  useState,
37
37
  } from "react";
38
- import { Icon, Spinner } from "@blueprintjs/core";
38
+ import { Classes, Icon, NonIdealState, Spinner } from "@blueprintjs/core";
39
39
  import {
40
40
  anchorRefAtom,
41
41
  ctx,
@@ -173,7 +173,9 @@ export interface SelectModifiers {
173
173
  export function DataPanelRenderer<T>({
174
174
  itemComponent,
175
175
  actions = [],
176
+ filters = [],
176
177
  pageSize = 50,
178
+ filterDebounce,
177
179
  name,
178
180
  // Bottom bar
179
181
  statusBar,
@@ -211,8 +213,17 @@ export function DataPanelRenderer<T>({
211
213
  // (also available to the caller's `footer` via the same hook). The panel's
212
214
  // `autoLoadPages` prop is the store's configuration input.
213
215
  ctx.useSync(autoLoadPagesAtom, autoLoadPages ?? null);
214
- const { loading, hasMore, loaded, total, paused, canLoadMore, advance } =
215
- useLoadControls();
216
+ const {
217
+ loading,
218
+ initialized,
219
+ error,
220
+ hasMore,
221
+ loaded,
222
+ total,
223
+ paused,
224
+ canLoadMore,
225
+ advance,
226
+ } = useLoadControls();
216
227
 
217
228
  // Track whether the body is scrolled off the top, to gate the top fade.
218
229
  // `setState` with an unchanged value is a no-op, so this only re-renders on
@@ -256,8 +267,8 @@ export function DataPanelRenderer<T>({
256
267
  const selected = enableSelection && selectedIndices.has(i);
257
268
  cards.push(
258
269
  h(
259
- "div.data-panel-item",
260
- { key: `row-${i}`, className: classNames({ selected }) },
270
+ "div.data-panel-item-container",
271
+ { key: `item-${i}`, className: classNames({ selected }) },
261
272
  h(itemComponent, {
262
273
  data: row,
263
274
  index: i,
@@ -270,9 +281,52 @@ export function DataPanelRenderer<T>({
270
281
  );
271
282
  });
272
283
 
284
+ // Body-level empty/error state: when nothing has loaded, show a clear message
285
+ // instead of a blank list — an errored source (e.g. a 401 on the whole route)
286
+ // degrades gracefully, and a genuinely empty result reads as "no results"
287
+ // rather than a perpetual spinner.
288
+ // A load is pending whenever a fetch is in flight OR the view was just reset
289
+ // and hasn't fetched yet (`!initialized`) — the window that would otherwise
290
+ // flash "No results" before the request starts.
291
+ const loadPending = (loading || !initialized) && error == null;
292
+
293
+ let emptyState: ReactNode = null;
294
+ if (cards.length === 0) {
295
+ if (error != null) {
296
+ emptyState = h(NonIdealState, {
297
+ icon: "error",
298
+ title: "Couldn't load data",
299
+ description: error.message ?? "The data source returned an error.",
300
+ });
301
+ } else if (initialized && !loading) {
302
+ // Only after a fetch settled with no rows — not during the reset gap.
303
+ emptyState = h(NonIdealState, {
304
+ icon: "search",
305
+ title: "No results",
306
+ });
307
+ }
308
+ }
309
+
310
+ // Skeleton placeholders for the page being fetched — on a view change (the
311
+ // reset pre-sizes to a page of `null` slots) or the next scroll page — so the
312
+ // body shows shimmer where rows will land instead of a blank flash or a
313
+ // footer pinging up into the gap. Bounded to a viewport's worth of cards.
314
+ if (loadPending) {
315
+ const pending = Math.min(Math.max(data.length - loadedCount, 0), 24);
316
+ for (let i = 0; i < pending; i++) {
317
+ cards.push(
318
+ h(
319
+ "div.data-panel-item-container.is-skeleton",
320
+ { key: `skeleton-${i}`, "aria-hidden": true },
321
+ h("div.data-panel-skeleton", { className: Classes.SKELETON }),
322
+ ),
323
+ );
324
+ }
325
+ }
326
+
273
327
  // The default spinner sentinel (below-placement): hidden while paused so the
274
328
  // pinned footer's "Load more" takes over.
275
- const shouldLoadNextPage = (hasMore || loading) && !paused;
329
+ const shouldLoadNextPage = (hasMore || loading) && !paused && error == null;
276
330
 
277
331
  // Mount the loader only once the provider resolves (see `PanelLoader`). Built
278
332
  // as a real conditional — `h.if(...)` evaluates its arguments eagerly, so
@@ -283,10 +337,11 @@ export function DataPanelRenderer<T>({
283
337
  fetchData: activeProvider.fetchData,
284
338
  pageSize: loaderPageSize,
285
339
  fetchMode: isLocalProvider ? undefined : "scroll",
340
+ filterDebounce,
286
341
  });
287
342
  }
288
343
 
289
- const coreActions = useDataPanelControls();
344
+ const coreActions = useDataPanelControls(filters);
290
345
 
291
346
  // Merge consumer actions with the synthesized Filter/Sort controls, deduped
292
347
  // by id — consumer actions come first, so passing an action with id `filter`
@@ -360,6 +415,10 @@ export function DataPanelRenderer<T>({
360
415
  actions: _actions,
361
416
  tableName: name,
362
417
  className: "data-panel-toolbar-content",
418
+ // In the panel the title doubles as the modal-selection control,
419
+ // so only render it when modal selection is toggle-able (or a
420
+ // selection is active) — not as a bare label otherwise.
421
+ compact: true,
363
422
  },
364
423
  toolbar,
365
424
  ),
@@ -371,7 +430,7 @@ export function DataPanelRenderer<T>({
371
430
  className: classNames({ "is-scrolled": scrolled }),
372
431
  },
373
432
  h("div.data-panel-body-content", [
374
- h(ScrollBody, cards),
433
+ emptyState ?? h(ScrollBody, cards),
375
434
  _contentFooter,
376
435
  ]),
377
436
  ),
package/src/data-sheet.ts CHANGED
@@ -108,6 +108,7 @@ export function DataSheetRenderer<T>({
108
108
  provider,
109
109
  pageSize,
110
110
  fetchMode,
111
+ filterDebounce,
111
112
  onVisibleCellsChange,
112
113
  onUpdateData,
113
114
  onEdit,
@@ -286,6 +287,13 @@ export function DataSheetRenderer<T>({
286
287
  }
287
288
 
288
289
  const onColumnsReordered = useSelector((state) => state.onColumnsReordered);
290
+ // Whether table-level column drag-reordering is enabled. Held in the store
291
+ // (set from the `enableColumnReordering` prop by the provider); it must reach
292
+ // the Blueprint `Table` — the `onColumnsReordered` handler alone doesn't turn
293
+ // on the drag affordance.
294
+ const enableColumnReordering = useSelector(
295
+ (state) => state.enableColumnReordering,
296
+ );
289
297
 
290
298
  // Auto-detect if any columns have sortable/filterable set.
291
299
  // If so and no explicit columnHeaderCellRenderer was provided,
@@ -447,9 +455,14 @@ export function DataSheetRenderer<T>({
447
455
  }
448
456
 
449
457
  const defaultLabel = `${dataRowIndex + 1}`;
450
- let name: string = defaultLabel;
458
+ // A custom renderer supplies the header's *name* content (a group-key
459
+ // label, an omit indicator, …); a nullish return keeps the default
460
+ // 1-based label. Either way the node is wrapped in a `RowHeaderCell` so
461
+ // status styling and the row index are always applied — the renderer is
462
+ // not responsible for producing the whole cell.
463
+ let name: ReactNode = defaultLabel;
451
464
  if (rowHeaderRenderer != null) {
452
- return rowHeaderRenderer({
465
+ const custom = rowHeaderRenderer({
453
466
  rowIndex: dataRowIndex,
454
467
  visibleIndex: rowIndex,
455
468
  row: data[dataRowIndex] ?? updatedData[dataRowIndex],
@@ -457,6 +470,7 @@ export function DataSheetRenderer<T>({
457
470
  isDeleted: statusVal === TableElementStatus.DELETED,
458
471
  defaultLabel,
459
472
  });
473
+ if (custom != null) name = custom;
460
474
  }
461
475
 
462
476
  return h(RowHeaderCell, {
@@ -526,6 +540,7 @@ export function DataSheetRenderer<T>({
526
540
  fetchData: activeProvider.fetchData,
527
541
  pageSize: isLocalProvider ? Math.max(localCount, 1) : pageSize,
528
542
  fetchMode: isLocalProvider ? undefined : fetchMode,
543
+ filterDebounce,
529
544
  });
530
545
  }
531
546
  const showFilterBar =
@@ -558,6 +573,7 @@ export function DataSheetRenderer<T>({
558
573
  numRows,
559
574
  className: "data-sheet",
560
575
  enableFocusedCell,
576
+ enableColumnReordering,
561
577
  onColumnsReordered,
562
578
  focusedCell,
563
579
  selectedRegions,
@@ -2,7 +2,7 @@
2
2
 
3
3
  import { useAsyncEffect } from "@macrostrat/ui-components";
4
4
  import { debounce } from "underscore";
5
- import { useCallback, useEffect, useMemo, useRef } from "react";
5
+ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
6
6
  import update, { Spec } from "immutability-helper";
7
7
  import {
8
8
  ClientServerOptions,
@@ -372,6 +372,10 @@ export interface TableFooterInfo {
372
372
  loaded: number;
373
373
  total: number | null;
374
374
  loading: boolean;
375
+ /** A fetch has been attempted since the last view reset — so `loaded === 0`
376
+ * can be told apart from "not loaded yet" (avoids an empty-state flash). */
377
+ initialized: boolean;
378
+ error: Error | null;
375
379
  page: number;
376
380
  pageSize: number;
377
381
  totalPages: number | null;
@@ -396,6 +400,8 @@ export const tableFooterAtom = atom<TableFooterInfo>((get) => {
396
400
  loaded,
397
401
  total,
398
402
  loading: core.loading,
403
+ initialized: core.initialized,
404
+ error: core.error,
399
405
  page: get(chunkPageAtom),
400
406
  pageSize: core.pageSize,
401
407
  totalPages,
@@ -419,6 +425,12 @@ export interface LoadControls {
419
425
  loadMore: () => void;
420
426
  /** A fetch is in flight. */
421
427
  loading: boolean;
428
+ /** A fetch has been attempted since the last view reset (so an empty result
429
+ * can be told apart from "not loaded yet"). */
430
+ initialized: boolean;
431
+ /** The most recent load error (cleared on the next successful load), else
432
+ * `null` — so a footer/consumer can degrade gracefully instead of hanging. */
433
+ error: Error | null;
422
434
  /** More rows remain to load. */
423
435
  hasMore: boolean;
424
436
  /** Rows loaded so far. */
@@ -472,6 +484,8 @@ export function useLoadControls(): LoadControls {
472
484
  return {
473
485
  loadMore,
474
486
  loading: footer.loading,
487
+ initialized: footer.initialized,
488
+ error: footer.error,
475
489
  hasMore,
476
490
  loaded: footer.loaded,
477
491
  total: footer.total,
@@ -627,7 +641,7 @@ export function useDataLoader<T = any>(
627
641
  fetchChunk: FetchData<T>,
628
642
  options: FetchDataOptions = {},
629
643
  ) {
630
- const { pageSize = 100, fetchMode = "scroll" } = options;
644
+ const { pageSize = 100, fetchMode = "scroll", filterDebounce = 0 } = options;
631
645
  const [state, dispatch] = useLazyLoaderReducer();
632
646
 
633
647
  const { isLocalProvider, provider } = ctx.useValue(dataProviderAtom);
@@ -671,10 +685,17 @@ export function useDataLoader<T = any>(
671
685
  () => JSON.stringify({ sorts: columnSorts, filters }),
672
686
  [columnSorts, filters],
673
687
  );
688
+ // Debounce the view-state → refetch: rapid changes (typing in a text filter)
689
+ // otherwise reset + refetch on every keystroke, flashing the list. The store
690
+ // (and so the filter input) still updates instantly; only the *fetch* waits
691
+ // for the view to settle. Scroll paging is unaffected — it's driven by
692
+ // `visibleRegion`/`data`, not this key. `filterDebounce: 0` (default) keeps
693
+ // the immediate behavior.
694
+ const debouncedViewKey = useDebouncedValue(viewKey, filterDebounce);
674
695
  useEffect(() => {
675
696
  dispatch({ type: "reset" });
676
697
  setPage(0);
677
- }, [viewKey, fetchMode, refreshToken]);
698
+ }, [debouncedViewKey, fetchMode, refreshToken]);
678
699
 
679
700
  useAsyncEffect(async () => {
680
701
  if (state.loading) return;
@@ -759,11 +780,26 @@ export function useDataLoader<T = any>(
759
780
  dispatch({ type: "error", error: err as Error });
760
781
  }
761
782
  }
762
- }, [state.data, visibleRegion, viewKey, page, fetchMode]);
783
+ }, [state.data, visibleRegion, debouncedViewKey, page, fetchMode]);
763
784
 
764
785
  return { data: state.data, loading: state.loading, error: state.error };
765
786
  }
766
787
 
788
+ /** A value that trails `value` by `delay` ms of stability — the first value is
789
+ * returned immediately, and `delay <= 0` disables debouncing entirely. */
790
+ function useDebouncedValue<T>(value: T, delay: number): T {
791
+ const [debounced, setDebounced] = useState(value);
792
+ useEffect(() => {
793
+ if (delay <= 0) {
794
+ setDebounced(value);
795
+ return;
796
+ }
797
+ const t = setTimeout(() => setDebounced(value), delay);
798
+ return () => clearTimeout(t);
799
+ }, [value, delay]);
800
+ return debounced;
801
+ }
802
+
767
803
  /**
768
804
  * Build a `fetchChunk` backed by a PostgREST endpoint, for use with
769
805
  * `useChunkLoader` / `ChunkLoaderManager`. It reuses `buildQuery`, so it pages