@macrostrat/data-sheet 4.0.0-dev3 → 4.0.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 (212) hide show
  1. package/CHANGELOG.md +56 -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 +51 -32
  30. package/dist/actions/selection.cjs.map +1 -1
  31. package/dist/actions/selection.d.ts +3 -7
  32. package/dist/actions/selection.js +51 -32
  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 +3 -3
  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 +73 -54
  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
@@ -1,6 +1,7 @@
1
- import { Spec } from 'immutability-helper';
2
- import { PostgrestFilterBuilder, PostgrestQueryBuilder } from '@supabase/postgrest-js';
1
+ import { PostgrestFilterBuilder } from '@supabase/postgrest-js';
3
2
  import { RowRegion } from './loading-utils.ts';
3
+ import { ColumnSort } from '../types.ts';
4
+ export type FetchMode = "scroll" | "paged";
4
5
  export interface PostgrestOrder<T> {
5
6
  key: string;
6
7
  ascending?: boolean;
@@ -25,42 +26,28 @@ export interface PostgrestFilter {
25
26
  }
26
27
  export declare function standardizeFilter(columnFilter: PostgrestColumnFilter): PostgrestFilter;
27
28
  export declare function applyColumnFilters(req: PostgrestFilterBuilder<any, any, any, any>, filters: PostgrestColumnFilter[]): PostgrestFilterBuilder<any, any, any, any, unknown, unknown, unknown>;
28
- type LazyLoaderAction<T> = {
29
- type: "start-loading";
30
- } | {
31
- type: "loaded";
32
- data: T[];
33
- offset: number;
34
- totalSize: number;
35
- } | {
36
- type: "error";
37
- error: Error;
38
- } | {
39
- type: "update-data";
40
- changes: Spec<T[]>;
41
- } | {
42
- type: "reset";
43
- } | {
44
- type: "start-reload";
45
- };
46
- type SortAndFilterOptions = {
47
- /** Column-level sort state, managed externally. When provided, overrides
48
- * the `order` prop for query building. */
49
- order?: PostgrestOrder<any>[];
50
- filters?: PostgrestFilter[];
29
+ /** Current page index (0-based) for paged fetch mode. */
30
+ export declare const chunkPageAtom: import('jotai').PrimitiveAtom<number> & {
31
+ init: number;
51
32
  };
52
- type LazyLoaderOptions = Omit<QueryConfig, "count" | "offset" | "limit"> & SortAndFilterOptions & {
53
- chunkSize?: number;
54
- sortKey?: string;
33
+ /** Bump this to force the active chunk loader to reset and re-fetch from
34
+ * scratch — e.g. after a mutation (save/delete) that invalidates loaded rows. */
35
+ export declare const dataRefreshTokenAtom: import('jotai').PrimitiveAtom<number> & {
36
+ init: number;
55
37
  };
56
- interface QueryConfig extends SortAndFilterOptions {
57
- columns?: string | string[];
58
- count?: "exact" | "estimated";
59
- limit?: number;
60
- identityKey: string;
61
- lastLoadedRow?: any;
62
- lastLoadedRowIndex: number;
38
+ /** Footer state for the optional bottom-of-table indicator: rows loaded, the
39
+ * source total when known, load status, and — in paged mode — the current
40
+ * page and total pages. */
41
+ export interface TableFooterInfo {
42
+ mode: FetchMode;
43
+ loaded: number;
44
+ total: number | null;
45
+ loading: boolean;
46
+ page: number;
47
+ pageSize: number;
48
+ totalPages: number | null;
63
49
  }
50
+ export declare const tableFooterAtom: import('jotai').Atom<TableFooterInfo>;
64
51
  export interface ViewInfo {
65
52
  visibleRegion: RowRegion;
66
53
  totalCount: number | null;
@@ -69,17 +56,128 @@ export interface ViewInfo {
69
56
  }
70
57
  export declare const viewInfoAtom: import('jotai').Atom<ViewInfo>;
71
58
  export declare function useScrollHandler(): ((visibleCells: RowRegion) => void) & import('underscore').Cancelable;
72
- export declare function usePostgRESTLazyLoader(endpoint: string, table: string, config?: LazyLoaderOptions): {
73
- data: any;
74
- loading: any;
75
- dispatch: (action: LazyLoaderAction<any>) => any;
76
- getClient: () => PostgrestQueryBuilder<{
77
- PostgrestVersion: "12";
78
- }, any, any, string, unknown>;
79
- };
80
- export declare function useTestLazyLoader(config?: LazyLoaderOptions): {
59
+ /** The active view state (a filter's id / column / config), passed to a
60
+ * `fetchChunk`. A server provider translates `columnKey` + `state` into a
61
+ * query; a local (in-memory) provider applies `predicate` directly. Both come
62
+ * from the same `TableFilter`, so one filter definition serves either target. */
63
+ export interface FetchDataFilter {
64
+ id: string;
65
+ columnKey?: string;
66
+ state: any;
67
+ /** Client-side row predicate (from the `TableFilter`). Server providers
68
+ * ignore it and translate `columnKey` + `state` instead. */
69
+ predicate?: (row: any, state: any) => boolean;
70
+ }
71
+ /** Parameters passed to a `fetchChunk` implementation for one window. */
72
+ export interface FetchDataParams {
73
+ /** Row offset of the requested chunk (chunk-aligned). */
74
+ offset: number;
75
+ /** Maximum rows to return. */
76
+ limit: number;
77
+ /** Aborts when the request is superseded (view change / unmount). */
78
+ signal: AbortSignal;
79
+ /** Active sorts, in priority order. */
80
+ sorts: ColumnSort[];
81
+ /** Active filters (id + column + config). */
82
+ filters: FetchDataFilter[];
83
+ /** In scroll mode, the already-loaded row immediately before this chunk
84
+ * (and its data-array index), or `null` at the start / in paged mode. Keyset
85
+ * sources can page from this cursor (e.g. `WHERE key > cursor`) instead of a
86
+ * slow `OFFSET`; offset-based sources can ignore it. */
87
+ cursor?: {
88
+ row: any;
89
+ index: number;
90
+ } | null;
91
+ }
92
+ /** Result of a `fetchChunk` call. `totalCount` reports the source length when
93
+ * known (drives sparse-array pre-sizing and a proportional scrollbar); omit it
94
+ * for unknown-length sources (the array grows as chunks arrive). */
95
+ export interface FetchDataResult<T = any> {
96
+ rows: T[];
97
+ totalCount?: number | null;
98
+ }
99
+ export type FetchData<T = any> = (params: FetchDataParams) => Promise<FetchDataResult<T>>;
100
+ /**
101
+ * A table's data source, addressed uniformly whether it's an in-memory array or
102
+ * a remote backend. `fetchChunk` returns a window with the active sorts/filters
103
+ * already applied (in memory by the local provider, in SQL by a server one);
104
+ * `identity` addresses a row for edits/mutations — stable across re-sorts,
105
+ * unlike an array index. The mutation ops are present only for editable /
106
+ * persisting sources. The in-memory case (`createLocalProvider`) is just the
107
+ * degenerate implementation, so local and server tables share one path.
108
+ */
109
+ export interface TableDataProvider<T = any> {
110
+ fetchData(params: FetchDataParams): Promise<FetchDataResult<T>>;
111
+ identity(row: T): string | number;
112
+ saveRows?(rows: T[]): Promise<void>;
113
+ deleteRows?(ids: Array<string | number>): Promise<void>;
114
+ insertRow?(row: Partial<T>): Promise<void>;
115
+ }
116
+ /**
117
+ * The degenerate provider: an in-memory array. `fetchChunk` applies the active
118
+ * filter predicates and sorts over the array and returns the requested slice
119
+ * plus the (fully-known) total — the same view engine used for client-side
120
+ * tables, expressed as a provider.
121
+ */
122
+ export declare function createLocalProvider<T = any>(data: T[], options?: {
123
+ identity?: (row: T) => string | number;
124
+ }): TableDataProvider<T>;
125
+ /** Multi-key row comparator (priority order; nulls first when ascending),
126
+ * shared by the local provider and any other in-memory sort. */
127
+ export declare function compareRowsBySorts(sorts: ColumnSort[]): (a: any, b: any) => number;
128
+ export interface FetchDataOptions {
129
+ pageSize?: number;
130
+ fetchMode?: FetchMode;
131
+ }
132
+ /**
133
+ * A generic, backend-agnostic windowed data source. Give it a `fetchChunk`
134
+ * function and it drives the sheet's lazy loading: it loads the chunk covering
135
+ * the first unloaded visible row, pre-sizes the sparse array from `totalCount`,
136
+ * threads the active sorts/filters through so the source can apply them
137
+ * server-side, and re-fetches from scratch when the view state changes. This
138
+ * is the unified seam that upstreams bespoke loaders (`fetchChunk` receives the
139
+ * view state; there's no separate adapter object).
140
+ *
141
+ * Call it from a component rendered inside `DataSheet` (see `ChunkLoaderManager`).
142
+ */
143
+ export declare function useDataLoader<T = any>(fetchChunk: FetchData<T>, options?: FetchDataOptions): {
81
144
  data: any;
82
145
  loading: any;
83
- dispatch: (action: LazyLoaderAction<any>) => any;
146
+ error: any;
84
147
  };
85
- export {};
148
+ /**
149
+ * Build a `fetchChunk` backed by a PostgREST endpoint, for use with
150
+ * `useChunkLoader` / `ChunkLoaderManager`. It reuses `buildQuery`, so it pages
151
+ * with **keyset pagination** (via the loader's `cursor`) whenever the query is
152
+ * ordered — falling back to `OFFSET` only when it isn't — and threads the
153
+ * active store sorts/filters into the query. The total count is requested only
154
+ * on the initial (cursorless) fetch, since a keyset cursor filter would skew it.
155
+ */
156
+ export declare function createPostgRESTFetchChunk<T = any>(config: {
157
+ endpoint: string;
158
+ table: string;
159
+ identityKey: string;
160
+ columns?: string | string[];
161
+ /** Order applied before the active column sorts (identity key appended last). */
162
+ baseOrder?: PostgrestOrder<any>[];
163
+ /** A transform over the query builder, applied as a base filter (the `filter` prop). */
164
+ baseFilter?: (q: PostgrestFilterBuilder<any, any, any, any>) => PostgrestFilterBuilder<any, any, any, any>;
165
+ /** Translate a stored filter entry to a `PostgrestFilter` (return `null` to
166
+ * skip). Defaults to the `{ key, operator, value }` column-filter shape. */
167
+ translateFilter?: (f: FetchDataFilter) => PostgrestFilter | null;
168
+ }): FetchData<T>;
169
+ /**
170
+ * A full PostgREST `TableDataProvider`: the read side (`fetchData` + row
171
+ * `identity`) plus persistence — `saveRows` (upsert) and `deleteRows` (by
172
+ * identity). Pass it to `DataSheet`'s `provider` prop. The mutation methods
173
+ * throw on error so the Save action surfaces it.
174
+ */
175
+ export declare function createPostgRESTProvider<T = any>(config: {
176
+ endpoint: string;
177
+ table: string;
178
+ identityKey: string;
179
+ columns?: string | string[];
180
+ baseOrder?: PostgrestOrder<any>[];
181
+ baseFilter?: (q: PostgrestFilterBuilder<any, any, any, any>) => PostgrestFilterBuilder<any, any, any, any>;
182
+ translateFilter?: (f: FetchDataFilter) => PostgrestFilter | null;
183
+ }): TableDataProvider<T>;