@macrostrat/data-sheet 4.1.1 → 4.2.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 (303) hide show
  1. package/CHANGELOG.md +34 -0
  2. package/dist/actions/builtin.cjs +1 -1
  3. package/dist/actions/builtin.cjs.map +1 -1
  4. package/dist/actions/builtin.d.ts +0 -2
  5. package/dist/actions/builtin.js +1 -1
  6. package/dist/actions/builtin.js.map +1 -1
  7. package/dist/actions/clipboard.cjs +1 -1
  8. package/dist/actions/clipboard.cjs.map +1 -1
  9. package/dist/actions/clipboard.d.ts +3 -2
  10. package/dist/actions/clipboard.js +1 -1
  11. package/dist/actions/clipboard.js.map +1 -1
  12. package/dist/actions/column-controls.cjs +7 -196
  13. package/dist/actions/column-controls.cjs.map +1 -1
  14. package/dist/actions/column-controls.d.ts +1 -1
  15. package/dist/actions/column-controls.js +5 -194
  16. package/dist/actions/column-controls.js.map +1 -1
  17. package/dist/actions/column-filter.cjs +24 -73
  18. package/dist/actions/column-filter.cjs.map +1 -1
  19. package/dist/actions/column-filter.d.ts +6 -4
  20. package/dist/actions/column-filter.js +25 -74
  21. package/dist/actions/column-filter.js.map +1 -1
  22. package/dist/actions/context.cjs +147 -0
  23. package/dist/actions/context.cjs.map +1 -0
  24. package/dist/actions/context.d.ts +93 -0
  25. package/dist/actions/context.js +145 -0
  26. package/dist/actions/context.js.map +1 -0
  27. package/dist/actions/edit-actions.cjs.map +1 -1
  28. package/dist/actions/edit-actions.d.ts +3 -1
  29. package/dist/actions/edit-actions.js.map +1 -1
  30. package/dist/actions/index.d.ts +2 -3
  31. package/dist/actions/selection.cjs +70 -115
  32. package/dist/actions/selection.cjs.map +1 -1
  33. package/dist/actions/selection.d.ts +22 -12
  34. package/dist/actions/selection.js +71 -114
  35. package/dist/actions/selection.js.map +1 -1
  36. package/dist/actions/table-actions.cjs +41 -0
  37. package/dist/actions/table-actions.cjs.map +1 -0
  38. package/dist/actions/{table-controls.d.ts → table-actions.d.ts} +0 -4
  39. package/dist/actions/{table-controls.js → table-actions.js} +2 -23
  40. package/dist/actions/table-actions.js.map +1 -0
  41. package/dist/actions/types.d.ts +11 -89
  42. package/dist/components/cell-detail.cjs +6 -6
  43. package/dist/components/cell-detail.cjs.map +1 -1
  44. package/dist/components/cell-detail.js +1 -1
  45. package/dist/components/colors.cjs.map +1 -1
  46. package/dist/components/colors.js.map +1 -1
  47. package/dist/components/editor-popup.cjs +7 -7
  48. package/dist/components/editor-popup.cjs.map +1 -1
  49. package/dist/components/editor-popup.js +1 -1
  50. package/dist/components/index.d.ts +2 -1
  51. package/dist/components/indicators/filter-and-sort.cjs +378 -0
  52. package/dist/components/indicators/filter-and-sort.cjs.map +1 -0
  53. package/dist/components/indicators/filter-and-sort.d.ts +59 -0
  54. package/dist/components/indicators/filter-and-sort.js +376 -0
  55. package/dist/components/indicators/filter-and-sort.js.map +1 -0
  56. package/dist/components/indicators/filter-and-sort.module.sass.cjs +16 -0
  57. package/dist/components/indicators/filter-and-sort.module.sass.cjs.map +1 -0
  58. package/dist/components/indicators/filter-and-sort.module.sass.js +14 -0
  59. package/dist/components/indicators/filter-and-sort.module.sass.js.map +1 -0
  60. package/dist/components/indicators/index.d.ts +4 -0
  61. package/dist/components/indicators/selection.cjs +113 -0
  62. package/dist/components/indicators/selection.cjs.map +1 -0
  63. package/dist/components/indicators/selection.d.ts +3 -0
  64. package/dist/components/indicators/selection.js +111 -0
  65. package/dist/components/indicators/selection.js.map +1 -0
  66. package/dist/components/indicators/selection.module.sass.cjs +19 -0
  67. package/dist/components/indicators/selection.module.sass.cjs.map +1 -0
  68. package/dist/components/indicators/selection.module.sass.js +17 -0
  69. package/dist/components/indicators/selection.module.sass.js.map +1 -0
  70. package/dist/components/indicators/unified-filters.cjs +130 -0
  71. package/dist/components/indicators/unified-filters.cjs.map +1 -0
  72. package/dist/components/indicators/unified-filters.d.ts +10 -0
  73. package/dist/components/indicators/unified-filters.js +130 -0
  74. package/dist/components/indicators/unified-filters.js.map +1 -0
  75. package/dist/components/indicators/view-info.cjs +59 -0
  76. package/dist/components/indicators/view-info.cjs.map +1 -0
  77. package/dist/components/{view-info.d.ts → indicators/view-info.d.ts} +1 -0
  78. package/dist/components/{view-info.js → indicators/view-info.js} +17 -13
  79. package/dist/components/indicators/view-info.js.map +1 -0
  80. package/dist/components/text-areas.cjs +5 -5
  81. package/dist/components/text-areas.cjs.map +1 -1
  82. package/dist/components/text-areas.js +1 -1
  83. package/dist/components/toolbars/actions-toolbar.cjs +185 -0
  84. package/dist/components/toolbars/actions-toolbar.cjs.map +1 -0
  85. package/dist/{actions/toolbar.d.ts → components/toolbars/actions-toolbar.d.ts} +9 -5
  86. package/dist/{actions/toolbar.js → components/toolbars/actions-toolbar.js} +37 -112
  87. package/dist/components/toolbars/actions-toolbar.js.map +1 -0
  88. package/dist/components/toolbars/actions-toolbar.module.sass.cjs +29 -0
  89. package/dist/components/toolbars/actions-toolbar.module.sass.cjs.map +1 -0
  90. package/dist/components/toolbars/actions-toolbar.module.sass.js +27 -0
  91. package/dist/components/toolbars/actions-toolbar.module.sass.js.map +1 -0
  92. package/dist/components/toolbars/active-filters.cjs +120 -0
  93. package/dist/components/toolbars/active-filters.cjs.map +1 -0
  94. package/dist/{actions/filters.d.ts → components/toolbars/active-filters.d.ts} +3 -3
  95. package/dist/components/toolbars/active-filters.js +120 -0
  96. package/dist/components/toolbars/active-filters.js.map +1 -0
  97. package/dist/components/toolbars/index.d.ts +2 -0
  98. package/dist/data-panel.cjs +291 -0
  99. package/dist/data-panel.cjs.map +1 -0
  100. package/dist/data-panel.d.ts +110 -0
  101. package/dist/data-panel.js +289 -0
  102. package/dist/data-panel.js.map +1 -0
  103. package/dist/data-panel.module.sass.cjs +40 -0
  104. package/dist/data-panel.module.sass.cjs.map +1 -0
  105. package/dist/data-panel.module.sass.js +38 -0
  106. package/dist/data-panel.module.sass.js.map +1 -0
  107. package/dist/{core.cjs → data-sheet.cjs} +123 -190
  108. package/dist/data-sheet.cjs.map +1 -0
  109. package/dist/data-sheet.css +241 -13
  110. package/dist/data-sheet.d.ts +16 -0
  111. package/dist/{core.js → data-sheet.js} +92 -159
  112. package/dist/data-sheet.js.map +1 -0
  113. package/dist/data-view.cjs +47 -0
  114. package/dist/data-view.cjs.map +1 -0
  115. package/dist/data-view.d.ts +15 -0
  116. package/dist/data-view.js +45 -0
  117. package/dist/data-view.js.map +1 -0
  118. package/dist/filters/operators.cjs +19 -2
  119. package/dist/filters/operators.cjs.map +1 -1
  120. package/dist/filters/operators.d.ts +4 -3
  121. package/dist/filters/operators.js +19 -2
  122. package/dist/filters/operators.js.map +1 -1
  123. package/dist/index.cjs +106 -47
  124. package/dist/index.cjs.map +1 -1
  125. package/dist/index.d.ts +4 -3
  126. package/dist/index.js +76 -17
  127. package/dist/index.js.map +1 -1
  128. package/dist/notifications.cjs +4 -4
  129. package/dist/notifications.cjs.map +1 -1
  130. package/dist/notifications.js +1 -1
  131. package/dist/postgrest-table/data-loaders.cjs +128 -95
  132. package/dist/postgrest-table/data-loaders.cjs.map +1 -1
  133. package/dist/postgrest-table/data-loaders.d.ts +52 -82
  134. package/dist/postgrest-table/data-loaders.js +109 -76
  135. package/dist/postgrest-table/data-loaders.js.map +1 -1
  136. package/dist/postgrest-table/index.cjs +18 -17
  137. package/dist/postgrest-table/index.cjs.map +1 -1
  138. package/dist/postgrest-table/index.d.ts +4 -3
  139. package/dist/postgrest-table/index.js +9 -8
  140. package/dist/postgrest-table/index.js.map +1 -1
  141. package/dist/{utils → provider}/column-spec.cjs +23 -9
  142. package/dist/provider/column-spec.cjs.map +1 -0
  143. package/dist/{utils → provider}/column-spec.d.ts +73 -2
  144. package/dist/{utils → provider}/column-spec.js +24 -10
  145. package/dist/provider/column-spec.js.map +1 -0
  146. package/dist/provider/core.cjs +382 -0
  147. package/dist/provider/core.cjs.map +1 -0
  148. package/dist/provider/core.d.ts +74 -0
  149. package/dist/provider/core.js +380 -0
  150. package/dist/provider/core.js.map +1 -0
  151. package/dist/provider/index.d.ts +7 -0
  152. package/dist/provider/interactions.cjs +128 -0
  153. package/dist/provider/interactions.cjs.map +1 -0
  154. package/dist/provider/interactions.d.ts +39 -0
  155. package/dist/provider/interactions.js +128 -0
  156. package/dist/provider/interactions.js.map +1 -0
  157. package/dist/provider/selection.cjs +29 -0
  158. package/dist/provider/selection.cjs.map +1 -0
  159. package/dist/provider/selection.d.ts +9 -0
  160. package/dist/provider/selection.js +29 -0
  161. package/dist/provider/selection.js.map +1 -0
  162. package/dist/provider/table-data.cjs +92 -0
  163. package/dist/provider/table-data.cjs.map +1 -0
  164. package/dist/provider/table-data.d.ts +81 -0
  165. package/dist/provider/table-data.js +92 -0
  166. package/dist/provider/table-data.js.map +1 -0
  167. package/dist/provider/types.cjs +22 -0
  168. package/dist/provider/types.cjs.map +1 -0
  169. package/dist/provider/types.d.ts +256 -0
  170. package/dist/provider/types.js +22 -0
  171. package/dist/provider/types.js.map +1 -0
  172. package/dist/{zustand-store.cjs → provider/zustand-store.cjs} +36 -23
  173. package/dist/provider/zustand-store.cjs.map +1 -0
  174. package/dist/{zustand-store.js → provider/zustand-store.js} +21 -8
  175. package/dist/provider/zustand-store.js.map +1 -0
  176. package/dist/{cell-renderer.cjs → renderers/cell-renderer.cjs} +67 -34
  177. package/dist/renderers/cell-renderer.cjs.map +1 -0
  178. package/dist/{cell-renderer.d.ts → renderers/cell-renderer.d.ts} +1 -2
  179. package/dist/{cell-renderer.js → renderers/cell-renderer.js} +65 -32
  180. package/dist/renderers/cell-renderer.js.map +1 -0
  181. package/dist/renderers/column-header-cell.cjs +21 -13
  182. package/dist/renderers/column-header-cell.cjs.map +1 -1
  183. package/dist/renderers/column-header-cell.d.ts +3 -2
  184. package/dist/renderers/column-header-cell.js +20 -12
  185. package/dist/renderers/column-header-cell.js.map +1 -1
  186. package/dist/renderers/index.d.ts +1 -0
  187. package/dist/types.cjs +7 -19
  188. package/dist/types.cjs.map +1 -1
  189. package/dist/types.d.ts +117 -229
  190. package/dist/types.js +7 -19
  191. package/dist/types.js.map +1 -1
  192. package/dist/utils/atoms.cjs +24 -0
  193. package/dist/utils/atoms.cjs.map +1 -0
  194. package/dist/utils/atoms.d.ts +4 -0
  195. package/dist/utils/atoms.js +24 -0
  196. package/dist/utils/atoms.js.map +1 -0
  197. package/dist/utils/debug-overlay.cjs.map +1 -1
  198. package/dist/utils/debug-overlay.js.map +1 -1
  199. package/dist/utils/index.d.ts +2 -3
  200. package/dist/utils/key-handling.cjs +140 -139
  201. package/dist/utils/key-handling.cjs.map +1 -1
  202. package/dist/utils/key-handling.d.ts +4 -2
  203. package/dist/utils/key-handling.js +136 -135
  204. package/dist/utils/key-handling.js.map +1 -1
  205. package/dist/utils/validation.cjs +6 -1
  206. package/dist/utils/validation.cjs.map +1 -1
  207. package/dist/utils/validation.d.ts +1 -1
  208. package/dist/utils/validation.js +6 -1
  209. package/dist/utils/validation.js.map +1 -1
  210. package/package.json +4 -3
  211. package/src/actions/builtin.ts +1 -4
  212. package/src/actions/clipboard.ts +4 -3
  213. package/src/actions/column-controls.ts +12 -245
  214. package/src/actions/column-filter.ts +28 -92
  215. package/src/actions/context.ts +299 -0
  216. package/src/actions/edit-actions.ts +3 -1
  217. package/src/actions/index.ts +2 -3
  218. package/src/actions/selection.ts +109 -156
  219. package/src/actions/{table-controls.ts → table-actions.ts} +0 -24
  220. package/src/actions/types.ts +17 -101
  221. package/src/components/colors.ts +1 -1
  222. package/src/components/index.ts +2 -1
  223. package/src/components/indicators/filter-and-sort.module.sass +13 -0
  224. package/src/components/indicators/filter-and-sort.ts +478 -0
  225. package/src/components/indicators/index.ts +4 -0
  226. package/src/components/indicators/selection.module.sass +22 -0
  227. package/src/components/indicators/selection.ts +141 -0
  228. package/src/components/indicators/unified-filters.ts +161 -0
  229. package/src/components/{view-info.ts → indicators/view-info.ts} +16 -27
  230. package/src/{actions/toolbar.module.sass → components/toolbars/actions-toolbar.module.sass} +17 -4
  231. package/src/{actions/toolbar.ts → components/toolbars/actions-toolbar.ts} +49 -150
  232. package/src/components/toolbars/active-filters.ts +150 -0
  233. package/src/components/toolbars/index.ts +2 -0
  234. package/src/data-panel.module.sass +185 -0
  235. package/src/data-panel.ts +556 -0
  236. package/src/{core.ts → data-sheet.ts} +145 -330
  237. package/src/data-view.ts +70 -0
  238. package/src/filters/operators.ts +33 -3
  239. package/src/index.ts +4 -3
  240. package/src/postgrest-table/data-loaders.ts +244 -171
  241. package/src/postgrest-table/index.ts +10 -9
  242. package/src/{utils → provider}/column-spec.ts +30 -15
  243. package/src/provider/core.ts +585 -0
  244. package/src/provider/index.ts +7 -0
  245. package/src/provider/interactions.ts +161 -0
  246. package/src/provider/selection.ts +31 -0
  247. package/src/provider/table-data.ts +178 -0
  248. package/src/provider/types.ts +273 -0
  249. package/src/{zustand-store.ts → provider/zustand-store.ts} +35 -14
  250. package/src/{cell-renderer.ts → renderers/cell-renderer.ts} +140 -57
  251. package/src/renderers/column-header-cell.ts +21 -14
  252. package/src/renderers/index.ts +1 -0
  253. package/src/types.ts +137 -239
  254. package/src/utils/atoms.ts +28 -0
  255. package/src/utils/debug-overlay.ts +1 -1
  256. package/src/utils/index.ts +2 -8
  257. package/src/utils/key-handling.ts +170 -164
  258. package/src/utils/validation.ts +7 -2
  259. package/dist/actions/filters.cjs +0 -139
  260. package/dist/actions/filters.cjs.map +0 -1
  261. package/dist/actions/filters.js +0 -139
  262. package/dist/actions/filters.js.map +0 -1
  263. package/dist/actions/table-controls.cjs +0 -62
  264. package/dist/actions/table-controls.cjs.map +0 -1
  265. package/dist/actions/table-controls.js.map +0 -1
  266. package/dist/actions/toolbar.cjs +0 -260
  267. package/dist/actions/toolbar.cjs.map +0 -1
  268. package/dist/actions/toolbar.js.map +0 -1
  269. package/dist/actions/toolbar.module.sass.cjs +0 -27
  270. package/dist/actions/toolbar.module.sass.cjs.map +0 -1
  271. package/dist/actions/toolbar.module.sass.js +0 -25
  272. package/dist/actions/toolbar.module.sass.js.map +0 -1
  273. package/dist/cell-renderer.cjs.map +0 -1
  274. package/dist/cell-renderer.js.map +0 -1
  275. package/dist/components/view-info.cjs +0 -55
  276. package/dist/components/view-info.cjs.map +0 -1
  277. package/dist/components/view-info.js.map +0 -1
  278. package/dist/core.cjs.map +0 -1
  279. package/dist/core.d.ts +0 -117
  280. package/dist/core.js.map +0 -1
  281. package/dist/provider.cjs +0 -197
  282. package/dist/provider.cjs.map +0 -1
  283. package/dist/provider.d.ts +0 -26
  284. package/dist/provider.js +0 -195
  285. package/dist/provider.js.map +0 -1
  286. package/dist/table-updates/data-parameter.d.ts +0 -14
  287. package/dist/table-updates/filter.d.ts +0 -16
  288. package/dist/table-updates/index.d.ts +0 -19
  289. package/dist/utils/column-spec.cjs.map +0 -1
  290. package/dist/utils/column-spec.js.map +0 -1
  291. package/dist/utils/index.cjs +0 -9
  292. package/dist/utils/index.cjs.map +0 -1
  293. package/dist/utils/index.js +0 -9
  294. package/dist/utils/index.js.map +0 -1
  295. package/dist/zustand-store.cjs.map +0 -1
  296. package/dist/zustand-store.js.map +0 -1
  297. package/src/actions/filters.ts +0 -176
  298. package/src/components/actions.module.sass +0 -8
  299. package/src/provider.ts +0 -267
  300. package/src/table-updates/data-parameter.ts +0 -44
  301. package/src/table-updates/filter.ts +0 -124
  302. package/src/table-updates/index.ts +0 -239
  303. /package/dist/{zustand-store.d.ts → provider/zustand-store.d.ts} +0 -0
