@viewkitjs/views 0.5.0 → 0.6.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 (413) hide show
  1. package/CHANGELOG.md +620 -0
  2. package/README.md +4 -2
  3. package/dist/atoms/Avatar.d.ts +2 -0
  4. package/dist/atoms/Avatar.js +13 -0
  5. package/dist/atoms/CellMore.d.ts +2 -0
  6. package/dist/atoms/CellMore.js +4 -0
  7. package/dist/atoms/DisabledReason.d.ts +11 -0
  8. package/dist/atoms/DisabledReason.js +10 -0
  9. package/dist/atoms/DrillRows.d.ts +2 -2
  10. package/dist/atoms/DrillRows.js +7 -5
  11. package/dist/atoms/Loading.d.ts +6 -0
  12. package/dist/atoms/Loading.js +4 -1
  13. package/dist/atoms/PanelRows.js +3 -5
  14. package/dist/atoms/Pill.d.ts +2 -0
  15. package/dist/atoms/Pill.js +25 -0
  16. package/dist/atoms/RangeCalendar.d.ts +8 -0
  17. package/dist/atoms/RangeCalendar.js +30 -0
  18. package/dist/atoms/RelationRoles.js +2 -2
  19. package/dist/atoms/SelectionSheet.js +5 -4
  20. package/dist/atoms/ToolbarButton.d.ts +2 -0
  21. package/dist/atoms/ToolbarButton.js +18 -0
  22. package/dist/atoms/defaults.js +10 -0
  23. package/dist/atoms/types.d.ts +141 -1
  24. package/dist/cells/cell-format.d.ts +10 -1
  25. package/dist/cells/cell-title.d.ts +5 -1
  26. package/dist/cells/cell-title.js +2 -2
  27. package/dist/cells/cell-values.js +22 -7
  28. package/dist/cells/relation-wrap.js +1 -1
  29. package/dist/contract.d.ts +351 -15
  30. package/dist/contract.js +482 -4
  31. package/dist/display/actor.js +1 -1
  32. package/dist/display/boolean.js +5 -0
  33. package/dist/display/entity-chip.d.ts +12 -9
  34. package/dist/display/entity-chip.js +4 -5
  35. package/dist/display/fit-values.d.ts +34 -0
  36. package/dist/display/fit-values.js +45 -0
  37. package/dist/display/location.js +1 -1
  38. package/dist/display/multi-value.js +72 -8
  39. package/dist/display/options.d.ts +9 -1
  40. package/dist/display/relation.js +1 -1
  41. package/dist/display/rich-text.js +17 -6
  42. package/dist/display/select.js +6 -4
  43. package/dist/display/status-steps.d.ts +8 -0
  44. package/dist/display/status-steps.js +18 -0
  45. package/dist/display/viewer.js +1 -0
  46. package/dist/editors/BodyFrame.d.ts +29 -0
  47. package/dist/editors/BodyFrame.js +80 -0
  48. package/dist/editors/DateEditor.js +13 -17
  49. package/dist/editors/LocationEditor.d.ts +2 -0
  50. package/dist/editors/LocationEditor.js +29 -5
  51. package/dist/editors/NameEditor.d.ts +2 -0
  52. package/dist/editors/NameEditor.js +27 -7
  53. package/dist/editors/NumberEditor.d.ts +18 -0
  54. package/dist/editors/NumberEditor.js +29 -2
  55. package/dist/editors/RangeEditor.d.ts +2 -0
  56. package/dist/editors/RangeEditor.js +29 -4
  57. package/dist/editors/SelectEditor.d.ts +5 -0
  58. package/dist/editors/SelectEditor.js +3 -2
  59. package/dist/editors/TextEditor.d.ts +11 -1
  60. package/dist/editors/TextEditor.js +25 -8
  61. package/dist/editors/ValueListEditor.d.ts +7 -0
  62. package/dist/editors/ValueListEditor.js +60 -48
  63. package/dist/editors/body-panel.d.ts +7 -0
  64. package/dist/editors/body-panel.js +8 -0
  65. package/dist/editors/edit-session.d.ts +20 -3
  66. package/dist/editors/edit-session.js +43 -3
  67. package/dist/editors/leave-scope.d.ts +23 -0
  68. package/dist/editors/leave-scope.js +28 -0
  69. package/dist/editors/number-body.d.ts +29 -0
  70. package/dist/editors/number-body.js +37 -0
  71. package/dist/editors/parts-body.d.ts +66 -0
  72. package/dist/editors/parts-body.js +114 -0
  73. package/dist/editors/tab-ends.d.ts +5 -0
  74. package/dist/editors/tab-ends.js +7 -0
  75. package/dist/editors/text-body.d.ts +16 -0
  76. package/dist/editors/text-body.js +30 -0
  77. package/dist/editors/values-body.d.ts +47 -0
  78. package/dist/editors/values-body.js +140 -0
  79. package/dist/field-row/FieldRow.d.ts +7 -0
  80. package/dist/field-row/FieldRow.js +44 -24
  81. package/dist/field-row/FieldRowLane.js +12 -4
  82. package/dist/field-row/editors/RowChipsEditor.js +3 -1
  83. package/dist/field-row/editors/RowEditor.js +2 -1
  84. package/dist/field-row/editors/RowNameEditor.d.ts +5 -2
  85. package/dist/field-row/editors/RowNameEditor.js +12 -5
  86. package/dist/field-row/editors/RowNumberEditor.js +18 -2
  87. package/dist/field-row/editors/RowPlaceEditor.js +4 -2
  88. package/dist/field-row/editors/RowRangeEditor.d.ts +5 -2
  89. package/dist/field-row/editors/RowRangeEditor.js +13 -6
  90. package/dist/field-row/editors/RowRelationEditor.js +5 -2
  91. package/dist/field-row/editors/RowSelectEditor.js +4 -1
  92. package/dist/field-row/editors/RowTextEditor.d.ts +1 -1
  93. package/dist/field-row/editors/RowTextEditor.js +12 -3
  94. package/dist/field-row/editors/RowValueListEditor.d.ts +2 -1
  95. package/dist/field-row/editors/RowValueListEditor.js +17 -4
  96. package/dist/field-row/editors/host.d.ts +3 -0
  97. package/dist/field-row/editors/row-session.d.ts +12 -1
  98. package/dist/field-row/editors/row-session.js +52 -2
  99. package/dist/field-row/field-row-button.d.ts +40 -0
  100. package/dist/field-row/field-row-button.js +18 -0
  101. package/dist/field-row/field-row-checkbox.d.ts +9 -0
  102. package/dist/field-row/field-row-checkbox.js +7 -0
  103. package/dist/filters/filter-model.d.ts +2 -0
  104. package/dist/grid/chrome/GridAddColumn.js +17 -3
  105. package/dist/grid/chrome/GridAggregateMenu.d.ts +2 -0
  106. package/dist/grid/chrome/GridAggregateMenu.js +2 -0
  107. package/dist/grid/chrome/GridCellEditors.js +16 -6
  108. package/dist/grid/chrome/GridCellOutline.d.ts +7 -4
  109. package/dist/grid/chrome/GridCellOutline.js +4 -2
  110. package/dist/grid/chrome/GridChipsEditor.js +3 -1
  111. package/dist/grid/chrome/GridColumnMenu.d.ts +4 -1
  112. package/dist/grid/chrome/GridColumnMenu.js +5 -3
  113. package/dist/grid/chrome/GridColumnSortSection.d.ts +20 -0
  114. package/dist/grid/chrome/GridColumnSortSection.js +18 -1
  115. package/dist/grid/chrome/GridFooter.d.ts +4 -1
  116. package/dist/grid/chrome/GridFooter.js +6 -4
  117. package/dist/grid/chrome/GridGroupMenu.d.ts +5 -1
  118. package/dist/grid/chrome/GridGroupMenu.js +30 -8
  119. package/dist/grid/chrome/GridHeader.d.ts +5 -1
  120. package/dist/grid/chrome/GridHeader.js +9 -5
  121. package/dist/grid/chrome/GridLongTextEditor.js +15 -11
  122. package/dist/grid/chrome/GridNameEditor.js +4 -2
  123. package/dist/grid/chrome/GridNumberEditor.d.ts +8 -1
  124. package/dist/grid/chrome/GridNumberEditor.js +15 -3
  125. package/dist/grid/chrome/GridPager.d.ts +7 -0
  126. package/dist/grid/chrome/GridPager.js +34 -0
  127. package/dist/grid/chrome/GridPlaceEditor.js +4 -2
  128. package/dist/grid/chrome/GridRangeEditor.js +12 -4
  129. package/dist/grid/chrome/GridRelationEditor.js +5 -2
  130. package/dist/grid/chrome/GridRow.js +18 -6
  131. package/dist/grid/chrome/GridRowActions.d.ts +8 -3
  132. package/dist/grid/chrome/GridRowActions.js +16 -6
  133. package/dist/grid/chrome/GridRowCells.js +23 -7
  134. package/dist/grid/chrome/GridRowGlyph.d.ts +3 -1
  135. package/dist/grid/chrome/GridRowGlyph.js +7 -2
  136. package/dist/grid/chrome/GridSelectEditor.js +6 -3
  137. package/dist/grid/chrome/GridStructure.d.ts +6 -1
  138. package/dist/grid/chrome/GridStructure.js +32 -8
  139. package/dist/grid/chrome/GridTable.js +36 -24
  140. package/dist/grid/chrome/GridTableSurface.d.ts +5 -1
  141. package/dist/grid/chrome/GridTableSurface.js +5 -2
  142. package/dist/grid/chrome/GridTextEditor.d.ts +5 -1
  143. package/dist/grid/chrome/GridTextEditor.js +13 -3
  144. package/dist/grid/chrome/GridValueListEditor.d.ts +12 -4
  145. package/dist/grid/chrome/GridValueListEditor.js +11 -3
  146. package/dist/grid/chrome/StuckMarker.d.ts +3 -1
  147. package/dist/grid/chrome/StuckMarker.js +6 -2
  148. package/dist/grid/chrome/cells.d.ts +4 -2
  149. package/dist/grid/chrome/cells.js +2 -2
  150. package/dist/grid/chrome/grid-add-column-items.d.ts +1 -1
  151. package/dist/grid/chrome/grid-add-column-items.js +8 -1
  152. package/dist/grid/chrome/grid-button.d.ts +32 -0
  153. package/dist/grid/chrome/grid-button.js +12 -0
  154. package/dist/grid/chrome/grid-cell-classes.d.ts +38 -0
  155. package/dist/grid/chrome/grid-cell-classes.js +30 -0
  156. package/dist/grid/chrome/grid-column-menu-items.d.ts +3 -0
  157. package/dist/grid/chrome/grid-column-menu-items.js +32 -3
  158. package/dist/grid/chrome/grid-columns-template.d.ts +27 -0
  159. package/dist/grid/chrome/grid-columns-template.js +13 -0
  160. package/dist/grid/chrome/grid-edit-session.d.ts +4 -1
  161. package/dist/grid/chrome/grid-edit-session.js +11 -1
  162. package/dist/grid/chrome/grid-group-menu-items.d.ts +8 -1
  163. package/dist/grid/chrome/grid-group-menu-items.js +17 -0
  164. package/dist/grid/chrome/grid-group-menu-parts.d.ts +10 -6
  165. package/dist/grid/chrome/grid-group-menu-parts.js +4 -2
  166. package/dist/grid/chrome/grid-hover.d.ts +4 -1
  167. package/dist/grid/chrome/grid-hover.js +16 -6
  168. package/dist/grid/chrome/grid-pages.d.ts +15 -0
  169. package/dist/grid/chrome/grid-pages.js +9 -0
  170. package/dist/grid/chrome/grid-row-menu-items.js +18 -10
  171. package/dist/grid/chrome/grid-row-props.d.ts +6 -2
  172. package/dist/grid/chrome/grid-row-window.d.ts +7 -0
  173. package/dist/grid/chrome/grid-row-window.js +35 -1
  174. package/dist/grid/chrome/grid-table-props.d.ts +38 -4
  175. package/dist/grid/chrome/useGridColumnLayout.d.ts +3 -1
  176. package/dist/grid/chrome/useGridColumnLayout.js +29 -9
  177. package/dist/grid/chrome/useGridPartColumns.js +1 -1
  178. package/dist/grid/chrome/useGridScrollArea.js +2 -0
  179. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +1 -0
  180. package/dist/grid/chrome/useGridTableInteractionModel.js +5 -3
  181. package/dist/grid/chrome/useGridTableSelection.d.ts +3 -1
  182. package/dist/grid/chrome/useGridTableSelection.js +2 -2
  183. package/dist/grid/chrome/useHeaderDragReorder.js +2 -0
  184. package/dist/grid/core/editing-controller.d.ts +36 -11
  185. package/dist/grid/core/editing-controller.js +92 -25
  186. package/dist/grid/core/grid-aria.d.ts +4 -0
  187. package/dist/grid/core/grid-aria.js +6 -4
  188. package/dist/grid/core/grid-focus.d.ts +6 -0
  189. package/dist/grid/core/grid-focus.js +28 -5
  190. package/dist/grid/core/useGridEditing.d.ts +11 -2
  191. package/dist/grid/core/useGridEditing.js +9 -5
  192. package/dist/grid/core/write-states.d.ts +20 -0
  193. package/dist/grid/core/write-states.js +21 -0
  194. package/dist/grid/grid-format-props.d.ts +26 -0
  195. package/dist/grid/grid-format-props.js +65 -0
  196. package/dist/grid/index.d.ts +3 -1
  197. package/dist/grid/index.js +1 -0
  198. package/dist/grid/useGridTablePrefs.d.ts +19 -20
  199. package/dist/grid/useGridTablePrefs.js +6 -58
  200. package/dist/grid/useGridTableSettings.d.ts +60 -0
  201. package/dist/grid/useGridTableSettings.js +61 -0
  202. package/dist/internal/count.d.ts +3 -0
  203. package/dist/internal/count.js +3 -0
  204. package/dist/model/body-frame.d.ts +16 -0
  205. package/dist/model/body-frame.js +5 -0
  206. package/dist/model/column-capabilities.d.ts +4 -1
  207. package/dist/model/column-capabilities.js +4 -1
  208. package/dist/model/column-filters.d.ts +7 -4
  209. package/dist/model/column-filters.js +26 -18
  210. package/dist/model/column-inspect.d.ts +3 -2
  211. package/dist/model/column-inspect.js +3 -1
  212. package/dist/model/column-sort.d.ts +11 -0
  213. package/dist/model/column-sort.js +14 -0
  214. package/dist/model/one-value.d.ts +6 -0
  215. package/dist/model/one-value.js +5 -0
  216. package/dist/model/part-write.js +1 -1
  217. package/dist/model/place-parts.d.ts +6 -0
  218. package/dist/model/place-parts.js +14 -0
  219. package/dist/model/relation-filters.d.ts +13 -2
  220. package/dist/model/relation-filters.js +9 -4
  221. package/dist/model/row-icon.d.ts +16 -6
  222. package/dist/model/settings-columns.d.ts +34 -0
  223. package/dist/model/settings-columns.js +146 -0
  224. package/dist/model/settings-look.d.ts +17 -0
  225. package/dist/model/settings-look.js +23 -0
  226. package/dist/model/view-rules.js +6 -2
  227. package/dist/panels/availability.d.ts +26 -0
  228. package/dist/panels/availability.js +28 -0
  229. package/dist/panels/filter/DateFilterBody.d.ts +42 -0
  230. package/dist/panels/filter/DateFilterBody.js +64 -0
  231. package/dist/panels/filter/DateFilterCalendar.d.ts +19 -0
  232. package/dist/panels/filter/DateFilterCalendar.js +37 -0
  233. package/dist/panels/filter/DateFilterInput.d.ts +16 -0
  234. package/dist/panels/filter/DateFilterInput.js +37 -0
  235. package/dist/panels/filter/FilterIcon.d.ts +7 -0
  236. package/dist/panels/filter/FilterIcon.js +15 -0
  237. package/dist/panels/filter/MenuSelect.d.ts +12 -0
  238. package/dist/panels/filter/MenuSelect.js +34 -0
  239. package/dist/panels/filter/NumberFilterBody.d.ts +21 -0
  240. package/dist/panels/filter/NumberFilterBody.js +76 -0
  241. package/dist/panels/filter/RangeFilterBody.d.ts +19 -0
  242. package/dist/panels/filter/RangeFilterBody.js +71 -0
  243. package/dist/panels/filter/RelationFilterBody.d.ts +17 -0
  244. package/dist/panels/filter/RelationFilterBody.js +20 -0
  245. package/dist/panels/filter/TextFilterBody.d.ts +31 -0
  246. package/dist/panels/filter/TextFilterBody.js +44 -0
  247. package/dist/panels/filter/TimeScopeDetail.d.ts +6 -0
  248. package/dist/panels/filter/TimeScopeDetail.js +47 -0
  249. package/dist/panels/filter/details.d.ts +17 -0
  250. package/dist/panels/filter/details.js +73 -0
  251. package/dist/panels/filter/filter-list.d.ts +23 -0
  252. package/dist/panels/filter/filter-list.js +38 -0
  253. package/dist/panels/group-sort.d.ts +24 -0
  254. package/dist/panels/group-sort.js +58 -0
  255. package/dist/panels/index.d.ts +24 -0
  256. package/dist/panels/index.js +17 -0
  257. package/dist/panels/labels.d.ts +37 -0
  258. package/dist/panels/labels.js +166 -0
  259. package/dist/panels/model.d.ts +343 -0
  260. package/dist/panels/model.js +77 -0
  261. package/dist/panels/react/GroupBucketsList.d.ts +16 -0
  262. package/dist/panels/react/GroupBucketsList.js +38 -0
  263. package/dist/panels/react/LayoutColumnsList.d.ts +24 -0
  264. package/dist/panels/react/LayoutColumnsList.js +71 -0
  265. package/dist/panels/react/PopoverColumnDetail.d.ts +11 -0
  266. package/dist/panels/react/PopoverColumnDetail.js +24 -0
  267. package/dist/panels/react/chrome.d.ts +17 -0
  268. package/dist/panels/react/chrome.js +8 -0
  269. package/dist/panels/react/column-refusals.d.ts +7 -0
  270. package/dist/panels/react/column-refusals.js +14 -0
  271. package/dist/panels/react/customize.d.ts +26 -0
  272. package/dist/panels/react/customize.js +98 -0
  273. package/dist/panels/react/drag.d.ts +2 -0
  274. package/dist/panels/react/drag.js +6 -0
  275. package/dist/panels/react/field-editor.d.ts +10 -0
  276. package/dist/panels/react/field-editor.js +1 -0
  277. package/dist/panels/react/filter-panel.d.ts +15 -0
  278. package/dist/panels/react/filter-panel.js +48 -0
  279. package/dist/panels/react/layout-detail.d.ts +4 -0
  280. package/dist/panels/react/layout-detail.js +21 -0
  281. package/dist/panels/react/order-details.d.ts +32 -0
  282. package/dist/panels/react/order-details.js +81 -0
  283. package/dist/panels/react/panel-header.d.ts +10 -0
  284. package/dist/panels/react/panel-header.js +12 -0
  285. package/dist/panels/react/panel-sheet.d.ts +19 -0
  286. package/dist/panels/react/panel-sheet.js +22 -0
  287. package/dist/panels/react/popover.d.ts +71 -0
  288. package/dist/panels/react/popover.js +47 -0
  289. package/dist/panels/react/root-list.d.ts +6 -0
  290. package/dist/panels/react/root-list.js +31 -0
  291. package/dist/panels/react/toolbar/ReadyToolbar.d.ts +42 -0
  292. package/dist/panels/react/toolbar/ReadyToolbar.js +92 -0
  293. package/dist/panels/react/toolbar/Toolbar.d.ts +16 -0
  294. package/dist/panels/react/toolbar/Toolbar.js +34 -0
  295. package/dist/panels/react/toolbar/ToolbarButton.d.ts +5 -0
  296. package/dist/panels/react/toolbar/ToolbarButton.js +9 -0
  297. package/dist/panels/react/toolbar/ToolbarFilter.d.ts +19 -0
  298. package/dist/panels/react/toolbar/ToolbarFilter.js +32 -0
  299. package/dist/panels/react/toolbar/ToolbarNew.d.ts +12 -0
  300. package/dist/panels/react/toolbar/ToolbarNew.js +21 -0
  301. package/dist/panels/react/toolbar/ToolbarOptions.d.ts +25 -0
  302. package/dist/panels/react/toolbar/ToolbarOptions.js +33 -0
  303. package/dist/panels/react/toolbar/ToolbarSearch.d.ts +9 -0
  304. package/dist/panels/react/toolbar/ToolbarSearch.js +41 -0
  305. package/dist/panels/react/toolbar/ToolbarSort.d.ts +12 -0
  306. package/dist/panels/react/toolbar/ToolbarSort.js +16 -0
  307. package/dist/panels/react/toolbar/ToolbarViews.d.ts +13 -0
  308. package/dist/panels/react/toolbar/ToolbarViews.js +24 -0
  309. package/dist/panels/react/toolbar/context.d.ts +29 -0
  310. package/dist/panels/react/toolbar/context.js +49 -0
  311. package/dist/panels/react/toolbar/panel-part.d.ts +37 -0
  312. package/dist/panels/react/toolbar/panel-part.js +37 -0
  313. package/dist/panels/react/toolbar/panel-state.d.ts +9 -0
  314. package/dist/panels/react/toolbar/panel-state.js +12 -0
  315. package/dist/panels/react/toolbar/use-box-narrow.d.ts +2 -0
  316. package/dist/panels/react/toolbar/use-box-narrow.js +18 -0
  317. package/dist/panels/react/toolbar/use-list-settings-state.d.ts +10 -0
  318. package/dist/panels/react/toolbar/use-list-settings-state.js +10 -0
  319. package/dist/panels/react/view-actions.d.ts +4 -0
  320. package/dist/panels/react/view-actions.js +37 -0
  321. package/dist/panels/react/view-footer.d.ts +16 -0
  322. package/dist/panels/react/view-footer.js +11 -0
  323. package/dist/panels/react/views-row/FoldingViewRow.d.ts +4 -0
  324. package/dist/panels/react/views-row/FoldingViewRow.js +105 -0
  325. package/dist/panels/react/views-row/HScrollRow.d.ts +7 -0
  326. package/dist/panels/react/views-row/HScrollRow.js +42 -0
  327. package/dist/panels/react/views-row/PillGroup.d.ts +30 -0
  328. package/dist/panels/react/views-row/PillGroup.js +86 -0
  329. package/dist/panels/react/views-row/ViewAxes.d.ts +6 -0
  330. package/dist/panels/react/views-row/ViewAxes.js +16 -0
  331. package/dist/panels/react/views-row/ViewCreatePill.d.ts +7 -0
  332. package/dist/panels/react/views-row/ViewCreatePill.js +11 -0
  333. package/dist/panels/react/views-row/ViewPicker.d.ts +5 -0
  334. package/dist/panels/react/views-row/ViewPicker.js +65 -0
  335. package/dist/panels/react/views-row/ViewPickerRow.d.ts +7 -0
  336. package/dist/panels/react/views-row/ViewPickerRow.js +18 -0
  337. package/dist/panels/react/views-row/ViewTabs.d.ts +31 -0
  338. package/dist/panels/react/views-row/ViewTabs.js +29 -0
  339. package/dist/panels/react/views-row/menu-classes.d.ts +6 -0
  340. package/dist/panels/react/views-row/menu-classes.js +3 -0
  341. package/dist/panels/react/views-row/use-anchored-toggle.d.ts +19 -0
  342. package/dist/panels/react/views-row/use-anchored-toggle.js +31 -0
  343. package/dist/panels/react.d.ts +51 -0
  344. package/dist/panels/react.js +43 -0
  345. package/dist/panels/settings/axes.d.ts +28 -0
  346. package/dist/panels/settings/axes.js +71 -0
  347. package/dist/panels/settings/filters.d.ts +5 -0
  348. package/dist/panels/settings/filters.js +62 -0
  349. package/dist/panels/settings/group-buckets.d.ts +23 -0
  350. package/dist/panels/settings/group-buckets.js +73 -0
  351. package/dist/panels/settings/input.d.ts +69 -0
  352. package/dist/panels/settings/input.js +1 -0
  353. package/dist/panels/settings/layout.d.ts +5 -0
  354. package/dist/panels/settings/layout.js +244 -0
  355. package/dist/panels/settings/order.d.ts +19 -0
  356. package/dist/panels/settings/order.js +271 -0
  357. package/dist/panels/settings/settings-panels.d.ts +17 -0
  358. package/dist/panels/settings/settings-panels.js +28 -0
  359. package/dist/panels/toolbar/clear.d.ts +9 -0
  360. package/dist/panels/toolbar/clear.js +26 -0
  361. package/dist/panels/toolbar/counts.d.ts +15 -0
  362. package/dist/panels/toolbar/counts.js +21 -0
  363. package/dist/panels/toolbar/edit-view.d.ts +5 -0
  364. package/dist/panels/toolbar/edit-view.js +18 -0
  365. package/dist/panels/toolbar/model.d.ts +34 -0
  366. package/dist/panels/toolbar/model.js +52 -0
  367. package/dist/panels/use-filter-opened.d.ts +8 -0
  368. package/dist/panels/use-filter-opened.js +11 -0
  369. package/dist/panels/view-state.d.ts +38 -0
  370. package/dist/panels/view-state.js +1 -0
  371. package/dist/panels/views-row/model.d.ts +131 -0
  372. package/dist/panels/views-row/model.js +14 -0
  373. package/dist/provider/ViewsProvider.d.ts +46 -6
  374. package/dist/provider/ViewsProvider.js +32 -2
  375. package/dist/provider/components.d.ts +258 -11
  376. package/dist/provider/context.d.ts +21 -2
  377. package/dist/react.d.ts +5 -2
  378. package/dist/selection/SelectionBar.js +13 -7
  379. package/dist/selection/bar-overflow.js +14 -1
  380. package/dist/selection/bar-parts.d.ts +4 -2
  381. package/dist/selection/bar-parts.js +5 -3
  382. package/dist/selection/useListSelectionShortcuts.d.ts +3 -2
  383. package/dist/selection/useListSelectionShortcuts.js +1 -1
  384. package/dist/selection/verbs.d.ts +7 -0
  385. package/docs/contract.md +307 -41
  386. package/docs/getting-started.md +1 -1
  387. package/docs/guides/atoms.md +37 -5
  388. package/docs/guides/columns.md +1 -1
  389. package/docs/guides/display.md +3 -2
  390. package/docs/guides/editors.md +4 -3
  391. package/docs/guides/selection.md +4 -2
  392. package/docs/guides/the-grid.md +21 -11
  393. package/docs/guides/the-provider.md +22 -6
  394. package/docs/index.md +2 -2
  395. package/docs/install.md +2 -3
  396. package/docs/reference/cells.md +1 -1
  397. package/docs/reference/display.md +5 -4
  398. package/docs/reference/editors-location.md +3 -1
  399. package/docs/reference/editors-name.md +3 -1
  400. package/docs/reference/editors-number.md +1 -0
  401. package/docs/reference/editors-range.md +3 -1
  402. package/docs/reference/editors-session.md +1 -0
  403. package/docs/reference/editors-text.md +2 -2
  404. package/docs/reference/editors-value-list.md +1 -1
  405. package/docs/reference/field-row.md +2 -2
  406. package/docs/reference/grid.md +8 -5
  407. package/docs/reference/panels-react.md +101 -0
  408. package/docs/reference/panels.md +123 -0
  409. package/docs/reference/react.md +39 -16
  410. package/docs/reference/selection.md +5 -5
  411. package/docs/reference/views.md +17 -12
  412. package/package.json +16 -6
  413. package/skills/views/SKILL.md +4 -3
