@macrostrat/data-sheet 4.2.1 → 4.4.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 (95) hide show
  1. package/CHANGELOG.md +134 -0
  2. package/dist/actions/types.d.ts +10 -0
  3. package/dist/components/indicators/filter-and-sort.cjs +61 -9
  4. package/dist/components/indicators/filter-and-sort.cjs.map +1 -1
  5. package/dist/components/indicators/filter-and-sort.d.ts +49 -7
  6. package/dist/components/indicators/filter-and-sort.js +62 -10
  7. package/dist/components/indicators/filter-and-sort.js.map +1 -1
  8. package/dist/components/indicators/filter-and-sort.module.sass.cjs +7 -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 +7 -3
  11. package/dist/components/indicators/filter-and-sort.module.sass.js.map +1 -1
  12. package/dist/components/indicators/selection.cjs +7 -12
  13. package/dist/components/indicators/selection.cjs.map +1 -1
  14. package/dist/components/indicators/selection.d.ts +5 -0
  15. package/dist/components/indicators/selection.js +9 -14
  16. package/dist/components/indicators/selection.js.map +1 -1
  17. package/dist/components/indicators/unified-filters.cjs +135 -22
  18. package/dist/components/indicators/unified-filters.cjs.map +1 -1
  19. package/dist/components/indicators/unified-filters.d.ts +17 -8
  20. package/dist/components/indicators/unified-filters.js +137 -24
  21. package/dist/components/indicators/unified-filters.js.map +1 -1
  22. package/dist/components/indicators/view-info.cjs +6 -0
  23. package/dist/components/indicators/view-info.cjs.map +1 -1
  24. package/dist/components/indicators/view-info.d.ts +2 -2
  25. package/dist/components/indicators/view-info.js +7 -1
  26. package/dist/components/indicators/view-info.js.map +1 -1
  27. package/dist/components/toolbars/actions-toolbar.cjs +7 -1
  28. package/dist/components/toolbars/actions-toolbar.cjs.map +1 -1
  29. package/dist/components/toolbars/actions-toolbar.js +7 -1
  30. package/dist/components/toolbars/actions-toolbar.js.map +1 -1
  31. package/dist/components/toolbars/actions-toolbar.module.sass.cjs +12 -12
  32. package/dist/components/toolbars/actions-toolbar.module.sass.js +12 -12
  33. package/dist/data-panel.cjs +62 -9
  34. package/dist/data-panel.cjs.map +1 -1
  35. package/dist/data-panel.d.ts +14 -2
  36. package/dist/data-panel.js +64 -11
  37. package/dist/data-panel.js.map +1 -1
  38. package/dist/data-panel.module.sass.cjs +25 -21
  39. package/dist/data-panel.module.sass.cjs.map +1 -1
  40. package/dist/data-panel.module.sass.js +25 -21
  41. package/dist/data-panel.module.sass.js.map +1 -1
  42. package/dist/data-sheet.cjs +3 -1
  43. package/dist/data-sheet.cjs.map +1 -1
  44. package/dist/data-sheet.css +75 -50
  45. package/dist/data-sheet.d.ts +1 -1
  46. package/dist/data-sheet.js +3 -1
  47. package/dist/data-sheet.js.map +1 -1
  48. package/dist/index.cjs +6 -0
  49. package/dist/index.cjs.map +1 -1
  50. package/dist/index.js +9 -3
  51. package/dist/postgrest-table/data-loaders.cjs +20 -3
  52. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  53. package/dist/postgrest-table/data-loaders.d.ts +10 -0
  54. package/dist/postgrest-table/data-loaders.js +21 -4
  55. package/dist/postgrest-table/data-loaders.js.map +1 -1
  56. package/dist/provider/core.cjs +27 -56
  57. package/dist/provider/core.cjs.map +1 -1
  58. package/dist/provider/core.d.ts +7 -9
  59. package/dist/provider/core.js +19 -48
  60. package/dist/provider/core.js.map +1 -1
  61. package/dist/provider/interactions.cjs +14 -0
  62. package/dist/provider/interactions.cjs.map +1 -1
  63. package/dist/provider/interactions.d.ts +20 -1
  64. package/dist/provider/interactions.js +15 -1
  65. package/dist/provider/interactions.js.map +1 -1
  66. package/dist/provider/selection.cjs +2 -2
  67. package/dist/provider/selection.cjs.map +1 -1
  68. package/dist/provider/selection.d.ts +1 -1
  69. package/dist/provider/selection.js +3 -3
  70. package/dist/provider/selection.js.map +1 -1
  71. package/dist/provider/zustand-store.cjs +13 -6
  72. package/dist/provider/zustand-store.cjs.map +1 -1
  73. package/dist/provider/zustand-store.js +13 -6
  74. package/dist/provider/zustand-store.js.map +1 -1
  75. package/dist/types.cjs.map +1 -1
  76. package/dist/types.d.ts +4 -0
  77. package/dist/types.js.map +1 -1
  78. package/package.json +5 -6
  79. package/src/actions/types.ts +11 -0
  80. package/src/components/indicators/filter-and-sort.module.sass +7 -0
  81. package/src/components/indicators/filter-and-sort.ts +102 -13
  82. package/src/components/indicators/selection.ts +10 -15
  83. package/src/components/indicators/unified-filters.ts +215 -32
  84. package/src/components/indicators/view-info.ts +10 -0
  85. package/src/components/toolbars/actions-toolbar.module.sass +1 -1
  86. package/src/components/toolbars/actions-toolbar.ts +10 -1
  87. package/src/data-panel.module.sass +26 -4
  88. package/src/data-panel.ts +92 -9
  89. package/src/data-sheet.ts +2 -0
  90. package/src/postgrest-table/data-loaders.ts +40 -4
  91. package/src/provider/core.ts +29 -53
  92. package/src/provider/interactions.ts +31 -0
  93. package/src/provider/selection.ts +3 -3
  94. package/src/provider/zustand-store.ts +23 -5
  95. package/src/types.ts +4 -0
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,
@@ -43,6 +43,7 @@ import {
43
43
  DataSheetProvider,
44
44
  DataViewRendererType,
45
45
  FetchData,
46
+ enableSelectionAtom,
46
47
  interactionOptionsAtom,
47
48
  selectionAtom,
48
49
  splitDataProviderProps,
@@ -64,6 +65,7 @@ import {
64
65
  ActionsToolbar,
65
66
  LoadProgressIndicator,
66
67
  useDataPanelControls,
68
+ type ViewControlsPresentation,
67
69
  } from "./components";
68
70
  import { DataViewSharedProps, FetchDataOptions } from "./types";
69
71
  import { atom } from "jotai";
@@ -73,6 +75,10 @@ export enum DataPanelToolbarStyle {
73
75
  BORDERED = "bordered",
74
76
  FADE = "fade",
75
77
  MINIMAL = "minimal",
78
+ /** Toolbar (and footer) sized to their contents and lifted over the scroll
79
+ * body, rather than occupying a full-width band. Pairs with
80
+ * `viewControls: "popover"`, since inline controls cost real space here. */
81
+ FLOATING = "floating",
76
82
  }
77
83
 
78
84
  /** Props for a custom scroll-body layout component. It receives the
@@ -138,6 +144,13 @@ export interface DataPanelProps<T = any> extends DataViewSharedProps<T> {
138
144
  scrollBody?: ComponentType<ScrollBodyProps>;
139
145
  className?: string;
140
146
  toolbarStyle?: DataPanelToolbarStyle | string;
147
+ /** Where the built-in view controls (inline filters, Filter menu, Sort menu)
148
+ * sit in the toolbar: `"inline"` (default) places each in the toolbar;
149
+ * `"popover"` collapses all of them behind a single button — for a narrow or
150
+ * deliberately chrome-light toolbar. Same controls and state either way.
151
+ * Ignored while a modal view is selecting: the toolbar then carries a single
152
+ * control that leaves select mode. */
153
+ viewControls?: ViewControlsPresentation;
141
154
  /** Arbitrary children rendered inside the provider, after the panel. */
142
155
  children?: ReactNode;
143
156
  }