@@ -0,0 +1,556 @@
1
+ /**
2
+ * DataPanel — a card/list renderer over the same headless core as `DataSheet`.
3
+ *
4
+ * The two components differ in only two dimensions: the **view** (cards vs. the
5
+ * Blueprint cell grid) and **edit granularity** (immediate per-item vs. a
6
+ * batched pending-ops stack). Everything else — provider-driven windowed
7
+ * loading, `{sorts, filters}` view state, the selection set, and set-based
8
+ * actions — is the shared substrate, reused here unchanged:
9
+ *
10
+ * - `DataSheetProvider` supplies the jotai+zustand store.
11
+ * - `useDataLoader(provider.fetchData)` drives windowed loading and threads the
12
+ * active store sorts/filters through so a server provider applies them.
13
+ * - `ActionsToolbar` + `FilterBar` render selection-aware actions and the
14
+ * active sort/filter tags — they read the store, not the table.
15
+ *
16
+ * The only list-specific pieces are: rows rendered as cards via a consumer
17
+ * `itemComponent`; selection expressed as `FULL_ROWS` regions (so the existing
18
+ * row-targeted `TableAction`s apply); an infinite-scroll sentinel that advances
19
+ * the loader's visible region; and `FacetControls`, which stands in for the
20
+ * column-header dropdown the list doesn't have (a menu to add a column filter /
21
+ * sort from the column-declared `filterable` / `sortable` capabilities).
22
+ *
23
+ * See [[Data list editors]] in the Macrostrat workbench for the design.
24
+ */
25
+ import h from "./data-panel.module.sass";
26
+ import {
27
+ ComponentType,
28
+ CSSProperties,
29
+ MouseEvent as ReactMouseEvent,
30
+ ReactNode,
31
+ UIEvent as ReactUIEvent,
32
+ useCallback,
33
+ useEffect,
34
+ useMemo,
35
+ useRef,
36
+ useState,
37
+ } from "react";
38
+ import { Icon, Spinner } from "@blueprintjs/core";
39
+ import {
40
+ anchorRefAtom,
41
+ ctx,
42
+ dataProviderAtom,
43
+ DataSheetProvider,
44
+ DataViewRendererType,
45
+ FetchData,
46
+ interactionOptionsAtom,
47
+ selectionAtom,
48
+ splitDataProviderProps,
49
+ useSelector,
50
+ } from "./provider";
51
+ import {
52
+ buildDataViewSelection,
53
+ getSelectedRowIndices,
54
+ rowIndicesToRegions,
55
+ TableAction,
56
+ } from "./actions";
57
+ import {
58
+ autoLoadPagesAtom,
59
+ useDataLoader,
60
+ useLoadControls,
61
+ } from "./postgrest-table";
62
+ import classNames from "classnames";
63
+ import {
64
+ ActionsToolbar,
65
+ LoadProgressIndicator,
66
+ useDataPanelControls,
67
+ } from "./components";
68
+ import { DataViewSharedProps, FetchDataOptions } from "./types";
69
+ import { atom } from "jotai";
70
+ import { passThroughSet } from "./utils";
71
+
72
+ export enum DataPanelToolbarStyle {
73
+ BORDERED = "bordered",
74
+ FADE = "fade",
75
+ MINIMAL = "minimal",
76
+ }
77
+
78
+ /** Props for a custom scroll-body layout component. It receives the
79
+ * already-rendered, selection-wrapped item cards and lays them out however it
80
+ * likes (a grid, sections, sticky headers, its own windowing). The panel owns
81
+ * the surrounding scroll container and the loading sentinel; the scroll body
82
+ * only arranges the items. */
83
+ export interface ScrollBodyProps {
84
+ /** The rendered item cards (each wrapped for selection styling). */
85
+ children: ReactNode;
86
+ }
87
+
88
+ /** Props handed to a consumer's card renderer for one row. */
89
+ export interface ItemComponentProps<T = any> {
90
+ /** The row's data. */
91
+ data: T;
92
+ /** Underlying data-row index (stable within a loaded window). */
93
+ index: number;
94
+ /** Whether this row is in the current selection. */
95
+ selected: boolean;
96
+ /** Whether the row can be selected */
97
+ selectable: boolean;
98
+ /** Select this row. Pass the click's `MouseEvent` (or `React.MouseEvent`) to
99
+ * honor shift / cmd / ctrl automatically — the usual wiring is
100
+ * `onClick: onSelect`. Or pass an explicit `SelectModifiers` object; no
101
+ * argument means a plain (replace) select. */
102
+ onSelect: (arg?: SelectModifiers | ReactMouseEvent) => void;
103
+ }
104
+
105
+ export interface DataPanelProps<T = any> extends DataViewSharedProps<T> {
106
+ /** Renders one row as a card. */
107
+ itemComponent: ComponentType<ItemComponentProps<T>>;
108
+ /** Arbitrary nodes for the bottom status row (beside the loaded/total
109
+ * counter). Pass `false` to drop the status row entirely — e.g. when the
110
+ * counter is folded into an inline footer instead. */
111
+ statusBar?: ReactNode | false;
112
+ /** Custom header controls, replacing the default `FacetControls` +
113
+ * `FilterBar`. Rendered inside the provider, so it can drive sort/filter via
114
+ * the exported building blocks (`FacetControls`, `FilterBar`) and the store
115
+ * hooks (`useStoreAPI` / `useSelector`). The selection `ActionsToolbar` still
116
+ * renders above it. Omit for the sane default. */
117
+ toolbar?: ReactNode;
118
+ /** A filter/detail sidebar beside the scroll body (its own scroll). Rendered
119
+ * inside the provider, so a custom filter panel drives sort/filter through
120
+ * the store hooks — the alternative placement to the top `toolbar`. */
121
+ sidebar?: ReactNode;
122
+ /** Footer content. Rendered inside the provider, so it reads live load state
123
+ * from the store via `useLoadControls()` (loadMore / loading / hasMore /
124
+ * loaded / total / paused) rather than a passed-down contract — a footer, a
125
+ * status line, or a "Load more" button all just call the hook. */
126
+ contentFooter?: ReactNode;
127
+ /** Auto-load this many pages per burst, then pause: a paused panel stops
128
+ * fetching on scroll until `useLoadControls().loadMore()` starts the next
129
+ * burst (e.g. a footer "Load more" button). Omit for unbounded auto-scroll. */
130
+ // TODO: we may deprecate this for opt-in scrolling
131
+ autoLoadPages?: number;
132
+ /** Custom layout for the item cards — the seam for anything other than a
133
+ * vertical list (a CSS grid for several per row, grouped sections, sticky
134
+ * sub-headers, a windowed renderer). Receives the rendered cards as
135
+ * `children`; the panel still owns the scroll container and the loading
136
+ * sentinel, so paging and selection keep working. Defaults to a vertical
137
+ * flex list. */
138
+ scrollBody?: ComponentType<ScrollBodyProps>;
139
+ className?: string;
140
+ toolbarStyle?: DataPanelToolbarStyle | string;
141
+ /** Arbitrary children rendered inside the provider, after the panel. */
142
+ children?: ReactNode;
143
+ }
144
+
145
+ /**
146
+ * Resolve the data source (shared with `DataSheet` / `DataView` via
147
+ * `useResolvedProvider`), wrap in the shared provider, and render the inner
148
+ * panel.
149
+ */
150
+ export function DataPanel<T>(props: DataPanelProps<T>) {
151
+ const [providerProps, rendererProps] = splitDataProviderProps({
152
+ ...props,
153
+ viewType: DataViewRendererType.CARDS,
154
+ });
155
+ return h(
156
+ DataSheetProvider<T>,
157
+ providerProps,
158
+ h(DataPanelRenderer<any>, rendererProps),
159
+ );
160
+ }
161
+
162
+ /** Selection modifier keys, following the familiar list idiom. */
163
+ export interface SelectModifiers {
164
+ /** cmd/ctrl — toggle this row in/out of the selection (or extend a range). */
165
+ additive?: boolean;
166
+ /** shift — select the range from the anchor (last plain/cmd click) to here. */
167
+ range?: boolean;
168
+ }
169
+
170
+ /** The card-list renderer. Assumes it is rendered inside a `DataSheetProvider`
171
+ * (the `DataPanel` wrapper, or `DataView`). Exported so a shared-store
172
+ * `DataView` can mount it directly alongside `_DataSheet`. */
173
+ export function DataPanelRenderer<T>({
174
+ itemComponent,
175
+ actions = [],
176
+ pageSize = 50,
177
+ name,
178
+ // Bottom bar
179
+ statusBar,
180
+ toolbar,
181
+ sidebar,
182
+ // Footer within content flow
183
+ contentFooter,
184
+ autoLoadPages,
185
+ scrollBody,
186
+ className,
187
+ toolbarStyle = DataPanelToolbarStyle.BORDERED,
188
+ children,
189
+ }: Omit<DataPanelProps<T>, "provider" | "fetchData" | "data" | "identity">) {
190
+ const {
191
+ provider: activeProvider,
192
+ isLocalProvider,
193
+ localCount,
194
+ } = ctx.useValue(dataProviderAtom);
195
+
196
+ // The loader is mounted as a child component (below), NOT called as a hook
197
+ // here, and only once `activeProvider` resolves. This mirrors `_DataSheet`:
198
+ // `dataProviderAtom` is synced by a parent effect that fires *after* this
199
+ // component's effects, so a hook call here would capture the placeholder
200
+ // provider on first render and — since `fetchData` isn't one of its effect
201
+ // deps — never re-fetch with the real one. A child that mounts with the real
202
+ // `fetchData` already in hand sidesteps that entirely.
203
+ // A local (in-memory) source loads all of its rows in one page; its count
204
+ // rides on the resolved provider, so the renderer no longer takes a `data`
205
+ // prop (the store is the single source of live rows).
206
+ const loaderPageSize = isLocalProvider ? Math.max(localCount, 1) : pageSize;
207
+
208
+ const data = useSelector((s) => s.data);
209
+
210
+ // Load state + pause/resume live in the store, read via `useLoadControls`
211
+ // (also available to the caller's `footer` via the same hook). The panel's
212
+ // `autoLoadPages` prop is the store's configuration input.
213
+ ctx.useSync(autoLoadPagesAtom, autoLoadPages ?? null);
214
+ const { loading, hasMore, loaded, total, paused, canLoadMore, advance } =
215
+ useLoadControls();
216
+
217
+ // Track whether the body is scrolled off the top, to gate the top fade.
218
+ // `setState` with an unchanged value is a no-op, so this only re-renders on
219
+ // the at-top ↔ scrolled transition.
220
+ const [scrolled, setScrolled] = useState(false);
221
+ const onScroll = useCallback((e: ReactUIEvent<HTMLDivElement>) => {
222
+ setScrolled(e.currentTarget.scrollTop > 4);
223
+ }, []);
224
+
225
+ const enableSelection = ctx.useValue(interactionOptionsAtom).enableSelection;
226
+ const selectedIndices = ctx.useValue(selectedRowIndicesAtom);
227
+ const select = ctx.useSet(updateSelectionAtom);
228
+
229
+ const loadedCount = useMemo(() => {
230
+ let n = 0;
231
+ for (const r of data) if (r != null) n++;
232
+ return n;
233
+ }, [data]);
234
+
235
+ // Refresh-token, rowEditing, and load controls (loadMore / pause) are all
236
+ // store-managed (see `useLoadControls`), shared with `_DataSheet` — so both
237
+ // renderers, and any footer, drive loading off one source.
238
+
239
+ // Infinite scroll. A naive "load a page when the bottom sentinel is visible"
240
+ // over-fetches: when a page's rows commit, this component re-renders
241
+ // (loadedCount changed) *before* the IntersectionObserver has re-evaluated
242
+ // the sentinel's new position, so a stale "still visible" fires a second
243
+ // load. `useBottomSentinel` re-observes the sentinel whenever the pass-through
244
+ // deps change, so every trigger reflects the *current* post-layout
245
+ // visibility — it loads one page, and only loads another if the sentinel is
246
+ // genuinely still on screen. `advance` (from the store) moves the loader one
247
+ // page without resuming a paused auto-load.
248
+ const sentinelRef = useBottomSentinel(canLoadMore ? advance : null, [
249
+ loadedCount,
250
+ canLoadMore,
251
+ ]);
252
+
253
+ const cards: ReactNode[] = [];
254
+ data.forEach((row, i) => {
255
+ if (row == null) return;
256
+ const selected = enableSelection && selectedIndices.has(i);
257
+ cards.push(
258
+ h(
259
+ "div.data-panel-item",
260
+ { key: `row-${i}`, className: classNames({ selected }) },
261
+ h(itemComponent, {
262
+ data: row,
263
+ index: i,
264
+ selected,
265
+ selectable: enableSelection,
266
+ onSelect: (arg?: SelectModifiers | ReactMouseEvent) =>
267
+ select(i, modifiersOf(arg)),
268
+ }),
269
+ ),
270
+ );
271
+ });
272
+
273
+ // The default spinner sentinel (below-placement): hidden while paused so the
274
+ // pinned footer's "Load more" takes over.
275
+ const shouldLoadNextPage = (hasMore || loading) && !paused;
276
+
277
+ // Mount the loader only once the provider resolves (see `PanelLoader`). Built
278
+ // as a real conditional — `h.if(...)` evaluates its arguments eagerly, so
279
+ // `activeProvider.fetchData` can't be referenced inside it while null.
280
+ let loaderNode: ReactNode = null;
281
+ if (activeProvider != null) {
282
+ loaderNode = h(PanelLoader, {
283
+ fetchData: activeProvider.fetchData,
284
+ pageSize: loaderPageSize,
285
+ fetchMode: isLocalProvider ? undefined : "scroll",
286
+ });
287
+ }
288
+
289
+ const coreActions = useDataPanelControls();
290
+
291
+ // Merge consumer actions with the synthesized Filter/Sort controls, deduped
292
+ // by id — consumer actions come first, so passing an action with id `filter`
293
+ // or `sort` *replaces* the built-in one (a hybrid set keeps the others).
294
+ // Mirrors the sheet's action registry contract (see `data-sheet.ts`).
295
+ const _actions = useMemo(() => {
296
+ const merged: TableAction[] = [];
297
+ const add = (list: TableAction[]) => {
298
+ for (const a of list) {
299
+ if (!merged.some((x) => x.id === a.id)) merged.push(a);
300
+ }
301
+ };
302
+ add(actions);
303
+ add(coreActions);
304
+ return merged;
305
+ }, [actions, coreActions]);
306
+
307
+ const ScrollBody = scrollBody ?? DefaultScrollBody;
308
+
309
+ // The panel owns the scroll container + the loading sentinel; the (custom or
310
+ // default) scroll body only lays out the cards. So a grid / grouped / windowed
311
+ // body composes without reimplementing paging or selection. The end-of-scroll
312
+ // region is either the default spinner sentinel or the caller's inline
313
+ // footer — both carry the sentinel ref that drives auto-load.
314
+ // The top fade is gated on being scrolled (via `.is-scrolled`), so the first
315
+ // item isn't clipped at rest.
316
+
317
+ const showStatusBar = statusBar !== false;
318
+
319
+ let defaultFooter: ReactNode = null;
320
+ if (shouldLoadNextPage) {
321
+ defaultFooter = h("div.sentinel", [h(Spinner, { size: 16 }), "Loading..."]);
322
+ } else if (!showStatusBar) {
323
+ defaultFooter = h("div.sentinel", [
324
+ h(Icon, { size: 16, icon: "tick" }),
325
+ "Loaded",
326
+ ]);
327
+ }
328
+
329
+ const _contentFooter = h(
330
+ "div.content-footer-holder",
331
+ { ref: sentinelRef },
332
+ contentFooter ?? defaultFooter,
333
+ );
334
+
335
+ // Body + optional filter/detail sidebar share a horizontal row so each
336
+ // scrolls independently.
337
+
338
+ // Bottom status row (counter + extras). `statusBar === false` drops it — e.g.
339
+ // when an inline footer carries the counter itself.
340
+ let footer: ReactNode = null;
341
+ let _statusBarContent = statusBar ?? h(DataPanelStatusBar);
342
+ if (showStatusBar) {
343
+ footer = h(
344
+ "div.data-panel-footer",
345
+ h("div.data-panel-footer-content", [_statusBarContent]),
346
+ );
347
+ }
348
+
349
+ return h(
350
+ "div.data-panel",
351
+ { className: classNames(className, "toolbar-style-" + toolbarStyle) },
352
+ [
353
+ h("div.data-panel-main", [
354
+ loaderNode,
355
+ h(
356
+ "div.data-panel-toolbar",
357
+ h(
358
+ ActionsToolbar,
359
+ {
360
+ actions: _actions,
361
+ tableName: name,
362
+ className: "data-panel-toolbar-content",
363
+ },
364
+ toolbar,
365
+ ),
366
+ ),
367
+ h(
368
+ "div.data-panel-body",
369
+ {
370
+ onScroll,
371
+ className: classNames({ "is-scrolled": scrolled }),
372
+ },
373
+ h("div.data-panel-body-content", [
374
+ h(ScrollBody, cards),
375
+ _contentFooter,
376
+ ]),
377
+ ),
378
+ footer,
379
+ ]),
380
+ h.if(sidebar != null)("div.data-panel-sidebar-container", sidebar),
381
+ children,
382
+ ],
383
+ );
384
+ }
385
+
386
+ function DataPanelStatusBar({ children }) {
387
+ /** Default status bar for the Data Panel */
388
+ return h("div.data-panel-status-bar", [children, h(LoadProgressIndicator)]);
389
+ }
390
+
391
+ /** Default scroll-body layout: a vertical flex list of cards. */
392
+ function DefaultScrollBody({ children }: { children: ReactNode }) {
393
+ return h("div.data-panel-list", children);
394
+ }
395
+
396
+ /** Runs the shared windowed loader from inside the panel (renders nothing).
397
+ * Mounted only once the real provider is resolved, so `useDataLoader` captures
398
+ * the real `fetchData` from the start (see `_DataPanel`). */
399
+ function PanelLoader<T = any>({
400
+ fetchData,
401
+ ...options
402
+ }: { fetchData: FetchData<T> } & FetchDataOptions) {
403
+ useDataLoader(fetchData, options);
404
+ return null;
405
+ }
406
+
407
+ /** Resolve the selection modifiers from either a click event (reads shift /
408
+ * cmd / ctrl) or an explicit modifier object; no argument ⇒ a plain select. */
409
+ function modifiersOf(arg?: SelectModifiers | ReactMouseEvent): SelectModifiers {
410
+ if (arg == null) return {};
411
+ if ("shiftKey" in arg) {
412
+ return { additive: arg.metaKey || arg.ctrlKey, range: arg.shiftKey };
413
+ }
414
+ return arg;
415
+ }
416
+
417
+ /**
418
+ * Bottom-sentinel infinite-scroll hook (no `react-intersection-observer`
419
+ * dependency). Calls `onVisible` when the observed element is on screen, and —
420
+ * crucially — **re-observes on every `deps` change** so the callback reflects
421
+ * the *current* post-layout visibility rather than the pre-load render.
422
+ *
423
+ * This is what avoids the double-load: a plain observer whose visibility is
424
+ * mirrored into React state lags a render behind the DOM, so a load-driven
425
+ * re-render fires a second `onVisible` before the observer catches up. By
426
+ * re-arming after each load (`deps = [loadedCount, canLoadMore]`), the observer
427
+ * emits a fresh callback for the settled layout: it fires again only if the
428
+ * sentinel is *still* visible (viewport not yet filled), so it loads exactly
429
+ * one page per bottom-reach and self-fills an underfull viewport without
430
+ * overshooting. Pass `onVisible = null` to disarm (loading / no more data).
431
+ */
432
+ function useBottomSentinel<E extends HTMLElement>(
433
+ onVisible: (() => void) | null,
434
+ deps: unknown[],
435
+ ): (el: E | null) => void {
436
+ const elRef = useRef<E | null>(null);
437
+ const observerRef = useRef<IntersectionObserver | null>(null);
438
+ const cbRef = useRef(onVisible);
439
+ cbRef.current = onVisible;
440
+
441
+ const setRef = useCallback((el: E | null) => {
442
+ elRef.current = el;
443
+ observerRef.current?.disconnect();
444
+ observerRef.current = null;
445
+ if (el == null) return;
446
+ const observer = new IntersectionObserver(
447
+ ([entry]) => {
448
+ if (entry.isIntersecting) cbRef.current?.();
449
+ },
450
+ { rootMargin: "300px" },
451
+ );
452
+ observer.observe(el);
453
+ observerRef.current = observer;
454
+ }, []);
455
+
456
+ // Re-arm after each load so the observer re-checks the settled layout.
457
+ useEffect(() => {
458
+ const el = elRef.current;
459
+ const observer = observerRef.current;
460
+ if (el == null || observer == null) return;
461
+ observer.disconnect();
462
+ observer.observe(el);
463
+ // eslint-disable-next-line react-hooks/exhaustive-deps
464
+ }, deps);
465
+
466
+ useEffect(() => () => observerRef.current?.disconnect(), []);
467
+ return setRef;
468
+ }
469
+
470
+ const rowSelectionAtom = atom((get) => {
471
+ /** Coerce selection to full rows, for use with data panel instead of data sheet. */
472
+ const selection = get(selectionAtom);
473
+ if (selection.some((r) => r.cols != null)) {
474
+ // A card list has no cells or columns. When the selection carries columns —
475
+ // inherited from a shared store the sheet also drives (a `DataView` toggle) —
476
+ // coerce it to the full rows it covers, so the toolbar shows row-scoped
477
+ // actions rather than column/cell ones for a column that isn't visible here.
478
+ // Column-only selections (no rows) collapse to nothing.
479
+ return rowIndicesToRegions(new Set(getSelectedRowIndices(selection)));
480
+ } else {
481
+ return selection;
482
+ }
483
+ }, passThroughSet(selectionAtom));
484
+
485
+ const updateSelectionAtom = atom(
486
+ null,
487
+ (get, set, index: number, mods: SelectModifiers) => {
488
+ /** Update selection from a row index and modifiers. */
489
+ const { enableMultipleSelection, enableSelection } = get(
490
+ interactionOptionsAtom,
491
+ );
492
+ if (!enableSelection) return;
493
+ const selection = get(rowSelectionAtom);
494
+ const anchorRef = get(anchorRefAtom);
495
+ const res = buildDataViewSelection(
496
+ index,
497
+ mods,
498
+ selection,
499
+ anchorRef,
500
+ enableMultipleSelection,
501
+ );
502
+ set(selectionAtom, res);
503
+ },
504
+ );
505
+
506
+ const selectedRowIndicesAtom = atom((get) => {
507
+ const sel = get(selectionAtom);
508
+ return new Set(getSelectedRowIndices(sel));
509
+ });
510
+
511
+ type ItemSelectionKeys = "onSelect" | "selected" | "selectable";
512
+
513
+ type DataCardProps = {
514
+ children: ReactNode;
515
+ className: string;
516
+ style?: CSSProperties;
517
+ } & Pick<ItemComponentProps, ItemSelectionKeys>;
518
+
519
+ export function DataCard<T = any>(props: DataCardProps) {
520
+ /** A basic card that implements the data panel's selection behavior. */
521
+ return h(
522
+ "div.data-card.data-panel-item",
523
+ {
524
+ className: classNames(props.className, {
525
+ selected: props.selected,
526
+ selectable: props.selectable,
527
+ }),
528
+ onClick: props.onSelect,
529
+ style: props.style,
530
+ },
531
+ props.children,
532
+ );
533
+ }
534
+
535
+ type DataCardInnerComponent<T> = (
536
+ props: ItemComponentProps<T>,
537
+ ) => React.ReactNode;
538
+
539
+ export function createDataCard<T>(
540
+ component: DataCardInnerComponent<T>,
541
+ extraProps = {},
542
+ ) {
543
+ return (props: ItemComponentProps<T>) => {
544
+ const { selected, selectable, onSelect } = props;
545
+ return h(
546
+ DataCard,
547
+ {
548
+ selected,
549
+ selectable,
550
+ onSelect,
551
+ ...extraProps,
552
+ },
553
+ h(component, props),
554
+ );
555
+ };
556
+ }