@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
|
@@ -0,0 +1,245 @@
|
|
|
1
|
+
# Atoms
|
|
2
|
+
|
|
3
|
+
The components map hands the package your primitives: a button, a popover, a menu. The atoms sit one level up. They are the small pieces the rendering is built from (a row, a tag, a status badge), and the pieces of your app it cannot draw itself (where a relation chip goes, a command cell's verbs, the row's right-click menu). Every atom ships with a default drawn from your colours, so an app that swaps nothing still gets a complete rendering. This page covers the thirteen atoms, swapping any of them, and drawing your own panels with the same rows the rendering uses.
|
|
4
|
+
|
|
5
|
+
## The thirteen and their defaults
|
|
6
|
+
|
|
7
|
+
`DEFAULT_VIEWS_ATOMS`, from `@viewkitjs/views/react`, holds one default per atom:
|
|
8
|
+
|
|
9
|
+
- `List`: the inset a run of rows sits in, inside a panel or a command list's group.
|
|
10
|
+
- `Row`: a whole row, a button or, with `interactive={false}`, a static line.
|
|
11
|
+
- `RowContent`: a row's inside, for inside a command list's item, which owns the element, the highlight and the keyboard.
|
|
12
|
+
- `TickBox`: a tick box that only paints; the control around it is yours.
|
|
13
|
+
- `StatusBadge`: a status value's dot and label, in its slot's hue.
|
|
14
|
+
- `StatusMarker`: an attention badge that opens its reason in a popover, with an optional resolve button.
|
|
15
|
+
- `Tag`: a category chip in its colour, with an optional leading glyph and remove control.
|
|
16
|
+
- `CommandMenu`: a `command` cell's verbs.
|
|
17
|
+
- `RelationLink`: where a relation chip goes.
|
|
18
|
+
- `Loading`: a wait, the whole list reloading or more rows arriving.
|
|
19
|
+
- `LoadMore`: how a list asks for its next page.
|
|
20
|
+
- `PlatformMark`: a link's platform mark, drawn before the link.
|
|
21
|
+
- `RowMenu`: the row's right-click menu.
|
|
22
|
+
|
|
23
|
+
The names are `ATOM_NAMES` from `@viewkitjs/views`, and the defaults hold exactly those.
|
|
24
|
+
|
|
25
|
+
```tsx
|
|
26
|
+
import assert from "node:assert/strict";
|
|
27
|
+
import { ATOM_NAMES } from "@viewkitjs/views";
|
|
28
|
+
import { DEFAULT_VIEWS_ATOMS, type ViewsAtoms } from "@viewkitjs/views/react";
|
|
29
|
+
|
|
30
|
+
assert.deepEqual(Object.keys(DEFAULT_VIEWS_ATOMS).sort(), [...ATOM_NAMES].sort());
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The first seven are the rendering's own look, and their defaults are usually all an app needs. The last six are where your app comes in: the package can't know where a record opens, which menu your app opens verbs in, or what a LinkedIn mark looks like. Their defaults are deliberately plain: a relation chip that goes nowhere, a command menu and a row menu on your components map's `Menu`, a ring for a wait, and no platform mark at all.
|
|
34
|
+
|
|
35
|
+
## Swapping an atom
|
|
36
|
+
|
|
37
|
+
An atom is a component typed by its props, all exported from `@viewkitjs/views/react` (`ViewsTagProps`, `ViewsRowProps` and the rest; [the React reference](../reference/react.md) lists them). Your own takes the same props and draws what your app draws. Here is a `Tag` in your app's chip classes, one per category colour:
|
|
38
|
+
|
|
39
|
+
```tsx
|
|
40
|
+
import { renderToStaticMarkup } from "react-dom/server";
|
|
41
|
+
import type { ViewsTagProps } from "@viewkitjs/views/react";
|
|
42
|
+
|
|
43
|
+
const TAG_CLASSES: Record<ViewsTagProps["color"], string> = {
|
|
44
|
+
gray: "tag tag-gray",
|
|
45
|
+
blue: "tag tag-blue",
|
|
46
|
+
green: "tag tag-green",
|
|
47
|
+
amber: "tag tag-amber",
|
|
48
|
+
red: "tag tag-red",
|
|
49
|
+
purple: "tag tag-purple",
|
|
50
|
+
pink: "tag tag-pink",
|
|
51
|
+
teal: "tag tag-teal",
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
function AppTag({ label, color, leading, onRemove, removeLabel, className }: ViewsTagProps) {
|
|
55
|
+
return (
|
|
56
|
+
<span data-slot="vk-tag" className={className ? `${TAG_CLASSES[color]} ${className}` : TAG_CLASSES[color]}>
|
|
57
|
+
{leading}
|
|
58
|
+
<span>{label}</span>
|
|
59
|
+
{onRemove ? (
|
|
60
|
+
<button
|
|
61
|
+
type="button"
|
|
62
|
+
aria-label={removeLabel ?? `Remove ${label}`}
|
|
63
|
+
onClick={(event) => {
|
|
64
|
+
// The tag sits in a row or an editor: its remove never reaches them.
|
|
65
|
+
event.stopPropagation();
|
|
66
|
+
onRemove();
|
|
67
|
+
}}
|
|
68
|
+
>
|
|
69
|
+
×
|
|
70
|
+
</button>
|
|
71
|
+
) : null}
|
|
72
|
+
</span>
|
|
73
|
+
);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const hotTag = renderToStaticMarkup(<AppTag label="Hot" color="red" />);
|
|
77
|
+
assert.ok(hotTag.includes("tag tag-red"));
|
|
78
|
+
assert.ok(hotTag.includes("Hot"));
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
`color` is one of the eight category colours fields defines; a select option's declared colour, a person's own colour for it, or the colour derived from its value reaches the tag already resolved. `leading` is an option's icon, drawn through your `AppIcon`. A swapped atom marks itself as your app does: keeping `data-slot="vk-tag"` is a choice, not a requirement.
|
|
82
|
+
|
|
83
|
+
A swapped atom may call `useViews()` like any component under the provider, to reach your components map, your icons, the package's messages or the ports. The default `Tag`, for one, takes its close glyph from your icons and its remove label from `views.editors.tag-remove`.
|
|
84
|
+
|
|
85
|
+
## Where a relation chip goes
|
|
86
|
+
|
|
87
|
+
The display draws a relation as a chip, its avatar or glyph and its label, and hands it to `RelationLink` with the `RelationValue` it stands for (`id`, `label`, and the record's `entity` kind when the value names one). The default wraps the chip in a plain span with its label as the hover, and goes nowhere: a relation is a fact as often as it is a destination. Yours decides where each kind of record opens.
|
|
88
|
+
|
|
89
|
+
```tsx
|
|
90
|
+
import { CHIP_INTERACTIVE } from "@viewkitjs/views/display";
|
|
91
|
+
import type { ViewsRelationLinkProps } from "@viewkitjs/views/react";
|
|
92
|
+
|
|
93
|
+
const RECORD_PATHS: Record<string, string> = { company: "/companies", person: "/people" };
|
|
94
|
+
|
|
95
|
+
function AppRelationLink({ relation, children }: ViewsRelationLinkProps) {
|
|
96
|
+
const base = relation.entity === undefined ? undefined : RECORD_PATHS[relation.entity];
|
|
97
|
+
// A kind with no page of its own stays a fact.
|
|
98
|
+
if (base === undefined) return <span title={relation.label}>{children}</span>;
|
|
99
|
+
return (
|
|
100
|
+
<a href={`${base}/${relation.id}`} title={relation.label} className={CHIP_INTERACTIVE}>
|
|
101
|
+
{children}
|
|
102
|
+
</a>
|
|
103
|
+
);
|
|
104
|
+
}
|
|
105
|
+
|
|
106
|
+
const acmeChip = renderToStaticMarkup(
|
|
107
|
+
<AppRelationLink relation={{ id: "c1", label: "Acme", entity: "company" }}>Acme</AppRelationLink>
|
|
108
|
+
);
|
|
109
|
+
assert.ok(acmeChip.includes('href="/companies/c1"'));
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
`CHIP_INTERACTIVE`, from `@viewkitjs/views/display`, is the chip's row made a link or a button: it keeps the surrounding text colour, so an `<a>` and a `<button>` read alike, and the label takes the brand colour and an underline on its own hover. A link or a button inside a grid row keeps its own click: the row's click rules stand aside for `a`, `button` and any element marked `data-no-nav` ([selection](selection.md)).
|
|
113
|
+
|
|
114
|
+
`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
|
+
|
|
116
|
+
## A link's platform mark
|
|
117
|
+
|
|
118
|
+
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.
|
|
119
|
+
|
|
120
|
+
```tsx
|
|
121
|
+
import type { ViewsPlatformMarkProps } from "@viewkitjs/views/react";
|
|
122
|
+
|
|
123
|
+
const PLATFORM_GLYPHS: Record<string, string> = { linkedin: "in", github: "gh", youtube: "yt" };
|
|
124
|
+
|
|
125
|
+
function AppPlatformMark({ platform, className }: ViewsPlatformMarkProps) {
|
|
126
|
+
const glyph = PLATFORM_GLYPHS[platform.key];
|
|
127
|
+
// A website, or a platform with no mark of yours: nothing, as the default.
|
|
128
|
+
if (glyph === undefined) return null;
|
|
129
|
+
return (
|
|
130
|
+
<span data-slot="vk-platform" data-platform={platform.key} title={platform.name} className={className}>
|
|
131
|
+
{glyph}
|
|
132
|
+
</span>
|
|
133
|
+
);
|
|
134
|
+
}
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
In your app the glyph is your icon component per key. The platform is read for filters whatever the mark draws.
|
|
138
|
+
|
|
139
|
+
## A command cell's verbs
|
|
140
|
+
|
|
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 `align`. Each item has a `label`, an optional `icon`, its `onClick`, and `destructive` and `disabled` flags. The default anchors your components map's `Menu` 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
|
+
|
|
143
|
+
## The row's menu
|
|
144
|
+
|
|
145
|
+
`RowMenu` wraps each grid row. 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` and a `shortcut` hint the menu draws but never binds.
|
|
146
|
+
|
|
147
|
+
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
|
+
|
|
149
|
+
Swap it for a menu of your own, or for a long-press that selects: `onToggleSelect`, present when the list can select, flips the row's selection. The default doesn't use it.
|
|
150
|
+
|
|
151
|
+
## Waits
|
|
152
|
+
|
|
153
|
+
`Loading` takes a `placement` and a `label`: `body` while the whole list reloads, `footer` while more rows arrive. The default is a ring with one turning arc, larger in the body. `LoadMore` is how a list asks for its next page: it takes `onReveal`, and an optional `label` drawn in place of the wait. The default watches a sentinel past the last row and calls `onReveal` as it comes within 600px of the viewport, drawing your `Loading` meanwhile; with no `IntersectionObserver` (a server render) it asks for nothing. Swap `LoadMore` for a button, or a different distance. [The grid guide](the-grid.md) shows the grid's `loadMore` prop that drives it.
|
|
154
|
+
|
|
155
|
+
## Handing them in
|
|
156
|
+
|
|
157
|
+
The provider's `atoms` takes any of them, each over the default of its name; the rest stay the defaults. Declare the object at module level: a new object each render re-renders every view.
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
import type { ReactNode } from "react";
|
|
161
|
+
import { defineConventions } from "@viewkitjs/fields";
|
|
162
|
+
import { NOOP_PORTS, ViewsProvider, type ViewsComponents, type ViewsIcons } from "@viewkitjs/views/react";
|
|
163
|
+
|
|
164
|
+
const atoms: Partial<ViewsAtoms> = {
|
|
165
|
+
Tag: AppTag,
|
|
166
|
+
RelationLink: AppRelationLink,
|
|
167
|
+
PlatformMark: AppPlatformMark,
|
|
168
|
+
};
|
|
169
|
+
|
|
170
|
+
// What the provider draws with: your atoms over the defaults.
|
|
171
|
+
const drawn: ViewsAtoms = { ...DEFAULT_VIEWS_ATOMS, ...atoms };
|
|
172
|
+
assert.equal(drawn.Tag, AppTag);
|
|
173
|
+
assert.equal(drawn.Row, DEFAULT_VIEWS_ATOMS.Row);
|
|
174
|
+
|
|
175
|
+
// Your adapter and icons, as getting started builds them.
|
|
176
|
+
declare const components: ViewsComponents;
|
|
177
|
+
declare const icons: ViewsIcons;
|
|
178
|
+
const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
|
|
179
|
+
|
|
180
|
+
export function AppViews({ children }: { children: ReactNode }) {
|
|
181
|
+
return (
|
|
182
|
+
<ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions} atoms={atoms}>
|
|
183
|
+
{children}
|
|
184
|
+
</ViewsProvider>
|
|
185
|
+
);
|
|
186
|
+
}
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
## Rows in your own panels
|
|
190
|
+
|
|
191
|
+
The atoms the rendering builds its menus and pickers from are yours to use too, so a panel of your own reads like the package's. Read them from `useViews().atoms`, which holds your swaps over the defaults.
|
|
192
|
+
|
|
193
|
+
A row's label truncates to one line when it is text, and is laid out in a row when it is a node (a badge, a link), so a chip sits on the row's centre; `wrap` breaks a long label instead. `size` is `compact` (13px: a command list's rows, a list of values) or `regular` (your menu size, the default). `detail` is what the row says at its right edge in the subtle colour, a setting's current choice or a live sample; a chosen row draws its detail in the brand colour instead of a check, so a column of samples stays in line. A row that opens a flyout beside its menu takes `opens` (`aria-haspopup="menu"`, and `aria-expanded` from `open`), and `open` while that flyout is up (`data-open`, and the pressed ground). `tone="muted"` is for a row that offers rather than lists: none, create, add.
|
|
194
|
+
|
|
195
|
+
```tsx
|
|
196
|
+
import { useViews } from "@viewkitjs/views/react";
|
|
197
|
+
|
|
198
|
+
const DENSITIES = ["Comfortable", "Compact"] as const;
|
|
199
|
+
type Density = (typeof DENSITIES)[number];
|
|
200
|
+
|
|
201
|
+
function DensityPicker({ current, onPick }: { current: Density; onPick: (density: Density) => void }) {
|
|
202
|
+
const { List, Row } = useViews().atoms;
|
|
203
|
+
return (
|
|
204
|
+
<List>
|
|
205
|
+
{DENSITIES.map((density) => (
|
|
206
|
+
<Row key={density} label={density} chosen={density === current} onClick={() => onPick(density)} />
|
|
207
|
+
))}
|
|
208
|
+
</List>
|
|
209
|
+
);
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
function SettingsMenu({ density, densityOpen, onOpenDensity }: { density: Density; densityOpen: boolean; onOpenDensity: () => void }) {
|
|
213
|
+
const { List, Row } = useViews().atoms;
|
|
214
|
+
return (
|
|
215
|
+
<List>
|
|
216
|
+
<Row label="Density" detail={density} opens open={densityOpen} onClick={onOpenDensity} />
|
|
217
|
+
<Row label="Row height" detail="32px" interactive={false} size="compact" />
|
|
218
|
+
</List>
|
|
219
|
+
);
|
|
220
|
+
}
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
Inside a command list's item, which owns the element, the highlight and the keyboard, draw `RowContent` rather than `Row`: it takes the same content props (`label`, `description`, `leading`, `detail`, `chosen` and the rest) and none of the button's.
|
|
224
|
+
|
|
225
|
+
## Styling the defaults
|
|
226
|
+
|
|
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:
|
|
228
|
+
|
|
229
|
+
```css
|
|
230
|
+
[data-slot="vk-row"][data-open] {
|
|
231
|
+
outline: 1px solid var(--vk-border);
|
|
232
|
+
}
|
|
233
|
+
[data-slot="vk-status"][data-status="error"] {
|
|
234
|
+
font-weight: 600;
|
|
235
|
+
}
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
Their colours are the package's `--vk-*` tokens, which [install](../install.md) maps onto your theme. [The contract](../contract.md#the-atoms) is the full list of atoms, slots and states.
|
|
239
|
+
|
|
240
|
+
## Next
|
|
241
|
+
|
|
242
|
+
- [The provider](the-provider.md): your components map, icons and words
|
|
243
|
+
- [Ports](ports.md): the toast, the confirm and the rest
|
|
244
|
+
- [The display](display.md): how a value reaches a tag, a badge or a chip
|
|
245
|
+
- [The React reference](../reference/react.md): every atom's props
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
# Cells
|
|
2
|
+
|
|
3
|
+
A cell is one column's value for one row, drawn. The grid draws its cells through `@viewkitjs/views/cells`, and so can your own surfaces: a list of cards, a phone row, a summary line. This page covers drawing a cell, drawing a row's name in your own chrome, the formatters that take a column rather than a field, the code a money cell is drawn in, and a column no registry field backs.
|
|
4
|
+
|
|
5
|
+
Every block on this page continues the one before, and the whole page runs as written.
|
|
6
|
+
|
|
7
|
+
## The columns
|
|
8
|
+
|
|
9
|
+
Cells draw columns, the same `columnFrom` columns the grid takes. Here a deal's value is in each row's own currency, read from a sibling select, so the value's binding names its `unit`; and the stage changes only through the deal's own verbs, a command field.
|
|
10
|
+
|
|
11
|
+
```tsx
|
|
12
|
+
import assert from "node:assert/strict";
|
|
13
|
+
import { defineConventions, defineFields } from "@viewkitjs/fields";
|
|
14
|
+
import { bindFields, columnFrom, type FieldRowMenuItem } from "@viewkitjs/views";
|
|
15
|
+
|
|
16
|
+
const DEAL_FIELDS = defineFields({
|
|
17
|
+
entity: "deal",
|
|
18
|
+
identity: "title",
|
|
19
|
+
fields: {
|
|
20
|
+
title: { type: "text", label: "Title", required: true },
|
|
21
|
+
currency: {
|
|
22
|
+
type: "select",
|
|
23
|
+
label: "Currency",
|
|
24
|
+
options: [
|
|
25
|
+
{ value: "EUR", label: "Euro" },
|
|
26
|
+
{ value: "RON", label: "Romanian leu" },
|
|
27
|
+
],
|
|
28
|
+
},
|
|
29
|
+
value: { type: "currency", label: "Value", code: { field: "currency" } },
|
|
30
|
+
stage: {
|
|
31
|
+
type: "status",
|
|
32
|
+
label: "Stage",
|
|
33
|
+
edit: { mutability: "command" },
|
|
34
|
+
options: [
|
|
35
|
+
{ value: "new", label: "New", slot: "pending" },
|
|
36
|
+
{ value: "won", label: "Won", slot: "success" },
|
|
37
|
+
],
|
|
38
|
+
},
|
|
39
|
+
closes_on: { type: "date", label: "Closes on", nullable: true },
|
|
40
|
+
},
|
|
41
|
+
});
|
|
42
|
+
|
|
43
|
+
type Deal = { id: string; title: string; currency: string; value: number; stage: string; closesOn: string | null };
|
|
44
|
+
|
|
45
|
+
const DEAL_BINDINGS = bindFields<Deal, typeof DEAL_FIELDS>(DEAL_FIELDS, {
|
|
46
|
+
title: { read: (deal) => deal.title },
|
|
47
|
+
currency: { read: (deal) => deal.currency },
|
|
48
|
+
value: { read: (deal) => deal.value, unit: { read: (deal) => deal.currency, options: ["EUR", "RON"] } },
|
|
49
|
+
stage: { read: (deal) => deal.stage },
|
|
50
|
+
closes_on: { read: (deal) => deal.closesOn },
|
|
51
|
+
});
|
|
52
|
+
|
|
53
|
+
const columns = {
|
|
54
|
+
title: columnFrom(DEAL_BINDINGS.title, { id: "title", width: 240 }),
|
|
55
|
+
value: columnFrom(DEAL_BINDINGS.value, { id: "value", width: 120 }),
|
|
56
|
+
stage: columnFrom(DEAL_BINDINGS.stage, { id: "stage", width: 120 }),
|
|
57
|
+
closesOn: columnFrom(DEAL_BINDINGS.closes_on, { id: "closes_on", width: 120 }),
|
|
58
|
+
};
|
|
59
|
+
|
|
60
|
+
const deals: Deal[] = [
|
|
61
|
+
{ id: "d1", title: "Acme renewal", currency: "EUR", value: 1200, stage: "won", closesOn: null },
|
|
62
|
+
{ id: "d2", title: "Globex pilot", currency: "RON", value: 5400, stage: "new", closesOn: "2026-11-14" },
|
|
63
|
+
];
|
|
64
|
+
|
|
65
|
+
assert.equal(columns.stage.command, true); // a command field's column
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
## Drawing a cell
|
|
69
|
+
|
|
70
|
+
`renderTypedCellValue(column, row, options)` reads the row's value through the column, takes the column's field, and hands both to the field display with what only the row and the reader know. It is a plain function that returns a React node; the node reads your provider where it renders, so call it inside a component below `ViewsProvider`.
|
|
71
|
+
|
|
72
|
+
What it does with a column depends on what the column is:
|
|
73
|
+
|
|
74
|
+
- An empty value draws nothing, `null`, so a card can leave the line out. A boolean draws its off state instead, which is what a person clicks to turn it on.
|
|
75
|
+
- A `title` column draws the row's title cell, the hotspot that opens the row (`data-cell-open`), with the column's `indicator` beside the name. A title whose field is a number, a percent, a currency, a date, a datetime or a name draws through that field, so a dated identity reads as a date; any other title draws as its text.
|
|
76
|
+
- A relation chip goes where your `RelationLink` atom says, the app-wide answer for each kind of record. `onOpenRelation` overrides it for one surface and is handed the chip that was pressed, which matters when a cell holds several.
|
|
77
|
+
- A `command` column handed `commandItems` opens your `CommandMenu` atom: the verbs for this row in place of an editor. The trigger is the value itself, or a chevron beside it where the value is a control of its own (a relation, a user, a link, an email, a phone or a domain). Without `commandItems` the cell is a plain value. [A command field](../contract.md#a-command-field) in the contract says where the verbs come from.
|
|
78
|
+
- Any other column draws its field's display, in the code `resolveRowCurrency` finds for a money value.
|
|
79
|
+
|
|
80
|
+
```tsx
|
|
81
|
+
import { renderIdentityValue, renderTypedCellValue } from "@viewkitjs/views/cells";
|
|
82
|
+
|
|
83
|
+
assert.equal(renderTypedCellValue(columns.closesOn, deals[0]), null); // no date, no line
|
|
84
|
+
assert.equal(renderTypedCellValue(columns.value, deals[0], { valueOverride: null }), null);
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
`valueOverride` is a value your surface holds before the row has it, such as an edit still being saved: it wins over the row's own value when it is defined.
|
|
88
|
+
|
|
89
|
+
The options, `GridCellOptions`, are all optional, and the grid fills the same ones from a person's choices:
|
|
90
|
+
|
|
91
|
+
- How it reads: `viewer` and `presentation` (both default to the provider's), `dateStyle`, `durationStyle`, `decimals`, `withTime`, `percentDisplay`, `optionColors`, and `wrap`, which lets text wrap instead of truncating.
|
|
92
|
+
- The row's answers: `currency`, `valueOverride` and `markerReason`.
|
|
93
|
+
- The verbs: `onToggle` (a two-way boolean is clickable only when it is given), `onResolve` (clears a marker), `commandItems` and `onOpenRelation`.
|
|
94
|
+
- Your host's: `entityIcon`, your glyph for a kind of record, and `slotOwnsClick`, for a host whose own element is the button (a calendar's event card): every cell inside it draws bare content, with no link, button or popover trigger of its own.
|
|
95
|
+
|
|
96
|
+
[The cells reference](../reference/cells.md) has each one.
|
|
97
|
+
|
|
98
|
+
## The row's name in your own chrome
|
|
99
|
+
|
|
100
|
+
A card draws the name as its heading, not as a title cell that opens the row. `renderIdentityValue(column, row, options)` draws the identity's value alone: a number, percent, currency, date, datetime or name through its field, anything else as its text, and `null` when it is empty.
|
|
101
|
+
|
|
102
|
+
```tsx
|
|
103
|
+
assert.equal(renderIdentityValue(columns.title, deals[0]), "Acme renewal");
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## A list of cards
|
|
107
|
+
|
|
108
|
+
The cells drawn in an app's own list. The stage's verbs are resolved for each row, as a command column's always are: the list follows the record's state.
|
|
109
|
+
|
|
110
|
+
```tsx
|
|
111
|
+
declare function markDealLost(id: string): void;
|
|
112
|
+
declare function reopenDeal(id: string): void;
|
|
113
|
+
|
|
114
|
+
function stageVerbs(deal: Deal): FieldRowMenuItem[] {
|
|
115
|
+
return deal.stage === "won"
|
|
116
|
+
? [{ label: "Reopen", onClick: () => reopenDeal(deal.id) }]
|
|
117
|
+
: [{ label: "Mark lost", onClick: () => markDealLost(deal.id), destructive: true }];
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
function DealCards({ items }: { items: Deal[] }) {
|
|
121
|
+
return (
|
|
122
|
+
<ul>
|
|
123
|
+
{items.map((deal) => (
|
|
124
|
+
<li key={deal.id}>
|
|
125
|
+
<h3>{renderIdentityValue(columns.title, deal)}</h3>
|
|
126
|
+
<p>{renderTypedCellValue(columns.stage, deal, { commandItems: stageVerbs(deal) })}</p>
|
|
127
|
+
<p>{renderTypedCellValue(columns.value, deal)}</p>
|
|
128
|
+
<p>{renderTypedCellValue(columns.closesOn, deal, { dateStyle: "long" })}</p>
|
|
129
|
+
</li>
|
|
130
|
+
))}
|
|
131
|
+
</ul>
|
|
132
|
+
);
|
|
133
|
+
}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## The column-shaped formatters
|
|
137
|
+
|
|
138
|
+
A line that is not a cell, such as a total under the cards, must still print the way the cells do. `formatNumber(value, column, options)` prints a number as the column prints its cells, and `formatDate(value, column, dateStyle, withTime, viewer)` prints a date as the column does, the two overrides winning over the column's own format. Both are plain functions that read no state; the viewer (the locale, time zone and wording) is yours to hand in. Inside a component, `useCellFormat()` reads it from the provider, with the provider's `presentation`.
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
import { formatDate, formatNumber, resolveRowCurrency, useCellFormat } from "@viewkitjs/views/cells";
|
|
142
|
+
|
|
143
|
+
function DealTotal({ items, currency }: { items: Deal[]; currency: string }) {
|
|
144
|
+
const { viewer, presentation } = useCellFormat();
|
|
145
|
+
const total = items.filter((deal) => deal.currency === currency).reduce((sum, deal) => sum + deal.value, 0);
|
|
146
|
+
return <p>{formatNumber(total, columns.value, { viewer, presentation, currency })}</p>;
|
|
147
|
+
}
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
Outside React, build the viewer from the conventions you hand the provider with `viewerFrom`, from `@viewkitjs/views/display`:
|
|
151
|
+
|
|
152
|
+
```tsx
|
|
153
|
+
import { viewerFrom } from "@viewkitjs/views/display";
|
|
154
|
+
|
|
155
|
+
const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
|
|
156
|
+
const viewer = viewerFrom(conventions);
|
|
157
|
+
|
|
158
|
+
const inLei = formatNumber(5400, columns.value, { viewer, currency: "RON" });
|
|
159
|
+
assert.ok(inLei.startsWith("RON") && inLei.endsWith("5,400.00")); // the locale puts a no-break space between
|
|
160
|
+
assert.equal(formatDate("2026-11-14", columns.closesOn, "long", undefined, viewer), "14 November 2026");
|
|
161
|
+
assert.equal(formatDate("2026-11-14", columns.closesOn, "numeric", undefined, viewer), "14/11/2026");
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## The code a money cell is drawn in
|
|
165
|
+
|
|
166
|
+
A value whose currency comes from the row has no code of its own on the column. `renderTypedCellValue` finds the row's for you; `formatNumber` is handed no row, so pass `currency` yourself, or the figure prints as euros. `resolveRowCurrency(column, row, options)` returns the options with `currency` set to the code this row's value is in: the binding's `unit` for a value in the row's own currency, or the code a column-wide currency names. It returns the options unchanged when neither gives one.
|
|
167
|
+
|
|
168
|
+
```tsx
|
|
169
|
+
assert.deepEqual(resolveRowCurrency(columns.value, deals[1]), { currency: "RON" });
|
|
170
|
+
|
|
171
|
+
const rowOptions = resolveRowCurrency(columns.value, deals[1], { decimals: 0 });
|
|
172
|
+
const rounded = formatNumber(5400, columns.value, { ...rowOptions, viewer });
|
|
173
|
+
assert.ok(rounded.startsWith("RON") && rounded.endsWith("5,400"));
|
|
174
|
+
|
|
175
|
+
// Handed no code, a column without one prints in euros.
|
|
176
|
+
assert.equal(formatNumber(5400, columns.value, { viewer }), "€5,400.00");
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
The cards, drawn:
|
|
180
|
+
|
|
181
|
+
```tsx
|
|
182
|
+
import { ICON_NAMES } from "@viewkitjs/views";
|
|
183
|
+
import { NOOP_PORTS, ViewsProvider, type ViewsComponents, type ViewsIcons } from "@viewkitjs/views/react";
|
|
184
|
+
import { renderToStaticMarkup } from "react-dom/server";
|
|
185
|
+
|
|
186
|
+
const components: ViewsComponents = {
|
|
187
|
+
Button: ({ children, onClick, disabled, type = "button", className, title }) => (
|
|
188
|
+
<button type={type} onClick={onClick} disabled={disabled} className={className} title={title}>
|
|
189
|
+
{children}
|
|
190
|
+
</button>
|
|
191
|
+
),
|
|
192
|
+
Popover: ({ open, children, className }) => (open ? <div className={className}>{children}</div> : null),
|
|
193
|
+
Tooltip: ({ children }) => children,
|
|
194
|
+
Checkbox: ({ checked, onCheckedChange, disabled }) => (
|
|
195
|
+
<input
|
|
196
|
+
type="checkbox"
|
|
197
|
+
checked={checked}
|
|
198
|
+
disabled={disabled}
|
|
199
|
+
onChange={(event) => onCheckedChange(event.target.checked, { event: event.nativeEvent })}
|
|
200
|
+
/>
|
|
201
|
+
),
|
|
202
|
+
Menu: ({ open, items }) =>
|
|
203
|
+
open ? (
|
|
204
|
+
<div role="menu">
|
|
205
|
+
{items.map((item) => (
|
|
206
|
+
<button key={item.key} type="button" role="menuitem" onClick={item.onSelect}>
|
|
207
|
+
{item.label}
|
|
208
|
+
</button>
|
|
209
|
+
))}
|
|
210
|
+
</div>
|
|
211
|
+
) : null,
|
|
212
|
+
Command: {
|
|
213
|
+
Root: ({ children, className }) => <div className={className}>{children}</div>,
|
|
214
|
+
Input: ({ value, onValueChange, placeholder, ref, onKeyDown }) => (
|
|
215
|
+
<input
|
|
216
|
+
ref={ref}
|
|
217
|
+
value={value}
|
|
218
|
+
placeholder={placeholder}
|
|
219
|
+
onChange={(event) => onValueChange(event.target.value)}
|
|
220
|
+
onKeyDown={onKeyDown}
|
|
221
|
+
/>
|
|
222
|
+
),
|
|
223
|
+
List: ({ children }) => <div role="listbox">{children}</div>,
|
|
224
|
+
Empty: ({ children }) => <div>{children}</div>,
|
|
225
|
+
Group: ({ children }) => <div>{children}</div>,
|
|
226
|
+
Item: ({ value, onSelect, chosen, children }) => (
|
|
227
|
+
<div role="option" aria-selected={chosen === true} onClick={() => onSelect(value)}>
|
|
228
|
+
{children}
|
|
229
|
+
</div>
|
|
230
|
+
),
|
|
231
|
+
},
|
|
232
|
+
Calendar: ({ value, onChange }) => (
|
|
233
|
+
<input type="date" value={value ?? ""} onChange={(event) => onChange(event.target.value)} />
|
|
234
|
+
),
|
|
235
|
+
Collapse: ({ open, children }) => (open ? <>{children}</> : null),
|
|
236
|
+
Sheet: ({ open, children }) => (open ? <div role="dialog">{children}</div> : null),
|
|
237
|
+
AppIcon: ({ name, className }) => <i data-icon={name} className={className} />,
|
|
238
|
+
Markdown: ({ source, className }) => <div className={className}>{source}</div>,
|
|
239
|
+
};
|
|
240
|
+
|
|
241
|
+
const icons = Object.fromEntries(
|
|
242
|
+
ICON_NAMES.map((name) => [name, ({ className }: { className?: string }) => <i data-icon={name} className={className} />])
|
|
243
|
+
) as ViewsIcons;
|
|
244
|
+
|
|
245
|
+
const cardsHtml = renderToStaticMarkup(
|
|
246
|
+
<ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions}>
|
|
247
|
+
<DealCards items={deals} />
|
|
248
|
+
<DealTotal items={deals} currency="RON" />
|
|
249
|
+
</ViewsProvider>
|
|
250
|
+
);
|
|
251
|
+
|
|
252
|
+
assert.ok(cardsHtml.includes("<h3>Acme renewal</h3>")); // the name as the card's heading
|
|
253
|
+
assert.ok(cardsHtml.includes('data-status="success"')); // a status wears its slot
|
|
254
|
+
assert.ok(cardsHtml.includes('aria-label="Stage"')); // the stage opens its verbs
|
|
255
|
+
assert.ok(cardsHtml.includes("€1,200.00") && cardsHtml.includes("RON")); // each row in its own code
|
|
256
|
+
assert.ok(cardsHtml.includes("14 November 2026")); // the long date the card asked for
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
## A column no registry field backs
|
|
260
|
+
|
|
261
|
+
A column you write by hand, with a `type` and an `accessor` and no field behind it, still draws through the field display: `renderTypedCellValue` reads it as a field first. `legacyFieldFromColumn(column)` is that reading, for display only. It keeps the column's type and label, and fills what a field requires that a column never had to say: a select option's label from its value, a status option's `muted` slot, a multiselect open to any value, a boolean's missing word as Yes or No, a currency's code from the column's format or `EUR`. It carries no write rule and no validation; whether the column may be edited stays the column's answer. A column with no type, or a `title` column, which is a role and not a storage type, throws `FieldDefinitionError`.
|
|
262
|
+
|
|
263
|
+
`legacyNumberLikeFormat(column)` is the column's number format as the display reads it, taken from the column's type: a currency column as `style: "currency"` with its code, a percent column as `style: "percent"`.
|
|
264
|
+
|
|
265
|
+
```tsx
|
|
266
|
+
import { FieldDefinitionError } from "@viewkitjs/fields";
|
|
267
|
+
import type { ListColumn } from "@viewkitjs/views";
|
|
268
|
+
import { legacyFieldFromColumn, legacyNumberLikeFormat } from "@viewkitjs/views/cells";
|
|
269
|
+
|
|
270
|
+
type Lead = { id: string; name: string; source: string; fee: number };
|
|
271
|
+
|
|
272
|
+
const sourceColumn: ListColumn<Lead> = {
|
|
273
|
+
id: "source",
|
|
274
|
+
header: "Source",
|
|
275
|
+
width: 120,
|
|
276
|
+
type: "select",
|
|
277
|
+
options: [{ value: "cold_call" }],
|
|
278
|
+
accessor: (lead) => lead.source,
|
|
279
|
+
};
|
|
280
|
+
const feeColumn: ListColumn<Lead> = { id: "fee", header: "Fee", width: 100, type: "currency", accessor: (lead) => lead.fee };
|
|
281
|
+
const nameColumn: ListColumn<Lead> = { id: "name", header: "Name", width: 200, type: "title", accessor: (lead) => lead.name };
|
|
282
|
+
|
|
283
|
+
assert.deepEqual(legacyFieldFromColumn(sourceColumn), {
|
|
284
|
+
key: "source",
|
|
285
|
+
label: "Source",
|
|
286
|
+
type: "select",
|
|
287
|
+
options: [{ value: "cold_call", label: "Cold Call" }],
|
|
288
|
+
});
|
|
289
|
+
assert.deepEqual(legacyNumberLikeFormat(feeColumn), { style: "currency", currency: "EUR" });
|
|
290
|
+
assert.throws(() => legacyFieldFromColumn(nameColumn), FieldDefinitionError);
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
## When to draw cells yourself
|
|
294
|
+
|
|
295
|
+
Draw cells yourself when the surface is yours and the grid is not: a list of cards, a phone row, a record's summary, a calendar event. You keep the layout, the click target and the order; the cells keep every value reading the way it reads in the grid, in the same locale, colours, slots and currency, and a relation chip going where it goes everywhere else. Where your own element is the button, as on a card that opens as a whole, pass `slotOwnsClick` so no cell nests a control inside it.
|
|
296
|
+
|
|
297
|
+
## Next
|
|
298
|
+
|
|
299
|
+
- [Editors and the edit session](editors.md): changing a value where you drew it
|
|
300
|
+
- [The contract](../contract.md): the atoms a cell draws through, `RelationLink` and `CommandMenu` among them
|
|
301
|
+
- [The cells reference](../reference/cells.md)
|
|
302
|
+
- [Getting started](../getting-started.md)
|