@viewkitjs/views 0.1.0 → 0.3.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 (390) hide show
  1. package/CHANGELOG.md +767 -1
  2. package/README.md +92 -41
  3. package/dist/atoms/LoadMore.js +11 -1
  4. package/dist/atoms/Row.js +1 -1
  5. package/dist/atoms/RowMenu.d.ts +1 -1
  6. package/dist/atoms/RowMenu.js +20 -6
  7. package/dist/atoms/types.d.ts +4 -4
  8. package/dist/cells/cell-format.d.ts +3 -3
  9. package/dist/cells/cell-title.d.ts +1 -2
  10. package/dist/cells/cell-title.js +2 -2
  11. package/dist/cells/cell-values.js +6 -3
  12. package/dist/contract.d.ts +79 -8
  13. package/dist/contract.js +55 -8
  14. package/dist/display/converted.d.ts +19 -0
  15. package/dist/display/converted.js +12 -0
  16. package/dist/display/format.d.ts +16 -1
  17. package/dist/display/format.js +10 -1
  18. package/dist/display/index.d.ts +2 -1
  19. package/dist/display/index.js +2 -1
  20. package/dist/display/link-click.d.ts +11 -0
  21. package/dist/display/link-click.js +3 -0
  22. package/dist/display/link.js +12 -6
  23. package/dist/display/location.d.ts +4 -3
  24. package/dist/display/location.js +12 -5
  25. package/dist/display/multi-value.d.ts +1 -1
  26. package/dist/display/multi-value.js +1 -1
  27. package/dist/display/options.d.ts +8 -2
  28. package/dist/display/percent.js +10 -3
  29. package/dist/display/phone.d.ts +2 -1
  30. package/dist/display/phone.js +11 -2
  31. package/dist/display/relation.js +1 -1
  32. package/dist/editors/ChipsEditor.d.ts +9 -4
  33. package/dist/editors/ChipsEditor.js +7 -3
  34. package/dist/editors/DateEditor.d.ts +21 -6
  35. package/dist/editors/DateEditor.js +118 -30
  36. package/dist/editors/EditorPanel.d.ts +61 -0
  37. package/dist/editors/EditorPanel.js +54 -0
  38. package/dist/editors/LocationEditor.d.ts +3 -0
  39. package/dist/editors/LocationEditor.js +28 -21
  40. package/dist/editors/NameEditor.d.ts +3 -0
  41. package/dist/editors/NameEditor.js +15 -10
  42. package/dist/editors/NumberEditor.d.ts +3 -0
  43. package/dist/editors/NumberEditor.js +7 -7
  44. package/dist/editors/RangeEditor.d.ts +16 -1
  45. package/dist/editors/RangeEditor.js +22 -6
  46. package/dist/editors/RelationEditor.d.ts +13 -28
  47. package/dist/editors/RelationEditor.js +17 -40
  48. package/dist/editors/RelationSetEditor.d.ts +53 -0
  49. package/dist/editors/RelationSetEditor.js +112 -0
  50. package/dist/editors/SelectEditor.d.ts +21 -3
  51. package/dist/editors/SelectEditor.js +55 -9
  52. package/dist/editors/TextEditor.d.ts +51 -0
  53. package/dist/editors/TextEditor.js +81 -0
  54. package/dist/editors/ValueListEditor.d.ts +5 -2
  55. package/dist/editors/ValueListEditor.js +11 -9
  56. package/dist/editors/edit-cores.d.ts +13 -10
  57. package/dist/editors/edit-cores.js +7 -6
  58. package/dist/editors/edit-session.d.ts +21 -11
  59. package/dist/editors/edit-session.js +19 -5
  60. package/dist/editors/keep-inside.d.ts +12 -0
  61. package/dist/editors/keep-inside.js +20 -0
  62. package/dist/editors/open-value.d.ts +21 -0
  63. package/dist/editors/open-value.js +36 -0
  64. package/dist/editors/open-values.d.ts +4 -0
  65. package/dist/editors/open-values.js +7 -0
  66. package/dist/editors/relation-kinds.d.ts +7 -0
  67. package/dist/editors/relation-kinds.js +21 -0
  68. package/dist/editors/relation-panel.d.ts +69 -0
  69. package/dist/editors/relation-panel.js +40 -0
  70. package/dist/field-row/FieldNoteLine.d.ts +14 -0
  71. package/dist/field-row/FieldNoteLine.js +14 -0
  72. package/dist/field-row/FieldRow.d.ts +73 -0
  73. package/dist/field-row/FieldRow.js +157 -0
  74. package/dist/field-row/FieldRowLane.d.ts +19 -0
  75. package/dist/field-row/FieldRowLane.js +11 -0
  76. package/dist/field-row/editors/RowChipsEditor.d.ts +11 -0
  77. package/dist/field-row/editors/RowChipsEditor.js +25 -0
  78. package/dist/field-row/editors/RowDateEditor.d.ts +16 -0
  79. package/dist/field-row/editors/RowDateEditor.js +18 -0
  80. package/dist/field-row/editors/RowEditor.d.ts +39 -0
  81. package/dist/field-row/editors/RowEditor.js +64 -0
  82. package/dist/field-row/editors/RowNameEditor.d.ts +4 -0
  83. package/dist/field-row/editors/RowNameEditor.js +15 -0
  84. package/dist/field-row/editors/RowNumberEditor.d.ts +12 -0
  85. package/dist/field-row/editors/RowNumberEditor.js +18 -0
  86. package/dist/field-row/editors/RowPlaceEditor.d.ts +8 -0
  87. package/dist/field-row/editors/RowPlaceEditor.js +18 -0
  88. package/dist/field-row/editors/RowRangeEditor.d.ts +4 -0
  89. package/dist/field-row/editors/RowRangeEditor.js +15 -0
  90. package/dist/field-row/editors/RowRelationEditor.d.ts +20 -0
  91. package/dist/field-row/editors/RowRelationEditor.js +77 -0
  92. package/dist/field-row/editors/RowSelectEditor.d.ts +13 -0
  93. package/dist/field-row/editors/RowSelectEditor.js +23 -0
  94. package/dist/field-row/editors/RowTextEditor.d.ts +15 -0
  95. package/dist/field-row/editors/RowTextEditor.js +16 -0
  96. package/dist/field-row/editors/RowValueListEditor.d.ts +4 -0
  97. package/dist/field-row/editors/RowValueListEditor.js +21 -0
  98. package/dist/field-row/editors/host.d.ts +59 -0
  99. package/dist/field-row/editors/host.js +1 -0
  100. package/dist/field-row/editors/row-session.d.ts +49 -0
  101. package/dist/field-row/editors/row-session.js +49 -0
  102. package/dist/field-row/index.d.ts +5 -0
  103. package/dist/field-row/index.js +5 -0
  104. package/dist/field-row/row-target.d.ts +20 -0
  105. package/dist/field-row/row-target.js +3 -0
  106. package/dist/field-row/useFieldWrite.d.ts +45 -0
  107. package/dist/field-row/useFieldWrite.js +190 -0
  108. package/dist/field-row/useRowSettlement.d.ts +33 -0
  109. package/dist/field-row/useRowSettlement.js +23 -0
  110. package/dist/fields/binding.d.ts +7 -2
  111. package/dist/fields/binding.js +13 -6
  112. package/dist/fields/currency.d.ts +0 -10
  113. package/dist/fields/currency.js +0 -14
  114. package/dist/fields/edit-core-types.d.ts +9 -9
  115. package/dist/fields/edit-core-types.js +6 -6
  116. package/dist/fields/money.d.ts +6 -0
  117. package/dist/fields/money.js +11 -0
  118. package/dist/fields/number-edit.d.ts +6 -0
  119. package/dist/fields/number-edit.js +4 -0
  120. package/dist/fields/prepare-write.js +6 -1
  121. package/dist/fields/relation-source-types.d.ts +12 -0
  122. package/dist/fields/write-target.d.ts +50 -0
  123. package/dist/fields/write-target.js +10 -0
  124. package/dist/filters/filter-model.d.ts +0 -1
  125. package/dist/filters/registry.d.ts +3 -36
  126. package/dist/filters/registry.js +0 -38
  127. package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
  128. package/dist/grid/chrome/GridAddColumn.js +29 -0
  129. package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
  130. package/dist/grid/chrome/GridAggregateMenu.js +29 -0
  131. package/dist/grid/chrome/GridCellEditors.d.ts +71 -0
  132. package/dist/grid/chrome/GridCellEditors.js +126 -0
  133. package/dist/grid/chrome/GridCellOutline.d.ts +49 -0
  134. package/dist/grid/chrome/GridCellOutline.js +16 -0
  135. package/dist/grid/chrome/GridChipsEditor.d.ts +38 -0
  136. package/dist/grid/chrome/GridChipsEditor.js +35 -0
  137. package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
  138. package/dist/grid/chrome/GridColumnColorSection.js +40 -0
  139. package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
  140. package/dist/grid/chrome/GridColumnDateSection.js +23 -0
  141. package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
  142. package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
  143. package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
  144. package/dist/grid/chrome/GridColumnMenu.js +103 -0
  145. package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
  146. package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
  147. package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
  148. package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
  149. package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
  150. package/dist/grid/chrome/GridColumnSortSection.js +16 -0
  151. package/dist/grid/chrome/GridDateEditor.d.ts +34 -0
  152. package/dist/grid/chrome/GridDateEditor.js +19 -0
  153. package/dist/grid/chrome/GridFlyout.d.ts +44 -0
  154. package/dist/grid/chrome/GridFlyout.js +80 -0
  155. package/dist/grid/chrome/GridFooter.d.ts +33 -0
  156. package/dist/grid/chrome/GridFooter.js +85 -0
  157. package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
  158. package/dist/grid/chrome/GridGroupMenu.js +64 -0
  159. package/dist/grid/chrome/GridHeader.d.ts +66 -0
  160. package/dist/grid/chrome/GridHeader.js +42 -0
  161. package/dist/grid/chrome/GridLongTextEditor.d.ts +55 -0
  162. package/dist/grid/chrome/GridLongTextEditor.js +69 -0
  163. package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
  164. package/dist/grid/chrome/GridMenuRow.js +15 -0
  165. package/dist/grid/chrome/GridNameEditor.d.ts +24 -0
  166. package/dist/grid/chrome/GridNameEditor.js +21 -0
  167. package/dist/grid/chrome/GridNumberEditor.d.ts +49 -0
  168. package/dist/grid/chrome/GridNumberEditor.js +51 -0
  169. package/dist/grid/chrome/GridPlaceEditor.d.ts +26 -0
  170. package/dist/grid/chrome/GridPlaceEditor.js +22 -0
  171. package/dist/grid/chrome/GridRangeEditor.d.ts +30 -0
  172. package/dist/grid/chrome/GridRangeEditor.js +21 -0
  173. package/dist/grid/chrome/GridRelationEditor.d.ts +45 -0
  174. package/dist/grid/chrome/GridRelationEditor.js +92 -0
  175. package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
  176. package/dist/grid/chrome/GridResizeHandle.js +19 -0
  177. package/dist/grid/chrome/GridRow.d.ts +31 -0
  178. package/dist/grid/chrome/GridRow.js +179 -0
  179. package/dist/grid/chrome/GridRowActions.d.ts +32 -0
  180. package/dist/grid/chrome/GridRowActions.js +25 -0
  181. package/dist/grid/chrome/GridRowCells.d.ts +4 -0
  182. package/dist/grid/chrome/GridRowCells.js +128 -0
  183. package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
  184. package/dist/grid/chrome/GridRowGlyph.js +13 -0
  185. package/dist/grid/chrome/GridSelectEditor.d.ts +33 -0
  186. package/dist/grid/chrome/GridSelectEditor.js +43 -0
  187. package/dist/grid/chrome/GridStructure.d.ts +47 -0
  188. package/dist/grid/chrome/GridStructure.js +41 -0
  189. package/dist/grid/chrome/GridTable.d.ts +4 -0
  190. package/dist/grid/chrome/GridTable.js +192 -0
  191. package/dist/grid/chrome/GridTableSurface.d.ts +52 -0
  192. package/dist/grid/chrome/GridTableSurface.js +15 -0
  193. package/dist/grid/chrome/GridTextEditor.d.ts +45 -0
  194. package/dist/grid/chrome/GridTextEditor.js +38 -0
  195. package/dist/grid/chrome/GridValueListEditor.d.ts +30 -0
  196. package/dist/grid/chrome/GridValueListEditor.js +19 -0
  197. package/dist/grid/chrome/StuckMarker.d.ts +16 -0
  198. package/dist/grid/chrome/StuckMarker.js +34 -0
  199. package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
  200. package/dist/grid/chrome/cell-clipboard.js +28 -0
  201. package/dist/grid/chrome/cell-cut-off.d.ts +11 -0
  202. package/dist/grid/chrome/cell-cut-off.js +20 -0
  203. package/dist/grid/chrome/cells.d.ts +21 -0
  204. package/dist/grid/chrome/cells.js +19 -0
  205. package/dist/grid/chrome/checks.d.ts +32 -0
  206. package/dist/grid/chrome/checks.js +32 -0
  207. package/dist/grid/chrome/column-glyph.d.ts +14 -0
  208. package/dist/grid/chrome/column-glyph.js +44 -0
  209. package/dist/grid/chrome/editors.d.ts +9 -0
  210. package/dist/grid/chrome/editors.js +10 -0
  211. package/dist/grid/chrome/grid-cell-classes.d.ts +53 -0
  212. package/dist/grid/chrome/grid-cell-classes.js +32 -0
  213. package/dist/grid/chrome/grid-cell-link.d.ts +13 -0
  214. package/dist/grid/chrome/grid-cell-link.js +9 -0
  215. package/dist/grid/chrome/grid-edit-session.d.ts +63 -0
  216. package/dist/grid/chrome/grid-edit-session.js +118 -0
  217. package/dist/grid/chrome/grid-hover.d.ts +60 -0
  218. package/dist/grid/chrome/grid-hover.js +81 -0
  219. package/dist/grid/chrome/grid-menu-focus.d.ts +43 -0
  220. package/dist/grid/chrome/grid-menu-focus.js +93 -0
  221. package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
  222. package/dist/grid/chrome/grid-menu-search.js +7 -0
  223. package/dist/grid/chrome/grid-row-menu-key.d.ts +15 -0
  224. package/dist/grid/chrome/grid-row-menu-key.js +36 -0
  225. package/dist/grid/chrome/grid-row-props.d.ts +143 -0
  226. package/dist/grid/chrome/grid-row-props.js +1 -0
  227. package/dist/grid/chrome/grid-row-window.d.ts +61 -0
  228. package/dist/grid/chrome/grid-row-window.js +212 -0
  229. package/dist/grid/chrome/grid-scroll-owner.d.ts +38 -0
  230. package/dist/grid/chrome/grid-scroll-owner.js +75 -0
  231. package/dist/grid/chrome/grid-styles.d.ts +40 -0
  232. package/dist/grid/chrome/grid-styles.js +9 -0
  233. package/dist/grid/chrome/grid-table-props.d.ts +172 -0
  234. package/dist/grid/chrome/grid-table-props.js +1 -0
  235. package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
  236. package/dist/grid/chrome/useGridBatchApi.js +35 -0
  237. package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
  238. package/dist/grid/chrome/useGridColumnLayout.js +206 -0
  239. package/dist/grid/chrome/useGridFocus.d.ts +45 -0
  240. package/dist/grid/chrome/useGridFocus.js +122 -0
  241. package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
  242. package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
  243. package/dist/grid/chrome/useGridKeyboard.d.ts +64 -0
  244. package/dist/grid/chrome/useGridKeyboard.js +450 -0
  245. package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
  246. package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
  247. package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
  248. package/dist/grid/chrome/useGridRailReveal.js +67 -0
  249. package/dist/grid/chrome/useGridRangeActions.d.ts +51 -0
  250. package/dist/grid/chrome/useGridRangeActions.js +195 -0
  251. package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
  252. package/dist/grid/chrome/useGridRangeGestures.js +237 -0
  253. package/dist/grid/chrome/useGridRowContextMenu.d.ts +37 -0
  254. package/dist/grid/chrome/useGridRowContextMenu.js +153 -0
  255. package/dist/grid/chrome/useGridScaleStyles.d.ts +3 -0
  256. package/dist/grid/chrome/useGridScaleStyles.js +28 -0
  257. package/dist/grid/chrome/useGridScrollArea.d.ts +21 -0
  258. package/dist/grid/chrome/useGridScrollArea.js +65 -0
  259. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +78 -0
  260. package/dist/grid/chrome/useGridTableInteractionModel.js +249 -0
  261. package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
  262. package/dist/grid/chrome/useGridTableSelection.js +55 -0
  263. package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
  264. package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
  265. package/dist/grid/core/clipboard-model.d.ts +83 -0
  266. package/dist/grid/core/clipboard-model.js +291 -0
  267. package/dist/grid/core/column-values.d.ts +27 -0
  268. package/dist/grid/core/column-values.js +76 -0
  269. package/dist/grid/core/commit-model.d.ts +41 -0
  270. package/dist/grid/core/commit-model.js +3 -0
  271. package/dist/grid/core/coordinates.d.ts +48 -0
  272. package/dist/grid/core/coordinates.js +27 -0
  273. package/dist/grid/core/edge-scroll.d.ts +21 -0
  274. package/dist/grid/core/edge-scroll.js +23 -0
  275. package/dist/grid/core/edit-values.d.ts +9 -0
  276. package/dist/grid/core/edit-values.js +1 -0
  277. package/dist/grid/core/editing-controller.d.ts +60 -0
  278. package/dist/grid/core/editing-controller.js +266 -0
  279. package/dist/grid/core/editing-model.d.ts +87 -0
  280. package/dist/grid/core/editing-model.js +148 -0
  281. package/dist/grid/core/flat-rows.d.ts +35 -0
  282. package/dist/grid/core/flat-rows.js +20 -0
  283. package/dist/grid/core/grid-aria.d.ts +27 -0
  284. package/dist/grid/core/grid-aria.js +39 -0
  285. package/dist/grid/core/grid-focus.d.ts +54 -0
  286. package/dist/grid/core/grid-focus.js +148 -0
  287. package/dist/grid/core/grid-scale.d.ts +14 -0
  288. package/dist/grid/core/grid-scale.js +8 -0
  289. package/dist/grid/core/nav.d.ts +94 -0
  290. package/dist/grid/core/nav.js +92 -0
  291. package/dist/grid/core/pending-reconciliation.d.ts +53 -0
  292. package/dist/grid/core/pending-reconciliation.js +51 -0
  293. package/dist/grid/core/range-model.d.ts +25 -0
  294. package/dist/grid/core/range-model.js +59 -0
  295. package/dist/grid/core/row-window.d.ts +40 -0
  296. package/dist/grid/core/row-window.js +43 -0
  297. package/dist/grid/core/spreadsheet-operations.d.ts +101 -0
  298. package/dist/grid/core/spreadsheet-operations.js +280 -0
  299. package/dist/grid/core/useGridEditing.d.ts +46 -0
  300. package/dist/grid/core/useGridEditing.js +93 -0
  301. package/dist/grid/core/useGridRange.d.ts +20 -0
  302. package/dist/grid/core/useGridRange.js +24 -0
  303. package/dist/grid/core/value-equality.d.ts +54 -0
  304. package/dist/grid/core/value-equality.js +80 -0
  305. package/dist/grid/index.d.ts +18 -0
  306. package/dist/grid/index.js +5 -0
  307. package/dist/grid/useGridTablePrefs.d.ts +49 -0
  308. package/dist/grid/useGridTablePrefs.js +99 -0
  309. package/dist/index.d.ts +1 -1
  310. package/dist/index.js +1 -1
  311. package/dist/internal/viewport.d.ts +3 -0
  312. package/dist/internal/viewport.js +15 -0
  313. package/dist/model/column-capabilities.d.ts +3 -2
  314. package/dist/model/column-capabilities.js +28 -8
  315. package/dist/model/column-from.js +3 -0
  316. package/dist/model/column-inspect.d.ts +10 -2
  317. package/dist/model/column-inspect.js +9 -0
  318. package/dist/model/column-schema.d.ts +6 -1
  319. package/dist/model/column-state.d.ts +1 -1
  320. package/dist/model/column-types.d.ts +3 -1
  321. package/dist/model/column-types.js +1 -1
  322. package/dist/model/density.js +3 -3
  323. package/dist/model/filter-capabilities.d.ts +1 -1
  324. package/dist/model/filter-capabilities.js +1 -1
  325. package/dist/model/index.d.ts +4 -6
  326. package/dist/model/index.js +0 -1
  327. package/dist/model/preferences.d.ts +7 -7
  328. package/dist/model/preferences.js +0 -1
  329. package/dist/model/prefs-buckets.d.ts +0 -1
  330. package/dist/model/prefs-buckets.js +0 -3
  331. package/dist/model/render-count.d.ts +6 -0
  332. package/dist/model/render-count.js +11 -0
  333. package/dist/provider/ViewsProvider.d.ts +6 -2
  334. package/dist/provider/ViewsProvider.js +12 -2
  335. package/dist/provider/components.d.ts +35 -9
  336. package/dist/provider/components.js +4 -2
  337. package/dist/provider/context.d.ts +8 -4
  338. package/dist/provider/desktop.d.ts +9 -0
  339. package/dist/provider/desktop.js +22 -0
  340. package/dist/provider/menu-groups.d.ts +8 -0
  341. package/dist/provider/menu-groups.js +38 -0
  342. package/dist/provider/plain-input.d.ts +8 -0
  343. package/dist/provider/plain-input.js +5 -0
  344. package/dist/provider/ports.d.ts +22 -0
  345. package/dist/provider/ports.js +1 -0
  346. package/dist/react.d.ts +3 -2
  347. package/dist/react.js +1 -0
  348. package/dist/selection/SelectCheckbox.d.ts +3 -1
  349. package/dist/selection/SelectCheckbox.js +2 -2
  350. package/dist/selection/useCheckDragSelect.js +6 -5
  351. package/docs/contract.md +202 -72
  352. package/docs/getting-started.md +250 -0
  353. package/docs/guides/atoms.md +245 -0
  354. package/docs/guides/cells.md +302 -0
  355. package/docs/guides/columns.md +413 -0
  356. package/docs/guides/display.md +204 -0
  357. package/docs/guides/editors.md +462 -0
  358. package/docs/guides/ports.md +246 -0
  359. package/docs/guides/selection.md +270 -0
  360. package/docs/guides/the-grid.md +696 -0
  361. package/docs/guides/the-provider.md +448 -0
  362. package/docs/index.md +52 -0
  363. package/docs/install.md +9 -47
  364. package/docs/reference/cells.md +28 -0
  365. package/docs/reference/display.md +44 -0
  366. package/docs/reference/editors-chips.md +6 -0
  367. package/docs/reference/editors-date.md +6 -0
  368. package/docs/reference/editors-location.md +10 -0
  369. package/docs/reference/editors-name.md +6 -0
  370. package/docs/reference/editors-number.md +11 -0
  371. package/docs/reference/editors-open-values.md +10 -0
  372. package/docs/reference/editors-panel.md +12 -0
  373. package/docs/reference/editors-range.md +6 -0
  374. package/docs/reference/editors-relation.md +12 -0
  375. package/docs/reference/editors-select.md +9 -0
  376. package/docs/reference/editors-session.md +11 -0
  377. package/docs/reference/editors-text.md +9 -0
  378. package/docs/reference/editors-value-list.md +6 -0
  379. package/docs/reference/editors.md +5 -0
  380. package/docs/reference/field-row.md +16 -0
  381. package/docs/reference/grid.md +39 -0
  382. package/docs/reference/react.md +89 -0
  383. package/docs/reference/selection.md +33 -0
  384. package/docs/reference/views.md +622 -0
  385. package/package.json +27 -4
  386. package/skills/views/SKILL.md +20 -5
  387. package/dist/filters/types.d.ts +0 -27
  388. package/dist/filters/types.js +0 -1
  389. package/dist/model/filter-pushdown.d.ts +0 -106
  390. package/dist/model/filter-pushdown.js +0 -147
