@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,16 +1,16 @@
1
1
  # `@viewkitjs/views/grid`
2
2
 
3
- The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The selection bar, the house menu rows, the group collapse and the type icons stay your app's: the grid takes them through its props. Guide: [the grid](../guides/the-grid.md).
3
+ The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The house menu rows, the group collapse and the type icons stay your app's: the grid takes them through its props. The bar a selection opens is `SelectionBar` from `@viewkitjs/views/selection`, which your `selection`'s `renderBar` draws with your verbs. Guide: [the grid](../guides/the-grid.md).
4
4
 
5
5
  ## The grid
6
6
 
7
7
  - `GridTable` — draws the spreadsheet: rows in their groups under a header whose column menus sort, group, format and hide, a checkbox rail and a ⋯ tail on each row, editors opened over cells, a selected range with copy, paste and undo, and a footer of figures per column. An edit shows in its cell at once and goes to `onCellCommit` (a batch to `onCellsCommit`); a failed write rolls the cell back. While `transitionPending` is true, or for one commit after `transitionKey` changes, it draws your app's loading atom instead of the rows. It takes a `GridTableProps`.
8
- - `GridTableProps` — what `GridTable` takes, flat, typed over your row. Five are required: `groups` (the rows, as the model's `ListGroup`s), `grouped` (whether they draw as group bands), `getRowId`, `columns` (the model's `ListColumn`s) and `onOpenRow` (what opening a row does: the title's text opens it). The rest are optional:
8
+ - `GridTableProps` — what `GridTable` takes, flat, typed over your row. Five are required: `groups` (the rows, as the model's `ListGroup`s), `grouped` (whether they draw as group bands), `getRowId`, `columns` (the model's `ListColumn`s) and `onOpenRow` (what opening a row does: the title's text opens it; it receives the row and a `GridRowOpenedFrom`, which brings the focus back to the row's cell once what it opened closes). The rest are optional:
9
9
  - Rows and groups: `rowHref`, `onPrefetchRow` (warm a row's detail on a pointer's intent), `rowClassName`, `rowIcon` and `showRowIcon` (the title cell's glyph, as a descriptor the grid sizes and colours), `onOpenRelation` and `entityIcon` (opening the record a relation cell points at, and the glyph for a kind; without `onOpenRelation`, relation cells are inert), `isCollapsed` and `onToggleGroup` (your group collapse), `renderGroupLabel`, `renderGroupFooter` (a group's paged continuation after its loaded rows), `onHideGroup`, `countOf`, `loadMore` (`hasMore`, `onReveal` and a `label`), `emptyState`, and `transitionKey`, `transitionPending` and `transitionLabel` (a view change: the wait paints before the new rows mount).
10
- - Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; the bar it opens is yours).
11
- - Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
10
+ - Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; its optional `renderBar` draws the bar it opens, `SelectionBar` with your verbs, and without one the rows still tick and no bar is drawn).
11
+ - Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupMenu` (the parts a group band's ⋯ holds, as `GridGroupMenuPart`s: `"sort"`, `"figures"`, `"hide"`; with it the sort list always searches through your `Command` on the `popover` route), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
12
12
  - Format overrides and their handlers, every map keyed by field key: `optionColors`, `dateStyles`, `durationStyles`, `numberFormats` (decimals null is the field's own), `showTimeOverrides` and `percentDisplays`, each with its `on…Change` handler taking the field key first, and `formatsWritable` (false hides the stored format knobs from the column menu; default true).
13
- - Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, the grid's own lists the hidden columns), `renderColumnMenuRows` (your rows in a column's menu, above Hide), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale`.
13
+ - Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, or answering `undefined`, `false` or `""`, the grid's own lists the hidden columns; answering `null`, none is drawn and no room is kept for it), `addColumnOnPhone` ("+ Add column" on a phone too, its list in your `Sheet`, or your `Menu` on the `menu` route; off by default), `parts` (a column per part of a name, a place or a range, offered under its field in "+ Add column"; off by default), `renderColumnMenuRows` (your rows in a column's menu, above Hide), `columnMenuItems` (the same rows as data, on the `menu` route), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale`.
14
14
  - Writes: `onCellCommit` (`GridCellCommitFn`) and `onCellsCommit` (`GridCellsCommitFn`).
15
15
  - List config: `listConfig` (the settings layer every user of the list inherits, which may only take away from what the columns declare: the table read-only, per-column locks; a constraint on the screen, while your API guards its own writes). The grid only reads it: a surface of your own changes it.
16
16
  - `useGridTablePrefs` — wires a list's view preferences to the grid. It takes `prefs` (the list's `ListViewPrefs`), `setPrefs` (stores a patch of them), `columns` (whose money reading the number formats read) and `viewBacked`, and returns `{ gridProps }` to spread on `GridTable`: the borders, row icon, frozen identity, checkboxes and scale, the format overrides, the column state, the group figures and the footer figures, each with the handler that writes it back through `setPrefs`.
@@ -20,7 +20,11 @@ The spreadsheet. The door carries no client directive; every rendering file behi
20
20
  - `GridSortState` — the list's sort, as the header menu reads and writes it: `value` (the sort key in force), `dir` and `onChange({ value, dir })`. The menu is a second control for the same stored sort your view's options drive.
21
21
  - `GridGroupByState` — the view's grouping, for the header menu's Group by and Ungroup: `fieldKey` (or null) and `onChange(fieldKey)`, null to ungroup. Present on lists backed by a saved view.
22
22
  - `GridGroupSortOption` — one sort a group band's menu offers, sorting the rows of every group at once: its `value`, `label` and an optional `defaultDir`.
23
- - `GridGroupFigure` — one figure a group's header can show: the summary `part` that turns it on, its column's header as its `label`, and `render(group)`, how it draws for a group.
23
+ - `GridGroupFigure` — one figure a group's band can show, either a `GridDeclaredFigure` or a `GridDrawnFigure`. Both carry the summary `part` that turns it on.
24
+ - `GridDeclaredFigure` — a figure the grid works out: its `column` (the column's id) and `kind` (a footer pick), written as that column's footer writes it, a paged group's from the source, or as your own footer cell where `renderAggregate` draws one; `label`, optional, is the column's header unless given.
25
+ - `GridDrawnFigure` — a figure you draw: its `label` and `render(group)`, how it draws for a group.
26
+ - `GridGroupMenuPart` — a part of a group band's ⋯ menu: `"sort"` (its sort choices), `"figures"` (the count and each figure, turned on and off) or `"hide"`.
27
+ - `GridRowOpenedFrom` — what `onOpenRow` hands with the row: the way back to the cell it was opened from. `focus()` puts the focus back on that cell and returns true; `element()` is that cell, for a dialog's final-focus option (pass the function itself: both are plain properties). A record a refetch moved under another group is found again by its id, at its first place; a record no longer shown sends the focus to the grid's frame (`focus()` returns false, `element()` is the frame; a dialog that focuses only a tabbable element, and so passes the frame on to its first one, still leaves the focus on the frame, with no cell selected). On a desktop the cell becomes the grid's selected cell once the focus is on it, so the next arrow moves from it; below your `desktopQuery` only the focus goes back, with no cell selected. Asked while a dialog closes, `element()` is settled again once the close is done: the focus moves to the cell (a row a refetch moved out of the drawn rows is drawn first) unless it went somewhere outside the grid. Once the grid is gone they return `false` and `null`.
24
28
  - `GroupCountNoun` — a group count's noun, `{ one, other }`, so a header reads "2 companies"; without one the count is bare.
25
29
 
26
30
  ## Writes
@@ -37,3 +41,18 @@ The spreadsheet. The door carries no client directive; every rendering file behi
37
41
  - `cellEditBaseline` — the value an edit of a cell starts from: the column's pending value when one is given, else the column's `editAccessor`, else its `accessor`.
38
42
  - `cellCopyText` — a cell's value as copied text, given its column and its baseline (from `cellEditBaseline`), which a CSV export can reuse. Empty for no value; a relation or an actor copies as its name, not its id; a select, status or multiselect copies as its options' labels, not their keys; a place, a name and a range copy as their cells write them; a list copies its items joined by commas, several values of one kind their values, the main one first.
39
43
  - `GRID_TITLE_LINK_CLASS` — the class that dresses the row-open text inside a title cell (the element carrying `data-cell-open`) as a link on its own hover: the brand colour and an underline.
44
+
45
+ ## The lab
46
+
47
+ What a grid's recorder hands your app while the lab asks for one. The lab itself, `setGridLab` and `GridLab`, is on the root door (`@viewkitjs/views`), so an app's shell can set it without loading the grid.
48
+
49
+ - `GridRecording` — one recording: `v` (1), `id`, `session` (one per page life), `startedAt`, the `GridRecordingContext` it was made in, `scrolls` (`GridScrollSample`s), `frames` (each animation frame's time), `touches` (`GridTouchSample`s), its `summary` (a `GridRecordingSummary`) and `dropped` (the samples left out past a cap, per kind). Times are in milliseconds since the recording began.
50
+ - `GridRecordingContext` — what a recording was made in: `page` (the path), `lab` (`overscan`, the rows drawn beyond each edge of the view), `device` (`ua`, `dpr`, `screen`, `viewport`, `cores`) and `grid` (`rows`, `groups`, `rowHeight`).
51
+ - `GridScrollSample` — one scroll event of the grid's own area: `[time, scrollTop, scrollLeft, handler ms, rendered (0 or 1), rows drawn, pinned (0 or 1), scrollHeight]`.
52
+ - `GridTouchKind` — what a touch sample marks: `"start"` or `"end"`.
53
+ - `GridTouchSample` — `[time, kind, x, y]` in client pixels; an `"end"` carries the finger's release speed in pixels per second as `x` and `y`.
54
+ - `GridRecordingSummary` — what a recording adds up to: `durationMs`, `scrollEvents`, `eventGapMs`, `jumpPx` and `handlerMs` (each `{ p50, p90, max }`; gaps over a second are pauses and left out), `aheadPx` (`overscan` × the row height), `jumpsOverAhead` (scroll events that moved farther than the rows drawn ahead), `frameGapMs` and `framesOver50ms`, `maxLeftPx`, `pinFlips`, `scrollHeightChanges` and `longestStillTouchMs` (the longest stretch with a finger down and no scroll event).
55
+ - `GridSpread` — a spread of one measure in a summary: `{ p50, p90, max }`, by nearest rank.
56
+ - `GRID_RECORDER_CAPS` — the most samples one recording holds, per kind: `{ scrolls: 4000, frames: 8000, touches: 2000 }`.
57
+
58
+ The recorder can't see the screen: on iOS the screen scrolls on its own while the page draws, so it measures how late the page is, not how much of the screen was blank.
@@ -7,20 +7,22 @@ Import from `@viewkitjs/views/react` in a client component: the door opens with
7
7
  Guide: [the provider](../guides/the-provider.md).
8
8
 
9
9
  - `ViewsProvider` — the provider every view reads: mount it once at your app's client root, above every view, with its components, icons, ports and conventions. It lays your atoms over the defaults, hands your `Menu` its items with every row under a disabled group already disabled, and fills in the browser's own confirm where your ports carry no `confirm`. It hands its views one context value per distinct set of inputs, so pass module-level objects: a new one on each render re-renders every view.
10
- - `ViewsProviderProps` — what the provider takes. Its optional `desktopQuery` is the media query that means a desktop, so an editor opens as a popover there and as a sheet elsewhere; hand in the one your own shell switches on. Default `DEFAULT_DESKTOP_QUERY`.
10
+ - `ViewsProviderProps` — what the provider takes. Its optional `desktopQuery` is the media query that means a desktop, so an editor opens as a popover there and as a sheet elsewhere; hand in the one your own shell switches on. Default `DEFAULT_DESKTOP_QUERY`. Its optional `sheetActions` (`ViewsSheetActionsPlace`, default `bar`) says where an editor's ✕ and ✓ stand in that sheet. Its optional `escape` (`ViewsEscapeRules`) says what Escape does in an editor of each field type on a desktop, `"keep"` or `"cancel"`, a type left out cancelling. Its optional `sayRefusals` (default false) has the grid say, through the toast port's `error`, why your app refused an edit it sent. Its optional `menus` (`ViewsMenuRoute`, default `popover`) says how the grid opens its own menus: in your `Popover` with ViewKit's rows, or through your `Menu`. Its optional `selectionBar` (`ViewsSelectionBarSettings`) says where the selection bar sits.
11
+ - `EditEscape` — `"cancel" | "keep"`: what Escape does in an edit session (`@viewkitjs/views/editors/session` hands it on too).
12
+ - `ViewsEscapeRules` — `Partial<Record<FieldType, EditEscape>>`, the provider's `escape`.
11
13
  - `DEFAULT_DESKTOP_QUERY` — `(min-width: 1024px)`: the width a desktop starts at when the provider is handed no `desktopQuery`. Where the screen can't be asked (a server render, a browser with no `matchMedia`), it is a desktop.
12
14
  - Required: `components` (your primitives, `ViewsComponents`), `icons` (your glyphs by meaning, `ViewsIcons`), `ports` (your runtime services, `ViewsPorts`), `conventions` (the `FieldConventions` of `@viewkitjs/fields` every value is read with) and `children`.
13
15
  - Optional: `atoms`, any of your own atoms, each laid over the default of its name; `messages`, your wording for the package's own messages, defaulting to `resolveViewsMessage` (the package's English); `presentation`, `(defaults: FieldPresentation) => FieldPresentation`, how your numbers, dates and durations read: given the package's defaults in the conventions' locale, return yours. It is called where a value is drawn, so your provider imports none of the display.
14
16
  - `useViews` — reads the nearest provider's value inside a view or an atom of your own. It throws an error that says where to mount one when no `ViewsProvider` is above it.
15
- - `ViewsContextValue` — what `useViews` returns: the `components` (your `Menu` wrapped to settle disabled groups), the merged `atoms`, the `icons`, the `ports` as `ViewsResolvedPorts` (`confirm` always a function), the `messages` resolver, the `conventions`, your `presentation` when you handed one, and the `desktopQuery` in force (yours or `DEFAULT_DESKTOP_QUERY`).
17
+ - `ViewsContextValue` — what `useViews` returns: the `components` (your `Menu` wrapped to settle disabled groups), the merged `atoms`, the `icons`, the `ports` as `ViewsResolvedPorts` (`confirm` always a function), the `messages` resolver, the `conventions`, your `presentation` when you handed one, and the `desktopQuery` in force (yours or `DEFAULT_DESKTOP_QUERY`); `escape` and `sayRefusals` when you handed them; and `menus`, how the grid opens its own menus (absent means `popover`); `selectionBar` when you handed it.
16
18
  - `NOOP_PORTS` — ports that do nothing, for a server render, a test or an app without a device: the toasts and haptics are empty, the clipboard writes nothing (resolving `false`) and reads `null`, and the prefs store keeps nothing. It carries no `confirm`, so the provider falls back to the browser's.
17
19
 
18
20
  ## The components map
19
21
 
20
22
  The primitives your app hands in, modelled on Base UI's shapes: a controlled `open` with `onOpenChange(open, details)`, an `anchor` rather than a trigger child on the popover and the menu, and no `asChild`. An adapter on Base UI wraps its copies thinly; one on Radix absorbs the difference. The package ships none of them and depends on neither library. The [contract](../contract.md) says what each slot promises and how to write an adapter.
21
23
 
22
- - `ViewsComponents` — the map itself, one key per name of the contract's components: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. `AppIcon` is your own icon component, taking `name` and `className`, for the glyphs a host declares (a row's icon, a binding's icon); it draws on the first paint, because rows are measured as they mount, so map its names from a static record. `Markdown` is your markdown renderer, handed the stored text whole as `source`; the package parses no markdown itself. One key is optional, `Input`: leave it out and the editors draw a plain `<input>`.
23
- - `ViewsResolvedComponents` — the map as `useViews()` hands it on: yours, with `Input` always there, your own or the plain one.
24
+ - `ViewsComponents` — the map itself, one key per name of the contract's components: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. `AppIcon` is your own icon component, taking `name` and `className`, for the glyphs a host declares (a row's icon, a binding's icon); it draws on the first paint, because rows are measured as they mount, so map its names from a static record. `Markdown` is your markdown renderer, handed the stored text whole as `source`; the package parses no markdown itself. Five keys are optional: `Input` (leave it out and the editors draw a plain `<input>`), `Command` (the command list's parts; a list reached without one throws an error naming it; with `Picker` and `menus: "menu"`, none is needed), `Picker` (a whole pick list your app draws; leave it out and the select, several-values, place and relation editors draw from `Command`), `Calendar` (the date editor's month; reached without one, it throws an error naming it; handed `DateBody`, it is never reached) and `DateBody` (a whole date body your app draws; handed one, the date editor opens it).
25
+ - `ViewsResolvedComponents` — the map as `useViews()` hands it on: yours, with `Input` always there, your own or the plain one, and `Command` and `Calendar` always there, yours or a stand-in that throws an error naming the slot when it is reached.
24
26
  - `ViewsButtonProps` — a button: its `children`, `onClick`, `disabled`, a `variant` (`default`, `ghost`, `outline`, `destructive`), a `size` (`default`, `sm`, `icon`), its `type`, a class, `aria-label` and `title`.
25
27
  - `ViewsPopoverProps` — a popover opened at an `anchor`, controlled by `open` and `onOpenChange`, placed by `side`, `align`, `sideOffset` and `alignOffset`.
26
28
  - Focus: `initialFocus` false keeps focus where it was when the popup opens, for an editor that focuses its own input (with `preventScroll`). Default true.
@@ -28,12 +30,23 @@ The primitives your app hands in, modelled on Base UI's shapes: a controlled `op
28
30
  - Look: `chrome` is `panel` (your card popover, the default) or `menu` (your menu panel's surface, for a popover that holds a list: no inset, no card width). `onPanelClick` takes a click inside the popup, `panelData` sets `data-*` attributes on it, and `style` carries what a class cannot say, such as a width that follows a cell.
29
31
  - `ViewsTooltipProps` — a tooltip around the element it wraps (`children`), showing `content`, with `side`, `align`, `delayMs` and a class. Your app mounts one tooltip provider above the views; a tooltip never mounts its own.
30
32
  - `ViewsCheckboxProps` — a checkbox: `checked`, and `indeterminate` for a box ticked partly, whose press hands `true` while `checked` is false. `onCheckedChange` hands the new value and, where your library reports it, `{ event }`, the press that changed it (a list reads its shift key for a range). `partialTone` colours the partial mark, `muted` by default or `brand` for a select-all with a live selection; with `disabled`, a class, `tabIndex` and `aria-label`.
31
- - `ViewsMenuProps` — a menu opened at an `anchor`, with no trigger child and no flyouts, controlled by `open` and `onOpenChange`, drawing its `items` and placed by `side` and `align`. On Base UI it is the menu's root, positioner and popup, the anchor handed to the positioner.
32
- - `ViewsMenuItem` — one row of a menu, as data your `Menu` draws: its `key`, `label`, `icon`, `onSelect`, `disabled` and `destructive`, a `separatorBefore`, a `shortcut` hint drawn at its end and never bound, and an `href` that makes it a link (with `onSelect` still firing). A `checked` row is checkable and closes the menu like any row. A row with `children` is a group: its rows drawn in place under its label, never a flyout, its own `onSelect`, `href` and `checked` ignored; a disabled group's rows reach your `Menu` already `disabled`.
33
+ - `ViewsMenuProps` — a menu opened at an `anchor`, with no trigger child (a group opens beside it only where it asks to and your menu can), controlled by `open` and `onOpenChange`, drawing its `items`, placed by `side` and `align`, and named by `label`, its accessible name, which every menu the package opens hands. On Base UI it is the menu's root, positioner and popup, the anchor handed to the positioner.
34
+ - `ViewsMenuItem` — one row of a menu, as data your `Menu` draws: its `key`, `label` (always words), `icon`, `onSelect`, `disabled` with an optional `disabledReason` (why, for you to show), and `destructive`, a `separatorBefore`, a `shortcut` hint drawn at its end and never bound, and an `href` that makes it a link (with `onSelect` still firing). A `checked` row is checkable and closes the menu like any row, unless it carries `keepOpen`. A row with `children` is a group: its rows drawn in place under its label, unless it carries `beside` (open them one level in), its own `onSelect`, `href` and `checked` ignored; a disabled group's rows reach your `Menu` already `disabled`, with the group's reason where they give none. Any row may carry `detail`, its current value in words, for its end. All three are hints: a menu that draws none of them keeps every group in place and every row closing.
33
35
  - `ViewsCommandParts` — the command list's parts, the shape cmdk-based copies already have: `Root` (taking `label`, `shouldFilter` false to hand filtering to the host, a scoring `filter`, `loop` to wrap the arrows, and `defaultValue`, the value of the item highlighted as the list opens, none while no item has it), `Input` (a controlled `value` with `onValueChange`, a `placeholder`, `autoFocus`, a `ref`, `onKeyDown`, and `chrome` `search` for your search row or `bare` for the input alone), `List`, `Empty`, `Group` (with a `heading`) and `Item` (a `value`, `onSelect`, `disabled`, and `chosen`, which you colour as your chosen row while the package's row inside draws the check).
