@viewkitjs/views 0.1.0 → 0.2.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 (246) hide show
  1. package/CHANGELOG.md +196 -1
  2. package/README.md +90 -41
  3. package/dist/atoms/Row.js +1 -1
  4. package/dist/atoms/RowMenu.d.ts +1 -1
  5. package/dist/atoms/RowMenu.js +15 -4
  6. package/dist/atoms/types.d.ts +4 -4
  7. package/dist/contract.d.ts +37 -7
  8. package/dist/contract.js +24 -5
  9. package/dist/display/format.d.ts +16 -1
  10. package/dist/display/format.js +10 -1
  11. package/dist/display/index.d.ts +1 -1
  12. package/dist/display/index.js +1 -1
  13. package/dist/display/link.js +5 -3
  14. package/dist/display/location.d.ts +4 -3
  15. package/dist/display/location.js +12 -5
  16. package/dist/display/options.d.ts +1 -1
  17. package/dist/display/percent.js +10 -3
  18. package/dist/display/phone.d.ts +2 -1
  19. package/dist/display/phone.js +8 -1
  20. package/dist/display/relation.js +1 -1
  21. package/dist/editors/ChipsEditor.js +1 -1
  22. package/dist/editors/LocationEditor.js +16 -17
  23. package/dist/editors/NameEditor.js +5 -4
  24. package/dist/editors/NumberEditor.js +2 -2
  25. package/dist/editors/RangeEditor.js +2 -2
  26. package/dist/editors/ValueListEditor.d.ts +2 -2
  27. package/dist/editors/ValueListEditor.js +8 -8
  28. package/dist/editors/edit-cores.d.ts +1 -1
  29. package/dist/fields/binding.d.ts +1 -1
  30. package/dist/fields/currency.d.ts +0 -10
  31. package/dist/fields/currency.js +0 -14
  32. package/dist/fields/money.d.ts +1 -0
  33. package/dist/fields/money.js +1 -0
  34. package/dist/filters/filter-model.d.ts +0 -1
  35. package/dist/filters/registry.d.ts +3 -36
  36. package/dist/filters/registry.js +0 -38
  37. package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
  38. package/dist/grid/chrome/GridAddColumn.js +29 -0
  39. package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
  40. package/dist/grid/chrome/GridAggregateMenu.js +27 -0
  41. package/dist/grid/chrome/GridCellEditors.d.ts +64 -0
  42. package/dist/grid/chrome/GridCellEditors.js +55 -0
  43. package/dist/grid/chrome/GridCellOutline.d.ts +70 -0
  44. package/dist/grid/chrome/GridCellOutline.js +21 -0
  45. package/dist/grid/chrome/GridChipsEditor.d.ts +28 -0
  46. package/dist/grid/chrome/GridChipsEditor.js +40 -0
  47. package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
  48. package/dist/grid/chrome/GridColumnColorSection.js +40 -0
  49. package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
  50. package/dist/grid/chrome/GridColumnDateSection.js +23 -0
  51. package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
  52. package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
  53. package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
  54. package/dist/grid/chrome/GridColumnMenu.js +99 -0
  55. package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
  56. package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
  57. package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
  58. package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
  59. package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
  60. package/dist/grid/chrome/GridColumnSortSection.js +16 -0
  61. package/dist/grid/chrome/GridDateEditor.d.ts +22 -0
  62. package/dist/grid/chrome/GridDateEditor.js +31 -0
  63. package/dist/grid/chrome/GridFlyout.d.ts +44 -0
  64. package/dist/grid/chrome/GridFlyout.js +80 -0
  65. package/dist/grid/chrome/GridFooter.d.ts +23 -0
  66. package/dist/grid/chrome/GridFooter.js +81 -0
  67. package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
  68. package/dist/grid/chrome/GridGroupMenu.js +57 -0
  69. package/dist/grid/chrome/GridHeader.d.ts +61 -0
  70. package/dist/grid/chrome/GridHeader.js +37 -0
  71. package/dist/grid/chrome/GridLongTextEditor.d.ts +36 -0
  72. package/dist/grid/chrome/GridLongTextEditor.js +127 -0
  73. package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
  74. package/dist/grid/chrome/GridMenuRow.js +15 -0
  75. package/dist/grid/chrome/GridNameEditor.d.ts +19 -0
  76. package/dist/grid/chrome/GridNameEditor.js +36 -0
  77. package/dist/grid/chrome/GridNumberEditor.d.ts +35 -0
  78. package/dist/grid/chrome/GridNumberEditor.js +25 -0
  79. package/dist/grid/chrome/GridRangeEditor.d.ts +20 -0
  80. package/dist/grid/chrome/GridRangeEditor.js +25 -0
  81. package/dist/grid/chrome/GridRelationEditor.d.ts +21 -0
  82. package/dist/grid/chrome/GridRelationEditor.js +30 -0
  83. package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
  84. package/dist/grid/chrome/GridResizeHandle.js +19 -0
  85. package/dist/grid/chrome/GridRow.d.ts +25 -0
  86. package/dist/grid/chrome/GridRow.js +136 -0
  87. package/dist/grid/chrome/GridRowActions.d.ts +32 -0
  88. package/dist/grid/chrome/GridRowActions.js +25 -0
  89. package/dist/grid/chrome/GridRowCells.d.ts +4 -0
  90. package/dist/grid/chrome/GridRowCells.js +133 -0
  91. package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
  92. package/dist/grid/chrome/GridRowGlyph.js +13 -0
  93. package/dist/grid/chrome/GridSelectEditor.d.ts +18 -0
  94. package/dist/grid/chrome/GridSelectEditor.js +49 -0
  95. package/dist/grid/chrome/GridStructure.d.ts +48 -0
  96. package/dist/grid/chrome/GridStructure.js +45 -0
  97. package/dist/grid/chrome/GridTable.d.ts +4 -0
  98. package/dist/grid/chrome/GridTable.js +125 -0
  99. package/dist/grid/chrome/GridTableSurface.d.ts +15 -0
  100. package/dist/grid/chrome/GridTableSurface.js +6 -0
  101. package/dist/grid/chrome/GridTextEditor.d.ts +11 -0
  102. package/dist/grid/chrome/GridTextEditor.js +40 -0
  103. package/dist/grid/chrome/GridValueListEditor.d.ts +18 -0
  104. package/dist/grid/chrome/GridValueListEditor.js +36 -0
  105. package/dist/grid/chrome/StuckMarker.d.ts +16 -0
  106. package/dist/grid/chrome/StuckMarker.js +34 -0
  107. package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
  108. package/dist/grid/chrome/cell-clipboard.js +28 -0
  109. package/dist/grid/chrome/cells.d.ts +21 -0
  110. package/dist/grid/chrome/cells.js +20 -0
  111. package/dist/grid/chrome/checks.d.ts +35 -0
  112. package/dist/grid/chrome/checks.js +22 -0
  113. package/dist/grid/chrome/column-glyph.d.ts +14 -0
  114. package/dist/grid/chrome/column-glyph.js +44 -0
  115. package/dist/grid/chrome/editors.d.ts +9 -0
  116. package/dist/grid/chrome/editors.js +10 -0
  117. package/dist/grid/chrome/grid-cell-classes.d.ts +59 -0
  118. package/dist/grid/chrome/grid-cell-classes.js +30 -0
  119. package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
  120. package/dist/grid/chrome/grid-menu-search.js +7 -0
  121. package/dist/grid/chrome/grid-row-props.d.ts +131 -0
  122. package/dist/grid/chrome/grid-row-props.js +1 -0
  123. package/dist/grid/chrome/grid-styles.d.ts +37 -0
  124. package/dist/grid/chrome/grid-styles.js +8 -0
  125. package/dist/grid/chrome/grid-table-props.d.ts +173 -0
  126. package/dist/grid/chrome/grid-table-props.js +1 -0
  127. package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
  128. package/dist/grid/chrome/useGridBatchApi.js +35 -0
  129. package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
  130. package/dist/grid/chrome/useGridColumnLayout.js +206 -0
  131. package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
  132. package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
  133. package/dist/grid/chrome/useGridKeyboard.d.ts +47 -0
  134. package/dist/grid/chrome/useGridKeyboard.js +274 -0
  135. package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
  136. package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
  137. package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
  138. package/dist/grid/chrome/useGridRailReveal.js +67 -0
  139. package/dist/grid/chrome/useGridRangeActions.d.ts +49 -0
  140. package/dist/grid/chrome/useGridRangeActions.js +188 -0
  141. package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
  142. package/dist/grid/chrome/useGridRangeGestures.js +190 -0
  143. package/dist/grid/chrome/useGridRowContextMenu.d.ts +35 -0
  144. package/dist/grid/chrome/useGridRowContextMenu.js +127 -0
  145. package/dist/grid/chrome/useGridScaleStyles.d.ts +1 -0
  146. package/dist/grid/chrome/useGridScaleStyles.js +29 -0
  147. package/dist/grid/chrome/useGridScrollSync.d.ts +38 -0
  148. package/dist/grid/chrome/useGridScrollSync.js +176 -0
  149. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +55 -0
  150. package/dist/grid/chrome/useGridTableInteractionModel.js +197 -0
  151. package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
  152. package/dist/grid/chrome/useGridTableSelection.js +55 -0
  153. package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
  154. package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
  155. package/dist/grid/core/clipboard-model.d.ts +81 -0
  156. package/dist/grid/core/clipboard-model.js +291 -0
  157. package/dist/grid/core/column-values.d.ts +27 -0
  158. package/dist/grid/core/column-values.js +76 -0
  159. package/dist/grid/core/commit-model.d.ts +34 -0
  160. package/dist/grid/core/commit-model.js +3 -0
  161. package/dist/grid/core/coordinates.d.ts +48 -0
  162. package/dist/grid/core/coordinates.js +27 -0
  163. package/dist/grid/core/edit-values.d.ts +9 -0
  164. package/dist/grid/core/edit-values.js +1 -0
  165. package/dist/grid/core/editing-controller.d.ts +59 -0
  166. package/dist/grid/core/editing-controller.js +240 -0
  167. package/dist/grid/core/editing-model.d.ts +78 -0
  168. package/dist/grid/core/editing-model.js +136 -0
  169. package/dist/grid/core/grid-scale.d.ts +14 -0
  170. package/dist/grid/core/grid-scale.js +8 -0
  171. package/dist/grid/core/nav.d.ts +94 -0
  172. package/dist/grid/core/nav.js +92 -0
  173. package/dist/grid/core/pending-reconciliation.d.ts +50 -0
  174. package/dist/grid/core/pending-reconciliation.js +49 -0
  175. package/dist/grid/core/range-model.d.ts +25 -0
  176. package/dist/grid/core/range-model.js +59 -0
  177. package/dist/grid/core/spreadsheet-operations.d.ts +85 -0
  178. package/dist/grid/core/spreadsheet-operations.js +253 -0
  179. package/dist/grid/core/useGridEditing.d.ts +43 -0
  180. package/dist/grid/core/useGridEditing.js +90 -0
  181. package/dist/grid/core/useGridRange.d.ts +20 -0
  182. package/dist/grid/core/useGridRange.js +24 -0
  183. package/dist/grid/core/value-equality.d.ts +32 -0
  184. package/dist/grid/core/value-equality.js +34 -0
  185. package/dist/grid/index.d.ts +18 -0
  186. package/dist/grid/index.js +5 -0
  187. package/dist/grid/useGridTablePrefs.d.ts +50 -0
  188. package/dist/grid/useGridTablePrefs.js +101 -0
  189. package/dist/index.d.ts +0 -1
  190. package/dist/index.js +0 -1
  191. package/dist/internal/viewport.d.ts +5 -0
  192. package/dist/internal/viewport.js +29 -0
  193. package/dist/model/column-capabilities.d.ts +2 -2
  194. package/dist/model/column-state.d.ts +1 -1
  195. package/dist/model/density.js +3 -3
  196. package/dist/model/filter-capabilities.d.ts +1 -1
  197. package/dist/model/filter-capabilities.js +1 -1
  198. package/dist/model/index.d.ts +4 -6
  199. package/dist/model/index.js +0 -1
  200. package/dist/model/preferences.d.ts +7 -3
  201. package/dist/provider/ViewsProvider.d.ts +1 -1
  202. package/dist/provider/ViewsProvider.js +5 -1
  203. package/dist/provider/components.d.ts +16 -8
  204. package/dist/provider/context.d.ts +3 -2
  205. package/dist/provider/menu-groups.d.ts +8 -0
  206. package/dist/provider/menu-groups.js +38 -0
  207. package/dist/provider/ports.d.ts +22 -0
  208. package/dist/provider/ports.js +1 -0
  209. package/dist/react.d.ts +1 -1
  210. package/docs/contract.md +128 -56
  211. package/docs/getting-started.md +250 -0
  212. package/docs/guides/atoms.md +245 -0
  213. package/docs/guides/cells.md +302 -0
  214. package/docs/guides/columns.md +412 -0
  215. package/docs/guides/display.md +203 -0
  216. package/docs/guides/editors.md +404 -0
  217. package/docs/guides/ports.md +246 -0
  218. package/docs/guides/selection.md +270 -0
  219. package/docs/guides/the-grid.md +677 -0
  220. package/docs/guides/the-provider.md +446 -0
  221. package/docs/index.md +50 -0
  222. package/docs/install.md +9 -47
  223. package/docs/reference/cells.md +28 -0
  224. package/docs/reference/display.md +42 -0
  225. package/docs/reference/editors-chips.md +6 -0
  226. package/docs/reference/editors-date.md +6 -0
  227. package/docs/reference/editors-location.md +10 -0
  228. package/docs/reference/editors-name.md +6 -0
  229. package/docs/reference/editors-number.md +11 -0
  230. package/docs/reference/editors-open-values.md +9 -0
  231. package/docs/reference/editors-range.md +6 -0
  232. package/docs/reference/editors-relation.md +9 -0
  233. package/docs/reference/editors-select.md +8 -0
  234. package/docs/reference/editors-session.md +9 -0
  235. package/docs/reference/editors-value-list.md +6 -0
  236. package/docs/reference/editors.md +5 -0
  237. package/docs/reference/grid.md +39 -0
  238. package/docs/reference/react.md +86 -0
  239. package/docs/reference/selection.md +33 -0
  240. package/docs/reference/views.md +601 -0
  241. package/package.json +7 -3
  242. package/skills/views/SKILL.md +20 -5
  243. package/dist/filters/types.d.ts +0 -27
  244. package/dist/filters/types.js +0 -1
  245. package/dist/model/filter-pushdown.d.ts +0 -106
  246. package/dist/model/filter-pushdown.js +0 -147
