@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,6 @@
1
1
  # Selection
2
2
 
3
- People pick rows to act on several at once: a click with a modifier, a checkbox, a drag down the checkbox lane, select all. `@viewkitjs/views/selection` holds the selection itself and the rules a row follows; the bar a selection opens, and what its verbs do, are your app's. This page builds a plain list that people can select, then hands a selection to the grid, which wires the same pieces itself.
3
+ People pick rows to act on several at once: a click with a modifier, a checkbox, a drag down the checkbox lane, select all. `@viewkitjs/views/selection` holds the selection itself, the rules a row follows and the bar a selection opens; what its verbs do is your app's. This page builds a plain list that people can select, then hands a selection to the grid, which wires the same pieces itself.
4
4
 
5
5
  ## A list's selection
6
6
 
@@ -31,6 +31,7 @@ import {
31
31
  ROW_NO_TEXT_SELECT,
32
32
  ROW_OPEN_STOP_SELECTOR,
33
33
  SelectCheckbox,
34
+ SelectionBar,
34
35
  selectFromClick,
35
36
  useCheckDragSelect,
36
37
  useEscapeToClear,
@@ -38,6 +39,7 @@ import {
38
39
  useRestIntent,
39
40
  type ListBatchApi,
40
41
  type ListSelectionConfig,
42
+ type SelectionVerb,
41
43
  type UseListSelectionResult,
42
44
  } from "@viewkitjs/views/selection";
43
45
 
@@ -195,41 +197,51 @@ function DealList({ deals, filterKey }: { deals: Deal[]; filterKey: string }) {
195
197
  }
196
198
  ```
197
199
 
198
- ## The bar is yours
200
+ ## The bar
199
201
 
200
- What a selection lets a person do (move twelve deals to a stage, export them, delete them) is your app's, and so is the bar that offers it. It reads the selection and acts through your API, then calls `clear`.
202
+ `SelectionBar` is the bar a selection opens: the count, which clears the selection when pressed (Escape does too, where the list wires `useEscapeToClear`, as the grid does), your verbs, a trash when you hand `onDelete`, and More. On a desktop it floats as an island at the foot of the screen, the first four verbs on it and the rest in More; on a phone it is a pill reading "3 selected · Actions · ✕", whose Actions open a sheet of every verb. It draws nothing while `count` is zero, so a `renderBar` can always return it.
203
+
204
+ What a selection lets a person do (move twelve deals to a stage, export them, delete them) is your app's. You hand the bar its verbs as data, a `SelectionVerb` each, and each verb's handler calls your own action over the selected ids, then `clear`; an agent working through your actions does the same thing. A verb is one of three kinds:
205
+
206
+ - `action`: a button, with its `label`, an optional `icon` and `onClick`; `destructive` paints it in the danger colour;
207
+ - `group`: a button opening a small menu of `items`, each an action;
208
+ - `options`: one field set on every selected row, its `options` drawn as the badges a cell shows (a `PickerOption` each), `onSelect` handed the value picked.
209
+
210
+ Delete is not a verb: it is the bar's own `onDelete`, drawn as the trailing trash in the same place on every list (in words, last, in the phone's sheet). `busy` disables everything while a batch runs.
201
211
 
202
212
  A renderer with an editing model also hands the bar a `ListBatchApi`: `setColumnValue(rowIds, columnId, value)` writes one column across the rows through the renderer's own write path, and resolves to whether the write landed. The grid's goes through the same gate as a cell edit, so a column that can't be written, or one a workspace locked, resolves `false`, and a selected id whose row isn't loaded is skipped. The plain list above has no editing model, so its bar gets none.
203
213
 
204
214
  ```tsx
205
215
  function DealsBar({ sel, batch }: { sel: UseListSelectionResult; batch?: ListBatchApi }) {
206
- if (sel.count === 0) return null;
207
- const moveToProposal = async () => {
208
- const landed = await batch?.setColumnValue([...sel.selectedIds], "stage", "proposal");
216
+ const moveTo = async (stage: string) => {
217
+ const landed = await batch?.setColumnValue([...sel.selectedIds], "stage", stage);
209
218
  if (landed) sel.clear();
210
219
  };
211
- return (
212
- <div role="toolbar">
213
- <span>{sel.count} selected</span>
214
- {batch ? (
215
- <button type="button" onClick={() => void moveToProposal()}>
216
- Move to proposal
217
- </button>
218
- ) : null}
219
- <button type="button" onClick={sel.clear}>
220
- Clear
221
- </button>
222
- </div>
223
- );
220
+ const verbs: SelectionVerb[] = batch
221
+ ? [
222
+ {
223
+ kind: "options",
224
+ label: "Move to stage",
225
+ options: [
226
+ { value: "proposal", label: "Proposal", slot: "running" },
227
+ { value: "won", label: "Won", slot: "success" },
228
+ ],
229
+ onSelect: (stage) => void moveTo(stage),
230
+ },
231
+ ]
232
+ : [];
233
+ return <SelectionBar count={sel.count} onClear={sel.clear} verbs={verbs} />;
224
234
  }
225
235
  ```
226
236
 
237
+ Where the bar sits is yours, set once on the provider's `selectionBar`: its `bottom`, `zIndex` and `className` on each form, and a `phoneQuery` when your shell's phone layout starts at another width (an app with a bottom nav lifts the pill above it). The phone's sheet is the `SelectionSheet` atom: its default is your `Sheet` holding plain rows, and you swap in your own action sheet through the provider's `atoms`.
238
+
227
239
  ## The grid takes a selection
228
240
 
229
241
  `GridTable` wires the selection itself when you pass `selection`, a `ListSelectionConfig`: its checkbox rail (Shift on a checkbox extends the range), the drag down the lane (rows in collapsed groups left out), a plain click toggling a row while rows are selected, Escape, and a group's checkbox. One rule differs from a plain list: in the grid a modifier click on a cell is a cell-range gesture, as in a spreadsheet (Shift extends the active range, Cmd or Ctrl adds the cell), so rows are picked from the rail. You give it:
230
242
 
231
243
  - `resetKey`: the selection clears when it changes;
232
- - `renderBar(sel, batch?)`: your bar, drawn from the selection and, when the grid can write (you passed `onCellCommit`), its `ListBatchApi`. The grid calls it on every render, so the bar draws nothing while `sel.count` is zero;
244
+ - optionally `renderBar(sel, batch?)`: the bar, drawn from the selection and, when the grid can write (you passed `onCellCommit`), its `ListBatchApi`. The grid calls it on every render, and `SelectionBar` draws nothing while `sel.count` is zero. Leave it out and rows still tick, with no bar;
233
245
  - optionally `orderedIds`, when the order a range runs over is not the grid's rows as drawn, and `retention`.
234
246
 
235
247
  ```tsx
@@ -169,7 +169,8 @@ The header's menu offers Sort ascending, Sort descending and Clear sort, and Gro
169
169
 
170
170
  ```tsx
171
171
  import { useMemo, useState } from "react";
172
- import { columnLabel, sortableColumns, sortDirFor, type OrderDir } from "@viewkitjs/views";
172
+ import type { SortDirection } from "@viewkitjs/fields/query";
173
+ import { columnLabel, sortableColumns, sortDirFor } from "@viewkitjs/views";
173
174
  import type { GridGroupByState, GridGroupSortOption, GridSortState } from "@viewkitjs/views/grid";
174
175
 
175
176
  const dealSortOptions: GridGroupSortOption[] = sortableColumns(columns).map((entry) => ({
@@ -191,7 +192,7 @@ assert.deepEqual(
191
192
  );
192
193
 
193
194
  function SortedDeals({ deals, onOpen }: { deals: Deal[]; onOpen: (deal: Deal) => void }) {
194
- const [order, setOrder] = useState<{ value: string; dir: OrderDir }>({ value: "value", dir: "desc" });
195
+ const [order, setOrder] = useState<{ value: string; dir: SortDirection }>({ value: "value", dir: "desc" });
195
196
  const [groupKey, setGroupKey] = useState<string | null>("stage");
196
197
  const [collapsed, setCollapsed] = useState<ReadonlySet<string>>(new Set());
197
198
 
@@ -246,7 +247,7 @@ Editing turns on with `onCellCommit`: without it the grid is read-only, and invi
246
247
  - It resolves with `{ status: "unconfirmed", history: false }`: nothing says the write landed, and it leaves no step to undo.
247
248
  - It rejects (or throws): the cell rolls back to the value it held. Never swallow a failed request, since the rejection is what rolls the cell back.
248
249
 
249
- A `write` that refuses, `{ skip: true, reason }`, is a rejection too: throw its reason, and the cell rolls back. The grid shows no reason for a rejection, so your app shows it, through its own toast. Returning nothing on a refusal would count a write that was never sent as landed, with a step to undo.
250
+ A `write` that refuses, `{ skip: true, reason }`, is a rejection too: throw its reason, and the cell rolls back. With the provider's `sayRefusals` on, the grid says why through your toast's `error`: the error's own words (its `message`, shown as it is, so reject with words a person can read), or "Couldn't save Amount." when it has none, and a batch, a paste or an undo once, with its count. Off, the default, your app shows it, through its own toast; turn it on and stop toasting your own, or each says twice. Returning nothing on a refusal would count a write that was never sent as landed, with a step to undo.
250
251
 
251
252
  What a cell commits is its type's commit ([the contract](../contract.md#four-shapes-of-a-value)), with one exception: Delete, Cut, the row menu's Clear and a clear over a range commit `""` for most types (a relation `null`, a multiselect `[]`, a boolean `false`). A `write` maps `""` to what the row stores for nothing, as `closeOn` does above. An undo that empties a number, percent or money cell again writes `null`.
252
253
 
@@ -391,7 +392,11 @@ function DealsWithPrefs({ onOpen }: { onOpen: (deal: Deal) => void }) {
391
392
  }
392
393
  ```
393
394
 
394
- The columns' widths, order and visibility travel as `columnState`, a `ListColumnState` (`widths` by column id, `hidden` ids, `visible` ids of columns hidden by default that the person turned on, and `order`), and every change as `onColumnStateChange`; `gridProps` carries both. Resizing, moving and hiding a column, and the header's "+ Add column", which lists the hidden columns, appear only where `onColumnStateChange` is passed, since there would be nowhere to keep them. `renderAddColumn` replaces that last cell with your own, and `renderColumnMenuRows` adds your rows (Edit field, say) to a column's menu above Hide.
395
+ The columns' widths, order and visibility travel as `columnState`, a `ListColumnState` (`widths` by column id, `hidden` ids, `visible` ids of columns hidden by default that the person turned on, and `order`), and every change as `onColumnStateChange`; `gridProps` carries both. Resizing, moving and hiding a column, and the header's "+ Add column", which lists the hidden columns, appear only where `onColumnStateChange` is passed, since there would be nowhere to keep them. `renderAddColumn` replaces that last cell with your own; answering `null` draws none and keeps no room for it, so column state needs no Add column. `renderColumnMenuRows` adds your rows (Edit field, say) to a column's menu above Hide. On the `menu` route (the provider's `menus`), hand your rows as data through `columnMenuItems(fieldKey)`, keyed apart from the grid's own (it is called while the grid renders, for every column, so keep it pure and cheap); `renderColumnMenuRows` isn't drawn there. On a phone the header ends with nothing unless you pass `addColumnOnPhone`: then "+ Add column" ends it there too, its list in your `Sheet` (your `Menu` on the `menu` route), where a person brings back a column they hid on the phone.
396
+
397
+ ### A column per part
398
+
399
+ With `parts`, a name, a place or a range offers a column per part beside its whole column: a place's country, region, city and postal code, a name's given and family names, a range's low and high ends. Each starts hidden; "+ Add column" lists a field with parts as one row that drills into the field (when hidden) and its hidden parts, as Attio's does, and a search lists parts by their full label ("Address · Country"). On the `menu` route (the provider's `menus`) that field is a group beside your `Menu`, its count as `detail`, with no search field, and on a phone too it is your `Menu`, not your `Sheet`. A part column's id is `partKey(columnId, part)`, the key its Filter row has when your panels pass `parts: true`, so that row filters what the column shows; its sort value is `partKey(fieldKey, part)`, which `parsePartKey` turns into a sort's `fieldKey` and `by`. It reads and copies its part, and it edits and pastes as its part, in a box of its own: text for a name's part and a place's region, city and postal code, a number for a range's end, and the select over every country by name, searchable, for a place's country. A paste or a fill into a country cell takes a country's name, in the app's locale or in English, or its code. A part is locked, refused and read-only as its whole is, and it may be emptied unless its whole declares `clearable: false`; emptying the last part is judged by the field. A box refuses a value the whole field would refuse, such as a range's low end above its high end, and stays open with the field's reason. Your `onCellCommit` and `onCellsCommit` receive the whole column's id and the whole value with that part replaced, so a place keeps its other parts, a range its other end and a name its other part. A name's full name follows its given or family name only when it was empty or exactly the two joined by a space; "Nagy Imre" is kept. A place's other country clears its region and its code, and another region clears its code. A paste over two parts of one field in one row lands as one edit of the whole, and a part edit made while the field's earlier ones are still in flight builds on them. Like every composite value's, the commit goes without a pending overlay; the refetch repaints. Escape in a part's box follows the box's own type, text or number, not the field's, so `escape={{ name: "keep" }}` on the provider does not reach a given name's box. A place field limited to some `parts` offers part columns only for those. Its menu offers no Group row. Keep part columns out of your panels: they belong to the grid, and your panels take the columns you declare.
395
400
 
396
401
  `gridProps` also carries the per-person switches: `verticalBorders`, `showRowIcon` (the `rowIcon` you declare, in the title cell), `freezeIdentity` (every column through the title pinned at the left edge; off in `LIST_VIEW_PREF_DEFAULTS`, so start your prefs with `gridFreezeIdentity: true` to open it on), `alwaysCheckboxes` and `scale`, the density. Every row is one height, and a cell's text stays on one line.
397
402
 
@@ -399,7 +404,9 @@ The columns' widths, order and visibility travel as `columnState`, a `ListColumn
399
404
 
400
405
  Each column's footer shows one figure: the person's pick from what the column offers (sum, average, min, max and count for a number, count, filled and unique for the rest), else the column's `defaultAggregate`. Pass `aggregates`, the picks by column id, and `onAggregateChange`, which makes each footer cell a picker. On a `viewBacked` list only a column with a field can change its pick. With neither `onAggregateChange` nor a `renderAggregate` of your own, the grid draws no footer. `renderAggregate(columnId, group)` draws a footer cell yourself, with no label.
401
406
 
402
- A group's band shows its count and, beside it, the figures the person turned on. `groupSummary` is that set of parts (`"count"`, `"total"` for the list's first figure, `total:<columnId>` for each one after it), changed through `onGroupSummaryChange`, and `groupFigures` declares which figures a band can show and how each draws. `countNoun` words the count ("2 deals"); without it the count is bare. `countOf` answers the count when a group holds more rows than are loaded.
407
+ A group's band shows its count and, beside it, the figures the person turned on. `groupSummary` is that set of parts (`"count"`, `"total"` for the list's first figure, `total:<columnId>` for each one after it), changed through `onGroupSummaryChange`, and `groupFigures` declares which figures a band can show. Declare one by its `column` and `kind` (`"sum"`, `"avg"` and the rest of the footer's picks), and the grid adds it up and writes it as that column's footer does: the same number, in the column's format and currency, a paged group's from your `figures`, or your own footer cell where `renderAggregate` draws one. Its `label` is the column's header unless you give one. To draw a figure yourself, give `label` and `render(group)` in place of `column` and `kind`. `countNoun` words the count ("2 deals"); without it the count is bare. `countOf` answers the count when a group holds more rows than are loaded.
408
+
409
+ A band's ⋯ menu holds the sort choices (`sort` with `sortOptions`), the figure toggles (`groupFigures` with `onGroupSummaryChange`) and Hide (`onHideGroup`). By default the ⋯ opens for sort or Hide, the figure toggles come with them, and the sort list searches through your `Command` once it passes eight choices, on the `popover` route; on the `menu` route the choices open beside the menu with no search field. `groupMenu` names the parts yourself, `["sort", "figures", "hide"]` or any of them: the ⋯ then holds exactly the parts you named and passed what they need, so the figure toggles or Hide come without sort, and the sort list always searches through your `Command`, at any count (on the `popover` route). An app whose `Command` isn't ready leaves `"sort"` out (on the `popover` route; the `menu` route uses no `Command`), and knows from its props which slots the menu reaches.
403
410
 
404
411
  When the rows come a page at a time, a group's `figures` are your database's over the whole group, and the footer reads its picks from them rather than from the rows in hand. `GroupFigures` in the [root reference](../reference/views.md) has the shape.
405
412
 
@@ -407,19 +414,10 @@ When the rows come a page at a time, a group's `figures` are your database's ove
407
414
  import { groupFigurePart, type ListAggregateKind } from "@viewkitjs/views";
408
415
  import type { GridGroupFigure, GroupCountNoun } from "@viewkitjs/views/grid";
409
416
 
410
- const euros = new Intl.NumberFormat(conventions.locale, { style: "currency", currency: "EUR" });
411
-
412
- /** A group's total value: the database's figure when it counted one, else the rows in hand. */
413
- function dealTotal(group: ListGroup<Deal>): string {
414
- const counted = group.figures?.fields.value?.sum;
415
- return euros.format(counted ?? group.items.reduce((sum, deal) => sum + deal.value, 0));
416
- }
417
-
418
- const dealFigures: GridGroupFigure<Deal>[] = [{ part: groupFigurePart("value", true), label: "Value", render: dealTotal }];
417
+ const dealFigures: GridGroupFigure<Deal>[] = [{ part: groupFigurePart("value", true), column: "value", kind: "sum" }];
419
418
  const dealNoun: GroupCountNoun = { one: "deal", other: "deals" };
420
419
 
421
420
  assert.equal(dealFigures[0].part, "total");
422
- assert.equal(dealTotal(stageGroups[1]), "€31,200.00");
423
421
 
424
422
  function DealsWithFigures({ onOpen }: { onOpen: (deal: Deal) => void }) {
425
423
  const [aggregates, setAggregates] = useState<Record<string, ListAggregateKind>>({});
@@ -446,6 +444,30 @@ function DealsWithFigures({ onOpen }: { onOpen: (deal: Deal) => void }) {
446
444
 
447
445
  On a desktop, a click on the title's text calls `onOpenRow`, and a click anywhere else selects the cell. Below your provider's `desktopQuery`, a tap anywhere on the title's cell calls `onOpenRow`, and a tap on any other cell opens its editor (The keyboard and the pointer, below). `rowHref` gives a row its own page: a middle-click opens it in a new tab, and the row's menu starts with Open page. `onPrefetchRow` is called on a pointer's intent to open, to warm the row's detail.
448
446
 
447
+ `onOpenRow` receives, with the row, a `from` (`GridRowOpenedFrom`): the way back to the cell the row was opened from, for when what it opened closes. A dialog that takes an element to focus on close takes `from.element`; one that doesn't calls `from.focus()` as it closes. Either way the focus lands on that cell, read again at that moment: a record a refetch moved under another group is found by its id, and a record no longer shown sends the focus into the grid. On a desktop the cell is selected and the next arrow moves from it; below your `desktopQuery` only the focus goes back, and no cell is selected. A dialog that asks for its final focus while React is still closing it gets an answer the grid settles once the close is done. A close the person made by pressing somewhere else should leave the focus where they pressed: skip `from` for that close (a dialog's final-focus option usually says why it closed).
448
+
449
+ ```tsx
450
+ import type { GridRowOpenedFrom } from "@viewkitjs/views/grid";
451
+
452
+ declare function DealDrawer(props: { deal: Deal | null; onClose: () => void; finalFocus?: () => HTMLElement | null }): null;
453
+
454
+ function DealsWithDrawer() {
455
+ const [open, setOpen] = useState<{ deal: Deal; from: GridRowOpenedFrom } | null>(null);
456
+ return (
457
+ <>
458
+ <GridTable
459
+ groups={allDeals}
460
+ grouped={false}
461
+ getRowId={(deal) => deal.id}
462
+ columns={columns}
463
+ onOpenRow={(deal, from) => setOpen({ deal, from })}
464
+ />
465
+ <DealDrawer deal={open?.deal ?? null} onClose={() => setOpen(null)} finalFocus={open?.from.element} />
466
+ </>
467
+ );
468
+ }
469
+ ```
470
+
449
471
  The row's menu opens on a right-click and from the row's ⋯ at its end. It holds the cell's Copy, Cut, Paste and Clear, the rows your `rowMenu` builds, and Delete when you pass `onRowDelete`. Delete asks your `confirm` port first, with `deleteLabel` as what is deleted, and a delete that rejects says so through your toast port. `contextMenu` replaces `rowMenu` on right-click when the two must differ.
450
472
 
451
473
  `onOpenRelation` makes relation chips open what they point at; it receives the chip's value, so `value.entity` says which kind of record to open. Without it, a chip goes where your `RelationLink` atom says ([atoms](atoms.md)). `entityIcon` gives each kind of record its glyph in relation cells that carry none.
@@ -605,9 +627,9 @@ assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
605
627
 
606
628
  **A day or a moment.** A `date` opens the date editor with its date box and the calendar, no time: a click on a day saves it. A `datetime` keeps its time box (an empty time starts at 00:00) and stays open after a day click, so the time can be set; a click away or Enter saves both. Today, Tomorrow and Next Monday sit above the calendar, each setting its day as a click on the calendar does, a datetime's time kept. A column that may be emptied (`clearable`) ends the editor with a Clear row that empties the date; a required date shows none, and Delete still clears. A character typed on the cell opens the editor with it in the date box, and Enter saves the date it reads. On a phone the day and the time are in one sheet, and ✓ saves both.
607
629
 
608
- **A text cell** (text, a link, an email, a phone, a domain) types in the cell through the text editor (`@viewkitjs/views/editors/text`): what was typed is trimmed, an unchanged value writes nothing, and each type brings its own phone keyboard. Enter writes and moves down, Tab writes and moves on, Escape cancels.
630
+ **A text cell** (text, a link, an email, a phone, a domain) types in the cell through the text editor (`@viewkitjs/views/editors/text`): what was typed is trimmed, an unchanged value writes nothing, and each type brings its own phone keyboard. Enter writes and moves down, Tab writes and moves on, Escape cancels (or writes, where the provider's `escape` keeps the column's type).
609
631
 
610
- **A long text** (a `text` field with `format: { long: true }`, or rich text) opens a panel on the cell: Enter is a newline, ⌘ or Ctrl Enter commits and moves down, Tab commits and moves on, Escape cancels, and a click away commits. Where it cannot be written, the same panel opens read-only (`gridColumnInspectable`).
632
+ **A long text** (a `text` field with `format: { long: true }`, or rich text) opens a panel on the cell: Enter is a newline, ⌘ or Ctrl Enter commits and moves down, Tab commits and moves on, Escape cancels (or commits, where the column's type keeps), and a click away commits. Where it cannot be written, the same panel opens read-only (`gridColumnInspectable`).
611
633
 
612
634
  **A cut-off text** (a plain text, or a title that is text) opens whole in that panel when its cell cuts it off: a second click, a double-click or Enter shows all of it over the cell, editable where the cell can be written and read-only where it can't. It stays a line: the box wraps, Enter writes and moves down, and a newline is written as a space. Typing a character still replaces the value in the cell, and a text that fits opens in the cell as above. Links, emails, phones and domains keep their one-line box.
613
635
 
@@ -615,11 +637,11 @@ assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
615
637
 
616
638
  **The write gate** is `gridNormalizeWrite`, which every write the grid starts passes once: a key, the row's menu, a fill, a paste, a boolean's button. It coerces the value by the column's type, then has the column's field accept it, so a type's write rules are stated once: a marker boolean refuses any write but clear, an email or a url must look like one, a multiselect commits its whole set, trimmed and without duplicates. An emptied value passes unchecked, since `clearable` decides whether a clear may run; a clear reaches you as `""`, except a relation's `null`, a multiselect's `[]` and a boolean's `false` (Writes, above). A refusal is said in a toast and nothing is sent. Undo and redo do not pass the gate: they put a recorded value back as it was.
617
639
 
618
- **A select, status, date, tags, relation, number, range, place or list-of-values editor** opens through the same panel: your `Popover` on a desktop and your `Sheet` below your `desktopQuery`. Each asks the same gate before it closes, and the list's settings too, so a column locked while its editor is open says the lock in the editor. A value the gate refuses keeps the editor open with its reason, and nothing is sent until the value changes or Escape throws the edit away. Leaving the cell while the reason stands writes nothing, and says the reason in a toast. These editors share the edit session's rules: Escape always discards, and a refused value stays open with its reason. In the place editor's country or region list, Escape first closes the list, back to its boxes. On a desktop a picker opens your `Popover` under its cell, and a number or a range is typed in the cell. Below your provider's `desktopQuery`, each opens in your `Sheet`, a number or a range included, titled with the column's header, with ✕ and ✓, while the cell behind it keeps showing its value. ✕, a swipe and Escape change nothing. ✓ saves, and so does a pick. A value is sent once its popover or sheet has played out; a number or a range typed in the cell is sent at once. A list of values whose every value was removed, or a place whose every part was emptied, on a column that isn't `clearable`, stays open saying the field can't be emptied (the column's `reasons.clearable` when it declares one); Escape still throws the edit away. The name editor still closes and says a refusal in a toast.
640
+ **A select, status, date, tags, relation, number, range, place or list-of-values editor** opens through the same panel: your `Popover` on a desktop and your `Sheet` below your `desktopQuery`. Each asks the same gate before it closes, and the list's settings too, so a column locked while its editor is open says the lock in the editor. A value the gate refuses keeps the editor open with its reason, and nothing is sent until the value changes or Escape throws the edit away (where the column's type keeps on Escape, the first Escape keeps and shows the refusal, and a second throws the edit away). Leaving the cell while the reason stands writes nothing, and says the reason in a toast. These editors share the edit session's rules: Escape discards (or keeps, where the provider's `escape` keeps the column's type), and a refused value stays open with its reason. In the place editor's country or region list, Escape first closes the list, back to its boxes. On a desktop a picker opens your `Popover` under its cell, and a number or a range is typed in the cell. Below your provider's `desktopQuery`, each opens in your `Sheet`, a number or a range included, titled with the column's header, with ✕ and ✓, while the cell behind it keeps showing its value. ✕, a swipe and Escape change nothing. ✓ saves, and so does a pick. A value is sent once its popover or sheet has played out; a number or a range typed in the cell is sent at once. A list of values whose every value was removed, or a place whose every part was emptied, on a column that isn't `clearable`, stays open saying the field can't be emptied (the column's `reasons.clearable` when it declares one); Escape still throws the edit away, unless the column's type keeps on Escape. The name editor still closes and says a refusal in a toast.
619
641
 
620
642
  **The row's country.** A column's `region` (a binding's, carried by `columnFrom`) reads the record's country off the row, and a phone typed, pasted or filled without its country code is read in it, at the gate and in the editors' own check. Absent, the conventions' region reads it.
621
643
 
622
- **A relation** commits what its row stores, not the `{ id, label }` its cell draws: the id of the record picked, a ref `{ kind, id }` on a field that names its kinds, or, on a relation holding several records, the whole set (ids, or links with their kind, stored role and one lead where the field leads by a flag), edited in `RelationSetEditor` with the list open and saved as one change on a click outside, Tab or the sheet's ✓. A letter typed on a relation or member cell opens its picker searching for it; on a phone the picker's sheet opens on the list with the keyboard down. A relation whose binding carries `create` offers that row under its candidates, and links what the app's form saves as a change of its own. The grid shows no value of its own while the write runs: the cell repaints when your rows come back. A date, a range, a name, a place and a list of values show no value of their own while the write runs either. A place takes no paste: a text names none of its parts.
644
+ **A relation** commits what its row stores, not the `{ id, label }` its cell draws: the id of the record picked, a ref `{ kind, id }` on a field that names its kinds, or, on a relation holding several records, the whole set (ids, or links with their kind, stored role and roles, and one lead where the field leads by a flag), edited in `RelationSetEditor` with the list open and saved as one change on a click outside, Tab or the sheet's ✓. A letter typed on a relation or member cell opens its picker searching for it; on a phone the picker's sheet opens on the list with the keyboard down. A relation whose binding carries `create` offers that row under its candidates, and links what the app's form saves as a change of its own. The grid shows no value of its own while the write runs: the cell repaints when your rows come back. A date, a range, a name, a place and a list of values show no value of their own while the write runs either. A place takes no paste: a text names none of its parts.
623
645
 
624
646
  **A multi-value cell is written whole.** Your `onCellCommit` receives the whole list, never one item added or removed.
625
647
 
@@ -627,7 +649,7 @@ assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
627
649
 
628
650
  Tab enters the grid at its focused cell, or at the first cell on screen, and the keyboard is a spreadsheet's: the arrows and ⇧-arrows, ⌘A, Home and End, ⌘Home and ⌘End, Tab with the row wrapping, typing to replace (on a select or a status, typing starts its search), Enter to edit (or to flip a boolean), ⌘C, ⌘X and Delete over a range, ⌘Z and ⇧⌘Z, and pasted tab-separated text. On a desktop, a click selects a cell; a second click on it, a double-click or Enter opens its editor, or the panel of a long text or a cut-off text. An email, a phone, a url or a domain is part of its cell: a click on it selects the cell like any other, and a ⌘-click (Ctrl-click on Windows) follows the link. ⌘X and Delete over a range empty what may be emptied, then say in one toast which fields they left because those can't be empty (`views.grid.clear-required`). A drag selects a range, and the dot at its corner fills it. Below your provider's `desktopQuery`, one tap on a cell opens its editor in your `Sheet`, and a cell that opens nothing is selected and says why. The answer is read at the tap, so a test that clicks the grid answers your desktop query in its `matchMedia` stub to keep a desktop's clicks.
629
651
 
630
- Every cell takes the browser's own focus, and the grid's keys listen on the grid itself; only ⌘Z listens on the window, so an undo works wherever focus is, and lands on the cell it changed: selected, and holding the focus unless something outside the grid has it, so the next key moves from there. Tab past the grid's last cell (Shift+Tab before its first) leaves it, and Escape with nothing open clears the cell and lets go of the grid: the next Tab or Shift+Tab leaves. The arrows also reach what surrounds the cells: ↑ from a group's first row lands on its column names, where Enter or Space opens a column's menu with focus on its first row; ↓ from its last row lands on its footer, where Enter or Space opens the figure picker; above the column names is the group's bar, where Enter, Space or ← collapse it and Enter, Space or → open it again, and → on an open bar reaches its ⋯ menu; ← from a row's first column reaches its checkbox, and Space ticks it (the select-all and a group's box the same way from the column names). On a cell, Shift+F10, the menu key, or ⌘⇧\ (Ctrl+Shift+\ off a Mac, as in Google Sheets) opens the row's menu, the one a right-click on that cell opens, under the cell; the grid sends that right-click to your `RowMenu`, and your `Menu` puts focus on its first row. Safari may keep ⌘⇧\ for its own tab overview: there, fn+Shift+F10 opens it. In a column's menu, the figure picker and a group's ⋯ menu, ↓ and ↑ move between the rows, round at either end, and Enter picks the focused one. Past eight sort choices a group's menu lists them under a search, whose own arrows walk its matches: ↓ past the last match goes on to the rows below it, and ↑ from the first of those comes back. That reads the match your `Command` has highlighted from its field's `aria-activedescendant`, as cmdk names it; a list that names none keeps its own arrows, and Tab leaves it. Escape, or a pick, closes a menu and puts focus back on its cell, after your `Popover` or `Menu` has played its exit and left the page. The keyboard, a range, a copy, a clear, a paste and a fill skip a collapsed group's rows, and collapsing a group keeps an edit open in it.
652
+ Every cell takes the browser's own focus, and the grid's keys listen on the grid itself; only ⌘Z listens on the window, so an undo works wherever focus is, and lands on the cell it changed: selected, and holding the focus unless something outside the grid has it, so the next key moves from there. Tab past the grid's last cell (Shift+Tab before its first) leaves it, and Escape with nothing open clears the cell and lets go of the grid: the next Tab or Shift+Tab leaves. The arrows also reach what surrounds the cells: ↑ from a group's first row lands on its column names, where Enter or Space opens a column's menu with focus on its first row; ↓ from its last row lands on its footer, where Enter or Space opens the figure picker; above the column names is the group's bar, where Enter, Space or ← collapse it and Enter, Space or → open it again, and → on an open bar reaches its ⋯ menu; ← from a row's first column reaches its checkbox, and Space ticks it (the select-all and a group's box the same way from the column names). On a cell, Shift+F10, the menu key, or ⌘⇧\ (Ctrl+Shift+\ off a Mac, as in Google Sheets) opens the row's menu, the one a right-click on that cell opens, under the cell; the grid sends that right-click to your `RowMenu`, and your `Menu` puts focus on its first row. Safari may keep ⌘⇧\ for its own tab overview: there, fn+Shift+F10 opens it. In a column's menu, the figure picker and a group's ⋯ menu, ↓ and ↑ move between the rows, round at either end, and Enter picks the focused one (with the provider's `menus` set to `menu`, the figure picker, a column's menu, a group's ⋯ and Add column are your `Menu`, and their keys are your `Menu`'s). On the `popover` route, past eight sort choices, or at any count once you pass `groupMenu`, a group's menu lists them under a search (on the `menu` route they open beside the menu with no search field), whose own arrows walk its matches: ↓ past the last match goes on to the rows below it, and ↑ from the first of those comes back. That reads the match your `Command` has highlighted from its field's `aria-activedescendant`, as cmdk names it; a list that names none keeps its own arrows, and Tab leaves it. Escape, or a pick, closes a menu and puts focus back on its cell, after your `Popover` or `Menu` has played its exit and left the page. The keyboard, a range, a copy, a clear, a paste and a fill skip a collapsed group's rows, and collapsing a group keeps an edit open in it.
631
653
 
632
654
  A screen reader reads the grid as a grid, or as a tree grid when it is grouped: every row is numbered among all of them (a group's bar, its column names and its footer are rows too, so the total runs a little above the record count), a cell is read with its column's name, a group's bar with its name, its count and whether it is open, and a grouped record with its place in its group. While more rows remain to load, a row reads its number with no total.
633
655
 
@@ -641,7 +663,7 @@ A screen reader reads the grid as a grid, or as a tree grid when it is grouped:
641
663
 
642
664
  ## Styling
643
665
 
644
- The grid styles through attributes, never class names: each part carries a `data-slot` (`data-slot="vk-grid"` on the frame, `vk-grid-row`, `vk-grid-cell`, `vk-grid-group-header` and the rest), and its states are bare `data-*` flags beside it (`data-focused`, `data-selected`, `data-editing`, `data-pending`, `data-invalid` …). The grid sets its geometry and density as `--vk-*` variables on its frame (`--vk-row-h`, `--vk-px`, `--vk-scale` …), which a skin reads and your app may override there. `--vk-gutter`, the side padding your page gives its content, lines the rows' content up with your page when you declare it. [The contract](../contract.md) lists every slot, state and token; [Install](../install.md) maps the colours onto your theme.
666
+ The grid styles through attributes, never class names: each part carries a `data-slot` (`data-slot="vk-grid"` on the frame, `vk-grid-row`, `vk-grid-cell`, `vk-grid-group-header` and the rest), and its states are bare `data-*` flags beside it (`data-focused`, `data-selected`, `data-editing`, `data-pending`, `data-invalid` …). The grid sets its geometry and density as `--vk-*` variables on its frame (`--vk-row-h`, `--vk-px`, `--vk-scale` …), which a skin reads and your app may override there. `--vk-gutter`, the side padding your page gives its content, lines the rows' content up with your page when you declare it. The frame is its own stacking context: what the grid pins or lifts inside it (a group's head, the column names, frozen cells) stays under your page's header, bars and sheets that carry a positive z-index, with no CSS. [The contract](../contract.md) lists every slot, state and token; [Install](../install.md) maps the colours onto your theme.
645
667
 
646
668
  ## Helpers a host shares with the grid
647
669
 
@@ -4,10 +4,20 @@ Every view reads what it takes from its app, other than its own props, from one
4
4
 
5
5
  ## Mount it once
6
6
 
7
- `ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`. Four more are optional: `atoms`, `messages`, `presentation` and `desktopQuery`.
7
+ `ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`. Nine more are optional: `atoms`, `messages`, `presentation`, `desktopQuery`, `sheetActions`, `escape`, `sayRefusals`, `menus` and `selectionBar`.
8
8
 
9
9
  `desktopQuery` says which screens are desktops: there an editor opens as a popover, and elsewhere as a sheet. It defaults to `DEFAULT_DESKTOP_QUERY`, `(min-width: 1024px)`; hand in the query your own shell switches on, so the editors and your layout change at the same width. A server render counts as a desktop.
10
10
 
11
+ `escape` says what Escape does in an editor, per field type: `{ date: "keep", location: "keep" }` keeps what was typed in a date's and a place's editor and closes it, as a press outside does, and a value that would be refused stays open with its reason, until a second Escape throws the edit away. A type you leave out throws the edit away, which is the default for every type. It holds on a desktop: on a phone, every way out of the sheet throws the edit away. Pass a module-level object.
12
+
13
+ `sayRefusals`, off by default, has the grid say why your app refused an edit it sent, through your toast's `error`: the error's own words, "Couldn't save Amount." when it has none, and a batch once, with its count. Turn it on and stop toasting your own refusals, or each says twice.
14
+
15
+ `sheetActions` says where an editor's ✕ and ✓ stand in that sheet. `bar`, the default, is the editor panel's own bar inside your `Sheet`. `head` hands them to your `Sheet` as `actions` (`close`, and `done` unless the body saves on its pick), for a sheet that draws them in its own head, and the panel draws no bar.
16
+
17
+ `selectionBar` says where the selection bar sits: its `bottom`, its `zIndex` and your `className` on the desktop and on the phone, and a `phoneQuery` when your shell switches to its phone layout at another width than `desktopQuery`. An app with a bottom nav lifts the phone's pill above it; pass a module-level object.
18
+
19
+ `menus` says how the grid opens its own menus. `popover`, the default, draws ViewKit's rows in your `Popover`. `menu` hands them to your `Menu` as rows: today the footer's figure picker, one ticked row per figure, a column's header menu, each format setting and each option's colour a group beside it, a group's ⋯, its sort choices a group beside it with no search field and its figure toggles ticks that keep the menu open, and the grid's own "+ Add column", each field with parts a group beside it, with no search field and on a phone too. The row menu and a command cell's menu always go through your `Menu`.
20
+
11
21
  Each piece lives in a module of its own, which the sections below write. Here they are declared, so the page compiles without them.
12
22
 
13
23
  ```tsx
@@ -49,7 +59,7 @@ assert.equal(conventions.locale, "en-GB"); // the app's own, untouched
49
59
 
50
60
  ## The components map
51
61
 
52
- The package draws nothing with a UI library of its own. `ViewsComponents`, from `@viewkitjs/views/react`, is the map you hand it: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. The [contract](../contract.md#the-components-map) says what each slot must accept; the [`@viewkitjs/views/react` reference](../reference/react.md) lists every prop.
62
+ The package draws nothing with a UI library of its own. `ViewsComponents`, from `@viewkitjs/views/react`, is the map you hand it: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`, and five you may leave out: `Input`, `Command` (the command list's parts), `Picker` (a whole pick list your app draws), `Calendar` (the date editor's month) and `DateBody` (a whole date body your app draws). The [contract](../contract.md#the-components-map) says what each slot must accept; the [`@viewkitjs/views/react` reference](../reference/react.md) lists every prop.
53
63
 
54
64
  The shapes are Base UI's, and the types promise three things:
55
65
 
@@ -210,7 +220,7 @@ assert.equal(closeReason("escape-key"), "escape-key");
210
220
  assert.equal(closeReason("trigger-hover"), "none"); // a reason the contract doesn't name
211
221
  ```
212
222
 
213
- The menu is built from Base UI's root, positioner and popup, the anchor handed to the positioner. It has no trigger, because the package opens it, and no flyouts: a row with `children` is a group, its rows drawn in place under its label. Your Base UI menu copy is declared here.
223
+ The menu is built from Base UI's root, positioner and popup, the anchor handed to the positioner. It has no trigger, because the package opens it. A row with `children` is a group, its rows drawn in place under its label. This example draws none of the three hints a row may carry (`beside`, `keepOpen`, `detail`): every group stays in place and every row closes the menu, which is the fallback every adapter may keep. Your Base UI menu copy is declared here.
214
224
 
215
225
  ```tsx
216
226
  type BaseAnchor = Element | RefObject<Element | null> | Measurable | null;
@@ -342,7 +352,7 @@ These are the package's glyphs. The ones a host names itself, a row's icon or a
342
352
 
343
353
  ## Messages
344
354
 
345
- The package words only its own strings. They are a closed list of messages, each a `key` under `views.grid.*`, `views.editors.*`, `views.menus.*` or `views.display.*` and, where the sentence carries something, its `values`: `{ key: "views.menus.group-by", values: { field: "Stage" } }`. The [contract](../contract.md#message-keys) lists every key with its English. A string `@viewkitjs/fields` already keys stays a fields message, worded through the conventions.
355
+ The package words only its own strings. They are a closed list of messages, each a `key` under `views.grid.*`, `views.editors.*`, `views.menus.*`, `views.display.*`, `views.selection.*` or `views.panels.*` and, where the sentence carries something, its `values`: `{ key: "views.menus.group-by", values: { field: "Stage" } }`. The [contract](../contract.md#message-keys) lists every key with its English. A string `@viewkitjs/fields` already keys stays a fields message, worded through the conventions.
346
356
 
347
357
  `messages` is a `ViewsMessageResolver`, a function from a `ViewsMessage` to its text. It defaults to `resolveViewsMessage`, the package's English. The provider doesn't fall back for you: a resolver that words only some keys calls `resolveViewsMessage` for the rest.
348
358
 
package/docs/index.md CHANGED
@@ -50,3 +50,5 @@ One page per door. Each lists every name the door exports.
50
50
  - [`@viewkitjs/views/cells`](reference/cells.md): a column's typed cell
51
51
  - [`@viewkitjs/views/selection`](reference/selection.md): a list's selection
52
52
  - [`@viewkitjs/views/grid`](reference/grid.md): the grid, its props and the helpers a host shares with it
53
+
54
+ `@viewkitjs/views/panels`, what a list's panels read and say, is not in this version: it is still being built, and a later release publishes it with the controls. Its rows, icons and words are already here.
package/docs/install.md CHANGED
@@ -6,7 +6,10 @@
6
6
  pnpm add @viewkitjs/views @viewkitjs/fields zod
7
7
  ```
8
8
 
9
- `react` and `react-dom` 19 are peers you already have. ESM only, Node 20 or later.
9
+ `react` and `react-dom` 19 are peers you already have. `@dnd-kit/core`, `@dnd-kit/sortable` and
10
+ `@dnd-kit/utilities` are optional peers for the panels' door, which a later release publishes: this
11
+ version needs none of them. ESM only,
12
+ Node 20 or later.
10
13
 
11
14
  2. **Let Tailwind see it.** The rendering carries Tailwind classes drawn from your own tokens. Add one
12
15
  line to the stylesheet that imports Tailwind:
@@ -17,6 +20,10 @@
17
20
 
18
21
  (Adjust the relative path to where your stylesheet sits.) A missing line shows unstyled values and editors.
19
22
 
23
+ That is all the rendering asks of your styles: it needs no base reset (Tailwind's preflight or any
24
+ other). Every button, input, textarea and link it draws itself resets itself, at zero specificity, so
25
+ it looks the same with or without one, and your own classes and base styles elsewhere are untouched.
26
+
20
27
  3. **Map the colours.** The rendering paints through its own names, which your stylesheet declares
21
28
  once. On stock shadcn tokens:
22
29
 
@@ -3,4 +3,6 @@
3
3
  Import from `@viewkitjs/views/editors/date` in a client component: the door opens with the client directive. It holds the editor of a `date` and a `datetime` field: a value bar with a typeable date and a time chip, three quick days, your app's calendar, and a Clear row where the date may be empty. It owns the value bar, the calendar, the lenient reading of a typed date and the draft; its host owns the popover, the anchor and when a close means commit. It commits `YYYY-MM-DD` when no time is set, `YYYY-MM-DDTHH:MM` in local time, or `""` when the Clear row empties the date. Guide: [editors](../guides/editors.md).
4
4
 
5
5
  - `DateEditor` — the date panel; its ref is a `DateEditorHandle`. The date box reads a typed date day first and writes it back as `dd/mm/yyyy`; the time chip offers quick picks every 15 minutes; Today, Tomorrow and Next Monday (a week on when today is a Monday) above the calendar each set their day as a calendar click does; the calendar is the pointer path to the same day, with a year picker from 1900 to ten years ahead (a typed date outside it still lands). It takes `initial` (the stored value, a full ISO string or `YYYY-MM-DD`, which picks the day and the month it opens on; a bare `YYYY-MM-DD` is that day on the device's calendar in every time zone, never midnight UTC), `onRequestClose` (Enter means done, Escape means leave, and `pick` means a choice that ends the edit; Tab from the panel's last control asks to close with `tab`, and Shift-Tab from its first with `shift-tab`, while Tab between its own controls moves as usual, so a popover that keeps the focus in a loop can still be left; the panel never closes itself) and `message` (the fields message resolver, defaulting to the provider's conventions). With `timeOptional` the time chip starts empty and stays out of the commit until set; without it the chip carries the stored time, or 00:00, and every commit includes one. With `dayOnly`, for a calendar-day field, there is no time chip, the commit is the day, and a click on a day or a quick day asks to close with `pick`; without it, a day click keeps the panel open for the time and a quick day keeps the time, and on a desktop either puts the focus back in the date box, so Enter saves the day and time the panel shows. With `clearable` the panel ends with a Clear row: a click asks to close with `pick` and commits `""`, or nothing when there was no date. With `seed` the date box opens holding that text (a character typed on the cell), focused with the caret after it, and read as a typed date. With `focusDate` the date box takes the focus as the panel opens, without scrolling, so Tab walks the panel and leaves from its last control; leave it off on a phone, whose sheet opens with the keyboard down. The time chip's quick-pick closes when Tab leaves the time box, so Tab moves on to the quick days rather than through every quarter hour. With no stored value the box starts on today, and a close with no interaction writes nothing.
6
+
7
+ Handed `DateBody` in the components map, the editor opens it in place of its own value bar, quick days, time, calendar and Clear row. It hands the body the value on the local calendar (a day, or a day and a time, a stored day read as that day on any clock), `time` (false for a date-only field), `empty` (where the date may be emptied), the quick picks, today, the text typed on what opened it, `autoFocus` and `form`. A change from the body is the draft a close resolves, exactly as a calendar pick or a typed day is: `resolveClose` answers it unchanged, a datetime handed a bare day moves the day and keeps the time in force (the one it opened with, or the last one handed), while a field whose time is optional takes a bare day as holding no time, the empty pick is the Clear row's, and a value that isn't a date changes nothing. `onDone` asks the host to close with `pick`. Escape is taken before the body hears it and asks the host to close with `escape`, so your provider's rule for the field's type decides what it keeps; Tab walks the body's controls and asks to close with `tab` or `shift-tab` from either end, so a popover your body draws in a portal, outside its element, reads as a Tab out. `label` names the field for the body (default: the date box's words); the grid and the field row hand their field's name.
6
8
  - `DateEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape discards: `"escape"` answers `cancel`. After a click on the Clear row, any other close commits `""`, or is a `noop` when there was no date. Otherwise every other close commits the draft when it differs from the stored value, and is a `noop` otherwise, with text still typed in the date box read first.
@@ -3,10 +3,10 @@
3
3
  Import from `@viewkitjs/views/editors/panel` in a client component: the door opens with the client directive. It holds where an editor opens, for every surface: your popover on a desktop and your sheet on a phone, from the components map's `Popover` and `Sheet`, or nothing at all for a type-in editor that stays where its value stands. The editor inside never reads which. It takes the session your host opened (`@viewkitjs/views/editors/session`), so the session's rules hold on every surface. Guide: [editors](../guides/editors.md#the-panel-a-popover-on-the-desktop-a-sheet-on-the-phone).
4
4
 
5
5
  - `EditorPanel` — opens the editor it holds. The surface is chosen once, when the session opens, by the provider's `desktopQuery`: a window crossing the desktop width mid-edit keeps the panel it opened in. A panel already open in server-rendered HTML reads the server's answer, a desktop, so mount it on the person's tap, as a host does. What each dismissal means is the panel's, so every host agrees:
6
- - On a desktop, your `Popover`, opened on `anchor`: its Escape discards, unless it comes from inside an element carrying `EDITOR_INNER_ESCAPE`, which the panel answers `false` to so the popover stays open and the editor closes its own list; and a press outside closes with `"outside"`, which the editor answers by its own rule, while the session is open: a press while the popover plays its exit after a close reaches nothing. Its panel carries `data-slot="vk-editor-panel"`.
7
- - On a phone, your `Sheet`, titled with `title` (the field's name), and a bar with ✕ (`views.editors.discard`) and ✓ (`views.editors.save`). ✕, a swipe, the backdrop and Escape discard; ✓ closes with `"enter"`, as done; a pick in a select saves on its own. A picker always opens the sheet on a phone. A press inside the sheet stays in it: a click, a double-click or a context menu never bubbles through React's tree to what the panel is drawn in, such as a grid row.
6
+ - On a desktop, your `Popover`, opened on `anchor`: its Escape is the session's (a discard, or a keep where the session keeps), asked once though the popover reports the close it causes right after `onEscape`, unless it comes from inside an element carrying `EDITOR_INNER_ESCAPE`, which the panel answers `false` to so the popover stays open and the editor closes its own list; and a press outside closes with `"outside"`, which the editor answers by its own rule, while the session is open: a press while the popover plays its exit after a close reaches nothing. Its panel carries `data-slot="vk-editor-panel"`.
7
+ - On a phone, your `Sheet`, titled with `title` (the field's name), handed `label` too whenever `title` is words, and a bar with ✕ (`views.editors.discard`) and ✓ (`views.editors.save`). ✕, a swipe, the backdrop and Escape discard; ✓ closes with `"enter"`, as done; a pick in a select saves on its own. With the provider's `sheetActions: "head"` the panel draws no bar: your `Sheet` is handed the ✕ and ✓ as `actions` (`close`, and `done` unless the host passed `savesOnPick`) for its own head. A picker always opens the sheet on a phone. A press inside the sheet stays in it: a click, a double-click or a context menu never bubbles through React's tree to what the panel is drawn in, such as a grid row.
8
8
  - A type-in editor (`inPlace`) is drawn where it stands on a desktop, and on a phone too unless its host passes `sheetOnPhone`, which opens it in the sheet.
9
- - A refusal your `onAttempt` gave (`refusal`) is drawn under the editor, with `role="alert"` and `data-slot="vk-editor-refusal"`, in the popover and the sheet. In place, your own box draws it: pass the children as a function of the `EditorSurface` to know where the editor is.
10
- - `EditorPanelProps` — what the panel takes: `session` (an `EditSession`, from either mode), `title`, `anchor`, `inPlace` and `sheetOnPhone` (both default false), `snap` (the sheet's hint, default `auto`), the popover's `side`, `align`, `sideOffset`, `alignOffset`, `initialFocus`, `chrome`, `className`, `style` and `panelData`, handed on as they are, `onPanelClick` (a click inside the popover or the sheet; the sheet then keeps it, the popover leaves that to you), and `children`: the editor, or a function of the `EditorSurface` the panel chose.
9
+ - A refusal your `onAttempt` gave (`refusal`) is drawn under the editor, with `role="alert"` and `data-slot="vk-editor-refusal"`, in the popover and the sheet. In place, your own box draws it: pass the children as a function of the `EditorSurface` to know where the editor is. An editor that draws the refusal itself (a range with bands, handed it as `refusal`) takes `editorDrawsRefusal`, and the panel draws none.
10
+ - `EditorPanelProps` — what the panel takes: `session` (an `EditSession`, from either mode), `title`, `anchor`, `inPlace` and `sheetOnPhone` (both default false), `snap` (the sheet's hint, default `auto`), the popover's `side`, `align`, `sideOffset`, `alignOffset`, `initialFocus`, `chrome`, `className`, `style` and `panelData`, handed on as they are, `onPanelClick` (a click inside the popover or the sheet; the sheet then keeps it, the popover leaves that to you), `editorDrawsRefusal` (default false: the editor draws the session's refusal, so the panel doesn't), `savesOnPick` (default false: the body saves on its pick, a pick of one, so a `Sheet` drawing the panel's buttons in its head is handed no `done`; the panel's own bar keeps its ✓), and `children`: the editor, or a function of the `EditorSurface` the panel chose.
11
11
  - `EditorSurface` — where the panel opened its editor: `popover`, `sheet` or `in-place`. An `in-place` editor is drawn in its value's own box, which the panel scrolls into view as the editor opens, at the nearest edge (`scrollIntoView` with `nearest`), when `anchor` is that box: a box partly past the edge of what scrolls it opens whole.
12
12
  - `EDITOR_INNER_ESCAPE` — the attribute name (`data-vk-inner-escape`) an editor puts on an inner level of its own, such as a list opened from its boxes, while Escape there closes that level rather than the edit. A popover that hears Escape on the document before the editor does then leaves it to the editor. The place editor carries it on its country and region lists.
@@ -2,5 +2,5 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/range` in a client component: the door opens with the client directive. It holds the editor of a `range` field: two number boxes, low and high, inline like the number editor. Tab moves from low to high inside the editor, and a blur that lands on the other box is not a close. An empty box is an open end. It owns the two boxes and what a close means; its host owns where it mounts, the write, and keeping the pair in its own columns. It commits a `RangeValue` of `@viewkitjs/fields`, `{ low, high }`, each a number or null. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `RangeEditor` — the two boxes, the low one focused without scrolling; its ref is a `RangeEditorHandle`. It takes `initial` (the stored range, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the low box), `decimals` (default 0), `allowEmpty`, `suffix` (a unit drawn after the high box, such as `%` or a currency code), `align` (`end` by default, or `start`), `conventions` (how a number is written; default: the provider's), `bands` (the field's `presets`, listed under the boxes; a click writes the band's ends into the boxes and closes as `pick`, so it is read and judged as typed ends are), `bandsAt` (`popover` by default, a small menu under the boxes; `below`, in the editor's own column, for an editor already in a sheet or a panel) and `boxClassName` (classes for the box holding the two inputs, such as a sheet's field).
5
+ - `RangeEditor` — the two boxes, the low one focused without scrolling; its ref is a `RangeEditorHandle`. It takes `initial` (the stored range, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the low box), `decimals` (default 0), `allowEmpty`, `suffix` (a unit drawn after the high box, such as `%` or a currency code), `align` (`end` by default, or `start`), `conventions` (how a number is written; default: the provider's), `bands` (the field's `presets`, listed under the boxes; a click writes the band's ends into the boxes and closes as `pick`, so it is read and judged as typed ends are), `bandsAt` (`popover` by default, a small menu under the boxes; `below`, in the editor's own column, for an editor already in a sheet or a panel), `refusal` (your reason for refusing the range: with bands listed the editor draws it between the boxes and the bands, atop the menu or above the list, so you draw none and tell your `EditorPanel` with `editorDrawsRefusal`; without bands it draws nothing and you draw it as for any type-in) and `boxClassName` (classes for the box holding the two inputs, such as a sheet's field).
6
6
  - `RangeEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels, and so does a box holding text that is not a number. Both ends unchanged as the boxes showed them is a `noop`, so a stored 2.555 that opened as 2.56 writes nothing. Two empty boxes cancel, or commit with `allowEmpty`. A low end above the high end commits as typed, for the host's acceptance to refuse in its own words.
@@ -2,11 +2,11 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/relation` in a client component: the door opens with the client directive. It holds the picker for a link, the editor of a `relation` and a `user` field: search the candidates, pick one, and it replaces the link; and the editor of a relation holding several records, which adds and removes links with the list open. The candidates are the host's, through a `RelationSource`: a static list the panel filters on its labels, or a remote search your function answers a page at a time. The panel owns the search box, the rows, the paging (it waits before a typed query searches, drops an answer a newer query superseded, asks for the next page as the end of the list scrolls into view, and says when it is searching, failed or found nothing) and, in `RelationEditor`, what a close means: a pick is the commit, every other close discards (`RelationSetEditor` saves on every close but Escape). It never does the asking itself, so access stays in your function's closure. Its host owns the popover, the anchor and the write. It commits the picked id, or null for None. The door also re-exports `RelationCandidate`, `RelationSearch` and `RelationSource`, which are documented with the root door. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `RelationEditor` — the relation-picking panel, built from your app's command list; its ref is a `RelationEditorHandle`. It takes `candidates` (the `RelationSource`), `initial` (the linked id, or null), `clearable` (a None row for a link the surface says is optional, hidden while a query is typed), `onRequestClose` (called with `pick` when someone chooses), `kindGlyph` (the glyph worn by every candidate with no icon of its own; given, every row keeps a glyph lane so the labels line up), `noneLabel` (the surface's words for the None row), `message` (the fields message resolver, defaulting to the provider's conventions), `creates` (`RelationCreate` rows pinned under the list), `seed` (the text the search opens with, such as a letter typed on the cell that opened it) and `focusSearch` (put the caret in the search as the panel opens, without scrolling; off by default, and left off on a phone so its sheet opens with the keyboard down). The list opens with the linked record highlighted, so an Enter pressed at once changes nothing; when a remote page doesn't hold it, nothing is highlighted until a key or typed text moves the highlight; with nothing linked, None or the first candidate; opened with a `seed`, the first match. It asks your command list for that through its root's `defaultValue`; a list that ignores it opens on its first row. A candidate's `sublabel` draws as a muted second line and its `badge` as a small chip at the row's end.
5
+ - `RelationEditor` — the relation-picking panel, built from your app's command list, or opened in your app's `Picker` when the provider has one (the list filtered or fetched by the editor, the create rows as its `actions`); its ref is a `RelationEditorHandle`. It takes `candidates` (the `RelationSource`), `initial` (the linked id, or null), `clearable` (a None row for a link the surface says is optional, hidden while a query is typed), `onRequestClose` (called with `pick` when someone chooses), `kindGlyph` (the glyph worn by every candidate with no icon of its own; given, every row keeps a glyph lane so the labels line up), `noneLabel` (the surface's words for the None row), `message` (the fields message resolver, defaulting to the provider's conventions), `creates` (`RelationCreate` rows pinned under the list), `seed` (the text the search opens with, such as a letter typed on the cell that opened it), `label` (the field's name, for your `Picker`; default the search's words) and `focusSearch` (put the caret in the search as the panel opens, without scrolling; off by default, and left off on a phone so its sheet opens with the keyboard down). The list opens with the linked record highlighted, so an Enter pressed at once changes nothing; when a remote page doesn't hold it, nothing is highlighted until a key or typed text moves the highlight; with nothing linked, None or the first candidate; opened with a `seed`, the first match. It asks your command list for that through its root's `defaultValue`; a list that ignores it opens on its first row. A candidate's `sublabel` draws as a muted second line and its `badge` as a small chip at the row's end.
6
6
  - `RelationEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `commit` with the picked id, or null for None, only for `pick` and only when it differs from `initial`; `noop` for a `pick` with nothing picked or the link already held; `cancel` for every other reason.
7
7
  - `RelationCreate` — a row pinned under the list for a record that isn't in it yet: `label(query)` gives its words from the trimmed query, and `onCreate(query)` runs after the host has been asked to close, so your own create form opens with what was typed. In `RelationEditor` a click on it is a `pick` that resolves `noop`: nothing is written. In `RelationSetEditor` it saves the set as it stands first. The grid writes a record your form links on top of that save however soon you call the link, even before the editor has finished closing.
8
8
  - `RELATION_SEARCH_DEBOUNCE_MS` — 200: how many milliseconds a typed query waits before a remote search runs. The empty query runs at once, so the panel opens on a first page.
9
9
  - `RELATION_PAGE_SIZE` — 20: the rows per page when a remote source names no `pageSize`. A page shorter than the size ends the list.
10
- - `RelationSetEditor` — the editor of a relation holding several records, on the same panel; its ref is a `RelationSetEditorHandle`. It takes `candidates`, `initial` (the linked records as `RelationSetItem`s, in their stored order), `lead` (the field leads by a flag), `onRequestClose` (called with `tab` or `shift-tab` from the search, and with `pick` from a create row), `kindGlyph`, `message`, `creates`, `seed` and `focusSearch`, as `RelationEditor` does. The linked records are drawn first and chosen, whatever page a remote search holds, and filtered by the query on their labels; a click on a candidate adds it to the end of the set, a click on a linked record removes it, and the list stays open. With `lead`, the first link leads: it carries a Lead mark, every other linked record a Make lead action that moves it first, and removing the lead passes it to the next; a set stored with none marked reads its first link as the lead. Space on a highlighted linked record, with the search empty, makes it the lead too; with a query typed, Space types. On open the highlight sits on the first linked record, so an Enter does nothing until the highlight leaves it, by a key, by typing or by the pointer. The editor reads the highlighted record off the search's `aria-activedescendant` and the row's `data-value`, as cmdk sets them; a command list that sets neither keeps the Enter guard until a key or typing moves the highlight, and has no Space for the lead. With `focusSearch`, the caret goes back to the search after every click, so Tab still saves.
11
- - `RelationSetEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `cancel` for `escape`; for every other reason, `noop` when the set holds the same records in the same order as it opened, else `commit` with the whole set as `RelationDraftLink[]` (from `@viewkitjs/fields`), in order with the lead first: each link's `id`, its `kind` where known, the `role` it was stored with (a new link has none), and with `lead`, `primary` on every link, true on the first.
10
+ - `RelationSetEditor` — the editor of a relation holding several records, on the same panel; its ref is a `RelationSetEditorHandle`. It takes `candidates`, `initial` (the linked records as `RelationSetItem`s, in their stored order), `lead` (the field leads by a flag), `onRequestClose` (called with `tab` or `shift-tab` from the search, and with `pick` from a create row), `kindGlyph`, `message`, `creates`, `seed`, `label` and `focusSearch`, as `RelationEditor` does; handed your `Picker`, it opens it with the linked records held and, where the field leads, `lead`, and your body's `onDone` closes it with `pick`, which saves the set. Without a `Picker`, the None row of `RelationEditor` hides while a query is typed; your body decides that for itself. The linked records are drawn first and chosen, whatever page a remote search holds, and filtered by the query on their labels; a click on a candidate adds it to the end of the set, a click on a linked record removes it, and the list stays open. With `lead`, the first link leads: it carries a Lead mark, every other linked record a Make lead action that moves it first, and removing the lead passes it to the next; a set stored with none marked reads its first link as the lead. Space on a highlighted linked record, with the search empty, makes it the lead too; with a query typed, Space types. On open the highlight sits on the first linked record, so an Enter does nothing until the highlight leaves it, by a key, by typing or by the pointer. The editor reads the highlighted record off the search's `aria-activedescendant` and the row's `data-value`, as cmdk sets them; a command list that sets neither keeps the Enter guard until a key or typing moves the highlight, and has no Space for the lead. With `focusSearch`, the caret goes back to the search after every click, so Tab still saves.
11
+ - `RelationSetEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `cancel` for `escape`; for every other reason, `noop` when the set holds the same records in the same order as it opened, else `commit` with the whole set as `RelationDraftLink[]` (from `@viewkitjs/fields`), in order with the lead first: each link's `id`, its `kind` where known, the `role` and `roles` it was stored with (a new link has neither), and with `lead`, `primary` on every link, true on the first.
12
12
  - `RelationSetItem` — one linked record as the set editor holds it: a `RelationDraftLink` with the `label` its row shows and an optional `icon`.
@@ -2,7 +2,7 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/select` in a client component: the door opens with the client directive. It holds the picker for one value out of a set, the editor of a `select` and a `status` field. The panel draws each option as your app's row with its badge or tag and owns what a close means: a pick is the commit, and every other close discards. Its host owns the popover, the anchor, the exit gap and the write. It commits the picked option's `value`, a string, and `""` for None, which a host maps to null. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `SelectEditor` — the option-picking panel; its ref is a `SelectEditorHandle`. It takes `options` (`PickerOption`s in display order, colours already resolved), `initial` (the value the surface holds, checked in the list), `clearable` (a None row first, for a value the surface says is optional), `onRequestClose` (called with `pick` when someone chooses) and `message` (the fields message resolver, defaulting to the provider's conventions). A list of more than `SELECT_SEARCH_PAST` (8) options opens with a search over the option labels, the None row hidden while a query is typed; Enter picks the first match. When it may be emptied, it opens with the value it holds highlighted, or None when it holds nothing, so an Enter pressed at once changes nothing, and the arrows walk every row, None included; opened with a `seed`, on the first match. It asks your command list for that through its root's `defaultValue`; a list that ignores it opens on None. One that can't be emptied opens on its first option. With `creatable`, for an open select, the search is always there and, after the matches, a row uses the typed text when no option's value is it, ignoring case; picking that row commits the trimmed text. `seed` is the text the search opens with (a letter typed on the cell that opened it), ignored by a list with no search; `focusSearch` puts the caret in the search as it opens, without scrolling. `focusList`, for a host opened from the keyboard, gives a plain list the keys: the row it holds takes the focus as it opens (None when it may be emptied and holds nothing, else its first row), ↓ and ↑ move it between the rows, round at either end, and Enter picks the focused row; a list with a search ignores it.
5
+ - `SelectEditor` — the option-picking panel; its ref is a `SelectEditorHandle`. It takes `options` (`PickerOption`s in display order, colours already resolved), `initial` (the value the surface holds, checked in the list), `clearable` (a None row first, for a value the surface says is optional), `onRequestClose` (called with `pick` when someone chooses) and `message` (the fields message resolver, defaulting to the provider's conventions). A list of more than `SELECT_SEARCH_PAST` (8) options opens with a search over the option labels, the None row hidden while a query is typed; Enter picks the first match. When it may be emptied, it opens with the value it holds highlighted, or None when it holds nothing, so an Enter pressed at once changes nothing, and the arrows walk every row, None included; opened with a `seed`, on the first match. It asks your command list for that through its root's `defaultValue`; a list that ignores it opens on None. One that can't be emptied opens on its first option. With `creatable`, for an open select, the search is always there and, after the matches, a row uses the typed text when no option's value is it, ignoring case; picking that row commits the trimmed text. `seed` is the text the search opens with (a letter typed on the cell that opened it), ignored by a list with no search; `focusSearch` puts the caret in the search as it opens, without scrolling. `focusList`, for a host opened from the keyboard, gives a plain list the keys: the row it holds takes the focus as it opens (None when it may be emptied and holds nothing, else its first row), ↓ and ↑ move it between the rows, round at either end, and Enter picks the focused row; a list with a search ignores it. Tab and Shift-Tab, in the search or on a focused row, ask the host to close with `tab` or `shift-tab`, which picks nothing, so a popover that loops Tab inside it can't hold the focus there.
6
6
  - `SelectEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `commit` with the picked value only for `pick`, and only when the pick differs from `initial` (`""` and null are the same absence); `noop` for a `pick` with nothing picked or the value already held; `cancel` for every other reason, so Escape and an outside click discard.
7
7
  - `SELECT_SEARCH_PAST` — the number of options a closed list holds before it opens with a search: 8.
8
8
  - `PickerOption` — one option as the panel draws it: its `value` and `label`, and a `slot` (a status's lifecycle state, drawn as your status badge) or a `color` (a category colour, drawn as your tag), or neither for a plain label. `icon` names your app's glyph, drawn before the label. Colours are resolved by the caller, never by the panel.
@@ -2,10 +2,11 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/session` in a client component: the door opens with the client directive. It holds the plumbing every host that opens an editor in a panel over a value repeats: the guard that lets a session answer once, and the gap that lets the popover's exit play before the value renders again behind it. A session that answers twice writes twice, and one that answers during its own exit unmounts the panel mid-flight. The host keeps its popover, its anchor, its focus and the shape of what it hands back. It is a door of its own so a host that needs the session does not load the editors. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `useAnchoredEditSession` — runs one edit session and returns an `EditSession`, `{ open, close, refusal }`. It opens already open; bind `open` to your popover and route every close to `close(reason)` (the popover's dismiss, the editor's `onRequestClose`, your own keys): only the first one counts. Escape always discards: on `close("escape")` the session answers a cancel without asking the editor. On any other reason it asks the editor's `resolveClose(reason)` through `editorRef` (a `noop` when there is no editor) and passes a commit's value through `mapPayload`, which never sees a cancel or a noop. Then one of two modes:
5
+ - `useAnchoredEditSession` — runs one edit session and returns an `EditSession`, `{ open, close, refusal, keeps }`. It opens already open; bind `open` to your popover and route every close to `close(reason)` (the popover's dismiss, the editor's `onRequestClose`, your own keys): only the first one counts. Escape discards: on `close("escape")` the session answers a cancel without asking the editor. With `escape: "keep"` (an `EditEscape`; default `"cancel"`), read once when the session opens and only on a desktop by the provider's `desktopQuery`, Escape keeps instead: the session asks the editor's `resolveClose("outside")`, as for a press outside, so what was typed is kept by the editor's own rule and a refusal stays open with its reason; a second Escape while that refusal stands throws the edit away. `keeps` says which. On any other reason it asks the editor's `resolveClose(reason)` through `editorRef` (a `noop` when there is no editor) and passes a commit's value through `mapPayload`, which never sees a cancel or a noop. Then one of two modes:
6
6
  - Admitted, the one to prefer: `onAttempt(answer)` is asked at once whether this answer may close and returns an `EditSessionAttempt`. A refusal keeps the session open for another try, and its `reason` comes back as `refusal` until the next attempt; an acceptance closes it and calls `onClose` after the exit gap, a timer cleared if the host unmounts. While `onAttempt` runs the session counts as answered, so a close that arrives during it (a write that moves the focus, and a box that closes on blur) is ignored; a refusal, or an `onAttempt` that throws, opens it again for the next try.
7
7
  - Deferred: the session closes at once and hands the answer to `onDone` after the exit gap, for a host whose answer still carries the write.
8
8
  - Gap: `exitMs` sets it, defaulting to `EDITOR_EXIT_MS`.
9
- - `EditSession` — what the session hands its host, and what `EditorPanel` (`@viewkitjs/views/editors/panel`) takes: `open`, `close(reason)`, and `refusal`, the reason the host gave for the last refused attempt until the next one, `null` otherwise and always in the deferred mode.
9
+ - `EditSession` — what the session hands its host, and what `EditorPanel` (`@viewkitjs/views/editors/panel`) takes: `open`, `close(reason)`, and `refusal`, the reason the host gave for the last refused attempt until the next one, `null` otherwise and always in the deferred mode; and `keeps`, optional, true when this session's Escape keeps (an editor that checks its draft before a key closes it, the value list, checks it before Escape too).
10
+ - `useEscapeRule(type)` — the provider's `escape` for a field type (`ViewsProvider`, `@viewkitjs/views/react`): `"keep"` where it names the type keep, else `"cancel"`, and `"cancel"` with no provider. A host of your own reads it and hands it to its session as `escape`.
10
11
  - `EditSessionAttempt` — the host's answer to an attempt: `{ accepted: boolean; reason?: string }`. A refusal may say why; the reason is what `refusal` shows.
11
12
  - `EDITOR_EXIT_MS` — 160: the milliseconds an anchored host waits between closing its popover and reporting its answer, so the exit animation plays out first.
@@ -2,5 +2,5 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/value-list` in a client component: the door opens with the client directive. It holds the editor of a field holding several values of one kind (a `multiple` email, phone, url or domain field), each with its label and one of them the main one. It is a draft, like the chips editor: the whole list commits once when the host closes it. It owns the rows, the reading of each value and what a close means; its host owns the popover, the anchor and the write. It commits a list of `ValueItem`s of `@viewkitjs/fields`, `{ value, label, main }`, the main one first, or null. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false).
5
+ - `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal; so does Escape with `escapeKeeps` (a host whose session keeps, `EditSession.keeps`), which also marks the list's box `EDITOR_INNER_ESCAPE`, so a popover leaves that Escape to the rows. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false).
6
6
  - `ValueListEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels; any other close keeps what was built. Blank rows are dropped. A row left untouched keeps its stored value exactly as stored, and a row typed in commits its trimmed text for the field's commit to read. With no main mark the first row is the main one. The same values, labels and main as opened is a `noop`; an empty list commits null with `allowEmpty` and cancels without it.
@@ -2,11 +2,11 @@
2
2
 
3
3
  Import from `@viewkitjs/views/field-row` in a client component, under your `ViewsProvider`: the door opens with the client directive. It holds a record's field row: one field drawn as its label, its value and, on a click, its type's editor in place, and the write path that admits each edit at once, queues one record's writes, settles each on the save's receipt and rolls a failure back. The row knows no entity, only a binding, a value and a commit, so your app builds its record's panel (its sections, its related records) around the rows. It draws with your provider's `Popover`, `Sheet`, `Collapse`, `AppIcon`, icons, `CommandMenu` atom and toast port. The shapes its writes go through (the write target, the receipt, the admission, a value's note, the reconciliation error) are the root door's, described under [A write's target](views.md#a-writes-target), and this door re-exports them. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width. Escape always throws the edit away, and a sheet's swipe or ✕ changes nothing. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once a write still saving has saved and unless the focus moved meanwhile, so the next Tab moves on from that row; an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry.
5
+ - `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width. Escape throws the edit away, unless the provider's `escape` keeps the field's type, on a desktop, where it keeps what was typed and a refusal stays open until a second Escape throws the edit away; a sheet's swipe or ✕ changes nothing. On a desktop, a short select opened by Enter or Space on the row puts the focus on the value it holds, so the arrows walk it and Enter picks; opened by a pointer, it moves no focus. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once its exit has played out and a write still saving has saved, so the next Tab moves on from that row; a press or a focus outside an editor's panel since the close lets that go, so a row opened meanwhile keeps its editor, and an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry.
6
6
  - `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
7
7
  - `RowEditor` — the editor a row mounts for its field's type, picked from `ROW_HOSTS`.
8
8
  - `ROW_HOSTS` — the host each field type mounts in a row, or `null` for a type the row never opens (a boolean, a derived or system field).
9
- - `RowEditorProps` — what a host receives: `binding`, `row`, `initial` (the stored value), `anchor` (the value as drawn, kept under an anchored editor), `shown` (the display value, whose labels a set of records opens on), `conversion` (the marked figure, when the row showed the amount converted, which a money host names under it), `onAttempt`, `onClose` (called with a `RowClosed` once the editor's exit has played out), `message` and `kindIcon`.
9
+ - `RowEditorProps` — what a host receives: `binding`, `row`, `initial` (the stored value), `anchor` (the value as drawn, kept under an anchored editor), `shown` (the display value, whose labels a set of records opens on), `conversion` (the marked figure, when the row showed the amount converted, which a money host names under it), `onAttempt`, `onClose` (called with a `RowClosed` once the editor's exit has played out), `message`, `kindIcon` and `openedByKey` (true when a key, Enter or Space, pressed the row's button rather than a pointer).
10
10
  - `RowClosed` — what a host's close tells its row: `focusBack`, true when the editor closed from the keys or a pick off a sheet, and the row takes the focus back on its button.
11
11
  - `RowEditorAttempt` — the row's answer to a close: `{ accepted: true }`, or `{ accepted: false, reason }`, which keeps the editor open.
12
12
  - `RowHostProps` — a host's props: `RowEditorProps` plus the field narrowed to the host's types.