@@ -0,0 +1,622 @@
1
+ # `@viewkitjs/views`
2
+
3
+ The root door is the model half of the package, and it reaches no React at runtime, so a server module may import it. It holds two things. The rendering contract: every slot, state, token, component, atom, port and icon name and every message key, as typed constants, with the English resolver for the keys ([the contract](../contract.md) says what each name means). And the model every view reads: what a column is and what may be done to it, a list's preferences and view rules, filters, figures and groups, and the field modules the columns stand on: bindings, money and currency, a write's preparation, the edit cores' types, format knobs, relation sources and a field's verb menus.
4
+
5
+ The rendering itself is behind the other doors: the provider and the atoms at [`/react`](react.md), the display at [`/display`](display.md), the editors at [`/editors`](editors.md), cells at [`/cells`](cells.md), selection at [`/selection`](selection.md) and the grid at [`/grid`](grid.md).
6
+
7
+ ## The rendering contract
8
+
9
+ Guide: [the provider](../guides/the-provider.md).
10
+
11
+ - `VK_PREFIX` — the prefix `"vk"`, worn by everything that shares a global namespace: the CSS variables (`--vk-*`) and the `data-slot` values (`vk-grid-row`). States are bare `data-*` attributes, and message keys live under `views.*` ([the contract](../contract.md)).
12
+ - `GRID_SLOTS` — every `data-slot` value the grid draws, from `vk-grid` (the frame) to `vk-grid-aggregate-menu`, in the order of the [contract's Slots table](../contract.md#slots). A skin styles a part through its slot, never through a class name the package happens to use.
13
+ - `GridSlot` — one member of `GRID_SLOTS`.
14
+ - `GRID_STATES` — the flags the grid styles, each a `data-*` attribute present when true (`focused`, `selected`, `editing`, `in-range`, `range-edge`, `pending`, `invalid`, `dragging`, `empty`, `frozen`, `scrolled`, `parked`), as the [contract's States table](../contract.md#states) lists them with where each sits.
15
+ - `GridState` — one member of `GRID_STATES`.
16
+ - `VK_TOKENS` — the CSS variables the package owns and sets on the grid's frame: geometry and density (`--vk-scale`, `--vk-row-h`, the paddings, the text sizes, the 0-or-1 flags `--vk-scrolled`, `--vk-parked` and `--vk-frozen-on`). A skin reads them and an app overrides them on the frame ([Tokens](../contract.md#tokens)).
17
+ - `VkToken` — one member of `VK_TOKENS`.
18
+ - `VK_COLOURS` — the colours the rendering paints, each a CSS variable your app declares (`--vk-fg`, `--vk-ground`, `--vk-brand`, `--vk-border` and the rest). The package sets none of them and names no variable of your own; you map each onto your tokens once ([Tokens](../contract.md#tokens)).
19
+ - `VkColour` — one member of `VK_COLOURS`.
20
+ - `VK_OPTIONAL_COLOURS` — the status hues (`--vk-success`, `--vk-warning`, `--vk-info`) and the category hues (`--vk-label-blue` to `--vk-label-teal`) the default atoms and the display read when your app declares them, each with a built-in fallback ([Tokens](../contract.md#tokens)).
21
+ - `VkOptionalColour` — one member of `VK_OPTIONAL_COLOURS`.
22
+ - `VK_OPTIONAL_LAYOUT` — the layout your app may declare, each read with a `0px` fallback: `--vk-gutter`, the side padding your page gives its content, which the grid's rows line their content up with; and `--vk-scroll-inset-bottom`, how much of the grid's foot your app covers with something it floats there (a phone's bottom bar), so the grid's scroll area runs underneath it and its last row scrolls clear of it ([Tokens](../contract.md#tokens)).
23
+ - `VkOptionalLayout` — one member of `VK_OPTIONAL_LAYOUT`.
24
+ - `VK_INTERNAL` — the grid's own variables, set and read by the grid alone: `--vk-drag-shift`, a header cell's offset while its column is dragged. Prefixed because they share the global namespace, and not public: your app neither sets nor reads them, and they may change in any release.
25
+ - `VkInternal` — one member of `VK_INTERNAL`.
26
+ - `VK_INTERNAL_FAMILIES` — the grid's internal variable families, a prefix with one variable per key after it: `--vk-col-w-<id>`, one column's resolved width, set on the grid's root for every visible column. Not public, like `VK_INTERNAL`.
27
+ - `COMPONENT_NAMES` — the primitives your app hands in through the provider: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command`, `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown` ([the components map](../contract.md#the-components-map)).
28
+ - `ComponentName` — one member of `COMPONENT_NAMES`.
29
+ - `OPTIONAL_COMPONENT_NAMES` — the primitives your app may leave out, each with a plain default the provider fills: `Input` ([the components map](../contract.md#the-components-map)).
30
+ - `OptionalComponentName` — one member of `OPTIONAL_COMPONENT_NAMES`.
31
+ - `ATOM_NAMES` — the pieces the rendering is built from, and the pieces of your app's own it cannot draw itself (a command cell's verb menu, the row's right-click menu, where a relation goes, a wait, how a list asks for more). Each ships as a default, and your app swaps any of them through the provider's `atoms` ([the atoms](../contract.md#the-atoms)).
32
+ - `AtomName` — one member of `ATOM_NAMES`.
33
+ - `ATOM_SLOTS` — the `data-slot` values the default atoms mark themselves with, prefixed like the grid's (`vk-row`, `vk-tick`, `vk-status`, `vk-row-menu` …) ([the atoms](../contract.md#the-atoms)).
34
+ - `AtomSlot` — one member of `ATOM_SLOTS`.
35
+ - `EDITOR_SLOTS` — the `data-slot` values the editor panel marks its parts with, prefixed like the grid's (`vk-editor-panel`, `vk-editor-bar`, `vk-editor-refusal`) ([the editor panel](../contract.md#the-editor-panel)).
36
+ - `EditorSlot` — one member of `EDITOR_SLOTS`.
37
+ - `ATOM_STATES` — the default atoms' states: `chosen`, `disabled`, `muted`, `checked` and `open` are flags present when true, `status` carries the status slot's name and `platform` a link's platform key ([the atoms](../contract.md#the-atoms)).
38
+ - `AtomState` — one member of `ATOM_STATES`.
39
+ - `PORT_NAMES` — the runtime services your app hands in through the provider: `toast`, `haptics`, `clipboard`, `viewPrefs` and `confirm` ([Ports](../contract.md#ports)).
40
+ - `PortName` — one member of `PORT_NAMES`.
41
+ - `ICON_NAMES` — the glyphs the rendering asks your app for, by what they mean, never by a library's name: the field types, who did it, the actions, navigation and order, the figures and the grid's menus. Your app maps each to its own icon component ([Icons](../contract.md#icons)).
42
+ - `ViewsIconName` — one member of `ICON_NAMES`.
43
+ - `MESSAGE_NAMESPACES` — the four namespaces every visible string the package owns is keyed under: `views.grid`, `views.editors`, `views.menus` and `views.display`.
44
+ - `ViewsMessageNamespace` — one member of `MESSAGE_NAMESPACES`.
45
+ - `ViewsMessage` — a message the package emits: its `key` and, where it has any, the `values` a resolver may interpolate (`{ key: "views.editors.tag-remove", values: { label } }`), never a sentence. The union is closed, so a new key is a compile error in every exhaustive resolver that has not worded it. A string `@viewkitjs/fields` already keys stays a fields message. The keys and their values are listed in [the contract](../contract.md#message-keys).
46
+ - `ViewsMessageKey` — the key of a `ViewsMessage`: the union of every message key.
47
+ - `VIEWS_MESSAGE_KEYS` — every message key as a list, the same set as `ViewsMessageKey`, for code that walks the keys (a test that your resolver words each one).
48
+ - `ViewsMessageResolver` — what your app hands in as its wording: a function from a `ViewsMessage` to the string to show. A resolver that words only some keys calls `resolveViewsMessage` for the rest; the provider does not fall back for it.
49
+ - `resolveViewsMessage` — the package's English, one line per key: takes a `ViewsMessage` and returns its sentence with its values in place. Every function in the package that takes a `messages` resolver defaults to it.
50
+ - `PlaceWordKey` — the message keys that name a place's word: the region, city or postal-code word a country's address format uses (`views.editors.place-region-county`, `views.editors.place-postal-zip`).
51
+ - `placeWordKey` — the message key for a place's word: takes the kind (`region`, `city` or `postal`) and the word `@viewkitjs/fields` names in a country's format, and returns the `PlaceWordKey`. `placeWordKey("region", "county")` is `views.editors.place-region-county`; an underscore in the word becomes a hyphen.
52
+
53
+ ## Columns
54
+
55
+ Guide: [columns](../guides/columns.md).
56
+
57
+ A column is plain data: what a list shows in one place for every row, how it reads the row, and what may be done to it. The grid, the board and the other views all read the same `ListColumn`.
58
+
59
+ - `ListColumn` — one column's declaration, generic over your row type. It requires `id`, `header` (a node) and `width` (the starting width every columnar view sizes from; what a person drags it to lives in their preferences). The optional members, by what they are for:
60
+ - Reading the row: `accessor` (the value the cell draws, compares and copies), `editAccessor` (the stored value an editor opens on, where the display read carries fallbacks), `aggAccessor` (the number the footer totals), `render` (a custom cell, handed the row and a `RenderedValue`), `indicator`, `actions` (buttons on the cell, `ListCellAction`).
61
+ - What the value is: `type` (`ListColumnType`), `options` (`ListColumnOption`), `multiple` (the cell holds several values), `labels: false` (a list whose rows keep only values, so its editor offers no label box), `region` (the record's country read off the row, where a phone typed, pasted or filled without its country code is read), `chips.normalize` (the rule that turns typed text into a stored multiselect value), `relation` (a relation's candidates: a `source`, or static `options`, and the default `entity` kind), `nameFallback` (the words a name column draws for a row with an empty name), `format` (`ListColumnFormat`), `align`, `icon`.
62
+ - Money: `currencyAccessor` (each row's own currency code, winning over `format.currency`), `surfaceOwnsCurrency` (the column, not the row, says which currency every figure is in), `money` and `reading` (a convertible column's declaration and the reading in force), `editUnit` (the unit picker beside the number editor).
63
+ - The footer: `defaultAggregate`, `footerKinds` (the picks the footer offers, `none` always among them), `footerField` (the field whose figures the footer reads when it is not the column's own), `aggregateSuffix` (the unit drawn after a figure), `ratio` (a ratio's numerator and denominator, summed and divided once).
64
+ - Order and splitting: `sortKey` (the key a sort hands your host), `sortable: false` (the source has no order for it), `bucketable: false` (take it out of Group by and Board by).
65
+ - Per view: `defaultHidden`, `grid` (`minWidth`, `maxWidth`), `card.zone` (`ListCardZone`), `list` (the rows view's `hidden`, `track`, and the title cell's `subtitle`, `avatar` and `inlineActions`).
66
+ - Writing: `editable`, `clearable`, `reasons` (full sentences for why an edit or a clear is absent, shown by the refusal and by a settings readout), `marker` (a marker boolean's badge `label`, panel `title` and per-row `reason`), `custom` (a derived value, `{ from }` completing "Computed from …"), `command` (changes only through the entity's verbs; the cell opens the verb menu).
67
+ - The field: `field` (the definition the column presents, which the write gate asks to accept a value) and `binding` (how that field reads and writes this row). `columnFrom` sets both.
68
+ - `ListColumnType` — a column's type: a field's value type (a rollup or formula column is its result's type), or `title`, the one column role, for the text a row is called.
69
+ - `fieldTypeOf` — the storage type behind a column: a bound column answers with its field's value type, a field-less one with its own `type`, and a `title` or untyped column reads as `text`. The format knobs and the query rules are keyed by it.
70
+ - `temporalKindOf` — whether a column's dates are calendar days (`date`) or instants (`datetime`), read from `fieldTypeOf`.
71
+ - `RenderedValue` — what the grid hands a custom `render` beside the row: `value`, the column's figure as its `accessor` reads it, and `code`, the currency that figure is in. A custom money cell draws that reading and converts nothing.
72
+ - `ListColumnOption` — one option of a select, status or multiselect column: its `value`, and optionally its `label`, its status `slot`, its category `color`, its stage `mark` (when the option is a position on a ladder, drawn in place of the plain dot) and `archived` (out of every picker, still drawn on a row that holds it).
73
+ - `ListSelectColor` — an option's category colour: one of the design palette's category hues.
74
+ - `ListStatusSlot` — a status slot from the design palette, as an option or a cell action names it.
75
+ - `ListRelationValue` — one relation value, already resolved by your host: the contract's `RelationValue` (`id` compared and committed but never shown, `label` shown, sorted and copied, `entity` handed back when the chip is opened, `avatarUrl`) plus an optional per-value `icon`, for a column whose rows point at different kinds. The grid never turns an id into a label itself.
76
+ - `ListCellAction` — a button drawn in a cell: its `id`, an `icon` for the row, and optionally a `label`, an `onClick` handed the row and the click, and a `status` slot that tints it.
77
+ - `ListCardZone` — where a column lands on a card: `title`, `chips`, `figures`, `footer` or `body`. The board's type defaults decide it for almost every column; `card.zone` overrides it. `body` is prose, never a default, and draws only on a card laid out roomy enough for a sentence.
78
+ - `ListAggregateKind` — a footer figure: `none`, `sum`, `avg`, `min`, `max`, `count`, `filled`, `unique` or `ratio`. `ratio` is sum over sum as a percent, offered only by a column that carries `ratio`.
79
+
80
+ ## A column from a field binding
81
+
82
+ Guide: [columns](../guides/columns.md).
83
+
84
+ - `columnFrom` — builds a `ListColumn` from a field binding and a `ColumnPresentation`. It carries the binding's reads onto the column (`accessor`, `editAccessor`, the unit picker, the relation candidates), derives the type (the field marked as the identity is the `title`), header, options, format, reasons, alignment (a number, percent or currency right-aligns unless you set `align`), clearability and shape facts from the field, and attaches both `field` and `binding`. The column is editable when the binding writes and its type has an editor; the presentation may only take that away, with `editable: false` or a `reasons.editable`. A derived field marks the column `custom`, a command field marks it `command`. Throws `FieldDefinitionError` when the declaration contradicts itself: a hand-written `custom`, an `aggAccessor` without its own `accessor`, `editable: true` on a binding with no write, or `editable: true` beside a `reasons.editable`. A binding whose unit states rates gives a convertible money column, returned already read on the reading it opens on.
85
+ - `ColumnPresentation` — what a column declares that neither the field nor the binding can know: everything on `ListColumn` except the keys `columnFrom` derives. `header` is optional and defaults to the field's label. `accessor` may override the binding's read (a figure converted for display; the binding still maps the write) or be `null` for a cell that draws itself and offers no comparable value: the column then carries no accessor, its filter row is listed but inert, and the editor still opens on the stored value.
86
+ - `moneyDeclarationFor` — `columnFrom`'s convertible-money step: takes the binding and the presentation's `id`, `accessor`, `aggAccessor` and `format.currency`, and returns the column's `MoneyDeclaration` (the amount and total in the row's own currency, the row's code, the rates, and the reading the column opens on), or `undefined` for a binding with no rates. Throws `FieldDefinitionError` at build time for a field that is not a currency, a fixed-code currency, an `accessor: null`, or an opening that is not a reading (`original`, `EUR`, `USD`, `RON` or `default`).
87
+
88
+ ## How a column's value reads
89
+
90
+ - `ListColumnFormat` — how a column's value is drawn. Numbers: `style` (`plain`, or `duration`, a number stored in `unit`, milliseconds by default, and drawn as a span), `decimals`, `suffix`, `signed` and `signedTone` (`positive-good`, the default, tints a positive figure as good; `neutral` does not), `currency` (one code for the whole column). Dates: `dateStyle`, `withTime`; durations: `durationStyle`; percents: `percentDisplay`; text: `long` (a paragraph, read and edited in a panel). Booleans: `booleanDisplay`, which is a write policy as much as a look: `checkbox` (the default, a two-way flip), `icon` (a flip drawn with the column's own `icon(on)` glyph), `text` (the column's two words from its options, read-only) or `marker` (an exception raised elsewhere: nothing drawn when false, and the only write is resolving it to false). `ignoresOverrides` says a custom `render` does not read the format settings, so the menus withhold knobs it would ignore.
91
+ - `ListDateStyle` — how a date reads: `short`, `long`, `numeric` or `relative`.
92
+ - `ListDurationStyle` — how a duration reads: `adaptive`, `clock` or `units`; the same union the duration formatter in `@viewkitjs/fields` implements.
93
+ - `ListNumberFormatState` — one field's number setting: `decimals` and, on a convertible money column, the `currency` reading in force and the `currencyOptions` the header menu offers.
94
+ - `ListNumberFormatOverrides` — the number settings by field key.
95
+ - `ListDateStyleOverrides` — the date style chosen for each field, by field key.
96
+ - `ListDurationStyleOverrides` — the duration style chosen for each field, by field key.
97
+ - `ListShowTimeOverrides` — whether each date-and-time field shows its time, by field key.
98
+ - `ListPercentDisplayOverrides` — how each percent field draws (as a number, a bar or a ring), by field key.
99
+ - `ListOptionColorOverrides` — the colour chosen for an option, by field key and then by option value. Every override map is keyed by field key, because a format is the workspace's answer about a field, shared by every surface that draws it.
100
+ - `LIST_DECIMALS_CHOICES` — the decimal places a number column can be shown at, `0` to `4`, offered by both the header menu and the Columns panel.
101
+ - `columnKnobs` — the format knobs a column offers, one answer for the header menu and the Columns panel: the field's type says which knobs exist and the column only takes away (no duration style on a plain number, no decimals on a duration, a currency reading only on a convertible money column). A field-less column, or a custom `render` that declares `ignoresOverrides`, offers none. Returns a set of knob kinds (`dateStyle`, `showTime`, `durationStyle`, `decimals`, `currency`, `percentDisplay`).
102
+
103
+ ## Type rules
104
+
105
+ What the machinery may do with each column type, declared once per type so a new type cannot be added without answering every question.
106
+
107
+ - `GRID_TYPE_RULES` — the rule for every `ListColumnType`: which editor it mounts, which filter editor it opens, how a paste becomes its value and what a written value must look like. A boolean has no editor and is still writable; an actor has no editor and takes no paste; a location opens the place editor and takes no paste.
108
+ - `GridTypeRule` — one type's rule: `editor` (a `GridEditorId`, or `null` for none), `filter`, `paste` and `value`.
109
+ - `typeRule` — the rule for a type, or `null` for a column that declares no type.
110
+ - `GridEditorId` — which editor a writable column mounts when clicked, Entered or typed into: `text`, `select`, `number`, `date`, `relation`, `chips`, `range`, `name`, `values` (several emails, phones, links or domains, each with its label and a main one) or `place` (the country first, then its parts).
111
+ - `ListFilterEditor` — which editor a column opens in the filter panel: `options`, `text`, `number`, `date`, `boolean`, `range`, or `none` (listed, opens nothing).
112
+ - `GridPasteKind` — how a pasted clipboard cell becomes a commit: `text`, `option` (the pasted text matched against an offered option's label or key, exact before ignoring case, an in-grid copy landing on the exact option it copied, a label two options share refused), `number`, `date`, `boolean`, `relation` (the pasted label matched against the candidates, committing the id), `list` (the text split into several values, each read as an `option` is on a column of options), `range` (an in-grid pair, or text read as a range is written: "11–50", "10,001+", "up to 50"), or `none` (the type refuses paste).
113
+ - `GridValueKind` — what a written value must look like for a type: `any`, `email`, `url`, `boolean`, `relation` or `list`. `gridNormalizeWrite` holds a value to it.
114
+ - `gridPasteKind` — how a paste becomes this column's value. A `multiple` column pastes as a `list` when it presents a field of a type that keeps several values, and takes no paste otherwise; any other column answers with its type's rule. Returns `null` for a column with no type.
115
+ - `resolveGridRelation` — reads a raw relation value as a `ListRelationValue`, filling in the column's default kind (`relation.entity`) where the value names none; a value's own `entity` wins. Returns `null` for a value that is not a relation.
116
+ - `gridRelationSource` — the candidates the relation picker offers for a column: its `relation.source`, or a static list of its `relation.options`. Given an `entityIcon` resolver, each candidate without an icon of its own wears its kind's glyph, both in a static list and in each page a remote search returns; without one, the candidates come back untouched.
117
+
118
+ ## What may be done to a column
119
+
120
+ Three layers decide a write, and each may only take away from the one before: the column's declaration, the workspace's settings for the list (`ListSettingsConfig`), and a person's preferences. The `columnEffective…` and `gridColumnEffective…` answers apply the first two together, and are the ones a write gate asks.
121
+
122
+ - `gridEditorKind` — the editor a column mounts, or `null`: none unless the column is `editable` and typed. A `multiple` column mounts `values` for the four types that keep several values and nothing for any other; a `title` whose field is a name mounts `name`; a `location` column mounts `place` when its field is a place, whose parts the editor reads, and nothing without one; any other column mounts its type's editor.
123
+ - `gridColumnHasEditor` — whether a column mounts an editor: the question a click, a double-click, Enter or typing asks. A boolean answers false and is still writable, which is why `columnWritable` is a separate answer.
124
+ - `columnWritable` — whether a column can be written by any route (an editor, Delete, Clear, a fill, a paste), by its declaration alone: false for a derived (`custom`) or `command` column and for one not `editable`; otherwise true when it mounts an editor or is a boolean. Gate sites ask `columnEffectiveWritable`, which adds the workspace's locks.
125
+ - `gridBooleanMode` — a boolean column's write model: `marker` (one-way, true to false) for a `marker` display, `toggle` for every other; `null` for a column that is not a boolean.
126
+ - `ListSettingsConfig` — the workspace's settings for one list, which your host stores and hands the grid as `listConfig`: `readOnly` (no cell writes anywhere) and `columns`, a lock per field keyed by `lockKeyOf`. Sparse: an absent key leaves the declaration in force, and a key matching no field or column is inert. It constrains the interface, not access: your host's routes still guard their own writes.
127
+ - `ListColumnConfig` — one entry of `ListSettingsConfig.columns`: `locked`, which stops every write through every route while display, sort, hide and resize stay.
128
+ - `toggleListColumnLock` — returns a new `ListSettingsConfig` with the lock under the key you pass turned on or off, dropping empty maps so the config stays sparse. One builder for every surface that edits locks.
129
+ - `toggleListReadOnly` — returns a new `ListSettingsConfig` with the whole list's read-only lock turned on or off (off is the key absent).
130
+ - `lockKeyOf` — the key a column's lock is stored under: its field's key, so one lock holds on every surface that draws the field; a column with no field keeps its own id.
131
+ - `gridColumnLocked` — whether the workspace's settings lock a column: the list is read-only, or the column's key is locked. False with no config.
132
+ - `columnEffectiveWritable` — `columnWritable` and not locked: the writable answer every gate site uses.
133
+ - `gridColumnEffectiveClearable` — whether a column accepts Clear, Cut or Delete-to-empty: effectively writable and `clearable`.
134
+ - `gridClearRefusal` — why a clear was refused, as the toast says it: the lock (`views.grid.locked`) when the declaration would allow the clear but the workspace locks the column, otherwise `columnClearRefusal`'s sentence. Takes the column, the config and a resolver that defaults to `resolveViewsMessage`.
135
+ - `columnClearRefusal` — why a column can't be emptied, by its declaration alone: its `reasons.clearable`, else `views.grid.not-clearable`. A settings readout shows it as it is; the toast adds the lock case through `gridClearRefusal`.
136
+ - `columnEditRefusal` — why a column can't be edited, in the person's words: its `reasons.editable`, else the cause its field names (derived, system-set, provider-owned, create-only), else "Computed from …" for a `custom` column; `undefined` when there is no sentence to say. Takes the column, the conventions and a resolver that defaults to `resolveViewsMessage`.
137
+ - `gridEditRefusal` — why the grid won't edit a column: the workspace's lock first, then `columnEditRefusal`. The one sentence a refused gesture and a refused commit both say.
138
+ - `gridNormalizeWrite` — the write gate every route passes through once: coerces a value by the column's type, then, when the column presents a field, has the field accept it. A `multiple` column reads text as a list; a boolean reads `yes`, `1`, `true` and their opposites, and a marker refuses true; an email or a url is trimmed and must look like one (a url with `http://` or `https://`); a relation commits what its row stores: an id, a ref `{ kind, id }` on a column that presents its field, or a relation holding several records' whole set (ids or links), each id refused outside a static candidate list, and an emptied set becomes the field's empty value; a multiselect commits the whole set, trimmed and without duplicates, and a clear as `[]`. An emptied value passes unchecked, since `clearable` decides whether a clear may run. Options: `region` (where a phone typed without its country code is read), `messages` (defaults to `resolveViewsMessage`) and `stored` (the value before the edit, so a value kept as stored is not read again). Returns a `GridWriteResult`.
139
+ - `GridWriteResult` — what `gridNormalizeWrite` returns: `{ ok: true, value }` with the value to commit, or `{ ok: false, reason }` with the sentence to show.
140
+ - `columnLabel` — a column's name for a toast or a readout: its header when that is a non-empty string, else its id made readable by `prettifyOptionValue`.
141
+
142
+ ## Reading a cell in full
143
+
144
+ - `isLongTextColumn` — whether a column holds a paragraph rather than a phrase: a `text` column with `format.long`, or a `rich_text` column. It reads and edits in the anchored long-text panel rather than the one-line input.
145
+ - `gridColumnInspectable` — whether a cell opens a panel to be read in full, whatever its write state, so a long text that can't be edited can still be read. Long text is the one kind that always does; a cut-off line does when its cell cuts it off (`isWholeTextColumn`).
146
+ - `isWholeTextColumn` — whether a column's text opens whole in that panel when its cell cuts it off: a plain `text` (not a paragraph) and a `title` that is text, not a person's name. Links, emails, phones and domains keep their one-line box.
147
+ - `gridTextOpensBox(column, whole)` — whether an open text cell is drawn in the panel over the cell rather than in the cell: a paragraph always, a line when it was opened `whole` (cut off when it opened).
148
+
149
+ ## Column state
150
+
151
+ What a person changes about the columns (which are shown, in what order, at what width) is a `ListColumnState`, stored by your host and handed back to the grid.
152
+
153
+ - `ListColumnState` — a person's columns for one view: `widths` by column id, `hidden` ids, `visible` ids (columns hidden by default that they turned on), `order`, and `breaks` (the board only: ids that start a new line on a card; present, even empty, is their own layout). The grid ignores `breaks`.
154
+ - `ListColumnItem` — one column as a list that shows and hides columns reads it: `id`, `label`, `icon`, `hidden`, `hideable`, and `fixed` for a column a saved view cannot hide or reorder.
155
+ - `ListColumnsConfig` — a view's columns with what may be done to them: the `items`, `onToggleHidden`, `onReorder`, and optionally `onReset` and `dirty`. The grid's "+ Add column" lists the hidden ones from it, and a host's own add-column (`renderAddColumn`) is handed the same.
156
+ - `columnHideable` — whether a column can be hidden: every column but the `title`.
157
+ - `columnDefaultHidden` — whether a column is hidden until asked for, in the view asking: the rows view (`viewId` `"list"`) reads `list.hidden` when the column states it; every other view reads `defaultHidden`.
158
+ - `isColumnHidden` — whether a column is hidden in a state, for a view: never the `title`; hidden when its id is in `hidden`; a column hidden by default stays hidden unless its id is in `visible`.
159
+ - `toggleColumnHidden` — returns a new `ListColumnState` with a column shown or hidden. A column hidden by default is toggled through `visible`, any other through `hidden`, the same key `isColumnHidden` reads back for that view; an emptied list is dropped.
160
+ - `resolveColumnOrder` — the declared columns in a stored order: the ids the order names first (an unknown id dropped), and each column the order leaves out placed after its nearest declared neighbour that is placed. An empty order returns the declaration.
161
+ - `resolveVisibleColumns` — the columns a view draws: in the state's order, without the hidden ones, and never none (the first column stays when every column is hidden).
162
+ - `resolveColumnWidths` — each visible column's width by id: its stored width, held to its bounds, or its declared `width`.
163
+ - `clampColumnWidth` — a width held between a column's `grid.minWidth` (default `LIST_DEFAULT_MIN_WIDTH`) and its `grid.maxWidth`, rounded to a whole pixel.
164
+ - `LIST_DEFAULT_MIN_WIDTH` — the narrowest a column can be dragged when it states no `grid.minWidth`: 60 pixels.
165
+ - `computeMinWidth` — the width a set of columns needs: their widths summed, plus the gutter you pass.
166
+ - `ListDensity` — the density every view shares: `compact`, `default` or `spacious`. Each view spends it its own way; the grid scales its pixels, the rows views widen their padding.
167
+ - `prettifyOptionValue` — a stored code made readable: underscores and hyphens become spaces and each word starts with a capital (`on_hold` reads `On Hold`).
168
+
169
+ ## What a saved view places
170
+
171
+ - `columnManagedByView` — whether a saved view can store a column's filters, sorts and totals: only a column that presents a field.
172
+ - `columnPlacedByView` — whether a saved view can place a column (its position, width and visibility): a column that presents a field, or a computed (`custom`) column, which the view stores under its id. A computed column still never filters, sorts, groups or totals.
173
+ - `VIEW_FIELDLESS_FILTER_REASON` — the English sentence for why a saved view cannot filter on a column that presents no field.
174
+ - `resolveViewColumnOrder` — the column ids in the order a saved view draws them: the columns the view places take the view's requested order among their own slots (an unknown or repeated id dropped); a field column it does not name follows the ones it does; a computed column it does not name, and every column it cannot place, keeps its declared slot.
175
+ - `baseColumnOrder` — the complete order a Move or a header drag rewrites, which is the order the grid draws: `resolveViewColumnOrder` on a saved view, `resolveColumnOrder` off one. Returns column ids.
176
+
177
+ ## Sorting and grouping
178
+
179
+ - `effectiveSortKey` — the key a column sorts by, or `undefined`. `sortable: false` offers none; a declared `sortKey` always wins. Without one, on a saved view (`viewBacked`), a bound column with an `accessor` sorts by its field's key, except a location or rich text, which have no order; off a saved view a column sorts only by a declared key, since your host owns the comparator there.
180
+ - `sortableColumns` — the Sort options a saved view offers, one per sort key in the columns' order (the first column that presents a key keeps it). With `parts: true`, each order of a value beyond its whole sort follows its column, keyed `partKey(fieldKey, by)`. Returns `SortableEntry` items.
181
+ - `SortableEntry` — one Sort option: its `key`, the `column` it sorts by and, for one order of a value, that order (`by`). The sort a host stores is `{ fieldKey, direction, by }`.
182
+ - `columnGroupable` — whether a column offers Group by on a saved view: it presents a field of a type that can split a list, and the list has not set `bucketable: false`.
183
+ - `groupableColumns` — the columns a saved view can group by, one per field, in the columns' order.
184
+ - `groupableOrders` — the Group dimensions: one per field and, with `parts: true`, one per order a type groups by, keyed `partKey(fieldKey, by)`. Without `parts`, exactly `groupableColumns`' columns keyed by field key. Returns `GroupableEntry` items.
185
+ - `GroupableEntry` — one Group dimension: its `key`, the `column` it groups by and, for one order of a value, that order (`by`). The axis a host stores is `{ fieldKey, by }`.
186
+ - `sortDirFor` — the direction a sort by a field opens in: a date, a number or a yes/no largest or newest first (`desc`), text and options A to Z (`asc`), and a date that looks ahead, such as a due date, soonest first.
187
+
188
+ ## Filters on a column
189
+
190
+ The filter panel's rows come from the columns themselves: every column is listed, in the person's column order, and its type decides what its row opens.
191
+
192
+ - `buildColumnFilters` — builds the filter panel's rows from a list's columns and returns them as filter configs. Each column gives one row in the person's `order`, opening its type's editor and reading and writing `rules` through `onRuleChange`; a column with no `accessor` is listed but opens nothing. A `declared` filter whose `key` matches a column id takes that column's row in place, and one matching no column is appended. A column `capabilities` marks unavailable is listed with its reason. A hidden column keeps its row and its rule under `HIDDEN_COLUMN_SECTION`. The other inputs:
193
+ - Options: `selectValues` (the values a select's editor offers), `relationValues` (the relations present in the rows), `knownValues` and `knownLabels` (the values and names your host read for an open field, a relation, a user or an actor, offered ahead of those on screen), and `onValuesWanted`, called when such a row opens so your host can fetch them.
194
+ - Reading: `decimals` (what each number cell shows, so equality rounds as the eye does), `columnState` and `viewId` (what "hidden" means for this view), `icon` (each row's glyph), `messages` and `conventions`.
195
+ - `parts: true` adds one row per part of a value right under its column ("Location · Country"), keyed `partKey(columnId, part)`; a location's whole-value row gives way to its parts.
196
+ - `filterEditor` — the filter editor a column's type opens (`ListFilterEditor`), or `null` for an untyped column.
197
+ - `booleanFilterOptions` — a boolean column's two filter choices, worded as its cell is: a marker reads its `marker.label` (or its header) and "Not …", a `text` display reads its two option labels (True and False by default), and a checkbox reads Checked and Unchecked.
198
+ - `numberDecimals` — the decimals a number cell shows, so a filter's equality rounds to what is on screen: `0` on an integer field, else the override for its field key, else its `format.decimals`, else `2`.
199
+ - `rowMatchesRules` — whether one row satisfies every filter rule, reading each value through its column's `accessor`. Rules join with AND and an inactive rule matches everything. A column with no accessor is skipped, and a key that is no column's id is read as a part row's. An absent boolean counts as false; picked options join with OR, and a multiselect matches when any of its values was picked; a relation compares by id and an actor by its key. Takes the row, the rules, the columns, the decimals each cell shows and the conventions.
200
+ - `HIDDEN_COLUMN_SECTION` — the section label, "Hidden columns", that `buildColumnFilters` puts a hidden column's row under.
201
+
202
+ ## Declaration warnings
203
+
204
+ Mistakes a column declaration can make that nothing else catches, returned as lists so the caller can name the offenders, for a warning while a page is written.
205
+
206
+ - `unknownSortKeys` — every `sortKey` the columns declare that your host's sort options do not name. A typo sorts by whatever your comparator does last, and a missing option shows as its raw key in the toolbar. Takes the columns and the sort options (`{ value }`) and returns the unknown keys.
207
+ - `columnsClaimingAbsentEditors` — the ids of columns that declare `editable` for a type nothing opens an editor for, a promise the grid quietly drops. A column presenting a field whose type has an edit core counts as editable; booleans are left out, since they write without an editor.
208
+
209
+ ## The row icon
210
+
211
+ - `ListRowIconAccessor` — what a list declares as `rowIcon` for the leading glyph in each row's title cell: a function from a row to an icon name for the neutral default, a `ListRowIcon` to tint it, or `null` to draw none for that row.
212
+ - `ListRowIcon` — a row icon as a descriptor: `icon`, your app's own name for the glyph, which your `AppIcon` draws, and an optional `tone`. The grid owns its size and colour.
213
+ - `ListRowIconTone` — a row icon's tint: a status slot, asked for by name, because a coloured row icon says something about state. Without one the glyph draws in the secondary text colour.
214
+ - `normalizeRowIcon` — reads either answer a `ListRowIconAccessor` gives as a `ListRowIcon`: a bare name becomes `{ icon }`, a descriptor stays as it is, and `null` stays `null`.
215
+
216
+ ## Render counting
217
+
218
+ A diagnostic for a performance log: it counts only in a browser whose `localStorage.perf` is `"1"`, and costs nothing otherwise.
219
+
220
+ - `countRowRender` — adds one to the count; the grid's rows call it each time one renders, so a list that re-renders with the same rows reads 0.
221
+ - `takeRowRenders` — returns the count and starts it again from zero. Under React's StrictMode a development build renders twice, so compare the number with itself, never with the row count.
222
+
223
+ ## Bindings
224
+
225
+ Guide: [columns](../guides/columns.md).
226
+
227
+ A binding says how one field reads and writes on one entity's row. Your app declares it once per entity, and every surface (a grid column, a panel row, a board card) derives from it, never stating its own accessor or write. Three things stay apart: the field's key, the binding (this row) and the storage column (the request body's business).
228
+
229
+ - `bindField` — binds one field: takes the field and its spec, freezes them together and runs `checkBinding`. The field passed always wins over a `field` a wider spec happens to carry. Throws `FieldBindingError` on a broken binding, where it is made.
230
+ - `bindFields` — binds a whole registry: takes the registry and one spec per field key, and returns the frozen `BoundFields`. It throws `FieldBindingError` for a field with no spec. A worked-out name that names its rename, and any worked-out field that names a stored field it is edited through, is bound to edit as that stored field: the edit read opens on the stored value, or on the value shown while the stored one is empty, and the stored field's write, history, unit and candidates carry over. A renamed name handed back unchanged while the stored field is empty reaches the stored write as the stored value. Binding an edit read on the worked-out field itself throws: it belongs on the stored field.
231
+ - `checkBinding` — holds one binding to its field and throws `FieldBindingError` when it breaks a rule; `bindField` runs it for you. It refuses:
232
+ - a write on a `command` field (its verbs change it), or on any field whose mutability is not `always`;
233
+ - a history without a write;
234
+ - a unit on a field whose value is not a currency or a number;
235
+ - candidates on a field that is not a relation or a user;
236
+ - a writable currency amount whose code is read off the row, bound without its unit;
237
+ - a ratio formula bound without its two readers, and ratio readers on anything else;
238
+ - a labels choice on a field that does not hold several values;
239
+ - a writable relation with no candidates;
240
+ - a `create` row on a member field (a member is invited, not created), on any field but a relation, or without a `write`.
241
+ - `bindingWritable` — says whether a binding is writable in principle: it declares a write and its field's mutability is `always`. A `command` field answers false: every surface opens its verbs instead of an editor.
242
+ - `FieldBinding` — one field bound to a row:
243
+ - what it binds and reads: `field`, the field; `read`, the display value (a relation reads its resolved value); and `editRead`, the stored value when it differs (a relation's id, the raw value behind a fallback);
244
+ - how it writes: `write` maps a commit onto a `FieldPatch`, the request body or a refusal with the reason the surface shows, and absent, the field is never writable on any surface; `history`, a `FieldHistoryAdapter`, covers a write that also moves companion state;
245
+ - what its editor needs: `unit`, a `FieldUnit`, for an amount whose code is the row's (the number editor's unit chip is a picker only with it); `region`, the record's country read off the row, where a phone typed without its country code is read (absent, the conventions' region); `relation`, a writable relation's candidates as a `RelationSource`; `create`, a relation's `RelationCellCreate` (refused on a member field, on any field but a relation, and without a `write`). A writable relation that stores refs or links binds, and the grid and a record's field row save it in its stored shape; a surface built on `RelationEditor` alone (a card, a form field) commits one bare id, so it can't save such a relation yet; and `labels: false` on a field holding several values that keeps only the values, so its editor offers no label box;
246
+ - how it draws and totals: `icon`, your app's own icon name for the field, drawn by the host (the type's glyph when absent); and `ratio`, a ratio formula's two parts read off the row, which a footer sums.
247
+ - `FieldBindingSpec` — a `FieldBinding` without its `field`: what `bindField` and `bindFields` take for each field.
248
+ - `BoundFields` — what `bindFields` returns: a frozen binding for every key of the registry, each typed to its own field.
249
+ - `FieldUnit` — a per-row unit: `read`, the row's code (the unit chip's value), and `options`, the codes the chip offers. With `rates`, the row's own multipliers into every readable currency, a surface may read the field in another currency: the binding then states every accessor in the row's own currency, never converted, and the list converts (`readMoneyColumn`). Without it the field is read in its own currency only.
250
+ - `FieldHistoryAdapter` — the inverse of a write whose effect reaches beyond the field: `capture` takes a snapshot of the row, `equals` compares two, and `restore` maps a snapshot back onto a `FieldPatch`, given the snapshot it expects to find. The snapshot is opaque to the surfaces: `restore` validates its own shape, and a patch that returns a `storedValue` also passes the field's stored-value gate.
251
+ - `fieldHistory` — takes an adapter typed with its own snapshot and returns it as a `FieldHistoryAdapter` whose snapshot is opaque, so a binding keeps its private type while the surfaces see none. It changes nothing at runtime.
252
+ - `FieldBindingError` — the error a broken binding throws; its message names the field's key and the rule it breaks (`binding: "<key>": <why>`).
253
+
254
+ ## A write's preparation
255
+
256
+ Every surface prepares a commit the same way before it sends anything. Both functions are pure, take an optional surface last (whether it is writable at all, the sentence it refuses in, and your conventions, `DEFAULT_CONVENTIONS` when it states none), and word every refusal through the conventions' messages.
257
+
258
+ - `prepareFieldWrite` — prepares one commit: takes the binding, the row and the commit, and returns a `PreparedFieldWrite`. It refuses when the surface is not writable (the surface's sentence, else `field.cannot-edit`) or the binding is not (the field's own reason, else `field.cannot-edit`). It then judges the commit (`acceptFieldCommit`, with the unit's options, the binding's `region` for this row and, for a phone, a url, a multiselect or a relation, the value stored before the edit, so a closed multiselect keeps the values it already holds and a relation link the role it was stored with), runs the binding's write, refuses a skip with its reason (else `field.cannot-save`), and judges the stored value (`acceptStoredFieldValue`). A number, percent, currency or datetime commit is a composite, so its write must say the stored value, or the result is `field.stored-value-required`. Only `body` is ever sent.
259
+ - `prepareFieldRestore` — prepares the restore of a history entry: takes the binding, the row, the snapshot and the value it expects to find, and runs the same surface gate. A binding with no history is refused with `field.history-unavailable`, and a restore that skips with its reason (else `field.restore-refused`). A restore that names a stored value passes the stored-value gate; one that does not keeps the snapshot as its stored value.
260
+ - `PreparedFieldWrite` — what both return: `{ ok: true, body, storedValue }`, with an optional `settlement`, the binding's account of what the write achieves (`requested` when the body lands locally and a provider still has to accept it; the transport's result may upgrade it to `confirmed`), or `{ ok: false, reason }`.
261
+ - `FieldWriteContext` — how a write arrived: `{ kind: "commit" }`, or `{ kind: "restore", expected }`, a history restore that names the value it expects and is refused once the row has moved on.
262
+ - `PreparedRowEdit` — one admitted edit of an operation across cells of one row, such as a paste or a fill: its `columnId`, its `value` and its `FieldWriteContext`. A binding that groups a row's edits into one request names this shape.
263
+ - `GroupedRowWrite` — one request for every admitted edit of a same-row operation: `body`, and `historyColumnId`, the cell whose history snapshot covers the whole operation. The other cells stay confirmed and leave the history entry, so Undo sends exactly one restore.
264
+
265
+ ## A write's target
266
+
267
+ The shapes a record's field writes go through, plain values with no React, so a write target and its tests read none of the rendering. `@viewkitjs/views/field-row` re-exports them beside the row and `useFieldWrite`.
268
+
269
+ - `FieldWriteReconciliationRequired` — thrown by a write target when a save may have landed but no confirmed row came back: the row warns, `refresh` runs, and no write is admitted until a new row arrives. Its `outcome` is `"saved-unconfirmed"` or `"uncertain"`, and its `warning` is the sentence shown.
270
+ - `EntityWriteTarget` — where a record's commits go: `save(rowId, body)`, resolving an `EntityWriteReceipt`, and `noun`, the record's singular name for toasts.
271
+ - `EntityWriteReceipt` — a save's answer: the confirmed `row`, an optional `warning`, and an optional `settlement` (`"requested"` draws the value pending until the next row arrives).
272
+ - `FieldWriteAdmission` — a commit's immediate answer: `{ accepted: false, reason }`, or `{ accepted: true, completion }`, the save's promise.
273
+ - `FieldWriteAdmissionGuard` — a function that refuses every write with a reason, or `null` to admit.
274
+ - `LockedResolver` — a field key to the reason it's locked on this surface, or `null`.
275
+ - `FieldNote` — a value's note: its `text`, and an optional `quote` it rests on.
276
+
277
+ ## Relation candidates
278
+
279
+ The types a relation's candidates are built from. A binding's `relation` names them, and `@viewkitjs/views/editors/relation` re-exports them beside the editor that pages through them.
280
+
281
+ - `RelationSource` — where a relation's candidates come from: `{ kind: "static", items }`, a whole list your app already holds, with nothing to page; or `{ kind: "remote", search, pageSize }`, a search your app runs, with the empty query when the panel opens, then per typed query, then a page at a time as the list scrolls to its end. `pageSize` must match what your search asks its route for: a full page is the only sign there may be more.
282
+ - `RelationCandidate` — one thing a relation can point at, already resolved by your app: its `id` (compared, stored and committed, never shown), its `label` (shown, and what a static list matches on), and optionally a `sublabel` (a muted second line that tells two same-named rows apart), a `badge` (a muted word at the row's right edge, for a list of several kinds), an `icon` (a glyph of its own, which wins over the host's glyph for its kind), an `avatarUrl` and a `kind` (what a pick stores with the id, on a list of several kinds).
283
+ - `RelationCellCreate` — a create row your app hands a relation's binding, for a record not in the list yet: `label(query)` gives its words from the trimmed query, and `onCreate(query, link)` runs after the picker closes, so your own form opens with what was typed; call `link(id, kind?)` when that form saves, and the surface links the new record as a change of its own, with its own undo (on a relation holding several records, added to the set the editor saved). The grid links only a record its candidates offer: with a static list, add the new record to it before calling `link`.
284
+ - `RelationSearch` — your app's search: takes the query, an abort signal (it aborts on the next query and when the panel closes) and the offset, how many rows the panel already holds for this query, and resolves to the next candidates.
285
+
286
+ ## A field's verb menu
287
+
288
+ A `command` field changes only through its entity's verbs: a transition that carries rules of its own (a reason, an end date) cannot be a picker. Every surface opens the same verb menu instead of an editor, and your app supplies the verbs. The [contract](../contract.md) names the menu each surface draws.
289
+
290
+ - `FieldMenus` — field key to the verbs a row offers instead of an editor, resolved per row so the list follows the record's state. `GridTable` takes it as `commands`; a `command` column with no verbs wired is a read-only badge, never an empty menu.
291
+ - `FieldRowMenuItem` — one verb: its `label`, its `onClick`, and optionally an `icon`, `destructive` and `disabled`.
292
+
293
+ ## Edit cores and number editing
294
+
295
+ Guide: [editors](../guides/editors.md).
296
+
297
+ - `EDIT_CORE_TYPES` — every field type, mapped to whether it has an editor of its own: true for the dates, the options, relations, users, the numbers, places, names, ranges and the text types; false for the rest. It answers the question without loading the editors, and it agrees with `EDIT_CORES` on `@viewkitjs/views/editors` by construction.
298
+ - `hasEditCore` — says whether a field type has an editor of its own (the text-like types share the text editor), so a host can skip wiring an editor it does not need.
299
+ - `numberEditDecimals` — the decimals a number-shaped field edits at, the same on every surface: zero for an integer field, else the field's own decimals, else zero for a percent and two for money and plain numbers.
300
+ - `numberEditCode` — the code a money field's amount is typed in when the field fixes one (`code: { fixed }`), for the number editor's `code`; nothing for any other field, a money field whose currency is per record included.
301
+ - `durationUnitOf` — the unit a duration field stores (milliseconds when the field names none), or undefined for any other field.
302
+
303
+ ## Format knobs
304
+
305
+ The display settings a field offers its reader, decided by its type. A knob writes the reader's own format overrides, never the view, so a field reads the same in every view. Option colours are not knobs: they belong to each value, not the field.
306
+
307
+ - `FORMAT_KNOBS` — every field type, mapped to its knobs in the order a panel draws them: a number's decimals and duration style, a percent's display and decimals, money's decimals and the currency it is read in, a date's style, and an instant's style and time. Every other type reads one way and offers none; a lookup, rollup or formula answers through `formatKnobsForField`.
308
+ - `formatKnobsFor` — the knobs a field type offers, as a set.
309
+ - `formatKnobsForField` — the knobs a field offers: those of the value it shows (a rollup's or a formula's result), with no decimals for an integer field. Whether a knob is live on a given column stays the column's call; a currency reading needs a binding that states rates.
310
+ - `FormatKnobKind` — one knob: `dateStyle`, `showTime`, `durationStyle`, `decimals`, `currency` or `percentDisplay`.
311
+ - `FormatKnobs` — one type's entry in `FORMAT_KNOBS`: its `knobs`, in drawing order.
312
+
313
+ ## Money and currency
314
+
315
+ Money is stored in the currency each row was entered in, and a column is read either way: every row in its own currency (the Original reading), or every row converted into one display currency by the row's own rate. These pieces import nothing with React in them, so a server-side reader can use them too.
316
+
317
+ - `SUPPORTED_CURRENCIES` — the currencies money may be denominated in: EUR, USD, RON and GBP. One list for every picker, so no currency is selectable on one surface and refused on another.
318
+ - `SupportedCurrency` — one of `SUPPORTED_CURRENCIES`.
319
+ - `CURRENCY_OPTIONS` — `SUPPORTED_CURRENCIES` as a picker's options, `{ value, label }` with the code as its label: what a registry's currency select takes.
320
+ - `isSupportedCurrency` — says whether a code is one of `SUPPORTED_CURRENCIES`, for a row read back untyped; false for null.
321
+ - `DisplayCurrency` — a currency a column can be read into: EUR, USD or RON, the set every row's rates convert into.
322
+ - `DEFAULT_DISPLAY_CURRENCY` — the display currency when the reader has chosen none: EUR.
323
+ - `DISPLAY_CURRENCY_OPTIONS` — the display currencies as options, symbol first (`€ EUR`): the reader's default-currency picker, where Original is not an answer.
324
+ - `isDisplayCurrency` — says whether a stored value is a display currency.
325
+ - `ORIGINAL_READING` — `"original"`: the reading that keeps each row in its own currency. It is not a currency code, so it never collides with one.
326
+ - `MoneyReading` — how a reader reads a money column: `ORIGINAL_READING` or a display currency.
327
+ - `MONEY_READING_OPTIONS` — the readings as a menu's rows, Original first, then the display currencies.
328
+ - `isMoneyReading` — says whether a value is a `MoneyReading`.
329
+ - `FxMap` — a row's own multipliers into every display currency, filled by your data layer from the rate of the row's day.
330
+ - `FxRateError` — the error a conversion throws when a row that has a currency carries no usable rate, a data bug never covered by a guess; its message starts `rate:`.
331
+ - `convertRowAmount` — converts an amount of the row's currency into a display currency by the row's own rate: takes `{ currency, fx }`, the amount and the target. Null for an empty or non-finite amount and for a row with no currency; throws `FxRateError` when the rate is missing, not finite or not above zero.
332
+ - `MoneyOpensOn` — what a money column declares it opens on: a `MoneyReading`, or `"default"` for the reader's own default currency.
333
+ - `isMoneyOpensOn` — says whether a value is a `MoneyOpensOn`.
334
+ - `resolveOpensOn` — the reading a column opens on for this reader: its declared reading, or the reader's default currency for `"default"`.
335
+ - `MoneyDeclaration` — what a money column declares so it can be read in another currency: `amount`, what the cell shows, in the row's own currency; optionally `total`, what the footer totals (else `amount`); `code`, the row's currency code; `rates`, the row's multipliers or null for a row with no currency; and `opensOn`, its default reading.
336
+ - `MoneyColumn` — the members a money column carries: a `DenominatedColumn` with its `money` declaration, the `reading` in force, its `accessor`, its `aggAccessor` and its `editAccessor`. Structural, so a grid column and a server-side source column both satisfy it.
337
+ - `convertMoney` — a row's figure in a display currency, from its declaration: null for a value that is not a number, null for a row whose rates are null (a row with no currency), and the `FxRateError` of `convertRowAmount` for a row with a currency and no rate.
338
+ - `readMoneyColumn` — returns the column read the given way. Original sets the accessor to the amount, the total to its own figure and the currency to the row's code; a display currency converts the accessor and the total, sets the column's currency and marks the column as owning it. In every reading the `editAccessor` reads the row's own amount (one the column already has is kept), so an edit, an undo, a copy and a fill work on what the row stores, in its own currency, while the cell shows the converted figure. Every derivation starts from the declaration, so reading twice is reading once; a column with no declaration comes back unchanged.
339
+ - `readMoneyColumns` — reads every money column the reader's way: their chosen reading by field key, else the optional legacy reader's choice, else what the column opens on for the reader's default currency. A column with no declaration or no field comes back unchanged.
340
+ - `moneyReadingOf` — the reading in force on a money column: the one it was read with, else its declared reading; undefined for a column with no declaration, or one declared `"default"` and not yet read.
341
+ - `convertedFromOf` — the currency a column's figure was converted from for a row: the row's own code, when the column is read in a currency other than Original, the row has a figure to draw (it has rates) and stores another currency than the reading's; null otherwise. What `renderTypedCellValue` marks with ≈, and what a money editor names under the row's own amount.
342
+ - `shownCodeOf` — the code a cell draws for a row: a per-row column's row code, a converted column's one code, undefined for a column that is not money. Never `COLUMN_WIDE_CODE`.
343
+ - `DenominatedColumn` — what a column's denomination is read off: its `field`, `currencyAccessor` (each row keeps its own code), `surfaceOwnsCurrency` (one code for every row) and `format.currency`. Structural, so a grid column and a server-side source column both satisfy it.
344
+ - `denominationOf` — the currency a number read off a row is in, as a field reader's `codeOf` asks it for the money sort: the row's code for a column that keeps each row's own, the column's one code (or `COLUMN_WIDE_CODE`) for a column that owns its currency, and undefined for anything else, which leaves the field's own `code` in charge. A rollup or formula over money answers as money.
345
+ - `COLUMN_WIDE_CODE` — the code a column that owns its currency but names none reports, the same for every row, so its rows sort as plain numbers of one currency. It is never drawn and never a real code.
346
+
347
+ ## The filter registry
348
+
349
+ What a list filters at its source, as plain data the host owns. The grid knows a column's id and what it holds, never the database column behind it, so the mapping lives with the host. A column the registry does not name filters in the browser, and a named column is taken as nullable unless its entry says otherwise.
350
+
351
+ - `ListFilterRegistry` — what a list filters at its source: one `GridFilterEntry` per column, keyed by the grid's column id, never by the database column.
352
+ - `GridFilterEntry` — one column's entry. `column` is the physical column or a json path, absent only on a resolved entry. `resolved` says the host filters the column at the source with its own code, because the value the cell shows is not a column of the queried table (a name joined from another table); the rule still passes the boundary, and the browser does not filter it a second time. `type` is set only for a real `date` column. `nullable` is set false only for a NOT NULL column, which drops the null legs a negative text operator needs; wrong, it loses rows. `array` marks an array column, so is any of and is none of test an overlap with the array, never `in`.
353
+ - `GridFilterColumnType` — how a date column is stored: `auto`, `date` (compared against calendar days) or `timestamptz` (compared against instants).
354
+ - `GridFilterRegistryInput` — the shorthand a list writes: a column id to the bare database column's name when the name is all that differs, or to a whole entry when more does.
355
+ - `defineGridFilters` — turns the shorthand into the registry: each bare name becomes `{ column }`, each entry stays as written.
356
+ - `RESOLVED_AT_SOURCE` — the entry for a column the host filters at the source itself: `{ resolved: true }`.
357
+ - `ListFilterCapability` — one column's answer in the Filter panel, read by `buildColumnFilters`: `{ mode: "unavailable", reason }` shows the column greyed with its reason, so a stale rule on a saved view's column with no field behind it can be cleared. A column with no entry filters as any column does.
358
+ - `ListFilterCapabilities` — the capabilities keyed by column id: what `buildColumnFilters` takes as `capabilities`.
359
+
360
+ ## Text, number, range and date rules
361
+
362
+ Each rule is data, an operator and its values, so the same rule is judged in memory over the rows a list holds and translated into a host's own query. These names are `@viewkitjs/fields/query`'s own, re-exported here beside the filter configs that carry them; the same rule `@viewkitjs/fields/query` applies. Every function that reads the host's conventions takes them last and falls back to the neutral defaults.
363
+
364
+ ### Text
365
+
366
+ - `TextFilterOperator` — the text operators: is, is not, contains, does not contain, starts with, ends with, is empty and is not empty.
367
+ - `TextFilterRule` — a text rule: an operator and the query typed.
368
+ - `TEXT_FILTER_OPERATORS` — the text operators in the order a picker shows them, each with its English label and whether it takes a query.
369
+ - `DEFAULT_TEXT_FILTER_RULE` — the text rule a row opens on: contains, with an empty query.
370
+ - `textFilterNeedsQuery` — says whether a text operator takes a query; is empty and is not empty do not.
371
+ - `textFilterOperatorLabel` — a text operator's name in the host's words.
372
+ - `isTextRuleActive` — says whether a text rule narrows anything: an operator that takes a query needs one that is not blank, so a rule still being typed filters nothing.
373
+ - `nextTextRule` — the rule to store when someone picks an operator while the box holds a query: always a rule, keeping the query only when the operator takes one.
374
+ - `textRuleLabel` — a text rule's summary for the row, such as `contains "acme"`, an operator's name, or the word for any.
375
+ - `matchesTextRule` — judges a value against a text rule, ignoring case and diacritics; emptiness is judged on the value as it stands, and an inactive rule matches everything.
376
+
377
+ ### Number
378
+
379
+ - `NumberFilterOperator` — the number operators: equal, not equal, greater and less than (or equal), between, is empty and is not empty.
380
+ - `NumberFilterRule` — a number rule: an operator, its value (null while the box is empty) and, for between, the upper bound.
381
+ - `NUMBER_FILTER_OPERATORS` — the number operators in the order a picker shows them, each with its English label and how many boxes it needs.
382
+ - `DEFAULT_NUMBER_FILTER_RULE` — the number rule a row opens on: equal, with no value.
383
+ - `numberFilterInputs` — how many boxes a number operator needs: none, one or two.
384
+ - `numberFilterOperatorLabel` — a number operator's name in the host's words.
385
+ - `isNumberRuleActive` — says whether a number rule is complete enough to filter; a half-typed between is not.
386
+ - `numberRuleLabel` — a number rule's summary, such as `> 100` or `100 – 500`, at the column's decimals and with its unit.
387
+ - `matchesNumberRule` — judges a value against a number rule: equality rounds both sides to the column's displayed decimals, and zero is a value, never empty. Decimal text is read as the number it is.
388
+ - `parseNumber` — reads typed text as a number, or null when it is not clearly one, in the host's decimal separator or, with none stated, either style. It is `@viewkitjs/fields`' own reader, the one a number box and a duration box read through.
389
+ - `parseDurationInput` — reads a typed duration (`500ms`, `90s`, `2m 30s`, `1h30m`) into milliseconds; a bare number is seconds, and anything it cannot read whole is null.
390
+ - `formatDurationInput` — writes milliseconds as `parseDurationInput` reads them back exactly, keeping every millisecond and dropping only the zero units, in the host's decimal separator.
391
+ - `DurationUnit` — the unit a duration column stores: `ms` (the default) or `s`.
392
+ - `msToDurationUnit` — turns milliseconds into the unit a duration column stores.
393
+ - `durationUnitToMs` — turns a duration column's stored unit into milliseconds.
394
+
395
+ ### Range
396
+
397
+ - `RangeFilterOperator` — the range operators: any part between, entirely within, includes, at least, at most, is empty and is not empty.
398
+ - `RangeFilterRule` — a range rule: an operator, its bound or low bound, and the high bound of a two-box operator, where null is open.
399
+ - `RANGE_FILTER_OPERATORS` — the range operators in the order a picker shows them, each with its English label and how many boxes it needs.
400
+ - `DEFAULT_RANGE_FILTER_RULE` — the range rule a row opens on: any part between, with both bounds open.
401
+ - `rangeFilterInputs` — how many boxes a range operator needs: none, one or two.
402
+ - `rangeFilterOperatorLabel` — a range operator's name in the host's words.
403
+ - `isRangeRuleActive` — says whether a range rule filters: a two-box operator does once either end is typed.
404
+ - `rangeRuleLabel` — a range rule's summary, such as `20 – 100`, `≥ 50` or `Includes 30`.
405
+ - `matchesRangeRule` — judges a range value against a range rule; an open end of the value reaches forever, and an empty range matches only the emptiness operators.
406
+
407
+ ### Date
408
+
409
+ - `DateFilterOperator` — the date operators: is, is before, is after, is on or before, is on or after, is between, is relative to today, is empty and is not empty.
410
+ - `DateFilterRule` — a date rule: an operator, a day and, for between, a second day, or a relative direction and unit. Days are `YYYY-MM-DD` text, so a rule survives being saved and carries no time or zone.
411
+ - `DATE_FILTER_OPERATORS` — the date operators in the order a picker shows them, each with its English label and how many days it takes.
412
+ - `DEFAULT_DATE_FILTER_RULE` — the date rule a row opens on: relative, this week.
413
+ - `RelativeDirection` — the direction of a relative rule: past, next or this.
414
+ - `RelativeUnit` — the unit of a relative rule: day, week, month or year.
415
+ - `RELATIVE_DIRECTIONS` — the relative directions, each with its English label.
416
+ - `RELATIVE_UNITS` — the relative units, each with its English label.
417
+ - `TemporalKind` — whether a temporal value is a `date`, a calendar day, or a `datetime`, an instant.
418
+ - `dateFilterDates` — how many days a date operator takes: none, one or two.
419
+ - `dateFilterOperatorLabel` — a date operator's name in the host's words.
420
+ - `isDateRuleActive` — says whether a date rule filters: a relative rule needs its direction and unit, the others their days.
421
+ - `dateRuleLabel` — a date rule's summary, its days written in the host's locale, or the word for any.
422
+ - `matchesDateRule` — judges a value against a date rule by its calendar day in the host's time zone; a relative rule is resolved against the current moment each time, so it moves with the clock.
423
+ - `resolveRelativeWindow` — the inclusive window of days a relative rule means today: this is the calendar period holding today, with weeks running Monday to Sunday; past and next run back or forward one unit from today.
424
+ - `valueDayKey` — the calendar day a stored date or instant means, in the host's time zone; a bare day is already a day and is never read as a UTC instant. Null for an empty or unreadable value.
425
+ - `toDayKey` — a `Date`'s local calendar day as `YYYY-MM-DD`.
426
+ - `fromDayKey` — reads `YYYY-MM-DD` as a local-midnight `Date`, never as UTC; null for text that is no real day.
427
+ - `parseDateInput` — reads a typed date, day first for the separated forms, and accepts an ISO day and a two-digit year; a date with no year is refused. Null for anything it cannot read.
428
+ - `formatDayInput` — writes a stored day the way a date box shows it, `27/07/2026`.
429
+
430
+ ## The filter configs and their guards
431
+
432
+ One row of the Filter panel is one `FilterConfig`, the union of what each editor needs, told apart by `editor`. They are types and pure functions, safe on a server.
433
+
434
+ - `FilterConfig` — one Filter panel row: an option row picking one value or several (`editor` absent), or a text, number, date, range, relation or unavailable row. It is generic over the option value's type.
435
+ - `FilterConfigBase` — what every row carries: `key`, `label` and optionally `icon` and `kind`. `disabled` lists a row that cannot be opened, so a table's every column reads as one inventory; it is never active, counted or cleared. `section` puts the row under a labelled section, with unsectioned rows first. `valueLabel` replaces the derived summary on the right ("All types", "3 selected"). `onOpen` is called once each time the row's detail opens, so the host can fetch the values it offers. `countsAsFilter` is optional too.
436
+ - `FilterKind` — what a row filters, which its default icon is chosen by: `status`, `category`, `metric` or `entity`.
437
+ - `FilterOption` — one choice in an option row: its `value`, its `label` and optionally an `icon`.
438
+ - `FilterConfigSingle` — an option row with one choice: `value`, `onChange` and `options`. Optionally the value that means every value (`allValue`, `"all"` when unstated) and its label, whether that choice is hidden, render hooks for an option and its leading and trailing parts, and the list's class name.
439
+ - `FilterConfigMulti` — an option row with several choices (`multi: true`): `value` and `onChange` over a list, `options`, an `emptyLabel`, and the same render hooks and class name.
440
+ - `FilterConfigText` — a text row (`editor: "text"`): its `value` is a `TextFilterRule` or null, and `onChange` takes the next one.
441
+ - `FilterConfigNumber` — a number row (`editor: "number"`): a `NumberFilterRule` or null, with `decimals` (equality rounds as the cell does), `unit` shown in the box, `numberStyle` (`plain`, or `duration`, which reads and writes `2m 30s`) and `durationUnit`, the unit a duration rule is kept in so it compares against what the cell holds.
442
+ - `FilterConfigDate` — a date row (`editor: "date"`): a `DateFilterRule` or null, and `onChange`.
443
+ - `FilterConfigRange` — a range row (`editor: "range"`): a `RangeFilterRule` or null, a `unit` beside the boxes, and `presets`, quick picks each with a key, a label and two bounds.
444
+ - `FilterConfigRelation` — a relation's row (`editor: "relation"`): its `value` is the saved view's relation rule or null. `noun` names the far record, one and many; `subject` says what the list's rows are, plural and lower case; `where` holds the far fields' own rows, each editing one rule inside `value.where`; `canEvery` says whether Every may be chosen. `buildRelationFilters` builds them.
445
+ - `FilterConfigUnavailable` — a refusal (`editor: "unavailable"`): its `reason`, whether a stored rule sits on it (`stale`) and `onClear`. A stale row stays active only so the person can see and clear it; it never filters.
446
+ - `isUnavailableFilter` — narrows a row to `FilterConfigUnavailable`.
447
+ - `isTextFilter` — narrows a row to `FilterConfigText`; narrow before reading `multi` or `options`, which a text row lacks.
448
+ - `isNumberFilter` — narrows a row to `FilterConfigNumber`.
449
+ - `isDateFilter` — narrows a row to `FilterConfigDate`.
450
+ - `isRangeFilter` — narrows a row to `FilterConfigRange`.
451
+ - `isRelationFilter` — narrows a row to `FilterConfigRelation`.
452
+ - `isFilterActive` — says whether a row narrows the list: a disabled row never; an unavailable row when it is stale; a relation row when it holds a rule; a text, number, range or date row by its rule's own test; a multi row when something is picked; a single row when its value is not the value for every value.
453
+
454
+ ## The relation filter
455
+
456
+ A relation rule says which far records must match, any, none or every, and holds the far fields' own rules as its Where. These edit one, as the Filter panel changes it. Each is pure and returns a new rule, or null when the rule is gone. The rule is `@viewkitjs/fields/query`'s `FilterRelationRule`.
457
+
458
+ - `RelationQuantifier` — which far records must match a relation rule's Where: `any`, `none` or `every`.
459
+ - `canChooseEvery` — says whether Every may be offered: the rule holds at least one Where rule that constrains something, since Every with no condition matches every row. Given the far fields, a rule picked but not filled in does not count; without them, every rule does.
460
+ - `chooseQuantifier` — picks a quantifier for a relation field: the one the rule holds clears it (null); Every with an empty Where is refused and the rule comes back as it was; any other pick returns the rule with that quantifier and the Where it held, or an empty Where for a new rule.
461
+ - `whereRulesOf` — the Where rules the panel edits, as panel rules keyed by far field key. Groups, nested relation rules and rules on a field the far fields do not hold are skipped.
462
+ - `withWhereRule` — replaces the Where rule on one far field, or drops it on null. With no rule yet, a rule starts as Any. When the last Where rule of an Every rule goes, or, given the far fields, only unfilled ones are left, the whole rule goes.
463
+ - `setRelationRule` — the set of relation rules keyed by field key with one replaced, or removed on null, as a new object.
464
+
465
+ ## A relation's Related records row
466
+
467
+ One Filter panel row per relation the list's source can look across, under the section Related records, with the far fields as its Where rows. The Where rows are the column filter's own (`buildColumnFilters`) over columns made from the far fields, so a far status, number, date or text opens the editor it opens everywhere.
468
+
469
+ - `buildRelationFilters` — builds the Related records rows, one `FilterConfigRelation` per target. It takes `targets` keyed by the relation's field key, the current `rules`, `onRuleChange(fieldKey, rule)`, the `subject` (what the list's rows are, plural and lower case), optionally an `icon` for the rows and a `fieldIcon` for each Where row, and `farValues`. A far relation, user or actor is offered only when its target names it and `farValues` answers it; without, it is listed greyed, as is a place and an option field that declares no options.
470
+ - `RelationFilterTarget` — one relation the list can filter across: the far entity's `kind` ("campaign"), the relation's own `label` on the list's entity ("Campaigns"), the far `fields` a Where rule may name, and `named`, the far relations, users or actors whose values the host answers by name. A far field it leaves out stays greyed.
471
+ - `FarValues` — the far values a host hands as `farValues`, keyed by `farPathOf`: `values`, each path's values; optionally `labels`, each path's values to their names; and `onWanted(path)`, called when a named far field's row opens, so the host can fetch its values.
472
+ - `farPathOf` — a far field's path, as the host keys its values: the relation's key (itself a two-hop path, `a.b`, for a rollup's second hop), `FAR_PATH_SEPARATOR` and the far field's key, such as `deals.owner`.
473
+ - `FAR_PATH_SEPARATOR` — `.`, what separates a far path's hops and its far field; a field key never holds one.
474
+ - `RELATED_RECORDS_SECTION` — `"Related records"`, the section every relation row sits under.
475
+ - `relationFilterKey` — a Related records row's key, from the relation's field key: the key with `relation:` before it.
476
+ - `relationFieldKeyOf` — the relation's field key, back from a Related records row's key; a key without the prefix comes back as it is.
477
+
478
+ ## A list's preferences
479
+
480
+ Guide: [the grid](../guides/the-grid.md).
481
+
482
+ What a person keeps for one list: which view it opens on, on a desktop and on a phone, how the table is drawn, how each field reads, the footer's picks, the filters, and the figures beside a group's name. The setters each return a new map with one entry changed and the others untouched, so a host stores the result as it is.
483
+
484
+ - `ListViewPrefs` — a list's preferences as one flat object. Its keys are stored, so they stay readable by every version that wrote them.
485
+ - Which view: `viewStyle` on a desktop, `viewStyleMobile` on a phone.
486
+ - The table's switches: vertical borders, the row icon in the title cell, the identity columns frozen at the left edge, every row's checkbox always shown.
487
+ - How fields read, by field key and sparse (a key that is absent keeps the column's own answer): option colours, date styles, duration styles, whether a date shows its time, percent displays, decimals and money readings.
488
+ - The footer's pick per column (`gridAggregates`), the columns' widths, order and visibility (`gridColumns`) and the density (`gridScale`).
489
+ - The calendar's date column and the board's field and lanes, `null` or empty to follow the host's default.
490
+ - The filters: one rule per column id (`gridFilterRules`) and one relation rule per relation field key (`relationFilterRules`), both sparse.
491
+ - `groupSummary`: the figures beside a group's name.
492
+ - `LIST_VIEW_PREF_DEFAULTS` — the preferences of a list nobody has touched: the table on a desktop and the list on a phone, every switch off but the row icon, empty maps, the default density and a group that shows its count.
493
+ - `StoredListViewStyle` — the stored name of a view: `rows` for the list, `grid` for the table, `board` and `calendar`.
494
+ - `ListFilterRule` — one column's filter rule, tagged with the editor that wrote it: `text`, `options` (the ticked values, ORed; none ticked is no rule), `number` (bounds in what the column shows, so a converted money column filters in its display currency), `date` (a relative rule keeps its intent, so the window moves with the clock) or `range`.
495
+ - `ListFilterRuleState` — the filter rules of a list, by column id.
496
+ - `setFilterRule` — sets one column's rule, or drops it when handed `null`, so a list with no rules stores `{}`.
497
+ - `setOptionColor` — sets the colour of one option of one column, or drops it when handed `null`; a column left with no colours leaves the map.
498
+ - `setDateStyle` — sets one column's date style.
499
+ - `setDurationStyle` — sets one column's duration style.
500
+ - `setShowTime` — sets whether one column's dates show their time.
501
+ - `setPercentDisplay` — sets how one field draws a percent: as text, a bar or a ring.
502
+ - `setAggregate` — sets the footer's pick for one column.
503
+ - `setDecimals` — sets the decimals one key draws at.
504
+ - `setCurrency` — sets how one money field is read, in its original currencies or in one currency, by field key.
505
+ - `ListGroupSummaryPart` — one figure a group header can carry: `count`, `total` (the list's first figure, a position the menu names after its column) or a `ListGroupFigurePart` for each figure after it.
506
+ - `ListGroupFigurePart` — a figure after the list's first: `total:` and the column id it totals.
507
+ - `groupFigurePart` — the part that shows one column's figure: `total` when it is the list's first, `total:<columnId>` otherwise.
508
+ - `isGroupSummaryPart` — says whether a stored value is a part a group header knows: `count`, `total`, or `total:` and a column id of 1 to 120 characters.
509
+ - `normalizeGroupSummary` — reads a stored `groupSummary` as a set of parts: an array, or a single string as one part. It keeps each part it knows once and drops the rest, so a value it cannot read draws a bare group name.
510
+
511
+ ## Where preferences are kept
512
+
513
+ Guide: [the grid](../guides/the-grid.md).
514
+
515
+ A list keeps its preferences in separate buckets, by what each follows. The layout follows the list and the view: widths, order, visibility, density and the table's switches are one answer per view, shared by every surface that shows the list. Money readings follow the list and the reader. How a field reads follows the field, the same in every view. Filters stay with the surface. The store is the host's; these names give it the keys and the shapes.
516
+
517
+ - `ListViewLayout` — one view's layout, every key resolved: its columns and density, the table's optional switches (vertical borders, row icon, frozen identity, checkboxes always shown) that the rows views ignore, and three keys carried only when someone picked them: the calendar's `dateColumnId` and the board's `boardFieldId` and `boardLanes`.
518
+ - `StoredViewLayout` — what is stored for one view: only the keys someone set. A key that is absent follows the reader's default, so a key is written only where the view means to differ.
519
+ - `ListLayoutBucket` — a list's layouts, `{ views }`, the stored layout of each view by view id.
520
+ - `EMPTY_LAYOUT_BUCKET` — a layout bucket with no views.
521
+ - `LIST_LAYOUT_DEFAULTS` — the shipped layout: no column state, the default density, the row icon on and every other switch off.
522
+ - `layoutKey` — the key a list's layout bucket is stored under: `list:<listKey>:layout`.
523
+ - `readViewLayout` — resolves one view's layout from the bucket, key by key: a stored value wins (a stored `false` included), vertical borders fall to the reader's defaults, the rest to `LIST_LAYOUT_DEFAULTS`. The calendar's and the board's keys appear only when stored.
524
+ - `writeViewLayout` — patches one view's stored layout and returns a new bucket, every other view untouched. The patch lands on what is stored, never on the resolved layout; vertical borders set to the reader's default and any key set to `undefined` are dropped, so the view follows the default again.
525
+ - `ListDefaults` — the reader's own defaults, which every view without an answer of its own follows: whether a table draws rules between its columns (`verticalBorders`).
526
+ - `LIST_DEFAULTS_KEY` — the key the reader's defaults are stored under, `list:defaults`, one per person across devices.
527
+ - `verticalBordersDefault` — what vertical borders resolve to for a view with no answer of its own: the reader's default, or off when the reader set none.
528
+ - `ListMoneyBucket` — the reader's money readings for one list, `{ gridCurrencies }`, by field key: one per list, so a pick in a money column's header means the same on every view.
529
+ - `EMPTY_MONEY_BUCKET` — a money bucket with no readings, frozen.
530
+ - `moneyKey` — the key a list's money bucket is stored under: `list:<listKey>:money`.
531
+ - `ListFieldFormatPrefs` — how one field reads, the host's shared answer for every view and every member: decimals, currency, date style, duration style, whether a date shows its time, option colours and percent display. The flat maps of `ListViewPrefs` are this shape spread out by field key.
532
+ - `hoistLegacyPrefs` — reads a flat preferences blob into a layout bucket, `{ layout }`: the columns, density and five switches it carries go to the `table` view (a key it lacks stays unset), and the `list` view starts empty. Filters, sort, grouping and formats are left where they are. It is pure, so a host may run it on every read and store the bucket only once the person changes something.
533
+
534
+ ## The view rules
535
+
536
+ A saved view's filter is a tree of rules keyed by field key; the Filter panel edits its root level as `ListFilterRule`s keyed by column id. These convert between the two and read a list's rows the way a view names them. With `parts: true`, a rule on one part of a value is edited by its own row, under its part key (`partKey`).
537
+
538
+ - `fieldKeyOf` — the key a column is known by off the grid: its field's key, or its own id when it has no field.
539
+ - `fromListFilterRule` — converts a panel rule into a view's rule for one field key and field type, the part it reads when given one. Returns `null` for a rule that asks nothing: options with none ticked, or a yes/no field with both ticked.
540
+ - `toListFilterRule` — converts a view's rule into the panel rule that edits it, or `null` when no editor can show it: a place, a derived field's raw type, an operator its editor does not offer. A rule on one part of a value maps only with `parts: true`, to a checklist for a part that opens on `is_any_of` (a place's country) and to text otherwise.
541
+ - `rootRulesByColumn` — the root rules the panel can edit, by column id (and part key, with `parts`). Groups, relation rules and rules on a field no column carries are left out.
542
+ - `withRootRuleState` — the tree with its root rules replaced by the panel's state. Groups, relation rules and every rule no panel row can name are kept as they are, never cleared.
543
+ - `withRootRule` — the tree with one column's root rule, or its rule on one part, replaced, or dropped when handed `null`; groups, relation rules and rules the row never showed stay.
544
+ - `rootRelationRules` — the root relation rules, by relation field key: what the panel's related-records rows edit.
545
+ - `withRootRelationRules` — the tree with its root relation rules replaced by the ones given, every other rule and group untouched.
546
+ - `viewReaderFrom` — builds the `ViewFieldReader` a view reads a list's rows through, from its columns and the decimals map (by field key). It reads what the cell draws, so a filter, a sort and a group agree with the column on screen; a column that draws itself is read through its edit accessor. Decimals come from the map or the column's format, and a number's currency from the column.
547
+
548
+ ## A value's parts as rows
549
+
550
+ One part of a value can have a row of its own in the Filter, Sort and Group menus: "Location · Country", "Name · Given name". A host turns these rows on with `parts: true`; the tables say which parts of which types get one.
551
+
552
+ - `PART_KEY_SEPARATOR` — what joins a row's id and its part in a part key: `::`.
553
+ - `partKey` — a part row's key: a column id (Filter) or a field key (Sort, Group), the separator, then the part.
554
+ - `parsePartKey` — splits a key at its last separator: `{ id }` for a whole value, `{ id, part }` for a part.
555
+ - `FILTER_PART_ROWS` — the parts each type offers a Filter row for, in their order: a place's country, region, city and postal code; a name's given and family name.
556
+ - `SORT_PART_ROWS` — the orders each type offers beyond sorting by the whole value: a place by city, region or country; a name by family or given name.
557
+ - `GROUP_PART_ROWS` — the orders each type offers beyond grouping by the whole value: a place by city, region or country.
558
+ - `partWord` — a part's word ("Country", "Given name") in the host's messages, or undefined for a part no table lists. Messages default to `resolveViewsMessage`.
559
+ - `partLabel` — a part row's label, the field's label and the part's word through `views.menus.part-row`; a part with no word shows its own name. Messages default to `resolveViewsMessage`.
560
+
561
+ ## Density
562
+
563
+ - `densityStyle` — the style object that sets a rows view's density as CSS variables: a row's vertical padding (`--vk-row-py`), the space under a header (`--vk-head-mb`) and the gap in a row (`--vk-row-gap`), for compact, default and spacious. Write it on one root and every row beneath reads it; an unknown density reads as default. The grid spends the same three words on its own scale (`--vk-scale`).
564
+
565
+ ## The footer's figures
566
+
567
+ Guide: [the grid](../guides/the-grid.md).
568
+
569
+ A column's footer shows one figure, the pick the reader made from the ones the column offers. A list whose rows come a page at a time (a source list) has its figures counted by the database instead; `SourcedAggregates` tells these functions which ones it answered.
570
+
571
+ - `aggregateLabel` — a pick's name, through `views.grid.figure`. Messages default to `resolveViewsMessage`.
572
+ - `LIST_AGGREGATE_LABELS` — every pick's name but `none`, in the package's English. A grid words them through `aggregateLabel` with the host's messages.
573
+ - `gridColumnIsNumericAgg` — says whether a column totals as numbers: it declares a figure to total (`aggAccessor`) or holds a number, a percent or money.
574
+ - `aggregateOptions` — the picks a column offers, `none` first. A numeric column offers sum, average, min, max and count; a percent never sums, and offers ratio only when the column carries its two parts; any other column offers count, filled and unique. On a source list it offers what the database can answer: count everywhere, and the numeric picks where it can total the column. A column that names its picks (`footerKinds`) offers only those.
575
+ - `resolveAggregateKind` — the pick a column's footer shows: the reader's, when the column offers it; else ratio for a ratio column; else the column's declared default, when offered (on a source list, only when the database totalled it); else `none`.
576
+ - `computeAggregate` — a pick's figure over the rows in hand, or `null` for nothing to show. Count is the rows; filled and unique read a place, a name and a phone by their text, and several values as a set; ratio is sum over sum as a whole percent, `null` on an empty denominator; the numeric picks skip blanks and are `null` over no values.
577
+ - `MoneyTotal` — one money figure and its currency code, `{ amount, code }`.
578
+ - `moneyTotal` — one figure for a money column, never one per currency. A column read in a currency totals in it; a column read in its original currencies totals each row converted into the reader's default currency. Returns `null` for a column whose rows keep their own currency with no rates to convert them, and `undefined` for a column that is not money or a pick that is not numeric (that one is `computeAggregate`'s).
579
+ - `moneyFigureCode` — the currency a money column's database figure is drawn in: the reader's default under the original currencies, else the column's code (`undefined` when it has no single one), `null` for a column nothing can convert.
580
+ - `figureKeyOf` — the key a column's database figure is read under: the field its footer names, or its field key; for a convertible money column, `<key>.<currency>` in the currency it shows, the reader's default when read in its original currencies.
581
+ - `SourcedAggregates` — what a source list's footer was answered with: the keys the database totalled (`totalled`) and the reader's default currency.
582
+
583
+ ## Cards
584
+
585
+ A board or calendar card is laid out in zones: the title, a row of chips, a strip of figures, a footer for dates and, at the richest density, a body line for prose. A field's type picks its zone, so every card composes the same way; a column may name its own.
586
+
587
+ - `CardDensity` — how much of a card is drawn: `compact`, `standard` or `rich`.
588
+ - `meetsDensity` — says whether a field with this density floor is drawn at this density; a field with no floor always is.
589
+ - `CardZoneRule` — where a type lands on a card: its zone and, optionally, the least density that draws it.
590
+ - `ZONE_BY_TYPE` — every column type's zone: relations, statuses, options, members and actors as chips; numbers, percents, money and ranges as figures; dates in the footer; text, prose, links, yes/no, places and names off cards (`null`) unless the column names a zone.
591
+ - `cardZoneOf` — where one column lands at a density (`rich` by default): its own `card.zone` first (the body only at `rich`), else its type's; `null` when it stays off or falls below its floor.
592
+ - `CardField` — one field bound for a card: its column, and the zone that styles it.
593
+ - `CardLayout` — a card's plan: its title column, its fields in display order, and the ids that start a new line (`breakIds`).
594
+ - `ListCardLayoutOpts` — what `listCardLayout` takes beside the columns: the column the board is laid out by and a column the host draws elsewhere, both left off, and the density (`rich` by default).
595
+ - `listCardLayout` — builds a card's plan from the visible columns and their stored state: the title in its own slot, the fields in the stored order or else by zone (figures, chips, footer, body), and the stored line breaks or else a break before the first date.
596
+ - `effectiveCardBreakIds` — the line breaks a card uses: the stored ones once any were written (an empty list puts every field on one line), else the default break before the first date.
597
+ - `buildCardLines` — splits one row's drawn fields into lines at the break ids. A break belongs to its field, so when that field is empty the fields after it flow on; a break on the first field does nothing.
598
+
599
+ ## A group's figures
600
+
601
+ A source list holds a page, not the list, so its footer and its group headers read figures the database counted over the whole group. Four numbers per totalled key, the sum, the count of values present, the smallest and the largest, answer every pick the database can and combine exactly when parts fold into one group. These names import nothing, so a server may use them.
602
+
603
+ - `FigureKind` — the footer picks, as `ListAggregateKind` names them.
604
+ - `ColumnFigure` — one key's four numbers: `sum`, `count`, `min` and `max`, a `null` meaning no value.
605
+ - `GroupFigures` — a group's, or the whole list's, figures: its row count (`rows`) and each totalled key's `ColumnFigure` (`fields`).
606
+ - `EMPTY_FIGURE` — the figure of no values: count 0, the rest `null`.
607
+ - `combineFigure` — two parts' figures as the figure of both. A `null` is a value absent, never a zero.
608
+ - `figureOf` — the figure of some numbers, a blank or `NaN` not counted.
609
+ - `figureFor` — the number a pick shows for one key, or `null`: count is the group's rows, filled the values present, sum, average, min and max `null` over no values. Unique and ratio are not the database's to answer, and give `null`.
610
+ - `ratioFigure` — a ratio column's figure from its two parts' keys: sum over sum as a whole percent, `null` when either part was not totalled or the denominator is empty.
611
+ - `isGroupFigures` — says whether a value has the shape of `GroupFigures`.
612
+
613
+ ## Grouping
614
+
615
+ Guide: [the grid](../guides/the-grid.md).
616
+
617
+ - `ListGroup` — one group of rows, already filtered, sorted and grouped by the host: its `key`, its `label` (`null` for none), its `items` and, when the database counted them, its `figures` over the whole group.
618
+ - `OrderMode` — how groups are ordered: `lifecycle` (the order the host states), `count` (most rows first), `name`, or `manual` (the reader's stored positions, which only a source list orders by; `sortGroupEntries` treats it as `name`).
619
+ - `OrderDir` — `asc` or `desc`.
620
+ - `OrderChoice` — a mode and a direction, `{ mode, dir }`.
621
+ - `defaultDirFor` — a mode's natural direction, for seeding a new pick: `desc` for `count`, `asc` for the others.
622
+ - `sortGroupEntries` — sorts `[key, rows]` entries by an `OrderChoice` and returns a new array. It takes the lifecycle positions (a key without one sorts after), a label for each key and the key of the uncategorised group, which always sorts last; ties fall back to the label.