@viewkitjs/views 0.3.0 → 0.5.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 +641 -0
- package/README.md +3 -3
- package/dist/atoms/CommandMenu.d.ts +1 -1
- package/dist/atoms/CommandMenu.js +7 -3
- package/dist/atoms/DrillRows.d.ts +3 -0
- package/dist/atoms/DrillRows.js +25 -0
- package/dist/atoms/PanelRows.d.ts +5 -0
- package/dist/atoms/PanelRows.js +40 -0
- package/dist/atoms/PanelSearch.d.ts +2 -0
- package/dist/atoms/PanelSearch.js +21 -0
- package/dist/atoms/RelationRoles.d.ts +2 -0
- package/dist/atoms/RelationRoles.js +6 -0
- package/dist/atoms/Row.js +2 -1
- package/dist/atoms/RowMenu.js +2 -1
- package/dist/atoms/SelectionSheet.d.ts +3 -0
- package/dist/atoms/SelectionSheet.js +30 -0
- package/dist/atoms/StatusMarker.js +3 -1
- package/dist/atoms/Tag.js +2 -1
- package/dist/atoms/defaults.js +14 -0
- package/dist/atoms/types.d.ts +146 -8
- package/dist/cells/cell-values.js +4 -2
- package/dist/cells/relation-wrap.js +3 -1
- package/dist/contract.d.ts +212 -17
- package/dist/contract.js +208 -6
- package/dist/display/boolean.js +3 -1
- package/dist/display/date.d.ts +1 -1
- package/dist/display/date.js +4 -2
- package/dist/display/format.js +20 -4
- package/dist/display/link.js +4 -3
- package/dist/display/multi-value.js +2 -1
- package/dist/display/percent.js +2 -1
- package/dist/display/phone.js +2 -1
- package/dist/display/range.js +3 -13
- package/dist/display/relation.js +23 -8
- package/dist/display/rich-text.js +2 -1
- package/dist/editors/ChipsEditor.d.ts +5 -1
- package/dist/editors/ChipsEditor.js +15 -2
- package/dist/editors/DateEditor.d.ts +2 -0
- package/dist/editors/DateEditor.js +76 -10
- package/dist/editors/EditorPanel.d.ts +14 -4
- package/dist/editors/EditorPanel.js +21 -4
- package/dist/editors/LocationEditor.js +35 -3
- package/dist/editors/NumberEditor.js +3 -2
- package/dist/editors/RangeEditor.d.ts +8 -0
- package/dist/editors/RangeEditor.js +3 -2
- package/dist/editors/RelationEditor.d.ts +2 -0
- package/dist/editors/RelationEditor.js +16 -2
- package/dist/editors/RelationSetEditor.d.ts +4 -2
- package/dist/editors/RelationSetEditor.js +36 -2
- package/dist/editors/SelectEditor.d.ts +5 -2
- package/dist/editors/SelectEditor.js +31 -4
- package/dist/editors/TextEditor.js +3 -1
- package/dist/editors/ValueListEditor.d.ts +3 -0
- package/dist/editors/ValueListEditor.js +10 -4
- package/dist/editors/edit-session.d.ts +14 -2
- package/dist/editors/edit-session.js +13 -5
- package/dist/editors/escape-rule.d.ts +12 -0
- package/dist/editors/escape-rule.js +8 -0
- package/dist/editors/open-value.js +2 -1
- package/dist/editors/picker-slot.d.ts +25 -0
- package/dist/editors/picker-slot.js +37 -0
- package/dist/editors/relation-picker.d.ts +44 -0
- package/dist/editors/relation-picker.js +49 -0
- package/dist/editors/relation-source.d.ts +1 -0
- package/dist/editors/relation-source.js +7 -1
- package/dist/field-row/FieldNoteLine.js +2 -1
- package/dist/field-row/FieldRow.js +41 -6
- package/dist/field-row/FieldRowLane.js +3 -1
- package/dist/field-row/editors/RowChipsEditor.js +1 -1
- package/dist/field-row/editors/RowDateEditor.js +1 -1
- package/dist/field-row/editors/RowEditor.js +2 -1
- package/dist/field-row/editors/RowRangeEditor.js +2 -1
- package/dist/field-row/editors/RowRelationEditor.js +2 -2
- package/dist/field-row/editors/RowSelectEditor.d.ts +1 -1
- package/dist/field-row/editors/RowSelectEditor.js +2 -2
- package/dist/field-row/editors/RowValueListEditor.js +1 -1
- package/dist/field-row/editors/host.d.ts +3 -0
- package/dist/field-row/editors/row-session.js +4 -1
- package/dist/fields/menus.d.ts +2 -0
- package/dist/fields/range-unit.d.ts +7 -0
- package/dist/fields/range-unit.js +13 -0
- package/dist/figures.d.ts +5 -48
- package/dist/figures.js +1 -63
- package/dist/grid/chrome/GridAddColumn.d.ts +8 -0
- package/dist/grid/chrome/GridAddColumn.js +66 -9
- package/dist/grid/chrome/GridAggregateMenu.d.ts +5 -2
- package/dist/grid/chrome/GridAggregateMenu.js +33 -4
- package/dist/grid/chrome/GridCellEditors.d.ts +9 -2
- package/dist/grid/chrome/GridCellEditors.js +24 -5
- package/dist/grid/chrome/GridCellOutline.d.ts +3 -2
- package/dist/grid/chrome/GridCellOutline.js +11 -1
- package/dist/grid/chrome/GridChipsEditor.js +1 -1
- package/dist/grid/chrome/GridColumnColorSection.d.ts +2 -0
- package/dist/grid/chrome/GridColumnColorSection.js +2 -2
- package/dist/grid/chrome/GridColumnDateSection.d.ts +4 -0
- package/dist/grid/chrome/GridColumnDateSection.js +2 -2
- package/dist/grid/chrome/GridColumnDurationSection.d.ts +4 -0
- package/dist/grid/chrome/GridColumnDurationSection.js +2 -2
- package/dist/grid/chrome/GridColumnMenu.d.ts +10 -6
- package/dist/grid/chrome/GridColumnMenu.js +62 -24
- package/dist/grid/chrome/GridColumnNumberSection.d.ts +4 -0
- package/dist/grid/chrome/GridColumnNumberSection.js +2 -2
- package/dist/grid/chrome/GridColumnPercentSection.d.ts +1 -0
- package/dist/grid/chrome/GridColumnPercentSection.js +1 -1
- package/dist/grid/chrome/GridColumnSortSection.d.ts +3 -3
- package/dist/grid/chrome/GridDateEditor.js +1 -1
- package/dist/grid/chrome/GridFooter.js +7 -48
- package/dist/grid/chrome/GridGroupMenu.d.ts +11 -5
- package/dist/grid/chrome/GridGroupMenu.js +28 -13
- package/dist/grid/chrome/GridHeader.d.ts +3 -1
- package/dist/grid/chrome/GridHeader.js +8 -8
- package/dist/grid/chrome/GridNumberEditor.js +3 -24
- package/dist/grid/chrome/GridRangeEditor.js +3 -2
- package/dist/grid/chrome/GridRelationEditor.js +2 -2
- package/dist/grid/chrome/GridRow.d.ts +2 -1
- package/dist/grid/chrome/GridRow.js +13 -37
- package/dist/grid/chrome/GridRowActions.js +2 -1
- package/dist/grid/chrome/GridRowCells.js +9 -4
- package/dist/grid/chrome/GridSelectEditor.js +30 -20
- package/dist/grid/chrome/GridStructure.d.ts +11 -4
- package/dist/grid/chrome/GridStructure.js +19 -7
- package/dist/grid/chrome/GridTable.js +138 -16
- package/dist/grid/chrome/GridTableSurface.d.ts +25 -12
- package/dist/grid/chrome/GridTableSurface.js +13 -6
- package/dist/grid/chrome/GridTextEditor.js +3 -1
- package/dist/grid/chrome/GridValueListEditor.js +1 -1
- package/dist/grid/chrome/cell-clipboard.d.ts +1 -1
- package/dist/grid/chrome/cell-clipboard.js +1 -1
- package/dist/grid/chrome/checks.d.ts +10 -2
- package/dist/grid/chrome/checks.js +17 -11
- package/dist/grid/chrome/column-glyph.d.ts +2 -2
- package/dist/grid/chrome/column-glyph.js +4 -0
- package/dist/grid/chrome/grid-add-column-items.d.ts +13 -0
- package/dist/grid/chrome/grid-add-column-items.js +40 -0
- package/dist/grid/chrome/grid-cell-classes.d.ts +2 -0
- package/dist/grid/chrome/grid-cell-classes.js +10 -4
- package/dist/grid/chrome/grid-column-menu-items.d.ts +75 -0
- package/dist/grid/chrome/grid-column-menu-items.js +263 -0
- package/dist/grid/chrome/grid-edit-escape.d.ts +4 -0
- package/dist/grid/chrome/grid-edit-escape.js +12 -0
- package/dist/grid/chrome/grid-edit-session.d.ts +2 -1
- package/dist/grid/chrome/grid-edit-session.js +14 -1
- package/dist/grid/chrome/grid-figure-value.d.ts +25 -0
- package/dist/grid/chrome/grid-figure-value.js +40 -0
- package/dist/grid/chrome/grid-fitted-box.d.ts +15 -0
- package/dist/grid/chrome/grid-fitted-box.js +26 -0
- package/dist/grid/chrome/grid-group-menu-items.d.ts +31 -0
- package/dist/grid/chrome/grid-group-menu-items.js +75 -0
- package/dist/grid/chrome/grid-group-menu-parts.d.ts +27 -0
- package/dist/grid/chrome/grid-group-menu-parts.js +19 -0
- package/dist/grid/chrome/grid-hover.d.ts +1 -0
- package/dist/grid/chrome/grid-hover.js +13 -1
- package/dist/grid/chrome/grid-lab.d.ts +7 -0
- package/dist/grid/chrome/grid-lab.js +7 -0
- package/dist/grid/chrome/grid-menu-focus.d.ts +12 -0
- package/dist/grid/chrome/grid-menu-focus.js +13 -0
- package/dist/grid/chrome/{useGridRowContextMenu.d.ts → grid-row-menu-items.d.ts} +15 -4
- package/dist/grid/chrome/{useGridRowContextMenu.js → grid-row-menu-items.js} +15 -18
- package/dist/grid/chrome/grid-row-props.d.ts +3 -1
- package/dist/grid/chrome/grid-row-window.d.ts +15 -5
- package/dist/grid/chrome/grid-row-window.js +44 -10
- package/dist/grid/chrome/grid-rows-menu.d.ts +38 -0
- package/dist/grid/chrome/grid-rows-menu.js +83 -0
- package/dist/grid/chrome/grid-table-props.d.ts +53 -8
- package/dist/grid/chrome/useGridBandFigures.d.ts +26 -0
- package/dist/grid/chrome/useGridBandFigures.js +50 -0
- package/dist/grid/chrome/useGridBoxes.d.ts +22 -0
- package/dist/grid/chrome/useGridBoxes.js +22 -0
- package/dist/grid/chrome/useGridColumnLayout.js +29 -4
- package/dist/grid/chrome/useGridKeyboard.js +7 -2
- package/dist/grid/chrome/useGridPartColumns.d.ts +5 -0
- package/dist/grid/chrome/useGridPartColumns.js +9 -0
- package/dist/grid/chrome/useGridRangeGestures.js +2 -1
- package/dist/grid/chrome/useGridRecorder.d.ts +16 -0
- package/dist/grid/chrome/useGridRecorder.js +144 -0
- package/dist/grid/chrome/useGridRowOpener.d.ts +41 -0
- package/dist/grid/chrome/useGridRowOpener.js +83 -0
- package/dist/grid/chrome/useGridScrollArea.d.ts +38 -12
- package/dist/grid/chrome/useGridScrollArea.js +70 -17
- package/dist/grid/chrome/useGridTableInteractionModel.d.ts +1 -0
- package/dist/grid/chrome/useGridTableInteractionModel.js +67 -9
- package/dist/grid/core/clipboard-model.d.ts +11 -3
- package/dist/grid/core/clipboard-model.js +9 -4
- package/dist/grid/core/commit-model.d.ts +7 -0
- package/dist/grid/core/editing-controller.d.ts +31 -1
- package/dist/grid/core/editing-controller.js +65 -0
- package/dist/grid/core/grid-recorder.d.ts +111 -0
- package/dist/grid/core/grid-recorder.js +223 -0
- package/dist/grid/core/part-edits.d.ts +18 -0
- package/dist/grid/core/part-edits.js +48 -0
- package/dist/grid/core/pending-reconciliation.js +12 -3
- package/dist/grid/core/refusal-sentence.d.ts +3 -0
- package/dist/grid/core/refusal-sentence.js +15 -0
- package/dist/grid/core/row-opened-from.d.ts +21 -0
- package/dist/grid/core/row-opened-from.js +11 -0
- package/dist/grid/core/useGridEditing.d.ts +16 -2
- package/dist/grid/core/useGridEditing.js +10 -4
- package/dist/grid/core/value-equality.d.ts +19 -1
- package/dist/grid/core/value-equality.js +24 -0
- package/dist/grid/index.d.ts +4 -1
- package/dist/grid/index.js +1 -0
- package/dist/grid/useGridTablePrefs.d.ts +1 -1
- package/dist/grid-lab.d.ts +18 -0
- package/dist/grid-lab.js +16 -0
- package/dist/grouping/sort-groups.d.ts +6 -7
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/internal/reset.d.ts +9 -0
- package/dist/internal/reset.js +1 -0
- package/dist/model/aggregates.d.ts +3 -3
- package/dist/model/aggregates.js +17 -71
- package/dist/model/column-capabilities.d.ts +29 -2
- package/dist/model/column-capabilities.js +27 -3
- package/dist/model/column-filters.js +24 -4
- package/dist/model/column-inspect.d.ts +2 -1
- package/dist/model/column-order.d.ts +2 -2
- package/dist/model/column-schema.d.ts +18 -7
- package/dist/model/column-state.d.ts +9 -20
- package/dist/model/column-state.js +1 -4
- package/dist/model/column-types.d.ts +1 -15
- package/dist/model/column-types.js +1 -1
- package/dist/model/part-columns.d.ts +17 -0
- package/dist/model/part-columns.js +67 -0
- package/dist/model/part-rows.d.ts +3 -10
- package/dist/model/part-rows.js +6 -11
- package/dist/model/part-write.d.ts +11 -0
- package/dist/model/part-write.js +52 -0
- package/dist/model/preferences.d.ts +3 -23
- package/dist/model/preferences.js +1 -17
- package/dist/model/prefs-buckets.d.ts +0 -27
- package/dist/model/prefs-buckets.js +1 -1
- package/dist/model/relation-filters.d.ts +0 -1
- package/dist/model/relation-filters.js +1 -1
- package/dist/model/row-icon.d.ts +5 -9
- package/dist/model/view-rules.d.ts +32 -6
- package/dist/model/view-rules.js +101 -21
- package/dist/provider/ViewsProvider.d.ts +22 -2
- package/dist/provider/ViewsProvider.js +21 -2
- package/dist/provider/components.d.ts +197 -9
- package/dist/provider/context.d.ts +12 -1
- package/dist/provider/desktop.d.ts +3 -0
- package/dist/provider/desktop.js +7 -4
- package/dist/provider/menu-groups.d.ts +3 -2
- package/dist/provider/menu-groups.js +13 -7
- package/dist/provider/missing-slot.d.ts +10 -0
- package/dist/provider/missing-slot.js +15 -0
- package/dist/provider/plain-input.d.ts +3 -2
- package/dist/provider/plain-input.js +3 -1
- package/dist/react.d.ts +3 -2
- package/dist/selection/SelectionBar.d.ts +18 -0
- package/dist/selection/SelectionBar.js +92 -0
- package/dist/selection/SelectionBarPhone.d.ts +3 -0
- package/dist/selection/SelectionBarPhone.js +14 -0
- package/dist/selection/bar-overflow.d.ts +12 -0
- package/dist/selection/bar-overflow.js +42 -0
- package/dist/selection/bar-parts.d.ts +15 -0
- package/dist/selection/bar-parts.js +17 -0
- package/dist/selection/index.d.ts +2 -0
- package/dist/selection/index.js +1 -0
- package/dist/selection/types.d.ts +3 -2
- package/dist/selection/verbs.d.ts +34 -0
- package/dist/selection/verbs.js +1 -0
- package/docs/contract.md +142 -39
- package/docs/getting-started.md +1 -1
- package/docs/guides/atoms.md +32 -4
- package/docs/guides/columns.md +1 -1
- package/docs/guides/display.md +1 -1
- package/docs/guides/editors.md +3 -3
- package/docs/guides/ports.md +1 -1
- package/docs/guides/selection.md +32 -20
- package/docs/guides/the-grid.md +43 -21
- package/docs/guides/the-provider.md +14 -4
- package/docs/index.md +2 -0
- package/docs/install.md +8 -1
- package/docs/reference/editors-date.md +2 -0
- package/docs/reference/editors-panel.md +4 -4
- package/docs/reference/editors-range.md +1 -1
- package/docs/reference/editors-relation.md +3 -3
- package/docs/reference/editors-select.md +1 -1
- package/docs/reference/editors-session.md +3 -2
- package/docs/reference/editors-value-list.md +1 -1
- package/docs/reference/field-row.md +2 -2
- package/docs/reference/grid.md +25 -6
- package/docs/reference/react.md +30 -8
- package/docs/reference/selection.md +10 -2
- package/docs/reference/views.md +42 -36
- package/package.json +22 -3
- package/skills/views/SKILL.md +3 -3
package/docs/contract.md
CHANGED
|
@@ -23,7 +23,8 @@ use; the prefix keeps that selector from reaching an element of the app's own.
|
|
|
23
23
|
| slot | the element |
|
|
24
24
|
| ------------------------------------ | --------------------------------------------------------- |
|
|
25
25
|
| `data-slot="vk-grid"` | the grid's frame: fills the box the app gives it |
|
|
26
|
-
| `data-slot="vk-grid-
|
|
26
|
+
| `data-slot="vk-grid-pan"` | the grid's sideways box, drawn only while the lab's lock is on and the screen is a touch screen: it scrolls the table sideways |
|
|
27
|
+
| `data-slot="vk-grid-scroll"` | the rows' box: the grid's one scroll area, both ways; up and down only inside `vk-grid-pan` while that is drawn |
|
|
27
28
|
| `data-slot="vk-grid-head"` | an ungrouped grid's pinned head: its header row |
|
|
28
29
|
| `data-slot="vk-grid-header"` | the header row |
|
|
29
30
|
| `data-slot="vk-grid-header-cell"` | one column's header |
|
|
@@ -42,14 +43,22 @@ use; the prefix keeps that selector from reaching an element of the app's own.
|
|
|
42
43
|
| `data-slot="vk-grid-editor"` | the open editor over a cell |
|
|
43
44
|
| `data-slot="vk-grid-outline"` | the outline around the focused cell or the selected range |
|
|
44
45
|
| `data-slot="vk-grid-resize-handle"` | a column's resize handle |
|
|
45
|
-
| `data-slot="vk-grid-column-menu"` | the header menu
|
|
46
|
+
| `data-slot="vk-grid-column-menu"` | the header menu, on the `popover` route |
|
|
46
47
|
| `data-slot="vk-grid-flyout"` | a flyout a menu row opens beside its menu |
|
|
47
|
-
| `data-slot="vk-grid-group-menu"` | a group band's menu
|
|
48
|
-
| `data-slot="vk-grid-aggregate-menu"` | the footer's figure picker
|
|
48
|
+
| `data-slot="vk-grid-group-menu"` | a group band's menu, on the `popover` route |
|
|
49
|
+
| `data-slot="vk-grid-aggregate-menu"` | the footer's figure picker, on the `popover` route |
|
|
49
50
|
|
|
50
51
|
Board's slots (`vk-board`, `vk-board-lane`, `vk-board-lane-header`, `vk-board-card`,
|
|
51
52
|
`vk-board-add-card`) join this table when the board arrives.
|
|
52
53
|
|
|
54
|
+
The selection bar's parts (`SelectionBar`, `@viewkitjs/views/selection`):
|
|
55
|
+
|
|
56
|
+
| Slot | Part |
|
|
57
|
+
| ------------------------------------ | ---------------------------------------------------------- |
|
|
58
|
+
| `data-slot="vk-selection-bar"` | the fixed box the app places (the provider's `selectionBar`) |
|
|
59
|
+
| `data-slot="vk-selection-pill"` | the pill inside it: the count, the verbs, the trash, More |
|
|
60
|
+
| `data-slot="vk-selection-chip"` | the count that clears the selection, on the desktop |
|
|
61
|
+
|
|
53
62
|
## States
|
|
54
63
|
|
|
55
64
|
Flags the rendering styles, present as an attribute when true and absent when false, so a skin
|
|
@@ -116,6 +125,8 @@ frame from its scale and its state; a skin reads them and an app overrides them
|
|
|
116
125
|
| `--vk-text-10` | the smallest text size |
|
|
117
126
|
| `--vk-head-text` | header text size |
|
|
118
127
|
| `--vk-scrolled` | 0 or 1: content scrolled under the header |
|
|
128
|
+
| `--vk-pin` | a row's frozen cells and rail: `relative` at rest, `sticky` once the rows' box is scrolled sideways |
|
|
129
|
+
| `--vk-stick` | 0 or 1: 1 while `--vk-pin` is `sticky`; it scales their sticky offsets |
|
|
119
130
|
| `--vk-parked` | 0 or 1: identity columns parked |
|
|
120
131
|
| `--vk-frozen-on` | 0 or 1: the frozen band is on |
|
|
121
132
|
| `--vk-row-py` | a rows view's vertical row padding |
|
|
@@ -158,7 +169,8 @@ declares both wherever a ground declares its own, so a part takes the states of
|
|
|
158
169
|
The default atoms and the display also read `--vk-success`, `--vk-warning`, `--vk-info`,
|
|
159
170
|
`--vk-label-blue`, `--vk-label-green`, `--vk-label-amber`, `--vk-label-red`, `--vk-label-purple`,
|
|
160
171
|
`--vk-label-pink` and `--vk-label-teal` when the app declares them, each with a built-in fallback. The
|
|
161
|
-
|
|
172
|
+
selection bar reads `--vk-float-shadow`, a whole `box-shadow` value for what floats over a list, with a
|
|
173
|
+
built-in fallback. The corners come from the app's Tailwind radius scale.
|
|
162
174
|
|
|
163
175
|
**The page gutter is the app's, if it has one.** `--vk-gutter` is the side padding a page gives its
|
|
164
176
|
content: the grid's rows run edge to edge and line their content up with it. An app that pads its
|
|
@@ -169,17 +181,21 @@ clear of it and a revealed cell stops above it. An app declares it on the grid's
|
|
|
169
181
|
undeclared, the grid reads `0px`.
|
|
170
182
|
|
|
171
183
|
**The grid scrolls inside itself.** Its frame fills the box its app gives it: a definite height, or
|
|
172
|
-
a flex column (the frame is `height: 100%`, `flex: 1 1 0` and `min-height: 0`). Inside the frame
|
|
173
|
-
|
|
174
|
-
|
|
184
|
+
a flex column (the frame is `height: 100%`, `flex: 1 1 0` and `min-height: 0`). Inside the frame the
|
|
185
|
+
rows' box holds the table, both ways, and each group's name bar and header row pin at its top, so
|
|
186
|
+
nothing the app pins above the grid concerns it. While the page's lab asks for the lock
|
|
187
|
+
(`setGridLab({ boxes: 2 })`) on a touch screen, it scrolls up and down only, inside an outer box that
|
|
188
|
+
scrolls sideways only, so a flick moves the table one way, as the phone's own apps do. A box with no height gets a grid that grows
|
|
175
189
|
to its rows: the page scrolls it, and its heads don't pin. The grid's rows and frozen columns sit
|
|
176
190
|
inside your `Collapse`'s clip, so the clip must crop without scrolling (`overflow: clip`, never
|
|
177
191
|
`hidden`): a clip that scrolls takes the frozen columns' sticky edge with it.
|
|
178
192
|
|
|
179
193
|
**The grid's own variables are not public.** The grid sets `--vk-drag-shift` (a header cell's
|
|
180
194
|
offset while its column is dragged to a new place), `--vk-col-w-<id>` (one column's resolved
|
|
181
|
-
width, one per column)
|
|
182
|
-
reads)
|
|
195
|
+
width, one per column), `--vk-cols` (the columns' template on its rows' box, which every row
|
|
196
|
+
reads), and while the lab's lock is on `--vk-hold-x` and `--vk-sx` (the offsets that hold the frozen
|
|
197
|
+
columns, the rail, a group's name and the empty message at the left while the table is scrolled
|
|
198
|
+
sideways) for itself. They carry the prefix because they share the global namespace;
|
|
183
199
|
an app neither sets nor reads them, and they may change in any release.
|
|
184
200
|
|
|
185
201
|
## The components map
|
|
@@ -192,9 +208,17 @@ and no `asChild`; the tooltip takes the element it wraps as `children`. The slot
|
|
|
192
208
|
grid's editors and menus use, each in Base UI's shape, and an adapter on Radix and one on Base UI
|
|
193
209
|
both fill every one.
|
|
194
210
|
|
|
195
|
-
`Button` · `Popover` · `Tooltip` · `Checkbox` · `Menu` · `
|
|
211
|
+
`Button` · `Popover` · `Tooltip` · `Checkbox` · `Menu` · `Collapse` · `Sheet` · `AppIcon` · `Markdown`
|
|
212
|
+
|
|
213
|
+
`Input`, optional: a single-line text box, `ViewsInputProps`. Every editor's text box draws through it; without it the editors draw a plain `<input>`. Forward every prop to your element, `ref` included. `chrome` is `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame). `OPTIONAL_COMPONENT_NAMES` lists the five optional slots apart from `COMPONENT_NAMES`, which lists the slots you must fill.
|
|
214
|
+
|
|
215
|
+
`Command`, optional: the command list's parts (`ViewsCommandParts`), through which the editors' lists and the grid's menus on the `popover` route draw. A list reached without one throws an error naming it. An app that hands `Picker` and sets `menus: "menu"` needs none.
|
|
196
216
|
|
|
197
|
-
`
|
|
217
|
+
`Picker`, optional: a whole pick list your app draws, `ViewsPickerProps`. Handed one, the select, several-values, place and relation editors open it, handed their rows as `ViewsPickerItem` data (a value, its words, a status slot or a colour, a glyph, a line, a group), what is held, the empty row's words, the search's words, create (`onCreate`, handed what was typed, returning the value it makes) and `form`. The body hands back `onValueChange` (the pick, or the whole new list) and `onDone` (a pick of one is made). The editor keeps the draft, what each close means, Tab, Escape, the save and, on a phone, the panel's ✕ and ✓: at `form: "phone"` your body draws none of its own and hands every change as it is made. Tab is taken before your body hears it. Left out, these editors draw from `Command`. A relation's list is filtered (a static source, by label) or fetched (a remote one, a page at a time) by the editor, never by your body: it hands every typed query to `onSearch` and draws `items` as handed, with `doing` (`searching` or `failed`), `onRetry` and `onMore` for a remote one. A relation's rows may carry a `badge` (a word telling kinds apart), a `glyph` (the record's own, unsized), an `avatarUrl` and the record's `kind`; its create rows come as `actions` (`ViewsPickerAction`), after the rows, and picking one closes the editor before it runs; a set whose field leads hands `lead` (which value leads, `onLead`, and its words). Held records come first while nothing is typed, and by the same search once something is.
|
|
218
|
+
|
|
219
|
+
`Calendar`, optional: a calendar over ISO days, `ViewsCalendarProps`, which the date editor draws its month through, with its own typed line, quick days and time around it. Reached without one, it throws an error naming it. Handed `DateBody`, it is never reached.
|
|
220
|
+
|
|
221
|
+
`DateBody`, optional: a whole date body your app draws, `ViewsDateBodyProps`. Handed one, the date editor opens it in every host, handed the value on the local calendar (a day, or a day and a time), whether it holds a time, whether it may be emptied, the quick picks (`ViewsDatePick`), today, what was typed on what opened it, `autoFocus` and `form`. The body hands back `onValueChange` (every change as it is made, a typed day once it reads as one) and `onDone` (a pick that finishes the edit). The editor keeps the draft, what each close means (Escape's keep or throw-away by field type), the save and, on a phone, the panel's ✕ and ✓: at `form: "phone"` your body draws none of its own. Escape is taken before your body hears it, so a popover of your own inside the body never hears Escape either; Tab walks your body's controls and closes from either end.
|
|
198
222
|
|
|
199
223
|
The popover takes `alignOffset`, `initialFocus` (false keeps focus where it was when the popup
|
|
200
224
|
opens; the editor that then takes focus does so with `preventScroll`, so the package's own focus
|
|
@@ -213,10 +237,13 @@ calendar takes a controlled `month` (`YYYY-MM`) with `onMonthChange`, a `dropdow
|
|
|
213
237
|
draws its month and weekday names and starts its week; an adapter may ignore it and keep its
|
|
214
238
|
calendar's own. The tooltip takes `align` and a class; the checkbox takes `checked` and, for a box
|
|
215
239
|
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
|
|
216
|
-
one tooltip provider above the views, and a tooltip never mounts its own.
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
240
|
+
one tooltip provider above the views, and a tooltip never mounts its own. The menu takes `label`,
|
|
241
|
+
its name (its `aria-label`), which every menu the package opens hands. A menu item's `label` is its
|
|
242
|
+
words, always text; it may carry a `shortcut` hint and an `href`, and a `disabled` row may carry
|
|
243
|
+
`disabledReason`, why it can't be used, for you to show (a tooltip, a second line); a `checked` row is checkable and closes the menu like any row, unless it
|
|
244
|
+
carries `keepOpen`, a hint to leave the menu open so several can be ticked in turn; an
|
|
245
|
+
item's `children` are a group, its rows drawn in place under the item's label unless it carries `beside`, a hint to open them one level in, its row showing its label and `detail`, and
|
|
246
|
+
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`, each one that gives no reason carrying the group's `disabledReason`, so you draw each row by its own flag. Any row may carry `detail`, its current value in words, for its end. An adapter that draws none of the three keeps every row closing and every group in place, and loses nothing it needs. So an adapter needn't guess: a ticked row's `onSelect` fires on every pick, also when it is already ticked (a second pick of the ticked sort flips its direction), so an adapter that draws ticked rows as a radio value still calls it; ticked rows that close, inside a group, are one choice among several (a pick list), and ticked rows with `keepOpen` are separate ticks (checkboxes); a label is always text, so a swatch or a column's mark rides as the row's `icon` beside it. The sheet takes `label`, its title in words whenever the title is words (its accessible name, and the title of a head that takes only text), and, when the provider's `sheetActions` is `head`, `actions`: the editor panel's ✕ (`close`) and ✓ (`done`, absent where the body saves on its pick), each a `label` and an `onPress`, for your sheet's own head; with `bar`, the default, the panel draws them itself. `AppIcon` is the app's own icon component by the app's own names, for
|
|
220
247
|
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
|
|
221
248
|
needs are a port, by meaning (below). `Markdown` is the app's markdown renderer, handed the stored text whole; the
|
|
222
249
|
package draws rich text through it and parses none.
|
|
@@ -233,12 +260,19 @@ The package ships none of them and depends on neither library.
|
|
|
233
260
|
|
|
234
261
|
What a Base UI adapter over shadcn copies does where its copies stop short of a slot.
|
|
235
262
|
|
|
236
|
-
**The menu.** The map's `Menu` has an anchor and no trigger
|
|
263
|
+
**The menu.** The map's `Menu` has an anchor and no trigger. Build it from the menu
|
|
237
264
|
library's root, positioner and popup, handing the anchor to the positioner, where your copy's content
|
|
238
|
-
doesn't forward one;
|
|
265
|
+
doesn't forward one; the root needs no trigger of its own, because the package opens it. A group that asks for
|
|
266
|
+
`beside` may be a submenu whose trigger is the group's own row, inside the open menu; with none, draw it in place.
|
|
267
|
+
Opened, it puts focus on its
|
|
239
268
|
first row, as your `Popover` does by default: a row's menu opened by a key starts there.
|
|
240
269
|
|
|
241
|
-
**A disabled group.** Nothing to do: its rows reach you already `disabled
|
|
270
|
+
**A disabled group.** Nothing to do: its rows reach you already `disabled`, with the group's reason where they give none.
|
|
271
|
+
|
|
272
|
+
**The sheet's head.** A sheet that draws a head of its own (a title with buttons beside it) sets the
|
|
273
|
+
provider's `sheetActions` to `head` and draws `actions.close` and, when handed, `actions.done` there,
|
|
274
|
+
with your own ✕ and ✓ glyphs; a close of your sheet's own (its ✕, a swipe) still reaches
|
|
275
|
+
`onOpenChange` and discards like `actions.close`.
|
|
242
276
|
|
|
243
277
|
**`chrome: "menu"`.** It is your menu panel's surface: no inset, because the list inside carries its
|
|
244
278
|
own, and no card width: it is as wide as its list. Where your copy has only the card popover, lay your
|
|
@@ -248,7 +282,7 @@ menu classes over it.
|
|
|
248
282
|
check. Where your copy's item draws a tick of its own, hide it.
|
|
249
283
|
|
|
250
284
|
**A command list that scrolls as it mounts.** The chips, select and relation editors, and the grid's
|
|
251
|
-
Add column and group menu, mount a `Command.Root` with its rows in the frame the popover opens, before
|
|
285
|
+
Add column (on the `popover` route) and group menu (on the `popover` route: past eight sort choices, or at any count when the app names its parts with `groupMenu`), mount a `Command.Root` with its rows in the frame the popover opens, before
|
|
252
286
|
your popover has placed its popup. A command library that scrolls its selected item into view on mount
|
|
253
287
|
(cmdk does, with `scrollIntoView`) scrolls the page towards the popup's unplaced spot, which at a
|
|
254
288
|
library's default positioning can be the page's top, and `preventScroll` on the focus doesn't reach
|
|
@@ -282,9 +316,12 @@ container: the inset a run of rows sits in, inside a panel or a command list's g
|
|
|
282
316
|
a button or, with `interactive={false}`, a static line), `RowContent` (a row's inside, for inside a
|
|
283
317
|
command list's item, which owns the element and the highlight), `TickBox` (a paint-only tick box),
|
|
284
318
|
`StatusBadge` (a pill by status slot), `StatusMarker` (an attention badge that opens its reason) and
|
|
285
|
-
`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
|
|
319
|
+
`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 rows' right-click menu, once around each section's rows' container and aimed at the row a press or a right-click came from, its props that row's: 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"`; the grid's row-menu keys send a cell the same right-click, with no press before it, so a `RowMenu` of your own opens on any `contextmenu` and doesn't wait for a press; 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), `RelationRoles` (a link's roles, inside its chip after the record's name, on a `many` relation that declares `links`; the default draws their labels in the subtle colour after a middle dot, wrapped in `data-slot="vk-relation-roles"`), `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"`), and the rows the panels (`/panels`) draw with: `ChoiceRow` (picks a value: its label, a second line, a right-hand meta, the check when chosen), `CheckRow` (toggles one of many, a tick box on the left), `RadioRow` (picks one of a set, its mark a check or, with `mark="box"`, a tick box; a disabled row's reason in your `Tooltip`), `DirectionButton` (a sort's direction arrow, named `views.panels.direction`), `MenuRow` (a drill-in row: a glyph, the section, where it stands, a chevron), `ToggleRow` (a boolean flipped in place, with a way back named `views.panels.toggle-reset`) and `PanelSearch` (a panel's text box, a filled well with a magnifier). Each ships as a default, exported as `DEFAULT_VIEWS_ATOMS`, drawn
|
|
286
320
|
from the app's colours; an app swaps any of them through the provider's `atoms`, and the rest
|
|
287
|
-
stay the defaults.
|
|
321
|
+
stay the defaults. `SelectionSheet` is the phone's sheet of a selection's verbs, opened by the
|
|
322
|
+
selection bar's Actions: the default is the components map's `Sheet` holding the atoms' rows, a group's
|
|
323
|
+
or an options verb's rows opening in place under it and the delete last in words; picking a row closes
|
|
324
|
+
the sheet, then runs it. An app swaps in its own action sheet.
|
|
288
325
|
|
|
289
326
|
A row's `size` is `compact` (13px: a command list's rows, a list of values) or `regular` (the app's
|
|
290
327
|
menu size, the default). Its label truncates when it is text and is laid out in a row when it is a
|
|
@@ -298,7 +335,7 @@ since the flyout is the components map's `Popover`, a dialog of plain rows; and
|
|
|
298
335
|
and `open` while that flyout is up (`data-open`, the pressed ground).
|
|
299
336
|
|
|
300
337
|
The defaults mark themselves with `data-slot="vk-list"`, `data-slot="vk-row"`, `data-slot="vk-row-content"`,
|
|
301
|
-
`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
|
|
338
|
+
`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-relation-roles"`, `data-slot="vk-loading"`, `data-slot="vk-load-more"`, `data-slot="vk-platform"`, `data-slot="vk-row-menu"` and `data-slot="vk-selection-sheet"`, the panels' rows with `data-slot="vk-choice-row"`, `data-slot="vk-check-row"`, `data-slot="vk-radio-row"`, `data-slot="vk-direction"`, `data-slot="vk-menu-row"`, `data-slot="vk-toggle-row"` and `data-slot="vk-panel-search"`, and
|
|
302
339
|
with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked`, `data-open` (flags),
|
|
303
340
|
`data-status` (the slot's name) and `data-platform` (a link's platform key). A swapped atom marks itself as its app does.
|
|
304
341
|
|
|
@@ -313,7 +350,7 @@ a desktop and its `Sheet` on a phone, and marks its parts with these slots:
|
|
|
313
350
|
| slot | the element |
|
|
314
351
|
| ---------------------------------- | ------------------------------------------------------------- |
|
|
315
352
|
| `data-slot="vk-editor-panel"` | the popover's panel, or the sheet's body, an editor sits in |
|
|
316
|
-
| `data-slot="vk-editor-bar"` | the sheet's bar: its ✕ and its ✓
|
|
353
|
+
| `data-slot="vk-editor-bar"` | the sheet's bar: its ✕ and its ✓ (none with `sheetActions: "head"`) |
|
|
317
354
|
| `data-slot="vk-editor-refusal"` | the reason a refused value gave, under the editor |
|
|
318
355
|
| `data-slot="vk-text-editor"` | the text editor's box (`@viewkitjs/views/editors/text`), unless its host names its own |
|
|
319
356
|
|
|
@@ -339,6 +376,8 @@ The grid's menus: `moveLeft` `moveRight` `group` `clearSort` `sortRowsUp` `sortR
|
|
|
339
376
|
`sortRowsDown` are a menu's verbs, sorting the rows by a column; `sortAsc` and `sortDesc` are the mark a
|
|
340
377
|
sorted header wears.
|
|
341
378
|
|
|
379
|
+
The panels: `search` (a panel's text box, a magnifier) and `reset` (a setting's way back to the reader's default).
|
|
380
|
+
|
|
342
381
|
An app maps its own icon names onto these in its adapter; a glyph the rendering needs that is not
|
|
343
382
|
here is added here first, with a changelog line.
|
|
344
383
|
|
|
@@ -347,7 +386,7 @@ here is added here first, with a changelog line.
|
|
|
347
386
|
The package words only its own strings; a string `@viewkitjs/fields` already keys stays a fields
|
|
348
387
|
message, read from the conventions the provider carries. The package's are a closed list of
|
|
349
388
|
`{ key, values }` messages under `views.grid.*`,
|
|
350
|
-
`views.editors.*`, `views.menus.*` and `views.
|
|
389
|
+
`views.editors.*`, `views.menus.*`, `views.display.*`, `views.selection.*` and `views.panels.*`: `views.editors.tag-remove` (`{ label }`),
|
|
351
390
|
`views.editors.marker-resolve`, `views.editors.marker-no-reason`, `views.editors.range-low` and
|
|
352
391
|
`views.editors.range-high` (a range editor's two boxes, "From" and "To"), and `views.editors.name-given`,
|
|
353
392
|
`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); `views.editors.discard` ("Discard", the editor sheet's ✕) and `views.editors.save` ("Save", its ✓); `views.editors.open-email`, `views.editors.open-phone` and `views.editors.open-link` (`{ value }`, "Email {value}", "Call {value}", "Open {value}", the open action beside a stored value in a phone's sheet); 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`,
|
|
@@ -361,15 +400,19 @@ row), `views.menus.date-style` (`{ style }`: `"short"`, `"long"`, `"numeric"` or
|
|
|
361
400
|
`views.menus.automatic` (the field's own decimals, an option's own colour), `views.menus.currency`,
|
|
362
401
|
`views.menus.percent-display` ("Display"), `views.menus.percent-display-option` (`{ display }`: `"text"` is "Number",
|
|
363
402
|
`"bar"`, `"ring"`), `views.menus.colour` (`{ colour }`, one of the eight option colours: "Gray" … "Teal") and
|
|
364
|
-
`views.menus.colours-reset` ("Reset colors"); a group's menu: `views.menus.group-options` (its button's label),
|
|
403
|
+
`views.menus.colours-reset` ("Reset colors"); a group's menu: `views.menus.group-options` (its button's label, and its menu's name on the `menu` route),
|
|
365
404
|
`views.menus.group-sort` ("Sort rows"), `views.menus.search`, `views.menus.group-show` ("Show"), `views.menus.group-count`
|
|
366
405
|
("Count") and `views.menus.group-hide` ("Hide group"); "+ Add column": `views.grid.add-column` (its header
|
|
367
|
-
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:
|
|
406
|
+
cell, and its menu's name on the `menu` route), `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:
|
|
368
407
|
`views.menus.copy`, `views.menus.cut`, `views.menus.paste`, `views.menus.clear` and `views.menus.edit` (a cell's lane),
|
|
369
408
|
and the plain row menu's `views.menus.row-open` ("Open page"), `views.menus.row-select` (`{ selected }`, `"true"` is
|
|
370
409
|
"Deselect", as text for a catalog's `select`), `views.menus.row-delete`, `views.menus.row-delete-confirm` (the
|
|
371
410
|
browser's confirm before a delete: "Delete this row?") and `views.menus.row-delete-failed` (the error toast when the
|
|
372
|
-
delete the host ran rejects: "Failed to delete the row")
|
|
411
|
+
delete the host ran rejects: "Failed to delete the row"), and `views.menus.row-menu` (its name, handed to your `Menu` as
|
|
412
|
+
`label`: "Row actions"); a `command` field's verb menu's name: `views.menus.commands` (`{ field }`: "Actions for Stage")
|
|
413
|
+
and `views.menus.commands-unnamed` ("Actions", when its opener hands no field); `views.menus.figure-menu`
|
|
414
|
+
(`{ field }`: "Calculate Amount", the figure picker's name on the `menu` route) and `views.menus.column-menu`
|
|
415
|
+
(`{ field }`: "Options for Amount", a column menu's name on the `menu` route);
|
|
373
416
|
the grid's own: `views.grid.figure` (`{ kind }`, a footer figure's name, `"none"` included: "None", "Sum", "Avg", "Min",
|
|
374
417
|
"Max", "Count", "Filled", "Unique", "Ratio"), `views.grid.figure-pick` ("Calculate", an empty footer cell),
|
|
375
418
|
`views.grid.loading` ("Loading rows"), the labels `views.grid.select-row`, `views.grid.select-group`,
|
|
@@ -386,7 +429,10 @@ over several cells left because they can't be empty, already joined in the viewe
|
|
|
386
429
|
`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
|
|
387
430
|
record in another currency) and `views.grid.paste-not-range`; a paste or a fill that refused cells,
|
|
388
431
|
`views.grid.paste-skipped` and `views.grid.fill-skipped` (each `{ count, reason }`: one toast per reason, its
|
|
389
|
-
`reason` one of the refusals above in the app's words; an operation of one cell says the reason alone);
|
|
432
|
+
`reason` one of the refusals above in the app's words; an operation of one cell says the reason alone); a write the app
|
|
433
|
+
refused, said when the provider's `sayRefusals` is on, `views.grid.commit-refused` (`{ field }`, the field's name, for a
|
|
434
|
+
refusal whose error carries no words: "Couldn't save Amount.") and `views.grid.commit-refused-many` (`{ count, reason? }`,
|
|
435
|
+
a batch, once, with the first refusal's words when it has any); and the warnings
|
|
390
436
|
`views.grid.changed-elsewhere` (`{ field }`), `views.grid.changed-elsewhere-cells` (`{ count }`),
|
|
391
437
|
`views.grid.saved-value`, `views.grid.saved-values` and `views.grid.row-left`. The functions that word a refusal
|
|
392
438
|
(`gridClearRefusal`, `columnClearRefusal`, `columnEditRefusal`, `gridEditRefusal`) take the resolver last, and
|
|
@@ -401,6 +447,35 @@ record in another currency) and `views.grid.paste-not-range`; a paste or a fill
|
|
|
401
447
|
(the title on a phone stored as typed), and `views.display.converted-from` (`{ code }`, "Converted from USD", the
|
|
402
448
|
title on a money figure shown in another currency than its record's) and `views.display.as-shown` ("as shown",
|
|
403
449
|
after that figure under a money editor).
|
|
450
|
+
And the panels' words, for the panels' door a later release publishes: the "For you" heading, `views.panels.for-you`; the Group
|
|
451
|
+
panel's orders, `views.panels.group-order-most` ("Most first"), `views.panels.group-order-fewest`,
|
|
452
|
+
`views.panels.group-order-newest`, `views.panels.group-order-oldest`, `views.panels.group-order-alphabetical`,
|
|
453
|
+
`views.panels.group-order-reverse-alphabetical`, `views.panels.group-order-reversed` (`{ label }`, "Stage, reversed"),
|
|
454
|
+
`views.panels.group-order-default`, `views.panels.group-order-count`, `views.panels.group-order-name` and
|
|
455
|
+
`views.panels.group-order-manual`; a list's joins, `views.panels.join-or` (" or ") and `views.panels.join-and`
|
|
456
|
+
(" and "), which hand the keys below a list already joined, since a value is text or a number; a relation filter's:
|
|
457
|
+
`views.panels.quantifier` (`{ quantifier }`: `"any"`,
|
|
458
|
+
`"none"` or `"every"`), `views.panels.relation-condition-options` (`{ field, options }`: "status is Active or
|
|
459
|
+
Paused"), `views.panels.relation-condition` (`{ field, value }`), `views.panels.relation-sentence`
|
|
460
|
+
(`{ rule, subject, one, many, conditions }`, the whole sentence: "Clients with at least one campaign where status is Active.", its
|
|
461
|
+
`rule` `"all"`, `"any"`, `"none"`, `"every"` or `"every-unmatched"`), `views.panels.relation-value-one`
|
|
462
|
+
(`{ quantifier, field, value }`, "Any · Status: Active") and `views.panels.relation-value-many`
|
|
463
|
+
(`{ quantifier, count }`); a row's value: `views.panels.filter-unavailable` ("Saved filter unavailable"), `views.panels.filter-all`
|
|
464
|
+
("All"), `views.panels.filter-all-of` (`{ field }`, "All owners"), `views.panels.filter-selected` (`{ count }`),
|
|
465
|
+
`views.panels.date-range-all` ("All time"), `views.panels.date-range-between` (`{ from, to }`, "Jan 1 — Jan 9"),
|
|
466
|
+
`views.panels.date-range-from`, `views.panels.date-range-until`, `views.panels.time-scope-custom` ("Custom"),
|
|
467
|
+
`views.panels.sort-value` (`{ label, dir }`, "Name desc"), `views.panels.group-none` ("None") and
|
|
468
|
+
`views.panels.filter-count` (`{ count }`: "None", "1 filter", "2 filters"); and the rows':
|
|
469
|
+
`views.panels.direction` (`{ dir }`, "Direction: ascending"), `views.panels.toggle-reset` (`{ label }`, "Reset
|
|
470
|
+
Wrap"), `views.panels.toggle-reset-hint` ("Back to your default") and `views.panels.search-clear` ("Clear"). The
|
|
471
|
+
panels' label functions take the resolver last; each defaults to `resolveViewsMessage`.
|
|
472
|
+
The selection bar's words are under `views.selection.*`: `views.selection.count` (`{ count }`, "3 selected",
|
|
473
|
+
the phone sheet's title), `views.selection.selected` (the word after the count the bar draws),
|
|
474
|
+
`views.selection.deselect-all` (the count chip), `views.selection.clear` (the phone's ✕),
|
|
475
|
+
`views.selection.delete` (the trash's default name), `views.selection.more` and
|
|
476
|
+
`views.selection.more-label` (More, and its accessible name), `views.selection.actions` (the phone's
|
|
477
|
+
Actions), `views.selection.sheet-label` (the sheet's accessible name) and `views.selection.escape`
|
|
478
|
+
(the key cap in the chip's tooltip).
|
|
404
479
|
A span behind now is fields' own `time.ago`. The provider's `messages` resolves them; it defaults to the
|
|
405
480
|
package's English, `resolveViewsMessage`; an app's resolver that words only some keys calls
|
|
406
481
|
`resolveViewsMessage` for the rest, since the provider does not fall back for it. A new key is a
|
|
@@ -447,7 +522,7 @@ A field whose changes are transitions with rules of their own (a lost deal needs
|
|
|
447
522
|
|
|
448
523
|
## The doors
|
|
449
524
|
|
|
450
|
-
Twenty-one doors, and nothing else is importable but `./package.json
|
|
525
|
+
Twenty-one doors in this version, and nothing else is importable but `./package.json`; the twenty-second, the panels', is described last and comes in a later release. 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).
|
|
451
526
|
|
|
452
527
|
`@viewkitjs/views`, no React at runtime, holds two things. The rendering contract, every name listed:
|
|
453
528
|
the constants `VK_PREFIX`, `GRID_SLOTS`, `GRID_STATES`, `VK_TOKENS`, `VK_COLOURS`,
|
|
@@ -472,19 +547,32 @@ public; nothing else at the root door is.
|
|
|
472
547
|
|
|
473
548
|
`@viewkitjs/views/react`, which opens with the client directive: `ViewsProvider`, `useViews()` and
|
|
474
549
|
`NOOP_PORTS`; the provider's types `ViewsProviderProps` and `ViewsContextValue`; the adapter's types
|
|
475
|
-
`ViewsComponents`, `ViewsResolvedComponents` (the map as `useViews()` hands it on, `Input` always there), `ViewsPorts`, `ViewsIcons` and `ViewsIconProps`; the components' props
|
|
550
|
+
`ViewsComponents`, `ViewsResolvedComponents` (the map as `useViews()` hands it on, `Input`, `Command` and `Calendar` always there), `ViewsPorts`, `ViewsIcons` and `ViewsIconProps`; the components' props
|
|
476
551
|
`ViewsButtonProps`, `ViewsPopoverProps`, `ViewsTooltipProps`, `ViewsCheckboxProps`, `ViewsMenuProps`,
|
|
477
|
-
`ViewsMenuItem`, `ViewsCommandParts`, `ViewsCalendarProps`, `ViewsCollapseProps`,
|
|
552
|
+
`ViewsMenuItem`, `ViewsCommandParts`, `ViewsPickerProps`, `ViewsPickerItem`, `ViewsPickerAction`, `ViewsCalendarProps`, `ViewsDateBodyProps`, `ViewsDatePick`, `ViewsCollapseProps`,
|
|
478
553
|
`ViewsSheetProps` and `ViewsInputProps`, with their shared shapes `ViewsAnchor`, `ViewsSide`, `ViewsAlign`,
|
|
479
554
|
`ViewsCloseReason` and `ViewsOpenChange`; the ports' types `ViewsToastPort`, `ViewsHapticsPort`,
|
|
480
555
|
`ViewsClipboardPort`, `ViewsPrefsPort`, `ViewsConfirmPort`, `ViewsConfirmRequest` and `ViewsResolvedPorts` (the
|
|
481
556
|
ports `useViews()` hands on, `confirm` always there); the atoms' `DEFAULT_VIEWS_ATOMS` and types `ViewsAtoms`,
|
|
482
557
|
`ViewsListProps`, `ViewsRowProps`, `ViewsRowContentProps`, `ViewsTickBoxProps`, `ViewsStatusBadgeProps`,
|
|
483
|
-
`ViewsStatusMarkerProps`, `ViewsTagProps`, `ViewsCommandMenuProps`, `ViewsRowMenuProps`, `ViewsRowMenuItem`, `ViewsRelationLinkProps`, `ViewsLoadingProps`, `ViewsLoadMoreProps` and `ViewsPlatformMarkProps`; and, re-exported from the root door, `ComponentName`,
|
|
558
|
+
`ViewsStatusMarkerProps`, `ViewsTagProps`, `ViewsCommandMenuProps`, `ViewsRowMenuProps`, `ViewsRowMenuItem`, `ViewsRelationLinkProps`, `ViewsRelationRolesProps`, `ViewsLoadingProps`, `ViewsLoadMoreProps` and `ViewsPlatformMarkProps`; and, re-exported from the root door, `ComponentName`,
|
|
484
559
|
`PortName`, `ViewsIconName`, `ViewsMessage` and `ViewsMessageResolver`. The provider takes an
|
|
485
560
|
optional `presentation`, `(defaults: FieldPresentation) => FieldPresentation`: how the app's numbers,
|
|
486
561
|
dates and durations read — given the package's defaults (in the conventions' locale), return the
|
|
487
562
|
app's. It is called where a value is drawn, so the app's provider imports none of the display.
|
|
563
|
+
It takes an optional `escape` (`ViewsEscapeRules`, `{ [type]: EditEscape }`, `EditEscape` being `"cancel"` or `"keep"`,
|
|
564
|
+
both types from `./react`): what Escape does in an editor of each field type, on a desktop. `keep` keeps what was
|
|
565
|
+
typed and closes, as a press outside does, and a value that would be refused stays open with its reason, until a second Escape throws the edit away; a type left
|
|
566
|
+
out throws the edit away, the default. On a phone every way out of the sheet throws the edit away. An editor that
|
|
567
|
+
commits only on a pick (a select, a status, a single relation, a user) throws it away on Escape whatever the rule.
|
|
568
|
+
And an optional `sayRefusals` (default false): the grid says why the app refused an edit it sent, through the toast
|
|
569
|
+
port's `error`; off, the app says it. And an optional `menus` (`ViewsMenuRoute`, default `popover`): how the grid
|
|
570
|
+
opens its own menus. `popover` draws ViewKit's rows in your `Popover`; `menu` hands them to your `Menu` as rows, the
|
|
571
|
+
footer's figure picker one ticked row per figure, and a column's header menu its rows, each format setting and each
|
|
572
|
+
option's colour a group beside it with its current choice as `detail`, and a group's ⋯ its sort choices a group
|
|
573
|
+
beside it with no search field, its figure toggles ticks that keep the menu open, and Hide, and the grid's own "+ Add
|
|
574
|
+
column" each hidden column a row and each field with parts a group beside it with its count as `detail`, with no
|
|
575
|
+
search field, on a phone too. The row menu and a command cell's menu always go through your `Menu`.
|
|
488
576
|
|
|
489
577
|
`@viewkitjs/views/display`, no client directive on the door (a server module may reach its string
|
|
490
578
|
formatters), every rendering file behind it carrying its own: `renderFieldValue` and `DISPLAY_CORES`
|
|
@@ -508,7 +596,8 @@ low and high, an empty box an open end), `@viewkitjs/views/editors/location` (`L
|
|
|
508
596
|
`LocationEditorHandle`: the country first, then its parts in its order, a region from its list),
|
|
509
597
|
`@viewkitjs/views/editors/value-list` (`ValueListEditor`, `ValueListEditorHandle`: several emails, phones, links or
|
|
510
598
|
domains, a row each with its label and a main mark, committed as one list of `{ value, label, main }`, the main one
|
|
511
|
-
first; `labels: false` for a host that keeps only the values
|
|
599
|
+
first; `labels: false` for a host that keeps only the values; `escapeKeeps` for a host whose session keeps on
|
|
600
|
+
Escape, `EditSession.keeps`: its rows are checked first, as on Enter),
|
|
512
601
|
`@viewkitjs/views/editors/date` (`DateEditor`, `DateEditorHandle`) and
|
|
513
602
|
`@viewkitjs/views/editors/chips` (`ChipsEditor`, `ChipsEditorHandle`). An editor owns its panel and
|
|
514
603
|
what a close means; its host owns the popover, the anchor and the write. Its words are fields'
|
|
@@ -516,8 +605,11 @@ messages, read from the provider's conventions unless the host hands `message`.
|
|
|
516
605
|
|
|
517
606
|
`@viewkitjs/views/editors/session`, opening with the client directive: `useAnchoredEditSession` and
|
|
518
607
|
`EDITOR_EXIT_MS` — the one-answer guard and the exit gap every host that opens an editor over a value
|
|
519
|
-
shares; Escape
|
|
520
|
-
|
|
608
|
+
shares; Escape discards through it unless its optional `escape` is `"keep"` (on a desktop, read once at open: the
|
|
609
|
+
editor is asked as for a press outside, and `EditSession.keeps` says so), and a refused attempt's reason comes back as
|
|
610
|
+
`refusal` (`EditSession`, `EditSessionAttempt`). `useEscapeRule(type)` and `EditEscape` come from it too: the
|
|
611
|
+
provider's `escape` for a field type, for a host to hand its session. Its own door, so a host that needs the session
|
|
612
|
+
does not load the six editors.
|
|
521
613
|
|
|
522
614
|
`@viewkitjs/views/editors/panel`, opening with the client directive: `EditorPanel`, `EditorPanelProps`
|
|
523
615
|
and `EditorSurface` — an editor opened as the components map's `Popover` on a desktop and its `Sheet`
|
|
@@ -569,12 +661,23 @@ and `ROW_NO_TEXT_SELECT`, and the types `ListSelectionConfig`, `ListBatchApi`, `
|
|
|
569
661
|
own: `GridTable` and its props `GridTableProps` (flat, as a host's binding hands them),
|
|
570
662
|
`useGridTablePrefs` (a grid's personal preferences: the host's prefs and their setter in, the props to spread onto `GridTable` out), the types
|
|
571
663
|
an app writes its props against, `GridSortState`, `GridGroupSortOption`, `GridCellCommitFn` and
|
|
572
|
-
`GridCellsCommitFn`, and `GridGroupByState`, `GridGroupFigure` and `GroupCountNoun`; and the helpers a
|
|
664
|
+
`GridCellsCommitFn`, and `GridGroupByState`, `GridGroupFigure` (a `GridDeclaredFigure` or a `GridDrawnFigure`), `GridGroupMenuPart`, `GridRowOpenedFrom` (what `onOpenRow` hands with the row) and `GroupCountNoun`; and the helpers a
|
|
573
665
|
host's binding shares with the grid: `GridCommitContext` and `GridCommitOutcome` (what a commit was and how it ended),
|
|
574
666
|
`deriveGridSelectValues` and `deriveGridRelationValues` (the values a column's filter offers),
|
|
575
667
|
`cellCopyText` and `cellEditBaseline` (a cell's copy text and the value an edit starts from, which a
|
|
576
|
-
CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The
|
|
577
|
-
|
|
668
|
+
CSV export reuses), and `GRID_TITLE_LINK_CLASS`. The house menu rows, the group collapse and the type
|
|
669
|
+
icons are the app's; the selection bar is `SelectionBar`, on the selection door, drawn with the app's verbs.
|
|
670
|
+
|
|
671
|
+
`@viewkitjs/views/panels`, not in this version (a later release publishes it, with the controls), no client
|
|
672
|
+
directive on the door, the one hook behind it (`useFilterOpened`) carrying
|
|
673
|
+
its own: what a list's panels read and say. The settings they edit (`SortConfig`, `GroupConfig`, `ToggleConfig`,
|
|
674
|
+
`LayoutConfig` and its parts, `TimeScopeConfig`, `DateRangeConfig`, `ActivePanel`, `ViewOptionInputs`,
|
|
675
|
+
`CollectionViewState`) with their predicates and `clearViewOptions`; which sections exist on a viewport
|
|
676
|
+
(`getViewOptionAvailability`, `resolvePersonalSection`); the Group panel's orders (`groupSortChoices`); and every
|
|
677
|
+
row's value (`filterValueLabel`, `relationSentence`, `sortValueLabel` and their siblings), each worded through a
|
|
678
|
+
`views.panels.*` key, the resolver taken last. The panels themselves join it as they move in. It is the one door
|
|
679
|
+
that may reach dnd-kit (`@dnd-kit/core`, `@dnd-kit/sortable`, `@dnd-kit/utilities`), the package's optional peers,
|
|
680
|
+
which a panel's list drags with: an app that takes only the grid never installs them. The panels' rows are atoms.
|
|
578
681
|
|
|
579
682
|
## Registry items
|
|
580
683
|
|
package/docs/getting-started.md
CHANGED
|
@@ -8,7 +8,7 @@ This page takes you from install to a grid of records drawn with your own primit
|
|
|
8
8
|
pnpm add @viewkitjs/views @viewkitjs/fields zod
|
|
9
9
|
```
|
|
10
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.
|
|
11
|
+
`react` and `react-dom` 19 are peer dependencies you already have, and `zod` `^4.1.12` is a peer of both packages. The dnd-kit packages are optional peers of views, for the panels' door a later release publishes; this version needs none of them. The package is ESM only and runs on Node 20 or later.
|
|
12
12
|
|
|
13
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
14
|
|
package/docs/guides/atoms.md
CHANGED
|
@@ -15,10 +15,12 @@ The components map hands the package your primitives: a button, a popover, a men
|
|
|
15
15
|
- `Tag`: a category chip in its colour, with an optional leading glyph and remove control.
|
|
16
16
|
- `CommandMenu`: a `command` cell's verbs.
|
|
17
17
|
- `RelationLink`: where a relation chip goes.
|
|
18
|
+
- `RelationRoles`: a link's roles, inside its chip after the record's name.
|
|
18
19
|
- `Loading`: a wait, the whole list reloading or more rows arriving.
|
|
19
20
|
- `LoadMore`: how a list asks for its next page.
|
|
20
21
|
- `PlatformMark`: a link's platform mark, drawn before the link.
|
|
21
22
|
- `RowMenu`: the row's right-click menu.
|
|
23
|
+
- `ChoiceRow`, `CheckRow`, `RadioRow`, `DirectionButton`, `MenuRow`, `ToggleRow` and `PanelSearch`: the rows the panels (`/panels`) draw with, a value row, a tick row, a one-of-a-set row, a sort's direction arrow, a drill-in row, a switch row and a panel's text box.
|
|
22
24
|
|
|
23
25
|
The names are `ATOM_NAMES` from `@viewkitjs/views`, and the defaults hold exactly those.
|
|
24
26
|
|
|
@@ -113,6 +115,32 @@ assert.ok(acmeChip.includes('href="/companies/c1"'));
|
|
|
113
115
|
|
|
114
116
|
`RelationLink` is your app's answer for every list. Two things come before it: a host whose own element is already the button (`slotOwnsClick`, a calendar card) gets a bare chip with no link at all, and a grid handed its own relation handler for a column opens that instead ([cells](cells.md)).
|
|
115
117
|
|
|
118
|
+
## A link's roles
|
|
119
|
+
|
|
120
|
+
On a `many` relation that declares `links`, a link may hold roles (a deal's champion, a person's Owner and Decision maker at a company). The display reads them with `relationRolesOf` and hands `RelationRoles` the `RelationValue` and its roles in order, each its stored `value` and its `label` from the field's `links.roles` (a role the field no longer declares keeps its value as its label). It draws only when the link holds one or more, inside the chip, after the name, so the `RelationLink` around the chip wraps them too. The default draws the labels in the subtle colour after a middle dot (`Bea · Champion, Decision maker`), cut before the name in a narrow cell; hovering them names the record and every role in full, since the link around the chip names only the record. Yours draws them your way.
|
|
121
|
+
|
|
122
|
+
```tsx
|
|
123
|
+
import type { ViewsRelationRolesProps } from "@viewkitjs/views/react";
|
|
124
|
+
|
|
125
|
+
function AppRelationRoles({ roles }: ViewsRelationRolesProps) {
|
|
126
|
+
return (
|
|
127
|
+
<span className="flex gap-1">
|
|
128
|
+
{roles.map((role) => (
|
|
129
|
+
<em key={role.value}>{role.label}</em>
|
|
130
|
+
))}
|
|
131
|
+
</span>
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
const roleTags = renderToStaticMarkup(
|
|
136
|
+
<AppRelationRoles
|
|
137
|
+
relation={{ id: "p1", label: "Bea", roles: ["champion"] }}
|
|
138
|
+
roles={[{ value: "champion", label: "Champion" }]}
|
|
139
|
+
/>
|
|
140
|
+
);
|
|
141
|
+
assert.ok(roleTags.includes("<em>Champion</em>"));
|
|
142
|
+
```
|
|
143
|
+
|
|
116
144
|
## A link's platform mark
|
|
117
145
|
|
|
118
146
|
A `url` value is drawn as a link, its scheme left off the label. When the link's address names a platform (LinkedIn, GitHub and the rest fields knows, plus any your conventions add with `defineConventions({ platforms })`), the display draws `PlatformMark` before it with that `LinkPlatform`: its `key` says which, its `name` what to call it. A link no platform claims is a website (`key: "website"`). The default draws nothing, so a link looks plain, and the package ships no brand art: a mark is yours to draw.
|
|
@@ -138,15 +166,15 @@ In your app the glyph is your icon component per key. The platform is read for f
|
|
|
138
166
|
|
|
139
167
|
## A command cell's verbs
|
|
140
168
|
|
|
141
|
-
A `command` field offers verbs instead of an editor: moving a deal to Lost asks for a reason, so the cell opens your verbs rather than a picker. The cell draws the trigger (the value with a chevron, or a chevron beside a value that is already a control, such as a chip or a link) and hands it to `CommandMenu` with `trigger`, `items` and `
|
|
169
|
+
A `command` field offers verbs instead of an editor: moving a deal to Lost asks for a reason, so the cell opens your verbs rather than a picker. The cell draws the trigger (the value with a chevron, or a chevron beside a value that is already a control, such as a chip or a link) and hands it to `CommandMenu` with `trigger`, `items`, `align` and `label`, the field's name. Each item has a `label`, an optional `icon`, its `onClick`, `destructive` and `disabled` flags, and a `disabledReason` for a disabled one. The default names your components map's `Menu` after the field ("Actions for Stage"), anchors it on the trigger and keeps the click off the row, so opening the verbs neither selects the cell nor opens the row. Swap it when your app has its own action menu, or a sheet on a phone. [The contract](../contract.md#a-command-field) says how a command field is declared.
|
|
142
170
|
|
|
143
171
|
## The row's menu
|
|
144
172
|
|
|
145
|
-
`RowMenu` wraps
|
|
173
|
+
`RowMenu` wraps a section's rows: the grid mounts it once around each section's rows' container, never around each row, and aims it at the row a press or a right-click came from. Its props are that row's, set in the same event your menu opens on; `children` is the rows' container, which takes the props and `ref` your trigger hands it (a `Slot`, `asChild`) and passes them to its element; a right-click on no row arrives already prevented and opens nothing. The rendering builds its `items` (the clicked cell's clipboard rows, Select, your verbs for the row), and the menu adds an Open page row before them when the row has a page (`openHref`, opened in a new tab) and a Delete row after them when the row can be deleted (`onDelete`). Its props are `ViewsRowMenuProps`; each item is a `ViewsRowMenuItem`, a rule (`{ separator: true }`) or a labelled row with its `onClick`, optional `icon`, `destructive`, `disabled` with its `disabledReason`, and a `shortcut` hint the menu draws but never binds. The default names your `Menu` "Row actions" (`views.menus.row-menu`).
|
|
146
174
|
|
|
147
175
|
The default opens your `Menu` at the pointer on a right-click, or from the row's ⋯ (`data-slot="vk-grid-row-more"`). On a touch screen a long-press opens nothing: the ⋯ is the way in there. Its Delete asks first, through the `confirm` port, with the message `views.menus.row-delete-confirm` and the row's `deleteLabel` as the `subject`; an app that hands no `confirm` gets the browser's own, and a confirm that rejects or throws counts as no. A delete that then rejects leaves the row where it was and says so through the toast port's `error`, with `views.menus.row-delete-failed`. [Ports](ports.md) covers `confirm` and the toast.
|
|
148
176
|
|
|
149
|
-
Swap it for a menu of your own, or for a long-press that selects: `onToggleSelect`,
|
|
177
|
+
Swap it for a menu of your own, or for a long-press that selects: `onToggleSelect`, there from the first render wherever rows can be selected, flips the selection of the row last pressed. The default doesn't use it. The default opens your `Menu` at the pointer, so make your `Menu` a popover: one drawn in the page flow would draw after the section's rows.
|
|
150
178
|
|
|
151
179
|
## Waits
|
|
152
180
|
|
|
@@ -224,7 +252,7 @@ Inside a command list's item, which owns the element, the highlight and the keyb
|
|
|
224
252
|
|
|
225
253
|
## Styling the defaults
|
|
226
254
|
|
|
227
|
-
The defaults mark themselves with a `data-slot` each, `vk-list`, `vk-row`, `vk-row-content`, `vk-tick`, `vk-status`, `vk-marker`, `vk-tag`, `vk-command-menu`, `vk-relation-link`, `vk-loading`, `vk-load-more`, `vk-platform` and `vk-row-menu` (`ATOM_SLOTS`), and with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked` and `data-open` (present when true), `data-status` (the status slot's name) and `data-platform` (a link's platform key). A stylesheet reaches a default through them, never through a class the package happens to use:
|
|
255
|
+
The defaults mark themselves with a `data-slot` each, `vk-list`, `vk-row`, `vk-row-content`, `vk-tick`, `vk-status`, `vk-marker`, `vk-tag`, `vk-command-menu`, `vk-relation-link`, `vk-loading`, `vk-load-more`, `vk-platform`, `vk-row-menu`, and the panels' `vk-choice-row`, `vk-check-row`, `vk-radio-row`, `vk-direction`, `vk-menu-row`, `vk-toggle-row` and `vk-panel-search` (`ATOM_SLOTS`), and with the states `data-chosen`, `data-disabled`, `data-muted`, `data-checked` and `data-open` (present when true), `data-status` (the status slot's name) and `data-platform` (a link's platform key). A stylesheet reaches a default through them, never through a class the package happens to use:
|
|
228
256
|
|
|
229
257
|
```css
|
|
230
258
|
[data-slot="vk-row"][data-open] {
|
package/docs/guides/columns.md
CHANGED
|
@@ -377,7 +377,7 @@ assert.throws(
|
|
|
377
377
|
);
|
|
378
378
|
```
|
|
379
379
|
|
|
380
|
-
The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled`). Being a function of the row, the menu follows the record's state. The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
|
|
380
|
+
The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled` and its `disabledReason`). Being a function of the row, the menu follows the record's state. The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
|
|
381
381
|
|
|
382
382
|
```ts
|
|
383
383
|
import type { FieldMenus } from "@viewkitjs/views";
|
package/docs/guides/display.md
CHANGED
|
@@ -72,7 +72,7 @@ assert.equal(DISPLAY_CORES.date, DISPLAY_CORES.datetime);
|
|
|
72
72
|
- **date** and **datetime**: in the reader's `dateStyle`, else the field's, else `short`; `withTime` from the options wins over the field's, and only an instant has a time. Hovering for a second shows the full date (and time, for an instant) through your components map's `Tooltip`, so a relative "3d ago" can be pinned to a moment. A value that doesn't parse draws as its own text.
|
|
73
73
|
- **boolean**: four looks, the field's `format.style`. `checkbox` (the default) draws the `TickBox` atom, and `icon` your `booleanIcon(on)`; either becomes a real switch only when you hand `onToggle`, and is a plain glyph otherwise. `text` draws the option's label for the value, or the package's words. `marker` draws only when true, as the `StatusMarker` atom with your `marker` words, `markerReason` and `onResolve`.
|
|
74
74
|
- **select**, **status** and **multiselect**: a select is a category and draws the `Tag` atom in its colour (a reader's `optionColors` first, then the option's declared colour, then one derived from the value). A status is a state and draws the `StatusBadge` atom in its option's slot. A multiselect draws a tag per value, through the several-values layout. A value no option names draws as the raw value, muted, with a hover saying it is not an option, unless you hand a `labelFallback`; an open (`custom-values`) vocabulary's values are their own labels. An option's `icon` is drawn through your `AppIcon`.
|
|
75
|
-
- **relation** and **user**: a chip, the record's avatar when it has one, else your `entityIcon(kind)`, else the relation glyph, then its label. Where it goes is yours (`relationWrap`); without one the chip is inert. Several draw through the several-values layout, the lead link first. A user is drawn as a relation to a member, so the two never differ.
|
|
75
|
+
- **relation** and **user**: a chip, the record's avatar when it has one, else your `entityIcon(kind)`, else the relation glyph, then its label, then, on a `many` relation that declares `links`, the link's roles, drawn by the `RelationRoles` atom ([atoms](atoms.md)). Where it goes is yours (`relationWrap`); without one the chip is inert. Several draw through the several-values layout, the lead link first. A user is drawn as a relation to a member, so the two never differ.
|
|
76
76
|
- **url**, **domain**, **email** and **phone**: a url is a link with its scheme off the label, its platform's mark before it (the [`PlatformMark` atom](atoms.md)); a value that is no safe web address draws as text. A domain links to its site and reads no platform from it. An email is a `mailto:` link. A phone is written in its international form, as its country writes it for a viewer in that country (the conventions' `region`) and internationally for anyone else, its extension after it, and dialled through a `tel:` link; a phone stored as typed draws as its text and is marked `data-as-typed`. Several values of one of these draw as the main one and a count.
|
|
77
77
|
- **location**: in a cell, its city and its country; with `wrap: "full"`, the whole place. The country is named in the viewer's language.
|
|
78
78
|
- **name**: the full name as written, else the given and family names, else `nameFallback`, else nothing.
|
package/docs/guides/editors.md
CHANGED
|
@@ -62,7 +62,7 @@ assert.equal(TEXT_INPUT_TYPE.domain, "url");
|
|
|
62
62
|
|
|
63
63
|
## What an editor owns, and what you own
|
|
64
64
|
|
|
65
|
-
An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar and decides that Escape discards and every other close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
|
|
65
|
+
An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar (or opens your app's own `DateBody` in their place, keeping the draft) and decides that Escape discards and every other close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
|
|
66
66
|
|
|
67
67
|
The two speak through one handshake, the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`:
|
|
68
68
|
|
|
@@ -76,7 +76,7 @@ What an editor never does on its own (write, fetch, toast, decide the popover) i
|
|
|
76
76
|
|
|
77
77
|
Every host that opens a panel over a value repeats two things, and both are easy to get wrong without seeing it. A close can arrive more than once (your popover reports an Escape, then the closed state it caused), and a session that answers twice writes twice. And the popover has an exit animation: answering at once re-renders the value behind it and unmounts the panel mid-animation.
|
|
78
78
|
|
|
79
|
-
`useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. Escape
|
|
79
|
+
`useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. Escape throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. Hand it `escape: "keep"` and, on a desktop, Escape keeps what was typed: the session asks the editor as it would for a press outside, so a value that would be refused stays open with its reason, and a second Escape while that refusal stands throws the edit away. Read the rule for a field's type from the provider with `useEscapeRule(type)`; the app sets it once, `<ViewsProvider escape={{ date: "keep", location: "keep" }}>`, and a type it leaves out throws the edit away. An editor that commits only on a pick (a select, a status, a single relation, a user) throws the edit away on Escape whatever the rule, and the value list checks its rows first, as on Enter (`escapeKeeps={session.keeps}`). It gives you two ways to hear the answer:
|
|
80
80
|
|
|
81
81
|
- `onAttempt(resolution)` and `onClose()`: the answer is asked synchronously, the moment the close happens, and you send the write right there. Return `{ accepted: false, reason }` to refuse it: the panel stays open, the session hands the reason back as `refusal` until the next attempt, and the next close asks again. On `{ accepted: true }` the popover closes, and `onClose` runs after the exit gap to finish the visual close. Prefer this one.
|
|
82
82
|
- `onDone(resolution)`: the whole answer, the write included, arrives after the exit gap.
|
|
@@ -275,7 +275,7 @@ A pick of Won calls `close("pick")`; the editor answers `{ kind: "commit", paylo
|
|
|
275
275
|
|
|
276
276
|
The host above draws its own popover, so on a phone it still opens a popover. `EditorPanel`, from `@viewkitjs/views/editors/panel`, opens the same editor in your `Popover` on a desktop and your `Sheet` on a phone, by the provider's `desktopQuery` (`(min-width: 1024px)` unless you hand in your own), chosen once when the session opens. It routes every dismissal to the session, so each means the same on every surface:
|
|
277
277
|
|
|
278
|
-
- **Desktop:** the popover's Escape discards. A press outside closes with `"outside"`, which the editor answers by its own rule. A focus leaving the popover with no press (a Tab out of it) closes with `"blur"`, so a host that spends the click after an outside press spends none here. Once the session has closed, a press on the popover while it plays its exit is reported to nothing.
|
|
278
|
+
- **Desktop:** the popover's Escape discards, or keeps where the session keeps. A press outside closes with `"outside"`, which the editor answers by its own rule. A focus leaving the popover with no press (a Tab out of it) closes with `"blur"`, so a host that spends the click after an outside press spends none here. Once the session has closed, a press on the popover while it plays its exit is reported to nothing.
|
|
279
279
|
- **Phone:** the sheet carries the field's name as its title, and a bar with ✕ and ✓. ✕, a swipe and the backdrop change nothing. ✓ closes as done, and a pick in a select saves on its own.
|
|
280
280
|
- **Refusals:** a value your `onAttempt` refuses with a `reason` stays open, and the reason is drawn under the editor.
|
|
281
281
|
|
package/docs/guides/ports.md
CHANGED
|
@@ -51,7 +51,7 @@ declare function openConfirmDialog(options: {
|
|
|
51
51
|
|
|
52
52
|
The grid speaks through two of them:
|
|
53
53
|
|
|
54
|
-
- **`error`** when it refuses something and says why: an edit or a clear on a cell that can't take one, a value its column can't store, the cells of a paste that could not take their value, a clear over a range with nothing clearable, a delete your app rejected (`views.menus.row-delete-failed`), and the row a person was editing leaving the list (`views.grid.row-left`).
|
|
54
|
+
- **`error`** when it refuses something and says why: an edit or a clear on a cell that can't take one, a value its column can't store, the cells of a paste that could not take their value, a clear over a range with nothing clearable, a delete your app rejected (`views.menus.row-delete-failed`), an edit your app refused when the provider's `sayRefusals` is on (`views.grid.commit-refused`, `views.grid.commit-refused-many`), and the row a person was editing leaving the list (`views.grid.row-left`).
|
|
55
55
|
- **`warning`** when a value changes that the person didn't change: a cell they had edited, saved by someone else in the meantime (`views.grid.changed-elsewhere`, or `views.grid.changed-elsewhere-cells` for several), with a second line in `description` saying the saved value is what shows.
|
|
56
56
|
|
|
57
57
|
`success` and `info` complete the shape, so one object over your toast library serves your own code too.
|