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