@viewkitjs/views 0.3.0 → 0.5.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 (288) hide show
  1. package/CHANGELOG.md +641 -0
  2. package/README.md +3 -3
  3. package/dist/atoms/CommandMenu.d.ts +1 -1
  4. package/dist/atoms/CommandMenu.js +7 -3
  5. package/dist/atoms/DrillRows.d.ts +3 -0
  6. package/dist/atoms/DrillRows.js +25 -0
  7. package/dist/atoms/PanelRows.d.ts +5 -0
  8. package/dist/atoms/PanelRows.js +40 -0
  9. package/dist/atoms/PanelSearch.d.ts +2 -0
  10. package/dist/atoms/PanelSearch.js +21 -0
  11. package/dist/atoms/RelationRoles.d.ts +2 -0
  12. package/dist/atoms/RelationRoles.js +6 -0
  13. package/dist/atoms/Row.js +2 -1
  14. package/dist/atoms/RowMenu.js +2 -1
  15. package/dist/atoms/SelectionSheet.d.ts +3 -0
  16. package/dist/atoms/SelectionSheet.js +30 -0
  17. package/dist/atoms/StatusMarker.js +3 -1
  18. package/dist/atoms/Tag.js +2 -1
  19. package/dist/atoms/defaults.js +14 -0
  20. package/dist/atoms/types.d.ts +146 -8
  21. package/dist/cells/cell-values.js +4 -2
  22. package/dist/cells/relation-wrap.js +3 -1
  23. package/dist/contract.d.ts +212 -17
  24. package/dist/contract.js +208 -6
  25. package/dist/display/boolean.js +3 -1
  26. package/dist/display/date.d.ts +1 -1
  27. package/dist/display/date.js +4 -2
  28. package/dist/display/format.js +20 -4
  29. package/dist/display/link.js +4 -3
  30. package/dist/display/multi-value.js +2 -1
  31. package/dist/display/percent.js +2 -1
  32. package/dist/display/phone.js +2 -1
  33. package/dist/display/range.js +3 -13
  34. package/dist/display/relation.js +23 -8
  35. package/dist/display/rich-text.js +2 -1
  36. package/dist/editors/ChipsEditor.d.ts +5 -1
  37. package/dist/editors/ChipsEditor.js +15 -2
  38. package/dist/editors/DateEditor.d.ts +2 -0
  39. package/dist/editors/DateEditor.js +76 -10
  40. package/dist/editors/EditorPanel.d.ts +14 -4
  41. package/dist/editors/EditorPanel.js +21 -4
  42. package/dist/editors/LocationEditor.js +35 -3
  43. package/dist/editors/NumberEditor.js +3 -2
  44. package/dist/editors/RangeEditor.d.ts +8 -0
  45. package/dist/editors/RangeEditor.js +3 -2
  46. package/dist/editors/RelationEditor.d.ts +2 -0
  47. package/dist/editors/RelationEditor.js +16 -2
  48. package/dist/editors/RelationSetEditor.d.ts +4 -2
  49. package/dist/editors/RelationSetEditor.js +36 -2
  50. package/dist/editors/SelectEditor.d.ts +5 -2
  51. package/dist/editors/SelectEditor.js +31 -4
  52. package/dist/editors/TextEditor.js +3 -1
  53. package/dist/editors/ValueListEditor.d.ts +3 -0
  54. package/dist/editors/ValueListEditor.js +10 -4
  55. package/dist/editors/edit-session.d.ts +14 -2
  56. package/dist/editors/edit-session.js +13 -5
  57. package/dist/editors/escape-rule.d.ts +12 -0
  58. package/dist/editors/escape-rule.js +8 -0
  59. package/dist/editors/open-value.js +2 -1
  60. package/dist/editors/picker-slot.d.ts +25 -0
  61. package/dist/editors/picker-slot.js +37 -0
  62. package/dist/editors/relation-picker.d.ts +44 -0
  63. package/dist/editors/relation-picker.js +49 -0
  64. package/dist/editors/relation-source.d.ts +1 -0
  65. package/dist/editors/relation-source.js +7 -1
  66. package/dist/field-row/FieldNoteLine.js +2 -1
  67. package/dist/field-row/FieldRow.js +41 -6
  68. package/dist/field-row/FieldRowLane.js +3 -1
  69. package/dist/field-row/editors/RowChipsEditor.js +1 -1
  70. package/dist/field-row/editors/RowDateEditor.js +1 -1
  71. package/dist/field-row/editors/RowEditor.js +2 -1
  72. package/dist/field-row/editors/RowRangeEditor.js +2 -1
  73. package/dist/field-row/editors/RowRelationEditor.js +2 -2
  74. package/dist/field-row/editors/RowSelectEditor.d.ts +1 -1
  75. package/dist/field-row/editors/RowSelectEditor.js +2 -2
  76. package/dist/field-row/editors/RowValueListEditor.js +1 -1
  77. package/dist/field-row/editors/host.d.ts +3 -0
  78. package/dist/field-row/editors/row-session.js +4 -1
  79. package/dist/fields/menus.d.ts +2 -0
  80. package/dist/fields/range-unit.d.ts +7 -0
  81. package/dist/fields/range-unit.js +13 -0
  82. package/dist/figures.d.ts +5 -48
  83. package/dist/figures.js +1 -63
  84. package/dist/grid/chrome/GridAddColumn.d.ts +8 -0
  85. package/dist/grid/chrome/GridAddColumn.js +66 -9
  86. package/dist/grid/chrome/GridAggregateMenu.d.ts +5 -2
  87. package/dist/grid/chrome/GridAggregateMenu.js +33 -4
  88. package/dist/grid/chrome/GridCellEditors.d.ts +9 -2
  89. package/dist/grid/chrome/GridCellEditors.js +24 -5
  90. package/dist/grid/chrome/GridCellOutline.d.ts +3 -2
  91. package/dist/grid/chrome/GridCellOutline.js +11 -1
  92. package/dist/grid/chrome/GridChipsEditor.js +1 -1
  93. package/dist/grid/chrome/GridColumnColorSection.d.ts +2 -0
  94. package/dist/grid/chrome/GridColumnColorSection.js +2 -2
  95. package/dist/grid/chrome/GridColumnDateSection.d.ts +4 -0
  96. package/dist/grid/chrome/GridColumnDateSection.js +2 -2
  97. package/dist/grid/chrome/GridColumnDurationSection.d.ts +4 -0
  98. package/dist/grid/chrome/GridColumnDurationSection.js +2 -2
  99. package/dist/grid/chrome/GridColumnMenu.d.ts +10 -6
  100. package/dist/grid/chrome/GridColumnMenu.js +62 -24
  101. package/dist/grid/chrome/GridColumnNumberSection.d.ts +4 -0
  102. package/dist/grid/chrome/GridColumnNumberSection.js +2 -2
  103. package/dist/grid/chrome/GridColumnPercentSection.d.ts +1 -0
  104. package/dist/grid/chrome/GridColumnPercentSection.js +1 -1
  105. package/dist/grid/chrome/GridColumnSortSection.d.ts +3 -3
  106. package/dist/grid/chrome/GridDateEditor.js +1 -1
  107. package/dist/grid/chrome/GridFooter.js +7 -48
  108. package/dist/grid/chrome/GridGroupMenu.d.ts +11 -5
  109. package/dist/grid/chrome/GridGroupMenu.js +28 -13
  110. package/dist/grid/chrome/GridHeader.d.ts +3 -1
  111. package/dist/grid/chrome/GridHeader.js +8 -8
  112. package/dist/grid/chrome/GridNumberEditor.js +3 -24
  113. package/dist/grid/chrome/GridRangeEditor.js +3 -2
  114. package/dist/grid/chrome/GridRelationEditor.js +2 -2
  115. package/dist/grid/chrome/GridRow.d.ts +2 -1
  116. package/dist/grid/chrome/GridRow.js +13 -37
  117. package/dist/grid/chrome/GridRowActions.js +2 -1
  118. package/dist/grid/chrome/GridRowCells.js +9 -4
  119. package/dist/grid/chrome/GridSelectEditor.js +30 -20
  120. package/dist/grid/chrome/GridStructure.d.ts +11 -4
  121. package/dist/grid/chrome/GridStructure.js +19 -7
  122. package/dist/grid/chrome/GridTable.js +138 -16
  123. package/dist/grid/chrome/GridTableSurface.d.ts +25 -12
  124. package/dist/grid/chrome/GridTableSurface.js +13 -6
  125. package/dist/grid/chrome/GridTextEditor.js +3 -1
  126. package/dist/grid/chrome/GridValueListEditor.js +1 -1
  127. package/dist/grid/chrome/cell-clipboard.d.ts +1 -1
  128. package/dist/grid/chrome/cell-clipboard.js +1 -1
  129. package/dist/grid/chrome/checks.d.ts +10 -2
  130. package/dist/grid/chrome/checks.js +17 -11
  131. package/dist/grid/chrome/column-glyph.d.ts +2 -2
  132. package/dist/grid/chrome/column-glyph.js +4 -0
  133. package/dist/grid/chrome/grid-add-column-items.d.ts +13 -0
  134. package/dist/grid/chrome/grid-add-column-items.js +40 -0
  135. package/dist/grid/chrome/grid-cell-classes.d.ts +2 -0
  136. package/dist/grid/chrome/grid-cell-classes.js +10 -4
  137. package/dist/grid/chrome/grid-column-menu-items.d.ts +75 -0
  138. package/dist/grid/chrome/grid-column-menu-items.js +263 -0
  139. package/dist/grid/chrome/grid-edit-escape.d.ts +4 -0
  140. package/dist/grid/chrome/grid-edit-escape.js +12 -0
  141. package/dist/grid/chrome/grid-edit-session.d.ts +2 -1
  142. package/dist/grid/chrome/grid-edit-session.js +14 -1
  143. package/dist/grid/chrome/grid-figure-value.d.ts +25 -0
  144. package/dist/grid/chrome/grid-figure-value.js +40 -0
  145. package/dist/grid/chrome/grid-fitted-box.d.ts +15 -0
  146. package/dist/grid/chrome/grid-fitted-box.js +26 -0
  147. package/dist/grid/chrome/grid-group-menu-items.d.ts +31 -0
  148. package/dist/grid/chrome/grid-group-menu-items.js +75 -0
  149. package/dist/grid/chrome/grid-group-menu-parts.d.ts +27 -0
  150. package/dist/grid/chrome/grid-group-menu-parts.js +19 -0
  151. package/dist/grid/chrome/grid-hover.d.ts +1 -0
  152. package/dist/grid/chrome/grid-hover.js +13 -1
  153. package/dist/grid/chrome/grid-lab.d.ts +7 -0
  154. package/dist/grid/chrome/grid-lab.js +7 -0
  155. package/dist/grid/chrome/grid-menu-focus.d.ts +12 -0
  156. package/dist/grid/chrome/grid-menu-focus.js +13 -0
  157. package/dist/grid/chrome/{useGridRowContextMenu.d.ts → grid-row-menu-items.d.ts} +15 -4
  158. package/dist/grid/chrome/{useGridRowContextMenu.js → grid-row-menu-items.js} +15 -18
  159. package/dist/grid/chrome/grid-row-props.d.ts +3 -1
  160. package/dist/grid/chrome/grid-row-window.d.ts +15 -5
  161. package/dist/grid/chrome/grid-row-window.js +44 -10
  162. package/dist/grid/chrome/grid-rows-menu.d.ts +38 -0
  163. package/dist/grid/chrome/grid-rows-menu.js +83 -0
  164. package/dist/grid/chrome/grid-table-props.d.ts +53 -8
  165. package/dist/grid/chrome/useGridBandFigures.d.ts +26 -0
  166. package/dist/grid/chrome/useGridBandFigures.js +50 -0
  167. package/dist/grid/chrome/useGridBoxes.d.ts +22 -0
  168. package/dist/grid/chrome/useGridBoxes.js +22 -0
  169. package/dist/grid/chrome/useGridColumnLayout.js +29 -4
  170. package/dist/grid/chrome/useGridKeyboard.js +7 -2
  171. package/dist/grid/chrome/useGridPartColumns.d.ts +5 -0
  172. package/dist/grid/chrome/useGridPartColumns.js +9 -0
  173. package/dist/grid/chrome/useGridRangeGestures.js +2 -1
  174. package/dist/grid/chrome/useGridRecorder.d.ts +16 -0
  175. package/dist/grid/chrome/useGridRecorder.js +144 -0
  176. package/dist/grid/chrome/useGridRowOpener.d.ts +41 -0
  177. package/dist/grid/chrome/useGridRowOpener.js +83 -0
  178. package/dist/grid/chrome/useGridScrollArea.d.ts +38 -12
  179. package/dist/grid/chrome/useGridScrollArea.js +70 -17
  180. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +1 -0
  181. package/dist/grid/chrome/useGridTableInteractionModel.js +67 -9
  182. package/dist/grid/core/clipboard-model.d.ts +11 -3
  183. package/dist/grid/core/clipboard-model.js +9 -4
  184. package/dist/grid/core/commit-model.d.ts +7 -0
  185. package/dist/grid/core/editing-controller.d.ts +31 -1
  186. package/dist/grid/core/editing-controller.js +65 -0
  187. package/dist/grid/core/grid-recorder.d.ts +111 -0
  188. package/dist/grid/core/grid-recorder.js +223 -0
  189. package/dist/grid/core/part-edits.d.ts +18 -0
  190. package/dist/grid/core/part-edits.js +48 -0
  191. package/dist/grid/core/pending-reconciliation.js +12 -3
  192. package/dist/grid/core/refusal-sentence.d.ts +3 -0
  193. package/dist/grid/core/refusal-sentence.js +15 -0
  194. package/dist/grid/core/row-opened-from.d.ts +21 -0
  195. package/dist/grid/core/row-opened-from.js +11 -0
  196. package/dist/grid/core/useGridEditing.d.ts +16 -2
  197. package/dist/grid/core/useGridEditing.js +10 -4
  198. package/dist/grid/core/value-equality.d.ts +19 -1
  199. package/dist/grid/core/value-equality.js +24 -0
  200. package/dist/grid/index.d.ts +4 -1
  201. package/dist/grid/index.js +1 -0
  202. package/dist/grid/useGridTablePrefs.d.ts +1 -1
  203. package/dist/grid-lab.d.ts +18 -0
  204. package/dist/grid-lab.js +16 -0
  205. package/dist/grouping/sort-groups.d.ts +6 -7
  206. package/dist/index.d.ts +1 -0
  207. package/dist/index.js +1 -0
  208. package/dist/internal/reset.d.ts +9 -0
  209. package/dist/internal/reset.js +1 -0
  210. package/dist/model/aggregates.d.ts +3 -3
  211. package/dist/model/aggregates.js +17 -71
  212. package/dist/model/column-capabilities.d.ts +29 -2
  213. package/dist/model/column-capabilities.js +27 -3
  214. package/dist/model/column-filters.js +24 -4
  215. package/dist/model/column-inspect.d.ts +2 -1
  216. package/dist/model/column-order.d.ts +2 -2
  217. package/dist/model/column-schema.d.ts +18 -7
  218. package/dist/model/column-state.d.ts +9 -20
  219. package/dist/model/column-state.js +1 -4
  220. package/dist/model/column-types.d.ts +1 -15
  221. package/dist/model/column-types.js +1 -1
  222. package/dist/model/part-columns.d.ts +17 -0
  223. package/dist/model/part-columns.js +67 -0
  224. package/dist/model/part-rows.d.ts +3 -10
  225. package/dist/model/part-rows.js +6 -11
  226. package/dist/model/part-write.d.ts +11 -0
  227. package/dist/model/part-write.js +52 -0
  228. package/dist/model/preferences.d.ts +3 -23
  229. package/dist/model/preferences.js +1 -17
  230. package/dist/model/prefs-buckets.d.ts +0 -27
  231. package/dist/model/prefs-buckets.js +1 -1
  232. package/dist/model/relation-filters.d.ts +0 -1
  233. package/dist/model/relation-filters.js +1 -1
  234. package/dist/model/row-icon.d.ts +5 -9
  235. package/dist/model/view-rules.d.ts +32 -6
  236. package/dist/model/view-rules.js +101 -21
  237. package/dist/provider/ViewsProvider.d.ts +22 -2
  238. package/dist/provider/ViewsProvider.js +21 -2
  239. package/dist/provider/components.d.ts +197 -9
  240. package/dist/provider/context.d.ts +12 -1
  241. package/dist/provider/desktop.d.ts +3 -0
  242. package/dist/provider/desktop.js +7 -4
  243. package/dist/provider/menu-groups.d.ts +3 -2
  244. package/dist/provider/menu-groups.js +13 -7
  245. package/dist/provider/missing-slot.d.ts +10 -0
  246. package/dist/provider/missing-slot.js +15 -0
  247. package/dist/provider/plain-input.d.ts +3 -2
  248. package/dist/provider/plain-input.js +3 -1
  249. package/dist/react.d.ts +3 -2
  250. package/dist/selection/SelectionBar.d.ts +18 -0
  251. package/dist/selection/SelectionBar.js +92 -0
  252. package/dist/selection/SelectionBarPhone.d.ts +3 -0
  253. package/dist/selection/SelectionBarPhone.js +14 -0
  254. package/dist/selection/bar-overflow.d.ts +12 -0
  255. package/dist/selection/bar-overflow.js +42 -0
  256. package/dist/selection/bar-parts.d.ts +15 -0
  257. package/dist/selection/bar-parts.js +17 -0
  258. package/dist/selection/index.d.ts +2 -0
  259. package/dist/selection/index.js +1 -0
  260. package/dist/selection/types.d.ts +3 -2
  261. package/dist/selection/verbs.d.ts +34 -0
  262. package/dist/selection/verbs.js +1 -0
  263. package/docs/contract.md +142 -39
  264. package/docs/getting-started.md +1 -1
  265. package/docs/guides/atoms.md +32 -4
  266. package/docs/guides/columns.md +1 -1
  267. package/docs/guides/display.md +1 -1
  268. package/docs/guides/editors.md +3 -3
  269. package/docs/guides/ports.md +1 -1
  270. package/docs/guides/selection.md +32 -20
  271. package/docs/guides/the-grid.md +43 -21
  272. package/docs/guides/the-provider.md +14 -4
  273. package/docs/index.md +2 -0
  274. package/docs/install.md +8 -1
  275. package/docs/reference/editors-date.md +2 -0
  276. package/docs/reference/editors-panel.md +4 -4
  277. package/docs/reference/editors-range.md +1 -1
  278. package/docs/reference/editors-relation.md +3 -3
  279. package/docs/reference/editors-select.md +1 -1
  280. package/docs/reference/editors-session.md +3 -2
  281. package/docs/reference/editors-value-list.md +1 -1
  282. package/docs/reference/field-row.md +2 -2
  283. package/docs/reference/grid.md +25 -6
  284. package/docs/reference/react.md +30 -8
  285. package/docs/reference/selection.md +10 -2
  286. package/docs/reference/views.md +42 -36
  287. package/package.json +22 -3
  288. package/skills/views/SKILL.md +3 -3
