@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
package/CHANGELOG.md ADDED
@@ -0,0 +1,420 @@
1
+ # Changelog
2
+
3
+ All notable changes to `@viewkitjs/views`. `0.x`: the API may change between minor versions.
4
+
5
+ ## [Unreleased]
6
+
7
+ The grid's rendering, which ships in 0.2.0.
8
+
9
+ ### Added
10
+
11
+ - A column's menu is drawn with the package's own pieces: it opens the components map's `Popover` in the
12
+ `vk-grid-column-menu` slot, its rows are the `Row` atom, its colours the `Tag` atom, and each knob's choices fly out
13
+ of a `vk-grid-flyout` popover beside the row, one open at a time, after a short hover or at once on a tap.
14
+
15
+ ### Changed
16
+
17
+ - The grid counts a press as inside when it lands in the grid's React tree, not by your popover's wrapper: a press
18
+ inside a popup outside the grid's tree (a toolbar's menu, a select in a window the app opens) now clears the
19
+ focused cell, and a press on an overlay drawn inside the grid's root (a selection bar and its sheet, a
20
+ confirmation window) now keeps it.
21
+ - The grid turns mouse drag-select off itself; it no longer depends on what wraps a row.
22
+
23
+ ## [0.1.0] — 2026-10-30
24
+
25
+ The first publish: the rendering contract, the provider, the atoms, the model, the field display, the editors,
26
+ cells and selection. The grid's rendering follows in 0.2.0.
27
+
28
+ ### For an adapter
29
+
30
+ Everything an adapter written against the candidate of 27 October 2026 (the first to prove the components map on
31
+ Base UI) changes or adds for 0.1.0, slot by slot. Each line names the slot, what changed, and what the adapter does.
32
+ An adapter that hands partial `atoms` and keeps the package's English needs only the components map, the icons and
33
+ the messages it translates.
34
+
35
+ #### The components map (`ViewsComponents`)
36
+
37
+ - `Checkbox`: `checked: boolean | "indeterminate"` → `checked: boolean` plus `indeterminate?: boolean`, Base UI's
38
+ shape. Hand both to your checkbox; a press on a partial box that isn't `checked` hands `true`.
39
+ - `Menu`: an item's `children` is a group drawn in place under its label, never a flyout. Drop any submenu and the
40
+ hidden trigger it needed; draw a group label and its rows. A group row is a label: its own `onSelect`, `href` and
41
+ `checked` are ignored.
42
+ - `Menu`: a checkable row (`checked` set) closes the menu like any row. A Base UI adapter keeps `closeOnClick` on its
43
+ checkbox items.
44
+ - `Popover`: `onOutsidePress`'s `event` is the pointer press, also when the focus it moves would close the popup.
45
+ An adapter whose popover closes on that focus first keeps the last press and asks the veto with it. Focus leaving
46
+ by keyboard (a Tab out) closes without asking.
47
+ - `Popover`: a popup handed `panelData` carrying `data-slot="vk-grid-column-menu"` or `data-slot="vk-grid-flyout"`
48
+ sets it on the popup element, as for every `panelData`; dress those popups by their slot where your menus read
49
+ tighter than your card popover. A flyout sits above the menu it opened from, as any later popup does. The grid
50
+ opens them from 0.2.0.
51
+ - `Calendar` takes `locale` (required, BCP 47), the conventions' locale. Hand your calendar the matching
52
+ date-library locale (month and weekday names, the week's first day), or ignore it; a week-start lookup of your own
53
+ can go.
54
+ - `ViewsCloseReason` adds `close-press` and `swipe`. Pass your library's through instead of mapping them to `none`.
55
+ - Stacking: the package's popups carry no `z-90` or `z-95`; your popup layer decides. Drop any containment worked
56
+ around them.
57
+
58
+ #### The atoms (`ViewsAtoms`)
59
+
60
+ Two new atoms. An app that hands partial `atoms` needs nothing; one whose atoms object is typed as the whole
61
+ `ViewsAtoms` adds both entries (or spreads `DEFAULT_VIEWS_ATOMS`).
62
+
63
+ - `PlatformMark` (`ViewsPlatformMarkProps`, `{ platform, className }`): a link's platform, drawn before it. The
64
+ default draws nothing, so a link looks plain. Swap it to draw your own mark by `platform.key` into
65
+ `data-slot="vk-platform"` (state `data-platform`, the key).
66
+ - `RowMenu` (`ViewsRowMenuProps`, `ViewsRowMenuItem`): the row's right-click menu. The default runs without a swap:
67
+ the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯ (`data-slot="vk-grid-row-more"`),
68
+ wrapped in `data-slot="vk-row-menu"`, its Delete asking the browser's own confirm
69
+ (`views.menus.row-delete-confirm`); a long-press on a phone opens nothing. Swap it whole for your own (a dialog
70
+ before a delete, a long-press). The grid draws it from 0.2.0.
71
+ - `Row` and `RowContent` take `detail`, and `Row` takes `opens` and `open`. The default draws all three. A swapped
72
+ `Row` draws `detail` at its right edge in the subtle colour (a chosen row draws it in the brand colour and no
73
+ check); `opens` sets `aria-haspopup="menu"` and `aria-expanded` from `open`; `open` draws your pressed ground and
74
+ sets `data-open` (a new state, beside `data-chosen`, `data-disabled`, `data-muted`, `data-checked`).
75
+
76
+ #### The icons (`ViewsIcons`)
77
+
78
+ `ViewsIcons` is a full record, so an adapter maps every new name: ten.
79
+
80
+ - Field types: `domain`, `name`.
81
+ - A row's menu: `open` (Open page), `selectRow` (Select or Deselect).
82
+ - The grid's menus: `moveLeft`, `moveRight`, `group`, `clearSort`, `sortRowsUp`, `sortRowsDown`. `sortRowsUp` and
83
+ `sortRowsDown` are a menu's verbs, sorting the rows by a column; `sortAsc` and `sortDesc` stay the mark a sorted
84
+ header wears.
85
+
86
+ #### The slots
87
+
88
+ - `data-slot="vk-grid-flyout"`: a flyout a menu row opens beside its menu (see `Popover`).
89
+ - `data-slot="vk-grid-row-more"`: the row's ⋯ itself, which opens the row's menu.
90
+ - `data-slot="vk-row-menu"` and `data-slot="vk-platform"`: the default `RowMenu` and `PlatformMark`.
91
+
92
+ #### The messages (`ViewsMessage`)
93
+
94
+ One changed and 118 new, each with its English (`resolveViewsMessage` answers any key a catalog leaves out). A value
95
+ in `{ }` is interpolated.
96
+
97
+ - Changed: `views.display.boolean`'s `values.value` is `"true"` or `"false"` as text, not a boolean, so a catalog's
98
+ `select` reads it. Drop the conversion in your resolver, and compare `value === "true"`: the text `"false"` is
99
+ truthy.
100
+ - The name editor: `views.editors.name-given` "Given name", `views.editors.name-family` "Family name",
101
+ `views.editors.name-full` "Full name".
102
+ - The value list editor: `views.editors.values-add` "Add", `views.editors.values-label` "Label",
103
+ `views.editors.values-main` "Main", `views.editors.values-make-main` `{ value }` "Make {value} the main one",
104
+ `views.editors.values-remove` `{ value }` "Remove {value}".
105
+ - The place editor: `views.editors.place-country` "Country", `views.editors.place-country-search` "Search
106
+ countries", `views.editors.place-change-country` "Change country", `views.editors.place-region-search` "Search",
107
+ `views.editors.place-line1` "Address line 1", `views.editors.place-line2` "Address line 2",
108
+ `views.editors.place-region` "Region", `views.editors.place-required` `{ label }` "{label} *"; a country's own
109
+ words (`placeWordKey(kind, word)`): regions `views.editors.place-region-area` "Area", `-county` "County",
110
+ `-department` "Department", `-district` "District", `-do-si` "Do/Si", `-emirate` "Emirate", `-island` "Island",
111
+ `-oblast` "Oblast", `-parish` "Parish", `-prefecture` "Prefecture", `-province` "Province", `-state` "State";
112
+ cities `views.editors.place-city-city` "City", `-district` "District", `-post-town` "Post town", `-suburb`
113
+ "Suburb"; postal codes `views.editors.place-postal-eircode` "Eircode", `-pin` "PIN code", `-postal` "Postal
114
+ code", `-zip` "ZIP code".
115
+ - A panel's part row: `views.menus.part-row` `{ field, part }` "{field} · {part}".
116
+ - A phone: `views.display.phone-extension` `{ extension }` "ext. {extension}", `views.display.phone-as-typed` "Not
117
+ yet in international form".
118
+ - The grid's 79 (its menus, rows, header, footer, toasts and paste refusals), listed with their English under Added,
119
+ "The grid's words are message keys", `views.grid.add-column` "Add column" (the header's last cell) among them.
120
+ The grid draws them from 0.2.0; a catalog that words them now is ready.
121
+
122
+ #### The docs
123
+
124
+ - `docs/install.md`'s `messages` example scopes the translator to `views` and strips the `views.` prefix;
125
+ `docs/contract.md` gains "Writing an adapter", for the slots a Base UI adapter fills around its copies.
126
+
127
+ ### Added
128
+
129
+ - `RowMenu`, the row's right-click menu, among the atoms (`ViewsRowMenuProps`, `ViewsRowMenuItem`). Its default
130
+ draws the components map's `Menu` at the pointer, opened by a right-click or the row's ⋯
131
+ (`data-slot="vk-grid-row-more"`): Open page, the cell's Copy, Cut, Paste and Clear with their hints, Select or
132
+ Deselect, the host's verbs, and Delete, which asks the browser's own confirm (`views.menus.row-delete-confirm`)
133
+ before deleting. A row picked within 300 ms of the opening right-click runs nothing; a long-press on a phone opens
134
+ nothing. An app with its own row menu swaps it whole. Two icon names, `open` and `selectRow`.
135
+ - The grid's words are message keys: its menus, rows, header, footer, toasts and paste refusals, the figure names
136
+ and the refusals the package words, each with its English as before, so an app's `messages` words the whole grid
137
+ and nothing changes in English. `aggregateLabel(kind, messages?)` names a figure (`LIST_AGGREGATE_LABELS` stays,
138
+ in English); `gridClearRefusal`, `columnClearRefusal`, `columnEditRefusal` and `gridEditRefusal` take the resolver
139
+ last, and `gridNormalizeWrite` takes it in its options as `messages`; each defaults to `resolveViewsMessage`. 79
140
+ new keys, for an app's translator to word, with today's English (a value in `{ }` is interpolated; one listed as
141
+ choices is text, for a catalog's `select`):
142
+ - A column's menu: `views.menus.sort-asc` "Sort ascending", `views.menus.sort-desc` "Sort descending",
143
+ `views.menus.sort-clear` "Clear sort", `views.menus.group-by` `{ field }` "Group by {field}",
144
+ `views.menus.ungroup` "Ungroup", `views.menus.move-left` "Move left", `views.menus.move-right` "Move right",
145
+ `views.menus.hide-column` "Hide from view", `views.menus.format` "Format", `views.menus.date-style` `{ style }`
146
+ (`short` "Short", `long` "Long", `numeric` "Numeric", `relative` "Relative"), `views.menus.show-time` "Show
147
+ time", `views.menus.duration-style` `{ style }` (`adaptive` "Adaptive", `clock` "Clock", `units` "Units"),
148
+ `views.menus.decimals` "Decimals", `views.menus.automatic` "Automatic", `views.menus.currency` "Currency",
149
+ `views.menus.percent-display` "Display", `views.menus.percent-display-option` `{ display }` (`text` "Number",
150
+ `bar` "Bar", `ring` "Ring"), `views.menus.colour` `{ colour }` (`gray` "Gray", `blue` "Blue", `green` "Green",
151
+ `amber` "Amber", `red` "Red", `purple` "Purple", `pink` "Pink", `teal` "Teal"), `views.menus.colours-reset`
152
+ "Reset colors".
153
+ - A group's menu: `views.menus.group-options` "Group options", `views.menus.group-sort` "Sort rows",
154
+ `views.menus.search` "Search", `views.menus.group-show` "Show", `views.menus.group-count` "Count",
155
+ `views.menus.group-hide` "Hide group".
156
+ - "+ Add column": `views.grid.add-column` "Add column" (the header's last cell), `views.menus.add-column-search`
157
+ "Search columns…", `views.menus.add-column-no-match` `{ query }` "No column matches “{query}”.",
158
+ `views.menus.add-column-all-shown` "Every column is shown.".
159
+ - A row's menu: `views.menus.copy` "Copy", `views.menus.cut` "Cut", `views.menus.paste` "Paste",
160
+ `views.menus.clear` "Clear", `views.menus.edit` "Edit"; and the plain row menu's, worded now and drawn once it
161
+ ships: `views.menus.row-open` "Open page", `views.menus.row-select` `{ selected }` (`"false"` "Select", `"true"`
162
+ "Deselect"), `views.menus.row-delete` "Delete", `views.menus.row-delete-confirm` "Delete this row?".
163
+ - The footer: `views.grid.figure` `{ kind }` (`none` "None", `sum` "Sum", `avg` "Avg", `min` "Min", `max` "Max",
164
+ `count` "Count", `filled` "Filled", `unique` "Unique", `ratio` "Ratio"), `views.grid.figure-pick` "Calculate".
165
+ - The body and header: `views.grid.loading` "Loading rows", `views.grid.select-row` "Select row",
166
+ `views.grid.select-group` "Select group", `views.grid.select-all` "Select all", `views.grid.row-menu` "Row
167
+ menu", `views.grid.group-expand` "Expand group", `views.grid.group-collapse` "Collapse group",
168
+ `views.grid.change-value` "Change value", `views.grid.value` "Value", `views.grid.edit-value` "Edit value",
169
+ `views.grid.read-only` "Read-only", `views.grid.read-only-why` "Locked by workspace settings — this list is
170
+ read-only for everyone".
171
+ - Refusals: `views.grid.locked` `{ field }` "{field} is locked by workspace settings", `views.grid.not-clearable`
172
+ "This field can't be emptied", `views.grid.computed` `{ from }` "Computed from {from}",
173
+ `views.grid.cell-read-only` "Cell is read-only", `views.grid.clear-none` "Nothing in this selection can be
174
+ emptied — the fields are required", `views.grid.write-not-list` "Not a list of values",
175
+ `views.grid.write-not-boolean` "Not a yes/no value", `views.grid.write-marker` "This marker can only be cleared
176
+ here", `views.grid.write-not-email` "Not an email address", `views.grid.write-not-url` "Not a web address —
177
+ include http:// or https://", `views.grid.write-not-link` "Not a link", `views.grid.write-not-linkable` "Not one
178
+ of the linkable records".
179
+ - A paste: `views.grid.paste-refused` "Can't paste into this column", `views.grid.paste-empty` "Nothing to paste",
180
+ `views.grid.paste-not-number` "Not a number", `views.grid.paste-not-duration` "Not a duration — try 90s or 2m
181
+ 30s", `views.grid.paste-not-date` "Not a date", `views.grid.paste-not-option` `{ value }` "“{value}” is not an
182
+ option here", `views.grid.paste-pick` `{ value }` "“{value}” can't be pasted here — pick it from the list",
183
+ `views.grid.paste-not-linkable` `{ value }` "“{value}” is not linkable here", `views.grid.paste-not-range` "Not
184
+ a range — try 11–50, 200+ or up to 50", `views.grid.paste-failed` `{ count }` "Failed to paste {count} cell" (one)
185
+ or "… cells" (more).
186
+ - Warnings: `views.grid.changed-elsewhere` `{ field }` "{field} was changed elsewhere",
187
+ `views.grid.changed-elsewhere-cells` `{ count }` "{count} cells were changed elsewhere", `views.grid.saved-value`
188
+ "Showing the saved value.", `views.grid.saved-values` "Showing the saved values.", `views.grid.row-left` "Failed
189
+ to save the change: the row left the list while you were editing".
190
+ - `ListColumnsConfig` and `ListColumnItem`: a view's columns with what may be done to them (shown or hidden,
191
+ reordered, reset), the list a grid's "+ Add column" offers. A host's own richer column config may extend it.
192
+ - Several emails, phones, links or domains draw as their main value and a count ("ana@acme.ro +1"), each value's
193
+ label beside it behind the count; a phone the way its country writes it. A plain list draws as items, the first
194
+ main. `MultiValueCell` takes `details`, one word per value drawn in its popover.
195
+ - `@viewkitjs/views/editors/value-list`: `ValueListEditor` and `ValueListEditorHandle`. A row per value, with its
196
+ label, a main mark and a remove, and an Add row; each value is read by its type's own commit rule (a phone in the
197
+ host's `region`, else the conventions'), its reason said under the row. It commits the whole list once, the main
198
+ one first, as `{ value, label, main }` items; Escape discards and an untouched close writes nothing. Tab walks
199
+ each row's main mark, value, label and remove, then Add, and Enter or Space presses a mark or a remove. Five words:
200
+ `views.editors.values-add`, `views.editors.values-label`, `views.editors.values-main`,
201
+ `views.editors.values-make-main` and `views.editors.values-remove`.
202
+ - A column of several values mounts it: `GridEditorId` gains `values`, and `gridEditorKind` answers it for a
203
+ `multiple` email, phone, url or domain column. `gridPasteKind(col)`: a `multiple` column pastes as a list (outside
204
+ text splits on commas, a link's or a domain's only on a line break or a comma and a space so an address keeps its
205
+ own commas, each value read by the field), every other column as its type says. `FieldBinding.labels`
206
+ (`false`): a row that keeps only the values offers no label box; `columnFrom` copies it to `ListColumn.labels`, and
207
+ `checkBinding` refuses it on a field holding one value.
208
+
209
+ - `@viewkitjs/views/editors/location`: `LocationEditor` asks for the country first, then shows only that country's
210
+ parts in its own order, with its own words (County, State, ZIP code) and the parts it asks for marked, never
211
+ refused. Where the country has a region list, a picked region stores its name and its ISO 3166-2 code; the list
212
+ loads when the editor lands on that country (`loadRegions`, `@viewkitjs/fields/places`). A field limited to some
213
+ parts edits only those, and never loses one its country's format has no place for. Picking another country clears
214
+ the region and its code. `EDIT_CORES.location` is it. 27 new `views.editors.place-*` message keys, and
215
+ `placeWordKey(kind, word)` for the word a country's format names (`docs/contract.md`). A place's whole value
216
+ (`wrap: "full"`) is written in its country's order.
217
+ - A domain (`@viewkitjs/fields`' `domain` type) draws as a link to `https://` it, labelled as it is kept, with no
218
+ platform mark; it edits, filters and pastes as text, and a grid write is cleaned by the field's commit. A new icon
219
+ name, `domain`: an app's icons map adds its glyph.
220
+ - A url draws its platform before the link (`linkPlatform`, read with the provider's conventions, so an app's own
221
+ platforms show too) through a new atom, `PlatformMark` (`ViewsPlatformMarkProps`, `{ platform, className }`).
222
+ Its default draws nothing (see Changed). The package ships no brand art, so an app swaps in its own marks by
223
+ the platform's key, drawn into `data-slot="vk-platform"`. An app whose atoms map is typed as the whole `ViewsAtoms` adds the entry
224
+ (`DEFAULT_VIEWS_ATOMS.PlatformMark` keeps the default). A url drawn outside a provider draws its link with no
225
+ mark.
226
+ - A name draws its full name, else its given and family names, else the host's words for an empty one:
227
+ `DisplayOptions.nameFallback`, or a column's `nameFallback(row)`; it may be a record's title.
228
+ `@viewkitjs/views/editors/name`: `NameEditor`, three boxes, given, family and full; once a part is edited the full
229
+ box follows the parts until a person types in it, and an editor closed untouched writes nothing. A name column
230
+ edits in the `name` editor (`GridEditorId`), filters as text across its parts, pastes a text as its full name,
231
+ and totals by its text. The Filter panel keeps a rule on one part of a value when it edits the column's own rule.
232
+ - A Related records row's far relation, user or actor offers its far records by name: its target says
233
+ which far fields its host names (`RelationFilterTarget.named`), and `buildRelationFilters` takes `farValues`, the
234
+ host's values keyed by path (`farPathOf(relationKey, farKey)`, joined by `FAR_PATH_SEPARATOR`), asked when the row
235
+ opens. `useOpenValuesContext()` reads the nearest `OpenValuesProvider` whole. Without either, the row stays greyed.
236
+ - An engine run's actor wears the automation glyph.
237
+ - A place is a column: `columnFrom` makes one, read-only, with no sort, no group, no card zone and no paste, listed
238
+ in Filter but inert (it refused one, "location has no generic grid cell"). `renderLocation` draws a place's city
239
+ and country (`locationShort`), and the whole place on one line when the host asks for the whole value
240
+ (`wrap: "full"`, `locationText`); the country is named in the viewer's language. A footer's Filled and Unique read
241
+ a place by its whole text.
242
+ - `@viewkitjs/views/editors/open-values`: `OpenValuesProvider`, `useOpenValues(field)` and `offeredValues`. An app
243
+ hands an open field's values (what its records hold) to every editor of it; the hook asks for a field's values once
244
+ when its editor mounts, and reads none for a closed field or with no provider.
245
+ - `ChipsEditor`'s Add row comes after the matches, Enter picks the first match, the list loops, and a typed value
246
+ differing only in case from an offered one is that one, as `SelectEditor`'s creatable panel does.
247
+ - `bindFields` binds a worked-out name that names its rename (`defineFields({ rename })`) as the field it renames:
248
+ the name's own read shows it, the stored field's edit read opens its editor and the stored field's write saves it,
249
+ so a list's cell and a drawer's row rename the record through one declaration. While the stored field is empty the
250
+ editor opens on the name shown, and that name handed back unchanged reaches the stored field's write as its own
251
+ empty value. The name's own spec may not bind an edit read.
252
+ - `renderSelect` draws an open select's value as its own label. `SelectEditor` takes `creatable`: a search, and a
253
+ row after the matches that uses the typed text (`editor.use-value`) when no option's value is it, ignoring case.
254
+ Enter picks the first match; the list loops, so ArrowUp from it reaches the row.
255
+ - The command root takes `loop`: the arrows wrap from the last item to the first and back.
256
+ - `FilterConfigBase.onOpen`: a Filter row's detail opened, so a host may ask for what it offers.
257
+ `buildColumnFilters` takes `knownValues` and `onValuesWanted`: an open select or multiselect column offers the
258
+ values its host knows first, then those on screen, and its row's `onOpen` asks for them.
259
+ - The actor display: a chip with a member's avatar, or the glyph for an automation (`automation`), an
260
+ API key (`apiKey`) or the system (`system`). `ICON_NAMES` gains seven: those three and a glyph per
261
+ new type (`actor`, `rich_text`, `range`, `lookup`); an app's `ViewsIcons` is a full record and adds
262
+ all seven.
263
+ - Rich text: one line in a cell, the plain lines when wrapped, and the app's renderer in a drawer,
264
+ folded past 160px with Show more. A new component, `Markdown` (the app's markdown renderer), and two
265
+ messages, `views.display.show-more` and `views.display.show-less`.
266
+ - Range: drawn as "11–50" with its unit and period; a two-box editor (`@viewkitjs/views/editors/range`,
267
+ a new subpath, its boxes worded by `views.editors.range-low` and `views.editors.range-high`, a `seed`
268
+ for type-to-replace); a range
269
+ filter (`FilterConfigRange`, `isRangeFilter`) with presets as quick picks. `GridEditorId`,
270
+ `ListFilterEditor` and `GridPasteKind` gain `range`: a paste reads "11–50", "200+" or "up to 50".
271
+ - Lookup: drawn as its far field (`presentedDef`); no editor.
272
+ - A many relation draws its lead link first. `RelationCandidate.kind`: what a pick on a list of several
273
+ kinds stores. `checkBinding` refuses a writable binding of a relation that stores refs: the relation
274
+ editors commit a bare id.
275
+ - A breakdown: a segmented bar per option or a sparkline per time bucket, with its headline. A footer
276
+ totals the headline.
277
+ - A number's or percent's `format.bands` tint its figure with the status colours (`--vk-success`,
278
+ `--vk-warning`, `--vk-danger`); a band wins over the sign.
279
+ - An option's icon draws in its badge, its tag and the picker; `ViewsTagProps.leading`;
280
+ `PickerOption.icon`.
281
+ - A title whose identity is a figure or a moment draws through its field; `renderIdentityValue` on
282
+ `/cells`.
283
+ - Two atoms for the waits: `Loading` (the list reloading, or more rows arriving) and `LoadMore` (how a
284
+ list asks for its next page), each with a plain default an app swaps.
285
+ - `--vk-gutter` (`VK_OPTIONAL_LAYOUT`): the page's side padding, which the grid's rows line up with;
286
+ optional, `0px` without it.
287
+ - The components map grows by three optional props: the popover's `style`, the collapse's
288
+ `clipClassName` and the checkbox's `partialTone`. The toast port gains `warning`, and the icons gain
289
+ `caretRight`.
290
+ - An adapter that hands a full toast port adds `toast.warning`; one that builds a full `ViewsAtoms`
291
+ object adds `Loading` and `LoadMore` (or spreads `DEFAULT_VIEWS_ATOMS`). Atoms passed to the provider
292
+ as a partial override need nothing. The components map requires `Markdown` (the app's markdown
293
+ renderer), and the icons the seven new names.
294
+ - `@viewkitjs/views/cells`, moved from the portal: the typed cell (`renderTypedCellValue`), whose
295
+ command menu and relation destination are the app's atoms, and the column-shaped string formatters,
296
+ which take their viewer from the caller (`useCellFormat` reads the provider's).
297
+ - `@viewkitjs/views/selection`, moved from the portal: `useListSelection` (its haptics through the
298
+ provider's port), the row checkbox (the components map's), drag-select and the row-click rules.
299
+ - The app's own pieces are atoms too: `CommandMenu` (a command cell's verb menu; the default is the
300
+ components map's `Menu`) and `RelationLink` (where a relation chip goes; the default goes nowhere).
301
+ The checkbox's `onCheckedChange` hands `{ event }` as its second argument.
302
+ - `@viewkitjs/views/editors/session` (`useAnchoredEditSession`, `EDITOR_EXIT_MS`), and the host's
303
+ verb-menu types (`FieldMenus`, `FieldRowMenuItem`) at the root door, moved from the portal.
304
+ - `AppIcon` joins the components map: the app's icon component by the app's own names.
305
+ - `ViewsPopoverProps` gains `alignOffset`, `initialFocus`, `onOutsidePress` and `onEscape`; `ViewsMenuItem` gains `shortcut` and `href`.
306
+ - The components map grows for the editors: the popover's `chrome` (`panel` or `menu`), `onPanelClick` and `panelData`; the command root's `shouldFilter` and `filter`, its input's `ref`, `onKeyDown` and `chrome` (`search` or `bare`), a class on its empty state and groups; the calendar's controlled `month`, `captionLayout` and `startMonth`/`endMonth`; the tooltip's `align` and class. Every addition is optional.
307
+ - The atoms: `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker` and `Tag`, each a default
308
+ drawn from the app's theme (`DEFAULT_VIEWS_ATOMS`), swapped one at a time through the provider's
309
+ `atoms`. The contract names them, their slots and states, and the optional tokens the defaults read.
310
+ - The package's own messages: a closed list (`VIEWS_MESSAGE_KEYS`), the English resolver
311
+ `resolveViewsMessage`, and the provider's `messages`.
312
+ - The `List` atom (the inset a run of rows sits in), and a row's `size` (`compact` or `regular`) and
313
+ `wrap`. A command item takes `chosen`. The display's words are message keys under
314
+ `views.display.*`, and the rendering reads two more optional tokens, `--description-foreground`
315
+ and `--input-placeholder`.
316
+ - `@viewkitjs/views/display`: the field display, moved from the portal — `renderFieldValue` and one
317
+ renderer per storage type, drawn through the atoms, the components map and the icons; the string
318
+ formatters; `viewerFrom`. The provider takes an optional `presentation`, a function of the
319
+ package's defaults (so the app's provider imports none of the display). The display's words are
320
+ `views.display.*` keys, a span behind now is fields' `time.ago`, and nothing reads the runtime's
321
+ locale or zone.
322
+ - The field editors, moved from the portal: `@viewkitjs/views/editors` (`EDIT_CORES`, `hasEditCore`)
323
+ and one door per editor — `/editors/select`, `/relation`, `/number`, `/date`, `/chips` — drawn
324
+ through the components map (the command list, the popover, the calendar), the atoms and the icons.
325
+ An editor's words default to the provider's conventions.
326
+ - The rest intent on `/selection`: `useRestIntent(onRest, accepts?)` runs `onRest` once a mouse has
327
+ rested on a row's openable part for `REST_INTENT_MS` (100 ms), so a record's read starts before the
328
+ click. Once per visit; nothing when the pointer moves off first, with a button held, or for a finger.
329
+ - A list's panels can offer one part of a value as a row of its own, off by default: `parts: true` on
330
+ `buildColumnFilters`, `rootRulesByColumn`, `withRootRuleState` (new: the tree with its root rules replaced by the
331
+ panel's state, every rule no row can name kept), `sortableColumns` and the new `groupableOrders`. Filter rows
332
+ "Location · Country", "Location · Region", "Location · City" and "Location · Postal code" take a place's inert row;
333
+ "Name · Given name" and "Name · Family name" follow the name's own. The country row lists the host's codes under its
334
+ key, else every country by name (`conventions.locale`). Sort options "Location · City / Region / Country" and "Name ·
335
+ Family name / Given name", and Group dimensions "Location · City / Region / Country", carry `by`
336
+ (`SortableEntry`, `GroupableEntry`). A part row's key is `partKey(columnId, part)` (a sort's or group's,
337
+ `partKey(fieldKey, by)`; `parsePartKey`, `PART_KEY_SEPARATOR`), and `withRootRule` takes a part. Which parts get a
338
+ row: `FILTER_PART_ROWS`, `SORT_PART_ROWS`, `GROUP_PART_ROWS`; their words: `partWord`, `partLabel`, and the keys
339
+ `views.editors.place-country`, `views.editors.place-region`, `views.editors.place-city-city`,
340
+ `views.editors.place-postal-postal` and `views.menus.part-row`. `rowMatchesRules` filters by a part in memory; a
341
+ part rule never pushes down.
342
+ - The `Row` atom takes `detail` (what it says at its right edge: a setting's current choice or a live sample),
343
+ `opens` (it opens a flyout) and `open` (that flyout is up; the state `data-open`). The icon list gains six glyphs
344
+ for the grid's menus: `moveLeft`, `moveRight`, `group`, `clearSort`, `sortRowsUp` and `sortRowsDown` (a menu's
345
+ verbs; `sortAsc` and `sortDesc` stay the mark a sorted header wears). The grid slots gain `vk-grid-flyout`.
346
+
347
+ ### Changed
348
+
349
+ - The default `PlatformMark` draws nothing, so a url looks as a plain link. An app that wants marks swaps in an
350
+ icon per platform key; the platform is still read for filters.
351
+ - A `multiple` column mounts the value list editor and takes a paste and a cleared write, where it mounted no editor.
352
+ - Several values are items, `{ value, label, main }` (fields' Changed). An email list draws its values, the
353
+ main one first; a column's text filter holds when some value matches and a negative one when none does; `columnFrom`
354
+ marks a multiple phone, url or domain `multiple` too, so no single-value editor mounts over a list.
355
+ - `toListFilterRule` maps a rule on one part of a value only when asked (`{ parts: true }`); without it, such a rule
356
+ has no editor. A url's platform rule used to open the whole url's text box, which reads the address, not the
357
+ platform.
358
+ - A phone is its international form, `{ number, extension }` (fields' Changed). It is drawn the way its country writes
359
+ it: `0722 123 456` for a viewer whose conventions name RO (by calling code), `+40 722 123 456` elsewhere, its
360
+ extension after it (`views.display.phone-extension`), dialled by its RFC 3966 link; a phone stored as text is drawn
361
+ as before and flagged (`data-as-typed`, `views.display.phone-as-typed`). A column filter and the footer read it by
362
+ its number. `gridNormalizeWrite` takes the record's country (`{ region }`), and `FieldViewerContext` carries
363
+ `region`. The display imports `@viewkitjs/fields/phone`.
364
+ - A group header can show every figure, not one: `ListGroupSummaryPart` was `"count" | "total"`, and now also takes
365
+ `total:<columnId>`. `"total"` stays the list's first figure and each later one is `total:<columnId>`, so a stored
366
+ `["count", "total"]` reads as before. `groupFigurePart(columnId, first)` names a figure's part, `isGroupSummaryPart`
367
+ checks a stored one, and `normalizeGroupSummary` keeps every part it accepts.
368
+ - `renderUrl` links a web address stored without a scheme to `https://` plus it, so a bare host opens the site
369
+ instead of a path on the app, and draws a value of any scheme but http, https and ftp as plain text, no link.
370
+ `webHref` (`@viewkitjs/views/display`) says where a web address goes, or null when it is no link, for an app's own
371
+ links.
372
+ - `sortDirFor` opens a date that looks ahead (`looksAhead`) soonest first.
373
+ - The rendering paints its colours through its own names, `VK_COLOURS` (twenty) and
374
+ `VK_OPTIONAL_COLOURS` (the status and category hues), which the app declares once
375
+ (`docs/install.md`); it names no app variable. `APP_TOKENS` and `APP_OPTIONAL_TOKENS` are removed.
376
+ - The provider's `translate` is replaced by `messages`, a resolver in `@viewkitjs/fields`' shape;
377
+ `ViewsTranslate` is removed and `ViewsMessage` is a closed union.
378
+ - A row in the default tone takes its colour from what it sits in; a node label (a badge) is laid out
379
+ in a row instead of truncated; a muted button row brightens on hover; `aria-selected` rides only
380
+ with a stated role.
381
+ - `withRootRule` leaves a relation rule alone: setting or clearing a column's own filter keeps a
382
+ relation rule that names the same field key, since it asks about the far records, not the column's value.
383
+ - The peer `@viewkitjs/fields` is `^0.8.0`: the display, the editors and the model read what fields
384
+ 0.6.0 to 0.8.0 ship (the name, the full address and its formats, phones, several values, a link's
385
+ platform, the domain, `looksAhead`, the list writers for places and names, a commit's `stored`), beside the
386
+ vocabulary they already drew (actor, rich text, range, lookup, relation rules, open selects, `BoardLaneSpec`).
387
+ Under `0.x` a `^0.8.0` peer accepts no 0.9.
388
+ - An edit of several phones keeps an untouched phone kept as typed. `prepareFieldWrite` hands fields' two gates a
389
+ phone binding's stored value as `stored`, so a phone that comes back as it is stored is kept exactly as stored,
390
+ never read again; `prepareFieldRestore` keeps a restored snapshot's phones the same way, since it was stored once;
391
+ `gridNormalizeWrite` takes `stored` from its caller (`{ stored }`, the cell's value before the edit) and hands it
392
+ on.
393
+ - `columnFrom` marks a column `editable` only when its type has an editor, or is a boolean: a place whose
394
+ field may be edited is no longer `editable`, as no editor opens on one.
395
+
396
+ ### Fixed
397
+
398
+ - A place or a name reached through a many relation (a list of them) draws every value through the several-values
399
+ layout: the first, then "+N", the rest in its popover and all of them on the hover, each place in short (whole
400
+ under `wrap: "full"`) and each name as written. A footer counts the list filled by one written value and unique as
401
+ the set of them. Before: the cell drew nothing and the footer left the row out.
402
+ - A `command` cell of an email, a phone or a domain, one or several, keeps its value a link and puts the verbs on
403
+ the chevron beside it, as a relation, a member and a url already did. Before: the link sat inside the trigger's
404
+ button, and a click on the address followed it instead of opening the verbs.
405
+
406
+ ## [0.0.1] — unpublished
407
+
408
+ The version the workspace link carries; never on npm. The package check requires every packed
409
+ version to have its heading, and this is it.
410
+
411
+ ### Added
412
+
413
+ - The package exists: `@viewkitjs/views`, beside `@viewkitjs/fields` under the one scope. Nothing is
414
+ published yet; the portal consumes it through the workspace link.
415
+ - The rendering contract as the root door: the `vk` prefix, carried by the CSS variables and by the
416
+ grid's slot values (`vk-grid-row`) because both share a global namespace; the grid's states as
417
+ bare `data-*` attributes; the tokens the package owns and the app tokens it reads, the components
418
+ map, the ports, the icon names and the message-key namespaces (`views.*`) — `docs/contract.md`
419
+ and `src/contract.ts`, pinned to each other.
420
+ - The React door: `ViewsProvider`, `useViews`, `NOOP_PORTS`, and the types every adapter implements.
package/LICENSE.md ADDED
@@ -0,0 +1,7 @@
1
+ # ViewKit — licence
2
+
3
+ Copyright © 2026 Sheaf. All rights reserved.
4
+
5
+ This package is proprietary. It is published to the public npm registry for the convenience of installation only. No licence to use, copy, modify, merge, publish, distribute, sublicense or sell this software is granted by its availability there. Use is permitted only under a written agreement with Sheaf.
6
+
7
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.
package/README.md CHANGED
@@ -1,3 +1,51 @@
1
- # Temporary Holding Version
1
+ # ViewKit views
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The grid, board, calendar and list over typed fields: a headless engine every app installs and never
4
+ edits, and a default rendering written to skin discipline — markup, classes and slots only, states as
5
+ `data-*` attributes, primitives handed in by the app, geometry through `--vk-*` variables. By Sheaf.
6
+
7
+ **Status: 0.1.** The rendering contract, the provider, the model, the field display, the editors, the
8
+ cells and selection are here; the grid's rendering follows in 0.2, then the board.
9
+
10
+ ## What is here
11
+
12
+ | door | holds |
13
+ | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
14
+ | `@viewkitjs/views` | the rendering contract: slots, states, tokens, the components map, the atom names, ports, icon names, the message keys and their English resolver — `docs/contract.md` |
15
+ | `@viewkitjs/views/react` | `ViewsProvider`, `useViews`, the default atoms, and the types an adapter implements |
16
+ | `@viewkitjs/views/display` | the field display: one renderer per storage type, the string formatters, the viewer |
17
+ | `@viewkitjs/views/editors`, `/editors/<name>`, `/editors/session`, `/editors/open-values` | the edit registry, each field editor (select, relation, number, range, name, value list, date, chips), the anchored edit session, and an open field's values carried to its editors |
18
+ | `@viewkitjs/views/cells` | a column's typed cell, and its column-shaped string formatters |
19
+ | `@viewkitjs/views/selection` | a list's selection: the model, the hook, the row checkbox, drag-select and the row-click rules |
20
+
21
+ ## Actor, rich text, range, name and lookup
22
+
23
+ The display draws every field type the fields package defines. An `actor` is a chip with a member's
24
+ avatar, or a glyph for an automation, an API key or the system; a `rich_text` is one line in a cell and
25
+ folded text in a drawer; a `range` is "11–50" with its unit and period; a `name` is the full name as
26
+ written, else the given and family names, else the words the host gives an empty one
27
+ (`DisplayOptions.nameFallback`, or a column's `nameFallback(row)`), and it may be a record's title; a
28
+ `lookup` is drawn as the field it shows; a rollup with a breakdown is a segmented bar or a sparkline
29
+ beside its headline. The range has its own editor at `@viewkitjs/views/editors/range` (two boxes) and a
30
+ range filter; the name has its own at `@viewkitjs/views/editors/name` (given, family and full, the full
31
+ box filled from the parts once one is edited, until a person types in it); a place has its own at
32
+ `@viewkitjs/views/editors/location` (the country first, then that country's parts in its order, a region picked
33
+ from its list). An app hands the
34
+ provider a `Markdown` component in the components map, its own markdown renderer, which draws rich
35
+ text; the package renders no markdown itself.
36
+
37
+ ## Install
38
+
39
+ See `docs/install.md`: pin the package, add one `@source` line, mount `ViewsProvider` once with your
40
+ primitives, your icons, your field conventions and four small ports; your own atoms and wording are
41
+ optional.
42
+
43
+ ## Reshape
44
+
45
+ See `docs/reshaping.md`: a theme preset first, then `--vk-*` values, then wrappers and `data-slot`
46
+ selectors, then a copy of the rendering when the copy mode ships.
47
+
48
+ ## For coding agents
49
+
50
+ The package ships a usage skill at `skills/views/SKILL.md`; its examples compile against the packed
51
+ artifact on every check.
@@ -0,0 +1,2 @@
1
+ import type { ViewsCommandMenuProps } from "./types.js";
2
+ export declare function DefaultCommandMenu({ trigger, items, align }: ViewsCommandMenuProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,20 @@
1
+ "use client";
2
+ import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
3
+ import { useRef, useState } from "react";
4
+ import { useViews } from "../provider/context.js";
5
+ export function DefaultCommandMenu({ trigger, items, align = "start" }) {
6
+ const { Menu } = useViews().components;
7
+ const [open, setOpen] = useState(false);
8
+ const anchor = useRef(null);
9
+ return (_jsxs(_Fragment, { children: [_jsx("span", { ref: anchor, "data-slot": "vk-command-menu", className: "inline-flex min-w-0", onClick: (event) => {
10
+ event.stopPropagation();
11
+ setOpen((current) => !current);
12
+ }, children: trigger }), _jsx(Menu, { open: open, onOpenChange: (next) => setOpen(next), anchor: anchor, align: align, items: items.map((item, index) => ({
13
+ key: String(index),
14
+ label: item.label,
15
+ icon: item.icon,
16
+ onSelect: item.onClick,
17
+ destructive: item.destructive,
18
+ disabled: item.disabled,
19
+ })) })] }));
20
+ }
@@ -0,0 +1,2 @@
1
+ import type { ViewsListProps } from "./types.js";
2
+ export declare function DefaultList({ children, className }: ViewsListProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,6 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { cx } from "../internal/cx.js";
4
+ export function DefaultList({ children, className }) {
5
+ return (_jsx("div", { "data-slot": "vk-list", className: cx("p-1.5", className), children: children }));
6
+ }
@@ -0,0 +1,2 @@
1
+ import type { ViewsLoadMoreProps } from "./types.js";
2
+ export declare function DefaultLoadMore({ onReveal, label }: ViewsLoadMoreProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,25 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { useEffect, useRef } from "react";
4
+ import { useViews } from "../provider/context.js";
5
+ export function DefaultLoadMore({ onReveal, label }) {
6
+ const { Loading } = useViews().atoms;
7
+ const ref = useRef(null);
8
+ const onRevealRef = useRef(onReveal);
9
+ useEffect(() => {
10
+ onRevealRef.current = onReveal;
11
+ });
12
+ useEffect(() => {
13
+ const element = ref.current;
14
+ if (!element || typeof IntersectionObserver === "undefined")
15
+ return;
16
+ const observer = new IntersectionObserver((entries) => {
17
+ for (const entry of entries)
18
+ if (entry.isIntersecting)
19
+ onRevealRef.current();
20
+ }, { rootMargin: "600px 0px" });
21
+ observer.observe(element);
22
+ return () => observer.disconnect();
23
+ }, []);
24
+ return (_jsx("div", { ref: ref, "data-slot": "vk-load-more", children: label != null ? (_jsx("div", { className: "py-6 text-center text-xs text-(color:--vk-fg-subtlest)", children: label })) : (_jsx(Loading, { placement: "footer", label: "Loading more rows" })) }));
25
+ }
@@ -0,0 +1,2 @@
1
+ import type { ViewsLoadingProps } from "./types.js";
2
+ export declare function DefaultLoading({ placement, label }: ViewsLoadingProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,7 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { cx } from "../internal/cx.js";
4
+ export function DefaultLoading({ placement, label }) {
5
+ const body = placement === "body";
6
+ return (_jsx("div", { "data-slot": "vk-loading", className: cx("flex w-full items-center justify-center", body ? "min-h-40 py-10" : "min-h-12 py-6"), children: _jsx("span", { role: "status", "aria-label": label, className: cx("animate-spin rounded-full border-2 border-(color:--vk-border) border-t-(color:--vk-brand)", body ? "size-7" : "size-5") }) }));
7
+ }
@@ -0,0 +1,2 @@
1
+ import type { ViewsPlatformMarkProps } from "./types.js";
2
+ export declare function DefaultPlatformMark(_props: ViewsPlatformMarkProps): null;
@@ -0,0 +1,4 @@
1
+ "use client";
2
+ export function DefaultPlatformMark(_props) {
3
+ return null;
4
+ }
@@ -0,0 +1,2 @@
1
+ import type { ViewsRelationLinkProps } from "./types.js";
2
+ export declare function DefaultRelationLink({ relation, children }: ViewsRelationLinkProps): import("react/jsx-runtime").JSX.Element;
@@ -0,0 +1,6 @@
1
+ "use client";
2
+ import { jsx as _jsx } from "react/jsx-runtime";
3
+ import { CHIP_BASE } from "../internal/chip.js";
4
+ export function DefaultRelationLink({ relation, children }) {
5
+ return (_jsx("span", { "data-slot": "vk-relation-link", className: CHIP_BASE, title: relation.label, children: children }));
6
+ }
@@ -0,0 +1,3 @@
1
+ import type { ViewsRowContentProps, ViewsRowProps } from "./types.js";
2
+ export declare function DefaultRowContent({ label, description, leading, leadingLane, trailing, detail, chosen, chosenTint, tone, size, wrap, className, }: ViewsRowContentProps): import("react/jsx-runtime").JSX.Element;
3
+ export declare function DefaultRow({ onClick, onMouseDown, disabled, interactive, opens, open, title, role, "aria-selected": ariaSelected, className, ...content }: ViewsRowProps): import("react/jsx-runtime").JSX.Element;