@macrostrat/data-sheet 4.0.0-dev2 → 4.0.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 (212) hide show
  1. package/CHANGELOG.md +66 -0
  2. package/README.md +44 -0
  3. package/dist/actions/builtin.cjs +36 -5
  4. package/dist/actions/builtin.cjs.map +1 -1
  5. package/dist/actions/builtin.d.ts +3 -2
  6. package/dist/actions/builtin.js +36 -5
  7. package/dist/actions/builtin.js.map +1 -1
  8. package/dist/actions/column-controls.cjs +149 -0
  9. package/dist/actions/column-controls.cjs.map +1 -0
  10. package/dist/actions/column-controls.d.ts +11 -0
  11. package/dist/actions/column-controls.js +147 -0
  12. package/dist/actions/column-controls.js.map +1 -0
  13. package/dist/actions/column-filter.cjs +68 -0
  14. package/dist/actions/column-filter.cjs.map +1 -0
  15. package/dist/actions/column-filter.d.ts +11 -0
  16. package/dist/actions/column-filter.js +66 -0
  17. package/dist/actions/column-filter.js.map +1 -0
  18. package/dist/actions/edit-actions.cjs +42 -0
  19. package/dist/actions/edit-actions.cjs.map +1 -0
  20. package/dist/actions/edit-actions.d.ts +14 -0
  21. package/dist/actions/edit-actions.js +42 -0
  22. package/dist/actions/edit-actions.js.map +1 -0
  23. package/dist/actions/filters.cjs +39 -23
  24. package/dist/actions/filters.cjs.map +1 -1
  25. package/dist/actions/filters.d.ts +6 -3
  26. package/dist/actions/filters.js +41 -25
  27. package/dist/actions/filters.js.map +1 -1
  28. package/dist/actions/index.d.ts +4 -0
  29. package/dist/actions/selection.cjs +39 -30
  30. package/dist/actions/selection.cjs.map +1 -1
  31. package/dist/actions/selection.d.ts +3 -7
  32. package/dist/actions/selection.js +39 -30
  33. package/dist/actions/selection.js.map +1 -1
  34. package/dist/actions/table-controls.cjs +41 -0
  35. package/dist/actions/table-controls.cjs.map +1 -0
  36. package/dist/actions/table-controls.d.ts +4 -0
  37. package/dist/actions/table-controls.js +39 -0
  38. package/dist/actions/table-controls.js.map +1 -0
  39. package/dist/actions/toolbar.cjs +69 -10
  40. package/dist/actions/toolbar.cjs.map +1 -1
  41. package/dist/actions/toolbar.d.ts +9 -6
  42. package/dist/actions/toolbar.js +69 -10
  43. package/dist/actions/toolbar.js.map +1 -1
  44. package/dist/actions/toolbar.module.sass.cjs +12 -7
  45. package/dist/actions/toolbar.module.sass.cjs.map +1 -1
  46. package/dist/actions/toolbar.module.sass.js +12 -7
  47. package/dist/actions/toolbar.module.sass.js.map +1 -1
  48. package/dist/actions/types.d.ts +49 -4
  49. package/dist/cell-renderer.cjs +150 -14
  50. package/dist/cell-renderer.cjs.map +1 -1
  51. package/dist/cell-renderer.d.ts +1 -1
  52. package/dist/cell-renderer.js +151 -15
  53. package/dist/cell-renderer.js.map +1 -1
  54. package/dist/components/cell-detail.cjs +24 -0
  55. package/dist/components/cell-detail.cjs.map +1 -0
  56. package/dist/components/cell-detail.d.ts +12 -0
  57. package/dist/components/cell-detail.js +24 -0
  58. package/dist/components/cell-detail.js.map +1 -0
  59. package/dist/components/editor-popup.cjs +28 -24
  60. package/dist/components/editor-popup.cjs.map +1 -1
  61. package/dist/components/editor-popup.js +29 -25
  62. package/dist/components/editor-popup.js.map +1 -1
  63. package/dist/components/index.d.ts +2 -2
  64. package/dist/components/text-areas.cjs +51 -7
  65. package/dist/components/text-areas.cjs.map +1 -1
  66. package/dist/components/text-areas.d.ts +4 -1
  67. package/dist/components/text-areas.js +51 -7
  68. package/dist/components/text-areas.js.map +1 -1
  69. package/dist/components/view-info.cjs +46 -9
  70. package/dist/components/view-info.cjs.map +1 -1
  71. package/dist/components/view-info.d.ts +5 -1
  72. package/dist/components/view-info.js +47 -10
  73. package/dist/components/view-info.js.map +1 -1
  74. package/dist/core.cjs +167 -73
  75. package/dist/core.cjs.map +1 -1
  76. package/dist/core.d.ts +53 -6
  77. package/dist/core.js +169 -75
  78. package/dist/core.js.map +1 -1
  79. package/dist/data-sheet.css +72 -123
  80. package/dist/filters/operators.cjs +91 -0
  81. package/dist/filters/operators.cjs.map +1 -0
  82. package/dist/filters/operators.d.ts +17 -0
  83. package/dist/filters/operators.js +91 -0
  84. package/dist/filters/operators.js.map +1 -0
  85. package/dist/index.cjs +38 -10
  86. package/dist/index.cjs.map +1 -1
  87. package/dist/index.d.ts +2 -0
  88. package/dist/index.js +44 -16
  89. package/dist/index.js.map +1 -1
  90. package/dist/main.module.sass.cjs +13 -12
  91. package/dist/main.module.sass.cjs.map +1 -1
  92. package/dist/main.module.sass.js +13 -12
  93. package/dist/main.module.sass.js.map +1 -1
  94. package/dist/postgrest-table/data-loaders.cjs +255 -146
  95. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  96. package/dist/postgrest-table/data-loaders.d.ts +144 -46
  97. package/dist/postgrest-table/data-loaders.js +259 -150
  98. package/dist/postgrest-table/data-loaders.js.map +1 -1
  99. package/dist/postgrest-table/index.cjs +58 -169
  100. package/dist/postgrest-table/index.cjs.map +1 -1
  101. package/dist/postgrest-table/index.d.ts +5 -2
  102. package/dist/postgrest-table/index.js +63 -174
  103. package/dist/postgrest-table/index.js.map +1 -1
  104. package/dist/postgrest-table/loading-utils.cjs +0 -4
  105. package/dist/postgrest-table/loading-utils.cjs.map +1 -1
  106. package/dist/postgrest-table/loading-utils.js +1 -5
  107. package/dist/postgrest-table/loading-utils.js.map +1 -1
  108. package/dist/postgrest-table/main.module.sass.cjs +14 -13
  109. package/dist/postgrest-table/main.module.sass.cjs.map +1 -1
  110. package/dist/postgrest-table/main.module.sass.js +14 -13
  111. package/dist/postgrest-table/main.module.sass.js.map +1 -1
  112. package/dist/provider.cjs +68 -11
  113. package/dist/provider.cjs.map +1 -1
  114. package/dist/provider.d.ts +25 -0
  115. package/dist/provider.js +68 -11
  116. package/dist/provider.js.map +1 -1
  117. package/dist/renderers/column-header-cell.cjs +95 -75
  118. package/dist/renderers/column-header-cell.cjs.map +1 -1
  119. package/dist/renderers/column-header-cell.d.ts +3 -18
  120. package/dist/renderers/column-header-cell.js +98 -78
  121. package/dist/renderers/column-header-cell.js.map +1 -1
  122. package/dist/renderers/index.d.ts +0 -1
  123. package/dist/types.cjs +2 -0
  124. package/dist/types.cjs.map +1 -1
  125. package/dist/types.d.ts +84 -1
  126. package/dist/types.js +2 -0
  127. package/dist/types.js.map +1 -1
  128. package/dist/utils/column-spec.cjs.map +1 -1
  129. package/dist/utils/column-spec.d.ts +101 -1
  130. package/dist/utils/column-spec.js.map +1 -1
  131. package/dist/utils/debug-overlay.cjs +24 -0
  132. package/dist/utils/debug-overlay.cjs.map +1 -0
  133. package/dist/utils/debug-overlay.d.ts +4 -0
  134. package/dist/utils/debug-overlay.js +24 -0
  135. package/dist/utils/debug-overlay.js.map +1 -0
  136. package/dist/utils/index.cjs.map +1 -1
  137. package/dist/utils/index.d.ts +2 -0
  138. package/dist/utils/index.js.map +1 -1
  139. package/dist/utils/key-handling.cjs +52 -6
  140. package/dist/utils/key-handling.cjs.map +1 -1
  141. package/dist/utils/key-handling.js +52 -6
  142. package/dist/utils/key-handling.js.map +1 -1
  143. package/dist/utils/validation.cjs +41 -0
  144. package/dist/utils/validation.cjs.map +1 -0
  145. package/dist/utils/validation.d.ts +26 -0
  146. package/dist/utils/validation.js +41 -0
  147. package/dist/utils/validation.js.map +1 -0
  148. package/dist/zustand-store.cjs +119 -61
  149. package/dist/zustand-store.cjs.map +1 -1
  150. package/dist/zustand-store.js +121 -63
  151. package/dist/zustand-store.js.map +1 -1
  152. package/package.json +6 -6
  153. package/src/actions/builtin.ts +62 -7
  154. package/src/actions/column-controls.ts +185 -0
  155. package/src/actions/column-filter.ts +104 -0
  156. package/src/actions/edit-actions.ts +67 -0
  157. package/src/actions/filters.ts +54 -28
  158. package/src/actions/index.ts +4 -0
  159. package/src/actions/selection.ts +59 -52
  160. package/src/actions/table-controls.ts +46 -0
  161. package/src/actions/toolbar.module.sass +22 -2
  162. package/src/actions/toolbar.ts +113 -16
  163. package/src/actions/types.ts +49 -4
  164. package/src/cell-renderer.ts +211 -16
  165. package/src/components/cell-detail.ts +30 -0
  166. package/src/components/editor-popup.ts +39 -25
  167. package/src/components/index.ts +2 -2
  168. package/src/components/text-areas.ts +80 -16
  169. package/src/components/view-info.ts +63 -4
  170. package/src/core.ts +321 -103
  171. package/src/filters/operators.ts +127 -0
  172. package/src/index.ts +2 -0
  173. package/src/main.module.sass +6 -0
  174. package/src/postgrest-table/data-loaders.ts +459 -209
  175. package/src/postgrest-table/index.ts +81 -254
  176. package/src/postgrest-table/main.module.sass +11 -0
  177. package/src/provider.ts +109 -12
  178. package/src/renderers/column-header-cell.ts +60 -272
  179. package/src/renderers/index.ts +0 -1
  180. package/src/types.ts +76 -2
  181. package/src/utils/column-spec.ts +112 -1
  182. package/src/utils/debug-overlay.ts +22 -0
  183. package/src/utils/index.ts +2 -0
  184. package/src/utils/key-handling.ts +70 -6
  185. package/src/utils/validation.ts +72 -0
  186. package/src/zustand-store.ts +167 -60
  187. package/dist/components/actions.cjs +0 -12
  188. package/dist/components/actions.cjs.map +0 -1
  189. package/dist/components/actions.d.ts +0 -2
  190. package/dist/components/actions.js +0 -12
  191. package/dist/components/actions.js.map +0 -1
  192. package/dist/components/actions.module.sass.cjs +0 -12
  193. package/dist/components/actions.module.sass.cjs.map +0 -1
  194. package/dist/components/actions.module.sass.js +0 -11
  195. package/dist/components/actions.module.sass.js.map +0 -1
  196. package/dist/postgrest-table/lazy-loader-table.cjs +0 -27
  197. package/dist/postgrest-table/lazy-loader-table.cjs.map +0 -1
  198. package/dist/postgrest-table/lazy-loader-table.d.ts +0 -3
  199. package/dist/postgrest-table/lazy-loader-table.js +0 -27
  200. package/dist/postgrest-table/lazy-loader-table.js.map +0 -1
  201. package/dist/renderers/column-header-cell-postgrest.cjs +0 -216
  202. package/dist/renderers/column-header-cell-postgrest.cjs.map +0 -1
  203. package/dist/renderers/column-header-cell-postgrest.d.ts +0 -13
  204. package/dist/renderers/column-header-cell-postgrest.js +0 -216
  205. package/dist/renderers/column-header-cell-postgrest.js.map +0 -1
  206. package/dist/renderers/column-header-cell-postgrest.module.sass.cjs +0 -23
  207. package/dist/renderers/column-header-cell-postgrest.module.sass.cjs.map +0 -1
  208. package/dist/renderers/column-header-cell-postgrest.module.sass.js +0 -22
  209. package/dist/renderers/column-header-cell-postgrest.module.sass.js.map +0 -1
  210. package/src/components/actions.ts +0 -9
  211. package/src/postgrest-table/lazy-loader-table.ts +0 -25
  212. package/src/renderers/column-header-cell-postgrest.ts +0 -282