@@ -2,8 +2,8 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/text` in a client component: the door opens with the client directive. It holds the one editor for every text-like value: `text`, `url`, `domain`, `email`, `phone` and `rich_text`, a line or a paragraph. It tidies what was typed (trimmed; rich text tidied only at its edges, with fields' `normalizeMarkdown`, so its first line keeps its indent), and an unchanged value closes as no save. It owns the box and what a close means; its host owns where it opens (in place, a popover, a sheet), the session and the write. It commits a string. Guide: [editors](../guides/editors.md#a-text-box).
4
4
 
5
- - `TextEditor` — the box, focused without scrolling, its caret at the end; its ref is a `TextEditorHandle`. A line draws through the components map's `Input`; a paragraph (`multiline`) is the package's own textarea. Keys: Escape asks `onRequestClose("escape")`; Enter asks `"enter"` (in a paragraph only with ⌘ or Ctrl, and a bare Enter is a newline); Tab and Shift-Tab ask `"tab"` and `"shift-tab"`; leaving the box asks `"blur"` unless `closeOnBlur` is false. The box carries `data-slot="vk-text-editor"`.
6
- - `TextEditorProps` — `type` (a `TextEditorType`), `initial` (the stored value, `""` when unset), `onRequestClose`, and optionally `seed` (type-to-replace: the draft opens on it, compared against `initial`), `multiline` (a paragraph; the default for rich text), `readOnly` (every close a `noop`), `closeOnBlur` (default true; a host in a popover or a sheet passes false), `label` (the box's accessible name), `chrome` (handed to your `Input`: `bare`, the default, or `field`), `rows` and `maxLines` (a paragraph opens at `rows`, default 1, and grows with its text to `maxLines`, default 12, then scrolls; `maxLines` no greater than `rows` keeps it at `rows`), `className`, `style`, and `boxData` (`data-*` attributes set on the box, over its own slot).
5
+ - `TextEditor` — the box, focused without scrolling, its caret at the end; its ref is a `TextEditorHandle`. A line draws through the components map's `Input`; a paragraph (`multiline`) is the package's own textarea. Keys: Escape asks `onRequestClose("escape")`; Enter asks `"enter"` (in a paragraph only with ⌘ or Ctrl, and a bare Enter is a newline); Tab and Shift-Tab ask `"tab"` and `"shift-tab"`; leaving the box asks `"blur"` unless `closeOnBlur` is false. The box carries `data-slot="vk-text-editor"`. Handed the components map's `TextBody`, the editor opens it in place of its own box, in a frame carrying `data-slot="vk-text-body"`: it hands the body the draft and the field's settings (`ViewsTextBodyProps`), and keeps the draft, Escape's rule, Tab, ⌘ or Ctrl Enter (closes as `"enter"`), in place a press outside (`"blur"`), the close's tidy (a line's line breaks become a space; a phone that reads as the stored number is a `noop`) and the save.
6
+ - `TextEditorProps` — `type` (a `TextEditorType`), `initial` (the stored value, `""` when unset), `onRequestClose`, and optionally `seed` (type-to-replace: the draft opens on it, compared against `initial`), `multiline` (a paragraph; the default for rich text), `readOnly` (every close a `noop`), `closeOnBlur` (default true; a host in a popover or a sheet passes false), `label` (the box's accessible name), `chrome` (handed to your `Input`: `bare`, the default, or `field`), `rows` and `maxLines` (a paragraph opens at `rows`, default 1, and grows with its text to `maxLines`, default 12, then scrolls; `maxLines` no greater than `rows` keeps it at `rows`), `className`, `style`, `boxData` (`data-*` attributes set on the box, over its own slot), and for a `TextBody`: `check` (the host's reading of a value, handed to the body), `region` (a phone's country, handed to the body and read by its close), `escapeKeeps` (the session keeps on Escape: the frame carries `EDITOR_INNER_ESCAPE`) and `form` (`phone` in a sheet, default `computer`).
7
7
  - `TextEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Read-only answers `noop`; Escape cancels; otherwise the tidied draft against the tidied `initial`: equal is a `noop`, different a `commit` of the tidied draft.
