@macrostrat/data-sheet 4.4.1 → 4.5.1

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 (54) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/dist/data-panel.cjs +40 -36
  3. package/dist/data-panel.cjs.map +1 -1
  4. package/dist/data-panel.d.ts +1 -1
  5. package/dist/data-panel.js +40 -36
  6. package/dist/data-panel.js.map +1 -1
  7. package/dist/data-panel.module.sass.cjs +26 -25
  8. package/dist/data-panel.module.sass.cjs.map +1 -1
  9. package/dist/data-panel.module.sass.js +26 -25
  10. package/dist/data-panel.module.sass.js.map +1 -1
  11. package/dist/data-sheet.cjs +3 -1
  12. package/dist/data-sheet.cjs.map +1 -1
  13. package/dist/data-sheet.css +58 -41
  14. package/dist/data-sheet.d.ts +1 -1
  15. package/dist/data-sheet.js +3 -1
  16. package/dist/data-sheet.js.map +1 -1
  17. package/dist/index.cjs +4 -0
  18. package/dist/index.cjs.map +1 -1
  19. package/dist/index.js +5 -1
  20. package/dist/index.js.map +1 -1
  21. package/dist/postgrest-table/data-loaders.cjs +67 -2
  22. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  23. package/dist/postgrest-table/data-loaders.d.ts +8 -1
  24. package/dist/postgrest-table/data-loaders.js +67 -2
  25. package/dist/postgrest-table/data-loaders.js.map +1 -1
  26. package/dist/provider/core.cjs +23 -2
  27. package/dist/provider/core.cjs.map +1 -1
  28. package/dist/provider/core.d.ts +2 -2
  29. package/dist/provider/core.js +23 -2
  30. package/dist/provider/core.js.map +1 -1
  31. package/dist/provider/distinct-values.cjs +65 -0
  32. package/dist/provider/distinct-values.cjs.map +1 -0
  33. package/dist/provider/distinct-values.d.ts +21 -0
  34. package/dist/provider/distinct-values.js +65 -0
  35. package/dist/provider/distinct-values.js.map +1 -0
  36. package/dist/provider/index.d.ts +1 -0
  37. package/dist/provider/table-data.cjs +21 -0
  38. package/dist/provider/table-data.cjs.map +1 -1
  39. package/dist/provider/table-data.d.ts +22 -0
  40. package/dist/provider/table-data.js +21 -0
  41. package/dist/provider/table-data.js.map +1 -1
  42. package/dist/types.cjs.map +1 -1
  43. package/dist/types.d.ts +27 -4
  44. package/dist/types.js.map +1 -1
  45. package/package.json +1 -1
  46. package/src/data-panel.module.sass +31 -13
  47. package/src/data-panel.ts +37 -30
  48. package/src/data-sheet.ts +3 -1
  49. package/src/postgrest-table/data-loaders.ts +106 -3
  50. package/src/provider/core.ts +36 -3
  51. package/src/provider/distinct-values.ts +127 -0
  52. package/src/provider/index.ts +1 -0
  53. package/src/provider/table-data.ts +51 -0
  54. package/src/types.ts +33 -4
