@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
@@ -1,6 +1,7 @@
1
1
  import type { ReactNode } from "react";
2
2
  import type { DisplayCurrency } from "../../fields/currency.js";
3
3
  import type { ViewsRowMenuItem } from "../../atoms/types.js";
4
+ import type { ViewsMenuItem } from "../../provider/components.js";
4
5
  import type { FieldMenus } from "../../fields/menus.js";
5
6
  import type { ListGroup } from "../../grouping/types.js";
6
7
  import type { ListSelectionConfig } from "../../selection/types.js";
@@ -11,22 +12,38 @@ import type { ListColumnState, ListColumnsConfig } from "../../model/column-stat
11
12
  import type { PercentDisplay } from "@viewkitjs/fields";
12
13
  import type { ListGroupSummaryPart } from "../../model/preferences.js";
13
14
  import type { ListRowIconAccessor } from "../../model/row-icon.js";
15
+ import type { GridRowOpenedFrom } from "../core/row-opened-from.js";
14
16
  import type { GridCellCommitFn, GridCellsCommitFn } from "../core/commit-model.js";
15
17
  import type { GridGroupByState, GridSortState } from "./GridColumnMenu.js";
16
18
  import type { GridGroupSortOption } from "./GridGroupMenu.js";
19
+ import type { GridGroupMenuPart } from "./grid-group-menu-parts.js";
17
20
  /** A group count's noun, singular and plural ("company", "companies"): "2 companies". None: a bare
18
21
  * count. */
19
22
  export type GroupCountNoun = {
20
23
  one: string;
21
24
  other: string;
22
25
  };
