@viewkitjs/views 0.0.0-stage → 0.1.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 (270) hide show
  1. package/CHANGELOG.md +420 -0
  2. package/LICENSE.md +7 -0
  3. package/README.md +50 -2
  4. package/dist/atoms/CommandMenu.d.ts +2 -0
  5. package/dist/atoms/CommandMenu.js +20 -0
  6. package/dist/atoms/List.d.ts +2 -0
  7. package/dist/atoms/List.js +6 -0
  8. package/dist/atoms/LoadMore.d.ts +2 -0
  9. package/dist/atoms/LoadMore.js +25 -0
  10. package/dist/atoms/Loading.d.ts +2 -0
  11. package/dist/atoms/Loading.js +7 -0
  12. package/dist/atoms/PlatformMark.d.ts +2 -0
  13. package/dist/atoms/PlatformMark.js +4 -0
  14. package/dist/atoms/RelationLink.d.ts +2 -0
  15. package/dist/atoms/RelationLink.js +6 -0
  16. package/dist/atoms/Row.d.ts +3 -0
  17. package/dist/atoms/Row.js +30 -0
  18. package/dist/atoms/RowMenu.d.ts +2 -0
  19. package/dist/atoms/RowMenu.js +101 -0
  20. package/dist/atoms/StatusBadge.d.ts +2 -0
  21. package/dist/atoms/StatusBadge.js +7 -0
  22. package/dist/atoms/StatusMarker.d.ts +2 -0
  23. package/dist/atoms/StatusMarker.js +19 -0
  24. package/dist/atoms/Tag.d.ts +2 -0
  25. package/dist/atoms/Tag.js +13 -0
  26. package/dist/atoms/TickBox.d.ts +2 -0
  27. package/dist/atoms/TickBox.js +8 -0
  28. package/dist/atoms/defaults.d.ts +2 -0
  29. package/dist/atoms/defaults.js +27 -0
  30. package/dist/atoms/tones.d.ts +5 -0
  31. package/dist/atoms/tones.js +28 -0
  32. package/dist/atoms/types.d.ts +178 -0
  33. package/dist/atoms/types.js +3 -0
  34. package/dist/cells/cell-format.d.ts +138 -0
  35. package/dist/cells/cell-format.js +16 -0
  36. package/dist/cells/cell-title.d.ts +17 -0
  37. package/dist/cells/cell-title.js +8 -0
  38. package/dist/cells/cell-values.d.ts +28 -0
  39. package/dist/cells/cell-values.js +87 -0
  40. package/dist/cells/index.d.ts +4 -0
  41. package/dist/cells/index.js +4 -0
  42. package/dist/cells/legacy-field.d.ts +52 -0
  43. package/dist/cells/legacy-field.js +164 -0
  44. package/dist/cells/relation-wrap.d.ts +3 -0
  45. package/dist/cells/relation-wrap.js +24 -0
  46. package/dist/cells/use-cell-format.d.ts +5 -0
  47. package/dist/cells/use-cell-format.js +10 -0
  48. package/dist/contract.d.ts +431 -0
  49. package/dist/contract.js +663 -0
  50. package/dist/display/actor.d.ts +4 -0
  51. package/dist/display/actor.js +26 -0
  52. package/dist/display/boolean.d.ts +18 -0
  53. package/dist/display/boolean.js +43 -0
  54. package/dist/display/breakdown.d.ts +15 -0
  55. package/dist/display/breakdown.js +32 -0
  56. package/dist/display/currency.d.ts +9 -0
  57. package/dist/display/currency.js +29 -0
  58. package/dist/display/date.d.ts +12 -0
  59. package/dist/display/date.js +26 -0
  60. package/dist/display/display-cores.d.ts +31 -0
  61. package/dist/display/display-cores.js +57 -0
  62. package/dist/display/entity-chip.d.ts +26 -0
  63. package/dist/display/entity-chip.js +9 -0
  64. package/dist/display/format.d.ts +51 -0
  65. package/dist/display/format.js +181 -0
  66. package/dist/display/index.d.ts +8 -0
  67. package/dist/display/index.js +7 -0
  68. package/dist/display/link.d.ts +29 -0
  69. package/dist/display/link.js +48 -0
  70. package/dist/display/location.d.ts +7 -0
  71. package/dist/display/location.js +15 -0
  72. package/dist/display/multi-value.d.ts +18 -0
  73. package/dist/display/multi-value.js +28 -0
  74. package/dist/display/name.d.ts +6 -0
  75. package/dist/display/name.js +14 -0
  76. package/dist/display/number.d.ts +11 -0
  77. package/dist/display/number.js +27 -0
  78. package/dist/display/options.d.ts +153 -0
  79. package/dist/display/options.js +1 -0
  80. package/dist/display/percent.d.ts +4 -0
  81. package/dist/display/percent.js +33 -0
  82. package/dist/display/phone.d.ts +10 -0
  83. package/dist/display/phone.js +38 -0
  84. package/dist/display/range.d.ts +6 -0
  85. package/dist/display/range.js +29 -0
  86. package/dist/display/relation.d.ts +4 -0
  87. package/dist/display/relation.js +29 -0
  88. package/dist/display/rich-text.d.ts +10 -0
  89. package/dist/display/rich-text.js +34 -0
  90. package/dist/display/select.d.ts +6 -0
  91. package/dist/display/select.js +38 -0
  92. package/dist/display/text-class.d.ts +23 -0
  93. package/dist/display/text-class.js +5 -0
  94. package/dist/display/text.d.ts +19 -0
  95. package/dist/display/text.js +8 -0
  96. package/dist/display/use-display-options.d.ts +2 -0
  97. package/dist/display/use-display-options.js +14 -0
  98. package/dist/display/user.d.ts +11 -0
  99. package/dist/display/user.js +10 -0
  100. package/dist/display/value-list.d.ts +10 -0
  101. package/dist/display/value-list.js +12 -0
  102. package/dist/display/viewer.d.ts +4 -0
  103. package/dist/display/viewer.js +11 -0
  104. package/dist/display/web-href.d.ts +8 -0
  105. package/dist/display/web-href.js +12 -0
  106. package/dist/editors/ChipsEditor.d.ts +59 -0
  107. package/dist/editors/ChipsEditor.js +73 -0
  108. package/dist/editors/DateEditor.d.ts +25 -0
  109. package/dist/editors/DateEditor.js +122 -0
  110. package/dist/editors/LocationEditor.d.ts +22 -0
  111. package/dist/editors/LocationEditor.js +229 -0
  112. package/dist/editors/NameEditor.d.ts +22 -0
  113. package/dist/editors/NameEditor.js +91 -0
  114. package/dist/editors/NumberEditor.d.ts +67 -0
  115. package/dist/editors/NumberEditor.js +86 -0
  116. package/dist/editors/RangeEditor.d.ts +22 -0
  117. package/dist/editors/RangeEditor.js +70 -0
  118. package/dist/editors/RelationEditor.d.ts +65 -0
  119. package/dist/editors/RelationEditor.js +64 -0
  120. package/dist/editors/SelectEditor.d.ts +72 -0
  121. package/dist/editors/SelectEditor.js +59 -0
  122. package/dist/editors/ValueListEditor.d.ts +38 -0
  123. package/dist/editors/ValueListEditor.js +217 -0
  124. package/dist/editors/edit-cores.d.ts +83 -0
  125. package/dist/editors/edit-cores.js +38 -0
  126. package/dist/editors/edit-session.d.ts +74 -0
  127. package/dist/editors/edit-session.js +35 -0
  128. package/dist/editors/open-values.d.ts +28 -0
  129. package/dist/editors/open-values.js +26 -0
  130. package/dist/editors/relation-source.d.ts +66 -0
  131. package/dist/editors/relation-source.js +102 -0
  132. package/dist/fields/binding.d.ts +87 -0
  133. package/dist/fields/binding.js +117 -0
  134. package/dist/fields/currency.d.ts +92 -0
  135. package/dist/fields/currency.js +55 -0
  136. package/dist/fields/denomination.d.ts +42 -0
  137. package/dist/fields/denomination.js +11 -0
  138. package/dist/fields/edit-core-types.d.ts +40 -0
  139. package/dist/fields/edit-core-types.js +29 -0
  140. package/dist/fields/format-knobs.d.ts +34 -0
  141. package/dist/fields/format-knobs.js +36 -0
  142. package/dist/fields/menus.d.ts +28 -0
  143. package/dist/fields/menus.js +1 -0
  144. package/dist/fields/money.d.ts +59 -0
  145. package/dist/fields/money.js +77 -0
  146. package/dist/fields/number-edit.d.ts +11 -0
  147. package/dist/fields/number-edit.js +17 -0
  148. package/dist/fields/prepare-write.d.ts +55 -0
  149. package/dist/fields/prepare-write.js +67 -0
  150. package/dist/fields/relation-source-types.d.ts +54 -0
  151. package/dist/fields/relation-source-types.js +1 -0
  152. package/dist/figures.d.ts +52 -0
  153. package/dist/figures.js +63 -0
  154. package/dist/filters/date-filter.d.ts +2 -0
  155. package/dist/filters/date-filter.js +1 -0
  156. package/dist/filters/filter-model.d.ts +177 -0
  157. package/dist/filters/filter-model.js +41 -0
  158. package/dist/filters/number-filter.d.ts +2 -0
  159. package/dist/filters/number-filter.js +1 -0
  160. package/dist/filters/range-filter.d.ts +2 -0
  161. package/dist/filters/range-filter.js +1 -0
  162. package/dist/filters/registry.d.ts +136 -0
  163. package/dist/filters/registry.js +46 -0
  164. package/dist/filters/relation-filter.d.ts +16 -0
  165. package/dist/filters/relation-filter.js +53 -0
  166. package/dist/filters/text-filter.d.ts +2 -0
  167. package/dist/filters/text-filter.js +1 -0
  168. package/dist/filters/types.d.ts +27 -0
  169. package/dist/filters/types.js +1 -0
  170. package/dist/grouping/sort-groups.d.ts +18 -0
  171. package/dist/grouping/sort-groups.js +33 -0
  172. package/dist/grouping/types.d.ts +10 -0
  173. package/dist/grouping/types.js +1 -0
  174. package/dist/index.d.ts +29 -0
  175. package/dist/index.js +29 -0
  176. package/dist/internal/chip.d.ts +4 -0
  177. package/dist/internal/chip.js +3 -0
  178. package/dist/internal/cx.d.ts +3 -0
  179. package/dist/internal/cx.js +3 -0
  180. package/dist/model/aggregates.d.ts +59 -0
  181. package/dist/model/aggregates.js +186 -0
  182. package/dist/model/card-density.d.ts +8 -0
  183. package/dist/model/card-density.js +10 -0
  184. package/dist/model/card-layout.d.ts +85 -0
  185. package/dist/model/card-layout.js +90 -0
  186. package/dist/model/column-capabilities.d.ts +162 -0
  187. package/dist/model/column-capabilities.js +233 -0
  188. package/dist/model/column-filters.d.ts +106 -0
  189. package/dist/model/column-filters.js +321 -0
  190. package/dist/model/column-format.d.ts +103 -0
  191. package/dist/model/column-format.js +1 -0
  192. package/dist/model/column-from.d.ts +28 -0
  193. package/dist/model/column-from.js +160 -0
  194. package/dist/model/column-inspect.d.ts +18 -0
  195. package/dist/model/column-inspect.js +6 -0
  196. package/dist/model/column-knobs.d.ts +20 -0
  197. package/dist/model/column-knobs.js +16 -0
  198. package/dist/model/column-money.d.ts +13 -0
  199. package/dist/model/column-money.js +27 -0
  200. package/dist/model/column-order.d.ts +36 -0
  201. package/dist/model/column-order.js +68 -0
  202. package/dist/model/column-schema.d.ts +335 -0
  203. package/dist/model/column-schema.js +1 -0
  204. package/dist/model/column-sort.d.ts +17 -0
  205. package/dist/model/column-sort.js +11 -0
  206. package/dist/model/column-state.d.ts +77 -0
  207. package/dist/model/column-state.js +95 -0
  208. package/dist/model/column-types.d.ts +109 -0
  209. package/dist/model/column-types.js +50 -0
  210. package/dist/model/column-warnings.d.ts +44 -0
  211. package/dist/model/column-warnings.js +24 -0
  212. package/dist/model/density.d.ts +3 -0
  213. package/dist/model/density.js +13 -0
  214. package/dist/model/field-type-of.d.ts +21 -0
  215. package/dist/model/field-type-of.js +11 -0
  216. package/dist/model/filter-capabilities.d.ts +1 -0
  217. package/dist/model/filter-capabilities.js +1 -0
  218. package/dist/model/filter-pushdown.d.ts +106 -0
  219. package/dist/model/filter-pushdown.js +147 -0
  220. package/dist/model/index.d.ts +40 -0
  221. package/dist/model/index.js +21 -0
  222. package/dist/model/part-rows.d.ts +28 -0
  223. package/dist/model/part-rows.js +40 -0
  224. package/dist/model/preferences.d.ts +151 -0
  225. package/dist/model/preferences.js +84 -0
  226. package/dist/model/prefs-buckets.d.ts +173 -0
  227. package/dist/model/prefs-buckets.js +71 -0
  228. package/dist/model/relation-filters.d.ts +45 -0
  229. package/dist/model/relation-filters.js +78 -0
  230. package/dist/model/render-count.d.ts +2 -0
  231. package/dist/model/render-count.js +24 -0
  232. package/dist/model/row-icon.d.ts +23 -0
  233. package/dist/model/row-icon.js +5 -0
  234. package/dist/model/view-rules.d.ts +73 -0
  235. package/dist/model/view-rules.js +216 -0
  236. package/dist/provider/ViewsProvider.d.ts +26 -0
  237. package/dist/provider/ViewsProvider.js +12 -0
  238. package/dist/provider/components.d.ts +222 -0
  239. package/dist/provider/components.js +3 -0
  240. package/dist/provider/context.d.ts +19 -0
  241. package/dist/provider/context.js +10 -0
  242. package/dist/provider/icons.d.ts +6 -0
  243. package/dist/provider/icons.js +1 -0
  244. package/dist/provider/ports.d.ts +35 -0
  245. package/dist/provider/ports.js +8 -0
  246. package/dist/react.d.ts +9 -0
  247. package/dist/react.js +4 -0
  248. package/dist/selection/SelectCheckbox.d.ts +17 -0
  249. package/dist/selection/SelectCheckbox.js +11 -0
  250. package/dist/selection/index.d.ts +7 -0
  251. package/dist/selection/index.js +6 -0
  252. package/dist/selection/model.d.ts +55 -0
  253. package/dist/selection/model.js +86 -0
  254. package/dist/selection/row-click.d.ts +35 -0
  255. package/dist/selection/row-click.js +20 -0
  256. package/dist/selection/types.d.ts +17 -0
  257. package/dist/selection/types.js +1 -0
  258. package/dist/selection/useCheckDragSelect.d.ts +61 -0
  259. package/dist/selection/useCheckDragSelect.js +165 -0
  260. package/dist/selection/useListSelection.d.ts +39 -0
  261. package/dist/selection/useListSelection.js +48 -0
  262. package/dist/selection/useListSelectionShortcuts.d.ts +6 -0
  263. package/dist/selection/useListSelectionShortcuts.js +14 -0
  264. package/dist/selection/useRestIntent.d.ts +18 -0
  265. package/dist/selection/useRestIntent.js +35 -0
  266. package/docs/contract.md +453 -0
  267. package/docs/install.md +105 -0
  268. package/docs/reshaping.md +19 -0
  269. package/package.json +114 -3
  270. package/skills/views/SKILL.md +87 -0