@@ -0,0 +1,83 @@
1
+ "use client";
2
+ import { useCallback, useLayoutEffect, useRef } from "react";
3
+ import { resolveOpenedFrom } from "../core/row-opened-from.js";
4
+ import { isDesktopNow } from "../../provider/desktop.js";
5
+ import { gridFocusElement, GRID_KEY_OWNING_SURFACES } from "./useGridFocus.js";
6
+ function afterCommit(run) {
7
+ queueMicrotask(() => queueMicrotask(run));
8
+ }
9
+ export function useGridRowOpener(args) {
10
+ const latest = useRef(args);
11
+ useLayoutEffect(() => {
12
+ latest.current = args;
13
+ });
14
+ const pending = useRef(0);
15
+ const openRow = useCallback((row, at) => {
16
+ const place = () => {
17
+ const { rootRef, visibleRowKeys, visibleColIds } = latest.current;
18
+ const root = rootRef.current?.isConnected ? rootRef.current : null;
19
+ return { root, pos: root ? resolveOpenedFrom(at, visibleRowKeys, visibleColIds) : null };
20
+ };
21
+ const reveal = (root, pos) => {
22
+ latest.current.revealCell(pos, "auto");
23
+ return gridFocusElement(root, { kind: "cell", pos });
24
+ };
25
+ const select = (pos) => {
26
+ const { focusCell, desktopQuery } = latest.current;
27
+ if (isDesktopNow(desktopQuery))
28
+ focusCell(pos.rowId, pos.columnId);
29
+ };
30
+ const settle = () => {
31
+ pending.current -= 1;
32
+ const { root, pos } = place();
33
+ if (!root)
34
+ return;
35
+ const active = document.activeElement;
36
+ const free = active == null ||
37
+ active === document.body ||
38
+ (root.contains(active) && !active.closest(GRID_KEY_OWNING_SURFACES));
39
+ if (!free)
40
+ return;
41
+ if (pos)
42
+ select(pos);
43
+ const cell = pos ? reveal(root, pos) : null;
44
+ if (cell) {
45
+ if (active !== cell)
46
+ cell.focus({ preventScroll: true });
47
+ }
48
+ else if (active?.closest("[data-grid-guard]")) {
49
+ root.focus({ preventScroll: true });
50
+ }
51
+ };
52
+ const settleAfterCommit = () => {
53
+ pending.current += 1;
54
+ afterCommit(settle);
55
+ };
56
+ const from = {
57
+ focus: () => {
58
+ const { root, pos } = place();
59
+ if (!root)
60
+ return false;
61
+ if (!pos) {
62
+ root.focus({ preventScroll: true });
63
+ return false;
64
+ }
65
+ select(pos);
66
+ (reveal(root, pos) ?? root).focus({ preventScroll: true });
67
+ settleAfterCommit();
68
+ return true;
69
+ },
70
+ element: () => {
71
+ const { root, pos } = place();
72
+ if (!root)
73
+ return null;
74
+ const cell = pos ? reveal(root, pos) : null;
75
+ settleAfterCommit();
76
+ return cell ?? root;
77
+ },
78
+ };
79
+ latest.current.onOpenRow(row, from);
80
+ }, []);
81
+ const settling = useCallback(() => pending.current > 0, []);
82
+ return { openRow, settling };
83
+ }
@@ -1,21 +1,47 @@
1
1
  import { type RefObject } from "react";