36
+ - `ViewsPickerProps` — a whole pick list your app draws, its search, rows, empty row and create row: its `label` (the field's name), `items`, `multiple`, `value` (one value or `null`; several, a list), `onValueChange` (the pick, `null` for the empty row, or the whole new list on every change; nothing is saved until the editor closes), `onDone` (a pick of one is made), `empty` (the empty row's words; absent, a value of one can't be emptied), `search` (its words before anything is typed), `onCreate` (handed what was typed, returns the value it makes, which you then pick or add), `typed` (what was typed on what opened it), `autoFocus`, `form`, `computer` or `phone` (on a phone, draw no ✕, ✓ or Cancel of your own and hand every change as it is made), and for a relation `onSearch` (the editor filters or fetches: hand it every typed query and draw `items` as handed), `doing` (`searching` or `failed`), `onRetry`, `onMore`, `actions` (`ViewsPickerAction` rows after the rows) and `lead` (which held value leads, `onLead`, `label` and `makeLabel`).
37
+ - `ViewsPickerItem` — one row of a picker body, as data: its `value` and `label`, a status `slot` (draw your status badge) or a category `color` (draw your option chip), an `icon` (your glyph's name, as `AppIcon` draws it), a quieter `line`, the `group` it stands under, `disabled`, and for a relation's record a `badge` (a word telling kinds apart), a `glyph` (the record's own, unsized), an `avatarUrl` and its `kind`.
38
+ - `ViewsPickerAction` — a row of a picker body that does something rather than pick (create a record with what was typed): its `key`, `label`, an optional `icon`, and `onSelect`; picking it closes the editor, then runs it.
34
39
  - `ViewsCalendarProps` — a calendar over ISO days (`YYYY-MM-DD`): its `value` and `onChange`, `min` and `max`, a `month` (`YYYY-MM`) controlled with `onMonthChange`, a `captionLayout` of `label` or `dropdown`, the `startMonth` and `endMonth` its pickers offer, and `locale`, the conventions' locale, in which it draws its month and weekday names and starts its week (an adapter may keep its calendar's own). Your date library stays your own.
40
+ - `ViewsDateBodyProps` — a whole date body your app draws, its typed line, days, quick picks and time: its `label` (the field's name), `value` (on the local calendar, a day `YYYY-MM-DD`, a day and time `YYYY-MM-DDTHH:MM`, or `null`), `onValueChange` (every change as it is made, a typed day once it reads as one, `null` for the empty pick; nothing is saved until the editor closes), `onDone` (a pick that finishes the edit: a day on a field with no time, the empty pick), `time`, `empty`, `picks` (`ViewsDatePick`s, in order), `today` (`YYYY-MM-DD`, local), `typed` (what was typed on what opened it), `autoFocus` and `form` (`phone`: draw no ✕, ✓ or Cancel of your own, and hand every change as it is made). The editor around it keeps the draft, Tab, Escape, the save and the phone's ✕ and ✓.
41
+ - `ViewsDatePick` — a quick pick a date body offers: `today`, `tomorrow`, `next-monday` (the Monday after today, a week on when today is one) or `none`, which empties the field.
35
42
  - `ViewsCollapseProps` — a box that opens and closes its `children` with `open`, over `durationMs`, with a class and a `clipClassName` on the box that crops the content.
36
- - `ViewsSheetProps` — a phone sheet, controlled by `open` and `onOpenChange`, with a `title`, a `description`, a class, its `children`, and `snap` (`full`, `half`, `peek`, `auto`), a hint a sheet with no snap points ignores.
43
+ - `ViewsSheetProps` — a phone sheet, controlled by `open` and `onOpenChange`, with a `title`, a `label` (the title in words whenever the title is words: its accessible name, and the title of a head that takes only text), a `description`, a class, its `children`, and `snap` (`full`, `half`, `peek`, `auto`), a hint a sheet with no snap points ignores. With the provider's `sheetActions` at `head` it is handed `actions`, the editor panel's ✕ and ✓, to draw in its own head.
44
+ - `ViewsSheetActions` — the editor panel's ✕ and ✓, handed to a sheet that draws them in its head: `close`, which throws the edit away as a swipe does, and `done`, which closes it as done, absent where the body saves on its pick.
45
+ - `ViewsSheetAction` — one of them: its `label` (the accessible name) and `onPress`. The glyph is yours.
46
+ - `ViewsMenuRoute` — `"popover" | "menu"`, the provider's `menus`: how the grid opens its own menus (a column's, a footer's figure picker, a group's ⋯, Add column). `popover` (the default) draws ViewKit's rows in your `Popover`; `menu` hands your `Menu` its rows as data. The row menu and a command cell's menu always go through your `Menu`.
47
+ - `ViewsSelectionBarSettings` — the provider's `selectionBar`: `phoneQuery` (the media query under which the bar is the phone's pill; without it, wherever `desktopQuery` does not match), and `desktop` and `phone`, each a `ViewsBarPlacement`.
48
+ - `ViewsBarPlacement` — where the selection bar's fixed box sits on one form: `bottom` (a CSS length, default `calc(1rem + env(safe-area-inset-bottom))`), `zIndex` (default 50) and `className` (your own classes on the box).
49
+ - `ViewsSheetActionsPlace` — where the ✕ and ✓ stand on a phone, the provider's `sheetActions`: `bar` (the default, the panel's own bar inside your sheet) or `head` (handed to your sheet as `actions`, and no bar).
37
50
  - `ViewsInputProps` — a single-line text box: every prop of an `<input>`, `ref` included, which your element must receive, and `chrome`, `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame).
38
51
  - `ViewsAnchor` — where a floating part attaches: an element, a ref to one, a point `{ x, y }` (a context menu), or `null`.
39
52
  - `ViewsSide` — the side a floating part opens on: `top`, `right`, `bottom` or `left`.
@@ -70,7 +83,14 @@ Guide: [atoms](../guides/atoms.md).
70
83
  The pieces the rendering is built from, and your app's own pieces it cannot draw itself. Each ships as a default, drawn from your app's colours and marked with its own `data-slot`; your app swaps any of them through the provider's `atoms`, and the rest stay the defaults. A swapped atom marks itself as your app does. The [contract](../contract.md) lists their slots and states.
71
84
 
72
85
  - `DEFAULT_VIEWS_ATOMS` — the atoms every app starts with, one default per name of `ViewsAtoms`; the provider lays your `atoms` over it.
73
- - `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `Loading`, `LoadMore`, `PlatformMark` and `RowMenu`. The provider's `atoms` takes any part of it.
86
+ - `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `RelationRoles`, `Loading`, `LoadMore`, `PlatformMark`, `RowMenu`, and the panels' rows `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`. The provider's `atoms` takes any part of it.
87
+ - `ViewsChoiceRowProps` — a panel's value row: `label`, a `description` under it, a right-hand `meta` (a sample, a count; a row with one draws no check), `leading`, `trailing`, `selected`, `onClick`, `onMouseDown`, `disabled`, `role` and `aria-selected`.
88
+ - `ViewsCheckRowProps` — toggles one of many, a tick box on the left: `checked`, `onClick`, its `children`, `leading`, `trailing`, `disabled`.
89
+ - `ViewsRadioRowProps` — picks one of a set: `selected`, `label`, `onClick`, `leading`, `trailing`, `mark` (`"check"` or `"box"`), `disabled` and the `disabledReason` your `Tooltip` shows, and class hooks for the check and the label.
90
+ - `ViewsDirectionButtonProps` — a sort's direction arrow: `dir` (`"asc"` or `"desc"`) and `onClick`; a press never reaches the row around it.
91
+ - `ViewsMenuRowProps` — a drill-in row: `icon`, `label`, `value` (where the section stands), `active`, `disabled`, `onClick`.
92
+ - `ViewsToggleRowProps` — a boolean flipped in place: `icon`, `label`, `active`, `disabled`, `onClick`, and `reset` (`{ onReset }`), the way back to the reader's default.
93
+ - `ViewsPanelSearchProps` — a panel's text box: `value`, `onChange`, `onClear`, `placeholder`, `autoFocus`, `onKeyDown`, `onFocus`, `inputRef`, `leading` (`null` drops the magnifier), `suffix` and `inputMode`.
74
94
  - `ViewsListProps` — the rows' container, the inset a run of rows sits in inside a panel or a command list's group: its `children` and a class.
75
95
  - `ViewsRowContentProps` — a row's inside, all the row is inside a command list's item, which owns the element, the highlight and the keyboard.
76
96
  - What it says: a `label` (text truncates to one line, any other node is laid out in a row so it centres; `wrap` lets a long label break), a `description` line under it, a `leading` glyph (with `leadingLane` to keep its width when there is none), `trailing` content after the label, and a `detail` at its right edge in the subtle colour, such as a setting's current choice.
@@ -81,9 +101,11 @@ The pieces the rendering is built from, and your app's own pieces it cannot draw
81
101
  - `ViewsStatusMarkerProps` — an attention badge that opens its reason in a popover: its `label`, its `title` (the panel's heading and the marker's accessible name), a `slot` (`warning` by default), the `reason`, the `emptyReason` shown when there is none (the package's wording by default), and `onResolve` with its `resolveLabel`; without `onResolve` the marker is read-only.
82
102
  - `ViewsTagProps` — a category chip: its `label` and category `color`, a `leading` glyph (an option's icon, drawn by your `AppIcon`), a class, and `onRemove`, which draws a remove control, named by `removeLabel` (the package's wording by default).
83
103
  - `ViewsCommandMenuProps` — a `command` cell's verb menu: the `trigger` the cell drew (a button), the host's `items` as `FieldRowMenuItem`s, and `align`. The default is your components map's `Menu`; your app may swap in its own action menu.
104
+ - `ViewsSelectionSheetProps` — the phone's sheet of a selection's verbs, opened by the selection bar's Actions: `open`, `onOpenChange`, `title` ("3 selected"), the `verbs`, `onDelete` and `deleteLabel` for the bar's own delete, drawn last, and `busy`. Picking a row closes the sheet, then runs it.
84
105
  - `ViewsRowMenuProps` — the row's right-click menu, around the row it opens on (`children`): opened by a right-click on the row or by its ⋯, it lists an Open page row for `openHref` (a new tab), the `items` the rendering built, and a Delete row when `onDelete` is given, called with `rowId` once the confirm port says yes, with `deleteLabel` as its `subject`. A delete that rejects says so through the toast port's `error`. `onToggleSelect` flips the row's selection, for an app whose long-press selects; the default doesn't use it, and a long-press on a phone opens nothing.
85
106
  - `ViewsRowMenuItem` — one row of the row's menu, the shape a host's own row-menu items already have: a rule (`{ separator: true }`), or a row with its `label`, `icon`, `onClick`, `destructive`, `disabled` and a `shortcut` hint drawn at its end and never bound.
86
107
  - `ViewsRelationLinkProps` — where a relation chip goes: the `relation` value and the chip the display drew as `children`, for your app's own link around it. The default goes nowhere, since a relation is a fact as often as a destination.
108
+ - `ViewsRelationRolesProps` — a link's roles, drawn inside its chip after the record's name, on a `many` relation that declares `links`: the `relation` value and its `roles` in order, each its stored `value` and its `label` (the field's, else the value). Handed only when the link holds one or more. The default draws the labels in the subtle colour after a middle dot, cut before the name in a narrow cell, and names the record and every role on hover.
87
109
  - `ViewsLoadingProps` — a wait: `placement` `body` (the whole list reloading) or `footer` (more rows arriving), and the `label` read to assistive technology. The default is a plain ring, larger in the body.
88
110
  - `ViewsLoadMoreProps` — how a list asks for its next page once its end comes near: `onReveal`, and an optional `label` drawn while it waits. The default watches a sentinel past the last row, calls `onReveal` as it comes within 600px of the end of what it scrolls in (the grid's own scroll area, else the viewport), and draws your `Loading` (or the label) meanwhile.
89
111
  - `ViewsPlatformMarkProps` — a link's platform, drawn before the link: the `platform` (its key says which, its name what to call it) and a class. The default draws nothing, so a link looks plain; the package ships no brand art, so an app that wants marks draws its own.
@@ -1,6 +1,6 @@
1
1
  # `@viewkitjs/views/selection`
2
2
 
3
- Import from `@viewkitjs/views/selection` to let people pick rows of a list: the selection over the rows' visual order with a range anchor, the row checkbox, the drag down its lane, the rules a row click follows, and the rest that starts a record's read before the click. The door carries no client directive; each hook and component file behind it carries its own, and they read the provider's components and haptics. The bar a selection opens, and what its verbs do, stay your app's.
3
+ Import from `@viewkitjs/views/selection` to let people pick rows of a list: the selection over the rows' visual order with a range anchor, the row checkbox, the drag down its lane, the rules a row click follows, the rest that starts a record's read before the click, and the bar a selection opens. The door carries no client directive; each hook and component file behind it carries its own, and they read the provider's components and haptics. What the bar's verbs do stays your app's.
4
4
 
5
5
  ## The selection
6
6
 
@@ -10,9 +10,17 @@ Guide: [selection](../guides/selection.md).
10
10
  - `UseListSelectionResult` — what `useListSelection` returns: `selectedIds`, `count`, `isSelected(id)`, `anchorId`, `allSelected` and `someSelected` (some but not all, for an indeterminate box), and the verbs `toggle(id, next?)` (sets the range anchor), `toggleRange(id)` (adds the run from the anchor to `id`), `toggleMany(ids)` (selects them all, or clears them when all are selected), `selectAll()`, `clear()` (also resets the anchor) and `setSelected(ids)`.
11
11
  - `SelectionRetention` — what happens to a selected id that leaves the visual order: `"ordered"` drops it; `"external"` keeps it, for a selection across a whole query whose rows need not all be loaded. Either way the range anchor must stay visible to count.
12
12
  - `useEscapeToClear` — while `active` is true, Escape anywhere in the window calls `clear`.
13
- - `ListSelectionConfig` — what a list or table takes to be selectable (the grid's `selection`): `resetKey` (the selection clears when it changes) and `renderBar` (draws your bar from the selection and, when the renderer can write, a `ListBatchApi`), with optional `orderedIds` and `retention`.
13
+ - `ListSelectionConfig` — what a list or table takes to be selectable (the grid's `selection`): `resetKey` (the selection clears when it changes), with optional `renderBar` (draws the bar from the selection and, when the renderer can write, a `ListBatchApi`; left out, rows still tick and no bar is drawn), `orderedIds` and `retention`.
14
14
  - `ListBatchApi` — the batch write a renderer with an editing model hands your bar: `setColumnValue(rowIds, columnId, value)`, resolving to whether the write landed. The grid's resolves `false` for a column it cannot write, and skips an id whose row is not loaded.
15
15
 
16
+ ## The bar
17
+
18
+ - `SelectionBar` — the bar a selection opens, portalled to the body and placed by the provider's `selectionBar`. On a desktop, an island: the count chip (a press clears the selection; its tooltip names Escape), the first four verbs, the trash when `onDelete` is handed, a hairline and More, always drawn, holding the rest (a group or an options verb opening its rows beside it). On a phone, a pill reading the count, Actions and ✕; Actions opens the `SelectionSheet` atom. It draws nothing while `count` is zero.
19
+ - `SelectionBarProps` — what `SelectionBar` takes: `count`, `onClear`, `verbs` (`SelectionVerb`s, in order), optional `busy` (disables every control), `onDelete` (the bar's own verb, the trailing trash; never a verb in `verbs`) and `deleteLabel` (the trash's name; default the `views.selection.delete` message).
20
+ - `SelectionVerb` — one verb, as data: `{ kind: "action" }` with a `SelectionVerbItem`'s fields; `{ kind: "group", label, icon?, disabled?, items }`, a button opening a menu of `SelectionVerbItem`s; or a `SelectionOptionsVerb`.
21
+ - `SelectionVerbItem` — an action: `label`, optional `icon` (your glyph), `onClick`, `destructive` (the danger colour) and `disabled`.
22
+ - `SelectionOptionsVerb` — one field set on every selected row: `{ kind: "options", label, icon?, disabled?, options, onSelect }`, its `options` `PickerOption`s drawn as the badges a cell shows, `onSelect` handed the value picked. It closes, then runs.
23
+
16
24
  ## Picking rows with the pointer
17
25
 
18
26
  - `selectFromClick` — the modifier click on a row: takes the click, the row's id and the selection's `toggle` and `toggleRange`. Cmd or Ctrl toggles the row, Shift extends the range, and it returns `true` when it handled the click, so your handler stops before opening the row.
@@ -24,23 +24,25 @@ Guide: [the provider](../guides/the-provider.md).
24
24
  - `VK_INTERNAL` — the grid's own variables, set and read by the grid alone: `--vk-drag-shift`, a header cell's offset while its column is dragged. Prefixed because they share the global namespace, and not public: your app neither sets nor reads them, and they may change in any release.
25
25
  - `VkInternal` — one member of `VK_INTERNAL`.
26
26
  - `VK_INTERNAL_FAMILIES` — the grid's internal variable families, a prefix with one variable per key after it: `--vk-col-w-<id>`, one column's resolved width, set on the grid's root for every visible column. Not public, like `VK_INTERNAL`.
27
- - `COMPONENT_NAMES` — the primitives your app hands in through the provider: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command`, `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown` ([the components map](../contract.md#the-components-map)).
27
+ - `COMPONENT_NAMES` — the primitives your app hands in through the provider: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Collapse`, `Sheet`, `AppIcon` and `Markdown` ([the components map](../contract.md#the-components-map)).
28
28
  - `ComponentName` — one member of `COMPONENT_NAMES`.
29
- - `OPTIONAL_COMPONENT_NAMES` — the primitives your app may leave out, each with a plain default the provider fills: `Input` ([the components map](../contract.md#the-components-map)).
29
+ - `OPTIONAL_COMPONENT_NAMES` — the primitives your app may leave out: `Input` (a plain default), `Command` (reached without one, it throws an error naming it), `Picker` (without one, the lists draw from `Command`), `Calendar` (reached without one, it throws an error naming it) and `DateBody` (without one, the date editor draws its own around `Calendar`) ([the components map](../contract.md#the-components-map)).
30
30
  - `OptionalComponentName` — one member of `OPTIONAL_COMPONENT_NAMES`.
31
- - `ATOM_NAMES` — the pieces the rendering is built from, and the pieces of your app's own it cannot draw itself (a command cell's verb menu, the row's right-click menu, where a relation goes, a wait, how a list asks for more). Each ships as a default, and your app swaps any of them through the provider's `atoms` ([the atoms](../contract.md#the-atoms)).
31
+ - `ATOM_NAMES` — the pieces the rendering is built from, and the pieces of your app's own it cannot draw itself (a command cell's verb menu, the row's right-click menu, where a relation goes, a wait, how a list asks for more), and the panels' rows. Each ships as a default, and your app swaps any of them through the provider's `atoms` ([the atoms](../contract.md#the-atoms)).
32
32
  - `AtomName` — one member of `ATOM_NAMES`.
33
33
  - `ATOM_SLOTS` — the `data-slot` values the default atoms mark themselves with, prefixed like the grid's (`vk-row`, `vk-tick`, `vk-status`, `vk-row-menu` …) ([the atoms](../contract.md#the-atoms)).
34
34
  - `AtomSlot` — one member of `ATOM_SLOTS`.
35
35
  - `EDITOR_SLOTS` — the `data-slot` values the editor panel marks its parts with, prefixed like the grid's (`vk-editor-panel`, `vk-editor-bar`, `vk-editor-refusal`) ([the editor panel](../contract.md#the-editor-panel)).
36
36
  - `EditorSlot` — one member of `EDITOR_SLOTS`.
37
+ - `SELECTION_SLOTS` — the `data-slot` values the selection bar marks its parts with, prefixed like the grid's (`vk-selection-bar`, `vk-selection-pill`, `vk-selection-chip`) ([slots](../contract.md#slots)).
38
+ - `SelectionSlot` — one member of `SELECTION_SLOTS`.
37
39
  - `ATOM_STATES` — the default atoms' states: `chosen`, `disabled`, `muted`, `checked` and `open` are flags present when true, `status` carries the status slot's name and `platform` a link's platform key ([the atoms](../contract.md#the-atoms)).
38
40
  - `AtomState` — one member of `ATOM_STATES`.
39
41
  - `PORT_NAMES` — the runtime services your app hands in through the provider: `toast`, `haptics`, `clipboard`, `viewPrefs` and `confirm` ([Ports](../contract.md#ports)).
40
42
  - `PortName` — one member of `PORT_NAMES`.
41
- - `ICON_NAMES` — the glyphs the rendering asks your app for, by what they mean, never by a library's name: the field types, who did it, the actions, navigation and order, the figures and the grid's menus. Your app maps each to its own icon component ([Icons](../contract.md#icons)).
43
+ - `ICON_NAMES` — the glyphs the rendering asks your app for, by what they mean, never by a library's name: the field types, who did it, the actions, navigation and order, the figures, the grid's menus and the panels' (`search`, `reset`). Your app maps each to its own icon component ([Icons](../contract.md#icons)).
42
44
  - `ViewsIconName` — one member of `ICON_NAMES`.
43
- - `MESSAGE_NAMESPACES` — the four namespaces every visible string the package owns is keyed under: `views.grid`, `views.editors`, `views.menus` and `views.display`.
45
+ - `MESSAGE_NAMESPACES` — the six namespaces every visible string the package owns is keyed under: `views.grid`, `views.editors`, `views.menus`, `views.display`, `views.selection` and `views.panels`.
44
46
  - `ViewsMessageNamespace` — one member of `MESSAGE_NAMESPACES`.
45
47
  - `ViewsMessage` — a message the package emits: its `key` and, where it has any, the `values` a resolver may interpolate (`{ key: "views.editors.tag-remove", values: { label } }`), never a sentence. The union is closed, so a new key is a compile error in every exhaustive resolver that has not worded it. A string `@viewkitjs/fields` already keys stays a fields message. The keys and their values are listed in [the contract](../contract.md#message-keys).
46
48
  - `ViewsMessageKey` — the key of a `ViewsMessage`: the union of every message key.
@@ -65,13 +67,15 @@ A column is plain data: what a list shows in one place for every row, how it rea
65
67
  - Per view: `defaultHidden`, `grid` (`minWidth`, `maxWidth`), `card.zone` (`ListCardZone`), `list` (the rows view's `hidden`, `track`, and the title cell's `subtitle`, `avatar` and `inlineActions`).
66
68
  - Writing: `editable`, `clearable`, `reasons` (full sentences for why an edit or a clear is absent, shown by the refusal and by a settings readout), `marker` (a marker boolean's badge `label`, panel `title` and per-row `reason`), `custom` (a derived value, `{ from }` completing "Computed from …"), `command` (changes only through the entity's verbs; the cell opens the verb menu).
67
69
  - The field: `field` (the definition the column presents, which the write gate asks to accept a value) and `binding` (how that field reads and writes this row). `columnFrom` sets both.
70
+ - A part: `partOf` (`ListColumnPartOf`), on a column the grid derives to show one part of another column's value (its `parts`); you never declare it.
71
+ - `ListColumnPartOf<Row>` — which part of which column's value a part column shows: the whole column's `column` id, the `part` (`countryCode`, `given`, `low`), the whole column's `field`, and `read(row)`, the whole value as stored on a row (the whole column's `editAccessor`, else its `accessor`).
72
+ - `coerceWrite` — a value coerced into a column's write shape by its type before any field is asked: a boolean read from its spellings, an email or a link trimmed and checked, several values split from text; `{ ok, value }` or `{ ok: false, reason }`.
68
73
  - `ListColumnType` — a column's type: a field's value type (a rollup or formula column is its result's type), or `title`, the one column role, for the text a row is called.
69
74
  - `fieldTypeOf` — the storage type behind a column: a bound column answers with its field's value type, a field-less one with its own `type`, and a `title` or untyped column reads as `text`. The format knobs and the query rules are keyed by it.
70
75
  - `temporalKindOf` — whether a column's dates are calendar days (`date`) or instants (`datetime`), read from `fieldTypeOf`.
71
76
  - `RenderedValue` — what the grid hands a custom `render` beside the row: `value`, the column's figure as its `accessor` reads it, and `code`, the currency that figure is in. A custom money cell draws that reading and converts nothing.
72
77
  - `ListColumnOption` — one option of a select, status or multiselect column: its `value`, and optionally its `label`, its status `slot`, its category `color`, its stage `mark` (when the option is a position on a ladder, drawn in place of the plain dot) and `archived` (out of every picker, still drawn on a row that holds it).
73
78
  - `ListSelectColor` — an option's category colour: one of the design palette's category hues.
74
- - `ListStatusSlot` — a status slot from the design palette, as an option or a cell action names it.
75
79
  - `ListRelationValue` — one relation value, already resolved by your host: the contract's `RelationValue` (`id` compared and committed but never shown, `label` shown, sorted and copied, `entity` handed back when the chip is opened, `avatarUrl`) plus an optional per-value `icon`, for a column whose rows point at different kinds. The grid never turns an id into a label itself.
76
80
  - `ListCellAction` — a button drawn in a cell: its `id`, an `icon` for the row, and optionally a `label`, an `onClick` handed the row and the click, and a `status` slot that tints it.
77
81
  - `ListCardZone` — where a column lands on a card: `title`, `chips`, `figures`, `footer` or `body`. The board's type defaults decide it for almost every column; `card.zone` overrides it. `body` is prose, never a default, and draws only on a card laid out roomy enough for a sentence.
@@ -112,7 +116,6 @@ What the machinery may do with each column type, declared once per type so a new
112
116
  - `GridPasteKind` — how a pasted clipboard cell becomes a commit: `text`, `option` (the pasted text matched against an offered option's label or key, exact before ignoring case, an in-grid copy landing on the exact option it copied, a label two options share refused), `number`, `date`, `boolean`, `relation` (the pasted label matched against the candidates, committing the id), `list` (the text split into several values, each read as an `option` is on a column of options), `range` (an in-grid pair, or text read as a range is written: "11–50", "10,001+", "up to 50"), or `none` (the type refuses paste).
113
117
  - `GridValueKind` — what a written value must look like for a type: `any`, `email`, `url`, `boolean`, `relation` or `list`. `gridNormalizeWrite` holds a value to it.
114
118
  - `gridPasteKind` — how a paste becomes this column's value. A `multiple` column pastes as a `list` when it presents a field of a type that keeps several values, and takes no paste otherwise; any other column answers with its type's rule. Returns `null` for a column with no type.
115
- - `resolveGridRelation` — reads a raw relation value as a `ListRelationValue`, filling in the column's default kind (`relation.entity`) where the value names none; a value's own `entity` wins. Returns `null` for a value that is not a relation.
116
119
  - `gridRelationSource` — the candidates the relation picker offers for a column: its `relation.source`, or a static list of its `relation.options`. Given an `entityIcon` resolver, each candidate without an icon of its own wears its kind's glyph, both in a static list and in each page a remote search returns; without one, the candidates come back untouched.
117
120
 
118
121
  ## What may be done to a column
@@ -151,7 +154,7 @@ Three layers decide a write, and each may only take away from the one before: th
151
154
  What a person changes about the columns (which are shown, in what order, at what width) is a `ListColumnState`, stored by your host and handed back to the grid.
152
155
 
153
156
  - `ListColumnState` — a person's columns for one view: `widths` by column id, `hidden` ids, `visible` ids (columns hidden by default that they turned on), `order`, and `breaks` (the board only: ids that start a new line on a card; present, even empty, is their own layout). The grid ignores `breaks`.
154
- - `ListColumnItem` — one column as a list that shows and hides columns reads it: `id`, `label`, `icon`, `hidden`, `hideable`, and `fixed` for a column a saved view cannot hide or reorder.
157
+ - `ListColumnItem` — one column as a list that shows and hides columns reads it: `id`, `label`, `icon`, `hidden`, `hideable`, `fixed` for a column a saved view cannot hide or reorder, and `partOf` for a part column: its whole column's id, its part and the part's word ("Country"), which an add-column drills into.
155
158
  - `ListColumnsConfig` — a view's columns with what may be done to them: the `items`, `onToggleHidden`, `onReorder`, and optionally `onReset` and `dirty`. The grid's "+ Add column" lists the hidden ones from it, and a host's own add-column (`renderAddColumn`) is handed the same.
156
159
  - `columnHideable` — whether a column can be hidden: every column but the `title`.
157
160
  - `columnDefaultHidden` — whether a column is hidden until asked for, in the view asking: the rows view (`viewId` `"list"`) reads `list.hidden` when the column states it; every other view reads `defaultHidden`.
@@ -160,18 +163,16 @@ What a person changes about the columns (which are shown, in what order, at what
160
163
  - `resolveColumnOrder` — the declared columns in a stored order: the ids the order names first (an unknown id dropped), and each column the order leaves out placed after its nearest declared neighbour that is placed. An empty order returns the declaration.
161
164
  - `resolveVisibleColumns` — the columns a view draws: in the state's order, without the hidden ones, and never none (the first column stays when every column is hidden).
162
165
  - `resolveColumnWidths` — each visible column's width by id: its stored width, held to its bounds, or its declared `width`.
163
- - `clampColumnWidth` — a width held between a column's `grid.minWidth` (default `LIST_DEFAULT_MIN_WIDTH`) and its `grid.maxWidth`, rounded to a whole pixel.
164
- - `LIST_DEFAULT_MIN_WIDTH` — the narrowest a column can be dragged when it states no `grid.minWidth`: 60 pixels.
165
- - `computeMinWidth` — the width a set of columns needs: their widths summed, plus the gutter you pass.
166
+ - `clampColumnWidth` — a width held between a column's `grid.minWidth` (60 pixels when it states none) and its `grid.maxWidth`, rounded to a whole pixel.
166
167
  - `ListDensity` — the density every view shares: `compact`, `default` or `spacious`. Each view spends it its own way; the grid scales its pixels, the rows views widen their padding.
167
168
  - `prettifyOptionValue` — a stored code made readable: underscores and hyphens become spaces and each word starts with a capital (`on_hold` reads `On Hold`).
168
169
 
169
170
  ## What a saved view places
170
171
 
171
172
  - `columnManagedByView` — whether a saved view can store a column's filters, sorts and totals: only a column that presents a field.
172
- - `columnPlacedByView` — whether a saved view can place a column (its position, width and visibility): a column that presents a field, or a computed (`custom`) column, which the view stores under its id. A computed column still never filters, sorts, groups or totals.
173
+ - `columnPlacedByView` — whether a saved view can place a column (its position, width and visibility): a column that presents a field, a computed (`custom`) column, which the view stores under its id, or a part column (`partOf`), placed as its whole is. A computed column still never filters, sorts, groups or totals.
173
174
  - `VIEW_FIELDLESS_FILTER_REASON` — the English sentence for why a saved view cannot filter on a column that presents no field.
174
- - `resolveViewColumnOrder` — the column ids in the order a saved view draws them: the columns the view places take the view's requested order among their own slots (an unknown or repeated id dropped); a field column it does not name follows the ones it does; a computed column it does not name, and every column it cannot place, keeps its declared slot.
175
+ - `resolveViewColumnOrder` — the column ids in the order a saved view draws them: the columns the view places take the view's requested order among their own slots (an unknown or repeated id dropped); a field column it does not name follows the ones it does; a computed column it does not name, and every column it cannot place, keeps its declared slot; a part column it does not name sits right after its whole.
175
176
  - `baseColumnOrder` — the complete order a Move or a header drag rewrites, which is the order the grid draws: `resolveViewColumnOrder` on a saved view, `resolveColumnOrder` off one. Returns column ids.
176
177
 
177
178
  ## Sorting and grouping
@@ -209,8 +210,7 @@ Mistakes a column declaration can make that nothing else catches, returned as li
209
210
  ## The row icon
210
211
 
211
212
  - `ListRowIconAccessor` — what a list declares as `rowIcon` for the leading glyph in each row's title cell: a function from a row to an icon name for the neutral default, a `ListRowIcon` to tint it, or `null` to draw none for that row.
212
- - `ListRowIcon` — a row icon as a descriptor: `icon`, your app's own name for the glyph, which your `AppIcon` draws, and an optional `tone`. The grid owns its size and colour.
213
- - `ListRowIconTone` — a row icon's tint: a status slot, asked for by name, because a coloured row icon says something about state. Without one the glyph draws in the secondary text colour.
213
+ - `ListRowIcon` — a row icon as a descriptor: `icon`, your app's own name for the glyph, which your `AppIcon` draws, and an optional `tone`, a status slot asked for by name, because a coloured row icon says something about state. Without one the glyph draws in the secondary text colour. The grid owns its size and colour.
214
214
  - `normalizeRowIcon` — reads either answer a `ListRowIconAccessor` gives as a `ListRowIcon`: a bare name becomes `{ icon }`, a descriptor stays as it is, and `null` stays `null`.
215
215
 
216
216
  ## Render counting
@@ -255,7 +255,7 @@ A binding says how one field reads and writes on one entity's row. Your app decl
255
255
 
256
256
  Every surface prepares a commit the same way before it sends anything. Both functions are pure, take an optional surface last (whether it is writable at all, the sentence it refuses in, and your conventions, `DEFAULT_CONVENTIONS` when it states none), and word every refusal through the conventions' messages.
257
257
 
258
- - `prepareFieldWrite` — prepares one commit: takes the binding, the row and the commit, and returns a `PreparedFieldWrite`. It refuses when the surface is not writable (the surface's sentence, else `field.cannot-edit`) or the binding is not (the field's own reason, else `field.cannot-edit`). It then judges the commit (`acceptFieldCommit`, with the unit's options, the binding's `region` for this row and, for a phone, a url, a multiselect or a relation, the value stored before the edit, so a closed multiselect keeps the values it already holds and a relation link the role it was stored with), runs the binding's write, refuses a skip with its reason (else `field.cannot-save`), and judges the stored value (`acceptStoredFieldValue`). A number, percent, currency or datetime commit is a composite, so its write must say the stored value, or the result is `field.stored-value-required`. Only `body` is ever sent.
258
+ - `prepareFieldWrite` — prepares one commit: takes the binding, the row and the commit, and returns a `PreparedFieldWrite`. It refuses when the surface is not writable (the surface's sentence, else `field.cannot-edit`) or the binding is not (the field's own reason, else `field.cannot-edit`). It then judges the commit (`acceptFieldCommit`, with the unit's options, the binding's `region` for this row and, for a phone, a url, a multiselect or a relation, the value stored before the edit, so a closed multiselect keeps the values it already holds and a relation link the role and roles it was stored with), runs the binding's write, refuses a skip with its reason (else `field.cannot-save`), and judges the stored value (`acceptStoredFieldValue`). A number, percent, currency or datetime commit is a composite, so its write must say the stored value, or the result is `field.stored-value-required`. Only `body` is ever sent.
259
259
  - `prepareFieldRestore` — prepares the restore of a history entry: takes the binding, the row, the snapshot and the value it expects to find, and runs the same surface gate. A binding with no history is refused with `field.history-unavailable`, and a restore that skips with its reason (else `field.restore-refused`). A restore that names a stored value passes the stored-value gate; one that does not keeps the snapshot as its stored value.
260
260
  - `PreparedFieldWrite` — what both return: `{ ok: true, body, storedValue }`, with an optional `settlement`, the binding's account of what the write achieves (`requested` when the body lands locally and a provider still has to accept it; the transport's result may upgrade it to `confirmed`), or `{ ok: false, reason }`.
261
261
  - `FieldWriteContext` — how a write arrived: `{ kind: "commit" }`, or `{ kind: "restore", expected }`, a history restore that names the value it expects and is refused once the row has moved on.
@@ -288,7 +288,7 @@ The types a relation's candidates are built from. A binding's `relation` names t
288
288
  A `command` field changes only through its entity's verbs: a transition that carries rules of its own (a reason, an end date) cannot be a picker. Every surface opens the same verb menu instead of an editor, and your app supplies the verbs. The [contract](../contract.md) names the menu each surface draws.
289
289
 
290
290
  - `FieldMenus` — field key to the verbs a row offers instead of an editor, resolved per row so the list follows the record's state. `GridTable` takes it as `commands`; a `command` column with no verbs wired is a read-only badge, never an empty menu.
291
- - `FieldRowMenuItem` — one verb: its `label`, its `onClick`, and optionally an `icon`, `destructive` and `disabled`.
291
+ - `FieldRowMenuItem` — one verb: its `label`, its `onClick`, and optionally an `icon`, `destructive`, `disabled` and `disabledReason` (why it can't be used now).
292
292
 
293
293
  ## Edit cores and number editing
294
294
 
@@ -471,7 +471,6 @@ One Filter panel row per relation the list's source can look across, under the s
471
471
  - `FarValues` — the far values a host hands as `farValues`, keyed by `farPathOf`: `values`, each path's values; optionally `labels`, each path's values to their names; and `onWanted(path)`, called when a named far field's row opens, so the host can fetch its values.
472
472
  - `farPathOf` — a far field's path, as the host keys its values: the relation's key (itself a two-hop path, `a.b`, for a rollup's second hop), `FAR_PATH_SEPARATOR` and the far field's key, such as `deals.owner`.
473
473
  - `FAR_PATH_SEPARATOR` — `.`, what separates a far path's hops and its far field; a field key never holds one.
474
- - `RELATED_RECORDS_SECTION` — `"Related records"`, the section every relation row sits under.
475
474
  - `relationFilterKey` — a Related records row's key, from the relation's field key: the key with `relation:` before it.
476
475
  - `relationFieldKeyOf` — the relation's field key, back from a Related records row's key; a key without the prefix comes back as it is.
477
476
 
@@ -518,9 +517,8 @@ A list keeps its preferences in separate buckets, by what each follows. The layo
518
517
  - `StoredViewLayout` — what is stored for one view: only the keys someone set. A key that is absent follows the reader's default, so a key is written only where the view means to differ.
519
518
  - `ListLayoutBucket` — a list's layouts, `{ views }`, the stored layout of each view by view id.
520
519
  - `EMPTY_LAYOUT_BUCKET` — a layout bucket with no views.
521
- - `LIST_LAYOUT_DEFAULTS` — the shipped layout: no column state, the default density, the row icon on and every other switch off.
522
520
  - `layoutKey` — the key a list's layout bucket is stored under: `list:<listKey>:layout`.
523
- - `readViewLayout` — resolves one view's layout from the bucket, key by key: a stored value wins (a stored `false` included), vertical borders fall to the reader's defaults, the rest to `LIST_LAYOUT_DEFAULTS`. The calendar's and the board's keys appear only when stored.
521
+ - `readViewLayout` — resolves one view's layout from the bucket, key by key: a stored value wins (a stored `false` included), vertical borders fall to the reader's defaults, the rest to the shipped layout: no column state, the default density, the row icon on and every other switch off. The calendar's and the board's keys appear only when stored.
524
522
  - `writeViewLayout` — patches one view's stored layout and returns a new bucket, every other view untouched. The patch lands on what is stored, never on the resolved layout; vertical borders set to the reader's default and any key set to `undefined` are dropped, so the view follows the default again.
525
523
  - `ListDefaults` — the reader's own defaults, which every view without an answer of its own follows: whether a table draws rules between its columns (`verticalBorders`).
526
524
  - `LIST_DEFAULTS_KEY` — the key the reader's defaults are stored under, `list:defaults`, one per person across devices.
@@ -528,20 +526,28 @@ A list keeps its preferences in separate buckets, by what each follows. The layo
528
526
  - `ListMoneyBucket` — the reader's money readings for one list, `{ gridCurrencies }`, by field key: one per list, so a pick in a money column's header means the same on every view.
529
527
  - `EMPTY_MONEY_BUCKET` — a money bucket with no readings, frozen.
530
528
  - `moneyKey` — the key a list's money bucket is stored under: `list:<listKey>:money`.
531
- - `ListFieldFormatPrefs` — how one field reads, the host's shared answer for every view and every member: decimals, currency, date style, duration style, whether a date shows its time, option colours and percent display. The flat maps of `ListViewPrefs` are this shape spread out by field key.
532
529
  - `hoistLegacyPrefs` — reads a flat preferences blob into a layout bucket, `{ layout }`: the columns, density and five switches it carries go to the `table` view (a key it lacks stays unset), and the `list` view starts empty. Filters, sort, grouping and formats are left where they are. It is pure, so a host may run it on every read and store the bucket only once the person changes something.
533
530
 
534
531
  ## The view rules
535
532
 
536
533
  A saved view's filter is a tree of rules keyed by field key; the Filter panel edits its root level as `ListFilterRule`s keyed by column id. These convert between the two and read a list's rows the way a view names them. With `parts: true`, a rule on one part of a value is edited by its own row, under its part key (`partKey`).
537
534
 
535
+ `filterPanelFromTree` and `treeFromFilterPanel` are the one conversion between a panel and a tree, and the quick values read and write through the same one. A root rule is drawn on a row only when writing the row's rule back gives the same rule; everything else stays in the state's `rest`, whole, so a round trip loses no rule. A between with an end still empty keeps it empty (`null`), so it filters nothing until both ends are in.
536
+
537
+ - `FilterPanelState` — a filter tree as a panel edits it: the root's `op`, one rule per row in `rules` (a column's whole value under its id, a part row's under its part key), and every root item no row draws in `rest`, in its order: and/or/not groups, relation rules, a second rule on a row already drawn, and a rule no row can show.
538
+ - `filterPanelFromTree` — reads a tree into a `FilterPanelState` over a list's columns, part rows included with `parts: true`.
539
+ - `treeFromFilterPanel` — the tree a `FilterPanelState` says: the rows' rules in column order, then the rest. A rule that asks nothing (none ticked, yes and no both ticked) writes nothing, nor does a key no row names. Reading the tree it writes gives the same state.
540
+ - `QuickValues` — a quick-filter panel's picks by field key: an option's codes, a yes/no field's `"true"` or `"false"`.
541
+ - `QuickValueField` — a field a quick-filter panel offers: its key, and the type its value is read as, one whose rule picks options.
542
+ - `quickValuesFromTree` — the picks a quick-filter panel draws: each offered field's root rule that picks options, as its values.
543
+ - `withQuickValues` — the tree with the offered fields' picks written as ordinary root rules, a field with none picked left with none; every other item kept, a rule on an offered field the panel can't show (an `is_none_of`) among them.
544
+
538
545
  - `fieldKeyOf` — the key a column is known by off the grid: its field's key, or its own id when it has no field.
539
- - `fromListFilterRule` — converts a panel rule into a view's rule for one field key and field type, the part it reads when given one. Returns `null` for a rule that asks nothing: options with none ticked, or a yes/no field with both ticked.
546
+ - `fromListFilterRule` — converts a panel rule into a view's rule for one field key and field type, the part it reads when given one. Returns `null` for a rule that asks nothing: options with none ticked, or a yes/no field with both ticked. A between's end still empty stays `null`, and an operator that takes no value (is empty, is not empty) stores `null`.
540
547
  - `toListFilterRule` — converts a view's rule into the panel rule that edits it, or `null` when no editor can show it: a place, a derived field's raw type, an operator its editor does not offer. A rule on one part of a value maps only with `parts: true`, to a checklist for a part that opens on `is_any_of` (a place's country) and to text otherwise.
541
- - `rootRulesByColumn` — the root rules the panel can edit, by column id (and part key, with `parts`). Groups, relation rules and rules on a field no column carries are left out.
542
- - `withRootRuleState` — the tree with its root rules replaced by the panel's state. Groups, relation rules and every rule no panel row can name are kept as they are, never cleared.
543
- - `withRootRule` — the tree with one column's root rule, or its rule on one part, replaced, or dropped when handed `null`; groups, relation rules and rules the row never showed stay.
544
- - `rootRelationRules` — the root relation rules, by relation field key: what the panel's related-records rows edit.
548
+ - `rootRulesByColumn` — the root rules the panel can edit, by column id (and part key, with `parts`). Groups, relation rules, set-aside rules and rules on a field no column carries are left out.
549
+ - `withRootRule` — the tree with one column's root rule, or its rule on one part, replaced, or dropped when handed `null`; groups, relation rules, set-aside rules and rules the row never showed stay.
550
+ - `rootRelationRules` — the root relation rules, by relation field key: what the panel's related-records rows edit. A set-aside one is left out, and `withRootRelationRules` keeps it.
545
551
  - `withRootRelationRules` — the tree with its root relation rules replaced by the ones given, every other rule and group untouched.
546
552
  - `viewReaderFrom` — builds the `ViewFieldReader` a view reads a list's rows through, from its columns and the decimals map (by field key). It reads what the cell draws, so a filter, a sort and a group agree with the column on screen; a column that draws itself is read through its edit accessor. Decimals come from the map or the column's format, and a number's currency from the column.
547
553
 
@@ -549,11 +555,10 @@ A saved view's filter is a tree of rules keyed by field key; the Filter panel ed
549
555
 
550
556
  One part of a value can have a row of its own in the Filter, Sort and Group menus: "Location · Country", "Name · Given name". A host turns these rows on with `parts: true`; the tables say which parts of which types get one.
551
557
 
552
- - `PART_KEY_SEPARATOR` — what joins a row's id and its part in a part key: `::`.
553
- - `partKey` — a part row's key: a column id (Filter) or a field key (Sort, Group), the separator, then the part.
558
+ - `partKey` — a part row's key: a column id (Filter) or a field key (Sort, Group), `::`, then the part.
554
559
  - `parsePartKey` — splits a key at its last separator: `{ id }` for a whole value, `{ id, part }` for a part.
555
- - `FILTER_PART_ROWS` — the parts each type offers a Filter row for, in their order: a place's country, region, city and postal code; a name's given and family name.
556
- - `SORT_PART_ROWS` — the orders each type offers beyond sorting by the whole value: a place by city, region or country; a name by family or given name.
560
+ - `FILTER_PART_ROWS` — the parts each type offers a Filter row for, in their order: a place's country, region, city and postal code; a name's given and family name; a range's low and high end, each a number row.
561
+ - `SORT_PART_ROWS` — the orders each type offers beyond sorting by the whole value: a place by city, region, country or postal code; a name by family or given name; a range by its low or its high end.
557
562
  - `GROUP_PART_ROWS` — the orders each type offers beyond grouping by the whole value: a place by city, region or country.
558
563
  - `partWord` — a part's word ("Country", "Given name") in the host's messages, or undefined for a part no table lists. Messages default to `resolveViewsMessage`.
559
564
  - `partLabel` — a part row's label, the field's label and the part's word through `views.menus.part-row`; a part with no word shows its own name. Messages default to `resolveViewsMessage`.
@@ -569,8 +574,6 @@ Guide: [the grid](../guides/the-grid.md).
569
574
  A column's footer shows one figure, the pick the reader made from the ones the column offers. A list whose rows come a page at a time (a source list) has its figures counted by the database instead; `SourcedAggregates` tells these functions which ones it answered.
570
575
 
571
576
  - `aggregateLabel` — a pick's name, through `views.grid.figure`. Messages default to `resolveViewsMessage`.
572
- - `LIST_AGGREGATE_LABELS` — every pick's name but `none`, in the package's English. A grid words them through `aggregateLabel` with the host's messages.
573
- - `gridColumnIsNumericAgg` — says whether a column totals as numbers: it declares a figure to total (`aggAccessor`) or holds a number, a percent or money.
574
577
  - `aggregateOptions` — the picks a column offers, `none` first. A numeric column offers sum, average, min, max and count; a percent never sums, and offers ratio only when the column carries its two parts; any other column offers count, filled and unique. On a source list it offers what the database can answer: count everywhere, and the numeric picks where it can total the column. A column that names its picks (`footerKinds`) offers only those.
575
578
  - `resolveAggregateKind` — the pick a column's footer shows: the reader's, when the column offers it; else ratio for a ratio column; else the column's declared default, when offered (on a source list, only when the database totalled it); else `none`.
576
579
  - `computeAggregate` — a pick's figure over the rows in hand, or `null` for nothing to show. Count is the rows; filled and unique read a place, a name and a phone by their text, and several values as a set; ratio is sum over sum as a whole percent, `null` on an empty denominator; the numeric picks skip blanks and are `null` over no values.
@@ -598,7 +601,7 @@ A board or calendar card is laid out in zones: the title, a row of chips, a stri
598
601
 
599
602
  ## A group's figures
600
603
 
601
- A source list holds a page, not the list, so its footer and its group headers read figures the database counted over the whole group. Four numbers per totalled key, the sum, the count of values present, the smallest and the largest, answer every pick the database can and combine exactly when parts fold into one group. These names import nothing, so a server may use them.
604
+ A source list holds a page, not the list, so its footer and its group headers read figures the database counted over the whole group. Four numbers per totalled key, the sum, the count of values present, the smallest and the largest, answer every pick the database can and combine exactly when parts fold into one group. These names are `@viewkitjs/fields/query`'s own, free of React, so a server may use them.
602
605
 
603
606
  - `FigureKind` — the footer picks, as `ListAggregateKind` names them.
604
607
  - `ColumnFigure` — one key's four numbers: `sum`, `count`, `min` and `max`, a `null` meaning no value.
@@ -615,8 +618,11 @@ A source list holds a page, not the list, so its footer and its group headers re
615
618
  Guide: [the grid](../guides/the-grid.md).
616
619
 
617
620
  - `ListGroup` — one group of rows, already filtered, sorted and grouped by the host: its `key`, its `label` (`null` for none), its `items` and, when the database counted them, its `figures` over the whole group.
618
- - `OrderMode` — how groups are ordered: `lifecycle` (the order the host states), `count` (most rows first), `name`, or `manual` (the reader's stored positions, which only a source list orders by; `sortGroupEntries` treats it as `name`).
619
- - `OrderDir` — `asc` or `desc`.
620
- - `OrderChoice` — a mode and a direction, `{ mode, dir }`.
621
+ - `OrderChoice` — a mode and a direction, `{ mode, dir }`: fields' `BucketOrderMode` (`lifecycle`, the order the host states; `count`, most rows first; `name`; or `manual`, the reader's stored positions, which only a source list orders by and `sortGroupEntries` treats as `name`) and `SortDirection` (`asc` or `desc`).
621
622
  - `defaultDirFor` — a mode's natural direction, for seeding a new pick: `desc` for `count`, `asc` for the others.
622
623
  - `sortGroupEntries` — sorts `[key, rows]` entries by an `OrderChoice` and returns a new array. It takes the lifecycle positions (a key without one sorts after), a label for each key and the key of the uncategorised group, which always sorts last; ties fall back to the label.
624
+
625
+ ## The grid's lab
626
+
627
+ - `setGridLab` — sets, for every grid on the page, what an app turns on to measure a grid on a device, or clears it with `null`. It takes a `GridLab`. It is on this door, beside the model, so an app's shell can set it without loading the grid.
628
+ - `GridLab` — `{ record?(recording), boxes?: 1 | 2 }`. `record`: a function that receives each recording of a grid's scrolls, frames and touches, sent once the scroll area has been still 3 s with no finger down, when the page is hidden, or when the lab changes. Its shape is `GridRecording`, on `@viewkitjs/views/grid`. `boxes: 2`: on a device that doesn't hover with a fine pointer, the grid's rows scroll up and down in their own box inside one that scrolls the table sideways (`vk-grid-pan`), so a flick moves one way only. With none set, a grid is exactly as without it.
package/package.json CHANGED
@@ -1,14 +1,16 @@
1
1
  {
2
2
  "name": "@viewkitjs/views",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "ViewKit views — the grid, board, calendar and list over typed fields: a headless engine and a default rendering written to skin discipline. By Sheaf.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
7
7
  "sideEffects": false,
8
8
  "files": [
9
9
  "dist",
10
+ "!dist/panels",
10
11
  "skills",
11
12
  "docs",
13
+ "!docs/reference/panels.md",
12
14
  "README.md",
13
15
  "CHANGELOG.md",
14
16
  "LICENSE.md"
@@ -108,12 +110,29 @@
108
110
  "access": "public"
109
111
  },
110
112
  "peerDependencies": {
111
- "@viewkitjs/fields": "^0.10.0",
113
+ "@dnd-kit/core": "^6.3.1",
114
+ "@dnd-kit/sortable": "^10.0.0",
115
+ "@dnd-kit/utilities": "^3.2.2",
116
+ "@viewkitjs/fields": "^0.12.0",
112
117
  "react": "^19.0.0",
113
118
  "react-dom": "^19.0.0",
114
119
  "zod": "^4.1.12"
115
120
  },
121
+ "peerDependenciesMeta": {
122
+ "@dnd-kit/core": {
123
+ "optional": true
124
+ },
125
+ "@dnd-kit/sortable": {
126
+ "optional": true
127
+ },
128
+ "@dnd-kit/utilities": {
129
+ "optional": true
130
+ }
131
+ },
116
132
  "devDependencies": {
133
+ "@dnd-kit/core": "^6.3.1",
134
+ "@dnd-kit/sortable": "^10.0.0",
135
+ "@dnd-kit/utilities": "^3.2.2",
117
136
  "@tailwindcss/postcss": "^4.3.3",
118
137
  "@testing-library/react": "^16.3.2",
119
138
  "@types/node": "^20",
@@ -128,7 +147,7 @@
128
147
  "typescript": "^5",
129
148
  "vitest": "^4.1.5",
130
149
  "zod": "^4.1.12",
131
- "@viewkitjs/fields": "0.10.0"
150
+ "@viewkitjs/fields": "0.12.0"
132
151
  },
133
152
  "scripts": {
134
153
  "typecheck": "tsc -p tsconfig.json",
@@ -58,7 +58,7 @@ export function AppViews({ children }: { children: ReactNode }) {
58
58
 
59
59
  ## Write the adapter against the contract
60
60
 
61
- `docs/contract.md` lists the eleven components and the optional `Input`, the five ports (`confirm` optional) and the icon names. Implement
61
+ `docs/contract.md` lists the ten required components and the optional `Input`, `Command` and `Picker`, the five ports (`confirm` optional) and the icon names. Implement
62
62
  `ViewsComponents` over your own shadcn copies: a controlled `open` with `onOpenChange(open, details)`,
63
63
  an `anchor` element or ref on the popover and the menu, and no `asChild`; `AppIcon` is your own
64
64
  icon component by your own names. The shapes are Base UI's; `docs/contract.md`'s "Writing an
@@ -69,14 +69,14 @@ toast, haptics, clipboard and a per-device store.
69
69
  ## Bind the messages and swap the atoms
70
70
 
71
71
  The package words only its own strings — a closed list of `{ key, values }` messages under
72
- `views.editors.*`, `views.display.*`, `views.menus.*` and `views.grid.*`; a string `@viewkitjs/fields` already keys
72
+ `views.editors.*`, `views.display.*`, `views.menus.*`, `views.grid.*`, `views.selection.*` and `views.panels.*`; a string `@viewkitjs/fields` already keys
73
73
  stays a fields message. `messages` defaults to `resolveViewsMessage`, the package's English. With
74
74
  next-intl, scope the translator to the namespace (`useTranslations("views")`; a root translator over a
75
75
  typed catalog can overflow TypeScript) and read each key without its `views.` prefix:
76
76
  `(m) => { const key = m.key.slice("views.".length); return t.has(key) ? t(key, "values" in m ? m.values : undefined) : resolveViewsMessage(m); }`.
77
77
 
78
78
  The atoms — `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`,
79
- `RelationLink`, `Loading`, `LoadMore`, `PlatformMark`, `RowMenu` — ship as defaults drawn from your theme. Swap any of them through `atoms` so the views wear
79
+ `RelationLink`, `RelationRoles`, `Loading`, `LoadMore`, `PlatformMark`, `RowMenu` — ship as defaults drawn from your theme. Swap any of them through `atoms` so the views wear
80
80
  your own menus and pills. `CommandMenu`, `RowMenu` and `RelationLink` are your app's own pieces — the verb menu a
81
81
  command cell opens, the row's right-click menu, and where a relation chip goes; their defaults are the map's menu,
82
82
  the map's menu at the pointer (its Delete asks the `confirm` port, the browser's own confirm when you hand none), and a chip that goes nowhere. `Loading` and `LoadMore` are your waits — the list reloading, and how it asks for more rows; their