@@ -0,0 +1,453 @@
1
+ # The rendering contract
2
+
3
+ The names the rendering speaks to the engine through, and the names an app hands in. Every name here
4
+ is public; nothing outside this list is. `src/contract.ts` holds the slots, states, tokens, component
5
+ names, port names, icon names and message namespaces as typed constants, and `src/contract.test.ts`
6
+ pins them to this file: a constant this file does not name, and a slot, state or `--vk-*` token this
7
+ file names that no constant holds, fail the package's tests. The getters, the row-state keys and the
8
+ ports' methods are named here only, until the engine that implements them lands. Renaming a name
9
+ after a second app holds a copy is a codemod across every app, so a rename is a changelog line and a
10
+ codemod, never a quiet edit.
11
+
12
+ The prefix is `vk`, and it goes on what shares a global namespace: the CSS variables (`--vk-*`) and
13
+ the `data-slot` values (`vk-grid-row`), because `data-slot` is one attribute shared by every
14
+ component copy in an app. States are bare `data-*` attributes on the package's own elements, read
15
+ beside the slot. Message keys live under `views.*`, which is their namespace.
16
+
17
+ ## Slots
18
+
19
+ The parts of the grid, as `data-slot` values on the element that draws each. A skin styles a part
20
+ through its slot (`[data-slot="vk-grid-row"]`), never through a class name the package happens to
21
+ use; the prefix keeps that selector from reaching an element of the app's own.
22
+
23
+ | slot | the element |
24
+ | ------------------------------------ | --------------------------------------------------------- |
25
+ | `data-slot="vk-grid"` | the grid's frame: the scroll container |
26
+ | `data-slot="vk-grid-header"` | the header row |
27
+ | `data-slot="vk-grid-header-cell"` | one column's header |
28
+ | `data-slot="vk-grid-row"` | one record's row |
29
+ | `data-slot="vk-grid-cell"` | one value |
30
+ | `data-slot="vk-grid-group"` | one group's band and its rows |
31
+ | `data-slot="vk-grid-group-header"` | a group's name and figures |
32
+ | `data-slot="vk-grid-footer"` | the footer row |
33
+ | `data-slot="vk-grid-footer-cell"` | one column's figure |
34
+ | `data-slot="vk-grid-rail"` | the left rail: the checkbox and the group caret |
35
+ | `data-slot="vk-grid-tail"` | the right tail: the row's ⋯ |
36
+ | `data-slot="vk-grid-row-more"` | the row's ⋯ itself: it opens the row's menu |
37
+ | `data-slot="vk-grid-editor"` | the open editor over a cell |
38
+ | `data-slot="vk-grid-outline"` | the outline around the focused cell or the selected range |
39
+ | `data-slot="vk-grid-resize-handle"` | a column's resize handle |
40
+ | `data-slot="vk-grid-column-menu"` | the header menu |
41
+ | `data-slot="vk-grid-flyout"` | a flyout a menu row opens beside its menu |
42
+ | `data-slot="vk-grid-group-menu"` | a group band's menu |
43
+ | `data-slot="vk-grid-aggregate-menu"` | the footer's figure picker |
44
+
45
+ Board's slots (`vk-board`, `vk-board-lane`, `vk-board-lane-header`, `vk-board-card`,
46
+ `vk-board-add-card`) join this table when the board arrives.
47
+
48
+ ## States
49
+
50
+ Flags the rendering styles, present as an attribute when true and absent when false, so a skin
51
+ writes `[data-selected]` and `data-[selected]:bg-…`. `data-range-edge` carries a value: one or more of
52
+ `top`, `right`, `bottom`, `left`, space-separated.
53
+
54
+ | state | on | means |
55
+ | ----------------- | ----------------- | ------------------------------------------------------ |
56
+ | `data-focused` | cell | the keyboard focus is here |
57
+ | `data-selected` | row | the row is checked |
58
+ | `data-editing` | cell | an editor is open here |
59
+ | `data-in-range` | cell | inside the selected range |
60
+ | `data-range-edge` | cell | which edges of the range this cell draws |
61
+ | `data-pending` | cell | a write is in flight |
62
+ | `data-invalid` | cell | the last commit was refused |
63
+ | `data-dragging` | header cell, row | being dragged |
64
+ | `data-empty` | cell, grid | no value; no rows |
65
+ | `data-frozen` | header cell, cell | pinned to the left edge |
66
+ | `data-scrolled` | grid | the content has scrolled under the header |
67
+ | `data-parked` | grid | the identity columns are parked behind the frozen band |
68
+
69
+ ## Getters
70
+
71
+ The engine's functions the rendering calls. They return only stable structure — role, ARIA indices,
72
+ `data-*` identifiers, geometry — and carry no per-cell handlers; they are pure functions of their
73
+ arguments, created once per engine.
74
+
75
+ - `getGridProps()`
76
+ - `getHeaderProps(colId)`
77
+ - `getRowProps(rowKey, index)`
78
+ - `getCellProps(rowKey, colId, colIndex)`
79
+
80
+ ## Row state
81
+
82
+ The slice `useGridRowState(rowKey)` returns, and the only thing that changes while the person works:
83
+ `focusedCol`, `editingCol`, `spans`, `selected`, `pending`, `invalid`. A row re-renders when its slice
84
+ changes and at no other time.
85
+
86
+ ## Tokens
87
+
88
+ **The package owns geometry and density.** Each is a CSS variable the grid sets on its
89
+ frame from its scale and its state; a skin reads them and an app overrides them on the frame.
90
+
91
+ | token | today's name in the portal | what it is |
92
+ | ----------------- | -------------------------- | ----------------------------------------- |
93
+ | `--vk-scale` | `--grid-scale` | the density multiplier |
94
+ | `--vk-row-h` | `--grid-row-h` | row height |
95
+ | `--vk-head-h` | `--grid-head-h` | header height |
96
+ | `--vk-footer-h` | `--grid-footer-h` | footer height |
97
+ | `--vk-label-h` | `--grid-label-h` | group band height |
98
+ | `--vk-line-h` | `--grid-line-h` | a cell's line height |
99
+ | `--vk-chrome-h` | `--grid-chrome-h` | the chrome above the first row |
100
+ | `--vk-px` | `--grid-px` | horizontal cell padding |
101
+ | `--vk-cell-py` | `--grid-cell-py` | vertical cell padding |
102
+ | `--vk-tail-py` | `--grid-tail-py` | the tail button's vertical padding |
103
+ | `--vk-rail-w` | `--grid-rail-w` | the left rail's width |
104
+ | `--vk-rail-gap` | `--grid-rail-gap` | the gap between rail and first cell |
105
+ | `--vk-tail-w` | `--grid-tail-w` | the right tail's width |
106
+ | `--vk-indent` | `--grid-indent` | the group indent |
107
+ | `--vk-frozen-w` | `--grid-frozen-w` | the frozen band's width |
108
+ | `--vk-scroll-mt` | `--grid-scroll-mt` | scroll-margin-top for a focused row |
109
+ | `--vk-glyph` | `--grid-glyph` | glyph size in cells |
110
+ | `--vk-head-glyph` | `--grid-head-glyph` | glyph size in the header |
111
+ | `--vk-text` | `--grid-text` | cell text size |
112
+ | `--vk-text-xs` | `--grid-text-xs` | small text size |
113
+ | `--vk-text-10` | `--grid-text-10` | the smallest text size |
114
+ | `--vk-head-text` | `--grid-head-text` | header text size |
115
+ | `--vk-scrolled` | `--grid-scrolled` | 0 or 1: content scrolled under the header |
116
+ | `--vk-parked` | `--grid-parked` | 0 or 1: identity columns parked |
117
+ | `--vk-frozen-on` | `--grid-frozen-on` | 0 or 1: the frozen band is on |
118
+
119
+ The rename from `--grid-*` happens when the grid moves into the package, in the same commit the
120
+ variable's setter moves; no portal file names a geometry `--vk-*` before that.
121
+
122
+ **Colour is the app's, by the package's names.** The rendering paints every colour through a CSS
123
+ variable the app declares, spelled in a class as `text-(color:--vk-fg)` and in a value as
124
+ `var(--vk-ground)`, and names no variable of the app's own. An app maps each name onto its tokens
125
+ once; `docs/install.md` holds the block for stock shadcn.
126
+
127
+ | colour | what it paints |
128
+ | ---------------------- | ----------------------------------------------------- |
129
+ | `--vk-fg` | text |
130
+ | `--vk-fg-subtle` | secondary text: labels, meta, glyphs |
131
+ | `--vk-fg-subtlest` | hints: placeholders, units, a suffix |
132
+ | `--vk-fg-brand` | brand text: a link, a hovered chip |
133
+ | `--vk-fg-selected` | the chosen mark in a picker |
134
+ | `--vk-fg-on-brand` | text on a brand fill |
135
+ | `--vk-ground` | the ground a part paints, where it paints one |
136
+ | `--vk-overlay` | a floating panel's ground |
137
+ | `--vk-hovered` | the hover of the ground a part sits on |
138
+ | `--vk-pressed` | the pressed or open state of that ground |
139
+ | `--vk-neutral` | a neutral fill: a well, a chip, a track |
140
+ | `--vk-neutral-hovered` | a neutral fill under the pointer or focus |
141
+ | `--vk-brand` | a brand fill: a bar, a checked box, a selection edge |
142
+ | `--vk-brand-subtlest` | a brand wash |
143
+ | `--vk-danger` | a destructive colour |
144
+ | `--vk-danger-subtlest` | a destructive wash |
145
+ | `--vk-border` | the default line |
146
+ | `--vk-border-subtle` | a table's line |
147
+ | `--vk-border-bold` | a strong line |
148
+ | `--vk-border-brand` | a focused or editing ring |
149
+
150
+ `--vk-hovered` and `--vk-pressed` are the ground's own: an app whose grounds each tune their states
151
+ declares both wherever a ground declares its own, so a part takes the states of the ground nearest it.
152
+ The default atoms and the display also read `--vk-success`, `--vk-warning`, `--vk-info`,
153
+ `--vk-label-blue`, `--vk-label-green`, `--vk-label-amber`, `--vk-label-red`, `--vk-label-purple`,
154
+ `--vk-label-pink` and `--vk-label-teal` when the app declares them, each with a built-in fallback. The
155
+ corners come from the app's Tailwind radius scale.
156
+
157
+ **The page gutter is the app's, if it has one.** `--vk-gutter` is the side padding a page gives its
158
+ content: the grid's rows run edge to edge and line their content up with it. An app that pads its
159
+ pages declares it once, onto its own padding; undeclared, the grid reads `0px` and sits flush with its
160
+ container.
161
+
162
+ ## The components map
163
+
164
+ The primitives an app hands in through `ViewsProvider`, typed in `src/provider/components.ts`.
165
+ Modelled on Base UI's shapes, so an app on Base UI wraps its own copies thinly and an app on Radix
166
+ absorbs the difference in its adapter. What the types promise is a controlled `open` with
167
+ `onOpenChange(open, details)`, an `anchor` rather than a trigger child on the popover and the menu,
168
+ and no `asChild`; the tooltip takes the element it wraps as `children`. The slots are the ones the
169
+ grid's editors and menus use, each in Base UI's shape, and an adapter on Radix and one on Base UI
170
+ both fill every one.
171
+
172
+ `Button` · `Popover` · `Tooltip` · `Checkbox` · `Menu` · `Command` · `Calendar` · `Collapse` · `Sheet` · `AppIcon` · `Markdown`
173
+
174
+ The popover takes `alignOffset`, `initialFocus` (false keeps focus where it was when the popup
175
+ opens), and two vetoes, `onOutsidePress` and `onEscape`, each returning `false` to keep it open.
176
+ `onOutsidePress` is handed the pointer press, its `target` where the press landed, also when the
177
+ focus that press moves is what would close the popup: a vetoed press holds against its focus too,
178
+ and focus leaving by keyboard (a Tab out) closes without asking. Its
179
+ `chrome` is `panel` (the app's card popover) or `menu` (the app's menu panel, for a list); a panel
180
+ click reaches `onPanelClick`, and `panelData` sets `data-*` attributes on the popup; its `style` carries what a class cannot say, a width that follows a cell. The command
181
+ list's root takes `shouldFilter`, `filter` and `loop` (the arrows wrap); an item takes `chosen`, and the app draws its chosen
182
+ mark on it; its input takes a `ref`, `onKeyDown`, and `chrome`
183
+ `search` or `bare` (the input without the search row); its empty state and groups take a class. The
184
+ calendar takes a controlled `month` (`YYYY-MM`) with `onMonthChange`, a `dropdown` caption, and the
185
+ `startMonth` and `endMonth` its pickers offer, and `locale`, the conventions' locale, in which it
186
+ draws its month and weekday names and starts its week; an adapter may ignore it and keep its
187
+ calendar's own. The tooltip takes `align` and a class; the checkbox takes `checked` and, for a box
188
+ ticked partly (some, not all), `indeterminate`, a press on which hands `true` while `checked` is false; its `onCheckedChange` hands, as its second argument, `{ event }`, the press that changed it, as Base UI reports it; its `partialTone` (`muted` or `brand`) colours the partial mark; the collapse takes `clipClassName`, a class on the box that crops; the app mounts
189
+ one tooltip provider above the views, and a tooltip never mounts its own. A menu item may carry a
190
+ `shortcut` hint and an `href`; a `checked` row is checkable and closes the menu like any row; an
191
+ item's `children` are a group, its rows drawn in place under the item's label, never a flyout, and
192
+ the group's own `onSelect`, `href` and `checked` are ignored. `AppIcon` is the app's own icon component by the app's own names, for
193
+ the glyphs a host declares (a row's icon, a binding's icon, an option's icon); the semantic glyphs the rendering itself
194
+ needs are a port, by meaning (below). `Markdown` is the app's markdown renderer, handed the stored text whole; the
195
+ package draws rich text through it and parses none.
196
+
197
+ A popup reports why it closed through `onOpenChange`'s `details.reason`: `trigger-press`,
198
+ `outside-press`, `escape-key`, `focus-out`, `item-press`, `close-press` (a close button inside it) or
199
+ `swipe` (a sheet dragged away), by Base UI's names; any other reason is `none`. The package sets no
200
+ stacking order on a popup it opens: the app's popups sit above its own modals and drawers, and a
201
+ popup opened later sits above the one it opened from.
202
+
203
+ The package ships none of them and depends on neither library.
204
+
205
+ ### Writing an adapter
206
+
207
+ What a Base UI adapter over shadcn copies does where its copies stop short of a slot.
208
+
209
+ **The menu.** The map's `Menu` has an anchor and no trigger, and no flyouts. Build it from the menu
210
+ library's root, positioner and popup, handing the anchor to the positioner, where your copy's content
211
+ doesn't forward one; with no flyouts, a root needs no trigger of its own.
212
+
213
+ **`chrome: "menu"`.** It is your menu panel's surface: no inset, because the list inside carries its
214
+ own. Where your copy has only the card popover, lay your menu classes over it.
215
+
216
+ **The command item's chosen mark.** The row inside the item draws the check. Where your copy's item
217
+ draws a tick of its own, hide it, and mark `chosen` on the item.
218
+
219
+ **`chrome: "bare"`.** The input alone, without the search row's glyph and divider. Where your copy
220
+ has only the search row, reach the command library's own input.
221
+
222
+ **The sheet's `snap`.** Map `full`, `half`, `peek` and `auto` onto your drawer's snap points if it
223
+ has them, or ignore `snap`.
224
+
225
+ **`AppIcon`.** It draws on the first paint, because rows are measured. Use a static record of your
226
+ icons, not one loaded on demand.
227
+
228
+ **Stacking.** Your popup's layer sits above your modal tier, and a later popup above an earlier one,
229
+ in your adapter: a positioner your copy isolates at a lower layer holds the popup under a modal.
230
+
231
+ **The press veto.** Where your popover closes on the focus an outside press moves before the press's
232
+ own event reaches it, keep the last pointer press and ask `onOutsidePress` with it; when the veto
233
+ refuses, refuse that focus-out too.
234
+
235
+ **Close reasons.** Pass your library's `close-press` and `swipe` through; any other reason the
236
+ contract doesn't name is `none`.
237
+
238
+ ## The atoms
239
+
240
+ The pieces the rendering is built from, and the app's own pieces it cannot draw itself, typed in `src/atoms/types.ts`: `List` (the rows'
241
+ container: the inset a run of rows sits in, inside a panel or a command list's group), `Row` (a whole row,
242
+ a button or, with `interactive={false}`, a static line), `RowContent` (a row's inside, for inside a
243
+ command list's item, which owns the element and the highlight), `TickBox` (a paint-only tick box),
244
+ `StatusBadge` (a pill by status slot), `StatusMarker` (an attention badge that opens its reason) and
245
+ `Tag` (a category chip, removable, with an optional leading glyph), `CommandMenu` (a `command` cell's verb menu, opened from the trigger the cell drew; the default is the components map's `Menu`), `RowMenu` (the row's right-click menu, around the row: Open page, the rows the rendering builds, Delete; the default is the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯ (`data-slot="vk-grid-row-more"`), wrapped in `data-slot="vk-row-menu"`; its Delete asks the browser's own confirm with `views.menus.row-delete-confirm`; a long-press on a phone opens nothing) and `RelationLink` (where a relation chip goes, around the chip the display drew; the default goes nowhere), `Loading` (a wait: the list reloading, or more rows arriving; the default is a plain ring) `LoadMore` (how a list asks for its next page; the default watches a sentinel past the last row) and `PlatformMark` (a link's platform, drawn before it, read from its address with the conventions' platforms; the default draws nothing, so a link looks plain, and the package ships no brand art, so an app that wants marks draws its own by the platform's key into `data-slot="vk-platform"`). Each ships as a default, exported as `DEFAULT_VIEWS_ATOMS`, drawn
246
+ from the app's colours; an app swaps any of them through the provider's `atoms`, and the rest
247
+ stay the defaults.
248
+
249
+ A row's `size` is `compact` (13px: a command list's rows, a list of values) or `regular` (the app's
250
+ menu size, the default). Its label truncates when it is text and is laid out in a row when it is a
251
+ node — a badge, a link — so a chip sits on the row's centre; `wrap` lets a long label break instead.
252
+ A row in the default tone takes its colour from what it sits in, so a command item's chosen mark and
253
+ highlight read through it; a `muted` row brightens on hover when it is itself the button.
254
+ A row's `detail` is what it says at its right edge, in the subtle colour: a setting's current choice,
255
+ or a live sample; a chosen row draws its detail in the brand colour and no check, so a column of
256
+ samples stays in line. A row that opens a flyout beside its menu takes `opens` (`aria-haspopup="menu"`,
257
+ and `aria-expanded` from `open`), and `open` while that flyout is up (`data-open`, the pressed ground).
258
+
259
+ The defaults mark themselves with `data-slot="vk-list"`, `data-slot="vk-row"`, `data-slot="vk-row-content"`,
260
+ `data-slot="vk-tick"`, `data-slot="vk-status"`, `data-slot="vk-marker"`, `data-slot="vk-tag"`, `data-slot="vk-command-menu"`, `data-slot="vk-relation-link"`, `data-slot="vk-loading"`, `data-slot="vk-load-more"`, `data-slot="vk-platform"` and `data-slot="vk-row-menu"`, and
261
+ with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked`, `data-open` (flags),
262
+ `data-status` (the slot's name) and `data-platform` (a link's platform key). A swapped atom marks itself as its app does.
263
+
264
+ Lists that scroll wear the class `scrollbar-overlay`, which an app may define (the
265
+ portal shows the OS overlay scrollbar through it); without it the class does nothing.
266
+
267
+ ## Ports
268
+
269
+ Runtime services the app hands in through the provider, typed in `src/provider/ports.ts`:
270
+
271
+ - `toast` — `success(message)`, `error(message)`, `info(message)`, `warning(message, { description })` (a change the person did not make).
272
+ - `haptics` — `selection()`, `impact(style)`, `notification(type)`; an app without a device hands in no-ops.
273
+ - `clipboard` — `writeText(text)` resolving to whether it succeeded; `readText()` resolving to the text or `null`.
274
+ - `viewPrefs` — `get(key)`, `set(key, value)`, `subscribe(key, listener)`: per-device state the grid keeps between visits (a column's width before the view saved it, a collapsed group).
275
+
276
+ ## Icons
277
+
278
+ The glyphs the rendering asks for, by meaning. The app maps each name to a component taking
279
+ `className`. Field types: `text` `longText` `number` `percent` `currency` `date` `datetime` `duration`
280
+ `boolean` `select` `status` `multiselect` `relation` `user` `url` `domain` `email` `phone` `location` `name` `actor`
281
+ `rich_text` `range` `lookup` `rollup` `formula` `computed`. Who did it: `automation` `apiKey` `system` (a member wears `user`). Actions: `add` `edit` `delete` `copy` `cut` `paste` `clear` `hide` `show` `lock`
282
+ `pin` `wrap` `more` `close` `check` `warning` `drag` `resize` `open` `selectRow`. Navigation and order: `chevronDown`
283
+ `chevronRight` `caretDown` `caretRight` `sortAsc` `sortDesc` `enter`. Figures: `calendar` `time` `progress`.
284
+ The grid's menus: `moveLeft` `moveRight` `group` `clearSort` `sortRowsUp` `sortRowsDown`. `sortRowsUp` and
285
+ `sortRowsDown` are a menu's verbs, sorting the rows by a column; `sortAsc` and `sortDesc` are the mark a
286
+ sorted header wears.
287
+
288
+ An app maps its own icon names onto these in its adapter; a glyph the rendering needs that is not
289
+ here is added here first, with a changelog line.
290
+
291
+ ## Message keys
292
+
293
+ The package words only its own strings; a string `@viewkitjs/fields` already keys stays a fields
294
+ message, read from the conventions the provider carries. The package's are a closed list of
295
+ `{ key, values }` messages under `views.grid.*`,
296
+ `views.editors.*`, `views.menus.*` and `views.display.*`: `views.editors.tag-remove` (`{ label }`),
297
+ `views.editors.marker-resolve`, `views.editors.marker-no-reason`, `views.editors.range-low` and
298
+ `views.editors.range-high` (a range editor's two boxes, "From" and "To"), and `views.editors.name-given`,
299
+ `views.editors.name-family` and `views.editors.name-full` (a name editor's three boxes); `views.editors.values-add` ("Add"), `views.editors.values-label` ("Label"), `views.editors.values-main` ("Main", the main value's mark), `views.editors.values-make-main` (`{ value }`, "Make {value} the main one") and `views.editors.values-remove` (`{ value }`, "Remove {value}") (a value list editor's rows); the place editor's: `views.editors.place-country` ("Country"), `views.editors.place-country-search` ("Search countries"), `views.editors.place-change-country` ("Change country"), `views.editors.place-region-search` ("Search"), `views.editors.place-line1` ("Address line 1"), `views.editors.place-line2` ("Address line 2"), `views.editors.place-required` (`{ label }`, "{label} *", a part its country asks for), the region's words `views.editors.place-region-area`, `views.editors.place-region-county`, `views.editors.place-region-department`, `views.editors.place-region-district`, `views.editors.place-region-do-si`, `views.editors.place-region-emirate`, `views.editors.place-region-island`, `views.editors.place-region-oblast`, `views.editors.place-region-parish`, `views.editors.place-region-prefecture`, `views.editors.place-region-province` and `views.editors.place-region-state`, the city's `views.editors.place-city-city`, `views.editors.place-city-district`, `views.editors.place-city-post-town` and `views.editors.place-city-suburb`, and the postal code's `views.editors.place-postal-eircode`, `views.editors.place-postal-pin`, `views.editors.place-postal-postal` and `views.editors.place-postal-zip` (each its word in English: "County", "Do/Si", "Post town", "PIN code", "ZIP code"); `placeWordKey(kind, word)` gives the key for a word `placeFormat` names; `views.editors.place-region` ("Region") beside the place editor's `views.editors.place-country`,
300
+ `views.editors.place-city-city` and `views.editors.place-postal-postal`, a place's parts in a panel;
301
+ `views.menus.part-row` (`{ field, part }`, one part's row in a panel: "Location · Country");
302
+ the grid's column menu: `views.menus.sort-asc` ("Sort ascending"), `views.menus.sort-desc`, `views.menus.sort-clear`
303
+ ("Clear sort"), `views.menus.group-by` (`{ field }`, "Group by {field}"), `views.menus.ungroup`, `views.menus.move-left`,
304
+ `views.menus.move-right`, `views.menus.hide-column` ("Hide from view"), `views.menus.format` (a date's or a duration's
305
+ row), `views.menus.date-style` (`{ style }`: `"short"`, `"long"`, `"numeric"` or `"relative"`), `views.menus.show-time`,
306
+ `views.menus.duration-style` (`{ style }`: `"adaptive"`, `"clock"` or `"units"`), `views.menus.decimals`,
307
+ `views.menus.automatic` (the field's own decimals, an option's own colour), `views.menus.currency`,
308
+ `views.menus.percent-display` ("Display"), `views.menus.percent-display-option` (`{ display }`: `"text"` is "Number",
309
+ `"bar"`, `"ring"`), `views.menus.colour` (`{ colour }`, one of the eight option colours: "Gray" … "Teal") and
310
+ `views.menus.colours-reset` ("Reset colors"); a group's menu: `views.menus.group-options` (its button's label),
311
+ `views.menus.group-sort` ("Sort rows"), `views.menus.search`, `views.menus.group-show` ("Show"), `views.menus.group-count`
312
+ ("Count") and `views.menus.group-hide` ("Hide group"); "+ Add column": `views.grid.add-column` (its header
313
+ cell), `views.menus.add-column-search` ("Search columns…"), `views.menus.add-column-no-match` (`{ query }`) and `views.menus.add-column-all-shown`; a row's menu:
314
+ `views.menus.copy`, `views.menus.cut`, `views.menus.paste`, `views.menus.clear` and `views.menus.edit` (a cell's lane),
315
+ and the plain row menu's `views.menus.row-open` ("Open page"), `views.menus.row-select` (`{ selected }`, `"true"` is
316
+ "Deselect", as text for a catalog's `select`), `views.menus.row-delete` and `views.menus.row-delete-confirm` (the
317
+ browser's confirm before a delete: "Delete this row?");
318
+ the grid's own: `views.grid.figure` (`{ kind }`, a footer figure's name, `"none"` included: "None", "Sum", "Avg", "Min",
319
+ "Max", "Count", "Filled", "Unique", "Ratio"), `views.grid.figure-pick` ("Calculate", an empty footer cell),
320
+ `views.grid.loading` ("Loading rows"), the labels `views.grid.select-row`, `views.grid.select-group`,
321
+ `views.grid.select-all`, `views.grid.row-menu`, `views.grid.group-expand`, `views.grid.group-collapse`,
322
+ `views.grid.change-value`, `views.grid.value` and `views.grid.edit-value` (a long text's box, read-only or not),
323
+ `views.grid.read-only` and `views.grid.read-only-why` (a locked list's badge and its title); its refusals
324
+ `views.grid.locked` (`{ field }`), `views.grid.not-clearable`, `views.grid.computed` (`{ from }`),
325
+ `views.grid.cell-read-only` and `views.grid.clear-none`; its write gate's `views.grid.write-not-list`,
326
+ `views.grid.write-not-boolean`, `views.grid.write-marker`, `views.grid.write-not-email`, `views.grid.write-not-url`, `views.grid.write-not-link` and
327
+ `views.grid.write-not-linkable`; a paste's `views.grid.paste-refused`, `views.grid.paste-empty`,
328
+ `views.grid.paste-not-number`, `views.grid.paste-not-duration`, `views.grid.paste-not-date`,
329
+ `views.grid.paste-not-option`, `views.grid.paste-pick` and `views.grid.paste-not-linkable` (each `{ value }`, the
330
+ pasted text), `views.grid.paste-not-range` and `views.grid.paste-failed` (`{ count }`); and the warnings
331
+ `views.grid.changed-elsewhere` (`{ field }`), `views.grid.changed-elsewhere-cells` (`{ count }`),
332
+ `views.grid.saved-value`, `views.grid.saved-values` and `views.grid.row-left`. The functions that word a refusal
333
+ (`gridClearRefusal`, `columnClearRefusal`, `columnEditRefusal`, `gridEditRefusal`) take the resolver last, and
334
+ `gridNormalizeWrite` in its options; each defaults to `resolveViewsMessage`. And the display's words —
335
+ `views.display.just-now`, `views.display.in` (`{ count, unit }`, a span ahead: "in 5m"),
336
+ `views.display.today`, `views.display.yesterday`, `views.display.tomorrow`, `views.display.month`
337
+ (`{ month, length }`), `views.display.not-an-option` (a stored value its field does not name),
338
+ `views.display.needs-attention` (a marker's default heading), `views.display.boolean`
339
+ (`{ value }`, `"true"` or `"false"` as text so a catalog's `select` reads it: a text boolean with no words of its own), `views.display.show-all` (`{ count }`), and
340
+ `views.display.show-more` and `views.display.show-less` (rich text folded in a drawer), and
341
+ `views.display.phone-extension` (`{ extension }`, "ext. 12" after a phone) and `views.display.phone-as-typed`
342
+ (the title on a phone stored as typed).
343
+ A span behind now is fields' own `time.ago`. The provider's `messages` resolves them; it defaults to the
344
+ package's English, `resolveViewsMessage`; an app's resolver that words only some keys calls
345
+ `resolveViewsMessage` for the rest, since the provider does not fall back for it. A new key is a
346
+ change to the list and a compile error in every exhaustive resolver (a `switch` with no default)
347
+ that has not worded it.
348
+
349
+ ## The doors
350
+
351
+ Thirteen doors, and nothing else is importable but `./package.json`. What each exports is named here.
352
+
353
+ `@viewkitjs/views`, no React at runtime, holds two things. The rendering contract, every name listed:
354
+ the constants `VK_PREFIX`, `GRID_SLOTS`, `GRID_STATES`, `VK_TOKENS`, `VK_COLOURS`,
355
+ `VK_OPTIONAL_COLOURS`, `VK_OPTIONAL_LAYOUT`, `COMPONENT_NAMES`, `ATOM_NAMES`, `ATOM_SLOTS`, `ATOM_STATES`, `PORT_NAMES`,
356
+ `ICON_NAMES`, `MESSAGE_NAMESPACES` and `VIEWS_MESSAGE_KEYS`; the functions `resolveViewsMessage` and `placeWordKey`; and
357
+ the types `GridSlot`, `GridState`, `VkToken`, `VkColour`, `VkOptionalColour`, `VkOptionalLayout`, `ComponentName`,
358
+ `AtomName`, `AtomSlot`, `AtomState`, `PortName`, `ViewsIconName`, `ViewsMessageNamespace`,
359
+ `ViewsMessageKey`, `ViewsMessage`, `ViewsMessageResolver` and `PlaceWordKey`.
360
+
361
+ And the model, by module: every export of `model/index.ts` (the column vocabulary — what a column is,
362
+ what may be done to it, its state, its filters, its preferences, the view rules, the aggregates) and
363
+ of the five model modules that barrel does not carry (`card-density`, `card-layout`, `column-format`,
364
+ `column-inspect`, `column-money`: the card's density and layout, a column's format, inspection and
365
+ money reading),
366
+ `filters/` (the filter registry and its types, the text, number and date rules, the filter config
367
+ types and their guards), `figures.ts`, `grouping/` (`ListGroup` and the group sort) and `fields/`
368
+ (the binding, money and currency, denomination, the write preparation, the edit-core types, number
369
+ edit, the format knobs and the relation source types, the host's verb-menu types (`FieldMenus`, `FieldRowMenuItem`)). A name exported by one of those modules is
370
+ public; nothing else at the root door is.
371
+
372
+ `@viewkitjs/views/react`, which opens with the client directive: `ViewsProvider`, `useViews()` and
373
+ `NOOP_PORTS`; the provider's types `ViewsProviderProps` and `ViewsContextValue`; the adapter's types
374
+ `ViewsComponents`, `ViewsPorts`, `ViewsIcons` and `ViewsIconProps`; the components' props
375
+ `ViewsButtonProps`, `ViewsPopoverProps`, `ViewsTooltipProps`, `ViewsCheckboxProps`, `ViewsMenuProps`,
376
+ `ViewsMenuItem`, `ViewsCommandParts`, `ViewsCalendarProps`, `ViewsCollapseProps` and
377
+ `ViewsSheetProps`, with their shared shapes `ViewsAnchor`, `ViewsSide`, `ViewsAlign`,
378
+ `ViewsCloseReason` and `ViewsOpenChange`; the ports' types `ViewsToastPort`, `ViewsHapticsPort`,
379
+ `ViewsClipboardPort` and `ViewsPrefsPort`; the atoms' `DEFAULT_VIEWS_ATOMS` and types `ViewsAtoms`,
380
+ `ViewsListProps`, `ViewsRowProps`, `ViewsRowContentProps`, `ViewsTickBoxProps`, `ViewsStatusBadgeProps`,
381
+ `ViewsStatusMarkerProps`, `ViewsTagProps`, `ViewsCommandMenuProps`, `ViewsRowMenuProps`, `ViewsRowMenuItem`, `ViewsRelationLinkProps`, `ViewsLoadingProps`, `ViewsLoadMoreProps` and `ViewsPlatformMarkProps`; and, re-exported from the root door, `ComponentName`,
382
+ `PortName`, `ViewsIconName`, `ViewsMessage` and `ViewsMessageResolver`. The provider takes an
383
+ optional `presentation`, `(defaults: FieldPresentation) => FieldPresentation`: how the app's numbers,
384
+ dates and durations read — given the package's defaults (in the conventions' locale), return the
385
+ app's. It is called where a value is drawn, so the app's provider imports none of the display.
386
+
387
+ `@viewkitjs/views/display`, no client directive on the door (a server module may reach its string
388
+ formatters), every rendering file behind it carrying its own: `renderFieldValue` and `DISPLAY_CORES`
389
+ (one renderer per storage type, a plain function that answers `null` for an empty value), the string
390
+ formatters `formatDateValue` and `formatNumberValue`, `DEFAULT_FIELD_PRESENTATION`, `viewerFrom`,
391
+ `CellSuffix`, `cellTextClass`, `MultiValueCell`, `CHIP_BASE`, `CHIP_INTERACTIVE`, and the types
392
+ `DisplayCore`, `DisplayOptions`, `FieldPresentation`, `FieldViewerContext`, `NumberLikeFormat` and
393
+ `RelationWrap`. A rendered value reads the provider's conventions, wording and presentation; a string
394
+ formatter handed no viewer reads the neutral conventions, never the runtime's.
395
+
396
+ `@viewkitjs/views/editors`, no client directive on the door: `EDIT_CORES` (one editor per storage
397
+ type, `null` where a type has no panel) and `hasEditCore`. One door per editor, each opening with the
398
+ client directive: `@viewkitjs/views/editors/select` (`SelectEditor`, `SelectEditorHandle`,
399
+ `pickerOptionsFromField`, `PickerOption`), `@viewkitjs/views/editors/relation` (`RelationEditor`,
400
+ `RelationEditorHandle`, `RelationCreate`, `RELATION_PAGE_SIZE`, `RELATION_SEARCH_DEBOUNCE_MS`, and
401
+ the relation source types), `@viewkitjs/views/editors/number` (`NumberEditor`, `NumberEditorHandle`,
402
+ `NumberEditValue`), `@viewkitjs/views/editors/range` (`RangeEditor`, `RangeEditorHandle`: two boxes,
403
+ low and high, an empty box an open end), `@viewkitjs/views/editors/location` (`LocationEditor`,
404
+ `LocationEditorHandle`: the country first, then its parts in its order, a region from its list),
405
+ `@viewkitjs/views/editors/value-list` (`ValueListEditor`, `ValueListEditorHandle`: several emails, phones, links or
406
+ domains, a row each with its label and a main mark, committed as one list of `{ value, label, main }`, the main one
407
+ first; `labels: false` for a host that keeps only the values),
408
+ `@viewkitjs/views/editors/date` (`DateEditor`, `DateEditorHandle`) and
409
+ `@viewkitjs/views/editors/chips` (`ChipsEditor`, `ChipsEditorHandle`). An editor owns its panel and
410
+ what a close means; its host owns the popover, the anchor and the write. Its words are fields'
411
+ messages, read from the provider's conventions unless the host hands `message`.
412
+
413
+ `@viewkitjs/views/editors/session`, opening with the client directive: `useAnchoredEditSession` and
414
+ `EDITOR_EXIT_MS` — the one-answer guard and the exit gap every host that opens an editor over a value
415
+ shares. Its own door, so a host that needs the session does not load the six editors.
416
+
417
+ `@viewkitjs/views/editors/open-values`, opening with the client directive: `OpenValuesProvider`,
418
+ `useOpenValues(field)` and `offeredValues(field, known, seen)`. An open field's values (what its records
419
+ hold, which the app's list answers) reach every editor of it: the app provides them above a surface, and
420
+ a host reads them, asking once for a field's values when its editor mounts. A closed field, or no
421
+ provider, reads none and asks nothing. `offeredValues` is what a host offers: the declared options, then
422
+ the known values, then those seen, each once. `useOpenValuesContext()` reads the nearest provider whole: what a host
423
+ hands `buildRelationFilters` as `farValues` (POR-1548).
424
+
425
+ A relation's Related records row (`buildRelationFilters`) offers a far relation, user or actor by name
426
+ only when its target names it (`RelationFilterTarget.named`, from the host's builder) and the host hands
427
+ `farValues`, the values its list answers keyed by path: `farPathOf(relationKey, farKey)`, the two joined by
428
+ `FAR_PATH_SEPARATOR` (`.`). The row asks for a far field's values by that path when it opens; anything
429
+ else stays greyed.
430
+
431
+ `@viewkitjs/views/cells`, no client directive on the door: `renderTypedCellValue` (a column, its row and
432
+ the user's overrides, handed to the field display — a `command` column's cell opens the app's
433
+ `CommandMenu`, a relation goes where the app's `RelationLink` says, and a title whose identity is a
434
+ figure or a moment draws through its field), `renderIdentityValue` (an identity's value without the
435
+ title cell, for a host that draws the name in its own chrome), the column-shaped string
436
+ formatters `formatDate` and `formatNumber` (the viewer is the caller's) with `useCellFormat`, which
437
+ reads it from the provider, `resolveRowCurrency`, `legacyFieldFromColumn` and `legacyNumberLikeFormat`
438
+ (a column no registry field backs, read as a field), and the type `GridCellOptions`. A column's glyph
439
+ is the app's.
440
+
441
+ `@viewkitjs/views/selection`, no client directive on the door: `useListSelection` (a list's selection
442
+ over its visual order, with a range anchor and the app's haptics), `useEscapeToClear`,
443
+ `useCheckDragSelect` and `ROW_CHECK_ATTR` (drag down the checkbox lane to set a run), `SelectCheckbox`
444
+ (the app's checkbox, revealed in its gutter zone, reading the shift key off the press), the row-click
445
+ rules `selectFromClick`, `preventShiftTextSelect`, `ROW_INTERACTIVE_SELECTOR`, `ROW_OPEN_STOP_SELECTOR`
446
+ and `ROW_NO_TEXT_SELECT`, and the types `ListSelectionConfig`, `ListBatchApi`, `SelectionRetention` and
447
+ `UseListSelectionResult`. The bar the selection opens is the app's.
448
+
449
+ ## Registry items
450
+
451
+ When the copy mode ships, each view's default rendering is one registry item, tagged by the package
452
+ version it was cut from (`views-v0.3.0`), and an app's manifest records item, tag and content hash.
453
+ Named here so the copy mode inherits the vocabulary; nothing uses it yet.
@@ -0,0 +1,105 @@
1
+ # Install
2
+
3
+ 1. **Pin it**, beside fields:
4
+
5
+ ```sh
6
+ pnpm add @viewkitjs/views @viewkitjs/fields zod
7
+ ```
8
+
9
+ `react` and `react-dom` 19 are peers you already have. ESM only, Node 20 or later.
10
+
11
+ 2. **Let Tailwind see it.** The rendering carries Tailwind classes drawn from your own tokens. Add one
12
+ line to the stylesheet that imports Tailwind:
13
+
14
+ ```css
15
+ @source "../../node_modules/@viewkitjs/views";
16
+ ```
17
+
18
+ (Adjust the relative path to where your stylesheet sits.) A missing line shows unstyled values and editors.
19
+
20
+ 3. **Map the colours.** The rendering paints through its own names, which your stylesheet declares
21
+ once. On stock shadcn tokens:
22
+
23
+ ```css
24
+ :root {
25
+ --vk-fg: var(--foreground);
26
+ --vk-fg-subtle: var(--muted-foreground);
27
+ --vk-fg-subtlest: var(--muted-foreground);
28
+ --vk-fg-brand: var(--primary);
29
+ --vk-fg-selected: var(--primary);
30
+ --vk-fg-on-brand: var(--primary-foreground);
31
+ --vk-ground: var(--background);
32
+ --vk-overlay: var(--popover);
33
+ --vk-hovered: var(--accent);
34
+ --vk-pressed: var(--accent);
35
+ --vk-neutral: var(--muted);
36
+ --vk-neutral-hovered: var(--accent);
37
+ --vk-brand: var(--primary);
38
+ --vk-brand-subtlest: color-mix(in oklab, var(--primary) 12%, var(--background));
39
+ --vk-danger: var(--destructive);
40
+ --vk-danger-subtlest: color-mix(in oklab, var(--destructive) 12%, var(--background));
41
+ --vk-border: var(--border);
42
+ --vk-border-subtle: var(--border);
43
+ --vk-border-bold: var(--ring);
44
+ --vk-border-brand: var(--primary);
45
+ }
46
+ ```
47
+
48
+ `.dark` needs nothing more: each line reads your own token, which your dark theme already sets.
49
+ If your grounds each tune their hover, declare `--vk-hovered` and `--vk-pressed` beside each
50
+ ground's own. The status and category hues (`--vk-success`, `--vk-label-blue`, …) are optional.
51
+
52
+ If your pages pad their content at the sides, tell the grid how far, so its rows line up with the
53
+ rest of the page: declare `--vk-gutter` beside the colours, onto your own padding. Without it the
54
+ grid sits flush with its container.
55
+
56
+ 4. **Mount the provider once**, above every view, with your primitives, your ports, your icons and
57
+ your field conventions; your own atoms and wording are optional:
58
+
59
+ ```tsx
60
+ "use client";
61
+ import { ViewsProvider } from "@viewkitjs/views/react";
62
+ import { viewsComponents } from "./views-components"; // your adapter over your shadcn copies
63
+ import { viewsIcons } from "./views-icons"; // your icon library, by meaning
64
+ import { viewsPorts } from "./views-ports"; // toast, haptics, clipboard, viewPrefs
65
+ import { conventions } from "./field-conventions"; // the same object you hand @viewkitjs/fields
66
+
67
+ export function AppViews({ children }: { children: React.ReactNode }) {
68
+ return (
69
+ <ViewsProvider
70
+ components={viewsComponents}
71
+ icons={viewsIcons}
72
+ ports={viewsPorts}
73
+ conventions={conventions}
74
+ >
75
+ {children}
76
+ </ViewsProvider>
77
+ );
78
+ }
79
+ ```
80
+
81
+ The package ships default atoms — a row, a tick box, a status badge and marker, a tag, and the
82
+ rest `docs/contract.md` names — drawn from your theme. Swap any of them with your own through `atoms` (a module-level object):
83
+ `atoms={{ Tag: MyTag }}`. Its own strings resolve through `messages`, which defaults to the package's
84
+ English. With next-intl, a translator scoped to the `views` namespace, each key read without its
85
+ `views.` prefix, and `resolveViewsMessage` from `@viewkitjs/views` for any key your catalog leaves out:
86
+
87
+ ```tsx
88
+ const t = useTranslations("views");
89
+ const messages = (m: ViewsMessage) => {
90
+ const key = m.key.slice("views.".length);
91
+ return t.has(key) ? t(key, "values" in m ? m.values : undefined) : resolveViewsMessage(m);
92
+ };
93
+ ```
94
+
95
+ A root translator over a typed catalog can overflow TypeScript, hence the namespace.
96
+
97
+ Numbers, dates and durations read in your conventions' locale. To print them your own way — a
98
+ currency's symbol, a date's order — hand `presentation`, a function that takes the package's
99
+ defaults and returns yours: `(defaults) => ({ ...defaults, number: … })`. Import only the
100
+ `FieldPresentation` type, so the module that mounts the provider pulls in none of the display.
101
+
102
+ 5. **Write the adapter.** `docs/contract.md` names the eleven components and what each must accept;
103
+ `ViewsComponents`, from `@viewkitjs/views/react`, is the type. An app on Base UI wraps its shadcn copies thinly, as
104
+ `docs/contract.md`'s "Writing an adapter" says where a copy stops short; an app on Radix maps
105
+ `anchor` to `Anchor` with a virtual ref and `onOpenChange` to its own.
@@ -0,0 +1,19 @@
1
+ # Reshaping a view
2
+
3
+ Cheapest change first. Each step reaches further and costs more to keep current.
4
+
5
+ 1. **A theme preset.** Every view follows your shadcn tokens: `--background`, `--foreground`,
6
+ `--primary`, `--muted`, `--border`, `--radius` and the rest the contract lists. Change the theme,
7
+ every view changes, no code.
8
+ 2. **The `--vk-*` variables.** Geometry and density: row height, header height, cell padding, the
9
+ rail's width. Set them on the grid's frame or on a wrapper; no code.
10
+ 3. **Wrappers and slots.** Every part carries a `data-slot`; every state a `data-*`. A stylesheet or a
11
+ wrapper styles `[data-slot="vk-grid-row"][data-selected]` without touching the package.
12
+ 4. **Your own primitives.** The components map is yours: the popover, the menu, the calendar inside
13
+ the grid are your copies, so their look is already yours.
14
+ 5. **A copy of the rendering.** When the copy mode ships, a view's default rendering is a registry
15
+ item you copy into your app and own from then on, updated by a three-way merge against the tag you
16
+ copied. Reach for it only when the structure itself must differ.
17
+
18
+ An `if` in a skin that is not about layout is engine code in the wrong place: file it as a package
19
+ issue, do not fork the rendering around it.