2
+ import type { GridRecorder } from "../core/grid-recorder.js";
3
+ import type { GridBoxes } from "./useGridBoxes.js";
2
4
  /**
3
- * The grid's one scroll area, and what the rest of the grid reads off it.
5
+ * The grid's scroll boxes, and what the rest of the grid reads off them.
4
6
  *
5
- * The whole table, headers and rows of every group, scrolls in ONE native element, both ways. Every
6
- * browser engine scrolls off the main thread, so a position script copies from one scroller to
7
- * another lands at least a frame late; here nothing is copied. The headers pin and the frozen
8
- * columns stick because they sit in the same scrollport as the rows, and the browser moves them all
9
- * at once.
7
+ * The rows' box (`vk-grid-scroll`) holds every head, row and footer and scrolls both ways: the grid's one box. While
8
+ * the page's lab asks for the lock on a touch screen (`useGridBoxes`), it sits inside an outer box (`vk-grid-pan`)
9
+ * that scrolls sideways, and itself scrolls up and down only. Every browser engine scrolls off the
10
+ * main thread, so a position script copies from one scroller to another lands at least a frame late; here no
11
+ * position is copied. The heads pin because they sit in the rows' box, and on one box the frozen columns stick
12
+ * because they sit in the same scrollport as the rows.
10
13
  *
11
- * What script still does is paint bookkeeping, never position: one passive listener writes two 0/1
12
- * flags on the frame, and only when one flips. `--vk-scrolled` is "has the table moved sideways at
13
- * all"; `--vk-parked` is "has the leading chrome (the checkbox rail, the frozen block) reached its
14
- * stop", which happens `parkAt` px later (measured below). It also keeps `scrollXRef` at the area's
15
- * x, which the header's column drag folds into its shift.
14
+ * What script does is paint bookkeeping, never a scroll position: one passive listener per box writes flags on the
15
+ * frame, and only when one changes. Only the box that scrolls sideways writes them: in two boxes the rows' box never
16
+ * moves sideways, and its up/down scrolls must leave the sideways flags as they are.
17
+ *
18
+ * - `--vk-scrolled` (0/1): has the table moved sideways at all, in either box. The paint reads it (the frozen
19
+ * band, its shadow, the frozen z tier).
20
+ * - `--vk-pin`: the position a row's frozen cells and rail take, `sticky` once the rows' box itself has moved
21
+ * sideways (one box), `relative` otherwise. `--vk-stick` (0/1) follows it and scales their sticky offsets, so a
22
+ * plain box is never moved by an offset.
23
+ * - `--vk-parked` (0/1): has the leading chrome (the checkbox rail, the frozen block) reached its stop, which
24
+ * happens `parkAt` px later (measured below).
25
+ * - `--vk-hold-x` and `--vk-sx`, two boxes only (the lab's lock): the offsets that hold the frozen block and the rail (`x − parkAt`,
26
+ * once parked) and a group's label and the empty message (`x`) at the left while the outer box is scrolled
27
+ * sideways, each a `left` on a box that is `position: relative` there. A sticky left can't hold them: their
28
+ * scroller, the rows' box, doesn't scroll sideways. An offset, never a transform: a transform on every drawn
29
+ * frozen cell made WebKit draw a flick through a table scrolled sideways far more slowly. Absent at the left edge,
30
+ * so the offsets read 0.
31
+ *
32
+ * WHY THE PIN WAITS for a sideways scroll: at rest nothing is held by its stop, so a plain box draws in the same
33
+ * place, and a sticky element in every drawn row is what iOS Safari can't keep up with as rows come and go under a
34
+ * fast flick: it leaves the screen empty in strips. The first frame of a sideways swipe moves them with the table
35
+ * before they pin. The hold waits for the same reason. It also keeps `scrollXRef` at the table's sideways offset,
36
+ * which the header's column drag folds into its shift.
16
37
  */