@@ -173,7 +186,9 @@ export interface SelectModifiers {
173
186
  export function DataPanelRenderer<T>({
174
187
  itemComponent,
175
188
  actions = [],
189
+ filters = [],
176
190
  pageSize = 50,
191
+ filterDebounce,
177
192
  name,
178
193
  // Bottom bar
179
194
  statusBar,
@@ -185,6 +200,7 @@ export function DataPanelRenderer<T>({
185
200
  scrollBody,
186
201
  className,
187
202
  toolbarStyle = DataPanelToolbarStyle.BORDERED,
203
+ viewControls = "inline",
188
204
  children,
189
205
  }: Omit<DataPanelProps<T>, "provider" | "fetchData" | "data" | "identity">) {
190
206
  const {
@@ -211,8 +227,17 @@ export function DataPanelRenderer<T>({
211
227
  // (also available to the caller's `footer` via the same hook). The panel's
212
228
  // `autoLoadPages` prop is the store's configuration input.
213
229
  ctx.useSync(autoLoadPagesAtom, autoLoadPages ?? null);
214
- const { loading, hasMore, loaded, total, paused, canLoadMore, advance } =
215
- useLoadControls();
230
+ const {
231
+ loading,
232
+ initialized,
233
+ error,
234
+ hasMore,
235
+ loaded,
236
+ total,
237
+ paused,
238
+ canLoadMore,
239
+ advance,
240
+ } = useLoadControls();
216
241
 
217
242
  // Track whether the body is scrolled off the top, to gate the top fade.
218
243
  // `setState` with an unchanged value is a no-op, so this only re-renders on
@@ -222,7 +247,7 @@ export function DataPanelRenderer<T>({
222
247
  setScrolled(e.currentTarget.scrollTop > 4);
223
248
  }, []);
224
249
 
225
- const enableSelection = ctx.useValue(interactionOptionsAtom).enableSelection;
250
+ const enableSelection = ctx.useValue(enableSelectionAtom);
226
251
  const selectedIndices = ctx.useValue(selectedRowIndicesAtom);
227
252
  const select = ctx.useSet(updateSelectionAtom);
228
253
 
@@ -270,9 +295,52 @@ export function DataPanelRenderer<T>({
270
295
  );
271
296
  });
272
297
 
298
+ // Body-level empty/error state: when nothing has loaded, show a clear message
299
+ // instead of a blank list — an errored source (e.g. a 401 on the whole route)
300
+ // degrades gracefully, and a genuinely empty result reads as "no results"
301
+ // rather than a perpetual spinner.
302
+ // A load is pending whenever a fetch is in flight OR the view was just reset
303
+ // and hasn't fetched yet (`!initialized`) — the window that would otherwise
304
+ // flash "No results" before the request starts.
305
+ const loadPending = (loading || !initialized) && error == null;
306
+
307
+ let emptyState: ReactNode = null;
308
+ if (cards.length === 0) {
309
+ if (error != null) {
310
+ emptyState = h(NonIdealState, {
311
+ icon: "error",
312
+ title: "Couldn't load data",
313
+ description: error.message ?? "The data source returned an error.",
314
+ });
315
+ } else if (initialized && !loading) {
316
+ // Only after a fetch settled with no rows — not during the reset gap.
317
+ emptyState = h(NonIdealState, {
318
+ icon: "search",
319
+ title: "No results",
320
+ });
321
+ }
322
+ }
323
+
324
+ // Skeleton placeholders for the page being fetched — on a view change (the
325
+ // reset pre-sizes to a page of `null` slots) or the next scroll page — so the
326
+ // body shows shimmer where rows will land instead of a blank flash or a
327
+ // footer pinging up into the gap. Bounded to a viewport's worth of cards.
328
+ if (loadPending) {
329
+ const pending = Math.min(Math.max(data.length - loadedCount, 0), 24);
330
+ for (let i = 0; i < pending; i++) {
331
+ cards.push(
332
+ h(
333
+ "div.data-panel-item-container.is-skeleton",
334
+ { key: `skeleton-${i}`, "aria-hidden": true },
335
+ h("div.data-panel-skeleton", { className: Classes.SKELETON }),
336
+ ),
337
+ );
338
+ }
339
+ }
340
+
273
341
  // The default spinner sentinel (below-placement): hidden while paused so the
274
342
  // pinned footer's "Load more" takes over.
275
- const shouldLoadNextPage = (hasMore || loading) && !paused;
343
+ const shouldLoadNextPage = (hasMore || loading) && !paused && error == null;
276
344
 
277
345
  // Mount the loader only once the provider resolves (see `PanelLoader`). Built
278
346
  // as a real conditional — `h.if(...)` evaluates its arguments eagerly, so
@@ -283,10 +351,11 @@ export function DataPanelRenderer<T>({
283
351
  fetchData: activeProvider.fetchData,
284
352
  pageSize: loaderPageSize,
285
353
  fetchMode: isLocalProvider ? undefined : "scroll",
354
+ filterDebounce,
286
355
  });
287
356
  }
288
357
 
289
- const coreActions = useDataPanelControls();
358
+ const coreActions = useDataPanelControls(filters, viewControls);
290
359
 
291
360
  // Merge consumer actions with the synthesized Filter/Sort controls, deduped
292
361
  // by id — consumer actions come first, so passing an action with id `filter`
@@ -360,6 +429,10 @@ export function DataPanelRenderer<T>({
360
429
  actions: _actions,
361
430
  tableName: name,
362
431
  className: "data-panel-toolbar-content",
432
+ // In the panel the title doubles as the modal-selection control,
433
+ // so only render it when modal selection is toggle-able (or a
434
+ // selection is active) — not as a bare label otherwise.
435
+ compact: true,
363
436
  },
364
437
  toolbar,
365
438
  ),
@@ -371,7 +444,7 @@ export function DataPanelRenderer<T>({
371
444
  className: classNames({ "is-scrolled": scrolled }),
372
445
  },
373
446
  h("div.data-panel-body-content", [
374
- h(ScrollBody, cards),
447
+ emptyState ?? h(ScrollBody, cards),
375
448
  _contentFooter,
376
449
  ]),
377
450
  ),
@@ -486,10 +559,20 @@ const updateSelectionAtom = atom(
486
559
  null,
487
560
  (get, set, index: number, mods: SelectModifiers) => {
488
561
  /** Update selection from a row index and modifiers. */
489
- const { enableMultipleSelection, enableSelection } = get(
562
+ const { enableMultipleSelection, enableModalSelection } = get(
490
563
  interactionOptionsAtom,
491
564
  );
492
- if (!enableSelection) return;
565
+ let enableSelection = get(enableSelectionAtom);
566
+ if (!enableSelection) {
567
+ // Cmd/ctrl-click *enters* select mode on a modal view and selects the
568
+ // row, the familiar list idiom — so a bulk action doesn't require finding
569
+ // the Select control first. The flag is read back below rather than
570
+ // trusted from this scope: the write goes through the store synchronously.
571
+ if (!enableModalSelection || !mods.additive) return;
572
+ set(enableSelectionAtom, true);
573
+ enableSelection = get(enableSelectionAtom);
574
+ if (!enableSelection) return;
575
+ }
493
576
  const selection = get(rowSelectionAtom);
494
577
  const anchorRef = get(anchorRefAtom);
495
578
  const res = buildDataViewSelection(
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,
@@ -539,6 +540,7 @@ export function DataSheetRenderer<T>({
539
540
  fetchData: activeProvider.fetchData,
540
541
  pageSize: isLocalProvider ? Math.max(localCount, 1) : pageSize,
541
542
  fetchMode: isLocalProvider ? undefined : fetchMode,
543
+ filterDebounce,
542
544
  });
543
545
  }
544
546
  const showFilterBar =
@@ -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
@@ -1,6 +1,5 @@
1
- import { SetStateAction, useEffect, useMemo, useRef, useState } from "react";
1
+ import { useEffect, useMemo, useRef } from "react";
2
2
  import h from "@macrostrat/hyper";
3
- import { createStore, StoreApi, useStore } from "zustand";
4
3
  import { Table } from "@blueprintjs/table";
5
4
  import {
6
5
  type ColumnSpec,
@@ -8,7 +7,15 @@ import {
8
7
  postprocessColumnSpec,
9
8
  } from "./column-spec.ts";
10
9
  import { splitProps } from "../utils";
11
- import { createScopedStore } from "@macrostrat/data-components";
10
+ import {
11
+ createScopedStore,
12
+ zustandAPIAtom,
13
+ zustandStoreAtom,
14
+ atom,
15
+ ZustandStoreProvider,
16
+ useZustandSelector,
17
+ useZustandStoreAPI,
18
+ } from "@macrostrat/scoped-store";
12
19
  import {
13
20
  DataSheetProviderProps,
14
21
  DataSheetState,
@@ -17,10 +24,8 @@ import {
17
24
  TableElementStatus,
18
25
  } from "./types.ts";
19
26
  import { createZustandStore } from "./zustand-store.ts";
20
- import { atomWithStore } from "jotai-zustand";
21
27
  import { toasterAtom } from "../notifications.ts";
22
28
  import { TableAction } from "../actions";
23
- import { atom } from "jotai";
24
29
  import {
25
30
  createLocalProvider,
26
31
  dataRefreshTokenAtom,
@@ -42,33 +47,10 @@ import { DataPanelProps } from "../data-panel.ts";
42
47
  /** Create a Jotai scoped store */
43
48
  export const ctx = createScopedStore();
44
49
 
45
- export const storeAPIAtom = atom<StoreApi<DataSheetStore<any>>>();
46
-
47
- const storeWrapperAtom = atom((get) => {
48
- const _storeAPIAtom = get(storeAPIAtom);
49
- if (_storeAPIAtom == null) {
50
- return undefined;
51
- }
52
- return atomWithStore(_storeAPIAtom);
53
- });
50
+ export const storeAPIAtom = zustandAPIAtom;
54
51
 
55
52
  /** This is the basis for all other atoms that manipulate the store. */
56
- export const storeAtom = atom(
57
- (get) => {
58
- const storeWrapper = get(storeWrapperAtom);
59
- if (storeWrapper == null) {
60
- return undefined;
61
- }
62
- return get(storeWrapper);
63
- },
64
- (get, set, action: SetStateAction<any>) => {
65
- const storeWrapper = get(storeWrapperAtom);
66
- if (storeWrapper == null) {
67
- throw new Error("Missing DataSheetProvider");
68
- }
69
- return set(storeWrapper, action);
70
- },
71
- );
53
+ export const storeAtom = zustandStoreAtom;
72
54
 
73
55
  /** Stable empty spec so a function `columnSpec` yields a constant init value
74
56
  * (see `DataSheetProviderInner`). */
@@ -77,7 +59,7 @@ const EMPTY_SPEC: ColumnSpec[] = [];
77
59
  const initializeStoreAtom = atom(
78
60
  null,
79
61
  (get, set, payload: Partial<DataSheetStore<any>>) => {
80
- set(storeAtom, (state) => {
62
+ set(zustandStoreAtom, (state) => {
81
63
  return {
82
64
  ...state,
83
65
  ...payload,
@@ -172,16 +154,13 @@ export function useResolvedProvider<T>(props: {
172
154
 
173
155
  function DataSheetStoreWrapper<T>(props: DataSheetProviderProps<T>) {
174
156
  const { toaster, ...rest } = props;
175
- const [store] = useState(() => {
176
- return createStore<DataSheetStore<T>>(createZustandStore);
177
- });
178
157
  return h(
179
- ctx.Provider,
158
+ ZustandStoreProvider,
180
159
  {
181
- atoms: [
182
- [storeAPIAtom, store],
183
- [toasterAtom, toaster],
184
- ],
160
+ ctx,
161
+ initializeStore: createZustandStore,
162
+ atoms: [[toasterAtom, toaster]],
163
+ debugName: "DataSheetProvider",
185
164
  },
186
165
  h(DataSheetProviderInner, rest),
187
166
  );
@@ -209,9 +188,7 @@ const dataProviderKeys = new Set([
209
188
  ]);
210
189
 
211
190
  type AnyDataSheetProps<T> =
212
- | DataViewProps<T>
213
- | DataPanelProps<T>
214
- | DataSheetProps<T>;
191
+ DataViewProps<T> | DataPanelProps<T> | DataSheetProps<T>;
215
192
 
216
193
  export function splitDataProviderProps<T>(props: AnyDataSheetProps<T>) {
217
194
  /** Split provided props based on provider's needs */
@@ -295,9 +272,13 @@ export function DataSheetProviderInner<T>(
295
272
  useEffect(() => {
296
273
  initializeStore({
297
274
  columnSpec: postprocessColumnSpec(baseSpec),
298
- // A function spec is derived from the loaded rows in `_DataSheet`; tell
299
- // the loader not to auto-generate a plain spec from the first chunk.
300
- deferColumnSpec: isFnSpec,
275
+ // Suppress the loader's first-chunk auto-generation whenever the consumer
276
+ // provided a spec at all — a function (derived later in `_DataSheet`) OR
277
+ // an explicit array, *including an empty one*. An empty array means "no
278
+ // facet columns" (e.g. a browse panel whose only control is a sheet-level
279
+ // search), not "please generate from the data". Auto-gen runs only when
280
+ // no `columnSpec` was passed.
281
+ deferColumnSpec: columnSpec != null,
301
282
  editable: interactionOptions.enableEditing,
302
283
  enableColumnReordering,
303
284
  data,
@@ -398,19 +379,14 @@ export function DataSheetProviderInner<T>(
398
379
  return children;
399
380
  }
400
381
 
401
- export function useStoreAPI<T>(): StoreApi<DataSheetStore<T>> {
402
- const store = ctx.useValue(storeAPIAtom);
403
- if (!store) {
404
- throw new Error("Missing DataSheetProvider");
405
- }
406
- return store;
382
+ export function useStoreAPI<T>() {
383
+ return useZustandStoreAPI<DataSheetStore<T>>(ctx);
407
384
  }
408
385
 
409
386
  export function useSelector<T = any, A = any>(
410
387
  selector: (state: DataSheetStore<T>) => A,
411
388
  ): A {
412
- const store = useStoreAPI<T>();
413
- return useStore(store, selector);
389
+ return useZustandSelector<T, A>(ctx, selector);
414
390
  }
415
391
  /** Atoms for efficient sub-selection of state */
416
392
 
@@ -152,6 +152,37 @@ export function resolveInteractionOptions(
152
152
  };
153
153
  }
154
154
 
155
+ /**
156
+ * Whether **modal** selection is currently switched on.
157
+ *
158
+ * This is *runtime view state*, not configuration, so it lives in its own atom
159
+ * rather than inside `interactionOptionsAtom`: the latter is re-synced from the
160
+ * view's props (`resolveInteractionOptions` builds a fresh object on every
161
+ * render of the provider), so a runtime override stored there is reset by any
162
+ * provider re-render that happens to fire. Keeping the flag separate makes
163
+ * select mode stable, and gives consumers a single, safe thing to read and set.
164
+ */
165
+ export const selectionModeActiveAtom = atom(false);
166
+
167
+ /**
168
+ * The effective "is selection live right now" flag — the one every selection
169
+ * path should read. For a modal view it follows {@link selectionModeActiveAtom};
170
+ * otherwise it's the configured `enableSelection`.
171
+ */
172
+ export const enableSelectionAtom = atom(
173
+ (get) => {
174
+ const options = get(interactionOptionsAtom);
175
+ if (options.enableModalSelection) return get(selectionModeActiveAtom);
176
+ return options.enableSelection;
177
+ },
178
+ (get, set, next: boolean) => {
179
+ /** Turn selection on/off. Only meaningful for a modal view; a view with a
180
+ * fixed selection style ignores it. */
181
+ if (!get(interactionOptionsAtom).enableModalSelection) return;
182
+ set(selectionModeActiveAtom, next);
183
+ },
184
+ );
185
+
155
186
  export const enableDragValueAtom = atom((get) => {
156
187
  return get(interactionOptionsAtom).enableDragValue;
157
188
  });
@@ -1,5 +1,5 @@
1
1
  import { atom } from "jotai";
2
- import { interactionOptionsAtom } from "./interactions.ts";
2
+ import { enableSelectionAtom } from "./interactions.ts";
3
3
  import { storeAtom } from "./core.ts";
4
4
  import type { Region } from "@blueprintjs/table";
5
5
 
@@ -11,12 +11,12 @@ export const anchorRefAtom = atom<{ current: number | null }>({
11
11
 
12
12
  export const selectionAtom = atom(
13
13
  (get) => {
14
- if (!get(interactionOptionsAtom).enableSelection) return [];
14
+ if (!get(enableSelectionAtom)) return [];
15
15
  return get(storeAtom)?.selection ?? [];
16
16
  },
17
17
  (get, set, regions: Region[] = []) => {
18
18
  /** Don't do anything if selection isn't enabled */
19
- if (!get(interactionOptionsAtom).enableSelection) return;
19
+ if (!get(enableSelectionAtom)) return;
20
20
  /** Reset the selection anchor ref */
21
21
  if (regions.length === 0) {
22
22
  get(anchorRefAtom).current = null;
@@ -431,7 +431,7 @@ export function createZustandStore<T>(set, get): DataSheetStoreMain<T> {
431
431
  state.activeFilters,
432
432
  );
433
433
  newFilters.set(filterId, { filter, state: filterState });
434
- return { activeFilters: newFilters };
434
+ return { activeFilters: newFilters, ...dropRowSelection(state) };
435
435
  });
436
436
  },
437
437
  removeFilter(filterId: string) {
@@ -440,12 +440,13 @@ export function createZustandStore<T>(set, get): DataSheetStoreMain<T> {
440
440
  state.activeFilters,
441
441
  );
442
442
  newFilters.delete(filterId);
443
- return { activeFilters: newFilters };
443
+ return { activeFilters: newFilters, ...dropRowSelection(state) };
444
444
  });
445
445
  },
446
446
  clearFilters() {
447
- set(() => ({
447
+ set((state) => ({
448
448
  activeFilters: new Map<string, { filter: any; state: any }>(),
449
+ ...dropRowSelection(state),
449
450
  }));
450
451
  },
451
452
  setColumnSort(key: string, ascending: boolean | null) {
@@ -457,11 +458,11 @@ export function createZustandStore<T>(set, get): DataSheetStoreMain<T> {
457
458
  const without = state.columnSorts.filter((s) => s.key !== key);
458
459
  newSorts = [...without, { key, ascending }];
459
460
  }
460
- return { columnSorts: newSorts };
461
+ return { columnSorts: newSorts, ...dropRowSelection(state) };
461
462
  });
462
463
  },
463
464
  clearColumnSorts() {
464
- set(() => ({ columnSorts: [] }));
465
+ set((state) => ({ columnSorts: [], ...dropRowSelection(state) }));
465
466
  },
466
467
  setClipboardProxy(proxy) {
467
468
  set({ clipboardProxy: proxy });
@@ -469,6 +470,23 @@ export function createZustandStore<T>(set, get): DataSheetStoreMain<T> {
469
470
  };
470
471
  }
471
472
 
473
+ /**
474
+ * Drop the parts of a selection that are addressed by **row index**, because a
475
+ * filter or sort change re-orders and re-filters the rows underneath them —
476
+ * "rows 3–5" then means different records, and a set-action would silently act
477
+ * on the wrong ones. Column selections are index-stable under a view change, so
478
+ * they survive (and must: the sheet's sort/filter controls are themselves
479
+ * column-scoped, and are invoked *from* that selection).
480
+ */
481
+ function dropRowSelection<T>(
482
+ state: DataSheetState<T>,
483
+ ): Partial<DataSheetState<T>> {
484
+ const selection = state.selection ?? [];
485
+ const kept = selection.filter((region) => region.rows == null);
486
+ if (kept.length === selection.length) return {};
487
+ return { selection: kept, focusedCell: null, topLeftCell: null };
488
+ }
489
+
472
490
  export function updateSelection<T>(selection: Region[]) {
473
491
  const focusedCell = singleFocusedCell(selection);
474
492
  let spec: Partial<DataSheetState<T>> = {
package/src/types.ts CHANGED
@@ -18,6 +18,10 @@ export type FetchMode = "scroll" | "paged";
18
18
  export interface FetchDataOptions {
19
19
  pageSize?: number;
20
20
  fetchMode?: FetchMode;
21
+ /** Debounce (ms) applied to view-state → refetch, so rapid changes (typing a
22
+ * text filter) collapse into one fetch once the view settles. The input stays
23
+ * instant; only the fetch waits. `0` (default) keeps immediate refetching. */
24
+ filterDebounce?: number;
21
25
  }
22
26
 
23
27
  /** Props shared between the wrapper components and the provider */