@@ -0,0 +1,127 @@
1
+ /**
2
+ * Reading a column's vocabulary — the distinct values it holds — so a filter
3
+ * control can offer choices that actually match something.
4
+ *
5
+ * The provider answers the question (`TableDataProvider.distinctValues`); this
6
+ * is the ergonomic half: one hook, one fetch per column per view, shared by
7
+ * every control that asks. Without it every consumer hand-rolls a fetch and a
8
+ * cache per facet, which is exactly what the ingestion list was doing three
9
+ * times over.
10
+ */
11
+ import { useEffect, useState } from "react";
12
+ import { ctx, dataProviderAtom } from "./core.ts";
13
+ import {
14
+ dataRefreshTokenAtom,
15
+ DistinctValue,
16
+ DistinctValuesOptions,
17
+ TableDataProvider,
18
+ } from "./table-data.ts";
19
+
20
+ export interface DistinctValuesState<V = any> {
21
+ /** The column's values, most useful first (frequency, then value). */
22
+ values: DistinctValue<V>[];
23
+ loading: boolean;
24
+ error: Error | null;
25
+ /** `false` when the source can't answer — a control should fall back to free
26
+ * entry rather than showing an empty list. */
27
+ supported: boolean;
28
+ }
29
+
30
+ const EMPTY: DistinctValue[] = [];
31
+
32
+ /**
33
+ * The distinct values of `columnKey` in the enclosing view's source.
34
+ *
35
+ * Cached per (provider, column, refresh token): controls mount and unmount as
36
+ * menus open, and shouldn't each pay for a request. A provider mutation bumps
37
+ * the refresh token, so a newly-created value shows up without a manual
38
+ * invalidation step.
39
+ */
40
+ export function useDistinctValues<V = any>(
41
+ columnKey: string | null | undefined,
42
+ options: DistinctValuesOptions = {},
43
+ ): DistinctValuesState<V> {
44
+ const { provider } = ctx.useValue(dataProviderAtom);
45
+ const refreshToken = ctx.useValue(dataRefreshTokenAtom);
46
+ const { limit } = options;
47
+
48
+ const supported = provider?.distinctValues != null && columnKey != null;
49
+ const [state, setState] = useState<DistinctValuesState<V>>({
50
+ values: EMPTY,
51
+ loading: supported,
52
+ error: null,
53
+ supported,
54
+ });
55
+
56
+ useEffect(() => {
57
+ if (!supported) {
58
+ setState({ values: EMPTY, loading: false, error: null, supported });
59
+ return;
60
+ }
61
+ let active = true;
62
+ const controller = new AbortController();
63
+ setState((prev) => ({ ...prev, loading: true, supported }));
64
+
65
+ read(provider!, columnKey!, refreshToken, limit)
66
+ .then((values) => {
67
+ if (!active) return;
68
+ setState({ values, loading: false, error: null, supported: true });
69
+ })
70
+ .catch((error) => {
71
+ if (!active || controller.signal.aborted) return;
72
+ setState({ values: EMPTY, loading: false, error, supported: true });
73
+ });
74
+
75
+ return () => {
76
+ active = false;
77
+ controller.abort();
78
+ };
79
+ }, [provider, columnKey, refreshToken, limit, supported]);
80
+
81
+ return state;
82
+ }
83
+
84
+ /** Just the values, for a control that doesn't care about counts or status. */
85
+ export function useDistinctValueList<V = any>(
86
+ columnKey: string | null | undefined,
87
+ options: DistinctValuesOptions = {},
88
+ ): V[] {
89
+ const { values } = useDistinctValues<V>(columnKey, options);
90
+ return values.map((v) => v.value);
91
+ }
92
+
93
+ // One in-flight-or-settled promise per (provider, column, token, limit). Keyed
94
+ // weakly on the provider so a discarded view's cache goes with it.
95
+ const cache = new WeakMap<
96
+ TableDataProvider<any>,
97
+ Map<string, Promise<DistinctValue[]>>
98
+ >();
99
+
100
+ function read(
101
+ provider: TableDataProvider<any>,
102
+ columnKey: string,
103
+ refreshToken: number,
104
+ limit: number | undefined,
105
+ ): Promise<DistinctValue[]> {
106
+ let byKey = cache.get(provider);
107
+ if (byKey == null) {
108
+ byKey = new Map();
109
+ cache.set(provider, byKey);
110
+ }
111
+ const key = `${columnKey} ${refreshToken} ${limit ?? ""}`;
112
+ const cached = byKey.get(key);
113
+ if (cached != null) return cached;
114
+
115
+ // The shared promise deliberately carries no abort signal: one unmounting
116
+ // control must not cancel the fetch for the others. Each caller's own signal
117
+ // only decides whether it still cares about the result.
118
+ const pending = provider.distinctValues!(columnKey, { limit }).catch(
119
+ (error) => {
120
+ // Don't cache a failure — the next control to mount should retry.
121
+ byKey!.delete(key);
122
+ throw error;
123
+ },
124
+ );
125
+ byKey.set(key, pending);
126
+ return pending;
127
+ }
@@ -5,3 +5,4 @@ export * from "./zustand-store";
5
5
  export * from "./interactions.ts";
6
6
  export * from "./selection.ts";
7
7
  export * from "./column-spec.ts";
8
+ export * from "./distinct-values.ts";
@@ -61,6 +61,54 @@ export interface TableDataProvider<T = any> {
61
61
  saveRows?(rows: T[]): Promise<void>;
62
62
  deleteRows?(ids: Array<string | number>): Promise<void>;
63
63
  insertRow?(row: Partial<T>): Promise<void>;
64
+ /** The distinct values a column holds — the vocabulary a value picker offers,
65
+ * so a filter can only be set to something that matches. Optional: a source
66
+ * that can't answer it cheaply simply omits it, and pickers fall back to free
67
+ * entry. See {@link useDistinctValues}. */
68
+ distinctValues?(
69
+ columnKey: string,
70
+ options?: DistinctValuesOptions,
71
+ ): Promise<DistinctValue[]>;
72
+ }
73
+
74
+ /** One value a column holds, with its frequency where the source reports it. */
75
+ export interface DistinctValue<V = any> {
76
+ value: V;
77
+ /** Rows carrying this value. Omitted when the source can't count cheaply. */
78
+ count?: number;
79
+ }
80
+
81
+ export interface DistinctValuesOptions {
82
+ /** Aborts when the request is superseded (unmount, key change). */
83
+ signal?: AbortSignal;
84
+ /** Cap on how many values to return — a high-cardinality column shouldn't
85
+ * become an unbounded fetch. */
86
+ limit?: number;
87
+ }
88
+
89
+ /** Distinct values of an in-memory column, ordered by descending frequency then
90
+ * value. Array cells are *not* flattened: the values of an array column are its
91
+ * arrays, matching what a server-side `GROUP BY` would report. */
92
+ export function distinctValuesOf<T>(
93
+ rows: T[],
94
+ columnKey: string,
95
+ options: DistinctValuesOptions = {},
96
+ ): DistinctValue[] {
97
+ const counts = new Map<any, number>();
98
+ for (const row of rows) {
99
+ const value = (row as any)?.[columnKey];
100
+ counts.set(value, (counts.get(value) ?? 0) + 1);
101
+ }
102
+ const values = [...counts.entries()].map(([value, count]) => ({
103
+ value,
104
+ count,
105
+ }));
106
+ values.sort((a, b) => {
107
+ if (b.count !== a.count) return b.count - a.count;
108
+ return String(a.value).localeCompare(String(b.value));
109
+ });
110
+ if (options.limit != null) return values.slice(0, options.limit);
111
+ return values;
64
112
  }