17
- export declare function useGridScrollArea(rootRef: RefObject<HTMLDivElement | null>): {
38
+ export declare function useGridScrollArea(rootRef: RefObject<HTMLDivElement | null>,
39
+ /** One box both ways, or the rows inside a box that scrolls sideways. */
40
+ boxes: GridBoxes,
41
+ /** The lab's recorder, when one runs: each event's sideways offset and pin go onto its sample. */
42
+ recorderRef?: RefObject<GridRecorder | null>): {
18
43
  areaRef: (element: HTMLDivElement | null) => (() => void) | undefined;
44
+ panRef: (element: HTMLDivElement | null) => (() => void) | undefined;
19
45
  scrollXRef: RefObject<number>;
20
46
  getScroller: () => HTMLElement | undefined;
21
47
  };
@@ -1,25 +1,59 @@
1
1
  "use client";
2
- import { useCallback, useEffect, useRef } from "react";
3
- export function useGridScrollArea(rootRef) {
2
+ import { useCallback, useEffect, useLayoutEffect, useRef } from "react";
3
+ export function useGridScrollArea(rootRef, boxes, recorderRef) {
4
4
  const areaElRef = useRef(null);
5
+ const panElRef = useRef(null);
6
+ const boxesRef = useRef(boxes);
5
7
  const scrollXRef = useRef(0);
6
8
  const parkAtRef = useRef(0);
7
- const flagsRef = useRef({ scrolled: "", parked: "" });
9
+ const flagsRef = useRef({ scrolled: "", parked: "", pin: "", hold: "", sx: "" });
8
10
  const writeFlags = useCallback((x) => {
9
11
  const root = rootRef.current;
10
12
  if (!root)
11
13
  return;
14
+ const held = boxesRef.current === 2;
15
+ const flags = flagsRef.current;
12
16
  const scrolled = x > 0 ? "1" : "0";
13
17
  const parked = x > 0 && x >= parkAtRef.current ? "1" : "0";
14
- if (flagsRef.current.scrolled !== scrolled) {
15
- flagsRef.current.scrolled = scrolled;
18
+ const pin = x > 0 && !held ? "sticky" : "relative";
19
+ const holdBy = x - parkAtRef.current;
20
+ const hold = held && holdBy > 0 ? `${holdBy}px` : "";
21
+ const sx = held && x > 0 ? `${x}px` : "";
22
+ if (flags.scrolled !== scrolled) {
23
+ flags.scrolled = scrolled;
16
24
  root.style.setProperty("--vk-scrolled", scrolled);
17
25
  }
18
- if (flagsRef.current.parked !== parked) {
19
- flagsRef.current.parked = parked;
26
+ if (flags.pin !== pin) {
27
+ flags.pin = pin;
28
+ root.style.setProperty("--vk-pin", pin);
29
+ root.style.setProperty("--vk-stick", pin === "sticky" ? "1" : "0");
30
+ }
31
+ if (flags.parked !== parked) {
32
+ flags.parked = parked;
20
33
  root.style.setProperty("--vk-parked", parked);
21
34
  }
35
+ if (flags.hold !== hold) {
36
+ flags.hold = hold;
37
+ if (hold)
38
+ root.style.setProperty("--vk-hold-x", hold);
39
+ else
40
+ root.style.removeProperty("--vk-hold-x");
41
+ }
42
+ if (flags.sx !== sx) {
43
+ flags.sx = sx;
44
+ if (sx)
45
+ root.style.setProperty("--vk-sx", sx);
46
+ else
47
+ root.style.removeProperty("--vk-sx");
48
+ }
22
49
  }, [rootRef]);
50
+ const sideways = useCallback(() => (boxesRef.current === 2 ? panElRef.current : areaElRef.current), []);
51
+ useLayoutEffect(() => {
52
+ boxesRef.current = boxes;
53
+ const x = sideways()?.scrollLeft ?? 0;
54
+ scrollXRef.current = x;
55
+ writeFlags(x);
56
+ }, [boxes, sideways, writeFlags]);
23
57
  useEffect(() => {
24
58
  const root = rootRef.current;
25
59
  if (!root)
@@ -44,22 +78,41 @@ export function useGridScrollArea(rootRef) {
44
78
  probe.remove();
45
79
  };
46
80
  }, [rootRef, writeFlags]);
81
+ const listen = useCallback((element) => {
82
+ const onScroll = () => {
83
+ if (sideways() === element) {
84
+ const x = element.scrollLeft;
85
+ scrollXRef.current = x;
86
+ writeFlags(x);
87
+ }
88
+ const x = scrollXRef.current;
89
+ recorderRef?.current?.amend(x, x > 0);
90
+ };
91
+ element.addEventListener("scroll", onScroll, { passive: true });
92
+ return () => element.removeEventListener("scroll", onScroll);
93
+ }, [recorderRef, sideways, writeFlags]);
47
94
  const areaRef = useCallback((element) => {
48
95
  areaElRef.current = element;
49
96
  if (!element)
50
97
  return;
51
- const onScroll = () => {
52
- const x = element.scrollLeft;
53
- scrollXRef.current = x;
54
- writeFlags(x);
55
- };
56
- element.addEventListener("scroll", onScroll, { passive: true });
98
+ const stop = listen(element);
57
99
  return () => {
58
- element.removeEventListener("scroll", onScroll);
100
+ stop();
59
101
  if (areaElRef.current === element)
60
102
  areaElRef.current = null;
61
103
  };
62
- }, [writeFlags]);
63
- const getScroller = useCallback(() => areaElRef.current ?? undefined, []);
64
- return { areaRef, scrollXRef, getScroller };
104
+ }, [listen]);
105
+ const panRef = useCallback((element) => {
106
+ panElRef.current = element;
107
+ if (!element)
108
+ return;
109
+ const stop = listen(element);
110
+ return () => {
111
+ stop();
112
+ if (panElRef.current === element)
113
+ panElRef.current = null;
114
+ };
115
+ }, [listen]);
116
+ const getScroller = useCallback(() => sideways() ?? undefined, [sideways]);
117
+ return { areaRef, panRef, scrollXRef, getScroller };
65
118
  }
@@ -31,6 +31,7 @@ export declare function useGridTableInteractionModel<Row>({ rootRef, props, rows
31
31
  * since only the rows on screen are drawn. The one reveal (`revealGridCell`) calls it for a row it can't find in the page. */
32
32
  revealRow?: (rowKey: string, columnId?: string) => void;
33
33
  }): {
34
+ revealCell: (pos: GridCellPos, behavior: ScrollBehavior) => void;
34
35
  focus: {
35
36
  chrome: import("../core/grid-focus.js").GridChromeTarget | null;
36
37
  setChrome: (target: import("../core/grid-focus.js").GridChromeTarget | null) => void;
@@ -3,7 +3,11 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
3
3
  import { useViews } from "../../provider/context.js";
4
4
  import { useGridEditing } from "../core/useGridEditing.js";
5
5
  import { useGridRange } from "../core/useGridRange.js";
6
- import { columnEffectiveWritable, gridColumnLocked, gridEditRefusal, gridNormalizeWrite, } from "../../model/column-capabilities.js";
6
+ import { gridRefusalSentence } from "../core/refusal-sentence.js";
7
+ import { columnEffectiveWritable, columnLabel, gridColumnLocked, gridEditRefusal, gridNormalizeWrite, } from "../../model/column-capabilities.js";
8
+ import { gridPartWrite } from "../../model/part-write.js";
9
+ import { foldPartEdits } from "../core/part-edits.js";
10
+ import { sameStoredValue } from "@viewkitjs/fields";
7
11
  import { gridRowIdFromKey } from "../core/coordinates.js";
8
12
  import { revealGridCell } from "./grid-scroll-owner.js";
9
13
  import { useGridFocus } from "./useGridFocus.js";
@@ -15,12 +19,64 @@ import { useGridRangeGestures } from "./useGridRangeGestures.js";
15
19
  const REFUSAL_REPEAT_MS = 600;
16
20
  export function useGridTableInteractionModel({ rootRef, props, rows, visibleRows, heldRows, rowIndex, visibleColumns, selecting, revealRow, focusShape, groupOfRow, }) {
17
21
  const { columns, getRowId, listConfig } = props;
18
- const { conventions, ports, messages } = useViews();
22
+ const { conventions, ports, messages, sayRefusals = false } = useViews();
19
23
  const editingEnabled = !!props.onCellCommit;
20
- const { focused: focusedCell, editing: editingCell, pendingByRow, settlementByRow, focusCell, clearFocus, startEdit, cancelEdit, closeEdit, commitEdit: commitEditRaw, commitBatch: commitBatchRaw, undo, redo, reconcile, hasInflight, pendingBaseline, } = useGridEditing(props.onCellCommit, props.onCellsCommit);
24
+ const sayRefusal = useCallback((refusal) => {
25
+ if (!sayRefusals)
26
+ return;
27
+ const nameOf = (columnId) => {
28
+ const col = columns.find((each) => each.id === columnId);
29
+ return col ? columnLabel(col) : columnId;
30
+ };
31
+ ports.toast.error(gridRefusalSentence(refusal, nameOf, messages));
32
+ }, [sayRefusals, columns, ports, messages]);
33
+ const { focused: focusedCell, editing: editingCell, pendingByRow, settlementByRow, focusCell, clearFocus, startEdit, cancelEdit, closeEdit, commitEdit: commitEditRaw, commitBatch: commitBatchRaw, undo, redo, reconcile, hasInflight, pendingBaseline, sent, sentCells, forgetSent, } = useGridEditing(props.onCellCommit, props.onCellsCommit, sayRefusal);
34
+ const columnById = useMemo(() => new Map([...columns, ...visibleColumns].map((column) => [column.id, column])), [columns, visibleColumns]);
35
+ const partOfWhole = useCallback((wholeId) => [...columnById.values()].find((column) => column.partOf?.column === wholeId)?.partOf, [columnById]);
36
+ const wholeStored = useCallback((rowId, wholeId, row) => {
37
+ const part = partOfWhole(wholeId);
38
+ const overlay = pendingByRow.get(rowId);
39
+ const last = sent(rowId, wholeId);
40
+ const inChain = (value) => !!part && !!last && last.chain.some((each) => sameStoredValue(part.field, value, each));
41
+ if (overlay && wholeId in overlay)
42
+ return inChain(overlay[wholeId]) ? last.value : overlay[wholeId];
43
+ if (!part)
44
+ return undefined;
45
+ const stored = part.read(row);
46
+ return inChain(stored) ? last.value : stored;
47
+ }, [partOfWhole, pendingByRow, sent]);
48
+ useEffect(() => {
49
+ for (const { rowId, columnId } of sentCells()) {
50
+ const part = partOfWhole(columnId);
51
+ if (!part)
52
+ continue;
53
+ const held = rowIndex.get(rowId) ?? [...rowIndex.values()].find((entry) => entry.rowId === rowId);
54
+ const last = sent(rowId, columnId);
55
+ if (held && last && sameStoredValue(part.field, part.read(held.row), last.value))
56
+ forgetSent(rowId, columnId);
57
+ }
58
+ }, [rowIndex, partOfWhole, sentCells, sent, forgetSent]);
21
59
  const lockedRefusal = useCallback((col) => gridColumnLocked(col, listConfig) ? gridEditRefusal(col, listConfig, conventions, messages) : undefined, [listConfig, conventions, messages]);
22
60
  const commitEdit = useCallback((row, rowId, columnId, prev, next, opts) => {
23
- const col = visibleColumns.find((c) => c.id === columnId);
61
+ const col = columnById.get(columnId);
62
+ if (col?.partOf) {
63
+ const locked = lockedRefusal(col);
64
+ if (locked) {
65
+ ports.toast.error(locked);
66
+ closeEdit(rowId, columnId);
67
+ return;
68
+ }
69
+ const wholeId = col.partOf.column;
70
+ const base = wholeStored(rowId, wholeId, row);
71
+ const res = gridPartWrite(col, base, next, conventions, { messages });
72
+ closeEdit(rowId, columnId);
73
+ if (!res.ok) {
74
+ ports.toast.error(res.reason);
75
+ return;
76
+ }
77
+ commitEditRaw(row, rowId, wholeId, base, res.value, { overlay: false });
78
+ return;
79
+ }
24
80
  if (col) {
25
81
  const locked = lockedRefusal(col);
26
82
  if (locked) {
@@ -37,12 +93,13 @@ export function useGridTableInteractionModel({ rootRef, props, rows, visibleRows
37
93
  next = res.value;
38
94
  }
39
95
  commitEditRaw(row, rowId, columnId, prev, next, opts);
40
- }, [visibleColumns, commitEditRaw, closeEdit, conventions, messages, ports, lockedRefusal]);
96
+ }, [columnById, commitEditRaw, closeEdit, conventions, messages, ports, lockedRefusal, wholeStored]);
41
97
  const commitBatch = useCallback((edits) => {
42
- const colById = new Map(visibleColumns.map((c) => [c.id, c]));
98
+ const colById = columnById;
43
99
  const kept = [];
44
- let firstRefusal;
45
- for (const edit of edits) {
100
+ const folded = foldPartEdits(edits, columnById, wholeStored, conventions, { messages });
101
+ let firstRefusal = folded.refusals[0];
102
+ for (const edit of folded.edits) {
46
103
  const col = colById.get(edit.columnId);
47
104
  if (!col) {
48
105
  kept.push(edit);
@@ -70,7 +127,7 @@ export function useGridTableInteractionModel({ rootRef, props, rows, visibleRows
70
127
  return Promise.resolve(true);
71
128
  }
72
129
  return commitBatchRaw(kept);
73
- }, [visibleColumns, commitBatchRaw, conventions, messages, ports, lockedRefusal]);
130
+ }, [columnById, commitBatchRaw, conventions, messages, ports, lockedRefusal, wholeStored]);
74
131
  const lastRefusalRef = useRef(null);
75
132
  const refuseEdit = useCallback((columnId) => {
76
133
  if (!editingEnabled)
@@ -244,6 +301,7 @@ export function useGridTableInteractionModel({ rootRef, props, rows, visibleRows
244
301
  handleRootClickCapture,
245
302
  ...rangeActions,
246
303
  ...keyboard,
304
+ revealCell,
247
305
  focus,
248
306
  };
249
307
  }
@@ -56,11 +56,19 @@ export declare function pasteUnit(sourceUnit: string | undefined, currentUnit: s
56
56
  * rates — a null map is the database's answer that the row has none — never off
57
57
  * `editUnit`, which a host may fill with a default. Any other column: yes. */
58
58
  export declare function rowHoldsCurrency<Row>(col: ListColumn<Row>, row: Row): boolean;
59
+ /**
60
+ * Whether a date written into this column paints at once, as an overlay over the cell: the one rule the date editor,
61
+ * a paste and a fill read, so the three gestures agree on a cell. A calendar-day field writes the `YYYY-MM-DD` its
62
+ * row stores; a datetime writes a local minute the refetch reads as the instant its row stores
63
+ * (`sameInstantMinute`). A day column on no registry writes a dated time its app's mapper strips to a day, which no
64
+ * read reconciles, so it waits for the refetch.
65
+ */
66
+ export declare function gridDateDrawsAtOnce<Row>(col: ListColumn<Row>): boolean;
59
67
  /**
60
68
  * Whether a paste or a fill into this column paints its value at once, as an overlay over the cell. Only a value the
61
- * refetch compares equal to (`looselyEqualValue`) may: a text, an option's key, a yes/no, a list of strings. A figure
62
- * commits `{ value, unit }`, a date a day or a minute string the row stores in its own shape, a relation an id against
63
- * a resolved object, a range an object, a list of several values its items: none reads equal to what the row holds,
69
+ * refetch reads back as the one written may: a text, an option's key, a yes/no, a list of strings, and a date where
70
+ * its editor paints one (`gridDateDrawsAtOnce`). A figure commits `{ value, unit }`, a relation an id against a
71
+ * resolved object, a range an object, a list of several values its items: none reads equal to what the row holds,
64
72
  * so an overlay would draw the payload ("[object Object]") and the settled write would read as changed elsewhere.
65
73
  * Those skip it, as the editors do, and the refetch repaints the cell.
66
74
  */
@@ -1,6 +1,7 @@
1
1
  import { actorLabel, formatLocalMinute, isActorValue, isBreakdown, isRangeValue, isValueItem, listValues, locationText, nameText, parseNumber, rangeText, relationIdOf, relationKey, } from "@viewkitjs/fields";
2
2
  import { phoneText } from "@viewkitjs/fields/phone";
3
- import { fromDayKey, msToDurationUnit, parseDateInput, parseDurationInput } from "@viewkitjs/fields/query";
3
+ import { msToDurationUnit, parseDateInput, parseDurationInput } from "@viewkitjs/fields/query";
4
+ import { calendarDayOf } from "./value-equality.js";
4
5
  import { GRID_TYPE_RULES, gridPasteKind } from "../../model/column-types.js";
5
6
  import { resolveViewsMessage } from "../../contract.js";
6
7
  import { gridNormalizeWrite } from "../../model/column-capabilities.js";
@@ -98,9 +99,8 @@ export function cellPrevPayload(col, baseline, unit) {
98
99
  return payload;
99
100
  }
100
101
  if (col.type === "date" || col.type === "datetime") {
101
- if (temporalKindOf(col) === "date") {
102
- return typeof baseline === "string" && fromDayKey(baseline) ? baseline : undefined;
103
- }
102
+ if (temporalKindOf(col) === "date")
103
+ return calendarDayOf(baseline) ?? undefined;
104
104
  const date = new Date(String(baseline ?? ""));
105
105
  return Number.isNaN(date.getTime()) ? undefined : toLocalMinuteString(date);
106
106
  }
@@ -120,12 +120,17 @@ export function pasteUnit(sourceUnit, currentUnit, allowed, holdsCurrency) {
120
120
  export function rowHoldsCurrency(col, row) {
121
121
  return col.money ? col.money.rates(row) !== null : true;
122
122
  }
123
+ export function gridDateDrawsAtOnce(col) {
124
+ return col.field?.type === "date" || fieldTypeOf(col) === "datetime";
125
+ }
123
126
  export function gridPasteOverlay(col) {
124
127
  const kind = gridPasteKind(col);
125
128
  if (kind === "text" || kind === "option" || kind === "boolean")
126
129
  return true;
127
130
  if (kind === "list")
128
131
  return !col.multiple;
132
+ if (kind === "date")
133
+ return gridDateDrawsAtOnce(col);
129
134
  return false;
130
135
  }
131
136
  export function coercePaste(col, source, opts) {
@@ -31,6 +31,13 @@ export type GridCommitOutcome = {
31
31
  status: "failed";
32
32
  error?: unknown;
33
33
  };
34
+ /** One write the app refused, as the editing core reports it: the columns of the cells that failed, in order, how many,
35
+ * and the first failure's error (or the call's rejection). */
36
+ export type GridCommitRefusal = {
37
+ columnIds: string[];
38
+ count: number;
39
+ error: unknown;
40
+ };
34
41
  export type GridCellCommitFn<Row> = (row: Row, columnId: string, value: unknown, context?: GridCommitContext) => Promise<void | GridCommitOutcome>;
35
42
  export type GridCellsCommitFn<Row> = (edits: {
36
43
  row: Row;
@@ -1,9 +1,12 @@
1
- import { type GridCellCommitFn, type GridCellsCommitFn } from "./commit-model.js";
1
+ import { type GridCellCommitFn, type GridCellsCommitFn, type GridCommitRefusal } from "./commit-model.js";
2
2
  import type { GridCellPos } from "./coordinates.js";
3
3
  import { type GridCommitCell, type GridSettlementByRow } from "./editing-model.js";
4
4
  export type GridEditingCallbacks<Row> = {
5
5
  onCellCommit?: GridCellCommitFn<Row>;
6
6
  onCellsCommit?: GridCellsCommitFn<Row>;
7
+ /** Told once per write the app refused (a commit, a batch, an undo or a redo), after its cells rolled back. The
8
+ * core says nothing itself: the chrome decides whether and how a refusal is said. */
9
+ onRefused?: (refusal: GridCommitRefusal) => void;
7
10
  };
8
11
  type ResolveRow<Row> = (rowId: string) => Row | undefined;
9
12
  /**
@@ -18,6 +21,9 @@ export declare class GridEditingController<Row> {
18
21
  private history;
19
22
  private pending;
20
23
  private readonly inflight;
24
+ /** The last value this grid sent for each cell and the value that write was built on, each entry its write's own
25
+ * (`token`), so an older write's end never drops a newer one's (`sent`). */
26
+ private readonly lastSent;
21
27
  private applyChain;
22
28
  private nextHistoryId;
23
29
  private nextPendingRevision;
@@ -41,6 +47,8 @@ export declare class GridEditingController<Row> {
41
47
  reconcile(matchedKeys: readonly string[]): void;
42
48
  undo(resolveRow: ResolveRow<Row>, onApply?: (pos: GridCellPos) => void): boolean;
43
49
  redo(resolveRow: ResolveRow<Row>, onApply?: (pos: GridCellPos) => void): boolean;
50
+ /** One write's failed cells, reported once: their columns, how many, and the first one's error. */
51
+ private reportRefusals;
44
52
  private publishPending;
45
53
  /** A confirmed outcome that says what was `stored` lays it over the cell in place of what was
46
54
  * typed; a `requested` one keeps its overlay and marks it. Nothing else changes. */
@@ -48,6 +56,28 @@ export declare class GridEditingController<Row> {
48
56
  /** Is a write for this cell still in flight? Reconciliation asks, so it can
49
57
  * tell "the refetch hasn't caught up yet" apart from "the server disagrees". */
50
58
  hasInflight(rowId: string, columnId: string): boolean;
59
+ /** The last value this grid sent for a cell, the value that write was built on, and the chain of values the writes
60
+ * built one on another led through (`builtOn` of the first, then each value sent). Kept until that write ends in
61
+ * anything but confirmed, an undo or a redo restores the cell, or the row is seen holding the value sent with
62
+ * nothing in flight (`forgetSent`). A part column's edit builds on it while the row holds a value of the chain. */
63
+ sent(rowId: string, columnId: string): {
64
+ value: unknown;
65
+ builtOn: unknown;
66
+ chain: readonly unknown[];
67
+ } | undefined;
68
+ /** The cells holding an entry, for the grid to retire the ones its rows have caught up with. */
69
+ sentCells(): {
70
+ rowId: string;
71
+ columnId: string;
72
+ }[];
73
+ /** Retires a cell's entry: its row holds what was sent and nothing is in flight. */
74
+ forgetSent(rowId: string, columnId: string): void;
75
+ /** Records what a commit sends for a cell; the token is that write's own. */
76
+ private noteSent;
77
+ /** Drops a cell's entry: any entry, or, with a token, only while it is still that write's own. */
78
+ private dropSent;
79
+ /** A write's end: its entry goes on a failure, and takes the value the app stored where it says. */
80
+ private settleSent;
51
81
  /** What this cell held before the pending write. Reconciliation asks, so it
52
82
  * can tell a value the SERVER normalised apart from one somebody else set. */
53
83
  pendingBaseline(rowId: string, columnId: string): unknown;