package/CHANGELOG.md CHANGED
@@ -4,21 +4,216 @@ All notable changes to `@viewkitjs/views`. `0.x`: the API may change between min
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
- The grid's rendering, which ships in 0.2.0.
7
+ ## [0.2.0] — 2026-10-31
8
+
9
+ The grid's rendering, behind its own door, `@viewkitjs/views/grid`, and the package's documentation in `docs/`.
10
+ It needs `@viewkitjs/fields` 0.9.
11
+
12
+ ### For an adapter
13
+
14
+ - Messages: five keys are new, `views.menus.row-delete-failed`, `views.grid.paste-other-currency`,
15
+ `views.grid.paste-ambiguous-option`, `views.grid.paste-skipped` and `views.grid.fill-skipped`, and one is gone,
16
+ `views.grid.paste-failed`. A catalog that words its own messages adds the new ones and drops the old one, which
17
+ `ViewsMessage`, a closed union, no longer holds; one that leaves a key out reads it in the package's English.
18
+ Each is worded in its own line, here or under Changed.
19
+
20
+ - A new message, `views.menus.row-delete-failed` "Failed to delete the row": the plain row menu's error toast when
21
+ the delete your `onDelete` ran rejects. A catalog that leaves it out gets the English.
22
+ - The grid stops its sticky header and its group headers under `--vk-pinned-top`, the height of what your surface
23
+ pins above it (a tab strip, a toolbar), read as `0px` when you declare none: declare it where you pin something
24
+ over a grid. The grid read `--drawer-pinned-top` before: an app that set it for the grid sets `--vk-pinned-top`.
25
+ - A new, optional port, `confirm({ message, confirmLabel, subject, destructive })`, resolving to whether the person
26
+ said yes. The plain row menu's Delete asks it, `message` worded by `views.menus.row-delete-confirm`,
27
+ `confirmLabel` by `views.menus.row-delete`, and `subject` the host's `deleteLabel`. Hand your own dialog through it
28
+ to keep the plain row menu; hand nothing and Delete asks the browser's own confirm, as in 0.1.0. A rejection or a
29
+ throw counts as no.
30
+ - `Menu`: a group marked `disabled` reaches your `Menu` with every row under it marked `disabled`. Draw each row by
31
+ its own flag; nothing else is needed.
32
+ - Four slots stay as they are, and the handling in "Writing an adapter" is the contract's answer: `Menu`'s anchor (the
33
+ menu library's root, positioner and popup), `Popover`'s `chrome: "menu"` (your menu surface laid over the card, no
34
+ inset), `Command.Input`'s `chrome: "bare"` (the command library's own input) and `Sheet`'s `snap` (map it onto your
35
+ snap points, or ignore it).
36
+ - Now said, with nothing to change for an adapter that already does it: `Popover`'s `chrome: "menu"` has no card
37
+ width (it is as wide as its list); `Command.Item`'s `chosen` (you colour the item, the package's row inside draws
38
+ the check, so hide your copy's own tick); and `AppIcon` (it draws on the first paint: a static record of your icons,
39
+ never icons loaded on demand).
40
+ - `Command.Input`: the place editor focuses its country and region search through the input's `ref`, with
41
+ `preventScroll`, no longer through `autoFocus`. Forward `ref` to the input, as the contract already asks.
42
+ - `Popover`: an editor opened with `initialFocus={false}` takes its own focus with `preventScroll`, so a popup that
43
+ places itself after mounting no longer jumps the page. An editor's popover positioned `fixed` only to hide that
44
+ jump can go back to your library's default.
45
+ - `Command.Input`: the grid's Add column search focuses through the input's `ref`, with `preventScroll`, no longer
46
+ through `autoFocus`, and its popover opens with `initialFocus={false}`. Nothing in the package passes `autoFocus`
47
+ any more, so a popover positioned `fixed` only to hide the opening jump can go back to your library's default for
48
+ the whole grid.
49
+ - `Row`'s `opens`: your row says a dialog opens beside it, `aria-haspopup="dialog"` with `aria-expanded` from
50
+ `open`. The flyout is the components map's `Popover`, a dialog of plain rows, not a menu, and a row that said
51
+ `menu` had a screen reader announce a menu it never found.
52
+ - A list's CSV export of a money column writes the figure the column shows, in its reading. A column that binds its own
53
+ raw read wrote the stored amount before.
8
54
 
