@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
package/docs/contract.md CHANGED
@@ -23,7 +23,8 @@ use; the prefix keeps that selector from reaching an element of the app's own.
23
23
  | slot | the element |
24
24
  | ------------------------------------ | --------------------------------------------------------- |
25
25
  | `data-slot="vk-grid"` | the grid's frame: fills the box the app gives it |
26
- | `data-slot="vk-grid-scroll"` | the grid's one scroll area, both ways |
26
+ | `data-slot="vk-grid-pan"` | the grid's sideways box, drawn only while the lab's lock is on and the screen is a touch screen: it scrolls the table sideways |
27
+ | `data-slot="vk-grid-scroll"` | the rows' box: the grid's one scroll area, both ways; up and down only inside `vk-grid-pan` while that is drawn |
27
28
  | `data-slot="vk-grid-head"` | an ungrouped grid's pinned head: its header row |
28
29
  | `data-slot="vk-grid-header"` | the header row |
29
30
  | `data-slot="vk-grid-header-cell"` | one column's header |
@@ -42,14 +43,22 @@ use; the prefix keeps that selector from reaching an element of the app's own.
42
43
  | `data-slot="vk-grid-editor"` | the open editor over a cell |
43
44
  | `data-slot="vk-grid-outline"` | the outline around the focused cell or the selected range |
44
45
  | `data-slot="vk-grid-resize-handle"` | a column's resize handle |
45
- | `data-slot="vk-grid-column-menu"` | the header menu |
46
+ | `data-slot="vk-grid-column-menu"` | the header menu, on the `popover` route |
46
47
  | `data-slot="vk-grid-flyout"` | a flyout a menu row opens beside its menu |
47
- | `data-slot="vk-grid-group-menu"` | a group band's menu |
48
- | `data-slot="vk-grid-aggregate-menu"` | the footer's figure picker |
48
+ | `data-slot="vk-grid-group-menu"` | a group band's menu, on the `popover` route |
49
+ | `data-slot="vk-grid-aggregate-menu"` | the footer's figure picker, on the `popover` route |
49
50
 
50
51
  Board's slots (`vk-board`, `vk-board-lane`, `vk-board-lane-header`, `vk-board-card`,
51
52
  `vk-board-add-card`) join this table when the board arrives.
52
53
 
54
+ The selection bar's parts (`SelectionBar`, `@viewkitjs/views/selection`):
55
+
56
+ | Slot | Part |
57
+ | ------------------------------------ | ---------------------------------------------------------- |
58
+ | `data-slot="vk-selection-bar"` | the fixed box the app places (the provider's `selectionBar`) |
59
+ | `data-slot="vk-selection-pill"` | the pill inside it: the count, the verbs, the trash, More |
60
+ | `data-slot="vk-selection-chip"` | the count that clears the selection, on the desktop |
61
+
53
62
  ## States
54
63
 
55
64
  Flags the rendering styles, present as an attribute when true and absent when false, so a skin
@@ -116,6 +125,8 @@ frame from its scale and its state; a skin reads them and an app overrides them
116
125
  | `--vk-text-10` | the smallest text size |
117
126
  | `--vk-head-text` | header text size |
118
127
  | `--vk-scrolled` | 0 or 1: content scrolled under the header |
128
+ | `--vk-pin` | a row's frozen cells and rail: `relative` at rest, `sticky` once the rows' box is scrolled sideways |
129
+ | `--vk-stick` | 0 or 1: 1 while `--vk-pin` is `sticky`; it scales their sticky offsets |
119
130
  | `--vk-parked` | 0 or 1: identity columns parked |
120
131
  | `--vk-frozen-on` | 0 or 1: the frozen band is on |
121
132
  | `--vk-row-py` | a rows view's vertical row padding |
@@ -158,7 +169,8 @@ declares both wherever a ground declares its own, so a part takes the states of
158
169
  The default atoms and the display also read `--vk-success`, `--vk-warning`, `--vk-info`,
159
170
  `--vk-label-blue`, `--vk-label-green`, `--vk-label-amber`, `--vk-label-red`, `--vk-label-purple`,
160
171
  `--vk-label-pink` and `--vk-label-teal` when the app declares them, each with a built-in fallback. The
161
- corners come from the app's Tailwind radius scale.
172
+ selection bar reads `--vk-float-shadow`, a whole `box-shadow` value for what floats over a list, with a
173
+ built-in fallback. The corners come from the app's Tailwind radius scale.
162
174
 
163
175
  **The page gutter is the app's, if it has one.** `--vk-gutter` is the side padding a page gives its
164
176
  content: the grid's rows run edge to edge and line their content up with it. An app that pads its
@@ -169,17 +181,21 @@ clear of it and a revealed cell stops above it. An app declares it on the grid's
169
181
  undeclared, the grid reads `0px`.
170
182
 
171
183
  **The grid scrolls inside itself.** Its frame fills the box its app gives it: a definite height, or
172
- a flex column (the frame is `height: 100%`, `flex: 1 1 0` and `min-height: 0`). Inside the frame one
173
- scroll area holds the table both ways, and each group's name bar and header row pin at the area's
174
- top, so nothing the app pins above the grid concerns it. A box with no height gets a grid that grows
184
+ a flex column (the frame is `height: 100%`, `flex: 1 1 0` and `min-height: 0`). Inside the frame the
185
+ rows' box holds the table, both ways, and each group's name bar and header row pin at its top, so
186
+ nothing the app pins above the grid concerns it. While the page's lab asks for the lock
187
+ (`setGridLab({ boxes: 2 })`) on a touch screen, it scrolls up and down only, inside an outer box that
188
+ scrolls sideways only, so a flick moves the table one way, as the phone's own apps do. A box with no height gets a grid that grows
175
189
  to its rows: the page scrolls it, and its heads don't pin. The grid's rows and frozen columns sit
176
190
  inside your `Collapse`'s clip, so the clip must crop without scrolling (`overflow: clip`, never
177
191
  `hidden`): a clip that scrolls takes the frozen columns' sticky edge with it.
178
192
 
179
193
  **The grid's own variables are not public.** The grid sets `--vk-drag-shift` (a header cell's
180
194
  offset while its column is dragged to a new place), `--vk-col-w-<id>` (one column's resolved
181
- width, one per column) and `--vk-cols` (the columns' template on its scroll area, which every row
182
- reads) for itself. They carry the prefix because they share the global namespace;
195
+ width, one per column), `--vk-cols` (the columns' template on its rows' box, which every row
196
+ reads), and while the lab's lock is on `--vk-hold-x` and `--vk-sx` (the offsets that hold the frozen
197
+ columns, the rail, a group's name and the empty message at the left while the table is scrolled
198
+ sideways) for itself. They carry the prefix because they share the global namespace;
183
199
  an app neither sets nor reads them, and they may change in any release.
184
200
 
185
201
  ## The components map
@@ -192,9 +208,17 @@ and no `asChild`; the tooltip takes the element it wraps as `children`. The slot
192
208
  grid's editors and menus use, each in Base UI's shape, and an adapter on Radix and one on Base UI
193
209
  both fill every one.
194
210
 
195
- `Button` · `Popover` · `Tooltip` · `Checkbox` · `Menu` · `Command` · `Calendar` · `Collapse` · `Sheet` · `AppIcon` · `Markdown`
211
+ `Button` · `Popover` · `Tooltip` · `Checkbox` · `Menu` · `Collapse` · `Sheet` · `AppIcon` · `Markdown`
212
+
213
+ `Input`, optional: a single-line text box, `ViewsInputProps`. Every editor's text box draws through it; without it the editors draw a plain `<input>`. Forward every prop to your element, `ref` included. `chrome` is `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame). `OPTIONAL_COMPONENT_NAMES` lists the five optional slots apart from `COMPONENT_NAMES`, which lists the slots you must fill.
214
+
215
+ `Command`, optional: the command list's parts (`ViewsCommandParts`), through which the editors' lists and the grid's menus on the `popover` route draw. A list reached without one throws an error naming it. An app that hands `Picker` and sets `menus: "menu"` needs none.
196
216
 