23
- /** One figure a group header can show: the part that turns it on, its column's header (what the menu and
24
- * the header call it), and how it draws for a group. */
25
- export type GridGroupFigure<Row> = {
26
+ /** A figure a group's band shows that the grid works out: a column and a kind ("value", "sum"), computed and
27
+ * written as that column's footer writes them (its format, its currency, a paged group's figure from the
28
+ * source), or the footer cell you draw yourself for that column (`renderAggregate`). */
29
+ export type GridDeclaredFigure = {
30
+ /** The part that turns it on. */
31
+ part: ListGroupSummaryPart;
32
+ /** What the band and the menu call it; the column's header when left out. */
33
+ label?: ReactNode;
34
+ /** The column's id. */
35
+ column: string;
36
+ kind: ListAggregateKind;
37
+ };
38
+ /** A figure a group's band shows that you draw yourself: the part that turns it on, its column's header (what
39
+ * the menu and the band call it), and how it draws for a group. */
40
+ export type GridDrawnFigure<Row> = {
26
41
  part: ListGroupSummaryPart;
27
42
  label: ReactNode;
28
43
  render: (group: ListGroup<Row>) => ReactNode;
29
44
  };
45
+ /** One figure a group's band can show: declared by its column and kind, or drawn by you. */
46
+ export type GridGroupFigure<Row> = GridDeclaredFigure | GridDrawnFigure<Row>;
30
47
  /** A view's identity: when it changes, the whole body is replaced, and the grid shows its wait for
31
48
  * one commit first. */
32
49
  type GridTransitionKey = string | number | boolean | null | undefined;
@@ -45,11 +62,21 @@ export type GridTableProps<Row> = {
45
62
  /** Hide a group in the view, from its band's menu. Absent where a
46
63
  * list cannot hide one. */
47
64
  onHideGroup?: (key: string) => void;
65
+ /** Which parts a group band's ⋯ menu holds: `"sort"`, `"figures"` (the count and each figure, turned on and
66
+ * off) and `"hide"`. Each shows only when you also pass what it needs: `sort` with `sortOptions`;
67
+ * `groupFigures` with `onGroupSummaryChange`; `onHideGroup`. On the `popover` route the sort list then always
68
+ * searches through your `Command`, at any count. Left out, the ⋯ opens for sort or Hide, carries the figure toggles
69
+ * with them, and searches past eight sort choices. On the `menu` route (the provider's `menus`) the sort choices
70
+ * open beside the menu with no search, either way. */
71
+ groupMenu?: readonly GridGroupMenuPart[];
48
72
  /** Source-paged group continuation, rendered after this group's loaded rows. */
49
73
  renderGroupFooter?: (group: ListGroup<Row>) => ReactNode;
50
74
  renderAggregate?: (columnId: string, group: ListGroup<Row>) => ReactNode;
51
75
  countOf?: (group: ListGroup<Row>) => number;
52
- onOpenRow: (row: Row) => void;
76
+ /** What opening a row does (a click on the title's text; a tap on the title's cell on a phone). `from` brings the
77
+ * focus back to the cell it was opened from once what it opened closes: call `from.focus()`, or hand
78
+ * `from.element` to a dialog's final-focus option. An app that has no use for it declares one parameter. */
79
+ onOpenRow: (row: Row, from: GridRowOpenedFrom) => void;
53
80
  /** Warm the row detail only from an actual primary pointer intent. */
54
81
  onPrefetchRow?: (row: Row) => void;
55
82
  /**
@@ -122,7 +149,8 @@ export type GridTableProps<Row> = {
122
149
  /** A saved view can change aggregate choices only for field-backed columns. */
123
150
  viewBacked?: boolean;
124
151
  onGroupSummaryChange?: (part: ListGroupSummaryPart, next: boolean) => void;
125
- /** The figures a group header can show, in the list's order: each part, its column's header and its drawing. */
152
+ /** The figures a group header can show, in the list's order: each declared by its column and kind, or drawn
153
+ * by you. */
126
154
  groupFigures?: GridGroupFigure<Row>[];
127
155
  /** The group count's noun: "2 companies". None: a bare count. */
128
156
  countNoun?: GroupCountNoun;
@@ -146,12 +174,29 @@ export type GridTableProps<Row> = {
146
174
  * false hides them from the column menu, where there is nothing to store them against. A reader's own
147
175
  * currency reading stays. Default true. */
148
176
  formatsWritable?: boolean;
149
- /** The host's own "+ Add column", the header row's last cell (a field editor's, for an admin). Nothing, or a
150
- * falsy answer, draws the grid's own: the columns the view hides. */
177
+ /** The host's own "+ Add column", the header row's last cell (a field editor's, for an admin). `null` draws none,
178
+ * and the tail keeps no room for one; nothing, `undefined`, `false` or `""` draw the grid's own: the columns the
179
+ * view hides. The table asks it whether to size the tail and the header asks it for the cell, so its answer is a
180
+ * plain function of `columns`, never a hook's. */
151
181
  renderAddColumn?: (columns: ListColumnsConfig) => ReactNode;
182
+ /** Draw "+ Add column" on a phone too, its list in the Sheet: where a person brings back a column they hid there.
183
+ * Off by default: a phone's header ends with nothing, an app's own column list being the way in. */
184
+ addColumnOnPhone?: boolean;
185
+ /** A column per part of a name, a place or a range (a place's country, a name's family name, a range's low end),
186
+ * offered under its field in "+ Add column" and hidden until picked. Its id is `partKey(columnId, part)`, the key
187
+ * its Filter row has; it reads, sorts (its sort value is `partKey(fieldKey, part)`, which `parsePartKey` turns into
188
+ * a sort's `fieldKey` and `by`), copies, edits and pastes as its part; an edit commits the whole column's id and
189
+ * the whole value with that part replaced, locked, refused and limited as its whole. Off by default. */
190
+ parts?: boolean;
152
191
  /** The host's rows in a column's menu for the column's field, above Hide (a field editor's Edit field and
153
- * Archive field); `close` shuts the menu. Null for a field the host adds nothing to. */
192
+ * Archive field); `close` shuts the menu. Null for a field the host adds nothing to. On the `menu` route (the
193
+ * provider's `menus`) it isn't drawn: hand `columnMenuItems`. */
154
194
  renderColumnMenuRows?: (fieldKey: string, close: () => void) => ReactNode;
195
+ /** The host's rows for a column's field on the `menu` route, as data, drawn just above Hide; null or an empty
196
+ * list for a field the host adds nothing to. Their keys must not reuse the package's own (`sort-asc`,
197
+ * `hide-column` and the rest). It is called while the grid renders, for every column: keep it pure and cheap.
198
+ * On the `popover` route `renderColumnMenuRows` draws them instead. */
199
+ columnMenuItems?: (fieldKey: string) => ViewsMenuItem[] | null;
155
200
  columnState?: ListColumnState;
156
201
  onColumnStateChange?: (next: ListColumnState) => void;
157
202
  scale?: number;
@@ -0,0 +1,26 @@
1
+ import type { ReactNode } from "react";
2
+ import type { ListGroup } from "../../grouping/types.js";
3
+ import type { ListColumn } from "../../model/column-schema.js";
4
+ import type { ListNumberFormatOverrides } from "../../model/column-format.js";
5
+ import type { ListGroupSummaryPart } from "../../model/preferences.js";
6
+ import { type DisplayCurrency } from "../../fields/currency.js";
7
+ import type { GridGroupFigure } from "./grid-table-props.js";
8
+ /** A figure as the band draws it. A `declared` one is left out of a group it has nothing for; one the app draws
9
+ * shows its label whatever it draws. */
10
+ export type GridBandFigure<Row> = {
11
+ part: ListGroupSummaryPart;
12
+ label: ReactNode;
13
+ /** The label in words, for a menu row: the label when it is text, else a declared figure's column label, else
14
+ * its part. */
15
+ text: string;
16
+ render: (group: ListGroup<Row>) => ReactNode;
17
+ declared: boolean;
18
+ };
19
+ export declare function useGridBandFigures<Row>(figures: readonly GridGroupFigure<Row>[] | undefined, { columns, numberFormats, defaultCurrency, renderAggregate, }: {
20
+ /** Every column, shown or hidden: a band's figure doesn't need its column on screen. */
21
+ columns: readonly ListColumn<Row>[];
22
+ numberFormats?: ListNumberFormatOverrides;
23
+ defaultCurrency?: DisplayCurrency;
24
+ /** The app's own footer cell, which a declared figure on that column shows in its place. */
25
+ renderAggregate?: (columnId: string, group: ListGroup<Row>) => ReactNode;
26
+ }): GridBandFigure<Row>[];
@@ -0,0 +1,50 @@
1
+ "use client";
2
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { columnLabel } from "../../model/column-capabilities.js";
4
+ import { DEFAULT_DISPLAY_CURRENCY } from "../../fields/currency.js";
5
+ import { CellSuffix } from "../../display/format.js";
6
+ import { useCellFormat } from "../../cells/use-cell-format.js";
7
+ import { gridFigureValue } from "./grid-figure-value.js";
8
+ const words = (label) => typeof label === "string" || typeof label === "number" ? String(label) : undefined;
9
+ export function useGridBandFigures(figures, { columns, numberFormats, defaultCurrency = DEFAULT_DISPLAY_CURRENCY, renderAggregate, }) {
10
+ const cellFormat = useCellFormat();
11
+ const drawn = [];
12
+ for (const figure of figures ?? []) {
13
+ if ("render" in figure) {
14
+ drawn.push({
15
+ part: figure.part,
16
+ label: figure.label,
17
+ text: words(figure.label) ?? figure.part,
18
+ render: figure.render,
19
+ declared: false,
20
+ });
21
+ continue;
22
+ }
23
+ const column = columns.find((candidate) => candidate.id === figure.column);
24
+ if (!column)
25
+ continue;
26
+ drawn.push({
27
+ part: figure.part,
28
+ label: figure.label ?? column.header,
29
+ text: words(figure.label) ?? columnLabel(column),
30
+ declared: true,
31
+ render: (group) => {
32
+ const own = renderAggregate?.(column.id, group);
33
+ if (own != null)
34
+ return own;
35
+ const value = gridFigureValue({
36
+ column,
37
+ group,
38
+ kind: figure.kind,
39
+ numberFormats,
40
+ defaultCurrency,
41
+ cellFormat,
42
+ });
43
+ if (!value)
44
+ return null;
45
+ return (_jsxs(_Fragment, { children: [value.text, value.suffix && _jsx(CellSuffix, { children: value.suffix })] }));
46
+ },
47
+ });
48
+ }
49
+ return drawn;
50
+ }
@@ -0,0 +1,22 @@
1
+ /**
2
+ * The fill dot's test, `(hover: hover) and (pointer: fine)`, spelled in its own order. A browser answers it
3
+ * exactly as the hover query (`internal/viewport.ts`); being its own string, a test can answer it apart from that
4
+ * one, so a grid test keeps one box while it reads a pointer that can't hover.
5
+ */
6
+ export declare const GRID_BOXES_QUERY = "(pointer: fine) and (hover: hover)";
7
+ /** How many boxes the grid scrolls in: 1, one box both ways; 2, the rows up and down inside a box that scrolls
8
+ * sideways. */
9
+ export type GridBoxes = 1 | 2;
10
+ /**
11
+ * Two boxes only where the page's lab asks for them (`lab.boxes`, a switch an app gives its owner to try the lock on
12
+ * a phone) and the device doesn't hover with a fine pointer; one box everywhere else, the grid as everyone has it.
13
+ *
14
+ * WHY TWO ON A TOUCH SCREEN: iOS locks a flick to its first direction only for the page's own scroll, never for a
15
+ * scroll box inside the page. A box that scrolls both ways slides sideways under a vertical flick with any drift of
16
+ * the thumb. In two boxes, each scrolling one way, iOS hands each flick to the box of its direction itself, with no
17
+ * script deciding and no touch held. Behind the lab while its cost is weighed on a phone: the rows' box is as wide
18
+ * as the table, and a fast flick through a wide table draws more slowly in it.
19
+ *
20
+ * One box on a server render and where there is no `matchMedia`; it follows the query's and the lab's changes.
21
+ */
22
+ export declare function useGridBoxes(): GridBoxes;
@@ -0,0 +1,22 @@
1
+ "use client";
2
+ import { useSyncExternalStore } from "react";
3
+ import { useGridLab } from "./grid-lab.js";
4
+ export const GRID_BOXES_QUERY = "(pointer: fine) and (hover: hover)";
5
+ function canAsk() {
6
+ return typeof window !== "undefined" && typeof window.matchMedia === "function";
7
+ }
8
+ function subscribe(onChange) {
9
+ if (!canAsk())
10
+ return () => { };
11
+ const list = window.matchMedia(GRID_BOXES_QUERY);
12
+ list.addEventListener("change", onChange);
13
+ return () => list.removeEventListener("change", onChange);
14
+ }
15
+ const fine = () => !canAsk() || window.matchMedia(GRID_BOXES_QUERY).matches;
16
+ const onServer = () => true;
17
+ const noSubscribe = () => () => { };
18
+ export function useGridBoxes() {
19
+ const asked = useGridLab()?.boxes === 2;
20
+ const fineNow = useSyncExternalStore(asked ? subscribe : noSubscribe, asked ? fine : onServer, onServer);
21
+ return asked && !fineNow ? 2 : 1;
22
+ }
@@ -5,12 +5,13 @@ import { gridWidthVar } from "../core/grid-scale.js";
5
5
  import { clampColumnWidth, columnHideable, isColumnHidden, prettifyOptionValue, resolveColumnOrder, resolveColumnWidths, resolveVisibleColumns, toggleColumnHidden, } from "../../model/column-state.js";
6
6
  import { useViews } from "../../provider/context.js";
7
7
  import { gridColumnGlyph } from "./column-glyph.js";
8
+ import { partWord } from "../../model/part-rows.js";
8
9
  function setBodyResizeState(active) {
9
10
  document.body.style.cursor = active ? "col-resize" : "";
10
11
  document.body.style.userSelect = active ? "none" : "";
11
12
  }
12
13
  export function useGridColumnLayout({ rootRef, columns, columnState, onColumnStateChange, scale, freezeIdentity = true, viewBacked = false, }) {
13
- const { icons, components } = useViews();
14
+ const { icons, components, messages } = useViews();
14
15
  const orderKey = columnState?.order;
15
16
  const hiddenKey = columnState?.hidden;
16
17
  const shownKey = columnState?.visible;
@@ -70,13 +71,37 @@ export function useGridColumnLayout({ rootRef, columns, columnState, onColumnSta
70
71
  hidden: isColumnHidden(col, viewBacked && !columnPlacedByView(col) ? undefined : columnState),
71
72
  hideable: !viewBacked || columnPlacedByView(col) ? columnHideable(col) : false,
72
73
  fixed: viewBacked && !columnPlacedByView(col),
74
+ ...(col.partOf
75
+ ? {
76
+ partOf: {
77
+ column: col.partOf.column,
78
+ part: col.partOf.part,
79
+ label: partWord(col.partOf.field.type, col.partOf.part, messages) ?? col.partOf.part,
80
+ },
81
+ }
82
+ : {}),
73
83
  })),
74
84
  onToggleHidden: (id, hide) => {
75
85
  const col = columns.find((candidate) => candidate.id === id);
76
86
  if (viewBacked && col && !columnPlacedByView(col))
77
87
  return;
78
- if (col)
79
- onColumnStateChange(toggleColumnHidden(columnState, col, hide));
88
+ if (!col)
89
+ return;
90
+ const next = toggleColumnHidden(columnState, col, hide);
91
+ if (!hide && col.partOf && columnState?.order) {
92
+ const whole = col.partOf.column;
93
+ const order = baseColumnOrder(columns, columnState.order, viewBacked).filter((other) => other !== id);
94
+ const at = order.indexOf(whole);
95
+ if (at >= 0) {
96
+ const partOf = new Map(columns.map((column) => [column.id, column.partOf?.column]));
97
+ let end = at + 1;
98
+ while (end < order.length && partOf.get(order[end]) === whole)
99
+ end += 1;
100
+ order.splice(end, 0, id);
101
+ next.order = viewBacked ? resolveViewColumnOrder(columns, order) : order;
102
+ }
103
+ }
104
+ onColumnStateChange(next);
80
105
  },
81
106
  onReorder: (ids) => onColumnStateChange({
82
107
  ...columnState,
@@ -85,7 +110,7 @@ export function useGridColumnLayout({ rootRef, columns, columnState, onColumnSta
85
110
  onReset: () => onColumnStateChange({}),
86
111
  dirty: Object.keys(columnState ?? {}).length > 0,
87
112
  };
88
- }, [columnState, columns, components.AppIcon, icons, onColumnStateChange, viewBacked]);
113
+ }, [columnState, columns, components.AppIcon, icons, messages, onColumnStateChange, viewBacked]);
89
114
  const gridTemplate = useMemo(() => [
90
115
  "0px",
91
116
  ...visibleColumns.map((col) => `calc(var(${gridWidthVar(col.id)}) * var(--vk-scale))`),
@@ -10,6 +10,7 @@ import { activeRangeHead, gridNavIntent, nextCellLinear, nextCellPos, resolveNav
10
10
  import { copyCell } from "./cell-clipboard.js";
11
11
  import { GRID_KEY_OWNING_SURFACES, gridFocusElement } from "./useGridFocus.js";
12
12
  import { isGridRowMenuKey, openGridRowMenu } from "./grid-row-menu-key.js";
13
+ import { openGridEditEscape } from "./grid-edit-escape.js";
13
14
  import { gridBarArrow, gridFocusStep, gridFocusTab, } from "../core/grid-focus.js";
14
15
  const NAV_KEYS = {
15
16
  ArrowUp: "up",
@@ -249,7 +250,7 @@ export function useGridKeyboard({ rootRef, focusedCell, editingCell, editingEnab
249
250
  if (event.key === "Escape") {
250
251
  event.stopPropagation();
251
252
  if (editingCell)
252
- cancelEdit();
253
+ (openGridEditEscape() ?? cancelEdit)();
253
254
  else {
254
255
  clearFocus();
255
256
  releaseToFrame();
@@ -315,7 +316,9 @@ export function useGridKeyboard({ rootRef, focusedCell, editingCell, editingEnab
315
316
  isWholeTextColumn(column) &&
316
317
  gridCellCutOff(findGridCell(rootRef.current, focusedCell));
317
318
  if (column &&
318
- ((editingEnabled && gridColumnHasEditor(column)) || gridColumnInspectable(column) || whole)) {
319
+ ((editingEnabled && gridColumnHasEditor(column) && columnEffectiveWritable(column, listConfig)) ||
320
+ gridColumnInspectable(column) ||
321
+ whole)) {
319
322
  startEdit(focusedCell.rowId, focusedCell.columnId, undefined, whole);
320
323
  return;
321
324
  }
@@ -330,6 +333,8 @@ export function useGridKeyboard({ rootRef, focusedCell, editingCell, editingEnab
330
333
  return;
331
334
  }
332
335
  }
336
+ if (column && refuseEdit(column.id))
337
+ return;
333
338
  const next = nextCellPos(focusedCell, "down", visibleRowIds, visibleColIds);
334
339
  if (!next)
335
340
  return;
@@ -0,0 +1,5 @@
1
+ import type { ListColumn } from "../../model/column-schema.js";
2
+ /** The columns the grid lays out: with `parts`, each whole followed by its part columns (`withPartColumns`), worded
3
+ * by the provider's messages and read in its locale; without, the columns as declared. The part columns live in the
4
+ * grid alone: an app's panels keep the whole columns, whose part rows share the part columns' keys. */
5
+ export declare function useGridPartColumns<Row>(columns: ListColumn<Row>[], parts: boolean | undefined): ListColumn<Row>[];
@@ -0,0 +1,9 @@
1
+ "use client";
2
+ import { useMemo } from "react";
3
+ import { withPartColumns } from "../../model/part-columns.js";
4
+ import { useViews } from "../../provider/context.js";
5
+ export function useGridPartColumns(columns, parts) {
6
+ const { messages, conventions } = useViews();
7
+ const locale = conventions.locale;
8
+ return useMemo(() => (parts ? withPartColumns(columns, { messages, locale }) : columns), [columns, parts, messages, locale]);
9
+ }
@@ -211,7 +211,8 @@ export function useGridRangeGestures({ rootRef, focusedCell, editingCell, editin
211
211
  if (rootRef.current?.contains(target)) {
212
212
  if (target.closest?.("[data-col-id]"))
213
213
  return;
214
- if (target.dataset?.slot === "vk-grid-scroll" && onScrollbar(target, event))
214
+ const slot = target.dataset?.slot;
215
+ if ((slot === "vk-grid-scroll" || slot === "vk-grid-pan") && onScrollbar(target, event))
215
216
  return;
216
217
  }
217
218
  if (editingRef.current) {
@@ -0,0 +1,16 @@
1
+ import { type RefObject } from "react";
2
+ import { type GridRecorder, type GridRecordingContext } from "../core/grid-recorder.js";
3
+ import type { GridLab } from "./grid-lab.js";
4
+ /**
5
+ * The grid's recorder, while the lab asks for one (`lab.record`). The row window writes each scroll
6
+ * sample of either box into it and the scroll area amends the table's sideways offset; this hook adds what the grid
7
+ * doesn't otherwise hear: the frames, the touches, and when to send. Every listener is passive and
8
+ * it writes nothing to the page. With no `record`, the ref stays null and nothing is attached.
9
+ */
10
+ export declare function useGridRecorder({ rootRef, lab, boxes, grid, }: {
11
+ rootRef: RefObject<HTMLDivElement | null>;
12
+ lab: GridLab | null;
13
+ /** The grid's mode: its boxes are drawn anew when it changes, and the listeners follow them. */
14
+ boxes: 1 | 2;
15
+ grid: () => GridRecordingContext["grid"];
16
+ }): RefObject<GridRecorder | null>;
@@ -0,0 +1,144 @@
1
+ "use client";
2
+ import { useLayoutEffect, useRef } from "react";
3
+ import { createGridRecorder, gridRecordingId, } from "../core/grid-recorder.js";
4
+ import { GRID_WINDOW_OVERSCAN } from "../core/row-window.js";
5
+ const STILL_MS = 3000;
6
+ const RELEASE_WINDOW_MS = 100;
7
+ let pageSession = null;
8
+ const sessionId = () => (pageSession ??= gridRecordingId());
9
+ export function useGridRecorder({ rootRef, lab, boxes, grid, }) {
10
+ const recorderRef = useRef(null);
11
+ const gridRef = useRef(grid);
12
+ useLayoutEffect(() => {
13
+ gridRef.current = grid;
14
+ });
15
+ const send = lab?.record;
16
+ useLayoutEffect(() => {
17
+ if (!send)
18
+ return;
19
+ const area = rootRef.current?.querySelector('[data-slot="vk-grid-scroll"]');
20
+ if (!area)
21
+ return;
22
+ const pan = rootRef.current?.querySelector('[data-slot="vk-grid-pan"]') ?? null;
23
+ const touched = pan ?? area;
24
+ let page = location.pathname.slice(0, 300);
25
+ const recorder = createGridRecorder({
26
+ send,
27
+ session: sessionId(),
28
+ context: () => ({
29
+ page,
30
+ lab: { overscan: GRID_WINDOW_OVERSCAN },
31
+ device: {
32
+ ua: navigator.userAgent.slice(0, 400),
33
+ dpr: devicePixelRatio,
34
+ screen: [screen.width, screen.height],
35
+ viewport: [innerWidth, innerHeight],
36
+ cores: navigator.hardwareConcurrency ?? 0,
37
+ },
38
+ grid: gridRef.current(),
39
+ }),
40
+ });
41
+ recorderRef.current = recorder;
42
+ let frame = 0;
43
+ let idle;
44
+ let lastActivity = 0;
45
+ let fingers = 0;
46
+ let lastT = 0;
47
+ let lastX = 0;
48
+ let lastY = 0;
49
+ let prevT = 0;
50
+ let prevX = 0;
51
+ let prevY = 0;
52
+ const gridRecorderFrame = (now) => {
53
+ recorder.frame(now);
54
+ frame = requestAnimationFrame(gridRecorderFrame);
55
+ };
56
+ const flush = () => {
57
+ clearTimeout(idle);
58
+ idle = undefined;
59
+ if (frame)
60
+ cancelAnimationFrame(frame);
61
+ frame = 0;
62
+ recorder.flush();
63
+ };
64
+ const check = () => {
65
+ idle = undefined;
66
+ if (fingers > 0)
67
+ return;
68
+ const left = STILL_MS - (performance.now() - lastActivity);
69
+ if (left > 0)
70
+ idle = setTimeout(check, left);
71
+ else
72
+ flush();
73
+ };
74
+ const arm = () => {
75
+ lastActivity = performance.now();
76
+ if (fingers === 0 && idle === undefined)
77
+ idle = setTimeout(check, STILL_MS);
78
+ };
79
+ const wake = () => {
80
+ if (recorder.empty)
81
+ page = location.pathname.slice(0, 300);
82
+ if (!frame)
83
+ frame = requestAnimationFrame(gridRecorderFrame);
84
+ arm();
85
+ };
86
+ const onScroll = () => wake();
87
+ const onTouchStart = (event) => {
88
+ fingers = event.touches.length;
89
+ const touch = event.touches[0];
90
+ const now = performance.now();
91
+ lastT = prevT = now;
92
+ lastX = prevX = touch?.clientX ?? 0;
93
+ lastY = prevY = touch?.clientY ?? 0;
94
+ recorder.touch(now, "start", lastX, lastY);
95
+ wake();
96
+ };
97
+ const onTouchMove = (event) => {
98
+ const touch = event.touches[0];
99
+ if (!touch)
100
+ return;
101
+ prevT = lastT;
102
+ prevX = lastX;
103
+ prevY = lastY;
104
+ lastT = performance.now();
105
+ lastX = touch.clientX;
106
+ lastY = touch.clientY;
107
+ };
108
+ const onTouchEnd = (event) => {
109
+ fingers = event.touches.length;
110
+ const now = performance.now();
111
+ const span = lastT - prevT;
112
+ const fresh = now - lastT <= RELEASE_WINDOW_MS && span > 0;
113
+ recorder.touch(now, "end", fresh ? ((lastX - prevX) / span) * 1000 : 0, fresh ? ((lastY - prevY) / span) * 1000 : 0);
114
+ arm();
115
+ };
116
+ const onVisibility = () => {
117
+ if (document.visibilityState !== "hidden")
118
+ return;
119
+ fingers = 0;
120
+ flush();
121
+ };
122
+ const passive = { passive: true };
123
+ area.addEventListener("scroll", onScroll, passive);
124
+ pan?.addEventListener("scroll", onScroll, passive);
125
+ touched.addEventListener("touchstart", onTouchStart, passive);
126
+ touched.addEventListener("touchmove", onTouchMove, passive);
127
+ touched.addEventListener("touchend", onTouchEnd, passive);
128
+ touched.addEventListener("touchcancel", onTouchEnd, passive);
129
+ document.addEventListener("visibilitychange", onVisibility, passive);
130
+ return () => {
131
+ area.removeEventListener("scroll", onScroll);
132
+ pan?.removeEventListener("scroll", onScroll);
133
+ touched.removeEventListener("touchstart", onTouchStart);
134
+ touched.removeEventListener("touchmove", onTouchMove);
135
+ touched.removeEventListener("touchend", onTouchEnd);
136
+ touched.removeEventListener("touchcancel", onTouchEnd);
137
+ document.removeEventListener("visibilitychange", onVisibility);
138
+ flush();
139
+ if (recorderRef.current === recorder)
140
+ recorderRef.current = null;
141
+ };
142
+ }, [rootRef, send, boxes]);
143
+ return recorderRef;
144
+ }
@@ -0,0 +1,41 @@
1
+ import { type RefObject } from "react";
2
+ import type { GridCellPos } from "../core/coordinates.js";
3
+ import { type GridRowOpenedFrom } from "../core/row-opened-from.js";
4
+ type Opener<Row> = {
5
+ rootRef: RefObject<HTMLDivElement | null>;
6
+ onOpenRow: (row: Row, from: GridRowOpenedFrom) => void;
7
+ /** The open groups' row keys, in order. */
8
+ visibleRowKeys: readonly string[];
9
+ visibleColIds: readonly string[];
10
+ /** The grid's own focused cell (with its one-cell range): where its ring and its keys go from. */
11
+ focusCell: (rowId: string, columnId: string) => void;
12
+ /** Scrolls to a cell, drawing its row first when the row window hasn't. */
13
+ revealCell: (pos: GridCellPos, behavior: ScrollBehavior) => void;
14
+ desktopQuery: string;
15
+ };
16
+ /**
17
+ * The grid's side of `onOpenRow`: a row hands the cell it was opened from, and the app gets, with the row, a `from`
18
+ * that brings the focus back there once what it opened closes. The place is resolved when `from` is called, against
19
+ * the rows as they are then (`resolveOpenedFrom`), and revealed: a row a refetch moved past the drawn ones is drawn.
20
+ * On a desktop the grid's focused cell moves there too once the focus has landed, so its ring shows where the keyboard
21
+ * is and the next arrow moves from it; on a phone (asked at the call, as a tap asks) only the focus goes back, and the
22
+ * phone looks as it did.
23
+ *
24
+ * Both are settled again after the commit (`afterCommit`): asked inside one, `element()` may answer from rows about
25
+ * to change, or the frame for a row not drawn yet. Then, while the focus is still free in the grid (on the page's
26
+ * body, the frame, or a part of the grid that isn't typing or a menu, as `useGridFocus` judges it), it moves to the
27
+ * cell; anywhere else (the person clicked away, the dialog let it go), it stays, and no cell is selected.
28
+ *
29
+ * A dialog that focuses only a tab stop passes the frame it was handed (a row not drawn yet, or no longer shown) on
30
+ * to the frame's start guard. While a settle is pending, `settling()` is true and the grid doesn't enter on a guard's
31
+ * focus (its entry cell would be selected, a ring a phone never shows); the settle then takes the focus from the
32
+ * guard to the cell, or to the frame when the cell isn't there.
33
+ *
34
+ * The opener keeps one identity for the grid's life (the rows are `memo`'d); what it reads is the latest render's.
35
+ */
36
+ export declare function useGridRowOpener<Row>(args: Opener<Row>): {
37
+ openRow: (row: Row, at: GridCellPos) => void;
38
+ /** Whether a `from` is still to settle: a guard's focus then waits for it instead of entering the grid. */
39
+ settling: () => boolean;
40
+ };
41
+ export {};