9
55
  ### Added
10
56
 
57
+ - The `confirm` port: an app keeps the plain row menu and asks before a delete in its own dialog. `useViews().ports`
58
+ always carries one (`ViewsResolvedPorts`), the browser's where the app handed none.
59
+ - The grid, at `@viewkitjs/views/grid`: `GridTable` with its props, `useGridTablePrefs`, its group and figure types,
60
+ and the helpers a host's binding shares with it (the commit types, a column's filter values, a cell's copy text and
61
+ edit baseline, the title link's class).
11
62
  - A column's menu is drawn with the package's own pieces: it opens the components map's `Popover` in the
12
63
  `vk-grid-column-menu` slot, its rows are the `Row` atom, its colours the `Tag` atom, and each knob's choices fly out
13
64
  of a `vk-grid-flyout` popover beside the row, one open at a time, after a short hover or at once on a tap.
65
+ - The package ships its documentation in `docs/`, starting at `docs/index.md`: getting started, from install to a grid
66
+ drawn with your own primitives; a guide per concept (the provider, ports, atoms, the display, editors and the edit
67
+ session, columns, cells, selection and the grid); and a reference per door naming every export. Every example in the
68
+ docs and the README is compiled and run against the packed package before each release.
69
+ - The contract states the four shapes of a value (stored, draft, commit, display) per type, what an edit core never
70
+ does, and how a `command` field is edited by verbs on every surface.
71
+ - `@viewkitjs/views/grid` exports `GridSortState`, `GridGroupSortOption`, `GridCellCommitFn` and `GridCellsCommitFn`
72
+ by name, the types an app writes the grid's `sort`, `sortOptions`, `onCellCommit` and `onCellsCommit` against. Before,
73
+ they were reachable only as `GridTableProps<Row>["sort"]` and the like, which still works.
74
+ - The grid draws every slot the contract names, so a skin reaches each part through `data-slot`: `vk-grid-header`
75
+ and `vk-grid-header-cell`, `vk-grid-row` and `vk-grid-cell`, `vk-grid-group` and `vk-grid-group-header`,
76
+ `vk-grid-footer` and `vk-grid-footer-cell`, `vk-grid-rail`, `vk-grid-tail` (the right tail of the header, each
77
+ row and the footer: a row's ⋯, the header's + Add column), `vk-grid-editor` (an inline editor, or
78
+ the popup of an anchored one), `vk-grid-outline` (the focused cell's ring and the range's edges) and
79
+ `vk-grid-resize-handle`. Before: only the frame, the row's ⋯ and the menus carried one.
14
80
 
15
81
  ### Changed
16
82
 
83
+ - The peer `@viewkitjs/fields` is `^0.9.0` (was `^0.8.0`): install fields 0.9 beside views 0.2. Under `0.x` a
84
+ `^0.9.0` peer accepts no 0.10.
85
+
86
+ - The grid's layout variables are `--vk-*` names (the contract's Tokens, which now lists `--vk-tail-pl` too): a skin or
87
+ an app that set a `--grid-*` name, `--grid-tail-pl` included, sets its `--vk-*` name.
88
+ - The grid's own variables are `--vk-drag-shift` and `--vk-col-w-<id>` (were `--drag-shift` and `--gw-<id>`), which
89
+ the contract names internal: an app neither sets nor reads them.
17
90
  - 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
91
  inside a popup outside the grid's tree (a toolbar's menu, a select in a window the app opens) now clears the
19
92
  focused cell, and a press on an overlay drawn inside the grid's root (a selection bar and its sheet, a
20
93
  confirmation window) now keeps it.
21
94
  - The grid turns mouse drag-select off itself; it no longer depends on what wraps a row.