197
- `Input`, optional: a single-line text box, `ViewsInputProps`. Every editor's text box draws through it; without it the editors draw a plain `<input>`. Forward every prop to your element, `ref` included. `chrome` is `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame). `OPTIONAL_COMPONENT_NAMES` lists it apart from `COMPONENT_NAMES`, which lists the slots you must fill.
217
+ `Picker`, optional: a whole pick list your app draws, `ViewsPickerProps`. Handed one, the select, several-values, place and relation editors open it, handed their rows as `ViewsPickerItem` data (a value, its words, a status slot or a colour, a glyph, a line, a group), what is held, the empty row's words, the search's words, create (`onCreate`, handed what was typed, returning the value it makes) and `form`. The body hands back `onValueChange` (the pick, or the whole new list) and `onDone` (a pick of one is made). The editor keeps the draft, what each close means, Tab, Escape, the save and, on a phone, the panel's ✕ and ✓: at `form: "phone"` your body draws none of its own and hands every change as it is made. Tab is taken before your body hears it. Left out, these editors draw from `Command`. A relation's list is filtered (a static source, by label) or fetched (a remote one, a page at a time) by the editor, never by your body: it hands every typed query to `onSearch` and draws `items` as handed, with `doing` (`searching` or `failed`), `onRetry` and `onMore` for a remote one. A relation's rows may carry a `badge` (a word telling kinds apart), a `glyph` (the record's own, unsized), an `avatarUrl` and the record's `kind`; its create rows come as `actions` (`ViewsPickerAction`), after the rows, and picking one closes the editor before it runs; a set whose field leads hands `lead` (which value leads, `onLead`, and its words). Held records come first while nothing is typed, and by the same search once something is.
218
+
219
+ `Calendar`, optional: a calendar over ISO days, `ViewsCalendarProps`, which the date editor draws its month through, with its own typed line, quick days and time around it. Reached without one, it throws an error naming it. Handed `DateBody`, it is never reached.
220
+
221
+ `DateBody`, optional: a whole date body your app draws, `ViewsDateBodyProps`. Handed one, the date editor opens it in every host, handed the value on the local calendar (a day, or a day and a time), whether it holds a time, whether it may be emptied, the quick picks (`ViewsDatePick`), today, what was typed on what opened it, `autoFocus` and `form`. The body hands back `onValueChange` (every change as it is made, a typed day once it reads as one) and `onDone` (a pick that finishes the edit). The editor keeps the draft, what each close means (Escape's keep or throw-away by field type), the save and, on a phone, the panel's ✕ and ✓: at `form: "phone"` your body draws none of its own. Escape is taken before your body hears it, so a popover of your own inside the body never hears Escape either; Tab walks your body's controls and closes from either end.
198
222
 
199
223
  The popover takes `alignOffset`, `initialFocus` (false keeps focus where it was when the popup
200
224
  opens; the editor that then takes focus does so with `preventScroll`, so the package's own focus
@@ -213,10 +237,13 @@ calendar takes a controlled `month` (`YYYY-MM`) with `onMonthChange`, a `dropdow
213
237
  draws its month and weekday names and starts its week; an adapter may ignore it and keep its
214
238
  calendar's own. The tooltip takes `align` and a class; the checkbox takes `checked` and, for a box
215
239
  ticked partly (some, not all), `indeterminate`, a press on which hands `true` while `checked` is false; its `onCheckedChange` hands, as its second argument, `{ event }`, the press that changed it, as Base UI reports it; its `partialTone` (`muted` or `brand`) colours the partial mark; the collapse takes `clipClassName`, a class on the box that crops; the app mounts
216
- one tooltip provider above the views, and a tooltip never mounts its own. A menu item may carry a
217
- `shortcut` hint and an `href`; a `checked` row is checkable and closes the menu like any row; an
218
- item's `children` are a group, its rows drawn in place under the item's label, never a flyout, and
219
- the group's own `onSelect`, `href` and `checked` are ignored, and a group marked `disabled` disables every row under it, at every depth: the provider hands your `Menu` those rows already `disabled`, so you draw each row by its own flag. `AppIcon` is the app's own icon component by the app's own names, for
240
+ one tooltip provider above the views, and a tooltip never mounts its own. The menu takes `label`,
241
+ its name (its `aria-label`), which every menu the package opens hands. A menu item's `label` is its
242
+ words, always text; it may carry a `shortcut` hint and an `href`, and a `disabled` row may carry
243
+ `disabledReason`, why it can't be used, for you to show (a tooltip, a second line); a `checked` row is checkable and closes the menu like any row, unless it
244
+ carries `keepOpen`, a hint to leave the menu open so several can be ticked in turn; an
245
+ item's `children` are a group, its rows drawn in place under the item's label unless it carries `beside`, a hint to open them one level in, its row showing its label and `detail`, and
246
+ the group's own `onSelect`, `href` and `checked` are ignored, and a group marked `disabled` disables every row under it, at every depth: the provider hands your `Menu` those rows already `disabled`, each one that gives no reason carrying the group's `disabledReason`, so you draw each row by its own flag. Any row may carry `detail`, its current value in words, for its end. An adapter that draws none of the three keeps every row closing and every group in place, and loses nothing it needs. So an adapter needn't guess: a ticked row's `onSelect` fires on every pick, also when it is already ticked (a second pick of the ticked sort flips its direction), so an adapter that draws ticked rows as a radio value still calls it; ticked rows that close, inside a group, are one choice among several (a pick list), and ticked rows with `keepOpen` are separate ticks (checkboxes); a label is always text, so a swatch or a column's mark rides as the row's `icon` beside it. The sheet takes `label`, its title in words whenever the title is words (its accessible name, and the title of a head that takes only text), and, when the provider's `sheetActions` is `head`, `actions`: the editor panel's ✕ (`close`) and ✓ (`done`, absent where the body saves on its pick), each a `label` and an `onPress`, for your sheet's own head; with `bar`, the default, the panel draws them itself. `AppIcon` is the app's own icon component by the app's own names, for
220
247
  the glyphs a host declares (a row's icon, a binding's icon, an option's icon), drawn on the first paint (rows are measured as they mount); the semantic glyphs the rendering itself
221
248
  needs are a port, by meaning (below). `Markdown` is the app's markdown renderer, handed the stored text whole; the
222
249
  package draws rich text through it and parses none.
@@ -233,12 +260,19 @@ The package ships none of them and depends on neither library.
233
260
 
234
261
  What a Base UI adapter over shadcn copies does where its copies stop short of a slot.
235
262
 
236
- **The menu.** The map's `Menu` has an anchor and no trigger, and no flyouts. Build it from the menu
263
+ **The menu.** The map's `Menu` has an anchor and no trigger. Build it from the menu
237
264
  library's root, positioner and popup, handing the anchor to the positioner, where your copy's content
238
- doesn't forward one; with no flyouts, a root needs no trigger of its own. Opened, it puts focus on its
265
+ doesn't forward one; the root needs no trigger of its own, because the package opens it. A group that asks for
266
+ `beside` may be a submenu whose trigger is the group's own row, inside the open menu; with none, draw it in place.
267
+ Opened, it puts focus on its
239
268
  first row, as your `Popover` does by default: a row's menu opened by a key starts there.
240
269
 
241
- **A disabled group.** Nothing to do: its rows reach you already `disabled`.
270
+ **A disabled group.** Nothing to do: its rows reach you already `disabled`, with the group's reason where they give none.
271
+
272
+ **The sheet's head.** A sheet that draws a head of its own (a title with buttons beside it) sets the
273
+ provider's `sheetActions` to `head` and draws `actions.close` and, when handed, `actions.done` there,
274
+ with your own ✕ and ✓ glyphs; a close of your sheet's own (its ✕, a swipe) still reaches
275
+ `onOpenChange` and discards like `actions.close`.
242
276
 
243
277
  **`chrome: "menu"`.** It is your menu panel's surface: no inset, because the list inside carries its
244
278
  own, and no card width: it is as wide as its list. Where your copy has only the card popover, lay your
@@ -248,7 +282,7 @@ menu classes over it.
248
282
  check. Where your copy's item draws a tick of its own, hide it.
249
283
 
250
284
  **A command list that scrolls as it mounts.** The chips, select and relation editors, and the grid's
251
- Add column and group menu, mount a `Command.Root` with its rows in the frame the popover opens, before
285
+ Add column (on the `popover` route) and group menu (on the `popover` route: past eight sort choices, or at any count when the app names its parts with `groupMenu`), mount a `Command.Root` with its rows in the frame the popover opens, before
252
286
  your popover has placed its popup. A command library that scrolls its selected item into view on mount
253
287
  (cmdk does, with `scrollIntoView`) scrolls the page towards the popup's unplaced spot, which at a
254
288
  library's default positioning can be the page's top, and `preventScroll` on the focus doesn't reach
@@ -282,9 +316,12 @@ container: the inset a run of rows sits in, inside a panel or a command list's g
282
316
  a button or, with `interactive={false}`, a static line), `RowContent` (a row's inside, for inside a
283
317
  command list's item, which owns the element and the highlight), `TickBox` (a paint-only tick box),
284
318
  `StatusBadge` (a pill by status slot), `StatusMarker` (an attention badge that opens its reason) and
285
- `Tag` (a category chip, removable, with an optional leading glyph), `CommandMenu` (a `command` cell's verb menu, opened from the trigger the cell drew; the default is the components map's `Menu`), `RowMenu` (the row's right-click menu, around the row: Open page, the rows the rendering builds, Delete; the default is the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯ (`data-slot="vk-grid-row-more"`), wrapped in `data-slot="vk-row-menu"`; the grid's row-menu keys send a cell the same right-click, with no press before it, so a `RowMenu` of your own opens on any `contextmenu` and doesn't wait for a press; its Delete asks the `confirm` port with `views.menus.row-delete-confirm` (the browser's own confirm when you hand none), and a delete that rejects says so through the toast port's `error` with `views.menus.row-delete-failed`; a long-press on a phone opens nothing) and `RelationLink` (where a relation chip goes, around the chip the display drew; the default goes nowhere), `Loading` (a wait: the list reloading, or more rows arriving; the default is a plain ring) `LoadMore` (how a list asks for its next page; the default watches a sentinel past the last row) and `PlatformMark` (a link's platform, drawn before it, read from its address with the conventions' platforms; the default draws nothing, so a link looks plain, and the package ships no brand art, so an app that wants marks draws its own by the platform's key into `data-slot="vk-platform"`). Each ships as a default, exported as `DEFAULT_VIEWS_ATOMS`, drawn
319
+ `Tag` (a category chip, removable, with an optional leading glyph), `CommandMenu` (a `command` cell's verb menu, opened from the trigger the cell drew; the default is the components map's `Menu`), `RowMenu` (the rows' right-click menu, once around each section's rows' container and aimed at the row a press or a right-click came from, its props that row's: Open page, the rows the rendering builds, Delete; the default is the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯ (`data-slot="vk-grid-row-more"`), wrapped in `data-slot="vk-row-menu"`; the grid's row-menu keys send a cell the same right-click, with no press before it, so a `RowMenu` of your own opens on any `contextmenu` and doesn't wait for a press; its Delete asks the `confirm` port with `views.menus.row-delete-confirm` (the browser's own confirm when you hand none), and a delete that rejects says so through the toast port's `error` with `views.menus.row-delete-failed`; a long-press on a phone opens nothing) and `RelationLink` (where a relation chip goes, around the chip the display drew; the default goes nowhere), `RelationRoles` (a link's roles, inside its chip after the record's name, on a `many` relation that declares `links`; the default draws their labels in the subtle colour after a middle dot, wrapped in `data-slot="vk-relation-roles"`), `Loading` (a wait: the list reloading, or more rows arriving; the default is a plain ring) `LoadMore` (how a list asks for its next page; the default watches a sentinel past the last row) and `PlatformMark` (a link's platform, drawn before it, read from its address with the conventions' platforms; the default draws nothing, so a link looks plain, and the package ships no brand art, so an app that wants marks draws its own by the platform's key into `data-slot="vk-platform"`), and the rows the panels (`/panels`) draw with: `ChoiceRow` (picks a value: its label, a second line, a right-hand meta, the check when chosen), `CheckRow` (toggles one of many, a tick box on the left), `RadioRow` (picks one of a set, its mark a check or, with `mark="box"`, a tick box; a disabled row's reason in your `Tooltip`), `DirectionButton` (a sort's direction arrow, named `views.panels.direction`), `MenuRow` (a drill-in row: a glyph, the section, where it stands, a chevron), `ToggleRow` (a boolean flipped in place, with a way back named `views.panels.toggle-reset`) and `PanelSearch` (a panel's text box, a filled well with a magnifier). Each ships as a default, exported as `DEFAULT_VIEWS_ATOMS`, drawn
286
320
  from the app's colours; an app swaps any of them through the provider's `atoms`, and the rest
287
- stay the defaults.
321
+ stay the defaults. `SelectionSheet` is the phone's sheet of a selection's verbs, opened by the
322
+ selection bar's Actions: the default is the components map's `Sheet` holding the atoms' rows, a group's
323
+ or an options verb's rows opening in place under it and the delete last in words; picking a row closes
324
+ the sheet, then runs it. An app swaps in its own action sheet.
288
325
 
289
326
  A row's `size` is `compact` (13px: a command list's rows, a list of values) or `regular` (the app's
290
327
  menu size, the default). Its label truncates when it is text and is laid out in a row when it is a
@@ -298,7 +335,7 @@ since the flyout is the components map's `Popover`, a dialog of plain rows; and
298
335
  and `open` while that flyout is up (`data-open`, the pressed ground).
299
336
 
300
337
  The defaults mark themselves with `data-slot="vk-list"`, `data-slot="vk-row"`, `data-slot="vk-row-content"`,
301
- `data-slot="vk-tick"`, `data-slot="vk-status"`, `data-slot="vk-marker"`, `data-slot="vk-tag"`, `data-slot="vk-command-menu"`, `data-slot="vk-relation-link"`, `data-slot="vk-loading"`, `data-slot="vk-load-more"`, `data-slot="vk-platform"` and `data-slot="vk-row-menu"`, and
338
+ `data-slot="vk-tick"`, `data-slot="vk-status"`, `data-slot="vk-marker"`, `data-slot="vk-tag"`, `data-slot="vk-command-menu"`, `data-slot="vk-relation-link"`, `data-slot="vk-relation-roles"`, `data-slot="vk-loading"`, `data-slot="vk-load-more"`, `data-slot="vk-platform"`, `data-slot="vk-row-menu"` and `data-slot="vk-selection-sheet"`, the panels' rows with `data-slot="vk-choice-row"`, `data-slot="vk-check-row"`, `data-slot="vk-radio-row"`, `data-slot="vk-direction"`, `data-slot="vk-menu-row"`, `data-slot="vk-toggle-row"` and `data-slot="vk-panel-search"`, and
302
339
  with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked`, `data-open` (flags),
303
340
  `data-status` (the slot's name) and `data-platform` (a link's platform key). A swapped atom marks itself as its app does.
304
341
 
@@ -313,7 +350,7 @@ a desktop and its `Sheet` on a phone, and marks its parts with these slots:
313
350
  | slot | the element |
314
351
  | ---------------------------------- | ------------------------------------------------------------- |
315
352
  | `data-slot="vk-editor-panel"` | the popover's panel, or the sheet's body, an editor sits in |
316
- | `data-slot="vk-editor-bar"` | the sheet's bar: its ✕ and its ✓ |
353
+ | `data-slot="vk-editor-bar"` | the sheet's bar: its ✕ and its ✓ (none with `sheetActions: "head"`) |
317
354
  | `data-slot="vk-editor-refusal"` | the reason a refused value gave, under the editor |
318
355
  | `data-slot="vk-text-editor"` | the text editor's box (`@viewkitjs/views/editors/text`), unless its host names its own |
319
356
 
@@ -339,6 +376,8 @@ The grid's menus: `moveLeft` `moveRight` `group` `clearSort` `sortRowsUp` `sortR
339
376
  `sortRowsDown` are a menu's verbs, sorting the rows by a column; `sortAsc` and `sortDesc` are the mark a
340
377
  sorted header wears.
341
378
 
379
+ The panels: `search` (a panel's text box, a magnifier) and `reset` (a setting's way back to the reader's default).
380
+
342
381
  An app maps its own icon names onto these in its adapter; a glyph the rendering needs that is not
343
382
  here is added here first, with a changelog line.
344
383
 
@@ -347,7 +386,7 @@ here is added here first, with a changelog line.
347
386
  The package words only its own strings; a string `@viewkitjs/fields` already keys stays a fields
348
387
  message, read from the conventions the provider carries. The package's are a closed list of
349
388
  `{ key, values }` messages under `views.grid.*`,
350
- `views.editors.*`, `views.menus.*` and `views.display.*`: `views.editors.tag-remove` (`{ label }`),
389
+ `views.editors.*`, `views.menus.*`, `views.display.*`, `views.selection.*` and `views.panels.*`: `views.editors.tag-remove` (`{ label }`),
351
390
  `views.editors.marker-resolve`, `views.editors.marker-no-reason`, `views.editors.range-low` and
352
391
  `views.editors.range-high` (a range editor's two boxes, "From" and "To"), and `views.editors.name-given`,
353
392
  `views.editors.name-family` and `views.editors.name-full` (a name editor's three boxes); `views.editors.values-add` ("Add"), `views.editors.values-label` ("Label"), `views.editors.values-main` ("Main", the main value's mark), `views.editors.values-make-main` (`{ value }`, "Make {value} the main one") and `views.editors.values-remove` (`{ value }`, "Remove {value}") (a value list editor's rows); `views.editors.discard` ("Discard", the editor sheet's ✕) and `views.editors.save` ("Save", its ✓); `views.editors.open-email`, `views.editors.open-phone` and `views.editors.open-link` (`{ value }`, "Email {value}", "Call {value}", "Open {value}", the open action beside a stored value in a phone's sheet); the place editor's: `views.editors.place-country` ("Country"), `views.editors.place-country-search` ("Search countries"), `views.editors.place-change-country` ("Change country"), `views.editors.place-region-search` ("Search"), `views.editors.place-line1` ("Address line 1"), `views.editors.place-line2` ("Address line 2"), `views.editors.place-required` (`{ label }`, "{label} *", a part its country asks for), the region's words `views.editors.place-region-area`, `views.editors.place-region-county`, `views.editors.place-region-department`, `views.editors.place-region-district`, `views.editors.place-region-do-si`, `views.editors.place-region-emirate`, `views.editors.place-region-island`, `views.editors.place-region-oblast`, `views.editors.place-region-parish`, `views.editors.place-region-prefecture`, `views.editors.place-region-province` and `views.editors.place-region-state`, the city's `views.editors.place-city-city`, `views.editors.place-city-district`, `views.editors.place-city-post-town` and `views.editors.place-city-suburb`, and the postal code's `views.editors.place-postal-eircode`, `views.editors.place-postal-pin`, `views.editors.place-postal-postal` and `views.editors.place-postal-zip` (each its word in English: "County", "Do/Si", "Post town", "PIN code", "ZIP code"); `placeWordKey(kind, word)` gives the key for a word `placeFormat` names; `views.editors.place-region` ("Region") beside the place editor's `views.editors.place-country`,
@@ -361,15 +400,19 @@ row), `views.menus.date-style` (`{ style }`: `"short"`, `"long"`, `"numeric"` or
361
400
  `views.menus.automatic` (the field's own decimals, an option's own colour), `views.menus.currency`,
362
401
  `views.menus.percent-display` ("Display"), `views.menus.percent-display-option` (`{ display }`: `"text"` is "Number",
363
402
  `"bar"`, `"ring"`), `views.menus.colour` (`{ colour }`, one of the eight option colours: "Gray" … "Teal") and
364
- `views.menus.colours-reset` ("Reset colors"); a group's menu: `views.menus.group-options` (its button's label),
403
+ `views.menus.colours-reset` ("Reset colors"); a group's menu: `views.menus.group-options` (its button's label, and its menu's name on the `menu` route),
365
404
  `views.menus.group-sort` ("Sort rows"), `views.menus.search`, `views.menus.group-show` ("Show"), `views.menus.group-count`
366
405
  ("Count") and `views.menus.group-hide` ("Hide group"); "+ Add column": `views.grid.add-column` (its header
367
- cell), `views.menus.add-column-search` ("Search columns…"), `views.menus.add-column-no-match` (`{ query }`) and `views.menus.add-column-all-shown`; a row's menu:
406
+ cell, and its menu's name on the `menu` route), `views.menus.add-column-search` ("Search columns…"), `views.menus.add-column-no-match` (`{ query }`) and `views.menus.add-column-all-shown`; a row's menu:
368
407
  `views.menus.copy`, `views.menus.cut`, `views.menus.paste`, `views.menus.clear` and `views.menus.edit` (a cell's lane),
369
408
  and the plain row menu's `views.menus.row-open` ("Open page"), `views.menus.row-select` (`{ selected }`, `"true"` is
370
409
  "Deselect", as text for a catalog's `select`), `views.menus.row-delete`, `views.menus.row-delete-confirm` (the
371
410
  browser's confirm before a delete: "Delete this row?") and `views.menus.row-delete-failed` (the error toast when the
372
- delete the host ran rejects: "Failed to delete the row");
411
+ delete the host ran rejects: "Failed to delete the row"), and `views.menus.row-menu` (its name, handed to your `Menu` as
412
+ `label`: "Row actions"); a `command` field's verb menu's name: `views.menus.commands` (`{ field }`: "Actions for Stage")
413
+ and `views.menus.commands-unnamed` ("Actions", when its opener hands no field); `views.menus.figure-menu`
414
+ (`{ field }`: "Calculate Amount", the figure picker's name on the `menu` route) and `views.menus.column-menu`
415
+ (`{ field }`: "Options for Amount", a column menu's name on the `menu` route);
373
416
  the grid's own: `views.grid.figure` (`{ kind }`, a footer figure's name, `"none"` included: "None", "Sum", "Avg", "Min",
374
417
  "Max", "Count", "Filled", "Unique", "Ratio"), `views.grid.figure-pick` ("Calculate", an empty footer cell),
375
418
  `views.grid.loading` ("Loading rows"), the labels `views.grid.select-row`, `views.grid.select-group`,
@@ -386,7 +429,10 @@ over several cells left because they can't be empty, already joined in the viewe
386
429
  `views.grid.paste-pick` and `views.grid.paste-not-linkable` (each `{ value }`, the pasted text), `views.grid.paste-other-currency` (`{ currency }`, the record's own: an amount pasted or filled into a
387
430
  record in another currency) and `views.grid.paste-not-range`; a paste or a fill that refused cells,
388
431
  `views.grid.paste-skipped` and `views.grid.fill-skipped` (each `{ count, reason }`: one toast per reason, its
389
- `reason` one of the refusals above in the app's words; an operation of one cell says the reason alone); and the warnings
432
+ `reason` one of the refusals above in the app's words; an operation of one cell says the reason alone); a write the app
433
+ refused, said when the provider's `sayRefusals` is on, `views.grid.commit-refused` (`{ field }`, the field's name, for a
434
+ refusal whose error carries no words: "Couldn't save Amount.") and `views.grid.commit-refused-many` (`{ count, reason? }`,
435
+ a batch, once, with the first refusal's words when it has any); and the warnings
390
436
  `views.grid.changed-elsewhere` (`{ field }`), `views.grid.changed-elsewhere-cells` (`{ count }`),
391
437
  `views.grid.saved-value`, `views.grid.saved-values` and `views.grid.row-left`. The functions that word a refusal
392
438
  (`gridClearRefusal`, `columnClearRefusal`, `columnEditRefusal`, `gridEditRefusal`) take the resolver last, and
@@ -401,6 +447,35 @@ record in another currency) and `views.grid.paste-not-range`; a paste or a fill
401
447
  (the title on a phone stored as typed), and `views.display.converted-from` (`{ code }`, "Converted from USD", the
402
448
  title on a money figure shown in another currency than its record's) and `views.display.as-shown` ("as shown",
403
449
  after that figure under a money editor).
450
+ And the panels' words, for the panels' door a later release publishes: the "For you" heading, `views.panels.for-you`; the Group
451
+ panel's orders, `views.panels.group-order-most` ("Most first"), `views.panels.group-order-fewest`,
452
+ `views.panels.group-order-newest`, `views.panels.group-order-oldest`, `views.panels.group-order-alphabetical`,
453
+ `views.panels.group-order-reverse-alphabetical`, `views.panels.group-order-reversed` (`{ label }`, "Stage, reversed"),
454
+ `views.panels.group-order-default`, `views.panels.group-order-count`, `views.panels.group-order-name` and
455
+ `views.panels.group-order-manual`; a list's joins, `views.panels.join-or` (" or ") and `views.panels.join-and`
456
+ (" and "), which hand the keys below a list already joined, since a value is text or a number; a relation filter's:
457
+ `views.panels.quantifier` (`{ quantifier }`: `"any"`,
458
+ `"none"` or `"every"`), `views.panels.relation-condition-options` (`{ field, options }`: "status is Active or
459
+ Paused"), `views.panels.relation-condition` (`{ field, value }`), `views.panels.relation-sentence`
460
+ (`{ rule, subject, one, many, conditions }`, the whole sentence: "Clients with at least one campaign where status is Active.", its
461
+ `rule` `"all"`, `"any"`, `"none"`, `"every"` or `"every-unmatched"`), `views.panels.relation-value-one`
462
+ (`{ quantifier, field, value }`, "Any · Status: Active") and `views.panels.relation-value-many`
463
+ (`{ quantifier, count }`); a row's value: `views.panels.filter-unavailable` ("Saved filter unavailable"), `views.panels.filter-all`
464
+ ("All"), `views.panels.filter-all-of` (`{ field }`, "All owners"), `views.panels.filter-selected` (`{ count }`),
465
+ `views.panels.date-range-all` ("All time"), `views.panels.date-range-between` (`{ from, to }`, "Jan 1 — Jan 9"),
466
+ `views.panels.date-range-from`, `views.panels.date-range-until`, `views.panels.time-scope-custom` ("Custom"),
467
+ `views.panels.sort-value` (`{ label, dir }`, "Name desc"), `views.panels.group-none` ("None") and
468
+ `views.panels.filter-count` (`{ count }`: "None", "1 filter", "2 filters"); and the rows':
469
+ `views.panels.direction` (`{ dir }`, "Direction: ascending"), `views.panels.toggle-reset` (`{ label }`, "Reset
470
+ Wrap"), `views.panels.toggle-reset-hint` ("Back to your default") and `views.panels.search-clear` ("Clear"). The
471
+ panels' label functions take the resolver last; each defaults to `resolveViewsMessage`.
472
+ The selection bar's words are under `views.selection.*`: `views.selection.count` (`{ count }`, "3 selected",
473
+ the phone sheet's title), `views.selection.selected` (the word after the count the bar draws),
474
+ `views.selection.deselect-all` (the count chip), `views.selection.clear` (the phone's ✕),
475
+ `views.selection.delete` (the trash's default name), `views.selection.more` and
476
+ `views.selection.more-label` (More, and its accessible name), `views.selection.actions` (the phone's
477
+ Actions), `views.selection.sheet-label` (the sheet's accessible name) and `views.selection.escape`
478
+ (the key cap in the chip's tooltip).
404
479
  A span behind now is fields' own `time.ago`. The provider's `messages` resolves them; it defaults to the
405
480
  package's English, `resolveViewsMessage`; an app's resolver that words only some keys calls
406
481
  `resolveViewsMessage` for the rest, since the provider does not fall back for it. A new key is a
@@ -447,7 +522,7 @@ A field whose changes are transitions with rules of their own (a lost deal needs
447
522
 
448
523
  ## The doors
449
524
 
450
- Twenty-one doors, and nothing else is importable but `./package.json`. What each holds is summarised here; each door's reference page names every export, one line each, starting at [`reference/views.md`](reference/views.md).
525
+ Twenty-one doors in this version, and nothing else is importable but `./package.json`; the twenty-second, the panels', is described last and comes in a later release. What each holds is summarised here; each door's reference page names every export, one line each, starting at [`reference/views.md`](reference/views.md).
451
526
 
452
527
  `@viewkitjs/views`, no React at runtime, holds two things. The rendering contract, every name listed:
453
528
  the constants `VK_PREFIX`, `GRID_SLOTS`, `GRID_STATES`, `VK_TOKENS`, `VK_COLOURS`,
@@ -472,19 +547,32 @@ public; nothing else at the root door is.
472
547
 
473
548
  `@viewkitjs/views/react`, which opens with the client directive: `ViewsProvider`, `useViews()` and
474
549
  `NOOP_PORTS`; the provider's types `ViewsProviderProps` and `ViewsContextValue`; the adapter's types
475
- `ViewsComponents`, `ViewsResolvedComponents` (the map as `useViews()` hands it on, `Input` always there), `ViewsPorts`, `ViewsIcons` and `ViewsIconProps`; the components' props
550
+ `ViewsComponents`, `ViewsResolvedComponents` (the map as `useViews()` hands it on, `Input`, `Command` and `Calendar` always there), `ViewsPorts`, `ViewsIcons` and `ViewsIconProps`; the components' props
476
551
  `ViewsButtonProps`, `ViewsPopoverProps`, `ViewsTooltipProps`, `ViewsCheckboxProps`, `ViewsMenuProps`,
477
- `ViewsMenuItem`, `ViewsCommandParts`, `ViewsCalendarProps`, `ViewsCollapseProps`,
552
+ `ViewsMenuItem`, `ViewsCommandParts`, `ViewsPickerProps`, `ViewsPickerItem`, `ViewsPickerAction`, `ViewsCalendarProps`, `ViewsDateBodyProps`, `ViewsDatePick`, `ViewsCollapseProps`,
478
553
  `ViewsSheetProps` and `ViewsInputProps`, with their shared shapes `ViewsAnchor`, `ViewsSide`, `ViewsAlign`,
479
554
  `ViewsCloseReason` and `ViewsOpenChange`; the ports' types `ViewsToastPort`, `ViewsHapticsPort`,
480
555
  `ViewsClipboardPort`, `ViewsPrefsPort`, `ViewsConfirmPort`, `ViewsConfirmRequest` and `ViewsResolvedPorts` (the
481
556
  ports `useViews()` hands on, `confirm` always there); the atoms' `DEFAULT_VIEWS_ATOMS` and types `ViewsAtoms`,
482
557
  `ViewsListProps`, `ViewsRowProps`, `ViewsRowContentProps`, `ViewsTickBoxProps`, `ViewsStatusBadgeProps`,
483
- `ViewsStatusMarkerProps`, `ViewsTagProps`, `ViewsCommandMenuProps`, `ViewsRowMenuProps`, `ViewsRowMenuItem`, `ViewsRelationLinkProps`, `ViewsLoadingProps`, `ViewsLoadMoreProps` and `ViewsPlatformMarkProps`; and, re-exported from the root door, `ComponentName`,
558
+ `ViewsStatusMarkerProps`, `ViewsTagProps`, `ViewsCommandMenuProps`, `ViewsRowMenuProps`, `ViewsRowMenuItem`, `ViewsRelationLinkProps`, `ViewsRelationRolesProps`, `ViewsLoadingProps`, `ViewsLoadMoreProps` and `ViewsPlatformMarkProps`; and, re-exported from the root door, `ComponentName`,
484
559
  `PortName`, `ViewsIconName`, `ViewsMessage` and `ViewsMessageResolver`. The provider takes an
485
560
  optional `presentation`, `(defaults: FieldPresentation) => FieldPresentation`: how the app's numbers,
486
561
  dates and durations read — given the package's defaults (in the conventions' locale), return the
487
562
  app's. It is called where a value is drawn, so the app's provider imports none of the display.
563
+ It takes an optional `escape` (`ViewsEscapeRules`, `{ [type]: EditEscape }`, `EditEscape` being `"cancel"` or `"keep"`,
564
+ both types from `./react`): what Escape does in an editor of each field type, on a desktop. `keep` keeps what was
565
+ typed and closes, 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 left
566
+ out throws the edit away, the default. On a phone every way out of the sheet throws the edit away. An editor that
567
+ commits only on a pick (a select, a status, a single relation, a user) throws it away on Escape whatever the rule.
568
+ And an optional `sayRefusals` (default false): the grid says why the app refused an edit it sent, through the toast
569
+ port's `error`; off, the app says it. And an optional `menus` (`ViewsMenuRoute`, default `popover`): how the grid
570
+ opens its own menus. `popover` draws ViewKit's rows in your `Popover`; `menu` hands them to your `Menu` as rows, the
571
+ footer's figure picker one ticked row per figure, and a column's header menu its rows, each format setting and each
572
+ option's colour a group beside it with its current choice as `detail`, and a group's ⋯ its sort choices a group
573
+ beside it with no search field, its figure toggles ticks that keep the menu open, and Hide, and the grid's own "+ Add
574
+ column" each hidden column a row and each field with parts a group beside it with its count as `detail`, with no
575
+ search field, on a phone too. The row menu and a command cell's menu always go through your `Menu`.
488
576
 
489
577
  `@viewkitjs/views/display`, no client directive on the door (a server module may reach its string
490
578
  formatters), every rendering file behind it carrying its own: `renderFieldValue` and `DISPLAY_CORES`
@@ -508,7 +596,8 @@ low and high, an empty box an open end), `@viewkitjs/views/editors/location` (`L
508
596
  `LocationEditorHandle`: the country first, then its parts in its order, a region from its list),
509
597
  `@viewkitjs/views/editors/value-list` (`ValueListEditor`, `ValueListEditorHandle`: several emails, phones, links or
510
598
  domains, a row each with its label and a main mark, committed as one list of `{ value, label, main }`, the main one
511
- first; `labels: false` for a host that keeps only the values),
599
+ first; `labels: false` for a host that keeps only the values; `escapeKeeps` for a host whose session keeps on
600
+ Escape, `EditSession.keeps`: its rows are checked first, as on Enter),
512
601
  `@viewkitjs/views/editors/date` (`DateEditor`, `DateEditorHandle`) and
513
602
  `@viewkitjs/views/editors/chips` (`ChipsEditor`, `ChipsEditorHandle`). An editor owns its panel and
514
603
  what a close means; its host owns the popover, the anchor and the write. Its words are fields'
@@ -516,8 +605,11 @@ messages, read from the provider's conventions unless the host hands `message`.
516
605
 
517
606
  `@viewkitjs/views/editors/session`, opening with the client directive: `useAnchoredEditSession` and
518
607
  `EDITOR_EXIT_MS` — the one-answer guard and the exit gap every host that opens an editor over a value
519
- shares; Escape always discards through it, and a refused attempt's reason comes back as `refusal`
520
- (`EditSession`, `EditSessionAttempt`). Its own door, so a host that needs the session does not load the six editors.
608
+ shares; Escape discards through it unless its optional `escape` is `"keep"` (on a desktop, read once at open: the
609
+ editor is asked as for a press outside, and `EditSession.keeps` says so), and a refused attempt's reason comes back as
610
+ `refusal` (`EditSession`, `EditSessionAttempt`). `useEscapeRule(type)` and `EditEscape` come from it too: the
611
+ provider's `escape` for a field type, for a host to hand its session. Its own door, so a host that needs the session
612
+ does not load the six editors.
521
613
 
522
614
  `@viewkitjs/views/editors/panel`, opening with the client directive: `EditorPanel`, `EditorPanelProps`
523
615
  and `EditorSurface` — an editor opened as the components map's `Popover` on a desktop and its `Sheet`
@@ -569,12 +661,23 @@ and `ROW_NO_TEXT_SELECT`, and the types `ListSelectionConfig`, `ListBatchApi`, `
569
661
  own: `GridTable` and its props `GridTableProps` (flat, as a host's binding hands them),
570
662
  `useGridTablePrefs` (a grid's personal preferences: the host's prefs and their setter in, the props to spread onto `GridTable` out), the types
571
663
  an app writes its props against, `GridSortState`, `GridGroupSortOption`, `GridCellCommitFn` and
572
- `GridCellsCommitFn`, and `GridGroupByState`, `GridGroupFigure` and `GroupCountNoun`; and the helpers a
664
+ `GridCellsCommitFn`, and `GridGroupByState`, `GridGroupFigure` (a `GridDeclaredFigure` or a `GridDrawnFigure`), `GridGroupMenuPart`, `GridRowOpenedFrom` (what `onOpenRow` hands with the row) and `GroupCountNoun`; and the helpers a
573
665
  host's binding shares with the grid: `GridCommitContext` and `GridCommitOutcome` (what a commit was and how it ended),
574
666
  `deriveGridSelectValues` and `deriveGridRelationValues` (the values a column's filter offers),
575
667
  `cellCopyText` and `cellEditBaseline` (a cell's copy text and the value an edit starts from, which a
576
- CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The selection bar, the house menu rows, the group
577
- collapse and the type icons are the app's.
668
+ CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The house menu rows, the group collapse and the type
669
+ icons are the app's; the selection bar is `SelectionBar`, on the selection door, drawn with the app's verbs.
670
+
671
+ `@viewkitjs/views/panels`, not in this version (a later release publishes it, with the controls), no client
672
+ directive on the door, the one hook behind it (`useFilterOpened`) carrying
673
+ its own: what a list's panels read and say. The settings they edit (`SortConfig`, `GroupConfig`, `ToggleConfig`,
674
+ `LayoutConfig` and its parts, `TimeScopeConfig`, `DateRangeConfig`, `ActivePanel`, `ViewOptionInputs`,
675
+ `CollectionViewState`) with their predicates and `clearViewOptions`; which sections exist on a viewport
676
+ (`getViewOptionAvailability`, `resolvePersonalSection`); the Group panel's orders (`groupSortChoices`); and every
677
+ row's value (`filterValueLabel`, `relationSentence`, `sortValueLabel` and their siblings), each worded through a
678
+ `views.panels.*` key, the resolver taken last. The panels themselves join it as they move in. It is the one door
679
+ that may reach dnd-kit (`@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`), the package's optional peers,
680
+ which a panel's list drags with: an app that takes only the grid never installs them. The panels' rows are atoms.
578
681
 
579
682
  ## Registry items
580
683
 
@@ -8,7 +8,7 @@ This page takes you from install to a grid of records drawn with your own primit
8
8
  pnpm add @viewkitjs/views @viewkitjs/fields zod
9
9
  ```
10
10
 
11
- `react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The package is ESM only and runs on Node 20 or later.
11
+ `react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The dnd-kit packages are optional peers of views, for the panels' door a later release publishes; this version needs none of them. The package is ESM only and runs on Node 20 or later.
12
12
 
13
13
  The rendering carries Tailwind classes drawn from your tokens and paints through its own colour names. Two lines of setup make it look like your app: one `@source` line, so Tailwind sees the package, and one block mapping the `--vk-*` colours onto your theme. [Install](install.md) has both.
14
14
 
@@ -15,10 +15,12 @@ The components map hands the package your primitives: a button, a popover, a men
15
15
  - `Tag`: a category chip in its colour, with an optional leading glyph and remove control.
16
16
  - `CommandMenu`: a `command` cell's verbs.
17
17
  - `RelationLink`: where a relation chip goes.
18
+ - `RelationRoles`: a link's roles, inside its chip after the record's name.
18
19
  - `Loading`: a wait, the whole list reloading or more rows arriving.
19
20
  - `LoadMore`: how a list asks for its next page.
20
21
  - `PlatformMark`: a link's platform mark, drawn before the link.
21
22
  - `RowMenu`: the row's right-click menu.
23
+ - `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`: the rows the panels (`/panels`) draw with, a value row, a tick row, a one-of-a-set row, a sort's direction arrow, a drill-in row, a switch row and a panel's text box.
22
24
 
23
25
  The names are `ATOM_NAMES` from `@viewkitjs/views`, and the defaults hold exactly those.
24
26
 
@@ -113,6 +115,32 @@ assert.ok(acmeChip.includes('href="/companies/c1"'));
113
115
 
114
116
  `RelationLink` is your app's answer for every list. Two things come before it: a host whose own element is already the button (`slotOwnsClick`, a calendar card) gets a bare chip with no link at all, and a grid handed its own relation handler for a column opens that instead ([cells](cells.md)).
115
117
 
118
+ ## A link's roles
119
+
120
+ On a `many` relation that declares `links`, a link may hold roles (a deal's champion, a person's Owner and Decision maker at a company). The display reads them with `relationRolesOf` and hands `RelationRoles` the `RelationValue` and its roles in order, each its stored `value` and its `label` from the field's `links.roles` (a role the field no longer declares keeps its value as its label). It draws only when the link holds one or more, inside the chip, after the name, so the `RelationLink` around the chip wraps them too. The default draws the labels in the subtle colour after a middle dot (`Bea · Champion, Decision maker`), cut before the name in a narrow cell; hovering them names the record and every role in full, since the link around the chip names only the record. Yours draws them your way.
121
+
122
+ ```tsx
123
+ import type { ViewsRelationRolesProps } from "@viewkitjs/views/react";
124
+
125
+ function AppRelationRoles({ roles }: ViewsRelationRolesProps) {
126
+ return (
127
+ <span className="flex gap-1">
128
+ {roles.map((role) => (
129
+ <em key={role.value}>{role.label}</em>
130
+ ))}
131
+ </span>
132
+ );
133
+ }
134
+
135
+ const roleTags = renderToStaticMarkup(
136
+ <AppRelationRoles
137
+ relation={{ id: "p1", label: "Bea", roles: ["champion"] }}
138
+ roles={[{ value: "champion", label: "Champion" }]}
139
+ />
140
+ );
141
+ assert.ok(roleTags.includes("<em>Champion</em>"));
142
+ ```
143
+
116
144
  ## A link's platform mark
117
145
 
118
146
  A `url` value is drawn as a link, its scheme left off the label. When the link's address names a platform (LinkedIn, GitHub and the rest fields knows, plus any your conventions add with `defineConventions({ platforms })`), the display draws `PlatformMark` before it with that `LinkPlatform`: its `key` says which, its `name` what to call it. A link no platform claims is a website (`key: "website"`). The default draws nothing, so a link looks plain, and the package ships no brand art: a mark is yours to draw.
@@ -138,15 +166,15 @@ In your app the glyph is your icon component per key. The platform is read for f
138
166
 
139
167
  ## A command cell's verbs
140
168
 
141
- A `command` field offers verbs instead of an editor: moving a deal to Lost asks for a reason, so the cell opens your verbs rather than a picker. The cell draws the trigger (the value with a chevron, or a chevron beside a value that is already a control, such as a chip or a link) and hands it to `CommandMenu` with `trigger`, `items` and `align`. Each item has a `label`, an optional `icon`, its `onClick`, and `destructive` and `disabled` flags. The default anchors your components map's `Menu` on the trigger and keeps the click off the row, so opening the verbs neither selects the cell nor opens the row. Swap it when your app has its own action menu, or a sheet on a phone. [The contract](../contract.md#a-command-field) says how a command field is declared.
169
+ A `command` field offers verbs instead of an editor: moving a deal to Lost asks for a reason, so the cell opens your verbs rather than a picker. The cell draws the trigger (the value with a chevron, or a chevron beside a value that is already a control, such as a chip or a link) and hands it to `CommandMenu` with `trigger`, `items`, `align` and `label`, the field's name. Each item has a `label`, an optional `icon`, its `onClick`, `destructive` and `disabled` flags, and a `disabledReason` for a disabled one. The default names your components map's `Menu` after the field ("Actions for Stage"), anchors it on the trigger and keeps the click off the row, so opening the verbs neither selects the cell nor opens the row. Swap it when your app has its own action menu, or a sheet on a phone. [The contract](../contract.md#a-command-field) says how a command field is declared.
142
170
 
143
171
  ## The row's menu
144
172
 
145
- `RowMenu` wraps each grid row. The rendering builds its `items` (the clicked cell's clipboard rows, Select, your verbs for the row), and the menu adds an Open page row before them when the row has a page (`openHref`, opened in a new tab) and a Delete row after them when the row can be deleted (`onDelete`). Its props are `ViewsRowMenuProps`; each item is a `ViewsRowMenuItem`, a rule (`{ separator: true }`) or a labelled row with its `onClick`, optional `icon`, `destructive`, `disabled` and a `shortcut` hint the menu draws but never binds.
173
+ `RowMenu` wraps a section's rows: the grid mounts it once around each section's rows' container, never around each row, and aims it at the row a press or a right-click came from. Its props are that row's, set in the same event your menu opens on; `children` is the rows' container, which takes the props and `ref` your trigger hands it (a `Slot`, `asChild`) and passes them to its element; a right-click on no row arrives already prevented and opens nothing. The rendering builds its `items` (the clicked cell's clipboard rows, Select, your verbs for the row), and the menu adds an Open page row before them when the row has a page (`openHref`, opened in a new tab) and a Delete row after them when the row can be deleted (`onDelete`). Its props are `ViewsRowMenuProps`; each item is a `ViewsRowMenuItem`, a rule (`{ separator: true }`) or a labelled row with its `onClick`, optional `icon`, `destructive`, `disabled` with its `disabledReason`, and a `shortcut` hint the menu draws but never binds. The default names your `Menu` "Row actions" (`views.menus.row-menu`).
146
174
 
147
175
  The default opens your `Menu` at the pointer on a right-click, or from the row's ⋯ (`data-slot="vk-grid-row-more"`). On a touch screen a long-press opens nothing: the ⋯ is the way in there. Its Delete asks first, through the `confirm` port, with the message `views.menus.row-delete-confirm` and the row's `deleteLabel` as the `subject`; an app that hands no `confirm` gets the browser's own, and a confirm that rejects or throws counts as no. A delete that then rejects leaves the row where it was and says so through the toast port's `error`, with `views.menus.row-delete-failed`. [Ports](ports.md) covers `confirm` and the toast.
148
176
 
149
- Swap it for a menu of your own, or for a long-press that selects: `onToggleSelect`, present when the list can select, flips the row's selection. The default doesn't use it.
177
+ Swap it for a menu of your own, or for a long-press that selects: `onToggleSelect`, there from the first render wherever rows can be selected, flips the selection of the row last pressed. The default doesn't use it. The default opens your `Menu` at the pointer, so make your `Menu` a popover: one drawn in the page flow would draw after the section's rows.
150
178
 
151
179
  ## Waits
152
180
 
@@ -224,7 +252,7 @@ Inside a command list's item, which owns the element, the highlight and the keyb
224
252
 
225
253
  ## Styling the defaults
226
254
 
227
- The defaults mark themselves with a `data-slot` each, `vk-list`, `vk-row`, `vk-row-content`, `vk-tick`, `vk-status`, `vk-marker`, `vk-tag`, `vk-command-menu`, `vk-relation-link`, `vk-loading`, `vk-load-more`, `vk-platform` and `vk-row-menu` (`ATOM_SLOTS`), and with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked` and `data-open` (present when true), `data-status` (the status slot's name) and `data-platform` (a link's platform key). A stylesheet reaches a default through them, never through a class the package happens to use:
255
+ The defaults mark themselves with a `data-slot` each, `vk-list`, `vk-row`, `vk-row-content`, `vk-tick`, `vk-status`, `vk-marker`, `vk-tag`, `vk-command-menu`, `vk-relation-link`, `vk-loading`, `vk-load-more`, `vk-platform`, `vk-row-menu`, and the panels' `vk-choice-row`, `vk-check-row`, `vk-radio-row`, `vk-direction`, `vk-menu-row`, `vk-toggle-row` and `vk-panel-search` (`ATOM_SLOTS`), and with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked` and `data-open` (present when true), `data-status` (the status slot's name) and `data-platform` (a link's platform key). A stylesheet reaches a default through them, never through a class the package happens to use:
228
256
 
229
257
  ```css
230
258
  [data-slot="vk-row"][data-open] {
@@ -377,7 +377,7 @@ assert.throws(
377
377
  );
378
378
  ```
379
379
 
380
- The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled`). Being a function of the row, the menu follows the record's state. The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
380
+ The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled` and its `disabledReason`). Being a function of the row, the menu follows the record's state. The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
381
381
 
382
382
  ```ts
383
383
  import type { FieldMenus } from "@viewkitjs/views";
@@ -72,7 +72,7 @@ assert.equal(DISPLAY_CORES.date, DISPLAY_CORES.datetime);
72
72
  - **date** and **datetime**: in the reader's `dateStyle`, else the field's, else `short`; `withTime` from the options wins over the field's, and only an instant has a time. Hovering for a second shows the full date (and time, for an instant) through your components map's `Tooltip`, so a relative "3d ago" can be pinned to a moment. A value that doesn't parse draws as its own text.
73
73
  - **boolean**: four looks, the field's `format.style`. `checkbox` (the default) draws the `TickBox` atom, and `icon` your `booleanIcon(on)`; either becomes a real switch only when you hand `onToggle`, and is a plain glyph otherwise. `text` draws the option's label for the value, or the package's words. `marker` draws only when true, as the `StatusMarker` atom with your `marker` words, `markerReason` and `onResolve`.
74
74
  - **select**, **status** and **multiselect**: a select is a category and draws the `Tag` atom in its colour (a reader's `optionColors` first, then the option's declared colour, then one derived from the value). A status is a state and draws the `StatusBadge` atom in its option's slot. A multiselect draws a tag per value, through the several-values layout. A value no option names draws as the raw value, muted, with a hover saying it is not an option, unless you hand a `labelFallback`; an open (`custom-values`) vocabulary's values are their own labels. An option's `icon` is drawn through your `AppIcon`.
75
- - **relation** and **user**: a chip, the record's avatar when it has one, else your `entityIcon(kind)`, else the relation glyph, then its label. Where it goes is yours (`relationWrap`); without one the chip is inert. Several draw through the several-values layout, the lead link first. A user is drawn as a relation to a member, so the two never differ.
75
+ - **relation** and **user**: a chip, the record's avatar when it has one, else your `entityIcon(kind)`, else the relation glyph, then its label, then, on a `many` relation that declares `links`, the link's roles, drawn by the `RelationRoles` atom ([atoms](atoms.md)). Where it goes is yours (`relationWrap`); without one the chip is inert. Several draw through the several-values layout, the lead link first. A user is drawn as a relation to a member, so the two never differ.
76
76
  - **url**, **domain**, **email** and **phone**: a url is a link with its scheme off the label, its platform's mark before it (the [`PlatformMark` atom](atoms.md)); a value that is no safe web address draws as text. A domain links to its site and reads no platform from it. An email is a `mailto:` link. A phone is written in its international form, as its country writes it for a viewer in that country (the conventions' `region`) and internationally for anyone else, its extension after it, and dialled through a `tel:` link; a phone stored as typed draws as its text and is marked `data-as-typed`. Several values of one of these draw as the main one and a count.
77
77
  - **location**: in a cell, its city and its country; with `wrap: "full"`, the whole place. The country is named in the viewer's language.
78
78
  - **name**: the full name as written, else the given and family names, else `nameFallback`, else nothing.
@@ -62,7 +62,7 @@ assert.equal(TEXT_INPUT_TYPE.domain, "url");
62
62
 
63
63
  ## What an editor owns, and what you own
64
64
 
65
- An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar and decides that Escape discards and every other close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
65
+ An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar (or opens your app's own `DateBody` in their place, keeping the draft) and decides that Escape discards and every other close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
66
66
 
67
67
  The two speak through one handshake, the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`:
68
68
 
@@ -76,7 +76,7 @@ What an editor never does on its own (write, fetch, toast, decide the popover) i
76
76
 
77
77
  Every host that opens a panel over a value repeats two things, and both are easy to get wrong without seeing it. A close can arrive more than once (your popover reports an Escape, then the closed state it caused), and a session that answers twice writes twice. And the popover has an exit animation: answering at once re-renders the value behind it and unmounts the panel mid-animation.
78
78
 
79
- `useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. Escape always throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. It gives you two ways to hear the answer:
79
+ `useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. Escape throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. Hand it `escape: "keep"` and, on a desktop, Escape keeps what was typed: the session asks the editor as it would for a press outside, so a value that would be refused stays open with its reason, and a second Escape while that refusal stands throws the edit away. Read the rule for a field's type from the provider with `useEscapeRule(type)`; the app sets it once, `<ViewsProvider escape={{ date: "keep", location: "keep" }}>`, and a type it leaves out throws the edit away. An editor that commits only on a pick (a select, a status, a single relation, a user) throws the edit away on Escape whatever the rule, and the value list checks its rows first, as on Enter (`escapeKeeps={session.keeps}`). It gives you two ways to hear the answer:
80
80
 
81
81
  - `onAttempt(resolution)` and `onClose()`: the answer is asked synchronously, the moment the close happens, and you send the write right there. Return `{ accepted: false, reason }` to refuse it: the panel stays open, the session hands the reason back as `refusal` until the next attempt, and the next close asks again. On `{ accepted: true }` the popover closes, and `onClose` runs after the exit gap to finish the visual close. Prefer this one.
82
82
  - `onDone(resolution)`: the whole answer, the write included, arrives after the exit gap.
@@ -275,7 +275,7 @@ A pick of Won calls `close("pick")`; the editor answers `{ kind: "commit", paylo
275
275
 
276
276
  The host above draws its own popover, so on a phone it still opens a popover. `EditorPanel`, from `@viewkitjs/views/editors/panel`, opens the same editor in your `Popover` on a desktop and your `Sheet` on a phone, by the provider's `desktopQuery` (`(min-width: 1024px)` unless you hand in your own), chosen once when the session opens. It routes every dismissal to the session, so each means the same on every surface:
277
277
 
278
- - **Desktop:** the popover's Escape discards. A press outside closes with `"outside"`, which the editor answers by its own rule. A focus leaving the popover with no press (a Tab out of it) closes with `"blur"`, so a host that spends the click after an outside press spends none here. Once the session has closed, a press on the popover while it plays its exit is reported to nothing.
278
+ - **Desktop:** the popover's Escape discards, or keeps where the session keeps. A press outside closes with `"outside"`, which the editor answers by its own rule. A focus leaving the popover with no press (a Tab out of it) closes with `"blur"`, so a host that spends the click after an outside press spends none here. Once the session has closed, a press on the popover while it plays its exit is reported to nothing.
279
279
  - **Phone:** the sheet carries the field's name as its title, and a bar with ✕ and ✓. ✕, a swipe and the backdrop change nothing. ✓ closes as done, and a pick in a select saves on its own.
280
280
  - **Refusals:** a value your `onAttempt` refuses with a `reason` stays open, and the reason is drawn under the editor.
281
281
 
@@ -51,7 +51,7 @@ declare function openConfirmDialog(options: {
51
51
 
52
52
  The grid speaks through two of them:
53
53
 
54
- - **`error`** when it refuses something and says why: an edit or a clear on a cell that can't take one, a value its column can't store, the cells of a paste that could not take their value, a clear over a range with nothing clearable, a delete your app rejected (`views.menus.row-delete-failed`), and the row a person was editing leaving the list (`views.grid.row-left`).
54
+ - **`error`** when it refuses something and says why: an edit or a clear on a cell that can't take one, a value its column can't store, the cells of a paste that could not take their value, a clear over a range with nothing clearable, a delete your app rejected (`views.menus.row-delete-failed`), an edit your app refused when the provider's `sayRefusals` is on (`views.grid.commit-refused`, `views.grid.commit-refused-many`), and the row a person was editing leaving the list (`views.grid.row-left`).
55
55
  - **`warning`** when a value changes that the person didn't change: a cell they had edited, saved by someone else in the meantime (`views.grid.changed-elsewhere`, or `views.grid.changed-elsewhere-cells` for several), with a second line in `description` saying the saved value is what shows.
56
56
 
57
57
  `success` and `info` complete the shape, so one object over your toast library serves your own code too.