65
113
 
66
114
  /**
@@ -94,6 +142,9 @@ export function createLocalProvider<T = any>(
94
142
  totalCount: rows.length,
95
143
  };
96
144
  },
145
+ async distinctValues(columnKey, opts) {
146
+ return distinctValuesOf(data, columnKey, opts);
147
+ },
97
148
  };
98
149
  }
99
150
 
package/src/types.ts CHANGED
@@ -8,16 +8,37 @@ import {
8
8
  TableElementStatus,
9
9
  VisibleCells,
10
10
  } from "./provider";
11
- import type { ColumnSpec, ColumnSpecOptions } from "./provider";
11
+ import type { ColumnSort, ColumnSpec, ColumnSpecOptions } from "./provider";
12
12
  import { ReactNode } from "react";
13
- import { TableAction, TableActionContext, TableFilter } from "./actions";
13
+ import {
14
+ ActiveFilterEntry,
15
+ TableAction,
16
+ TableActionContext,
17
+ TableFilter,
18
+ } from "./actions";
14
19
  import { Region, TableProps } from "@blueprintjs/table";
15
20
 
16
21
  export type FetchMode = "scroll" | "paged";
17
22
 
18
- export interface FetchDataOptions {
23
+ export interface InitialDataChunk<T = any> {
24
+ rows: T[];
25
+ /** Total rows in the source, when the caller's fetch reported it. */
26
+ totalCount?: number | null;
27
+ }
28
+
29
+ export interface FetchDataOptions<T = any> {
19
30
  pageSize?: number;
20
31
  fetchMode?: FetchMode;
32
+ /** Rows already in hand for the first window — typically fetched outside the
33
+ * view (a server render, a parent that needed the data anyway) — so mounting
34
+ * doesn't re-request a page the caller already has. The loader starts
35
+ * populated and initialized; scrolling past the seed fetches as usual, and any
36
+ * view change discards it and re-fetches (the seed only describes the view it
37
+ * was fetched for, so pass matching `initialFilters` / `initialSorts`).
38
+ *
39
+ * Pass `totalCount` when it's known — the array is pre-sized to it, so the
40
+ * scrollbar and the counter are right from the first paint. */
41
+ initialData?: T[] | InitialDataChunk<T>;
21
42
  /** Debounce (ms) applied to view-state → refetch, so rapid changes (typing a
22
43
  * text filter) collapse into one fetch once the view settles. The input stays
23
44
  * instant; only the fetch waits. `0` (default) keeps immediate refetching. */
@@ -57,10 +78,18 @@ export interface DataViewCoreProps<T> extends InteractionOptions {
57
78
  /** Bump to force a re-fetch from scratch (e.g. after an immediate edit that
58
79
  * mutated rows through the provider). */
59
80
  refreshToken?: number | string;
81
+ /** Filters active from the start, applied when the store is *created* rather
82
+ * than in an effect — so a restored view (from a link, a saved query, a
83
+ * server render) never fires an unfiltered fetch first and immediately
84
+ * supersedes it. Uncontrolled: the user's later changes win, and changing
85
+ * this prop afterwards does nothing. */
86
+ initialFilters?: ActiveFilterEntry[];
87
+ /** Sorts active from the start. Same contract as `initialFilters`. */
88
+ initialSorts?: ColumnSort[];
60
89
  }
61
90
 
62
91
  export interface DataViewSharedProps<T = any>
63
- extends FetchDataOptions, DataViewCoreProps<T> {
92
+ extends FetchDataOptions<T>, DataViewCoreProps<T> {
64
93
  /** Configurable table actions shown in a selection-aware toolbar.
65
94
  * When provided, the actions toolbar renders alongside the existing
66
95
  * edit toolbar. Actions are filtered by the current selection cardinality. */