8
8
  - `TextEditorType` — the types it edits: `text`, `url`, `domain`, `email`, `phone`, `rich_text`.
9
9
  - `TEXT_INPUT_TYPE` — the native input type per `TextEditorType`, the phone keyboard each brings: `text` and `rich_text` `text`, `url` and `domain` `url`, `email` `email`, `phone` `tel`.
@@ -2,5 +2,5 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/value-list` in a client component: the door opens with the client directive. It holds the editor of a field holding several values of one kind (a `multiple` email, phone, url or domain field), each with its label and one of them the main one. It is a draft, like the chips editor: the whole list commits once when the host closes it. It owns the rows, the reading of each value and what a close means; its host owns the popover, the anchor and the write. It commits a list of `ValueItem`s of `@viewkitjs/fields`, `{ value, label, main }`, the main one first, or null. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal; so does Escape with `escapeKeeps` (a host whose session keeps, `EditSession.keeps`), which also marks the list's box `EDITOR_INNER_ESCAPE`, so a popover leaves that Escape to the rows. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false).
5
+ - `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal; so does Escape with `escapeKeeps` (a host whose session keeps, `EditSession.keeps`), which also marks the list's box `EDITOR_INNER_ESCAPE`, so a popover leaves that Escape to the rows. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false), `label` (the field's name for an app's `ValuesBody`; default `field.label`), `holds` (`"one"`: one line with no main mark, no label box and no Add row, × empties the line and it stays; default `"several"`) and `seed` (what was typed on what opened it: the first row's text starts as it). Handed `ValuesBody` (the components map), the editor opens it in place of its own rows, handing it the draft as lines, the field's type, its check, `labels`, `holds`, a phone's `region`, `typed` and `form`, and keeps the draft, which value is kept as stored, Escape, Tab and the close; with a body it draws no row, no reason and no open action of its own.
6
6
  - `ValueListEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels; any other close keeps what was built. Blank rows are dropped. A row left untouched keeps its stored value exactly as stored, and a row typed in commits its trimmed text for the field's commit to read. With no main mark the first row is the main one. The same values, labels and main as opened is a `noop`; an empty list commits null with `allowEmpty` and cancels without it.
@@ -2,8 +2,8 @@
2
2
 
3
3
  Import from `@viewkitjs/views/field-row` in a client component, under your `ViewsProvider`: the door opens with the client directive. It holds a record's field row: one field drawn as its label, its value and, on a click, its type's editor in place, and the write path that admits each edit at once, queues one record's writes, settles each on the save's receipt and rolls a failure back. The row knows no entity, only a binding, a value and a commit, so your app builds its record's panel (its sections, its related records) around the rows. It draws with your provider's `Popover`, `Sheet`, `Collapse`, `AppIcon`, icons, `CommandMenu` atom and toast port. The shapes its writes go through (the write target, the receipt, the admission, a value's note, the reconciliation error) are the root door's, described under [A write's target](views.md#a-writes-target), and this door re-exports them. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width. Escape throws the edit away, unless the provider's `escape` keeps the field's type, on a desktop, where it keeps what was typed and a refusal stays open until a second Escape throws the edit away; a sheet's swipe or ✕ changes nothing. On a desktop, a short select opened by Enter or Space on the row puts the focus on the value it holds, so the arrows walk it and Enter picks; opened by a pointer, it moves no focus. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once its exit has played out and a write still saving has saved, so the next Tab moves on from that row; a press or a focus outside an editor's panel since the close lets that go, so a row opened meanwhile keeps its editor, and an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry.
6
- - `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
5
+ - `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width, except that with a `PartsBody` handed a name and a range open anchored under the value, as a place does, and that a single email or domain opens the value list holding one value, anchored, where the provider's `oneValue` says `list` for its type. Escape throws the edit away, unless the provider's `escape` keeps the field's type, on a desktop, where it keeps what was typed and a refusal stays open until a second Escape throws the edit away; a sheet's swipe or ✕ changes nothing. On a desktop, a short select opened by Enter or Space on the row puts the focus on the value it holds, so the arrows walk it and Enter picks; opened by a pointer, it moves no focus. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once its exit has played out and a write still saving has saved, so the next Tab moves on from that row; a press or a focus outside an editor's panel since the close lets that go, so a row opened meanwhile keeps its editor, and an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry. A text, an email, a phone, a link, a domain, long or rich text edits in place in the row; handed the components map's `TextBody`, the row opens it there, at every width, with the field's own check and the record's country. A number, money or a percent edits in place too; handed `NumberBody`, the row opens it there, at every width, with the field's own check and its limits (a duration keeps the editor's own box).
6
+ - `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles; an editor still open when the page or the row goes is asked as for a press outside, so it can be called inside `pagehide`), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
7
7
  - `RowEditor` — the editor a row mounts for its field's type, picked from `ROW_HOSTS`.
