@macrostrat/data-sheet 4.6.0 → 4.8.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 (50) hide show
  1. package/CHANGELOG.md +24 -0
  2. package/dist/data-panel.cjs +36 -0
  3. package/dist/data-panel.cjs.map +1 -1
  4. package/dist/data-panel.d.ts +4 -2
  5. package/dist/data-panel.js +37 -1
  6. package/dist/data-panel.js.map +1 -1
  7. package/dist/data-panel.module.sass.cjs +28 -26
  8. package/dist/data-panel.module.sass.cjs.map +1 -1
  9. package/dist/data-panel.module.sass.js +28 -26
  10. package/dist/data-panel.module.sass.js.map +1 -1
  11. package/dist/data-sheet.css +59 -36
  12. package/dist/data-sheet.d.ts +3 -1
  13. package/dist/data-view.d.ts +2 -0
  14. package/dist/index.cjs +1 -0
  15. package/dist/index.cjs.map +1 -1
  16. package/dist/index.js +2 -1
  17. package/dist/postgrest-table/data-loaders.cjs +24 -27
  18. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  19. package/dist/postgrest-table/data-loaders.js +20 -23
  20. package/dist/postgrest-table/data-loaders.js.map +1 -1
  21. package/dist/provider/core.cjs +35 -6
  22. package/dist/provider/core.cjs.map +1 -1
  23. package/dist/provider/core.d.ts +1 -1
  24. package/dist/provider/core.js +35 -6
  25. package/dist/provider/core.js.map +1 -1
  26. package/dist/provider/loader-state.cjs +55 -0
  27. package/dist/provider/loader-state.cjs.map +1 -0
  28. package/dist/provider/loader-state.d.ts +40 -0
  29. package/dist/provider/loader-state.js +55 -0
  30. package/dist/provider/loader-state.js.map +1 -0
  31. package/dist/provider/table-data.cjs +10 -1
  32. package/dist/provider/table-data.cjs.map +1 -1
  33. package/dist/provider/table-data.d.ts +10 -0
  34. package/dist/provider/table-data.js +11 -2
  35. package/dist/provider/table-data.js.map +1 -1
  36. package/dist/provider/types.cjs.map +1 -1
  37. package/dist/provider/types.d.ts +8 -1
  38. package/dist/provider/types.js.map +1 -1
  39. package/dist/types.cjs.map +1 -1
  40. package/dist/types.d.ts +25 -0
  41. package/dist/types.js.map +1 -1
  42. package/package.json +1 -1
  43. package/src/data-panel.module.sass +25 -0
  44. package/src/data-panel.ts +50 -1
  45. package/src/postgrest-table/data-loaders.ts +35 -41
  46. package/src/provider/core.ts +65 -6
  47. package/src/provider/loader-state.ts +95 -0
  48. package/src/provider/table-data.ts +23 -1
  49. package/src/provider/types.ts +8 -1
  50. package/src/types.ts +26 -0
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@macrostrat/data-sheet",
3
- "version": "4.6.0",
3
+ "version": "4.8.0",
4
4
  "description": "Scalable data sheet with optional editing capabilities",
