@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.
- package/CHANGELOG.md +196 -1
- package/README.md +90 -41
- package/dist/atoms/Row.js +1 -1
- package/dist/atoms/RowMenu.d.ts +1 -1
- package/dist/atoms/RowMenu.js +15 -4
- package/dist/atoms/types.d.ts +4 -4
- package/dist/contract.d.ts +37 -7
- package/dist/contract.js +24 -5
- package/dist/display/format.d.ts +16 -1
- package/dist/display/format.js +10 -1
- package/dist/display/index.d.ts +1 -1
- package/dist/display/index.js +1 -1
- package/dist/display/link.js +5 -3
- package/dist/display/location.d.ts +4 -3
- package/dist/display/location.js +12 -5
- package/dist/display/options.d.ts +1 -1
- package/dist/display/percent.js +10 -3
- package/dist/display/phone.d.ts +2 -1
- package/dist/display/phone.js +8 -1
- package/dist/display/relation.js +1 -1
- package/dist/editors/ChipsEditor.js +1 -1
- package/dist/editors/LocationEditor.js +16 -17
- package/dist/editors/NameEditor.js +5 -4
- package/dist/editors/NumberEditor.js +2 -2
- package/dist/editors/RangeEditor.js +2 -2
- package/dist/editors/ValueListEditor.d.ts +2 -2
- package/dist/editors/ValueListEditor.js +8 -8
- package/dist/editors/edit-cores.d.ts +1 -1
- package/dist/fields/binding.d.ts +1 -1
- package/dist/fields/currency.d.ts +0 -10
- package/dist/fields/currency.js +0 -14
- package/dist/fields/money.d.ts +1 -0
- package/dist/fields/money.js +1 -0
- package/dist/filters/filter-model.d.ts +0 -1
- package/dist/filters/registry.d.ts +3 -36
- package/dist/filters/registry.js +0 -38
- package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
- package/dist/grid/chrome/GridAddColumn.js +29 -0
- package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
- package/dist/grid/chrome/GridAggregateMenu.js +27 -0
- package/dist/grid/chrome/GridCellEditors.d.ts +64 -0
- package/dist/grid/chrome/GridCellEditors.js +55 -0
- package/dist/grid/chrome/GridCellOutline.d.ts +70 -0
- package/dist/grid/chrome/GridCellOutline.js +21 -0
- package/dist/grid/chrome/GridChipsEditor.d.ts +28 -0
- package/dist/grid/chrome/GridChipsEditor.js +40 -0
- package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
- package/dist/grid/chrome/GridColumnColorSection.js +40 -0
- package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
- package/dist/grid/chrome/GridColumnDateSection.js +23 -0
- package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
- package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
- package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
- package/dist/grid/chrome/GridColumnMenu.js +99 -0
- package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
- package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
- package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
- package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
- package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
- package/dist/grid/chrome/GridColumnSortSection.js +16 -0
- package/dist/grid/chrome/GridDateEditor.d.ts +22 -0
- package/dist/grid/chrome/GridDateEditor.js +31 -0
- package/dist/grid/chrome/GridFlyout.d.ts +44 -0
- package/dist/grid/chrome/GridFlyout.js +80 -0
- package/dist/grid/chrome/GridFooter.d.ts +23 -0
- package/dist/grid/chrome/GridFooter.js +81 -0
- package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
- package/dist/grid/chrome/GridGroupMenu.js +57 -0
- package/dist/grid/chrome/GridHeader.d.ts +61 -0
- package/dist/grid/chrome/GridHeader.js +37 -0
- package/dist/grid/chrome/GridLongTextEditor.d.ts +36 -0
- package/dist/grid/chrome/GridLongTextEditor.js +127 -0
- package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
- package/dist/grid/chrome/GridMenuRow.js +15 -0
- package/dist/grid/chrome/GridNameEditor.d.ts +19 -0
- package/dist/grid/chrome/GridNameEditor.js +36 -0
- package/dist/grid/chrome/GridNumberEditor.d.ts +35 -0
- package/dist/grid/chrome/GridNumberEditor.js +25 -0
- package/dist/grid/chrome/GridRangeEditor.d.ts +20 -0
- package/dist/grid/chrome/GridRangeEditor.js +25 -0
- package/dist/grid/chrome/GridRelationEditor.d.ts +21 -0
- package/dist/grid/chrome/GridRelationEditor.js +30 -0
- package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
- package/dist/grid/chrome/GridResizeHandle.js +19 -0
- package/dist/grid/chrome/GridRow.d.ts +25 -0
- package/dist/grid/chrome/GridRow.js +136 -0
- package/dist/grid/chrome/GridRowActions.d.ts +32 -0
- package/dist/grid/chrome/GridRowActions.js +25 -0
- package/dist/grid/chrome/GridRowCells.d.ts +4 -0
- package/dist/grid/chrome/GridRowCells.js +133 -0
- package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
- package/dist/grid/chrome/GridRowGlyph.js +13 -0
- package/dist/grid/chrome/GridSelectEditor.d.ts +18 -0
- package/dist/grid/chrome/GridSelectEditor.js +49 -0
- package/dist/grid/chrome/GridStructure.d.ts +48 -0
- package/dist/grid/chrome/GridStructure.js +45 -0
- package/dist/grid/chrome/GridTable.d.ts +4 -0
- package/dist/grid/chrome/GridTable.js +125 -0
- package/dist/grid/chrome/GridTableSurface.d.ts +15 -0
- package/dist/grid/chrome/GridTableSurface.js +6 -0
- package/dist/grid/chrome/GridTextEditor.d.ts +11 -0
- package/dist/grid/chrome/GridTextEditor.js +40 -0
- package/dist/grid/chrome/GridValueListEditor.d.ts +18 -0
- package/dist/grid/chrome/GridValueListEditor.js +36 -0
- package/dist/grid/chrome/StuckMarker.d.ts +16 -0
- package/dist/grid/chrome/StuckMarker.js +34 -0
- package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
- package/dist/grid/chrome/cell-clipboard.js +28 -0
- package/dist/grid/chrome/cells.d.ts +21 -0
- package/dist/grid/chrome/cells.js +20 -0
- package/dist/grid/chrome/checks.d.ts +35 -0
- package/dist/grid/chrome/checks.js +22 -0
- package/dist/grid/chrome/column-glyph.d.ts +14 -0
- package/dist/grid/chrome/column-glyph.js +44 -0
- package/dist/grid/chrome/editors.d.ts +9 -0
- package/dist/grid/chrome/editors.js +10 -0
- package/dist/grid/chrome/grid-cell-classes.d.ts +59 -0
- package/dist/grid/chrome/grid-cell-classes.js +30 -0
- package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
- package/dist/grid/chrome/grid-menu-search.js +7 -0
- package/dist/grid/chrome/grid-row-props.d.ts +131 -0
- package/dist/grid/chrome/grid-row-props.js +1 -0
- package/dist/grid/chrome/grid-styles.d.ts +37 -0
- package/dist/grid/chrome/grid-styles.js +8 -0
- package/dist/grid/chrome/grid-table-props.d.ts +173 -0
- package/dist/grid/chrome/grid-table-props.js +1 -0
- package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
- package/dist/grid/chrome/useGridBatchApi.js +35 -0
- package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
- package/dist/grid/chrome/useGridColumnLayout.js +206 -0
- package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
- package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
- package/dist/grid/chrome/useGridKeyboard.d.ts +47 -0
- package/dist/grid/chrome/useGridKeyboard.js +274 -0
- package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
- package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
- package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
- package/dist/grid/chrome/useGridRailReveal.js +67 -0
- package/dist/grid/chrome/useGridRangeActions.d.ts +49 -0
- package/dist/grid/chrome/useGridRangeActions.js +188 -0
- package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
- package/dist/grid/chrome/useGridRangeGestures.js +190 -0
- package/dist/grid/chrome/useGridRowContextMenu.d.ts +35 -0
- package/dist/grid/chrome/useGridRowContextMenu.js +127 -0
- package/dist/grid/chrome/useGridScaleStyles.d.ts +1 -0
- package/dist/grid/chrome/useGridScaleStyles.js +29 -0
- package/dist/grid/chrome/useGridScrollSync.d.ts +38 -0
- package/dist/grid/chrome/useGridScrollSync.js +176 -0
- package/dist/grid/chrome/useGridTableInteractionModel.d.ts +55 -0
- package/dist/grid/chrome/useGridTableInteractionModel.js +197 -0
- package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
- package/dist/grid/chrome/useGridTableSelection.js +55 -0
- package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
- package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
- package/dist/grid/core/clipboard-model.d.ts +81 -0
- package/dist/grid/core/clipboard-model.js +291 -0
- package/dist/grid/core/column-values.d.ts +27 -0
- package/dist/grid/core/column-values.js +76 -0
- package/dist/grid/core/commit-model.d.ts +34 -0
- package/dist/grid/core/commit-model.js +3 -0
- package/dist/grid/core/coordinates.d.ts +48 -0
- package/dist/grid/core/coordinates.js +27 -0
- package/dist/grid/core/edit-values.d.ts +9 -0
- package/dist/grid/core/edit-values.js +1 -0
- package/dist/grid/core/editing-controller.d.ts +59 -0
- package/dist/grid/core/editing-controller.js +240 -0
- package/dist/grid/core/editing-model.d.ts +78 -0
- package/dist/grid/core/editing-model.js +136 -0
- package/dist/grid/core/grid-scale.d.ts +14 -0
- package/dist/grid/core/grid-scale.js +8 -0
- package/dist/grid/core/nav.d.ts +94 -0
- package/dist/grid/core/nav.js +92 -0
- package/dist/grid/core/pending-reconciliation.d.ts +50 -0
- package/dist/grid/core/pending-reconciliation.js +49 -0
- package/dist/grid/core/range-model.d.ts +25 -0
- package/dist/grid/core/range-model.js +59 -0
- package/dist/grid/core/spreadsheet-operations.d.ts +85 -0
- package/dist/grid/core/spreadsheet-operations.js +253 -0
- package/dist/grid/core/useGridEditing.d.ts +43 -0
- package/dist/grid/core/useGridEditing.js +90 -0
- package/dist/grid/core/useGridRange.d.ts +20 -0
- package/dist/grid/core/useGridRange.js +24 -0
- package/dist/grid/core/value-equality.d.ts +32 -0
- package/dist/grid/core/value-equality.js +34 -0
- package/dist/grid/index.d.ts +18 -0
- package/dist/grid/index.js +5 -0
- package/dist/grid/useGridTablePrefs.d.ts +50 -0
- package/dist/grid/useGridTablePrefs.js +101 -0
- package/dist/index.d.ts +0 -1
- package/dist/index.js +0 -1
- package/dist/internal/viewport.d.ts +5 -0
- package/dist/internal/viewport.js +29 -0
- package/dist/model/column-capabilities.d.ts +2 -2
- package/dist/model/column-state.d.ts +1 -1
- package/dist/model/density.js +3 -3
- package/dist/model/filter-capabilities.d.ts +1 -1
- package/dist/model/filter-capabilities.js +1 -1
- package/dist/model/index.d.ts +4 -6
- package/dist/model/index.js +0 -1
- package/dist/model/preferences.d.ts +7 -3
- package/dist/provider/ViewsProvider.d.ts +1 -1
- package/dist/provider/ViewsProvider.js +5 -1
- package/dist/provider/components.d.ts +16 -8
- package/dist/provider/context.d.ts +3 -2
- package/dist/provider/menu-groups.d.ts +8 -0
- package/dist/provider/menu-groups.js +38 -0
- package/dist/provider/ports.d.ts +22 -0
- package/dist/provider/ports.js +1 -0
- package/dist/react.d.ts +1 -1
- package/docs/contract.md +128 -56
- package/docs/getting-started.md +250 -0
- package/docs/guides/atoms.md +245 -0
- package/docs/guides/cells.md +302 -0
- package/docs/guides/columns.md +412 -0
- package/docs/guides/display.md +203 -0
- package/docs/guides/editors.md +404 -0
- package/docs/guides/ports.md +246 -0
- package/docs/guides/selection.md +270 -0
- package/docs/guides/the-grid.md +677 -0
- package/docs/guides/the-provider.md +446 -0
- package/docs/index.md +50 -0
- package/docs/install.md +9 -47
- package/docs/reference/cells.md +28 -0
- package/docs/reference/display.md +42 -0
- package/docs/reference/editors-chips.md +6 -0
- package/docs/reference/editors-date.md +6 -0
- package/docs/reference/editors-location.md +10 -0
- package/docs/reference/editors-name.md +6 -0
- package/docs/reference/editors-number.md +11 -0
- package/docs/reference/editors-open-values.md +9 -0
- package/docs/reference/editors-range.md +6 -0
- package/docs/reference/editors-relation.md +9 -0
- package/docs/reference/editors-select.md +8 -0
- package/docs/reference/editors-session.md +9 -0
- package/docs/reference/editors-value-list.md +6 -0
- package/docs/reference/editors.md +5 -0
- package/docs/reference/grid.md +39 -0
- package/docs/reference/react.md +86 -0
- package/docs/reference/selection.md +33 -0
- package/docs/reference/views.md +601 -0
- package/package.json +7 -3
- package/skills/views/SKILL.md +20 -5
- package/dist/filters/types.d.ts +0 -27
- package/dist/filters/types.js +0 -1
- package/dist/model/filter-pushdown.d.ts +0 -106
- package/dist/model/filter-pushdown.js +0 -147
package/docs/contract.md
CHANGED
|
@@ -31,8 +31,8 @@ use; the prefix keeps that selector from reaching an element of the app's own.
|
|
|
31
31
|
| `data-slot="vk-grid-group-header"` | a group's name and figures |
|
|
32
32
|
| `data-slot="vk-grid-footer"` | the footer row |
|
|
33
33
|
| `data-slot="vk-grid-footer-cell"` | one column's figure |
|
|
34
|
-
| `data-slot="vk-grid-rail"` | the left rail: the checkbox
|
|
35
|
-
| `data-slot="vk-grid-tail"` | the right tail:
|
|
34
|
+
| `data-slot="vk-grid-rail"` | the left rail: the checkbox lane |
|
|
35
|
+
| `data-slot="vk-grid-tail"` | the right tail: a row's ⋯, the header's + Add column |
|
|
36
36
|
| `data-slot="vk-grid-row-more"` | the row's ⋯ itself: it opens the row's menu |
|
|
37
37
|
| `data-slot="vk-grid-editor"` | the open editor over a cell |
|
|
38
38
|
| `data-slot="vk-grid-outline"` | the outline around the focused cell or the selected range |
|
|
@@ -88,36 +88,40 @@ changes and at no other time.
|
|
|
88
88
|
**The package owns geometry and density.** Each is a CSS variable the grid sets on its
|
|
89
89
|
frame from its scale and its state; a skin reads them and an app overrides them on the frame.
|
|
90
90
|
|
|
91
|
-
| token |
|
|
92
|
-
| ----------------- |
|
|
93
|
-
| `--vk-scale` |
|
|
94
|
-
| `--vk-row-h` |
|
|
95
|
-
| `--vk-head-h` |
|
|
96
|
-
| `--vk-footer-h` |
|
|
97
|
-
| `--vk-label-h` |
|
|
98
|
-
| `--vk-line-h` |
|
|
99
|
-
| `--vk-chrome-h` |
|
|
100
|
-
| `--vk-px` |
|
|
101
|
-
| `--vk-cell-py` |
|
|
102
|
-
| `--vk-tail-py` |
|
|
103
|
-
| `--vk-
|
|
104
|
-
| `--vk-rail-
|
|
105
|
-
| `--vk-
|
|
106
|
-
| `--vk-
|
|
107
|
-
| `--vk-
|
|
108
|
-
| `--vk-
|
|
109
|
-
| `--vk-
|
|
110
|
-
| `--vk-
|
|
111
|
-
| `--vk-
|
|
112
|
-
| `--vk-text
|
|
113
|
-
| `--vk-text-
|
|
114
|
-
| `--vk-
|
|
115
|
-
| `--vk-
|
|
116
|
-
| `--vk-
|
|
117
|
-
| `--vk-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
91
|
+
| token | what it is |
|
|
92
|
+
| ----------------- | ----------------------------------------- |
|
|
93
|
+
| `--vk-scale` | the density multiplier |
|
|
94
|
+
| `--vk-row-h` | row height |
|
|
95
|
+
| `--vk-head-h` | header height |
|
|
96
|
+
| `--vk-footer-h` | footer height |
|
|
97
|
+
| `--vk-label-h` | group band height |
|
|
98
|
+
| `--vk-line-h` | a cell's line height |
|
|
99
|
+
| `--vk-chrome-h` | the chrome above the first row |
|
|
100
|
+
| `--vk-px` | horizontal cell padding |
|
|
101
|
+
| `--vk-cell-py` | vertical cell padding |
|
|
102
|
+
| `--vk-tail-py` | the tail button's vertical padding |
|
|
103
|
+
| `--vk-tail-pl` | the tail button's left padding |
|
|
104
|
+
| `--vk-rail-w` | the left rail's width |
|
|
105
|
+
| `--vk-rail-gap` | the gap between rail and first cell |
|
|
106
|
+
| `--vk-tail-w` | the right tail's width |
|
|
107
|
+
| `--vk-indent` | the group indent |
|
|
108
|
+
| `--vk-frozen-w` | the frozen band's width |
|
|
109
|
+
| `--vk-scroll-mt` | scroll-margin-top for a focused row |
|
|
110
|
+
| `--vk-glyph` | glyph size in cells |
|
|
111
|
+
| `--vk-head-glyph` | glyph size in the header |
|
|
112
|
+
| `--vk-text` | cell text size |
|
|
113
|
+
| `--vk-text-xs` | small text size |
|
|
114
|
+
| `--vk-text-10` | the smallest text size |
|
|
115
|
+
| `--vk-head-text` | header text size |
|
|
116
|
+
| `--vk-scrolled` | 0 or 1: content scrolled under the header |
|
|
117
|
+
| `--vk-parked` | 0 or 1: identity columns parked |
|
|
118
|
+
| `--vk-frozen-on` | 0 or 1: the frozen band is on |
|
|
119
|
+
| `--vk-row-py` | a rows view's vertical row padding |
|
|
120
|
+
| `--vk-head-mb` | the space under a rows view's header |
|
|
121
|
+
| `--vk-row-gap` | the gap inside a rows view's row |
|
|
122
|
+
|
|
123
|
+
`densityStyle(density)` writes the last three on the root of a rows view an app draws itself; its
|
|
124
|
+
rows read them.
|
|
121
125
|
|
|
122
126
|
**Colour is the app's, by the package's names.** The rendering paints every colour through a CSS
|
|
123
127
|
variable the app declares, spelled in a class as `text-(color:--vk-fg)` and in a value as
|
|
@@ -157,7 +161,15 @@ corners come from the app's Tailwind radius scale.
|
|
|
157
161
|
**The page gutter is the app's, if it has one.** `--vk-gutter` is the side padding a page gives its
|
|
158
162
|
content: the grid's rows run edge to edge and line their content up with it. An app that pads its
|
|
159
163
|
pages declares it once, onto its own padding; undeclared, the grid reads `0px` and sits flush with its
|
|
160
|
-
container.
|
|
164
|
+
container. `--vk-pinned-top` is how far down the surface's own pinned chrome reaches: the grid's
|
|
165
|
+
sticky header row and each group's header stop under it, not behind it. An app that pins something
|
|
166
|
+
over a grid (a tab strip, a toolbar) declares it on the element that scrolls the grid, onto the
|
|
167
|
+
height of what it pins there; undeclared, the grid reads `0px` and its header sticks at the top.
|
|
168
|
+
|
|
169
|
+
**The grid's own variables are not public.** The grid sets `--vk-drag-shift` (a header cell's
|
|
170
|
+
offset while its column is dragged to a new place) and `--vk-col-w-<id>` (one column's resolved
|
|
171
|
+
width, one per column) for itself. They carry the prefix because they share the global namespace;
|
|
172
|
+
an app neither sets nor reads them, and they may change in any release.
|
|
161
173
|
|
|
162
174
|
## The components map
|
|
163
175
|
|
|
@@ -172,14 +184,15 @@ both fill every one.
|
|
|
172
184
|
`Button` · `Popover` · `Tooltip` · `Checkbox` · `Menu` · `Command` · `Calendar` · `Collapse` · `Sheet` · `AppIcon` · `Markdown`
|
|
173
185
|
|
|
174
186
|
The popover takes `alignOffset`, `initialFocus` (false keeps focus where it was when the popup
|
|
175
|
-
opens
|
|
176
|
-
|
|
187
|
+
opens; the editor that then takes focus does so with `preventScroll`, so an adapter places its popup
|
|
188
|
+
however it likes, with no `fixed` positioning to hide a jump), and two vetoes, `onOutsidePress`
|
|
189
|
+
and `onEscape`, each returning `false` to keep it open. `onOutsidePress` is handed the pointer press, its `target` where the press landed, also when the
|
|
177
190
|
focus that press moves is what would close the popup: a vetoed press holds against its focus too,
|
|
178
191
|
and focus leaving by keyboard (a Tab out) closes without asking. Its
|
|
179
192
|
`chrome` is `panel` (the app's card popover) or `menu` (the app's menu panel, for a list); a panel
|
|
180
193
|
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
|
|
182
|
-
|
|
194
|
+
list's root takes `shouldFilter`, `filter` and `loop` (the arrows wrap); an item takes `chosen`: the app colours the item as
|
|
195
|
+
its chosen row, and the package's row inside draws the check, so the item draws no tick of its own; its input takes a `ref` (the place editor focuses its search through it), `onKeyDown`, and `chrome`
|
|
183
196
|
`search` or `bare` (the input without the search row); its empty state and groups take a class. The
|
|
184
197
|
calendar takes a controlled `month` (`YYYY-MM`) with `onMonthChange`, a `dropdown` caption, and the
|
|
185
198
|
`startMonth` and `endMonth` its pickers offer, and `locale`, the conventions' locale, in which it
|
|
@@ -189,8 +202,8 @@ ticked partly (some, not all), `indeterminate`, a press on which hands `true` wh
|
|
|
189
202
|
one tooltip provider above the views, and a tooltip never mounts its own. A menu item may carry a
|
|
190
203
|
`shortcut` hint and an `href`; a `checked` row is checkable and closes the menu like any row; an
|
|
191
204
|
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
|
|
205
|
+
the group's own `onSelect`, `href` and `checked` are ignored, and a group marked `disabled` disables every row under it, at every depth: the provider hands your `Menu` those rows already `disabled`, so you draw each row by its own flag. `AppIcon` is the app's own icon component by the app's own names, for
|
|
206
|
+
the glyphs a host declares (a row's icon, a binding's icon, an option's icon), drawn on the first paint (rows are measured as they mount); the semantic glyphs the rendering itself
|
|
194
207
|
needs are a port, by meaning (below). `Markdown` is the app's markdown renderer, handed the stored text whole; the
|
|
195
208
|
package draws rich text through it and parses none.
|
|
196
209
|
|
|
@@ -210,11 +223,14 @@ What a Base UI adapter over shadcn copies does where its copies stop short of a
|
|
|
210
223
|
library's root, positioner and popup, handing the anchor to the positioner, where your copy's content
|
|
211
224
|
doesn't forward one; with no flyouts, a root needs no trigger of its own.
|
|
212
225
|
|
|
226
|
+
**A disabled group.** Nothing to do: its rows reach you already `disabled`.
|
|
227
|
+
|
|
213
228
|
**`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
|
|
229
|
+
own, and no card width: it is as wide as its list. Where your copy has only the card popover, lay your
|
|
230
|
+
menu classes over it.
|
|
215
231
|
|
|
216
|
-
**The command item's chosen mark.**
|
|
217
|
-
draws a tick of its own, hide it
|
|
232
|
+
**The command item's chosen mark.** Colour the item as your chosen row; the row inside draws the
|
|
233
|
+
check. Where your copy's item draws a tick of its own, hide it.
|
|
218
234
|
|
|
219
235
|
**`chrome: "bare"`.** The input alone, without the search row's glyph and divider. Where your copy
|
|
220
236
|
has only the search row, reach the command library's own input.
|
|
@@ -242,7 +258,7 @@ container: the inset a run of rows sits in, inside a panel or a command list's g
|
|
|
242
258
|
a button or, with `interactive={false}`, a static line), `RowContent` (a row's inside, for inside a
|
|
243
259
|
command list's item, which owns the element and the highlight), `TickBox` (a paint-only tick box),
|
|
244
260
|
`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-
|
|
261
|
+
`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 `confirm` port with `views.menus.row-delete-confirm` (the browser's own confirm when you hand none), and a delete that rejects says so through the toast port's `error` with `views.menus.row-delete-failed`; 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
262
|
from the app's colours; an app swaps any of them through the provider's `atoms`, and the rest
|
|
247
263
|
stay the defaults.
|
|
248
264
|
|
|
@@ -253,16 +269,17 @@ A row in the default tone takes its colour from what it sits in, so a command it
|
|
|
253
269
|
highlight read through it; a `muted` row brightens on hover when it is itself the button.
|
|
254
270
|
A row's `detail` is what it says at its right edge, in the subtle colour: a setting's current choice,
|
|
255
271
|
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="
|
|
257
|
-
|
|
272
|
+
samples stays in line. A row that opens a flyout beside its menu takes `opens` (`aria-haspopup="dialog"`,
|
|
273
|
+
since the flyout is the components map's `Popover`, a dialog of plain rows; and `aria-expanded` from `open`),
|
|
274
|
+
and `open` while that flyout is up (`data-open`, the pressed ground).
|
|
258
275
|
|
|
259
276
|
The defaults mark themselves with `data-slot="vk-list"`, `data-slot="vk-row"`, `data-slot="vk-row-content"`,
|
|
260
277
|
`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
278
|
with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked`, `data-open` (flags),
|
|
262
279
|
`data-status` (the slot's name) and `data-platform` (a link's platform key). A swapped atom marks itself as its app does.
|
|
263
280
|
|
|
264
|
-
Lists that scroll wear the class `scrollbar-overlay`, which an app may define (the
|
|
265
|
-
|
|
281
|
+
Lists that scroll wear the class `scrollbar-overlay`, which an app may define (to show the OS
|
|
282
|
+
overlay scrollbar, say); without it the class does nothing.
|
|
266
283
|
|
|
267
284
|
## Ports
|
|
268
285
|
|
|
@@ -271,7 +288,8 @@ Runtime services the app hands in through the provider, typed in `src/provider/p
|
|
|
271
288
|
- `toast` — `success(message)`, `error(message)`, `info(message)`, `warning(message, { description })` (a change the person did not make).
|
|
272
289
|
- `haptics` — `selection()`, `impact(style)`, `notification(type)`; an app without a device hands in no-ops.
|
|
273
290
|
- `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
|
|
291
|
+
- `viewPrefs` — `get(key)`, `set(key, value)`, `subscribe(key, listener)`: a per-device store for state a view keeps between visits. No view in this release reads it; the grid's preferences come in through `useGridTablePrefs`, from wherever the host keeps them.
|
|
292
|
+
- `confirm` — `confirm({ message, confirmLabel, subject, destructive })` resolving to whether the person said yes; asked before a row's Delete, `subject` being the host's `deleteLabel`. Optional: an app that hands none gets the browser's own confirm with `message`, and a rejection or a throw counts as no. `useViews().ports.confirm` is always a function.
|
|
275
293
|
|
|
276
294
|
## Icons
|
|
277
295
|
|
|
@@ -313,8 +331,9 @@ row), `views.menus.date-style` (`{ style }`: `"short"`, `"long"`, `"numeric"` or
|
|
|
313
331
|
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
332
|
`views.menus.copy`, `views.menus.cut`, `views.menus.paste`, `views.menus.clear` and `views.menus.edit` (a cell's lane),
|
|
315
333
|
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
|
|
317
|
-
browser's confirm before a delete: "Delete this row?")
|
|
334
|
+
"Deselect", as text for a catalog's `select`), `views.menus.row-delete`, `views.menus.row-delete-confirm` (the
|
|
335
|
+
browser's confirm before a delete: "Delete this row?") and `views.menus.row-delete-failed` (the error toast when the
|
|
336
|
+
delete the host ran rejects: "Failed to delete the row");
|
|
318
337
|
the grid's own: `views.grid.figure` (`{ kind }`, a footer figure's name, `"none"` included: "None", "Sum", "Avg", "Min",
|
|
319
338
|
"Max", "Count", "Filled", "Unique", "Ratio"), `views.grid.figure-pick` ("Calculate", an empty footer cell),
|
|
320
339
|
`views.grid.loading` ("Loading rows"), the labels `views.grid.select-row`, `views.grid.select-group`,
|
|
@@ -326,8 +345,11 @@ the grid's own: `views.grid.figure` (`{ kind }`, a footer figure's name, `"none"
|
|
|
326
345
|
`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
346
|
`views.grid.write-not-linkable`; a paste's `views.grid.paste-refused`, `views.grid.paste-empty`,
|
|
328
347
|
`views.grid.paste-not-number`, `views.grid.paste-not-duration`, `views.grid.paste-not-date`,
|
|
329
|
-
`views.grid.paste-not-option`, `views.grid.paste-
|
|
330
|
-
|
|
348
|
+
`views.grid.paste-not-option`, `views.grid.paste-ambiguous-option` (a label two options share),
|
|
349
|
+
`views.grid.paste-pick` and `views.grid.paste-not-linkable` (each `{ value }`, the pasted text), `views.grid.paste-other-currency` (`{ currency }`, the record's own: an amount pasted or filled into a
|
|
350
|
+
record in another currency) and `views.grid.paste-not-range`; a paste or a fill that refused cells,
|
|
351
|
+
`views.grid.paste-skipped` and `views.grid.fill-skipped` (each `{ count, reason }`: one toast per reason, its
|
|
352
|
+
`reason` one of the refusals above in the app's words; an operation of one cell says the reason alone); and the warnings
|
|
331
353
|
`views.grid.changed-elsewhere` (`{ field }`), `views.grid.changed-elsewhere-cells` (`{ count }`),
|
|
332
354
|
`views.grid.saved-value`, `views.grid.saved-values` and `views.grid.row-left`. The functions that word a refusal
|
|
333
355
|
(`gridClearRefusal`, `columnClearRefusal`, `columnEditRefusal`, `gridEditRefusal`) take the resolver last, and
|
|
@@ -346,9 +368,47 @@ package's English, `resolveViewsMessage`; an app's resolver that words only some
|
|
|
346
368
|
change to the list and a compile error in every exhaustive resolver (a `switch` with no default)
|
|
347
369
|
that has not worded it.
|
|
348
370
|
|
|
371
|
+
## Four shapes of a value
|
|
372
|
+
|
|
373
|
+
A value takes up to four shapes on its way through a view: **stored** (what the row holds), **draft** (what an editor holds while it is open), **commit** (what the editor hands its host when it closes) and **display** (what a surface draws). Stored and commit differ on purpose, and the binding's `write` is where a host maps one onto the other.
|
|
374
|
+
|
|
375
|
+
| type | stored | draft | commit | display |
|
|
376
|
+
| -------------------------------------------- | --------------------------------------------------------- | ---------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- |
|
|
377
|
+
| `text` | a string | the host's own input | a string | the text; a long text folds |
|
|
378
|
+
| `url`, `domain`, `email`, `phone` | a string (a phone `{ number, extension }`) | the host's own input | the typed text, which fields' `acceptFieldCommit` reads | a link (`tel:` for a phone) |
|
|
379
|
+
| the same, `multiple` | `{ value, label, main }[]`, the main one first | a row each | the whole list (`editors/value-list`) | the main value, and the rest on demand |
|
|
380
|
+
| `number`, `percent`, `currency` | a number (a currency's code fixed, or in a sibling field) | the typed text | `NumberCommit`: `{ value, unit? }` | the figure in the conventions' locale; a percent appended, never multiplied |
|
|
381
|
+
| `date` | `"2026-09-15"` | the picked day | `"2026-09-15"` | the day in the column's style |
|
|
382
|
+
| `datetime` | an ISO instant | the local day and time | `"2026-09-15T14:30"`, local: the host merges it onto the stored instant | the day and time |
|
|
383
|
+
| `boolean` | a boolean | none | a boolean, from the display control itself | a checkbox, an icon, a marker or text |
|
|
384
|
+
| `select`, `status` | the option's code | none: a pick commits | the option's code, or `""` for None on a field that may be emptied | a badge, a status by its semantic slot |
|
|
385
|
+
| `multiselect` | the codes | the chosen codes | the whole set | badges |
|
|
386
|
+
| `relation`, `user` | an id or null (ids for a many relation) | the picked id | an id, or `null` for unlinked | a chip `{ id, label, entity, avatarUrl }` the host resolves |
|
|
387
|
+
| `range` | `{ low, high }` | two boxes | `{ low, high }`, an empty box an open end | "11–50" with its unit and period |
|
|
388
|
+
| `name` | `{ full, given, family }` | three boxes | `{ full, given, family }`, or `null` | the full name, else the parts, else the host's fallback |
|
|
389
|
+
| `location` | the place's parts in its country's order | the country, then its parts | the place, or `null` (the grid has no editor for it) | the place written whole |
|
|
390
|
+
| `rich_text` | a markdown string | the host's own input; in the grid, the long-text panel | the markdown string | folded text |
|
|
391
|
+
| `actor`, `lookup`, `rollup`, `formula` | set by the system, or derived | none | none: no editor opens | a chip, the far field, the result |
|
|
392
|
+
|
|
393
|
+
A clear is the one exception to the commit column. Delete, Cut, the grid row menu's Clear and a clear over a range commit `""` for every type above but three, on a field that may be emptied: a relation (and a member) commits `null` and a multiselect `[]`, and a boolean commits `false`, whether or not it may be emptied. So a cleared number, date, name, range, select or text reaches the binding's `write` as `""`, and the `write` maps it to what the row stores for nothing.
|
|
394
|
+
|
|
395
|
+
A derived field (a lookup, a rollup, a formula) has no commit at all: no edit core, and fields' `zodFor` refuses it. `EDIT_CORES` (`@viewkitjs/views/editors`) answers which types open an edit core; `null` is the answer for a type with none, including the types edited in the host's own text box (`text`, `rich_text`, `url`, `domain`, `email`, `phone`) and `boolean`, which its display control flips.
|
|
396
|
+
|
|
397
|
+
## What an edit core never does
|
|
398
|
+
|
|
399
|
+
An editor owns its panel and what a close means. Everything else is its host's, so the same core runs in a grid cell, a drawer row, a card or a form. An edit core never:
|
|
400
|
+
|
|
401
|
+
- calls a mutation or fetches on its own (its host writes, and its host hands it candidates; the relation editor's remote search calls the host's own `search`);
|
|
402
|
+
- closes itself or owns the exit timer (the host's popover closes it, and the edit session holds the gap);
|
|
403
|
+
- reads a form library, the grid's focus or selection, or a host's list.
|
|
404
|
+
|
|
405
|
+
## A command field
|
|
406
|
+
|
|
407
|
+
A field whose changes are transitions with rules of their own (a lost deal needs a reason, a reassigned record moves what is filed against it) declares `edit.mutability: "command"` in `@viewkitjs/fields`. It is edited by verbs, never by an editor: its binding takes no `write` (`checkBinding` refuses one), `bindingWritable` answers false, and `columnFrom` marks the column `command` and never `editable`. The grid cell, the drawer row and the card each open the same menu, shaped by `FieldMenus` (field key → menu items), and the host supplies the verbs; what a verb writes goes through the host's own route for that transition. The cell opens the app's `CommandMenu` atom with the host's items, where an editable cell would open an editor, so the field does not read as frozen; handed no verbs, it is a read-only value.
|
|
408
|
+
|
|
349
409
|
## The doors
|
|
350
410
|
|
|
351
|
-
|
|
411
|
+
Eighteen doors, and nothing else is importable but `./package.json`. What each holds is summarised here; each door's reference page names every export, one line each, starting at [`reference/views.md`](reference/views.md).
|
|
352
412
|
|
|
353
413
|
`@viewkitjs/views`, no React at runtime, holds two things. The rendering contract, every name listed:
|
|
354
414
|
the constants `VK_PREFIX`, `GRID_SLOTS`, `GRID_STATES`, `VK_TOKENS`, `VK_COLOURS`,
|
|
@@ -376,7 +436,8 @@ public; nothing else at the root door is.
|
|
|
376
436
|
`ViewsMenuItem`, `ViewsCommandParts`, `ViewsCalendarProps`, `ViewsCollapseProps` and
|
|
377
437
|
`ViewsSheetProps`, with their shared shapes `ViewsAnchor`, `ViewsSide`, `ViewsAlign`,
|
|
378
438
|
`ViewsCloseReason` and `ViewsOpenChange`; the ports' types `ViewsToastPort`, `ViewsHapticsPort`,
|
|
379
|
-
`ViewsClipboardPort
|
|
439
|
+
`ViewsClipboardPort`, `ViewsPrefsPort`, `ViewsConfirmPort`, `ViewsConfirmRequest` and `ViewsResolvedPorts` (the
|
|
440
|
+
ports `useViews()` hands on, `confirm` always there); the atoms' `DEFAULT_VIEWS_ATOMS` and types `ViewsAtoms`,
|
|
380
441
|
`ViewsListProps`, `ViewsRowProps`, `ViewsRowContentProps`, `ViewsTickBoxProps`, `ViewsStatusBadgeProps`,
|
|
381
442
|
`ViewsStatusMarkerProps`, `ViewsTagProps`, `ViewsCommandMenuProps`, `ViewsRowMenuProps`, `ViewsRowMenuItem`, `ViewsRelationLinkProps`, `ViewsLoadingProps`, `ViewsLoadMoreProps` and `ViewsPlatformMarkProps`; and, re-exported from the root door, `ComponentName`,
|
|
382
443
|
`PortName`, `ViewsIconName`, `ViewsMessage` and `ViewsMessageResolver`. The provider takes an
|
|
@@ -387,7 +448,7 @@ app's. It is called where a value is drawn, so the app's provider imports none o
|
|
|
387
448
|
`@viewkitjs/views/display`, no client directive on the door (a server module may reach its string
|
|
388
449
|
formatters), every rendering file behind it carrying its own: `renderFieldValue` and `DISPLAY_CORES`
|
|
389
450
|
(one renderer per storage type, a plain function that answers `null` for an empty value), the string
|
|
390
|
-
formatters `formatDateValue` and `
|
|
451
|
+
formatters `formatDateValue`, `formatNumberValue` and `formatMoney`, `DEFAULT_FIELD_PRESENTATION`, `viewerFrom`,
|
|
391
452
|
`CellSuffix`, `cellTextClass`, `MultiValueCell`, `CHIP_BASE`, `CHIP_INTERACTIVE`, and the types
|
|
392
453
|
`DisplayCore`, `DisplayOptions`, `FieldPresentation`, `FieldViewerContext`, `NumberLikeFormat` and
|
|
393
454
|
`RelationWrap`. A rendered value reads the provider's conventions, wording and presentation; a string
|
|
@@ -420,7 +481,7 @@ hold, which the app's list answers) reach every editor of it: the app provides t
|
|
|
420
481
|
a host reads them, asking once for a field's values when its editor mounts. A closed field, or no
|
|
421
482
|
provider, reads none and asks nothing. `offeredValues` is what a host offers: the declared options, then
|
|
422
483
|
the known values, then those seen, each once. `useOpenValuesContext()` reads the nearest provider whole: what a host
|
|
423
|
-
hands `buildRelationFilters` as `farValues
|
|
484
|
+
hands `buildRelationFilters` as `farValues`.
|
|
424
485
|
|
|
425
486
|
A relation's Related records row (`buildRelationFilters`) offers a far relation, user or actor by name
|
|
426
487
|
only when its target names it (`RelationFilterTarget.named`, from the host's builder) and the host hands
|
|
@@ -446,6 +507,17 @@ rules `selectFromClick`, `preventShiftTextSelect`, `ROW_INTERACTIVE_SELECTOR`, `
|
|
|
446
507
|
and `ROW_NO_TEXT_SELECT`, and the types `ListSelectionConfig`, `ListBatchApi`, `SelectionRetention` and
|
|
447
508
|
`UseListSelectionResult`. The bar the selection opens is the app's.
|
|
448
509
|
|
|
510
|
+
`@viewkitjs/views/grid`, no client directive on the door, every rendering file behind it carrying its
|
|
511
|
+
own: `GridTable` and its props `GridTableProps` (flat, as a host's binding hands them),
|
|
512
|
+
`useGridTablePrefs` (a grid's personal preferences: the host's prefs and their setter in, the props to spread onto `GridTable` out), the types
|
|
513
|
+
an app writes its props against, `GridSortState`, `GridGroupSortOption`, `GridCellCommitFn` and
|
|
514
|
+
`GridCellsCommitFn`, and `GridGroupByState`, `GridGroupFigure` and `GroupCountNoun`; and the helpers a
|
|
515
|
+
host's binding shares with the grid: `GridCommitContext` and `GridCommitOutcome` (what a commit was and how it ended),
|
|
516
|
+
`deriveGridSelectValues` and `deriveGridRelationValues` (the values a column's filter offers),
|
|
517
|
+
`cellCopyText` and `cellEditBaseline` (a cell's copy text and the value an edit starts from, which a
|
|
518
|
+
CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The selection bar, the house menu rows, the group
|
|
519
|
+
collapse and the type icons are the app's.
|
|
520
|
+
|
|
449
521
|
## Registry items
|
|
450
522
|
|
|
451
523
|
When the copy mode ships, each view's default rendering is one registry item, tagged by the package
|
|
@@ -0,0 +1,250 @@
|
|
|
1
|
+
# Getting started
|
|
2
|
+
|
|
3
|
+
This page takes you from install to a grid of records drawn with your own primitives. Every block on it continues the one before, and the whole page runs as written.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```sh
|
|
8
|
+
pnpm add @viewkitjs/views @viewkitjs/fields zod
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
`react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The package is ESM only and runs on Node 20 or later.
|
|
12
|
+
|
|
13
|
+
The rendering carries Tailwind classes drawn from your tokens and paints through its own colour names. Two lines of setup make it look like your app: one `@source` line, so Tailwind sees the package, and one block mapping the `--vk-*` colours onto your theme. [Install](install.md) has both.
|
|
14
|
+
|
|
15
|
+
The blocks below check their own results with `node:assert`. To run this page as a script, save the blocks in order as one `.tsx` file in an ES module project and run it with `tsx` (`pnpm add -D tsx @types/node`); in your app the asserts are only there to show you what each call returns.
|
|
16
|
+
|
|
17
|
+
## Define the fields
|
|
18
|
+
|
|
19
|
+
The grid draws fields, and `@viewkitjs/fields` says what each one is. A registry is one entity's fields; fields' own getting started, at `node_modules/@viewkitjs/fields/docs/getting-started.md`, covers it in full.
|
|
20
|
+
|
|
21
|
+
```tsx
|
|
22
|
+
import assert from "node:assert/strict";
|
|
23
|
+
import { defineConventions, defineFields } from "@viewkitjs/fields";
|
|
24
|
+
|
|
25
|
+
export const DEAL_FIELDS = defineFields({
|
|
26
|
+
entity: "deal",
|
|
27
|
+
identity: "title",
|
|
28
|
+
fields: {
|
|
29
|
+
title: { type: "text", label: "Title", required: true },
|
|
30
|
+
value: { type: "currency", label: "Value", code: { fixed: "EUR" } },
|
|
31
|
+
stage: {
|
|
32
|
+
type: "status",
|
|
33
|
+
label: "Stage",
|
|
34
|
+
options: [
|
|
35
|
+
{ value: "new", label: "New", slot: "pending" },
|
|
36
|
+
{ value: "won", label: "Won", slot: "success" },
|
|
37
|
+
],
|
|
38
|
+
},
|
|
39
|
+
},
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
## Bind them to your rows
|
|
46
|
+
|
|
47
|
+
A binding says how one field reads and writes on your row: `read` gives the value a surface draws, and `write`, when the field may be edited, maps what an editor commits onto the body of your own request. A field with no `write` is read-only on every surface.
|
|
48
|
+
|
|
49
|
+
An emptied value commits `""`: a text box emptied, and, on a field that may be emptied, Delete, Cut and Clear. A `write` either maps it (to `null` for a field that stores one) or refuses it with `{ skip: true, reason }`, as `title` does here, since a deal needs one. `stage` can't be emptied, so its `write` only ever receives an option's code.
|
|
50
|
+
|
|
51
|
+
```tsx
|
|
52
|
+
import { bindFields, columnFrom } from "@viewkitjs/views";
|
|
53
|
+
|
|
54
|
+
type Deal = { id: string; title: string; value: number; stage: string };
|
|
55
|
+
|
|
56
|
+
const DEAL_BINDINGS = bindFields<Deal, typeof DEAL_FIELDS>(DEAL_FIELDS, {
|
|
57
|
+
title: {
|
|
58
|
+
read: (deal) => deal.title,
|
|
59
|
+
write: (_deal, commit) =>
|
|
60
|
+
commit === "" ? { skip: true, reason: "A deal needs a title." } : { body: { title: commit } },
|
|
61
|
+
},
|
|
62
|
+
value: { read: (deal) => deal.value },
|
|
63
|
+
stage: { read: (deal) => deal.stage, write: (_deal, commit) => ({ body: { stage: commit } }) },
|
|
64
|
+
});
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
`bindFields` checks every binding when the module loads: a `write` on a field that can't be changed, or a writable money field whose currency comes from the row with no `unit`, throws `FieldBindingError` at startup. The [columns guide](guides/columns.md) has the rest.
|
|
68
|
+
|
|
69
|
+
## Make the columns
|
|
70
|
+
|
|
71
|
+
A column is what the grid draws: a binding plus what only the grid knows, such as its `id` and its starting width in pixels. `columnFrom` derives the column's type, options, format and whether it can be edited from the field and the binding.
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
const columns = [
|
|
75
|
+
columnFrom(DEAL_BINDINGS.title, { id: "title", width: 240, editable: true }),
|
|
76
|
+
columnFrom(DEAL_BINDINGS.value, { id: "value", width: 120 }),
|
|
77
|
+
columnFrom(DEAL_BINDINGS.stage, { id: "stage", width: 140, editable: true }),
|
|
78
|
+
];
|
|
79
|
+
|
|
80
|
+
assert.equal(columns[0].type, "title"); // the registry's identity field is the row's title
|
|
81
|
+
assert.equal(columns[1].align, "right"); // a figure is read down its decimal point
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
## Hand in your primitives
|
|
85
|
+
|
|
86
|
+
The package draws nothing with a UI library of its own. You hand it yours through a components map: the button, the popover, the menu, the command list, the calendar and the rest, each in the shape the contract names. Here they are plain elements, so this page runs anywhere; in your app each one wraps your own copy (a shadcn popover, a Base UI menu). The [provider guide](guides/the-provider.md) shows an adapter over Radix and over Base UI.
|
|
87
|
+
|
|
88
|
+
```tsx
|
|
89
|
+
import { ICON_NAMES } from "@viewkitjs/views";
|
|
90
|
+
import type { ViewsComponents, ViewsIcons } from "@viewkitjs/views/react";
|
|
91
|
+
|
|
92
|
+
const components: ViewsComponents = {
|
|
93
|
+
Button: ({ children, onClick, disabled, type = "button", className, title }) => (
|
|
94
|
+
<button type={type} onClick={onClick} disabled={disabled} className={className} title={title}>
|
|
95
|
+
{children}
|
|
96
|
+
</button>
|
|
97
|
+
),
|
|
98
|
+
Popover: ({ open, children, className }) => (open ? <div className={className}>{children}</div> : null),
|
|
99
|
+
Tooltip: ({ children }) => children,
|
|
100
|
+
Checkbox: ({ checked, onCheckedChange, disabled }) => (
|
|
101
|
+
<input
|
|
102
|
+
type="checkbox"
|
|
103
|
+
checked={checked}
|
|
104
|
+
disabled={disabled}
|
|
105
|
+
onChange={(event) => onCheckedChange(event.target.checked, { event: event.nativeEvent })}
|
|
106
|
+
/>
|
|
107
|
+
),
|
|
108
|
+
Menu: ({ open, items }) =>
|
|
109
|
+
open ? (
|
|
110
|
+
<div role="menu">
|
|
111
|
+
{items.map((item) => (
|
|
112
|
+
<button key={item.key} type="button" role="menuitem" onClick={item.onSelect}>
|
|
113
|
+
{item.label}
|
|
114
|
+
</button>
|
|
115
|
+
))}
|
|
116
|
+
</div>
|
|
117
|
+
) : null,
|
|
118
|
+
Command: {
|
|
119
|
+
Root: ({ children, className }) => <div className={className}>{children}</div>,
|
|
120
|
+
Input: ({ value, onValueChange, placeholder, ref, onKeyDown }) => (
|
|
121
|
+
<input
|
|
122
|
+
ref={ref}
|
|
123
|
+
value={value}
|
|
124
|
+
placeholder={placeholder}
|
|
125
|
+
onChange={(event) => onValueChange(event.target.value)}
|
|
126
|
+
onKeyDown={onKeyDown}
|
|
127
|
+
/>
|
|
128
|
+
),
|
|
129
|
+
List: ({ children }) => <div role="listbox">{children}</div>,
|
|
130
|
+
Empty: ({ children }) => <div>{children}</div>,
|
|
131
|
+
Group: ({ children }) => <div>{children}</div>,
|
|
132
|
+
Item: ({ value, onSelect, chosen, children }) => (
|
|
133
|
+
<div role="option" aria-selected={chosen === true} onClick={() => onSelect(value)}>
|
|
134
|
+
{children}
|
|
135
|
+
</div>
|
|
136
|
+
),
|
|
137
|
+
},
|
|
138
|
+
Calendar: ({ value, onChange }) => (
|
|
139
|
+
<input type="date" value={value ?? ""} onChange={(event) => onChange(event.target.value)} />
|
|
140
|
+
),
|
|
141
|
+
Collapse: ({ open, children }) => (open ? <>{children}</> : null),
|
|
142
|
+
Sheet: ({ open, children }) => (open ? <div role="dialog">{children}</div> : null),
|
|
143
|
+
AppIcon: ({ name, className }) => <i data-icon={name} className={className} />,
|
|
144
|
+
Markdown: ({ source, className }) => <div className={className}>{source}</div>,
|
|
145
|
+
};
|
|
146
|
+
|
|
147
|
+
// The glyphs the rendering asks for, by meaning: map each to your icon library's component.
|
|
148
|
+
const icons = Object.fromEntries(
|
|
149
|
+
ICON_NAMES.map((name) => [name, ({ className }: { className?: string }) => <i data-icon={name} className={className} />])
|
|
150
|
+
) as ViewsIcons;
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
## Mount the provider
|
|
154
|
+
|
|
155
|
+
`ViewsProvider` sits once above every view. Besides your primitives and icons it takes four ports (your toast, haptics, clipboard and a per-device store; [the ports guide](guides/ports.md)) and the same conventions you hand `@viewkitjs/fields`. `NOOP_PORTS` answers each with nothing, which is enough to start.
|
|
156
|
+
|
|
157
|
+
```tsx
|
|
158
|
+
import type { ReactNode } from "react";
|
|
159
|
+
import { NOOP_PORTS, ViewsProvider } from "@viewkitjs/views/react";
|
|
160
|
+
|
|
161
|
+
export function AppViews({ children }: { children: ReactNode }) {
|
|
162
|
+
return (
|
|
163
|
+
<ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions}>
|
|
164
|
+
{children}
|
|
165
|
+
</ViewsProvider>
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
## Draw the grid
|
|
171
|
+
|
|
172
|
+
`GridTable` takes five things: your rows in groups (one group when the list isn't grouped), whether they are grouped, each row's id, the columns, and what opening a row does. `onCellCommit` is where an edit lands: look up the column's binding, let its `write` map the value onto a body, and send it to your API. A rejected promise rolls the cell back, so a `write` that refuses becomes a thrown error. The grid says nothing about a rejection itself: your app shows the reason, through its own toast.
|
|
173
|
+
|
|
174
|
+
```tsx
|
|
175
|
+
import { renderToStaticMarkup } from "react-dom/server";
|
|
176
|
+
import { GridTable, type GridCellCommitFn } from "@viewkitjs/views/grid";
|
|
177
|
+
|
|
178
|
+
const deals: Deal[] = [
|
|
179
|
+
{ id: "d1", title: "Acme renewal", value: 1200, stage: "won" },
|
|
180
|
+
{ id: "d2", title: "Globex pilot", value: 5400, stage: "new" },
|
|
181
|
+
];
|
|
182
|
+
|
|
183
|
+
const sent: Record<string, unknown>[] = [];
|
|
184
|
+
async function saveDeal(id: string, body: Record<string, unknown>) {
|
|
185
|
+
sent.push({ id, ...body }); // your PATCH request
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
const refusals: string[] = [];
|
|
189
|
+
function showRefusal(reason: string) {
|
|
190
|
+
refusals.push(reason); // your toast
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
const onCellCommit: GridCellCommitFn<Deal> = async (deal, columnId, value) => {
|
|
194
|
+
const binding = columns.find((column) => column.id === columnId)?.binding;
|
|
195
|
+
const patch = binding?.write?.(deal, value);
|
|
196
|
+
if (!patch) throw new Error(`${columnId} can't be edited`);
|
|
197
|
+
if ("skip" in patch) {
|
|
198
|
+
const reason = patch.reason ?? "This change can't be saved.";
|
|
199
|
+
showRefusal(reason);
|
|
200
|
+
throw new Error(reason); // the cell rolls back
|
|
201
|
+
}
|
|
202
|
+
await saveDeal(deal.id, patch.body);
|
|
203
|
+
};
|
|
204
|
+
|
|
205
|
+
function DealsGrid() {
|
|
206
|
+
return (
|
|
207
|
+
<GridTable
|
|
208
|
+
groups={[{ key: "all", label: null, items: deals }]}
|
|
209
|
+
grouped={false}
|
|
210
|
+
getRowId={(deal) => deal.id}
|
|
211
|
+
columns={columns}
|
|
212
|
+
onOpenRow={(deal) => console.log("open", deal.id)}
|
|
213
|
+
onCellCommit={onCellCommit}
|
|
214
|
+
/>
|
|
215
|
+
);
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
const html = renderToStaticMarkup(
|
|
219
|
+
<AppViews>
|
|
220
|
+
<DealsGrid />
|
|
221
|
+
</AppViews>
|
|
222
|
+
);
|
|
223
|
+
|
|
224
|
+
assert.ok(html.includes('data-slot="vk-grid"')); // the grid's frame
|
|
225
|
+
assert.ok(html.includes("Acme renewal") && html.includes("Globex pilot")); // each row's title
|
|
226
|
+
assert.ok(html.includes("€1,200")); // a currency, in the conventions' locale
|
|
227
|
+
assert.ok(html.includes('data-status="success"')); // a status wears its semantic slot
|
|
228
|
+
|
|
229
|
+
// What an edit sends: the binding's write, handed what the editor committed.
|
|
230
|
+
await onCellCommit(deals[1], "stage", "won");
|
|
231
|
+
assert.deepEqual(sent, [{ id: "d2", stage: "won" }]);
|
|
232
|
+
|
|
233
|
+
// An emptied title: refused, so the cell rolls back, your toast says why, and nothing is sent.
|
|
234
|
+
await assert.rejects(onCellCommit(deals[0], "title", ""));
|
|
235
|
+
assert.deepEqual(refusals, ["A deal needs a title."]);
|
|
236
|
+
assert.equal(sent.length, 1);
|
|
237
|
+
```
|
|
238
|
+
|
|
239
|
+
In your app `DealsGrid` renders inside `AppViews` like any client component; the server render here only proves what it draws.
|
|
240
|
+
|
|
241
|
+
## What your app does around the grid
|
|
242
|
+
|
|
243
|
+
The grid draws the rows it is given and reports what a person did. Filtering, sorting and grouping the rows, keeping each person's column widths and choices, and saving writes are yours, and the package hands you the pieces: `evaluateView` from `@viewkitjs/fields/query` runs a filter, sorts and a group over the rows you hold, `useGridTablePrefs` turns the preferences you keep for a person into the grid's props, and the sort, group and figure props tell you what a person chose. [The grid guide](guides/the-grid.md) walks through each.
|
|
244
|
+
|
|
245
|
+
## Next
|
|
246
|
+
|
|
247
|
+
- [The provider](guides/the-provider.md): your adapter, your icons, your words
|
|
248
|
+
- [Columns](guides/columns.md): bindings, columns and what may be done to them
|
|
249
|
+
- [The grid](guides/the-grid.md): grouping, sorting, preferences, figures and writes
|
|
250
|
+
- [Every guide and reference](index.md)
|