8
8
  - `ROW_HOSTS` — the host each field type mounts in a row, or `null` for a type the row never opens (a boolean, a derived or system field).
9
9
  - `RowEditorProps` — what a host receives: `binding`, `row`, `initial` (the stored value), `anchor` (the value as drawn, kept under an anchored editor), `shown` (the display value, whose labels a set of records opens on), `conversion` (the marked figure, when the row showed the amount converted, which a money host names under it), `onAttempt`, `onClose` (called with a `RowClosed` once the editor's exit has played out), `message`, `kindIcon` and `openedByKey` (true when a key, Enter or Space, pressed the row's button rather than a pointer).
@@ -6,24 +6,27 @@ The spreadsheet. The door carries no client directive; every rendering file behi
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
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
- - 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).
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, or the row's picture through your `Avatar` atom when the descriptor hands an `avatar`), `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), `oneHeader` (a grouped grid draws one row of column names, pinned at the top over every group, in place of each group's own; each group's bar pins under it, and the row's checkbox picks every row; off by default, when each group draws its own with the box that picks its rows), `renderGroupLabel`, `renderGroupFooter` (a group's paged continuation after its loaded rows), `onHideGroup`, `countOf`, `loadMore` (`hasMore`, `onReveal` and a `label`), `pages` (`GridPages`: `page` from 1, `size`, `total`, the view's count, `exact`, false for a capped count, `sizes`, the page-size pick's choices, default 25, 50 and 100, and `onPage` and `onSize`: an ungrouped grid draws the page you hand and the pager part `vk-grid-pager` under it, `loadMore` is then not drawn, picks clear on a page or size change, and the footer shows only the figures a group carries in `figures`; a grouped grid draws no pager; absent by default), `emptyState`, and `transitionKey`, `transitionPending` and `transitionLabel` (a view change: the wait paints before the new rows mount).
10
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).
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: `"select"` (Select all in group, on a grid with a `selection`), `"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, 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`.
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`; and `headerVerticalBorders` (the header's columns ruled as the rows' are under `verticalBorders`, the last bare; off by default); and `fillWidth` (the columns share the grid's whole width, each in proportion to its own width and never below it, a column the person resized or one with a `grid.maxWidth` keeping its width; a table wider than the grid scrolls sideways as without it; off by default).
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`.
17
+ - `useGridTableSettings` — wires a list's settings and a person's layer to the grid, for a list kept as `@viewkitjs/fields/query`'s `ListSettings`. It takes `settings`, `layer` (the person's `ListPersonalLayer`), `columns` (the declared ones), `parts` (the same `parts` the grid takes, so a part column the settings place is drawn and moved as the grid draws it), `onChange` (a `ListSettingsChange`, never empty), `onLayerChange` (a layer patch), `defaults` (the reader's `ListDefaults`) and `formats` with `setFormats`, and returns `{ gridProps }` to spread on `GridTable`, as `useGridTablePrefs` does: a column hidden, moved, given a line break or a figure, and a group header's figures, come back through `onChange`; a resize through `onLayerChange` as the person's width (a width taken back by a double-click leaves it); a format through `setFormats`.
18
+ - `GridFormatPrefs` — how a list's fields read, which `useGridTableSettings` takes apart from its settings: `gridOptionColors`, `gridDateStyles`, `gridDurationStyles`, `gridShowTime`, `gridPercentDisplays`, `gridDecimals` and `gridCurrencies`, each keyed by field key.
17
19
 
18
20
  ## Sort, group and figures
19
21
 
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.
22
+ - `GridSortState` — the list's sort, as the header menu reads and writes it: `value` (the sort key in force; for a place column, the part key `partKey(fieldKey, part)` its menu picked, read with `parsePartKey`), `dir` and `onChange({ value, dir })`. The menu is a second control for the same stored sort your view's options drive.
21
23
  - `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
24
  - `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
25
  - `GridGroupFigure` — one figure a group's band can show, either a `GridDeclaredFigure` or a `GridDrawnFigure`. Both carry the summary `part` that turns it on.
26
+ - `GridPages` — a grid in pages, `GridTable`'s `pages`: `page` (from 1), `size`, `total` (the view's count), `exact` (false for a capped count, which reads "of 1,000+"; default true), `sizes` (the page-size pick's choices; default 25, 50 and 100), `onPage` and `onSize`.
24
27
  - `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
28
  - `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"`.
29
+ - `GridGroupMenuPart` — a part of a group band's ⋯ menu: `"select"` (Select all in group, which picks every row of the group or, when all are picked, clears them; on a grid that selects), `"sort"` (its sort choices), `"figures"` (the count and each figure, turned on and off) or `"hide"`.
27
30
  - `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`.
28
31
  - `GroupCountNoun` — a group count's noun, `{ one, other }`, so a header reads "2 companies"; without one the count is bare.
29
32
 
@@ -0,0 +1,101 @@
1
+ # `@viewkitjs/views/panels/react`
2
+
3
+ Import from `@viewkitjs/views/panels/react` for the panels as they draw: each is a client component that reads your `ViewsProvider` (its components, atoms, icons, conventions and words), so it renders under the provider your app mounts. The door carries the client directive. What the panels edit and say, the settings and their labels, is the pure door [`@viewkitjs/views/panels`](./panels.md), which a server file may read without shipping a panel. Rows draw through the panels' atoms, and a calendar through the `RangeCalendar` atom (see [the atoms](../contract.md#the-atoms)); every word is a `views.panels.*` key.
4
+
5
+ ## The filter panel
6
+
7
+ - `CompactFilterList` — the Filter drill-in: a row per filter, grouped under each filter's `section`, then the time scope and the date ranges; a press opens that row's detail through `onOpenPanel`.
8
+ - `dimensionRows` — the same rows without the scroll box, for a root list that shows them unfolded.
9
+ - `FilterSectionHeading` — a section's rule and heading in the filter panel, and the Where heading inside a relation's filter.
10
+ - `FilterIcon` — a filter row's glyph: the filter's own `icon`, else its kind's (`filterStatus`, `filterCategory`, `filterMetric`), else `filter`.
11
+ - `CompactFilterDetail` — one filter's page: the body for its type, an unavailable filter's reason and its Clear saved filter, a multi filter's ticked options, or a single filter's options after its All row. A relation's Where row opens its far field through `onOpenField`.
12
+ - `TextFilterBody` — a text filter's box and operators; the box commits after a short idle, on Enter or on its clear.
13
+ - `NumberFilterBody` — a number filter's bound or bounds and operators; a duration reads and writes the cell's own wording, stored in the column's unit.
14
+ - `RangeFilterBody` — a range filter's presets, bounds and operators; an empty bound is an open end.
15
+ - `RelationFilterBody` — a relation filter's Any, No and Every, the sentence that says what the list shows, and the far fields as Where rows your surface draws.
16
+ - `DateFilterBody` — a date filter's editor: the operator through your `Menu`, the relative direction and unit, the date boxes and the month.
17
+ - `DateFilterFields` — everything under the operator, for a surface that draws its own operator (a phone's sheet).
18
+ - `useDateFilterEditor` — the date editor's state: the rule, the end being picked, the boxes' refs, and its setters.
19
+ - `DateFilterEditor` — what `useDateFilterEditor` returns.
20
+ - `DateFilterCalendar` — the date filter's month, through `RangeCalendar`: a press sets the end being picked and hands the caret to the other end's box; a relative rule paints its window and takes no press.
21
+ - `DateFilterEditingEnd` — which end a press sets, `from` or `to`.
22
+ - `DateFilterInput` — one end's typed date, committed once it reads as a whole day, or on its clear.
23
+ - `CompactToggleDetail` — a toggle's On and Off; a pick goes back.
24
+ - `CompactDateRangeDetail` — a date range's month, with a Clear under it while either end is set.
25
+ - `CompactTimeScopeDetail` — a time scope's presets and its Custom row, which opens a month; a press on a finished custom range starts a new one, and your popover's back arrow steps from the month to the presets through `registerBackHandler`.
26
+
27
+ ## The views row
28
+
29
+ The row of views over a list, and any row of pills: each pill is your `Pill` atom, a pill's verbs open through your `Menu`, the folded views and the picker's list through your `Popover`, a view's glyph through your `AppIcon`. The pills drag with dnd-kit, by the mouse and the keyboard (Space on a pill's grip, the arrows, Space), within their block: a private view moves among the private ones, a shared view among the shared. The active pill's `Menu` is drawn beside it in the row, so a closed `Menu` must render nothing in place (a portaled popup does): the fold measures the row's children. Install `@dnd-kit/core`, `@dnd-kit/sortable` and `@dnd-kit/utilities` to use it. The axes it draws are `/panels`' (`ViewTabOption`, `CollectionViewsConfig` and the rest).
30
+
31
+ - `PillGroup` — a single-select drawn as pills, `solid` or `plain`, `default` or `sm`, reordering by drag when handed `onReorder`. Its options are `PillOption`s.
32
+ - `HScrollRow` — a scroll rail that keeps the active pill in view, its width and end room from `--vk-scroll-row-inset` and `--vk-scroll-row-end`.
33
+ - `ViewTabs` — one axis as plain pills on a scroll rail.
34
+ - `toPillOptions` — views turned into pill options: the label and count joined by `views.panels.view-count`, a slot's colours, the glyph by your `AppIcon`.
35
+ - `FoldingViewRow` — the saved-views row that folds what doesn't fit into a "+N" chip, never folding the active view, and closes with the + when the axis grows.
36
+ - `ViewPicker` — the same axis as one chip naming the active view, its views in a list: shared, then personal, a search past five, and "New view…" last. The list opens in your `Popover` at the chip; on a phone (in a `Toolbar`, its phone form; elsewhere your provider's `desktopQuery`) in your `Sheet` (`snap: "auto"`, titled `views.panels.views-list`), its search not taking the focus.
37
+ - `ViewPickerRow` — one view as a row of a list, with the active view's `⋮`.
38
+ - `ViewCreatePill` — the + that creates a view.
39
+ - `ViewAxes` — an axis or several on one row: one axis at the row's size folds, peer axes share one rail, each in its own track.
40
+
41
+ ## The Sort and Group panels
42
+
43
+ A panel's list keeps `--vk-panel-padding` from its edge ([Tokens](../contract.md#tokens)). Each panel's root is a `data-vs-detail` list and each row a `data-vs-row`, so a host that frames a panel styles it through those. This is the one door that may reach dnd-kit, the package's optional peers: the Columns list, the group order and the view pills drag through it. Install `@dnd-kit/core`, `@dnd-kit/sortable` and `@dnd-kit/utilities` to use it; an app that takes only the grid, or only the panels' pure door, never does.
44
+
45
+ - `CompactSortDetail` — Sort's page: every option the list sorts by, the current one ticked with its direction arrow, and a search once there are more than eight (`GROUP_BY_SEARCH_AFTER`). Takes `sort` (`SortConfig`); a pick sorts by that option in its own direction.
46
+ - `CompactGroupDetail` — the Group panel: Group by, Sort and Date by as rows that open pages of their own, Hide empty groups as a switch, the Groups to show, hide and drag, and Remove grouping. Takes `group` (`GroupConfig`) and `onOpenPanel`, called with `{ type: "groupBy" }`, `{ type: "groupSort" }` or `{ type: "groupDateBy" }`. A `group` with no `hideEmpty` or `groups` draws no such section.
47
+ - `CompactGroupByDetail` — Group by's page: None and every dimension, the current one checked, a search past eight. Takes `group` and `onBack`, called after a pick.
48
+ - `CompactGroupSortDetail` — the Group panel's Sort page: the dimension's orders both ways, then Manual where its groups can be dragged. Takes `group` and `onBack`.
49
+ - `CompactGroupDateByDetail` — Date by's page: a date dimension's granularities. Takes `group` and `onBack`.
50
+ - `GroupBucketsList` — the group order: every group with a grip to drag it and an eye to show or hide it, an empty group dimmed and the empty one named `views.panels.group-empty`. Takes `groups` (`GroupConfig["groups"]`) and `variant`, `"compact"` (a panel's row) or `"comfortable"` (a phone sheet's taller row). It drags by mouse after 8 px, by a long press of 250 ms that gives up past 5 px, and by the keyboard (Space or Enter lifts a focused grip, the arrows move it); the grip carries `data-base-ui-swipe-ignore`, so a drawer that honours it keeps still while a row inside it is dragged.
51
+
52
+ ## The Layout panel and the columns
53
+
54
+ - `CompactLayoutDetail` — the Layout panel: the layouts a list can draw, the ones it refuses greyed with their reason on a resting pointer, then the active layout's Options, its own pick-one settings, Density and the reader's For you section. Takes `layout` (`LayoutConfig`).
55
+ - `LayoutColumnsList` — the Columns list: a grip to reorder, an eye to show or hide, the row's body to open a column's settings, a board card's new-line toggle, and Reset when a column differs from the view. Takes `columns` (`LayoutColumnsConfig`), `variant`, `onOpenColumn`, `canOpen` (which rows open; every row when absent), `showNewLine` and `fieldEditor`. It drags as `GroupBucketsList` does; a `fixed` column has no grip and no eye.
56
+ - `PopoverColumnDetail` — one column's settings: Visible, its pick-one settings and toggles under their sections, and the field editor's rows for its field. Takes `column`, `columns`, `onDone` (called once a field editor's row has opened its window) and `fieldEditor`.
57
+ - `PanelFieldEditor` — what an app's field editor adds to the panels: `columnMenu(fieldKey, close)`, the rows a column's settings show for its field (`null` for a field it does not change), and `fieldsFooter(columns)`, what the Columns list shows under its rows. Without one, both draw as they always have.
58
+
59
+ ## Customize
60
+
61
+ The panel a list's Options button opens, put together from the panels above: one header frame (a back arrow only when deep, the title, Clear all at the root without a shared view, a ✕ when the host can close it) over the root list or the page a row opened, and, at the root of a shared view, its footer. Its root is a `data-vs-detail` list, its header `data-vs-header`, its footer `data-vs-footer` with `data-vs-inset` and each actions row a `data-vs-row`, so a drawer of your own insets them through those; the root's rows carry `data-vs-row` when your `MenuRow` and `ToggleRow` atoms do. Your app hosts it: in a popover, or in a full-height drawer with `fill`.
62
+
63
+ - `ViewOptionsPanelContent` — the panel. Takes the list's `filters`, `sort`, `group`, `timeScopeConfig`, `dateRangeConfigs`, `toggles` and `layout` (`ViewOptionInputs`), `activePanel` and `onOpenPanel`, `anyActive` and `clearAll`, and optionally `view` (`CollectionViewState`), `foldFilters` (one Filter row, on by default; off, every filter is a root row), `onClose`, `closeButton` (whether its header draws the ✕, default true; false in a sheet whose head draws it, `onClose` still closing it from inside, as a column's Done does), `fill` and `fieldEditor` (`PanelFieldEditor`). Back walks one level: a relation's Where field to its filter, a folded filter to the Filter list, a column to the Columns list, Group's own Group by, Sort and Date by pages to Group, anything else to the root.
64
+ - `PopoverRootList` — the root: Layout, Columns (`views.panels.columns-shown`), Filter (or each filter, unfolded), Sort, Group and the toggles, each opening its page through `onOpenPanel`.
65
+ - `ViewFooter` — Reset · Set default for everyone on a shared view this person has drifted from; a member sees Reset alone, and nothing draws while `changes` is 0. `className` replaces its side inset.
66
+ - `ViewOptionsActions` — the actions row: Copy link and Share parked, Export CSV live when `exportCsv` (`CollectionExportCsv`) is handed in, its count on the row and one export at a time behind the `loading` glyph, which your app draws turning.
67
+ - `ViewOptionsPopoverPanel` — the panel for a popover: `ViewOptionsPanelContent` with `setActivePanel` for `onOpenPanel`.
68
+ - `useViewOptionsPopover` — the state the trigger and the popover share (`ViewOptionsPopoverState`): `open`, the page it is on, the trigger's `badge` (the drift from everyone's view on a shared view, else the active options) and its `clearAll` (Reset, else clear them), and `handleOpenChange`, which forgets the page on a close. The trigger's own look is yours.
69
+ - `ViewOptionsPopoverState` — what `useViewOptionsPopover` hands back: `open` and `setOpen`, `badge`, `activePanel` and `setActivePanel`, `anyActive`, `clearAll` and `handleOpenChange`.
70
+ - `useViewActivePanel` — the page alone, with the active-options count and clear, for a host that keeps its own open state (a phone's sheet).
71
+ - `viewOptionsPopoverClassName` — the popover's own classes: its width (`w-60`, or the one you pass), `w-62` on a date range's or time scope's page whatever you pass, `z-90`, and its slide from the right, which needs your app's animation utilities.
72
+ - `keepPanelOpenForPortals` — hand it to your popover's outside-press and outside-focus handlers: a click inside one of the panel's own portalled children (a select's list, a nested popover, each inside Radix's `[data-radix-popper-content-wrapper]`), or on a page body a modal layer has locked, never closes the panel.
73
+
74
+ ## The toolbar
75
+
76
+ The frame that holds a list's controls, and the parts that need no list settings. `Toolbar` takes the parts your app hands it, each placed at the start or the end, on the first line or the second, and draws them in one of three forms (`/panels`' [arrangement](panels.md#the-toolbars-arrangement)): `row`, `narrow` (its own box under 700px) or `phone` (your provider's `desktopQuery` says it is not a desktop). Pass `phone` or `narrow` to decide either yourself. A part is any node: the frame tells it where it stands through `useToolbarSlot`, and its buttons draw through the `ToolbarButton` atom at their line's size. A part that opens something (a menu, a panel, a pane your app holds) registers it with `useToolbarPanel`, and opening one closes every other, however it opened. A change of form draws the parts afresh, so keep what must last across it (a search's text, a panel's open state) in your app: a panel part left to hold its own state closes when the box crosses 700px, and one handed its state from `useToolbarPanelState`, held above the `Toolbar`, stays open on its page. The row's end controls float over the views on a fade of `--vk-ground` (`data-toolbar-cluster`), which the folding views row measures. Its look is plain; its pieces carry the `data-slot`s the [contract](../contract.md) lists.
77
+
78
+ - `Toolbar` — the frame. Takes `parts` (`ToolbarPart[]`), and optionally `phone`, `narrow`, `narrowBelow` (700 by default) and `className`.
79
+ - `ToolbarPart` — a part as your app hands it: a `ToolbarPlacement` (its `key`, `side`, `line`, `role`) and its `node`.
80
+ - `ToolbarViews` — the views row: `views` (`CollectionViewsInput`) and `viewsLayout`. On the row and in the narrow panel it draws `ViewAxes`, or with `as="picker"` and one axis alone its `ViewPicker`; placed again with `stacked` on the second line, it draws the axes a stacked layout pushes beneath, small. On the phone it draws a `ViewPicker` per axis, every axis, and nothing for `stacked`. With `showCounts` the toolbar owns Show counts (`withCounts`). Place it only when the list has views: the phone's search fills the row when nothing is placed at the start.
81
+ - `ToolbarSearch` — the search, placed with `role: "search"`: `value`, `onChange`, `placeholder` (`views.panels.search` by default) and `searching` (while true, a spinner, worded `views.panels.searching`, stands where its glass is, on the button and in the field, and the field, marked `aria-busy`, keeps its value and its typing; your app decides when it is true). On the row, and beside the phone's views, a button that opens an inline field; in the narrow panel, and on a phone with no views, a field that fills its line. A field that holds a value shows from the start. Escape and its ✕ clear it and close a field the button opened; a blur with nothing typed closes it. The field is your `Input`.
82
+ - `ToolbarNew` — the +: `onAdd` (one way to add, the button fires it) or `items` (several, opened through your `Menu`, one of the toolbar's panels), `label` (`views.panels.toolbar-new` by default) and `icon` (your `add` glyph by default); its word for a dress is its label. With neither, the row draws it disabled, so its place never moves; the narrow panel and the phone draw nothing.
83
+ - `ToolbarButton` — the `ToolbarButton` atom at the size of the line it stands in, for a custom part's buttons.
84
+ - `useToolbarSlot` — where this part stands (`ToolbarSlotState`): `form`, `fill`, `size` and its line's kind; outside a `Toolbar`, the row's main line at `md`.
85
+ - `ToolbarSlotState` — what `useToolbarSlot` returns.
86
+ - `useToolbarPanel` — a part's open state as one of the toolbar's panels, named by a key: `{ open, onOpenChange }`. Each call is its own panel, so two parts that name the same key still close each other. Hand it `{ open, onOpenChange }` for a panel your app holds; without, it holds its own. Outside a `Toolbar`, plain open state.
87
+
88
+ ### The panel parts and the ready toolbar
89
+
90
+ Options, Sort and Filter each open their panel from their own button, and each takes the builder's panels ([`settingsPanels`](panels.md#built-from-a-lists-settings)): an app that arranges its own parts calls the builder and hands them in. A panel hangs in your `Popover` at its button (`chrome="menu"`, aligned to its end), or in a host you hand in, your side drawer or your sheet, where it draws full height. On a phone (in a `Toolbar`, its phone form; elsewhere your provider's `desktopQuery`) it opens in your `Sheet` instead (`snap: "full"`, named `label` with the part's name, its own header titling it), full height, with every page the popover has; a host you hand still takes it. With your provider's `sheetActions: "head"`, the sheet's head draws the panel's ✕ (`actions.close`, no `done`) and the panel draws none. Each is one of the toolbar's panels, so opening one closes the others. Hand `open` and `onOpenChange` (and `page` and `onPageChange` where it drills in) to hold its state yourself; without, it holds its own, forgetting its page when it closes.
91
+
92
+ - `ToolbarOptions` — Customize behind its own button, named and worded `views.panels.toolbar-options`: the builder's `filters`, `sort`, `group` and `layout`, your `toggles`, `timeScopeConfig` and `dateRangeConfigs` (a `ViewOptionInputs`), and optionally `view` (a shared view: the drift dot on the button instead of a count, and the panel's footer), `fieldEditor`, `foldFilters` (true by default), `onClear` (the ✕ and the panel's Clear all; by default each active option cleared through its own `onChange`, the builder's filter rows adding up so every filter clears, or Reset on a shared view; for one change, `settingsCleared(…, "options")`), `widthClassName` and `host`. Its button counts the active options (`countActiveViewOptions`) with a ✕ that clears them. Draws nothing when there is nothing to customize.
93
+ - `ToolbarSort` — the sort panel behind its own button, named `views.panels.sort`: the builder's `sort`, lit (`changed`) while the list sorts other than its default. Draws nothing when nothing sorts.
94
+ - `ToolbarFilter` — the filter list and its drill-ins behind its own button, named `views.panels.filter`: the builder's `filters`, and optionally `timeScopeConfig`, `dateRangeConfigs` and `onClear` (by default every applied filter cleared through the builder's rows, which add up, the last change clearing them all; for one change, `settingsCleared(…, "filters")`). Its button counts what is applied (`countActiveFilters`) with a ✕. Draws nothing with nothing to filter.
95
+ - `ToolbarPanelHost` — a host for a panel part: a component taking `open`, `onOpenChange`, `title` (the part's name) and the panel as `children`.
96
+ - `useToolbarPanelState` — a panel part's state for your app to hold (`ToolbarPanelState`): `open`, `onOpenChange`, `page` and `onPageChange`; closing forgets the page.
97
+ - `ToolbarPanelState` — what `useToolbarPanelState` returns.
98
+ - `FilterPanelContent` — the Filter panel standing alone, for a host of your own: the filter list at its root (titled `views.panels.filter`, no back arrow) and the pages it opens, with `filters`, `timeScopeConfig`, `dateRangeConfigs`, `page`, `onPageChange`, `onClose` and `fill`.
99
+ - `ReadyToolbar` — the toolbar for an app that doesn't arrange its own (`ReadyToolbarProps`): the builder's input (`settings`, `layer`, `columns`, `onChange`, `onLayerChange` and the rest of `SettingsPanelsInput`), and optionally `views`, `viewsLayout`, `showCounts` with `onShowCountsChange` (held by the toolbar, on, when absent), `onAdd` or `addItems` and `addLabel`, `view`, `toggles`, `fieldEditor`, `searchPlaceholder`, `searching` (handed to its search), `hosts` (`{ options, sort, filter }`), `phone`, `narrow` and `className`. It calls the builder and draws the views on the left; search, sort, filter, options and new on the right. Every change comes back as a `ListSettingsChange` or a layer patch: its search writes the settings' search, its ✕s clear in one change (`settingsCleared`), and the active view's menu gains "Edit view…" (`withEditView`), which opens Customize. It holds the three panels' state above its frame, so a change of form keeps a panel open on its page, in a sheet once the form is the phone's. Show counts joins Customize's toggles where the views carry counts, and Group steps aside on a board (`groupShown`).
100
+ - `ReadyToolbarProps` — what `ReadyToolbar` takes.
101
+ - `useListSettingsState` — a list's settings and layer held in memory, for an app that keeps none yet (a proof page, a test): `{ settings, layer? }` in, `{ settings, layer, onChange, onLayerChange }` out, ready to spread into `ReadyToolbar` beside its `columns`. Each change is applied to the latest settings (`applySettingsChange`), each patch merged into the latest layer.
@@ -0,0 +1,123 @@
1
+ # `@viewkitjs/views/panels`
2
+
3
+ Import from `@viewkitjs/views/panels` for what a list's panels read and say: the settings they edit, which sections exist on a viewport, the Group panel's orders, and every row's value in words. The door carries no client directive; its one hook, `useFilterOpened`, carries its own. Every word is a `views.panels.*` key (see [the contract's message keys](../contract.md#message-keys)): each label takes your resolver last and defaults to the package's English. The panels' rows are atoms (`ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow`, `PanelSearch`; see [the atoms](../contract.md#the-atoms)). The panels themselves, which draw under your provider, are [`@viewkitjs/views/panels/react`](./panels-react.md). These two doors are the only ones that may reach dnd-kit, the package's optional peers, once a panel whose list drags joins them: install `@dnd-kit/core`, `@dnd-kit/sortable` and `@dnd-kit/utilities` to use it; an app that takes only the grid never does. This door is pure, so a server file may import it.
4
+
5
+ ## The settings a panel edits
6
+
7
+ - `SortConfig` — a list's sort: its `options`, the `value` and `dir`, the `defaultValue` it resets to, `onChange`, and an optional `label`.
8
+ - `SortOption` — one field a list sorts by: `value`, `label` and the `defaultDir` it opens in.
9
+ - `GroupConfig` — a list's group: its `dimensions`, the `value` (or `"none"`), each dimension's `order` and `granularity`, `onChange`, `hideEmpty` and, while grouped, the `groups` to show, hide and drag.
10
+ - `GroupDimension` — one field a list groups by: its `orderOptions`, `defaultOrder`, and a date's `granularities` and `defaultGranularity`.
11
+ - `GroupOrderOption` — one way a dimension's groups are ordered, with the `defaultDir` it opens in.
12
+ - `GroupListEntry` — one group as the Group panel lists it: its `key`, `label`, and whether it is `empty` or `hidden`.
13
+ - `groupOrderFor` — the order a dimension opens in under a mode: that choice's own direction, else the mode's.
14
+ - `ToggleConfig` — a boolean the panel flips in place: `key`, `label`, `value`, `onChange`, an `icon`, `desktopOnly`, a `reset` back to the reader's default, and the `section` it sits under.
15
+ - `LayoutConfig` — the layouts a list can draw and the active one, with the layouts it refuses and why, its toggles, columns, per-view choices, density, the reader's own section (`personal`) and the phone's own layout.
16
+ - `LayoutColumnsConfig` — the Columns drill-in: the views package's columns, with each column's settings and the card layout's line breaks (`newLine`).
17
+ - `LayoutColumnItem` — one column, with the `settings` its drill-in shows.
18
+ - `LayoutColumnChoice` — a pick-one setting on a column (a currency, decimals).
19
+ - `LayoutViewChoice` — a pick-one setting of the active view, gated by the `views` it means something on.
20
+ - `LayoutDensityConfig` — the active view's row spacing.
21
+ - `LayoutPersonalConfig` — the reader's own settings over a shared view, under their own heading.
22
+ - `TimeScopeConfig` — a time range's choices, with an optional custom range.
23
+ - `DateRangeConfig` — a date range a list filters by: `key`, `label`, `value` (`DateRangeValue`) and `onChange`.
24
+ - `DateRangeValue` — a range's two ends, each a `Date` or `null`.
25
+ - `ActivePanel` — which drill-in is open: a filter (and a Where field inside a relation's), group, sort, time scope, a date range, a toggle, layout, the Filter list, Columns, one column, or Group's by, sort and date-by pages.
26
+ - `ViewOptionInputs` — everything a Customize panel is handed: filters, sort, group, time scope, date ranges, toggles and layout.
27
+ - `CollectionViewState` — the shared view on screen: how far what this person sees drifted from it (`changes`, `stale`), whether they may publish, a write in flight, and the two verbs that settle the drift.
28
+ - `CollectionExportCsv` — a list's export, when it offers one: `count`, the rows it would take, which the Export CSV row shows, and `run`, which builds and downloads the file and says how it went.
29
+ - `isSortActive` — whether a sort differs from its default.
30
+ - `isGroupActive` — whether a list is grouped.
31
+ - `isDateRangeActive` — whether a date range has either end.
32
+ - `countActiveFilters` — how many filter dimensions are filtering: the Filter row's count.
33
+ - `countActiveViewOptions` — the trigger's count: filters, sort, group and date ranges that differ from their defaults.
34
+ - `clearViewOptions` — clears every refinement, keeping each group's order and granularity.
35
+
36
+ ## Which sections exist
37
+
38
+ - `getViewOptionAvailability` — whether a Customize panel has anything to show on the desktop and on the phone.
39
+ - `resolvePersonalSection` — the "For you" section as it draws, or `null` when it has nothing: its label (`views.panels.for-you` unless the layout names one), toggles, choices and reset.
40
+
41
+ ## The Group panel's orders
42
+
43
+ - `groupSortChoices` — each of a dimension's orders in both directions, its own first, then Manual unless `manual` is false, each named by what it does ("Most first", "Newest first", "Alphabetical").
44
+ - `groupSortValue` — a choice's key: the mode and direction, or `"manual"`.
45
+ - `offersManualOrder` — whether the Group panel's sort offers Manual: where its groups can be dragged, or where Manual is already the order.
46
+
47
+ ## Every row's words
48
+
49
+ - `filterValueLabel` — a filter row's value: the conventions it reads ranges and dates with, then your resolver.
50
+ - `relationSentence` — what a relation's filter keeps, in one sentence: "Clients with at least one campaign where status is Active."
51
+ - `dateRangeValueLabel` — a date range's value: "All time", "Jan 1 — Jan 9", "From …", "Until …". Its days are written in the conventions' locale, its optional third argument.
52
+ - `timeScopeRowValueLabel` — a time range's value, a custom range's ends or its label; the ends in the conventions' locale, its optional third argument.
53
+ - `sortValueLabel` — the Sort row's value: "Name desc".
54
+ - `groupValueLabel` — the Group row's value: the dimension's label, or "None".
55
+ - `activeGroupDimension` — the dimension a grouped list is grouped by, or `null`.
56
+ - `groupSortLabel` — the Group panel's Sort row value, a stored order the dimension doesn't offer named in the same words.
57
+ - `groupDateByLabel` — the Group panel's Date by row value.
58
+ - `layoutValueLabel` — the Layout row's value.
59
+ - `filterRowValueLabel` — the Filter row's value: "None", "1 filter", "2 filters".
60
+ - `GROUP_BY_SEARCH_AFTER` — how many dimensions or sort options a page lists before it offers a search (8).
61
+ - `matchGroupDimensions` — the dimensions a Group by page lists for a search.
62
+ - `matchSortOptions` — the options a Sort page lists for a search.
63
+ - `useFilterOpened` — tells a filter row's host it opened, once per row, so the host may ask for what the row offers.
64
+
65
+ ## The views row's axes
66
+
67
+ What a list hands the views row ([`@viewkitjs/views/panels/react`](panels-react.md) draws it).
68
+
69
+ - `ViewTabOption` — one view: its `value`, `label`, `count`, a status `slot` or your own `activeClassName`, its `icon` by your own glyph's name, whether it is `private`, and its verbs as `menu` (the package's menu rows, reached from the active view only).
70
+ - `CollectionViewsConfig` — one axis of views: its `value`, `options`, `onChange`, `hideCounts`, `onCreate` and its `createLabel`, `onReorder` (one block in its new order, folded views included) and `canDrag`.
71
+ - `CollectionViewsInput` — one axis, or an array of peer axes.
72
+ - `ViewsLayout` — how peer axes lay out: `stacked` (each after the first on a row of its own) or `inline`.
73
+ - `CollectionChildAxis` — a child axis whose options depend on the primary selection, as data, for a phone's sheet.
74
+ - `toViewAxes` — the array form of either arity.
75
+ - `splitViewAxes` — the axes split into the primary row and the row a stacked layout pushes beneath.
76
+ - `PillOption` — one of a `PillGroup`'s options: its `value`, `label`, `badge`, a leading glyph, your own active and hover classes, whether it is `private`, and its `menu`.
77
+
78
+ ## The toolbar's arrangement
79
+
80
+ Which form a toolbar draws and where each part stands in it; [`@viewkitjs/views/panels/react`](panels-react.md)'s `Toolbar` draws it. Three forms: `row`, one line with the start and the end cluster and a second line beneath; `narrow`, for a box under 700px on a big screen, the search filling its own line with the end controls beside it and the views flowing on the line under it; and `phone`, one row with the views at the start, or the search filling the row when nothing stands at the start. A part marked as the search is the one the forms move; every other part stands where it asks.
81
+
82
+ - `ToolbarForm` — `"row"`, `"narrow"` or `"phone"`.
83
+ - `ToolbarPlacement` — where a part stands: its `key`, its `side` (`start`, the default, or `end`), its `line` (`1`, the default, or `2`) and `role: "search"` for the search. A second part marked as the search stands as a plain part.
84
+ - `ToolbarSlot` — one part in a line: its `key`, and `fill` when it takes the line's room (the search as a field).
85
+ - `ToolbarLine` — one line: its `kind` (`main`, `search`, `views` or `below`), its `start` and `end` slots, and the `size` its buttons take (`md` or `sm`).
86
+ - `TOOLBAR_NARROW_BELOW` — the box width under which a toolbar is narrow (700).
87
+ - `toolbarForm` — the form from `{ phone, narrow }`: a phone draws its own row whatever its box; a narrow box draws the narrow panel; not measured yet (`null`), the row.
88
+ - `arrangeToolbar` — the parts laid out into lines for a form, in the order they were handed in on each side; a line with nothing on it is dropped.
89
+
90
+ What the toolbar owns over a list's settings:
91
+
92
+ - `SHOW_COUNTS_KEY` — `"show_counts"`, the key of the toolbar's own Show counts.
93
+ - `withCounts` — the views with every axis that doesn't say `hideCounts` itself hiding its counts while Show counts is off.
94
+ - `countsToggle` — the toolbar's own Show counts as a `ToggleConfig` for the Options panel, worded `views.panels.show-counts`: absent when no option carries a number, or when the list's toggles already hold one keyed `show_counts`.
95
+ - `groupShown` — the list's `GroupConfig`, or nothing on a board: when the active layout (the phone's own on a phone) is one the layout's `hidesGroupFor` names.
96
+ - `withEditView` — the views with a row of yours (`ViewsMenuItem`, "Edit view…" in the ready toolbar, worded `views.panels.edit-view`) at the head of the active option's menu on every axis whose active option has a menu, the row after it carrying `separatorBefore`. One config in, one config out; an array, an array. Apply it once to the views your app hands in: applied twice, it adds the row twice.
97
+ - `settingsCleared` — what a toolbar ✕ clears over a list's settings, as one `ListSettingsChange`, or `null` when nothing would change: `"filters"` the Filter panel's rows, `"options"` those, the sort (back to its default) and the group (to none) where Options shows it: on a board the group is the table's and stays untouched, as `groupShown` says (pass `{ phone: true }` to read the phone's own layout). It takes the builder's input without its callbacks. Clearing the builder's rows through their own `onChange` hands several changes, the last of which clears them all (the rows of one build add up); this folds the clear through the builder and hands back one change.
98
+
99
+ ## Built from a list's settings
100
+
101
+ Every panel's config from one value: a list's `ListSettings` (`@viewkitjs/fields/query`), a person's `ListPersonalLayer` over it and the list's columns go in, and each change comes back through `onChange` as a `ListSettingsChange` (only the parts it changes, never empty) or through `onLayerChange` as a layer patch. Your app keeps the settings and the layer where it likes (a saved view, a draft, the link, its own store) and calls the builder again when they move; what is set aside in the settings is kept through every write. Every word is a `views.panels.*` key, worded by the `resolve` you hand in. Each call builds fresh configs and callbacks: memoize it on the settings and the layer, so a panel keeps its identity between renders. The look's toggles show what the person sees (their layer's look over the view's) and write the view's. `columns` are the list's declared columns; a part column the grid derives (its `parts`) is the grid's, and the Filter panel draws its rows under its whole column (`filterData.parts`).
102
+
103
+ - `settingsPanels` — every panel at once: `filters`, `sort`, `group`, `groupBy` (the grid header's), `layout`, and the two writes a list's body makes, `setLaneVisible` (a board lane shown or hidden) and `setFolded` (the groups the person folded, their layer's).
104
+ - `SettingsPanels` — what `settingsPanels` returns.
105
+ - `SettingsPanelsInput` — what every builder takes: `settings`, `layer`, `columns`, `onChange`, `onLayerChange`, and optionally `defaults` (the reader's), `resolve`, `conventions` (the reader's: the Filter rows' country names read its `language`; `ReadyToolbar` hands the provider's), `layouts` (the layouts the list offers, in order), `boardField` and `calendarField` (the fields a board and a calendar take when the settings name none), `rowsShowColumns`, `rowIcon`, `manualOrder` (Sort offers Manual), `defaultSort`, `sortOptions` and `groupDimensions` (a list's own, until it moves onto its fields), `groupHeads` (the answer's groups), `columnIcon`, `columnSettings` (a column's drill-in beyond Visible: its formats, a lock), `filterData` (what the filter rows offer) and `relationFilters`.
106
+ - `PanelGroupHead` — one group of the answer, as the Group panel lists it: `key`, `label`, `count`, `hidden`.
107
+ - `SettingsGroupDimension` — a Group dimension with the `fieldKey` it groups by.
108
+ - `settingsFilters` — the Filter rows: each column's root rule read from the settings' filter, an edit written back with every group, relation rule and set-aside rule kept; a column with no field is a row a saved list can't filter on.
109
+ - `settingsSort` — the Sort panel: the first live sort, a pick writing that one sort with the set-aside ones on other fields kept; with `manualOrder`, Manual first. A place column adds one option per part it sorts by ("Address · City"), keyed by the part key and written as `{ fieldKey, direction, by }`.
110
+ - `settingsGroup` — the Group panel: a new field opens with Hide empty groups on, the same field keeps its groups unless a new granularity re-keys them, and with `groupHeads` the groups to show, hide and drag.
111
+ - `settingsGroupBy` — the grid header's Group by over the settings.
112
+ - `groupDimensionFor` — what a field's Group by offers and opens with, worded through your resolver.
113
+ - `settingsLayout` — the Layout panel: the layouts the columns can draw (the others refused, with why), a switch to a board or a calendar naming its field in the same change, the phone's own layout (the layer's), the look's toggles and density, the Columns list with a card's line breaks, the board's and the calendar's fields, and the reader's own section.
114
+ - `columnStateOf` — the settings' columns as the grid's `ListColumnState`, the person's widths over the view's.
115
+ - `columnsChangeOf` — a column state handed back, as `{ change, layer }`: the settings' columns in its order and visibility, and only the widths that differ in the person's layer.
116
+ - `columnsReset` — the Columns list's reset, as a change.
117
+ - `aggregatesOf` — each placed column's figure, by grid column id.
118
+ - `figuresChangeOf` — the figures picked, as a change; a computed column is never totalled.
119
+ - `seenLook` — the look a person sees: theirs, the view's, then the defaults (the reader's own for vertical borders).
120
+ - `SeenLook` — that look, every setting resolved.
121
+ - `lookChange` — one look setting set on the view, as a change; vertical borders set to the reader's default leaves the view without an answer of its own.
122
+ - `boardFieldOf` — the column a board is laid out by: the settings' field, else the preferred one, else the type rule's.
123
+ - `calendarFieldOf` — the column a calendar is laid out by: the settings' field, else the preferred one, else the first a person can edit.
@@ -7,29 +7,31 @@ 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`. 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.
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, as do the toolbar's panels and the views picker outside a `Toolbar`; 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 ✓, and a toolbar panel's ✕, 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 `gridButtons` (`ViewsGridButtons`, default `own`) says who draws the buttons the grid draws itself: ViewKit, or your `Button`. Its optional `gridCheckboxes` (`ViewsGridCheckboxes`, default `own`) says who draws a yes/no cell's box in the grid: ViewKit's tick box, or your `Checkbox`. Its optional `fieldRowButtons` (`ViewsFieldRowButtons`, default `own`) and `fieldRowCheckboxes` (`ViewsFieldRowCheckboxes`, default `own`) say the same for a field row's own buttons and its yes/no. Its optional `selectionBar` (`ViewsSelectionBarSettings`) says where the selection bar sits. Its optional `oneValue` (`ViewsOneValueEditors`) says whether a single email or domain opens the text box in its cell (the default) or the value list holding one value, in the grid and a field row alike. Its optional `bodyFrame` (`ViewsBodyFrame`, default `views`) says who sets the width and padding of the popover around a whole body your app hands: ViewKit, or, at `popover`, your `Popover`, the popover marked `data-vk-body`. Its optional `datePicks` (`ViewsDatePicks`) names the quick days the date editors offer, in order; absent, today, tomorrow and next Monday.
11
11
  - `EditEscape` — `"cancel" | "keep"`: what Escape does in an edit session (`@viewkitjs/views/editors/session` hands it on too).
12
12
  - `ViewsEscapeRules` — `Partial<Record<FieldType, EditEscape>>`, the provider's `escape`.
13
+ - `ViewsOneValueEditors` — `Partial<Record<"email" | "domain", "text" | "list">>`, the provider's `oneValue`.
14
+ - `ViewsBodyFrame` — `"views" | "popover"`, the provider's `bodyFrame`.
13
15
  - `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.
14
16
  - 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`.
15
17
  - 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.
16
18
  - `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.
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.
19
+ - `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`, `oneValue` and `sayRefusals` when you handed them; and `menus`, how the grid opens its own menus (absent means `popover`); `gridButtons`, who draws the grid's own buttons (absent means `own`); `gridCheckboxes`, who draws a yes/no cell's box (absent means `own`); `fieldRowButtons` and `fieldRowCheckboxes`, the same for a field row (absent means `own`); `selectionBar` and `datePicks` when you handed them.
18
20
  - `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.
19
21
 
20
22
  ## The components map
21
23
 
22
24
  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.
23
25
 
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).
26
+ - `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. Nine 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), `DateBody` (a whole date body your app draws; handed one, the date editor opens it) `PartsBody` (a whole body for a field made of parts; handed one, the name, place and range editors open it), `ValuesBody` (a whole body for several emails, phones, links or domains; handed one, the value list editor opens it), `TextBody` (a whole body for a text typed as one string; handed one, the text editors open it) and `NumberBody` (a whole body for a number, money or a percent; handed one, the number editors open it).
25
27
  - `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.
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`.
28
+ - `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`; and a `ref`, `tabIndex`, `aria-haspopup`, `aria-expanded`, `data-slot` and `data-open`, which the grid hands its own buttons when the provider's `gridButtons` is `button`: forward each to your element; and `aria-disabled`, which a field row's edit target is handed while its write is pending when the provider's `fieldRowButtons` is `button`.
27
29
  - `ViewsPopoverProps` — a popover opened at an `anchor`, controlled by `open` and `onOpenChange`, placed by `side`, `align`, `sideOffset` and `alignOffset`.
28
30
  - Focus: `initialFocus` false keeps focus where it was when the popup opens, for an editor that focuses its own input (with `preventScroll`). Default true.
29
31
  - Vetoes: `onOutsidePress` is handed the pointer press, its `target` where it landed, and returns `false` to keep the popup open, also against the focus that press moves; focus leaving by keyboard closes without asking. `onEscape` does the same for Escape.
30
32
  - 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.
31
33
  - `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.
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`.
34
+ - `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`, `readOnly` (shown as it is and not pressable: a yes/no the grid or a field row can't write while the provider's `gridCheckboxes` or `fieldRowCheckboxes` is `checkbox`), a class, `tabIndex` and `aria-label`.
33
35
  - `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
36
  - `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.
35
37
  - `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).
@@ -37,16 +39,30 @@ The primitives your app hands in, modelled on Base UI's shapes: a controlled `op
37
39
  - `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
40
  - `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.
39
41
  - `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.
42
+ - `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: the provider's `datePicks`, then `none` where it may be emptied), `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 ✓.
43
+ - `ViewsDatePick` — a quick pick a date body offers: `today`, `tomorrow`, `next-monday` (the Monday after today, a week on when today is one), `in-a-week` (today + 7 on the local calendar) or `none`, which empties the field.
44
+ - `ViewsDatePicks` — the provider's `datePicks`: the quick days the date editors offer, in order, any `ViewsDatePick` but `none`. The date editor hands exactly these to your `DateBody` and its own panel draws the same; absent, `today`, `tomorrow` and `next-monday`.
45
+ - `ViewsPartsBodyProps` — a whole body for a field made of parts your app draws, by `kind`. Every kind: `label` (the field's name), `onDone` (no argument closes as Enter does, `"pick"` as a pick), `empty`, `typed`, `autoFocus` and `form` (`phone`: draw no ✕, ✓ or Cancel of your own). `name`: `value` and `onValueChange` over `{ given, family, full }`, `full` handed back as handed unless typed. `place`: `value` and `onValueChange` over `ViewsPlaceParts` (its `regionCode` the editor's), `parts`, `rows`, `words`, `required`, `countries`, `regions` and `opens`. `range`: `value` and `onValueChange` over `{ low, high }`, `decimals`, `unit` and `bands` (drawn as picks, each handing its ends, then `onDone("pick")`). Hand every change as it is made; the editor keeps the draft, Tab, Escape, the save and the phone's ✕ and ✓.
46
+ - `ViewsPlacePart` — a box of a place, besides its country and its region's code: `line1`, `line2`, `postalCode`, `city` or `region`.
47
+ - `ViewsPlaceParts` — a place's parts as a parts body holds them: each `ViewsPlacePart`, `regionCode` and `countryCode`, a string where it holds one.
48
+ - `ViewsValuesBodyProps` — a whole body for a field holding several emails, phones, links or domains your app draws: `label`, `kind` (`email`, `phone`, `url` or `domain`), `value` and `onValueChange` over `ViewsValueLine`s (the whole list, every change as it is made; `[]` for none), `onDone` (closes as Enter does), `check` (a value's reason, or null), `labels`, `holds` (`one` or `several`), `region` (a phone's country), `empty`, `typed`, `autoFocus` and `form` (`phone`: draw no ✕, ✓ or Cancel of your own). The editor keeps the draft, which value is kept as stored, Tab, Escape, the write check, the save and the phone's ✕ and ✓.
49
+ - `ViewsTextBodyProps` — a whole body for a field typed as one string your app draws: `label`, `kind` (`text`, `url`, `domain`, `email`, `phone` or `rich_text`), `paragraph`, `value` and `onValueChange` (the whole text, every change as it is made), `onDone` (closes as Enter does), `check` (a value's reason, or null), `region` (a phone's country), `typed`, `autoFocus` and `form` (`phone`: draw no ✕, ✓ or Cancel of your own). The editor keeps the draft, Tab, Escape, ⌘ or Ctrl Enter, the close's tidy, the write check, the save and the phone's ✕ and ✓.
50
+ - `ViewsNumberBodyProps` — a whole body for a number, money or a percent your app draws: `label`, `kind` (`number`, `money` or `percent`), `value` (a number, `null` empty, `NaN` unreadable) and `onValueChange` (the number and, when it is one of `units`, the unit; every change as it is made), `unit` and `units`, `onDone` (closes as Enter does), `check` (a value's reason, or null), `decimals`, `min`, `max`, `locale`, `decimal`, `empty`, `align`, `typed`, `autoFocus` and `form` (`phone`: draw no ✕, ✓ or Cancel of your own). The editor keeps the draft, the rounding, Tab, Escape, ⌘ or Ctrl Enter, the write check, the save and the phone's ✕ and ✓.
51
+ - `ViewsValueLine` — one value of a values body's list: `value` (its text), `label` where it has one, and `main`.
42
52
  - `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.
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.
53
+ - `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` to draw in its own head: the editor panel's ✕ and ✓, or a toolbar panel's ✕ alone.
54
+ - `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. A toolbar panel's sheet is handed `close` alone, which closes it.
45
55
  - `ViewsSheetAction` — one of them: its `label` (the accessible name) and `onPress`. The glyph is yours.
46
56
  - `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`.
57
+ - `ViewsSeveralValues` — `"first" | "fit"`, the provider's `severalValues`: how a cell of several values draws on one line. `first` (the default) draws its first value and a count at any width, as on 0.5.0; `fit` draws as many whole values as fit its width, then the count, following a column resize.
58
+ - `ViewsGridButtons` — `"own" | "button"`, the provider's `gridButtons`: who draws the buttons the grid draws itself (a group's fold and ⋯, "+ Add column", a row's ⋯, the name's actions, an action column's buttons, a pick-list cell's ▾, a command cell's ▾ and trigger). `own` (the default) draws ViewKit's own, as on 0.5.0; `button` draws your `Button`, handed the grid's box in `className`.
59
+ - `ViewsGridCheckboxes` — `"own" | "checkbox"`, the provider's `gridCheckboxes`: who draws a yes/no cell's box in the grid (the checkbox style). `own` (the default) draws ViewKit's tick box in its own switch button, as on 0.5.0; `checkbox` draws your `Checkbox`, handed `checked`, the column's name, `tabIndex` -1 and `onCheckedChange`, or `readOnly` where the grid can't write.
60
+ - `ViewsFieldRowButtons` — `"own" | "button"`, the provider's `fieldRowButtons`: who draws a field row's own buttons (its edit target, the verb trigger around a value, the lane's ▾, rich text's Show more). `own` (the default) draws ViewKit's, as on 0.5.0; `button` draws your `Button`.
61
+ - `ViewsFieldRowCheckboxes` — `"own" | "checkbox"`, the provider's `fieldRowCheckboxes`: who draws a field row's yes/no box. `own` (the default) draws ViewKit's tick box in its own switch button; `checkbox` draws your `Checkbox`, a Tab stop, or `readOnly` where the row can't write.
62
+ - `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), `desktop` and `phone`, each a `ViewsBarPlacement`, and `chip`, a `ViewsSelectionChip`.
63
+ - `ViewsSelectionChip` — `"own" | "button"`, the provider's `selectionBar`'s `chip`: who draws the selection bar's count chip on the desktop. `own` (the default) draws ViewKit's own, as on 0.5.0; `button` draws your `Button`, `outline`, `sm`, handed its box in `className`.
48
64
  - `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).
65
+ - `ViewsSheetActionsPlace` — where the ✕ and ✓ stand on a phone, the provider's `sheetActions`: `bar` (the default, the panel's own bar, or a toolbar panel's own ✕, inside your sheet) or `head` (handed to your sheet as `actions`, and none drawn inside).
50
66
  - `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).
51
67
  - `ViewsAnchor` — where a floating part attaches: an element, a ref to one, a point `{ x, y }` (a context menu), or `null`.
52
68
  - `ViewsSide` — the side a floating part opens on: `top`, `right`, `bottom` or `left`.
@@ -83,29 +99,36 @@ Guide: [atoms](../guides/atoms.md).
83
99
  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.
84
100
 
85
101
  - `DEFAULT_VIEWS_ATOMS` — the atoms every app starts with, one default per name of `ViewsAtoms`; the provider lays your `atoms` over 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.
102
+ - `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `Avatar`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `RelationRoles`, `CellMore`, `Loading`, `LoadMore`, `PlatformMark`, `RowMenu`, and the panels' rows `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`, the selection's `SelectionSheet`, the filter panel's month `RangeCalendar`, the views row's `Pill`, and the toolbar's `ToolbarButton`. The provider's `atoms` takes any part of it.
87
103
  - `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
104
  - `ViewsCheckRowProps` — toggles one of many, a tick box on the left: `checked`, `onClick`, its `children`, `leading`, `trailing`, `disabled`.
89
105
  - `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
106
  - `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.
107
+ - `ViewsMenuRowProps` — a drill-in row: `icon`, `label`, `value` (where the section stands), `active`, `disabled` and the `disabledReason` your `Tooltip` shows, `onClick`.
108
+ - `ViewsToggleRowProps` — a boolean flipped in place: `icon`, `label`, `active`, `disabled` and the `disabledReason` your `Tooltip` shows, `onClick`, and `reset` (`{ onReset }`), the way back to the reader's default.
93
109
  - `ViewsPanelSearchProps` — a panel's text box: `value`, `onChange`, `onClear`, `placeholder`, `autoFocus`, `onKeyDown`, `onFocus`, `inputRef`, `leading` (`null` drops the magnifier), `suffix` and `inputMode`.
110
+ - `ViewsPillProps` — one option of a row of pills: `active`, `variant` (`solid` or `plain`), `size` (`default` or `sm`), `leading` and `leadingSlot`, your own `activeClassName` and `hoverClassName`, `onClick`, `onContextMenu`, `onPointerDown`, `menuOpen` (it opens a menu) and `ref`.
111
+ - `ViewsToolbarButtonProps` — a toolbar's button: its `icon`, its `label` (its name, and the word a dress shows unless `word` says another, or `null` for none), a `count` in its corner that becomes a ✕ badge clearing what it counts when handed `onClear`, a `dot` drawn instead of a count, `open`, `changed`, `edge` (the row's outermost button), `disabled`, `size` (`md` or `sm`), `popup` (`menu` or `dialog`, with `aria-expanded` from `open`), `onClick`, `onPointerDown` and `ref`.
94
112
  - `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.
95
113
  - `ViewsRowContentProps` — a row's inside, all the row is inside a command list's item, which owns the element, the highlight and the keyboard.
96
114
  - 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.
97
115
  - How it reads: `chosen` draws a trailing check (a chosen row with a `detail` draws the detail in the brand colour and no check), `chosenTint` false keeps a badge label's own colour, `tone` `muted` for a row that offers rather than lists (none, create, add), and `size` `compact` (13px) or `regular` (your menu size, the default).
98
116
  - `ViewsRowProps` — a whole row: everything `ViewsRowContentProps` takes, as a button, or with `interactive` false a static line. It adds `onClick`, `onMouseDown` (for a row inside an editor that keeps its input focused), `disabled`, `title`, a `role` with `aria-selected`, and `opens` and `open` for a row that opens a flyout beside its menu.
99
117
  - `ViewsTickBoxProps` — a paint-only tick box: `checked` and a class. The control around it is the caller's.
100
- - `ViewsStatusBadgeProps` — a pill coloured by a status slot of `@viewkitjs/fields`: its `slot` and `label`, a `leading` mark that replaces the slot's own, a `title`, a `size` (`compact`, 11px, the default, as a status value is drawn in a cell; or `regular`) and a class.
118
+ - `ViewsAvatarProps` — a person's or a record's picture, drawn in a user's, a relation's and an actor's chip (`size: "chip"`) and before the name when the list's `rowIcon` hands the row's `avatar` (`size: "glyph"`, sized by `--vk-glyph`): `label` (whose picture it is, for initials), `avatarUrl` (the picture, when there is one), `kind` (the record's kind as your app names it: a relation's `entity`, `user` for a member, an actor's type) and `fallback` (the glyph the chip or the name draws without a picture). The default draws the picture while it loads and the fallback otherwise; yours may hand back the fallback for a kind it doesn't dress. It only paints: what wraps the chip owns the click.
119
+ - `ViewsStatusBadgeProps` — a pill coloured by a status slot of `@viewkitjs/fields`: its `slot` and `label`, a `leading` mark that replaces the slot's own, a `title`, a `size` (`compact`, 11px, the default, as a status value is drawn in a cell; or `regular`) and a class. It is handed `place` wherever a field's option is drawn (a cell, the select editor, the selection bar): where the status stands among the field's steps.
120
+ - `ViewsStatusPlace` — a status's `place`: `options`, the field's active options in their order (the same array for every cell of a field), and `index`, this one's place in them. A stray or archived value, and a badge that is no option, are handed none.
121
+ - `ViewsStatusOption` — one of those options as a badge is handed it: `value`, `label` and its `slot`.
101
122
  - `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.
102
123
  - `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).
103
124
  - `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.
125
+ - `ViewsRangeCalendarProps` — the filter panel's month, in ISO days: `mode` (`single` or `range`), `from`, `to`, `onSelect` (the selection a press makes, and the day pressed), `armed` (the end the next press sets), `limit`, a painted `window`, `minNights`, a `footer`, `cellSize`, `locale` and `className`. The default is the map's one-day `Calendar` on the end being picked; hand your own to paint a range.
126
+ - `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`. The default draws a disabled verb's `disabledReason` as its row's second line, none while `busy`. Picking a row closes the sheet, then runs it.
105
127
  - `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.
106
128
  - `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.
107
129
  - `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
130
  - `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.
131
+ - `ViewsCellMoreProps` — the count after a cell's shown values: `count`, how many are not shown, and `inert`, true where the host owns the click (the count is plain text, and nothing opens). Drawn inside `data-slot="vk-cell-more"`, a button that opens the whole list. The default, `DefaultCellMore`, draws "+" and the number, and ViewKit keeps its own frame on that element only for it; yours draws inside a bare button (or span), so a count tag of yours stands there alone.
109
132
  - `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.
110
133
  - `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.
111
134
  - `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.