5
5
  "repository": {
6
6
  "type": "git",
@@ -65,6 +65,31 @@
65
65
  align-items: center
66
66
  justify-content: center
67
67
 
68
+ // Crawlable next-page link: in the HTML for crawlers, out of the way for
69
+ // readers. Visually hidden rather than `display: none`, which crawlers may
70
+ // discount.
71
+ .crawl-next-link
72
+ position: absolute
73
+ width: 1px
74
+ height: 1px
75
+ overflow: hidden
76
+ clip-path: inset(50%)
77
+ white-space: nowrap
78
+
79
+ // Heads the content while the view starts mid-list (a `?after=` page).
80
+ .view-start-notice
81
+ flex: 0 0 auto
82
+ display: flex
83
+ align-items: center
84
+ justify-content: space-between
85
+ gap: var(--data-panel-item-gap, 8px)
86
+ padding: 6px 12px
87
+ margin-bottom: var(--data-panel-item-gap, 8px)
88
+ border-radius: 4px
89
+ background: var(--panel-background-color, rgba(128, 128, 128, 0.08))
90
+ color: var(--text-subtle, #738091)
91
+ font-size: 13px
92
+
68
93
  // Skeleton placeholder shown where a loading page's rows will land — sized like
69
94
  // a card so the body height stays stable (no blank flash, no footer ping). The
70
95
  // shimmer comes from Blueprint's `.bp6-skeleton`.
package/src/data-panel.ts CHANGED
@@ -35,7 +35,14 @@ import {
35
35
  useRef,
36
36
  useState,
37
37
  } from "react";
38
- import { Classes, Icon, NonIdealState, Spinner } from "@blueprintjs/core";
38
+ import {
39
+ AnchorButton,
40
+ Classes,
41
+ Icon,
42
+ NonIdealState,
43
+ Spinner,
44
+ } from "@blueprintjs/core";
45
+ import { startAfterAtom } from "./provider/loader-state.ts";
39
46
  import {
40
47
  anchorRefAtom,
41
48
  ctx,
@@ -205,6 +212,7 @@ export function DataPanelRenderer<T>({
205
212
  contentFooter,
206
213
  autoLoadPages,
207
214
  scrollBody,
215
+ pageLinks,
208
216
  className,
209
217
  toolbarStyle = DataPanelToolbarStyle.BORDERED,
210
218
  viewControls = "inline",
@@ -412,6 +420,45 @@ export function DataPanelRenderer<T>({
412
420
  contentFooter ?? defaultFooter,
413
421
  );
414
422
 
423
+ // Crawlable paging (see `PageLinks`). Both are plain links, so they work in
424
+ // the server-rendered HTML with no script: the next-page link is visually
425
+ // hidden after the loaded rows and points past the last loaded row; the
426
+ // "Return to top" notice heads the content while the view starts mid-list.
427
+ const startAfter = ctx.useValue(startAfterAtom);
428
+ const lastLoadedRow = useMemo(() => {
429
+ for (let i = data.length - 1; i >= 0; i--) {
430
+ if (data[i] != null) return data[i];
431
+ }
432
+ return null;
433
+ }, [data]);
434
+ // Gated on the counts rather than `hasMore`, which reads the resolved
435
+ // provider — synced after mount, so absent in a server render.
436
+ const moreToCome = total == null || loadedCount < total;
437
+ let nextPageLink: ReactNode = null;
438
+ if (pageLinks != null && lastLoadedRow != null && moreToCome) {
439
+ nextPageLink = h(
440
+ "a.crawl-next-link",
441
+ {
442
+ href: pageLinks.after(lastLoadedRow),
443
+ rel: "next",
444
+ tabIndex: -1,
445
+ "aria-hidden": true,
446
+ },
447
+ "Next page",
448
+ );
449
+ }
450
+ let viewStartNotice: ReactNode = null;
451
+ if (startAfter != null && pageLinks?.top != null) {
452
+ viewStartNotice = h("div.view-start-notice", [
453
+ h("span.view-start-text", `Continued after #${startAfter}`),
454
+ h(
455
+ AnchorButton,
456
+ { href: pageLinks.top, minimal: true, small: true, icon: "arrow-up" },
457
+ pageLinks.topLabel ?? "Return to top",
458
+ ),
459
+ ]);
460
+ }
461
+
415
462
  // Body + optional filter/detail sidebar share a horizontal row so each
416
463
  // scrolls independently.
417
464
 
@@ -461,7 +508,9 @@ export function DataPanelRenderer<T>({
461
508
  },
462
509
  [
463
510
  h("div.data-panel-body-content", [
511
+ viewStartNotice,
464
512
  emptyState ?? h(ScrollBody, { placeholders }, cards),
513
+ nextPageLink,
465
514
  _contentFooter,
466
515
  ]),
467
516
  ],
@@ -22,19 +22,14 @@ import {
22
22
  useSelector,
23
23
  } from "../provider";
24
24
  import { atom } from "jotai";
25
- import { FetchDataOptions, FetchMode, InitialDataChunk } from "../types.ts";
26
-
27
- interface LazyLoaderStateCore<T> {
28
- loading: boolean;
29
- error: Error | null;
30
- initialized: boolean;
31
- /** Reported source length when known (null = unknown / not reported). */
32
- totalCount: number | null;
33
- /** Windowing style: infinite-scroll windows, or one fixed page at a time. */
34
- fetchMode: FetchMode;
35
- /** Rows per chunk/page. */
36
- pageSize: number;
37
- }
25
+ import { FetchDataOptions, FetchMode } from "../types.ts";
26
+ import {
27
+ lazyLoaderCoreStateAtom,
28
+ resolveInitialData,
29
+ seededRows,
30
+ startAfterAtom,
31
+ type LazyLoaderStateCore,
32
+ } from "../provider/loader-state.ts";
38
33
 
39
34
  interface LazyLoaderState<T> extends LazyLoaderStateCore<T> {
40
35
  data: (T | null)[];
@@ -205,10 +200,10 @@ function lazyLoadingReducer<T>(
205
200
  // completed first fetch: pre-size to the reported total so the scrollbar
206
201
  // and counter are right immediately, and mark the loader `initialized` so
207
202
  // it neither refetches the seeded window nor flashes an empty state.
208
- const rows = action.data ?? [];
209
- const size = Math.max(action.totalCount ?? rows.length, rows.length);
210
- const data: (T | null)[] = new Array(size).fill(null);
211
- for (let i = 0; i < rows.length; i++) data[i] = rows[i];
203
+ const data = seededRows({
204
+ rows: action.data ?? [],
205
+ totalCount: action.totalCount,
206
+ });
212
207
  return {
213
208
  visibleRegion: defaultVisibleRegion,
214
209
  data: data as T[],
@@ -373,14 +368,6 @@ const defaultVisibleRegion: RowRegion = {
373
368
  /** Atom to house the current visible region of the table */
374
369
  const visibleRegionAtom = atom<RowRegion>(defaultVisibleRegion);
375
370
 
376
- const lazyLoaderCoreStateAtom = atom<LazyLoaderStateCore<any>>({
377
- loading: false,
378
- error: null,
379
- initialized: false,
380
- totalCount: null,
381
- fetchMode: "scroll",
382
- pageSize: 100,
383
- });
384
371
 
385
372
  /** Current page index (0-based) for paged fetch mode. */
386
373
  export const chunkPageAtom = atom(0);
@@ -691,6 +678,10 @@ export function useDataLoader<T = any>(
691
678
  const page = ctx.useValue(chunkPageAtom);
692
679
  const setPage = ctx.useSet(chunkPageAtom);
693
680
  const refreshToken = ctx.useValue(dataRefreshTokenAtom);
681
+ // The keyset cursor of a view that starts mid-list. Seeded at store creation
682
+ // (`startAfter`); cleared below on the first view change, since it describes
683
+ // only the view it arrived with.
684
+ const [startAfter, setStartAfter] = ctx.use(startAfterAtom);
694
685
  const columnSorts = useSelector((s) => s.columnSorts);
695
686
  const activeFilters = useSelector((s) => s.activeFilters);
696
687
  const abortRef = useRef<AbortController | null>(null);
@@ -736,14 +727,31 @@ export function useDataLoader<T = any>(
736
727
  // A caller-supplied first window (`initialData`) stands in for the mount-time
737
728
  // reset+fetch. It's consumed once: any later view change resets normally,
738
729
  // since the seed only describes the view it was fetched for.
730
+ //
731
+ // The store is normally created already seeded (`DataSheetStoreWrapper`), so
732
+ // the rows are in the very first render — including a server render. The
733
+ // dispatch below is the fallback for a store that wasn't.
739
734
  const seedRef = useRef(resolveInitialData(initialData));
740
735
  // Gate on the seed until it's actually in state (see the fetch effect).
741
736
  const awaitingSeedRef = useRef(seedRef.current != null);
737
+ const firstResetRef = useRef(true);
742
738
  useEffect(() => {
743
739
  const seed = seedRef.current;
744
740
  seedRef.current = null;
741
+ // A view change (not the mount) ends a mid-list start: the cursor only
742
+ // described the view it arrived with.
743
+ if (!firstResetRef.current) {
744
+ setStartAfter(null);
745
+ }
746
+ firstResetRef.current = false;
745
747
  if (seed != null) {
746
- dispatch({ type: "seed", data: seed.rows, totalCount: seed.totalCount });
748
+ if (!state.initialized) {
749
+ dispatch({
750
+ type: "seed",
751
+ data: seed.rows,
752
+ totalCount: seed.totalCount,
753
+ });
754
+ }
747
755
  setPage(0);
748
756
  // Paged mode tracks which (page, view) it has in hand separately from the
749
757
  // array; record the seed there too, or it would immediately re-fetch the
@@ -802,6 +810,7 @@ export function useDataLoader<T = any>(
802
810
  sorts: columnSorts,
803
811
  filters,
804
812
  cursor,
813
+ after: startAfter,
805
814
  });
806
815
  if (controller.signal.aborted) return;
807
816
  const rows = result.rows ?? [];
@@ -854,21 +863,6 @@ export function useDataLoader<T = any>(
854
863
 
855
864
  /** A value that trails `value` by `delay` ms of stability — the first value is
856
865
  * returned immediately, and `delay <= 0` disables debouncing entirely. */
857
- /** Normalize the two accepted `initialData` shapes (bare rows, or rows with a
858
- * total) to one. An empty seed is treated as no seed — there'd be nothing to
859
- * show and nothing saved. */
860
- function resolveInitialData<T>(
861
- initialData: FetchDataOptions<T>["initialData"],
862
- ): InitialDataChunk<T> | null {
863
- if (initialData == null) return null;
864
- if (Array.isArray(initialData)) {
865
- if (initialData.length === 0) return null;
866
- return { rows: initialData };
867
- }
868
- if ((initialData.rows ?? []).length === 0) return null;
869
- return initialData;
870
- }
871
-
872
866
  function useDebouncedValue<T>(value: T, delay: number): T {
873
867
  const [debounced, setDebounced] = useState(value);
874
868
  useEffect(() => {
@@ -41,7 +41,16 @@ import {
41
41
  resolveInteractionOptions,
42
42
  } from "./interactions.ts";
43
43
  import { DataViewProps } from "../data-view.ts";
44
- import { DataSheetProps, DataViewCoreProps } from "../types.ts";
44
+ import {
45
+ DataSheetProps,
46
+ DataViewCoreProps,
47
+ InitialDataChunk,
48
+ } from "../types.ts";
49
+ import {
50
+ loaderSeedAtoms,
51
+ resolveInitialData,
52
+ seededRows,
53
+ } from "./loader-state.ts";
45
54
  import { DataPanelProps } from "../data-panel.ts";
46
55
 
47
56
  /** Create a Jotai scoped store */
@@ -153,16 +162,30 @@ export function useResolvedProvider<T>(props: {
153
162
  }
154
163
 
155
164
  function DataSheetStoreWrapper<T>(props: DataSheetProviderProps<T>) {
156
- const { toaster, initialFilters, initialSorts, ...rest } = props;
165
+ const {
166
+ toaster,
167
+ initialFilters,
168
+ initialSorts,
169
+ initialData,
170
+ startAfter,
171
+ ...rest
172
+ } = props;
157
173
 
158
174
  // Initial view state is folded into the store's *creation*, not applied in an
159
175
  // effect: the loader mounts below this and its effects run first, so an
160
176
  // effect-applied filter would arrive after the first (unfiltered) fetch had
161
177
  // already gone out — and be immediately superseded. Creating the store with
162
178
  // the view already set means the first fetch is the right one.
179
+ //
180
+ // A seeded first window (`initialData`) is folded in the same way, for the
181
+ // same reason and one more: rows placed at creation are in the first render,
182
+ // so a server render carries them instead of the empty state the loader
183
+ // shows until its first (asynchronous) page resolves.
184
+ const seed = resolveInitialData(initialData);
163
185
  const initializeStore = (set: any, get: any) => ({
164
186
  ...createZustandStore<T>(set, get),
165
187
  ...initialViewState({ initialFilters, initialSorts }),
188
+ ...initialDataState(seed),
166
189
  });
167
190
 
168
191
  return h(
@@ -170,13 +193,24 @@ function DataSheetStoreWrapper<T>(props: DataSheetProviderProps<T>) {
170
193
  {
171
194
  ctx,
172
195
  initializeStore,
173
- atoms: [[toasterAtom, toaster]],
196
+ atoms: [
197
+ [toasterAtom, toaster],
198
+ ...loaderSeedAtoms(initialData, startAfter),
199
+ ],
174
200
  debugName: "DataSheetProvider",
175
201
  },
176
202
  h(DataSheetProviderInner, rest),
177
203
  );
178
204
  }
179
205
 
206
+ /** The store's `data` for a seeded first window; nothing without a seed. */
207
+ function initialDataState<T>(
208
+ seed: InitialDataChunk<T> | null,
209
+ ): Partial<DataSheetState<T>> {
210
+ if (seed == null) return {};
211
+ return { data: seededRows(seed) as T[] };
212
+ }
213
+
180
214
  /** The store fields that carry a caller-supplied starting view. Absent props
181
215
  * contribute nothing, so the store's own defaults stand. */
182
216
  function initialViewState<T>({
@@ -225,12 +259,29 @@ type AnyDataSheetProps<T> =
225
259
 
226
260
  export function splitDataProviderProps<T>(props: AnyDataSheetProps<T>) {
227
261
  /** Split provided props based on provider's needs */
228
- return splitProps<AnyDataSheetProps<T>, DataSheetProviderProps<T>>(
262
+ const [providerProps, rendererProps] = splitProps<
263
+ AnyDataSheetProps<T>,
264
+ DataSheetProviderProps<T>
265
+ >(
229
266
  props,
230
267
  dataProviderKeys
231
268
  .union(interactionOptionsKeys)
232
269
  .union(tableDataProviderKeys) as Set<keyof DataSheetProviderProps<T>>,
233
270
  );
271
+ // `initialData` and `startAfter` go to both sides: the provider creates the
272
+ // store seeded with them, and the loader takes them as the first window it
273
+ // needn't fetch and the cursor its chunks are counted from.
274
+ const { initialData, startAfter } = props as {
275
+ initialData?: any;
276
+ startAfter?: string | number | null;
277
+ };
278
+ if (initialData != null) {
279
+ providerProps.initialData = initialData;
280
+ }
281
+ if (startAfter != null) {
282
+ providerProps.startAfter = startAfter;
283
+ }
284
+ return [providerProps, rendererProps] as const;
234
285
  }
235
286
 
236
287
  export function DataSheetProvider<T>(
@@ -272,7 +323,8 @@ export function DataSheetProviderInner<T>(
272
323
  identity,
273
324
  } = providerProps;
274
325
 
275
- const { data, dataProvider } = useResolvedProvider<T>(providerProps);
326
+ const { data, dataProvider, isLocalProvider } =
327
+ useResolvedProvider<T>(providerProps);
276
328
 
277
329
  const initializeStore = ctx.useSet(initializeStoreAtom);
278
330
  const storeAPI = useStoreAPI<T>();
@@ -303,7 +355,15 @@ export function DataSheetProviderInner<T>(
303
355
  const baseSpec = staticSpec ?? generateColumnSpec(data, columnSpecOptions);
304
356
 
305
357
  useEffect(() => {
358
+ // The store's `data` is the loader's for any fetched source (and may hold a
359
+ // seeded first window from creation); only an in-memory `data` prop is
360
+ // placed here.
361
+ let localRows: Partial<DataSheetStore<T>> = {};
362
+ if (isLocalProvider) {
363
+ localRows = { data };
364
+ }
306
365
  initializeStore({
366
+ ...localRows,
307
367
  columnSpec: postprocessColumnSpec(baseSpec),
308
368
  // Suppress the loader's first-chunk auto-generation whenever the consumer
309
369
  // provided a spec at all — a function (derived later in `_DataSheet`) OR
@@ -314,7 +374,6 @@ export function DataSheetProviderInner<T>(
314
374
  deferColumnSpec: columnSpec != null,
315
375
  editable: interactionOptions.enableEditing,
316
376
  enableColumnReordering,
317
- data,
318
377
  defaultColumnWidth,
319
378
  tableRef,
320
379
  });
@@ -0,0 +1,95 @@
1
+ /** The loader's core state and the seeding of a first window.
2
+ *
3
+ * Kept apart from the loader (`postgrest-table/data-loaders.ts`) so the
4
+ * provider can seed the store at creation without a circular import.
5
+ */
6
+ import { atom } from "jotai";
7
+ import type { AtomMap } from "@macrostrat/scoped-store";
8
+ import type { FetchDataOptions, FetchMode, InitialDataChunk } from "../types.ts";
9
+
10
+ export interface LazyLoaderStateCore<T> {
11
+ loading: boolean;
12
+ error: Error | null;
13
+ initialized: boolean;
14
+ /** Reported source length when known (null = unknown / not reported). */
15
+ totalCount: number | null;
16
+ /** Windowing style: infinite-scroll windows, or one fixed page at a time. */
17
+ fetchMode: FetchMode;
18
+ /** Rows per chunk/page. */
19
+ pageSize: number;
20
+ }
21
+
22
+ export const DEFAULT_LOADER_CORE: LazyLoaderStateCore<any> = {
23
+ loading: false,
24
+ error: null,
25
+ initialized: false,
26
+ totalCount: null,
27
+ fetchMode: "scroll",
28
+ pageSize: 100,
29
+ };
30
+
31
+ export const lazyLoaderCoreStateAtom =
32
+ atom<LazyLoaderStateCore<any>>(DEFAULT_LOADER_CORE);
33
+
34
+ /** Normalize the two accepted `initialData` shapes (bare rows, or rows with a
35
+ * total) to one. An empty seed is treated as no seed — there'd be nothing to
36
+ * show and nothing saved. */
37
+ export function resolveInitialData<T>(
38
+ initialData: FetchDataOptions<T>["initialData"],
39
+ ): InitialDataChunk<T> | null {
40
+ if (initialData == null) return null;
41
+ if (Array.isArray(initialData)) {
42
+ if (initialData.length === 0) return null;
43
+ return { rows: initialData };
44
+ }
45
+ if ((initialData.rows ?? []).length === 0) return null;
46
+ return initialData;
47
+ }
48
+
49
+ /** The data array for a seeded first window: the rows in place, pre-sized to
50
+ * the reported total (with `null` for the rows not yet loaded) so the scrollbar
51
+ * and the counter are right immediately. */
52
+ export function seededRows<T>(seed: InitialDataChunk<T>): (T | null)[] {
53
+ const rows = seed.rows ?? [];
54
+ const size = Math.max(seed.totalCount ?? rows.length, rows.length);
55
+ const data: (T | null)[] = new Array(size).fill(null);
56
+ for (let i = 0; i < rows.length; i++) data[i] = rows[i];
57
+ return data;
58
+ }
59
+
60
+ /** The loader's core state for a seeded first window — the same shape as after
61
+ * a completed first fetch. `initialized` means the loader neither refetches the
62
+ * seeded window nor shows an empty state. */
63
+ export function seededLoaderCore<T>(
64
+ seed: InitialDataChunk<T>,
65
+ ): LazyLoaderStateCore<T> {
66
+ return {
67
+ ...DEFAULT_LOADER_CORE,
68
+ initialized: true,
69
+ totalCount: seed.totalCount ?? null,
70
+ };
71
+ }
72
+
73
+ /** The identity of the row the current view starts after (`startAfter`), or
74
+ * `null` for a view that starts at the top. Set at store creation so a server
75
+ * render shows the "Return to top" link; the loader clears it on the first view
76
+ * change. */
77
+ export const startAfterAtom = atom<string | number | null>(null);
78
+
79
+ /** Scoped-store atoms that make a store start out seeded. The store's own
80
+ * `data` is seeded alongside (see `DataSheetStoreWrapper`). Empty when there is
81
+ * no seed. */
82
+ export function loaderSeedAtoms<T>(
83
+ initialData: FetchDataOptions<T>["initialData"],
84
+ startAfter: FetchDataOptions<T>["startAfter"] = null,
85
+ ): AtomMap {
86
+ const atoms: AtomMap = [];
87
+ if (startAfter != null) {
88
+ atoms.push([startAfterAtom, startAfter]);
89
+ }
90
+ const seed = resolveInitialData(initialData);
91
+ if (seed != null) {
92
+ atoms.push([lazyLoaderCoreStateAtom, seededLoaderCore(seed)]);
93
+ }
94
+ return atoms;
95
+ }
@@ -32,6 +32,12 @@ export interface FetchDataParams {
32
32
  * sources can page from this cursor (e.g. `WHERE key > cursor`) instead of a
33
33
  * slow `OFFSET`; offset-based sources can ignore it. */
34
34
  cursor?: { row: any; index: number } | null;
35
+ /** Identity of the row the view is counted from: `offset` 0 is the first
36
+ * row *after* it. Set while a view starts mid-list (see `startAfter` in
37
+ * `FetchDataOptions`); absent or `null` when it starts at the top. Keyset
38
+ * sources translate it to `WHERE key > after`; the local provider slices past
39
+ * the row. `totalCount` then reports the rows after it. */
40
+ after?: string | number | null;
35
41
  }
36
42
 
37
43
  /** Result of a `fetchChunk` call. `totalCount` reports the source length when
@@ -125,7 +131,7 @@ export function createLocalProvider<T = any>(
125
131
 
126
132
  return {
127
133
  identity,
128
- async fetchData({ offset, limit, sorts, filters }) {
134
+ async fetchData({ offset, limit, sorts, filters, after }) {
129
135
  let rows = data;
130
136
  if (filters != null && filters.length > 0) {
131
137
  rows = rows.filter((row) =>
@@ -137,6 +143,7 @@ export function createLocalProvider<T = any>(
137
143
  if (sorts != null && sorts.length > 0) {
138
144
  rows = [...rows].sort(compareRowsBySorts(sorts));
139
145
  }
146
+ rows = rowsAfter(rows, after, identity);
140
147
  return {
141
148
  rows: rows.slice(offset, offset + limit),
142
149
  totalCount: rows.length,
@@ -148,6 +155,21 @@ export function createLocalProvider<T = any>(
148
155
  };
149
156
  }
150
157
 
158
+ /** The rows past the one with identity `after` in the (filtered, sorted) view;
159
+ * the whole view when `after` is absent or names no row. Identities are compared
160
+ * as strings, since a cursor read from a URL arrives as one. */
161
+ export function rowsAfter<T>(
162
+ rows: T[],
163
+ after: string | number | null | undefined,
164
+ identity: (row: T) => string | number | null | undefined,
165
+ ): T[] {
166
+ if (after == null) return rows;
167
+ const key = String(after);
168
+ const index = rows.findIndex((row) => String(identity(row)) === key);
169
+ if (index < 0) return rows;
170
+ return rows.slice(index + 1);
171
+ }
172
+
151
173
  // Stable synthetic identity for in-memory rows lacking a natural `id`. Keyed by
152
174
  // object reference (a local data array keeps the same row objects across
153
175
  // re-sorts), so edits survive re-ordering even without an id field.
@@ -6,7 +6,7 @@ import type {
6
6
  } from "@blueprintjs/table";
7
7
  import type { ColumnSpec, ColumnSpecOptions } from "./column-spec";
8
8
  import { OverlayToaster } from "@blueprintjs/core";
9
- import { DataViewCoreProps } from "../types";
9
+ import { DataViewCoreProps, FetchDataOptions } from "../types";
10
10
  import { DataViewRendererType } from "./interactions.ts";
11
11
 
12
12
  /** A single column sort entry for client-side sorting.
@@ -251,6 +251,13 @@ export interface DataSheetStoreMain<T> extends DataSheetVals<T> {
251
251
 
252
252
  export type DataSheetProviderProps<T> = DataViewCoreProps<T> & {
253
253
  toaster?: OverlayToaster;
254
+ /** A first window of rows the caller already has (see `FetchDataOptions`).
255
+ * The provider creates the store seeded with it, so the rows are in the very
256
+ * first render — a server render included. */
257
+ initialData?: FetchDataOptions<T>["initialData"];
258
+ /** The row the view starts after (see `FetchDataOptions`). Seeded into the
259
+ * store at creation alongside `initialData`. */
260
+ startAfter?: FetchDataOptions<T>["startAfter"];
254
261
  viewType?: DataViewRendererType;
255
262
  children?: React.ReactNode;
256
263
  };
package/src/types.ts CHANGED
@@ -39,6 +39,14 @@ export interface FetchDataOptions<T = any> {
39
39
  * Pass `totalCount` when it's known — the array is pre-sized to it, so the
40
40
  * scrollbar and the counter are right from the first paint. */
41
41
  initialData?: T[] | InitialDataChunk<T>;
42
+ /** Identity of the row the view starts after — the keyset cursor of a view
43
+ * that begins mid-list, as reached through a page link (`?after=<id>`). It is
44
+ * passed to the provider as `after` on every chunk of the view it was created
45
+ * for, and dropped on the first view change (sorts, filters, a refresh), since
46
+ * it only describes that view. Read from the URL when the page loads; the
47
+ * client never writes it back while scrolling. Pair it with an `initialData`
48
+ * seed of the rows after it for a complete server render. */
49
+ startAfter?: string | number | null;
42
50
  /** Debounce (ms) applied to view-state → refetch, so rapid changes (typing a
43
51
  * text filter) collapse into one fetch once the view settles. The input stays
44
52
  * instant; only the fetch waits. `0` (default) keeps immediate refetching. */
@@ -88,8 +96,26 @@ export interface DataViewCoreProps<T> extends InteractionOptions {
88
96
  initialSorts?: ColumnSort[];
89
97
  }
90
98
 
99
+ /** Links that make a paged view reachable without JavaScript. */
100
+ export interface PageLinks<T = any> {
101
+ /** The href of the view that starts after `row` (`?after=<id>`). Rendered as
102
+ * a visually hidden `rel="next"` link after the loaded rows, so a crawler
103
+ * following the server-rendered HTML reaches every page of the list while
104
+ * readers keep the infinite scroll. */
105
+ after: (row: T) => string;
106
+ /** The href of the view's first page. Shown as a "Return to top" link at the
107
+ * head of the content while the view starts mid-list (`startAfter`). */
108
+ top?: string;
109
+ /** Label for that link (default "Return to top"). */
110
+ topLabel?: ReactNode;
111
+ }
112
+
91
113
  export interface DataViewSharedProps<T = any>
92
114
  extends FetchDataOptions<T>, DataViewCoreProps<T> {
115
+ /** Crawlable page links (see `PageLinks`). Neither link is written to the
116
+ * browser's URL as the list is scrolled — deep pages are for crawlers and
117
+ * for whoever follows such a link, not a state the page keeps. */
118
+ pageLinks?: PageLinks<T>;
93
119
  /** Configurable table actions shown in a selection-aware toolbar.
94
120
  * When provided, the actions toolbar renders alongside the existing
95
121
  * edit toolbar. Actions are filtered by the current selection cardinality. */