95
+ - `densityStyle` writes `--vk-row-py`, `--vk-head-mb` and `--vk-row-gap` (were `--dt-row-py`, `--dt-head-mb` and
96
+ `--dt-row-gap`), now the contract's Tokens, with the same values at every density: an app whose rows look read or
97
+ set an old name reads or sets its `--vk-*` name.
98
+ - `ListFilterCapability` is `{ mode: "unavailable"; reason: string }`, the one answer `buildColumnFilters` reads. Its
99
+ `server` and `local` members built a column exactly as no entry: an app that hands `capabilities` to
100
+ `buildColumnFilters` drops those entries and keeps its unavailable ones.
101
+ - `formatMoney` moves from the package's root to `@viewkitjs/views/display`, beside `formatNumberValue`, and writes an
102
+ amount as a money cell does: through the presentation's `number` for the viewer, instead of in the `en-US` locale
103
+ whatever the viewer's. It takes the options a cell gets (`presentation`, `viewer`) as a fourth argument; with none it
104
+ reads in the default presentation and the neutral conventions (`en-GB`), so a dollar amount there reads
105
+ "US$109.00", not "$109.00". To keep your app's look, hand it your presentation and viewer:
106
+
107
+ ```ts
108
+ // before
109
+ import { formatMoney } from "@viewkitjs/views";
110
+ formatMoney(1234.5, "EUR"); // "€1,234.50", on every page
111
+
112
+ // after
113
+ import { formatMoney } from "@viewkitjs/views/display";
114
+ formatMoney(1234.5, "EUR", 2, { presentation, viewer }); // "1.234,50 EUR" for a Romanian viewer
115
+ ```
116
+ - Two doc comments your editor shows on hover say what their code does: `normalizeGroupSummary` returns `[]`, a bare
117
+ group name, for a value it cannot read, never the default, and `setDurationStyle` always writes the column's entry,
118
+ never dropping one.
119
+ - The contract describes `vk-grid-rail` as the checkbox lane: the group caret is drawn in `vk-grid-group-header`.
120
+ - The grid's doc comments, which your editor shows on hover, say what the code does in the library's own terms: none
121
+ names a tracker key, a plan or a path in another app any more, and a check in the package holds it.
122
+ - A paste or a fill of a money cell into a record that holds another currency is refused, with the message
123
+ `views.grid.paste-other-currency` ("This record is in EUR"); the copied currency is carried only into a record with
124
+ none of its own. Before, the copied currency was carried over, re-denominating the record. An app that words its own
125
+ messages adds this one.
126
+ - `readMoneyColumn` sets the column's `editAccessor` to the row's own amount, in every reading, keeping one the column
127
+ already has.
128
+ - A pasted label two options share is refused with the new message `views.grid.paste-ambiguous-option`, instead of
129
+ landing on one of them; an app that words its own messages adds it.
130
+ - A paste or a fill that refuses cells says why. One toast per reason it met, with how many cells that reason refused:
131
+ `views.grid.paste-skipped` and `views.grid.fill-skipped`, each `{ count, reason }` ("2 cells weren't filled: This
132
+ record is in EUR"), the `reason` one of the paste's own refusals in your words. A paste or a fill of one cell still
133
+ says the reason alone. Before, any refusal of more than one cell said only `views.grid.paste-failed` ("Failed to
134
+ paste 2 cells"), a fill included. The cells that fit are written, as before.
135
+ - `views.grid.paste-failed` is removed. An app that words its own messages replaces it with the two new keys:
136
+
137
+ ```ts
138
+ // before
139
+ case "views.grid.paste-failed":
140
+ return `${message.values.count} cells could not be pasted`;
141
+
142
+ // after
143
+ case "views.grid.paste-skipped":
144
+ return `${message.values.count} cells were not pasted: ${message.values.reason}`;
145
+ case "views.grid.fill-skipped":
146
+ return `${message.values.count} cells were not filled: ${message.values.reason}`;
147
+ ```
148
+
149
+ ### Fixed
150
+
151
+ - A menu group marked `disabled` disables its rows in every adapter: before, each row followed only its own flag, so a
152
+ disabled group's rows could still be pressed.
153
+ - The plain row menu's Delete, confirmed, tells the person when the delete fails: a rejecting `onDelete` calls the
154
+ toast port's `error` with `views.menus.row-delete-failed`. Before: the rejection went unhandled and the row stayed
155
+ with no word.
156
+ - An email, one or several, draws as plain text when the host's own slot owns the click (`slotOwnsClick`), as a
157
+ link, a domain and a phone already did, so the click reaches the host's row. Without it, each address is still a
158
+ `mailto:` link.
159
+ - A percent on Bar keeps a track you can read: the track never narrows below 1.5rem, and the figure's slot is the
160
+ figure's own width (it counted a whole character each for the point and the sign). A narrow percent column on Bar
161
+ shows the figure alone. Before: a column too narrow for both crushed a 100% bar to a dot.
162
+ - A grid copy of a phone, one or several, and a CSV export of its column through `cellCopyText`, write each phone as
163
+ `phoneText` writes it, in its international form, the main one first. Before: `[object Object]` for each.
164
+ - Opening an editor leaves the page where it was: the chips, name, number, range, value list and place editors, the
165
+ place editor's searches and the grid's long-text editor take focus with `preventScroll`. Before: on a popover that
166
+ places itself after mounting, the page jumped to where the popup sat before it was placed.
167
+ - A place and a phone drawn with no viewer (`renderFieldValue(field, value)`) take the provider's conventions, as a
168
+ date, a number, a percent and an amount do: the country is named in the app's language, a phone from the app's
169
+ region is written nationally, and its extension in the app's words. Before: the country was named in English
170
+ and the phone written internationally, so the place display and the place editor beside it disagreed.
171
+ - A percent on Bar never loses its leading digits: a figure wider than its box spills into the cell's padding, and
172
+ past that it is cut at its end with an ellipsis ("100.…"). At a 60px column and the default density a whole
173
+ figure fits at 0 decimals; 1 and 2 need a wider column. Before: the figure was cut at its front, and a 100.0 % row read "00.0 %".
174
+ - A selected range shows the values inside it: its tint drew over every cell's value, the anchor's included, so the
175
+ cells read as empty while the range was held. The tint now sits under the value; its colour, its boundary, the
176
+ anchor's ring and the fill dot are unchanged.
177
+ - Opening the grid's "+ Add column" can no longer scroll the page: its search took focus before a popover that
178
+ places itself after mounting had moved it to its anchor.
179
+ - The contract counts eighteen doors, as the package declares, and the usage skill names all of them.
180
+ - The contract says what the `viewPrefs` port is read for: no view reads it; the grid's preferences come in through
181
+ `useGridTablePrefs`, from wherever your app keeps them.
182
+ - The grid's triggers say what they open: the header cell that opens a column's menu and the footer cell that opens
183
+ its figure picker take `role="button"` and `aria-haspopup="dialog"`, and the group band's ⋯ says `dialog` too.
184
+ Before, each said `menu` over a popover that is a dialog.
185
+ - A money column read in another currency now edits the amount each row stores, in the row's own currency: its
186
+ editor opens on that amount, and undo, cut, Delete, Clear, copy, paste and fill carry it. Before, they carried the
187
+ converted figure beside the row's own currency, so an undo or a paste could store the converted figure as an amount
188
+ in the row's currency. The cell, its total, sorting, grouping and filtering still read the converted figure.
189
+ - Undoing a write into an empty number, percent or money cell empties it again. Before, it wrote 0. A fill from an
190
+ empty cell no longer writes 0 either: it empties a column that can be emptied, and skips one that can't.
191
+ - A copy of a number, percent or money cell pasted inside the grid lands as the number it copied, whatever the
192
+ conventions read a decimal point as.
193
+ - A select, status or multiselect cell copies as the labels it shows, alone, in a range and in an export, instead of
194
+ its stored keys. A pasted label lands on its option, from the grid or from a spreadsheet; a pasted key still lands
195
+ too, an exact match winning over one that differs only in case, and a copy pasted inside the grid lands on the exact
196
+ option it copied.
197
+ - With Wrap columns on, the selection rail beside a row that runs to several lines draws its line at the row's bottom
198
+ and its backing over the whole row, instead of at a one-line row's height. The checkbox stays level with the first
199
+ line.
200
+ - A fill of a money, percent or date-and-time cell no longer draws "[object Object]" in the filled cells until its
201
+ save lands, nor warns "Value was changed elsewhere" when it does. It paints nothing early, as a paste and the editor
202
+ already did: each filled cell keeps its figure until the save's refetch draws the new one. A fill of a relation, a
203
+ range or a list of several values does the same. A text, a select or a yes/no fill still shows at once.
204
+
205
+ ### Removed
206
+
207
+ - The filter capability split and its wire format, which nothing sent: `validateFilterCapabilities`,
208
+ `ListFilterCapabilityError`, `splitFilterRules`, `GridFilterSplit`, `GridPushdownSupport`, `serializeFilters`,
209
+ `effectiveDecimals`, `gridFilterSupport`, `ListWireRule`, `ListWireRuleState` and `GRID_FILTER_PARAM_MAX_BYTES`. A
210
+ list filters its rules in the browser, or evaluates its view at its source; the source registry
211
+ (`defineGridFilters` and its types) and `ListFilterCapability`, which the Filter panel reads, stay.
212
+ - `auditGridFilters`, a filter registry drift check for the filter split, which nothing called. The source registry
213
+ (`defineGridFilters` and its types) stays.
214
+ - `renderAs` on `FilterConfigBase`, which nothing read. `countsAsFilter` stays.
215
+ - `onListConfigChange` and `listWritable` on `GridTableProps`, which the grid never read. The grid reads `listConfig`
216
+ only; a settings surface of your own changes it and hands the grid the new value.
22
217
 
23
218
  ## [0.1.0] — 2026-10-30
24
219
 
package/README.md CHANGED
@@ -1,51 +1,100 @@
1
1
  # ViewKit views
2
2
 
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.
3
+ The grid, its cells, the field display and the editors over typed fields: a headless engine every app installs and never edits, and a default rendering written to skin discipline — markup, classes and slots only, states as `data-*` attributes, primitives handed in by the app, geometry through `--vk-*` variables. By Sheaf.
4
+
5
+ `@viewkitjs/fields` says what a value is; this package draws it and edits it. It ships no UI library of its own: your app hands in its button, popover, menu, command list and calendar through a components map, its icons by meaning, its toast, clipboard and per-device store as ports, and its wording as messages, so every view wears your app's look.
36
6
 
37
7
  ## Install
38
8
 
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.
9
+ ```sh
10
+ pnpm add @viewkitjs/views @viewkitjs/fields zod
11
+ ```
12
+
13
+ ESM only. Node 20 or later. `react` and `react-dom` 19 and `@viewkitjs/fields` are peer dependencies. Add one `@source` line so Tailwind sees the package, and map its colours onto your theme: [docs/install.md](./docs/install.md).
14
+
15
+ ## Getting started
16
+
17
+ Fields bound to your rows become the grid's columns. This block runs as written; [the getting-started page](./docs/getting-started.md) carries on from it to your primitives, the provider and the grid on screen.
18
+
19
+ ```ts
20
+ import assert from "node:assert/strict";
21
+ import { defineFields } from "@viewkitjs/fields";
22
+ import { bindFields, columnFrom, columnWritable } from "@viewkitjs/views";
23
+
24
+ const DEAL_FIELDS = defineFields({
25
+ entity: "deal",
26
+ identity: "title",
27
+ fields: {
28
+ title: { type: "text", label: "Title", required: true },
29
+ value: { type: "currency", label: "Value", code: { fixed: "EUR" } },
30
+ },
31
+ });
32
+
33
+ type Deal = { id: string; title: string; value: number };
34
+
35
+ // How each field reads on your row, and how an edit maps onto your request's body.
36
+ const DEAL_BINDINGS = bindFields<Deal, typeof DEAL_FIELDS>(DEAL_FIELDS, {
37
+ title: { read: (deal) => deal.title, write: (_deal, commit) => ({ body: { title: commit } }) },
38
+ value: { read: (deal) => deal.value },
39
+ });
40
+
41
+ // A column is what the grid draws: its type, format and edits come from the field and the binding.
42
+ const title = columnFrom(DEAL_BINDINGS.title, { id: "title", width: 240, editable: true });
43
+ const value = columnFrom(DEAL_BINDINGS.value, { id: "value", width: 120 });
44
+
45
+ assert.equal(title.type, "title");
46
+ assert.equal(columnWritable(title), true);
47
+ assert.equal(columnWritable(value), false); // no write: read-only on every surface
48
+ ```
49
+
50
+ Then mount `ViewsProvider` once with your primitives and draw `GridTable` from `@viewkitjs/views/grid` with the rows, the columns, each row's id and what opening a row does.
42
51
 
43
- ## Reshape
52
+ ## Documentation
44
53
 
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.
54
+ The package ships its documentation in `docs/`, starting at [docs/index.md](./docs/index.md). Every example in it is compiled and run against the packed package before each release.
55
+
56
+ - [Getting started](./docs/getting-started.md): install, fields bound to your rows, columns, your primitives, the provider and the grid.
57
+ - [Install](./docs/install.md): the Tailwind line and the colour block.
58
+
59
+ Guides:
60
+
61
+ - [The provider](./docs/guides/the-provider.md): mounting it once, your adapter over your own primitives, icons, messages and presentation.
62
+ - [Ports](./docs/guides/ports.md): your toast, haptics, clipboard, per-device store and confirm dialog.
63
+ - [Atoms](./docs/guides/atoms.md): the small pieces every view is built from, and swapping them for your own.
64
+ - [The display](./docs/guides/display.md): one renderer per field type, and the string formatters.
65
+ - [Editors and the edit session](./docs/guides/editors.md): one editor per field type, what an editor owns and what its host owns.
66
+ - [Columns](./docs/guides/columns.md): a field bound to your row, the column built from it, and what may be done to it.
67
+ - [Cells](./docs/guides/cells.md): a column's value drawn in a cell, outside the grid too.
68
+ - [Selection](./docs/guides/selection.md): a list's selection, its checkbox, drag-select and the row-click rules.
69
+ - [The grid](./docs/guides/the-grid.md): grouping, sorting, writes, preferences, figures and the editing rules.
70
+ - [The rendering contract](./docs/contract.md): every public name and what each door holds; [reshaping a view](./docs/reshaping.md): the cheapest change first.
71
+
72
+ References, one per door, each naming every export: [`@viewkitjs/views`](./docs/reference/views.md), [`/react`](./docs/reference/react.md), [`/display`](./docs/reference/display.md), [`/editors`](./docs/reference/editors.md), [`/editors/select`](./docs/reference/editors-select.md), [`/editors/relation`](./docs/reference/editors-relation.md), [`/editors/number`](./docs/reference/editors-number.md), [`/editors/range`](./docs/reference/editors-range.md), [`/editors/name`](./docs/reference/editors-name.md), [`/editors/location`](./docs/reference/editors-location.md), [`/editors/value-list`](./docs/reference/editors-value-list.md), [`/editors/date`](./docs/reference/editors-date.md), [`/editors/chips`](./docs/reference/editors-chips.md), [`/editors/session`](./docs/reference/editors-session.md), [`/editors/open-values`](./docs/reference/editors-open-values.md), [`/cells`](./docs/reference/cells.md), [`/selection`](./docs/reference/selection.md), [`/grid`](./docs/reference/grid.md).
73
+
74
+ ## Doors
75
+
76
+ | Import | Holds |
77
+ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
78
+ | `@viewkitjs/views` | the rendering contract (slots, states, tokens, the components map, atom and icon names, ports, message keys and their English resolver) and the model: columns, preferences, filters, figures, groups, bindings and money. No React at runtime |
79
+ | `@viewkitjs/views/react` | `ViewsProvider`, `useViews`, the default atoms, and the types an adapter implements |
80
+ | `@viewkitjs/views/display` | the field display: one renderer per storage type, the string formatters, the viewer |
81
+ | `@viewkitjs/views/editors` | the edit registry: which editor each type opens |
82
+ | `@viewkitjs/views/editors/<name>` | one editor each: `select`, `relation`, `number`, `range`, `name`, `location`, `value-list`, `date`, `chips` |
83
+ | `@viewkitjs/views/editors/session`, `/editors/open-values` | the anchored edit session every host shares, and an open field's values carried to its editors |
84
+ | `@viewkitjs/views/cells` | a column's typed cell, and its column-shaped string formatters |
85
+ | `@viewkitjs/views/selection` | a list's selection: the model, the hook, the row checkbox, drag-select and the row-click rules |
86
+ | `@viewkitjs/views/grid` | the grid: the table, its props, its preferences, and the helpers a host shares with it |
87
+
88
+ Eighteen doors; there are no other subpaths.
47
89
 
48
90
  ## For coding agents
49
91
 
50
- The package ships a usage skill at `skills/views/SKILL.md`; its examples compile against the packed
51
- artifact on every check.
92
+ The package ships a usage skill at `skills/views/SKILL.md`. Its example is compiled against the published artifact on every release.
93
+
94
+ ## Status
95
+
96
+ `0.x`: the API may change between minor versions.
97
+
98
+ ## Licence
99
+
100
+ Proprietary. See [LICENSE.md](./LICENSE.md).
package/dist/atoms/Row.js CHANGED
@@ -26,5 +26,5 @@ export function DefaultRow({ onClick, onMouseDown, disabled, interactive = true,
26
26
  if (!interactive) {
27
27
  return (_jsx("div", { "data-slot": "vk-row", title: title, className: cx(frame, className), children: body }));
28
28
  }
29
- return (_jsx("button", { type: "button", "data-slot": "vk-row", "data-disabled": disabled || undefined, "data-open": open || undefined, "aria-haspopup": opens ? "menu" : undefined, "aria-expanded": opens ? Boolean(open) : undefined, disabled: disabled, onClick: onClick, onMouseDown: onMouseDown, title: title, role: role, "aria-selected": role ? ariaSelected : undefined, className: cx(frame, "group/row transition-colors hover:bg-(color:--vk-hovered) data-open:bg-(color:--vk-pressed) disabled:pointer-events-none disabled:opacity-50", className), children: body }));
29
+ return (_jsx("button", { type: "button", "data-slot": "vk-row", "data-disabled": disabled || undefined, "data-open": open || undefined, "aria-haspopup": opens ? "dialog" : undefined, "aria-expanded": opens ? Boolean(open) : undefined, disabled: disabled, onClick: onClick, onMouseDown: onMouseDown, title: title, role: role, "aria-selected": role ? ariaSelected : undefined, className: cx(frame, "group/row transition-colors hover:bg-(color:--vk-hovered) data-open:bg-(color:--vk-pressed) disabled:pointer-events-none disabled:opacity-50", className), children: body }));
30
30
  }
@@ -1,2 +1,2 @@
1
1
  import type { ViewsRowMenuProps } from "./types.js";
2
- export declare function DefaultRowMenu({ children, rowId, items, openHref, onDelete }: ViewsRowMenuProps): import("react/jsx-runtime").JSX.Element;
2
+ export declare function DefaultRowMenu({ children, rowId, items, openHref, onDelete, deleteLabel }: ViewsRowMenuProps): import("react/jsx-runtime").JSX.Element;
@@ -34,8 +34,8 @@ function hostEntry(item, index) {
34
34
  },
35
35
  };
36
36
  }
37
- export function DefaultRowMenu({ children, rowId, items, openHref, onDelete }) {
38
- const { components, icons, messages } = useViews();
37
+ export function DefaultRowMenu({ children, rowId, items, openHref, onDelete, deleteLabel }) {
38
+ const { components, icons, messages, ports } = useViews();
39
39
  const { Menu } = components;
40
40
  const [point, setPoint] = useState(null);
41
41
  const openedAt = useRef(0);
@@ -68,8 +68,19 @@ export function DefaultRowMenu({ children, rowId, items, openHref, onDelete }) {
68
68
  icon: _jsx(Delete, { className: "h-4 w-4" }),
69
69
  destructive: true,
70
70
  onSelect: () => {
71
- if (window.confirm(messages({ key: "views.menus.row-delete-confirm" })))
72
- void onDelete(rowId);
71
+ const request = {
72
+ message: messages({ key: "views.menus.row-delete-confirm" }),
73
+ confirmLabel: messages({ key: "views.menus.row-delete" }),
74
+ ...(deleteLabel !== undefined && { subject: deleteLabel }),
75
+ destructive: true,
76
+ };
77
+ void new Promise((resolve) => resolve(ports.confirm(request)))
78
+ .catch(() => false)
79
+ .then((yes) => {
80
+ if (!yes)
81
+ return;
82
+ return new Promise((resolve) => resolve(onDelete(rowId))).catch(() => ports.toast.error(messages({ key: "views.menus.row-delete-failed" })));
83
+ });
73
84
  },
74
85
  },
75
86
  });
@@ -40,7 +40,7 @@ export type ViewsRowProps = ViewsRowContentProps & {
40
40
  disabled?: boolean;
41
41
  /** Default true. False draws a line that is read, not pressed. */
42
42
  interactive?: boolean;
43
- /** The row opens a flyout beside its menu: `aria-haspopup="menu"`, and `aria-expanded` from `open`. */
43
+ /** The row opens a flyout beside its menu, a dialog: `aria-haspopup="dialog"`, and `aria-expanded` from `open`. */
44
44
  opens?: boolean;
45
45
  /** The flyout this row opens is up now: `aria-expanded`, `data-open` and the pressed ground. */
46
46
  open?: boolean;
@@ -143,8 +143,8 @@ export type ViewsRowMenuItem = {
143
143
  };
144
144
  /** The row's right-click menu, around the row it opens on. The rendering builds `items` (the cell's
145
145
  * clipboard rows, Select, the host's verbs); the menu adds the page link before them and Delete after.
146
- * The default is the components map's `Menu` at the pointer; an app swaps in its own (a dialog before
147
- * a delete, a long-press). */
146
+ * The default is the components map's `Menu` at the pointer, its Delete asking the confirm port; an
147
+ * app swaps in its own (a long-press that selects). */
148
148
  export type ViewsRowMenuProps = {
149
149
  /** The row: right-click on it, or the row's ⋯, opens the menu. */
150
150
  children: ReactNode;
@@ -155,7 +155,7 @@ export type ViewsRowMenuProps = {
155
155
  openHref?: string;
156
156
  /** Absent: no Delete row. */
157
157
  onDelete?: (rowId: string) => Promise<void>;
158
- /** What Delete removes, for an app's own confirmation; the default's confirm doesn't use it. */
158
+ /** What Delete removes, handed to the confirm port as its `subject`. */
159
159
  deleteLabel?: string;
160
160
  /** Flips the row's selection, for an app whose long-press selects. Absent when the list can't select.
161
161
  * The default doesn't use it: on a phone the ⋯ is the way in. */
@@ -15,8 +15,9 @@ export type GridSlot = (typeof GRID_SLOTS)[number];
15
15
  /** The flags the rendering styles, as `data-*` attributes present when true. */
16
16
  export declare const GRID_STATES: readonly ["focused", "selected", "editing", "in-range", "range-edge", "pending", "invalid", "dragging", "empty", "frozen", "scrolled", "parked"];
17
17
  export type GridState = (typeof GRID_STATES)[number];
18
- /** The CSS variables the package owns: geometry and density. Its colours are `VK_COLOURS`, which the app declares. Today's `--grid-*` variables in the portal become these in the move. */
19
- export declare const VK_TOKENS: readonly ["--vk-scale", "--vk-row-h", "--vk-head-h", "--vk-footer-h", "--vk-label-h", "--vk-line-h", "--vk-chrome-h", "--vk-px", "--vk-cell-py", "--vk-tail-py", "--vk-rail-w", "--vk-rail-gap", "--vk-tail-w", "--vk-indent", "--vk-frozen-w", "--vk-scroll-mt", "--vk-glyph", "--vk-head-glyph", "--vk-text", "--vk-text-xs", "--vk-text-10", "--vk-head-text", "--vk-scrolled", "--vk-parked", "--vk-frozen-on"];
18
+ /** The CSS variables the package owns: geometry and density. Its colours are `VK_COLOURS`, which the app declares.
19
+ * The last three are `densityStyle`'s, written on the root of a rows view an app draws itself. */
20
+ export declare const VK_TOKENS: readonly ["--vk-scale", "--vk-row-h", "--vk-head-h", "--vk-footer-h", "--vk-label-h", "--vk-line-h", "--vk-chrome-h", "--vk-px", "--vk-cell-py", "--vk-tail-py", "--vk-tail-pl", "--vk-rail-w", "--vk-rail-gap", "--vk-tail-w", "--vk-indent", "--vk-frozen-w", "--vk-scroll-mt", "--vk-glyph", "--vk-head-glyph", "--vk-text", "--vk-text-xs", "--vk-text-10", "--vk-head-text", "--vk-scrolled", "--vk-parked", "--vk-frozen-on", "--vk-row-py", "--vk-head-mb", "--vk-row-gap"];
20
21
  export type VkToken = (typeof VK_TOKENS)[number];
21
22
  /** The colours the rendering paints, each a CSS variable the APP declares — the package
22
23
  * sets none, and names no variable of the app's own. An app maps each onto its tokens once
@@ -31,9 +32,19 @@ export declare const VK_OPTIONAL_COLOURS: readonly ["--vk-success", "--vk-warnin
31
32
  export type VkOptionalColour = (typeof VK_OPTIONAL_COLOURS)[number];
32
33
  /** Layout the APP may declare, read with a built-in fallback. `--vk-gutter` is the side padding the
33
34
  * page gives its content: the grid's rows run edge to edge and line their content up with it.
34
- * Undeclared, it reads `0px` — a grid flush with its container. */
35
- export declare const VK_OPTIONAL_LAYOUT: readonly ["--vk-gutter"];
35
+ * Undeclared, it reads `0px` — a grid flush with its container. `--vk-pinned-top` is how far
36
+ * down the surface's own pinned chrome reaches (a drawer's tab strip, a pinned toolbar): the
37
+ * grid's sticky header row and each group's header stop under it. Undeclared, it reads `0px`. */
38
+ export declare const VK_OPTIONAL_LAYOUT: readonly ["--vk-gutter", "--vk-pinned-top"];
36
39
  export type VkOptionalLayout = (typeof VK_OPTIONAL_LAYOUT)[number];
40
+ /** The grid's own machinery, set and read by the grid alone: prefixed because they share the
41
+ * global namespace, and not public. An app neither sets nor reads them, and they may change in
42
+ * any release. `--vk-drag-shift` is a header cell's offset while its column is dragged. */
43
+ export declare const VK_INTERNAL: readonly ["--vk-drag-shift"];
44
+ export type VkInternal = (typeof VK_INTERNAL)[number];
45
+ /** Internal families: a prefix, one variable per key after it. `--vk-col-w-<id>` is one
46
+ * column's resolved width, set on the grid's root for every visible column. */
47
+ export declare const VK_INTERNAL_FAMILIES: readonly ["--vk-col-w-"];
37
48
  /** The primitives an app hands in through the provider. */
38
49
  export declare const COMPONENT_NAMES: readonly ["Button", "Popover", "Tooltip", "Checkbox", "Menu", "Command", "Calendar", "Collapse", "Sheet", "AppIcon", "Markdown"];
39
50
  export type ComponentName = (typeof COMPONENT_NAMES)[number];
@@ -48,7 +59,7 @@ export type AtomSlot = (typeof ATOM_SLOTS)[number];
48
59
  export declare const ATOM_STATES: readonly ["chosen", "disabled", "muted", "checked", "open", "status", "platform"];
49
60
  export type AtomState = (typeof ATOM_STATES)[number];
50
61
  /** The runtime services an app hands in through the provider. */
51
- export declare const PORT_NAMES: readonly ["toast", "haptics", "clipboard", "viewPrefs"];
62
+ export declare const PORT_NAMES: readonly ["toast", "haptics", "clipboard", "viewPrefs", "confirm"];
52
63
  export type PortName = (typeof PORT_NAMES)[number];
53
64
  /** The glyphs the rendering asks the app for, by what they mean, never by a
54
65
  * library's name. The app maps each to its own icon component. */
@@ -257,6 +268,8 @@ export type ViewsMessage = {
257
268
  key: "views.menus.row-delete";
258
269
  } | {
259
270
  key: "views.menus.row-delete-confirm";
271
+ } | {
272
+ key: "views.menus.row-delete-failed";
260
273
  } | {
261
274
  key: "views.grid.figure";
262
275
  values: {
@@ -335,6 +348,16 @@ export type ViewsMessage = {
335
348
  values: {
336
349
  value: string;
337
350
  };
351
+ } | {
352
+ key: "views.grid.paste-ambiguous-option";
353
+ values: {
354
+ value: string;
355
+ };
356
+ } | {
357
+ key: "views.grid.paste-other-currency";
358
+ values: {
359
+ currency: string;
360
+ };
338
361
  } | {
339
362
  key: "views.grid.paste-pick";
340
363
  values: {
@@ -348,9 +371,16 @@ export type ViewsMessage = {
348
371
  } | {
349
372
  key: "views.grid.paste-not-range";
350
373
  } | {
351
- key: "views.grid.paste-failed";
374
+ key: "views.grid.paste-skipped";
375
+ values: {
376
+ count: number;
377
+ reason: string;
378
+ };
379
+ } | {
380
+ key: "views.grid.fill-skipped";
352
381
  values: {
353
382
  count: number;
383
+ reason: string;
354
384
  };
355
385
  } | {
356
386
  key: "views.grid.changed-elsewhere";
@@ -422,7 +452,7 @@ export type PlaceWordKey = Extract<ViewsMessageKey, `views.editors.place-${"regi
422
452
  export declare function placeWordKey(kind: "region", word: RegionWord): PlaceWordKey;
423
453
  export declare function placeWordKey(kind: "city", word: CityWord): PlaceWordKey;
424
454
  export declare function placeWordKey(kind: "postal", word: PostalWord): PlaceWordKey;
425
- export declare const VIEWS_MESSAGE_KEYS: readonly ["views.editors.tag-remove", "views.editors.marker-resolve", "views.editors.marker-no-reason", "views.editors.range-low", "views.editors.range-high", "views.editors.name-given", "views.editors.name-family", "views.editors.name-full", "views.editors.values-add", "views.editors.values-label", "views.editors.values-main", "views.editors.values-make-main", "views.editors.values-remove", "views.editors.place-country", "views.editors.place-country-search", "views.editors.place-change-country", "views.editors.place-region-search", "views.editors.place-line1", "views.editors.place-line2", "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", "views.editors.place-region-state", "views.editors.place-city-city", "views.editors.place-city-district", "views.editors.place-city-post-town", "views.editors.place-city-suburb", "views.editors.place-postal-eircode", "views.editors.place-postal-pin", "views.editors.place-postal-postal", "views.editors.place-postal-zip", "views.editors.place-required", "views.editors.place-region", "views.menus.part-row", "views.menus.sort-asc", "views.menus.sort-desc", "views.menus.sort-clear", "views.menus.group-by", "views.menus.ungroup", "views.menus.move-left", "views.menus.move-right", "views.menus.hide-column", "views.menus.format", "views.menus.date-style", "views.menus.show-time", "views.menus.duration-style", "views.menus.decimals", "views.menus.automatic", "views.menus.currency", "views.menus.percent-display", "views.menus.percent-display-option", "views.menus.colour", "views.menus.colours-reset", "views.menus.group-options", "views.menus.group-sort", "views.menus.search", "views.menus.group-show", "views.menus.group-count", "views.menus.group-hide", "views.menus.add-column-search", "views.menus.add-column-no-match", "views.menus.add-column-all-shown", "views.menus.copy", "views.menus.cut", "views.menus.paste", "views.menus.clear", "views.menus.edit", "views.menus.row-open", "views.menus.row-select", "views.menus.row-delete", "views.menus.row-delete-confirm", "views.grid.figure", "views.grid.figure-pick", "views.grid.add-column", "views.grid.loading", "views.grid.select-row", "views.grid.select-group", "views.grid.select-all", "views.grid.row-menu", "views.grid.group-expand", "views.grid.group-collapse", "views.grid.change-value", "views.grid.value", "views.grid.edit-value", "views.grid.read-only", "views.grid.read-only-why", "views.grid.locked", "views.grid.not-clearable", "views.grid.computed", "views.grid.cell-read-only", "views.grid.clear-none", "views.grid.write-not-list", "views.grid.write-not-boolean", "views.grid.write-marker", "views.grid.write-not-email", "views.grid.write-not-url", "views.grid.write-not-link", "views.grid.write-not-linkable", "views.grid.paste-refused", "views.grid.paste-empty", "views.grid.paste-not-number", "views.grid.paste-not-duration", "views.grid.paste-not-date", "views.grid.paste-not-option", "views.grid.paste-pick", "views.grid.paste-not-linkable", "views.grid.paste-not-range", "views.grid.paste-failed", "views.grid.changed-elsewhere", "views.grid.changed-elsewhere-cells", "views.grid.saved-value", "views.grid.saved-values", "views.grid.row-left", "views.display.just-now", "views.display.in", "views.display.today", "views.display.yesterday", "views.display.tomorrow", "views.display.month", "views.display.not-an-option", "views.display.needs-attention", "views.display.boolean", "views.display.show-all", "views.display.show-more", "views.display.show-less", "views.display.phone-extension", "views.display.phone-as-typed"];
455
+ export declare const VIEWS_MESSAGE_KEYS: readonly ["views.editors.tag-remove", "views.editors.marker-resolve", "views.editors.marker-no-reason", "views.editors.range-low", "views.editors.range-high", "views.editors.name-given", "views.editors.name-family", "views.editors.name-full", "views.editors.values-add", "views.editors.values-label", "views.editors.values-main", "views.editors.values-make-main", "views.editors.values-remove", "views.editors.place-country", "views.editors.place-country-search", "views.editors.place-change-country", "views.editors.place-region-search", "views.editors.place-line1", "views.editors.place-line2", "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", "views.editors.place-region-state", "views.editors.place-city-city", "views.editors.place-city-district", "views.editors.place-city-post-town", "views.editors.place-city-suburb", "views.editors.place-postal-eircode", "views.editors.place-postal-pin", "views.editors.place-postal-postal", "views.editors.place-postal-zip", "views.editors.place-required", "views.editors.place-region", "views.menus.part-row", "views.menus.sort-asc", "views.menus.sort-desc", "views.menus.sort-clear", "views.menus.group-by", "views.menus.ungroup", "views.menus.move-left", "views.menus.move-right", "views.menus.hide-column", "views.menus.format", "views.menus.date-style", "views.menus.show-time", "views.menus.duration-style", "views.menus.decimals", "views.menus.automatic", "views.menus.currency", "views.menus.percent-display", "views.menus.percent-display-option", "views.menus.colour", "views.menus.colours-reset", "views.menus.group-options", "views.menus.group-sort", "views.menus.search", "views.menus.group-show", "views.menus.group-count", "views.menus.group-hide", "views.menus.add-column-search", "views.menus.add-column-no-match", "views.menus.add-column-all-shown", "views.menus.copy", "views.menus.cut", "views.menus.paste", "views.menus.clear", "views.menus.edit", "views.menus.row-open", "views.menus.row-select", "views.menus.row-delete", "views.menus.row-delete-confirm", "views.menus.row-delete-failed", "views.grid.figure", "views.grid.figure-pick", "views.grid.add-column", "views.grid.loading", "views.grid.select-row", "views.grid.select-group", "views.grid.select-all", "views.grid.row-menu", "views.grid.group-expand", "views.grid.group-collapse", "views.grid.change-value", "views.grid.value", "views.grid.edit-value", "views.grid.read-only", "views.grid.read-only-why", "views.grid.locked", "views.grid.not-clearable", "views.grid.computed", "views.grid.cell-read-only", "views.grid.clear-none", "views.grid.write-not-list", "views.grid.write-not-boolean", "views.grid.write-marker", "views.grid.write-not-email", "views.grid.write-not-url", "views.grid.write-not-link", "views.grid.write-not-linkable", "views.grid.paste-refused", "views.grid.paste-empty", "views.grid.paste-not-number", "views.grid.paste-not-duration", "views.grid.paste-not-date", "views.grid.paste-not-option", "views.grid.paste-ambiguous-option", "views.grid.paste-other-currency", "views.grid.paste-pick", "views.grid.paste-not-linkable", "views.grid.paste-not-range", "views.grid.paste-skipped", "views.grid.fill-skipped", "views.grid.changed-elsewhere", "views.grid.changed-elsewhere-cells", "views.grid.saved-value", "views.grid.saved-values", "views.grid.row-left", "views.display.just-now", "views.display.in", "views.display.today", "views.display.yesterday", "views.display.tomorrow", "views.display.month", "views.display.not-an-option", "views.display.needs-attention", "views.display.boolean", "views.display.show-all", "views.display.show-more", "views.display.show-less", "views.display.phone-extension", "views.display.phone-as-typed"];
426
456
  /** What an app hands in: its wording for every message. A resolver that words
427
457
  * only some keys calls `resolveViewsMessage` for the rest; the provider does not. */
428
458
  export type ViewsMessageResolver = (message: ViewsMessage) => string;