@macrostrat/data-sheet 4.6.0 → 4.7.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.
@@ -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,23 @@ 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 { toaster, initialFilters, initialSorts, initialData, ...rest } = props;
157
166
 
158
167
  // Initial view state is folded into the store's *creation*, not applied in an
159
168
  // effect: the loader mounts below this and its effects run first, so an
160
169
  // effect-applied filter would arrive after the first (unfiltered) fetch had
161
170
  // already gone out — and be immediately superseded. Creating the store with
162
171
  // the view already set means the first fetch is the right one.
172
+ //
173
+ // A seeded first window (`initialData`) is folded in the same way, for the
174
+ // same reason and one more: rows placed at creation are in the first render,
175
+ // so a server render carries them instead of the empty state the loader
176
+ // shows until its first (asynchronous) page resolves.
177
+ const seed = resolveInitialData(initialData);
163
178
  const initializeStore = (set: any, get: any) => ({
164
179
  ...createZustandStore<T>(set, get),
165
180
  ...initialViewState({ initialFilters, initialSorts }),
181
+ ...initialDataState(seed),
166
182
  });
167
183
 
168
184
  return h(
@@ -170,13 +186,21 @@ function DataSheetStoreWrapper<T>(props: DataSheetProviderProps<T>) {
170
186
  {
171
187
  ctx,
172
188
  initializeStore,
173
- atoms: [[toasterAtom, toaster]],
189
+ atoms: [[toasterAtom, toaster], ...loaderSeedAtoms(initialData)],
174
190
  debugName: "DataSheetProvider",
175
191
  },
176
192
  h(DataSheetProviderInner, rest),
177
193
  );
178
194
  }
179
195
 
196
+ /** The store's `data` for a seeded first window; nothing without a seed. */
197
+ function initialDataState<T>(
198
+ seed: InitialDataChunk<T> | null,
199
+ ): Partial<DataSheetState<T>> {
200
+ if (seed == null) return {};
201
+ return { data: seededRows(seed) as T[] };
202
+ }
203
+
180
204
  /** The store fields that carry a caller-supplied starting view. Absent props
181
205
  * contribute nothing, so the store's own defaults stand. */
182
206
  function initialViewState<T>({
@@ -225,12 +249,22 @@ type AnyDataSheetProps<T> =
225
249
 
226
250
  export function splitDataProviderProps<T>(props: AnyDataSheetProps<T>) {
227
251
  /** Split provided props based on provider's needs */
228
- return splitProps<AnyDataSheetProps<T>, DataSheetProviderProps<T>>(
252
+ const [providerProps, rendererProps] = splitProps<
253
+ AnyDataSheetProps<T>,
254
+ DataSheetProviderProps<T>
255
+ >(
229
256
  props,
230
257
  dataProviderKeys
231
258
  .union(interactionOptionsKeys)
232
259
  .union(tableDataProviderKeys) as Set<keyof DataSheetProviderProps<T>>,
233
260
  );
261
+ // `initialData` goes to both sides: the provider creates the store seeded
262
+ // with it, and the loader takes it as the first window it needn't fetch.
263
+ const initialData = (props as { initialData?: any }).initialData;
264
+ if (initialData != null) {
265
+ providerProps.initialData = initialData;
266
+ }
267
+ return [providerProps, rendererProps] as const;
234
268
  }
235
269
 
236
270
  export function DataSheetProvider<T>(
@@ -272,7 +306,8 @@ export function DataSheetProviderInner<T>(
272
306
  identity,
273
307
  } = providerProps;
274
308
 
275
- const { data, dataProvider } = useResolvedProvider<T>(providerProps);
309
+ const { data, dataProvider, isLocalProvider } =
310
+ useResolvedProvider<T>(providerProps);
276
311
 
277
312
  const initializeStore = ctx.useSet(initializeStoreAtom);
278
313
  const storeAPI = useStoreAPI<T>();
@@ -303,7 +338,15 @@ export function DataSheetProviderInner<T>(
303
338
  const baseSpec = staticSpec ?? generateColumnSpec(data, columnSpecOptions);
304
339
 
305
340
  useEffect(() => {
341
+ // The store's `data` is the loader's for any fetched source (and may hold a
342
+ // seeded first window from creation); only an in-memory `data` prop is
343
+ // placed here.
344
+ let localRows: Partial<DataSheetStore<T>> = {};
345
+ if (isLocalProvider) {
346
+ localRows = { data };
347
+ }
306
348
  initializeStore({
349
+ ...localRows,
307
350
  columnSpec: postprocessColumnSpec(baseSpec),
308
351
  // Suppress the loader's first-chunk auto-generation whenever the consumer
309
352
  // provided a spec at all — a function (derived later in `_DataSheet`) OR
@@ -314,7 +357,6 @@ export function DataSheetProviderInner<T>(
314
357
  deferColumnSpec: columnSpec != null,
315
358
  editable: interactionOptions.enableEditing,
316
359
  enableColumnReordering,
317
- data,
318
360
  defaultColumnWidth,
319
361
  tableRef,
320
362
  });
@@ -0,0 +1,82 @@
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
+ /** Scoped-store atoms that make a store start out seeded. The store's own
74
+ * `data` is seeded alongside (see `DataSheetStoreWrapper`). Empty when there is
75
+ * no seed. */
76
+ export function loaderSeedAtoms<T>(
77
+ initialData: FetchDataOptions<T>["initialData"],
78
+ ): AtomMap {
79
+ const seed = resolveInitialData(initialData);
80
+ if (seed == null) return [];
81
+ return [[lazyLoaderCoreStateAtom, seededLoaderCore(seed)]];
82
+ }
@@ -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,10 @@ 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"];
254
258
  viewType?: DataViewRendererType;
255
259
  children?: React.ReactNode;
256
260
  };