@@ -9,15 +9,23 @@ import {
9
9
  PostgrestFilterBuilder,
10
10
  PostgrestQueryBuilder,
11
11
  } from "@supabase/postgrest-js";
12
- import { adjustArraySize, RowRegion, sleep } from "./loading-utils.ts";
13
- import { ctx, tableDataAtom } from "../provider.ts";
12
+ import { adjustArraySize, RowRegion } from "./loading-utils.ts";
13
+ import { ctx, tableDataAtom, useSelector } from "../provider.ts";
14
14
  import { atom } from "jotai";
15
- import h from "./main.module.sass";
15
+ import type { ColumnSort } from "../types.ts";
16
+
17
+ export type FetchMode = "scroll" | "paged";
16
18
 
17
19
  interface LazyLoaderStateCore<T> {
18
20
  loading: boolean;
19
21
  error: Error | null;
20
22
  initialized: boolean;
23
+ /** Reported source length when known (null = unknown / not reported). */
24
+ totalCount: number | null;
25
+ /** Windowing style: infinite-scroll windows, or one fixed page at a time. */
26
+ fetchMode: FetchMode;
27
+ /** Rows per chunk/page. */
28
+ pageSize: number;
21
29
  }
22
30
 
23
31
  interface LazyLoaderState<T> extends LazyLoaderStateCore<T> {
@@ -91,11 +99,18 @@ export function applyColumnFilters(
91
99
 
92
100
  type LazyLoaderAction<T> =
93
101
  | { type: "start-loading" }
94
- | { type: "loaded"; data: T[]; offset: number; totalSize: number }
102
+ | {
103
+ type: "loaded";
104
+ data: T[];
105
+ offset: number;
106
+ totalSize: number;
107
+ totalCount?: number | null;
108
+ }
95
109
  | { type: "error"; error: Error }
96
110
  | { type: "update-data"; changes: Spec<T[]> }
97
111
  | { type: "reset" }
98
- | { type: "start-reload" };
112
+ | { type: "start-reload" }
113
+ | { type: "configure"; fetchMode: FetchMode; pageSize: number };
99
114
 
100
115
  function lazyLoadingReducer<T>(
101
116
  state: LazyLoaderState<T>,
@@ -127,6 +142,16 @@ function lazyLoadingReducer<T>(
127
142
  ...state,
128
143
  data,
129
144
  loading: false,
145
+ totalCount:
146
+ action.totalCount !== undefined
147
+ ? action.totalCount
148
+ : state.totalCount,
149
+ };
150
+ case "configure":
151
+ return {
152
+ ...state,
153
+ fetchMode: action.fetchMode,
154
+ pageSize: action.pageSize,
130
155
  };
131
156
  case "start-reload":
132
157
  // Preserve the table dimensions but show ghost/skeleton cells
@@ -143,6 +168,9 @@ function lazyLoadingReducer<T>(
143
168
  loading: false,
144
169
  error: null,
145
170
  initialized: false,
171
+ totalCount: null,
172
+ fetchMode: state.fetchMode,
173
+ pageSize: state.pageSize,
146
174
  };
147
175
  case "error":
148
176
  return {
@@ -162,12 +190,6 @@ type SortAndFilterOptions = {
162
190
  filters?: PostgrestFilter[];
163
191
  };
164
192
 
165
- type LazyLoaderOptions = Omit<QueryConfig, "count" | "offset" | "limit"> &
166
- SortAndFilterOptions & {
167
- chunkSize?: number;
168
- sortKey?: string;
169
- };
170
-
171
193
  interface QueryConfig extends SortAndFilterOptions {
172
194
  columns?: string | string[];
173
195
  count?: "exact" | "estimated";
@@ -241,10 +263,58 @@ const defaultVisibleRegion: RowRegion = {
241
263
  /** Atom to house the current visible region of the table */
242
264
  const visibleRegionAtom = atom<RowRegion>(defaultVisibleRegion);
243
265
 
244
- const lazyLoaderCoreStateAtom = atom<LazyLoaderCoreState<any>>({
266
+ const lazyLoaderCoreStateAtom = atom<LazyLoaderStateCore<any>>({
245
267
  loading: false,
246
268
  error: null,
247
269
  initialized: false,
270
+ totalCount: null,
271
+ fetchMode: "scroll",
272
+ pageSize: 100,
273
+ });
274
+
275
+ /** Current page index (0-based) for paged fetch mode. */
276
+ export const chunkPageAtom = atom(0);
277
+
278
+ /** Bump this to force the active chunk loader to reset and re-fetch from
279
+ * scratch — e.g. after a mutation (save/delete) that invalidates loaded rows. */
280
+ export const dataRefreshTokenAtom = atom(0);
281
+
282
+ /** Footer state for the optional bottom-of-table indicator: rows loaded, the
283
+ * source total when known, load status, and — in paged mode — the current
284
+ * page and total pages. */
285
+ export interface TableFooterInfo {
286
+ mode: FetchMode;
287
+ loaded: number;
288
+ total: number | null;
289
+ loading: boolean;
290
+ page: number;
291
+ pageSize: number;
292
+ totalPages: number | null;
293
+ }
294
+
295
+ export const tableFooterAtom = atom<TableFooterInfo>((get) => {
296
+ const core = get(lazyLoaderCoreStateAtom);
297
+ const data = get(tableDataAtom) ?? [];
298
+ let loaded = 0;
299
+ let hasGaps = false;
300
+ for (const row of data) {
301
+ if (row != null) loaded++;
302
+ else hasGaps = true;
303
+ }
304
+ // Total is known when the source reported it, or (scroll mode) when the array
305
+ // is fully populated — otherwise it's still being discovered.
306
+ const total = core.totalCount ?? (hasGaps ? null : data.length);
307
+ const totalPages =
308
+ core.totalCount != null ? Math.ceil(core.totalCount / core.pageSize) : null;
309
+ return {
310
+ mode: core.fetchMode,
311
+ loaded,
312
+ total,
313
+ loading: core.loading,
314
+ page: get(chunkPageAtom),
315
+ pageSize: core.pageSize,
316
+ totalPages,
317
+ };
248
318
  });
249
319
 
250
320
  export interface ViewInfo {
@@ -287,7 +357,10 @@ const lazyLoaderStateAtom = atom(
287
357
  if (visibleRegion != null) {
288
358
  set(visibleRegionAtom, visibleRegion);
289
359
  }
290
- if (data != null && data.length > 0) {
360
+ // Propagate the data array even when empty — a `reset` (view change) must
361
+ // clear the stale rows so the re-fetch rebuilds a correctly-sized array
362
+ // (otherwise a filtered/sorted result splices over a stale, larger array).
363
+ if (data != null) {
291
364
  set(tableDataAtom, data);
292
365
  }
293
366
  if (Object.keys(rest).length > 1) {
@@ -338,64 +411,6 @@ function buildPostgrestOrderClauses(
338
411
  return clauses;
339
412
  }
340
413
 
341
- function _loadMorePostgRESTData<T>(
342
- client: PostgrestQueryBuilder<T, any>,
343
- config: QueryConfig & { chunkSize?: number },
344
- state: LazyLoaderState<T>,
345
- dispatch: any,
346
- ) {
347
- let rowIndex = indexOfFirstNullInRegion(state.data, state.visibleRegion);
348
- if (state.loading || rowIndex == null) {
349
- if (state.initialized) {
350
- return;
351
- }
352
- // For initial/reload queries, default to loading from the start
353
- rowIndex = rowIndex ?? 0;
354
- }
355
-
356
- const lastLoadedRowIndex: number = rowIndex - 1;
357
- let lastLoadedRow = null;
358
- if (lastLoadedRowIndex >= 0) {
359
- lastLoadedRow = state.data[lastLoadedRowIndex];
360
- }
361
-
362
- const { chunkSize = 100, ...rest } = config;
363
-
364
- // Determine the primary sort key from column sorts or the order prop
365
- const sortKey = config.order?.key ?? "id";
366
-
367
- let cfg: QueryConfig = {
368
- ...rest,
369
- limit: chunkSize,
370
- lastLoadedRow,
371
- lastLoadedRowIndex,
372
- };
373
-
374
- // Allows random seeking
375
- const isInitialQuery = !state.initialized;
376
- if (isInitialQuery) {
377
- cfg.count = "exact";
378
- }
379
-
380
- dispatch({ type: "start-loading" });
381
-
382
- const query = buildQuery(client, cfg);
383
-
384
- query.then((res) => {
385
- console.log(res);
386
- const { data, count } = res;
387
- dispatch({
388
- type: "loaded",
389
- data,
390
- offset: rowIndex,
391
- totalSize: count,
392
- });
393
- });
394
- }
395
-
396
- // Ensure only one data load is in progress at a time
397
- const loadMorePostgRESTData = debounce(_loadMorePostgRESTData, 100);
398
-
399
414
  export function useScrollHandler() {
400
415
  /** A standardized approach to holding onto the scroll position for the table */
401
416
  // Reference to hold onto the scroll position
@@ -411,7 +426,6 @@ export function useScrollHandler() {
411
426
  ) {
412
427
  return;
413
428
  }
414
- console.log("Visible cells changed", visibleCells);
415
429
  setVisibleRegion(visibleCells);
416
430
  ref.current = visibleCells;
417
431
  }, 500),
@@ -419,170 +433,406 @@ export function useScrollHandler() {
419
433
  );
420
434
  }
421
435
 
422
- export function usePostgRESTLazyLoader(
423
- endpoint: string,
424
- table: string,
425
- config: LazyLoaderOptions = {},
426
- ) {
427
- const getClient = useCallback(() => {
428
- return new PostgrestClient(endpoint).from(table);
429
- }, [endpoint, table]);
430
-
431
- const [state, dispatch] = useLazyLoaderReducer();
432
- const { data, loading } = state;
433
-
434
- // Reset data whenever sort/filter configuration changes so we re-fetch
435
- const sortFilterKey = useMemo(
436
- () =>
437
- JSON.stringify({
438
- s: config.order,
439
- v: config.filters,
440
- i: config.identityKey,
441
- }),
442
- [config.order, config.filters, config.identityKey],
443
- );
436
+ /** The active view state (a filter's id / column / config), passed to a
437
+ * `fetchChunk`. A server provider translates `columnKey` + `state` into a
438
+ * query; a local (in-memory) provider applies `predicate` directly. Both come
439
+ * from the same `TableFilter`, so one filter definition serves either target. */
440
+ export interface FetchDataFilter {
441
+ id: string;
442
+ columnKey?: string;
443
+ state: any;
444
+ /** Client-side row predicate (from the `TableFilter`). Server providers
445
+ * ignore it and translate `columnKey` + `state` instead. */
446
+ predicate?: (row: any, state: any) => boolean;
447
+ }
444
448
 
445
- const visibleRegion = ctx.useValue(visibleRegionAtom);
449
+ /** Parameters passed to a `fetchChunk` implementation for one window. */
450
+ export interface FetchDataParams {
451
+ /** Row offset of the requested chunk (chunk-aligned). */
452
+ offset: number;
453
+ /** Maximum rows to return. */
454
+ limit: number;
455
+ /** Aborts when the request is superseded (view change / unmount). */
456
+ signal: AbortSignal;
457
+ /** Active sorts, in priority order. */
458
+ sorts: ColumnSort[];
459
+ /** Active filters (id + column + config). */
460
+ filters: FetchDataFilter[];
461
+ /** In scroll mode, the already-loaded row immediately before this chunk
462
+ * (and its data-array index), or `null` at the start / in paged mode. Keyset
463
+ * sources can page from this cursor (e.g. `WHERE key > cursor`) instead of a
464
+ * slow `OFFSET`; offset-based sources can ignore it. */
465
+ cursor?: { row: any; index: number } | null;
466
+ }
446
467
 
447
- useEffect(() => {
448
- dispatch({ type: "reset" });
449
- }, [sortFilterKey]);
468
+ /** Result of a `fetchChunk` call. `totalCount` reports the source length when
469
+ * known (drives sparse-array pre-sizing and a proportional scrollbar); omit it
470
+ * for unknown-length sources (the array grows as chunks arrive). */
471
+ export interface FetchDataResult<T = any> {
472
+ rows: T[];
473
+ totalCount?: number | null;
474
+ }
450
475
 
451
- useAsyncEffect(async () => {
452
- const client = getClient();
453
- loadMorePostgRESTData(client, config, state, dispatch);
454
- }, [data, visibleRegion, sortFilterKey]);
476
+ export type FetchData<T = any> = (
477
+ params: FetchDataParams,
478
+ ) => Promise<FetchDataResult<T>>;
479
+
480
+ /**
481
+ * A table's data source, addressed uniformly whether it's an in-memory array or
482
+ * a remote backend. `fetchChunk` returns a window with the active sorts/filters
483
+ * already applied (in memory by the local provider, in SQL by a server one);
484
+ * `identity` addresses a row for edits/mutations — stable across re-sorts,
485
+ * unlike an array index. The mutation ops are present only for editable /
486
+ * persisting sources. The in-memory case (`createLocalProvider`) is just the
487
+ * degenerate implementation, so local and server tables share one path.
488
+ */
489
+ export interface TableDataProvider<T = any> {
490
+ fetchData(params: FetchDataParams): Promise<FetchDataResult<T>>;
491
+ identity(row: T): string | number;
492
+ saveRows?(rows: T[]): Promise<void>;
493
+ deleteRows?(ids: Array<string | number>): Promise<void>;
494
+ insertRow?(row: Partial<T>): Promise<void>;
495
+ }
455
496
 
497
+ /**
498
+ * The degenerate provider: an in-memory array. `fetchChunk` applies the active
499
+ * filter predicates and sorts over the array and returns the requested slice
500
+ * plus the (fully-known) total — the same view engine used for client-side
501
+ * tables, expressed as a provider.
502
+ */
503
+ export function createLocalProvider<T = any>(
504
+ data: T[],
505
+ options: { identity?: (row: T) => string | number } = {},
506
+ ): TableDataProvider<T> {
507
+ const identity: (row: T) => string | number =
508
+ options.identity ?? defaultLocalIdentity;
456
509
  return {
457
- data,
458
- loading,
459
- dispatch,
460
- getClient,
510
+ identity,
511
+ async fetchData({ offset, limit, sorts, filters }) {
512
+ let rows = data;
513
+ if (filters != null && filters.length > 0) {
514
+ rows = rows.filter((row) =>
515
+ filters.every((f) =>
516
+ f.predicate != null ? f.predicate(row, f.state) : true,
517
+ ),
518
+ );
519
+ }
520
+ if (sorts != null && sorts.length > 0) {
521
+ rows = [...rows].sort(compareRowsBySorts(sorts));
522
+ }
523
+ return {
524
+ rows: rows.slice(offset, offset + limit),
525
+ totalCount: rows.length,
526
+ };
527
+ },
461
528
  };
462
529
  }
463
530
 
464
- function indexOfFirstNullInRegion(
465
- data: any[],
466
- region: RowRegion,
467
- ): number | null {
468
- for (let i = region.rowIndexStart; i < region.rowIndexEnd; i++) {
469
- if (data[i] == null) {
470
- return i;
471
- }
531
+ // Stable synthetic identity for in-memory rows lacking a natural `id`. Keyed by
532
+ // object reference (a local data array keeps the same row objects across
533
+ // re-sorts), so edits survive re-ordering even without an id field.
534
+ const _syntheticRowIds = new WeakMap<object, string>();
535
+ let _syntheticRowCounter = 0;
536
+ function defaultLocalIdentity(row: any): string | number | undefined {
537
+ if (row == null) return undefined;
538
+ if (row.id != null) return row.id;
539
+ if (typeof row !== "object") return row;
540
+ let id = _syntheticRowIds.get(row);
541
+ if (id == null) {
542
+ id = `__row_${_syntheticRowCounter++}`;
543
+ _syntheticRowIds.set(row, id);
472
544
  }
473
- return null;
545
+ return id;
474
546
  }
475
547
 
476
- export function useTestLazyLoader(config: LazyLoaderOptions = {}) {
477
- const [state, dispatch] = useLazyLoaderReducer();
478
- const { data, loading } = state;
479
-
480
- const visibleRegion = ctx.useValue(visibleRegionAtom);
481
-
482
- useAsyncEffect(async () => {
483
- testDataLoader(config, state, dispatch);
484
- }, [data, visibleRegion]);
485
-
486
- return {
487
- data,
488
- loading,
489
- dispatch,
548
+ /** Multi-key row comparator (priority order; nulls first when ascending),
549
+ * shared by the local provider and any other in-memory sort. */
550
+ export function compareRowsBySorts(sorts: ColumnSort[]) {
551
+ return (a: any, b: any): number => {
552
+ for (const sort of sorts) {
553
+ const av = a?.[sort.key];
554
+ const bv = b?.[sort.key];
555
+ if (av == null && bv == null) continue;
556
+ if (av == null) return sort.ascending ? -1 : 1;
557
+ if (bv == null) return sort.ascending ? 1 : -1;
558
+ const cmp = av < bv ? -1 : av > bv ? 1 : 0;
559
+ if (cmp !== 0) return sort.ascending ? cmp : -cmp;
560
+ }
561
+ return 0;
490
562
  };
491
563
  }
492
564
 
493
- function testDataLoader(
494
- config: { chunkSize: number },
495
- state: LazyLoaderState<any>,
496
- dispatch,
497
- ) {
498
- const sortKey = "id";
499
- const rowIndex = indexOfFirstNullInRegion(state.data, state.visibleRegion);
500
- if (state.loading || rowIndex == null) {
501
- if (state.initialized) {
502
- return;
503
- }
504
- }
565
+ export interface FetchDataOptions {
566
+ pageSize?: number;
567
+ fetchMode?: FetchMode;
568
+ }
505
569
 
506
- const chunkSize = 10;
570
+ /**
571
+ * A generic, backend-agnostic windowed data source. Give it a `fetchChunk`
572
+ * function and it drives the sheet's lazy loading: it loads the chunk covering
573
+ * the first unloaded visible row, pre-sizes the sparse array from `totalCount`,
574
+ * threads the active sorts/filters through so the source can apply them
575
+ * server-side, and re-fetches from scratch when the view state changes. This
576
+ * is the unified seam that upstreams bespoke loaders (`fetchChunk` receives the
577
+ * view state; there's no separate adapter object).
578
+ *
579
+ * Call it from a component rendered inside `DataSheet` (see `ChunkLoaderManager`).
580
+ */
581
+ export function useDataLoader<T = any>(
582
+ fetchChunk: FetchData<T>,
583
+ options: FetchDataOptions = {},
584
+ ) {
585
+ const { pageSize = 100, fetchMode = "scroll" } = options;
586
+ const [state, dispatch] = useLazyLoaderReducer();
587
+ const visibleRegion = ctx.useValue(visibleRegionAtom);
588
+ const page = ctx.useValue(chunkPageAtom);
589
+ const setPage = ctx.useSet(chunkPageAtom);
590
+ const refreshToken = ctx.useValue(dataRefreshTokenAtom);
591
+ const columnSorts = useSelector((s) => s.columnSorts);
592
+ const activeFilters = useSelector((s) => s.activeFilters);
593
+ const abortRef = useRef<AbortController | null>(null);
594
+ // Tracks the (page, viewKey) already loaded in paged mode, so the effect
595
+ // doesn't re-fetch on unrelated re-renders.
596
+ const loadedRef = useRef<{ page: number; viewKey: string }>({
597
+ page: -1,
598
+ viewKey: "",
599
+ });
507
600
 
508
- let cfg: QueryConfig = {
509
- //...rest,
510
- limit: chunkSize,
511
- offset: null,
512
- };
601
+ const filters: FetchDataFilter[] = useMemo(
602
+ () =>
603
+ (Array.from(activeFilters.entries()) as [any, any][]).map(
604
+ ([id, entry]) => ({
605
+ id,
606
+ columnKey: entry.filter?.columnKey,
607
+ state: entry.state,
608
+ predicate: entry.filter?.predicate,
609
+ }),
610
+ ),
611
+ [activeFilters],
612
+ );
513
613
 
514
- // Allows random seeking
515
- const isInitialQuery = !state.initialized;
516
- if (isInitialQuery) {
517
- cfg.count = "exact";
518
- }
614
+ // Publish the windowing config so the footer/pager can read it.
615
+ useEffect(() => {
616
+ dispatch({ type: "configure", fetchMode, pageSize: pageSize });
617
+ }, [fetchMode, pageSize]);
618
+
619
+ // Reset (re-fetch from scratch) when sorts/filters change, or when the fetch
620
+ // mode switches (paged holds a dense page; scroll needs to re-initialize and
621
+ // pre-size) — so a table can flip between modes cleanly.
622
+ const viewKey = useMemo(
623
+ () => JSON.stringify({ sorts: columnSorts, filters }),
624
+ [columnSorts, filters],
625
+ );
626
+ useEffect(() => {
627
+ dispatch({ type: "reset" });
628
+ setPage(0);
629
+ }, [viewKey, fetchMode, refreshToken]);
519
630
 
520
- // This only works for forward queries
521
- if (!isInitialQuery) {
522
- cfg.after = state.data[rowIndex - 1]?.[sortKey];
523
- if (cfg.after == null) {
524
- cfg.offset = rowIndex;
631
+ useAsyncEffect(async () => {
632
+ if (state.loading) return;
633
+
634
+ // Determine the chunk offset to fetch, and (scroll mode) a keyset cursor:
635
+ // the already-loaded row just before the chunk, so keyset sources can page
636
+ // from it instead of a slow OFFSET.
637
+ let offset: number;
638
+ let cursor: { row: any; index: number } | null = null;
639
+ if (fetchMode === "paged") {
640
+ // Fetch the current page once; skip if already loaded for this view.
641
+ if (
642
+ loadedRef.current.page === page &&
643
+ loadedRef.current.viewKey === viewKey
644
+ ) {
645
+ return;
646
+ }
647
+ offset = page * pageSize;
648
+ } else {
649
+ const rowIndex = indexOfFirstNullInRegion(state.data, visibleRegion);
650
+ if (rowIndex == null && state.initialized) return;
651
+ offset = Math.floor((rowIndex ?? 0) / pageSize) * pageSize;
652
+ const prev = offset > 0 ? state.data[offset - 1] : null;
653
+ if (prev != null) cursor = { row: prev, index: offset - 1 };
525
654
  }
526
- }
527
655
 
528
- dispatch({ type: "start-loading" });
656
+ abortRef.current?.abort();
657
+ const controller = new AbortController();
658
+ abortRef.current = controller;
659
+
660
+ dispatch({ type: "start-loading" });
661
+ try {
662
+ const result = await fetchChunk({
663
+ offset,
664
+ limit: pageSize,
665
+ signal: controller.signal,
666
+ sorts: columnSorts,
667
+ filters,
668
+ cursor,
669
+ });
670
+ if (controller.signal.aborted) return;
671
+ const rows = result.rows ?? [];
672
+ if (fetchMode === "paged") {
673
+ loadedRef.current = { page, viewKey };
674
+ // The sheet shows just this page's rows (dense, from index 0); the
675
+ // real source length is tracked separately for the pager.
676
+ dispatch({
677
+ type: "loaded",
678
+ data: rows,
679
+ offset: 0,
680
+ totalSize: rows.length,
681
+ totalCount: result.totalCount ?? null,
682
+ });
683
+ } else {
684
+ // Size the (sparse) array. With a known total, size to it. Without one
685
+ // (keyset / infinite scroll), use the short-chunk heuristic: a chunk
686
+ // smaller than the page size means we've hit the end — size exactly to
687
+ // the loaded rows; otherwise pad one more page of nulls so scrolling
688
+ // into them triggers the next fetch. So an unknown-length source never
689
+ // needs a count — it grows a page at a time until a short chunk.
690
+ const loadedEnd = offset + rows.length;
691
+ let totalSize: number;
692
+ if (result.totalCount != null) {
693
+ totalSize = result.totalCount;
694
+ } else {
695
+ const reachedEnd = rows.length < pageSize;
696
+ totalSize = reachedEnd ? loadedEnd : loadedEnd + pageSize;
697
+ }
698
+ dispatch({
699
+ type: "loaded",
700
+ data: rows,
701
+ offset,
702
+ totalSize,
703
+ // Preserve a previously-known total when a chunk omits it (undefined):
704
+ // keyset pages can't re-count (the cursor filter would skew it), so
705
+ // only the initial cursorless fetch reports the total.
706
+ totalCount: result.totalCount,
707
+ });
708
+ }
709
+ } catch (err) {
710
+ if (!controller.signal.aborted) {
711
+ dispatch({ type: "error", error: err as Error });
712
+ }
713
+ }
714
+ }, [state.data, visibleRegion, viewKey, page, fetchMode]);
529
715
 
530
- const query = testQueryFunc(cfg);
531
- query.then((res) => {
532
- console.log(res);
533
- const { data, count } = res;
534
- dispatch({
535
- type: "loaded",
536
- data,
537
- offset: rowIndex,
538
- totalSize: count,
539
- });
540
- });
716
+ return { data: state.data, loading: state.loading, error: state.error };
541
717
  }
542
718
 
543
- interface QueryParams {
544
- count: "exact" | "estimated";
545
- limit: number;
546
- offset?: number;
547
- after?: number;
548
- }
549
-
550
- const testQueryFunc = async (
551
- cfg: QueryParams,
552
- ): Promise<{
553
- data: any[];
554
- count: number | null;
555
- }> => {
556
- console.log(cfg);
557
- let offset = null;
558
- if (cfg.after) {
559
- offset = cfg.after;
560
- } else if (cfg.offset) {
561
- offset = cfg.offset;
562
- }
719
+ /**
720
+ * Build a `fetchChunk` backed by a PostgREST endpoint, for use with
721
+ * `useChunkLoader` / `ChunkLoaderManager`. It reuses `buildQuery`, so it pages
722
+ * with **keyset pagination** (via the loader's `cursor`) whenever the query is
723
+ * ordered — falling back to `OFFSET` only when it isn't — and threads the
724
+ * active store sorts/filters into the query. The total count is requested only
725
+ * on the initial (cursorless) fetch, since a keyset cursor filter would skew it.
726
+ */
727
+ export function createPostgRESTFetchChunk<T = any>(config: {
728
+ endpoint: string;
729
+ table: string;
730
+ identityKey: string;
731
+ columns?: string | string[];
732
+ /** Order applied before the active column sorts (identity key appended last). */
733
+ baseOrder?: PostgrestOrder<any>[];
734
+ /** A transform over the query builder, applied as a base filter (the `filter` prop). */
735
+ baseFilter?: (
736
+ q: PostgrestFilterBuilder<any, any, any, any>,
737
+ ) => PostgrestFilterBuilder<any, any, any, any>;
738
+ /** Translate a stored filter entry to a `PostgrestFilter` (return `null` to
739
+ * skip). Defaults to the `{ key, operator, value }` column-filter shape. */
740
+ translateFilter?: (f: FetchDataFilter) => PostgrestFilter | null;
741
+ }): FetchData<T> {
742
+ const translate = config.translateFilter ?? standardColumnFilter;
743
+ return async ({ limit, signal, sorts, filters, cursor }) => {
744
+ const client = new PostgrestClient(config.endpoint).from(config.table);
745
+
746
+ const order: PostgrestOrder<any>[] = [
747
+ ...(config.baseOrder ?? []),
748
+ ...sorts.map((s) => ({ key: s.key, ascending: s.ascending })),
749
+ ];
750
+
751
+ const pgFilters: PostgrestFilter[] = [];
752
+ if (config.baseFilter != null) {
753
+ const apply = config.baseFilter;
754
+ pgFilters.push({ type: "filter", apply });
755
+ }
756
+ for (const f of filters) {
757
+ const pf = translate(f);
758
+ if (pf != null) pgFilters.push(pf);
759
+ }
563
760
 
564
- let count = cfg.limit;
565
- const totalCount = 50000;
566
- count = Math.min(count, totalCount - offset);
761
+ const query = buildQuery(client, {
762
+ columns: config.columns,
763
+ // Only the initial (cursorless) fetch reports an accurate total.
764
+ count: cursor == null ? "exact" : undefined,
765
+ limit,
766
+ identityKey: config.identityKey,
767
+ order,
768
+ filters: pgFilters,
769
+ lastLoadedRow: cursor?.row ?? null,
770
+ lastLoadedRowIndex: cursor?.index ?? -1,
771
+ });
567
772
 
568
- // wait for a little bit before returning
569
- await sleep(100);
773
+ const res: any = await query;
774
+ if (signal.aborted) return { rows: [] };
775
+ if (res?.error != null) throw res.error;
776
+ const rows = res?.data ?? [];
777
+ return res?.count != null ? { rows, totalCount: res.count } : { rows };
778
+ };
779
+ }
570
780
 
781
+ /**
782
+ * A full PostgREST `TableDataProvider`: the read side (`fetchData` + row
783
+ * `identity`) plus persistence — `saveRows` (upsert) and `deleteRows` (by
784
+ * identity). Pass it to `DataSheet`'s `provider` prop. The mutation methods
785
+ * throw on error so the Save action surfaces it.
786
+ */
787
+ export function createPostgRESTProvider<T = any>(config: {
788
+ endpoint: string;
789
+ table: string;
790
+ identityKey: string;
791
+ columns?: string | string[];
792
+ baseOrder?: PostgrestOrder<any>[];
793
+ baseFilter?: (
794
+ q: PostgrestFilterBuilder<any, any, any, any>,
795
+ ) => PostgrestFilterBuilder<any, any, any, any>;
796
+ translateFilter?: (f: FetchDataFilter) => PostgrestFilter | null;
797
+ }): TableDataProvider<T> {
798
+ const from = () => new PostgrestClient(config.endpoint).from(config.table);
571
799
  return {
572
- data: buildSyntheticData(offset, count),
573
- count: cfg.count != null ? 50000 : undefined,
800
+ fetchData: createPostgRESTFetchChunk<T>(config),
801
+ identity: (row: any) => row?.[config.identityKey],
802
+ async saveRows(rows) {
803
+ const res: any = await from().upsert(rows as any[], {
804
+ defaultToNull: false,
805
+ });
806
+ if (res?.error != null) throw res.error;
807
+ },
808
+ async deleteRows(ids) {
809
+ const res: any = await from().delete().in(config.identityKey, ids);
810
+ if (res?.error != null) throw res.error;
811
+ },
574
812
  };
575
- };
813
+ }
576
814
 
577
- function buildSyntheticData(offset: number, count: number | null) {
578
- console.log(
579
- `Getting data at indices between ${offset} and ${offset + count}`,
580
- );
581
- return range(offset, offset + count).map((i) => {
582
- const id = i + 1;
583
- return {
584
- id,
585
- name: `row ${id} has some long text content`,
586
- };
587
- });
815
+ /** Default filter translation for the built-in operator `columnFilter`: its
816
+ * column is `f.columnKey`, its state is `{ operator, value }`. (Also accepts a
817
+ * `key` in state for hand-rolled filters.) */
818
+ function standardColumnFilter(f: FetchDataFilter): PostgrestFilter | null {
819
+ const s = f.state;
820
+ if (s == null) return null;
821
+ const key = f.columnKey ?? s.key;
822
+ if (key != null && s.operator != null && s.value != null && s.value !== "") {
823
+ return standardizeFilter({ key, operator: s.operator, value: s.value });
824
+ }
825
+ return null;
826
+ }
827
+
828
+ function indexOfFirstNullInRegion(
829
+ data: any[],
830
+ region: RowRegion,
831
+ ): number | null {
832
+ for (let i = region.rowIndexStart; i < region.rowIndexEnd; i++) {
833
+ if (data[i] == null) {
834
+ return i;
835
+ }
836
+ }
837
+ return null;
588
838
  }