@viewkitjs/views 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (246) hide show
  1. package/CHANGELOG.md +196 -1
  2. package/README.md +90 -41
  3. package/dist/atoms/Row.js +1 -1
  4. package/dist/atoms/RowMenu.d.ts +1 -1
  5. package/dist/atoms/RowMenu.js +15 -4
  6. package/dist/atoms/types.d.ts +4 -4
  7. package/dist/contract.d.ts +37 -7
  8. package/dist/contract.js +24 -5
  9. package/dist/display/format.d.ts +16 -1
  10. package/dist/display/format.js +10 -1
  11. package/dist/display/index.d.ts +1 -1
  12. package/dist/display/index.js +1 -1
  13. package/dist/display/link.js +5 -3
  14. package/dist/display/location.d.ts +4 -3
  15. package/dist/display/location.js +12 -5
  16. package/dist/display/options.d.ts +1 -1
  17. package/dist/display/percent.js +10 -3
  18. package/dist/display/phone.d.ts +2 -1
  19. package/dist/display/phone.js +8 -1
  20. package/dist/display/relation.js +1 -1
  21. package/dist/editors/ChipsEditor.js +1 -1
  22. package/dist/editors/LocationEditor.js +16 -17
  23. package/dist/editors/NameEditor.js +5 -4
  24. package/dist/editors/NumberEditor.js +2 -2
  25. package/dist/editors/RangeEditor.js +2 -2
  26. package/dist/editors/ValueListEditor.d.ts +2 -2
  27. package/dist/editors/ValueListEditor.js +8 -8
  28. package/dist/editors/edit-cores.d.ts +1 -1
  29. package/dist/fields/binding.d.ts +1 -1
  30. package/dist/fields/currency.d.ts +0 -10
  31. package/dist/fields/currency.js +0 -14
  32. package/dist/fields/money.d.ts +1 -0
  33. package/dist/fields/money.js +1 -0
  34. package/dist/filters/filter-model.d.ts +0 -1
  35. package/dist/filters/registry.d.ts +3 -36
  36. package/dist/filters/registry.js +0 -38
  37. package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
  38. package/dist/grid/chrome/GridAddColumn.js +29 -0
  39. package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
  40. package/dist/grid/chrome/GridAggregateMenu.js +27 -0
  41. package/dist/grid/chrome/GridCellEditors.d.ts +64 -0
  42. package/dist/grid/chrome/GridCellEditors.js +55 -0
  43. package/dist/grid/chrome/GridCellOutline.d.ts +70 -0
  44. package/dist/grid/chrome/GridCellOutline.js +21 -0
  45. package/dist/grid/chrome/GridChipsEditor.d.ts +28 -0
  46. package/dist/grid/chrome/GridChipsEditor.js +40 -0
  47. package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
  48. package/dist/grid/chrome/GridColumnColorSection.js +40 -0
  49. package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
  50. package/dist/grid/chrome/GridColumnDateSection.js +23 -0
  51. package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
  52. package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
  53. package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
  54. package/dist/grid/chrome/GridColumnMenu.js +99 -0
  55. package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
  56. package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
  57. package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
  58. package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
  59. package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
  60. package/dist/grid/chrome/GridColumnSortSection.js +16 -0
  61. package/dist/grid/chrome/GridDateEditor.d.ts +22 -0
  62. package/dist/grid/chrome/GridDateEditor.js +31 -0
  63. package/dist/grid/chrome/GridFlyout.d.ts +44 -0
  64. package/dist/grid/chrome/GridFlyout.js +80 -0
  65. package/dist/grid/chrome/GridFooter.d.ts +23 -0
  66. package/dist/grid/chrome/GridFooter.js +81 -0
  67. package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
  68. package/dist/grid/chrome/GridGroupMenu.js +57 -0
  69. package/dist/grid/chrome/GridHeader.d.ts +61 -0
  70. package/dist/grid/chrome/GridHeader.js +37 -0
  71. package/dist/grid/chrome/GridLongTextEditor.d.ts +36 -0
  72. package/dist/grid/chrome/GridLongTextEditor.js +127 -0
  73. package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
  74. package/dist/grid/chrome/GridMenuRow.js +15 -0
  75. package/dist/grid/chrome/GridNameEditor.d.ts +19 -0
  76. package/dist/grid/chrome/GridNameEditor.js +36 -0
  77. package/dist/grid/chrome/GridNumberEditor.d.ts +35 -0
  78. package/dist/grid/chrome/GridNumberEditor.js +25 -0
  79. package/dist/grid/chrome/GridRangeEditor.d.ts +20 -0
  80. package/dist/grid/chrome/GridRangeEditor.js +25 -0
  81. package/dist/grid/chrome/GridRelationEditor.d.ts +21 -0
  82. package/dist/grid/chrome/GridRelationEditor.js +30 -0
  83. package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
  84. package/dist/grid/chrome/GridResizeHandle.js +19 -0
  85. package/dist/grid/chrome/GridRow.d.ts +25 -0
  86. package/dist/grid/chrome/GridRow.js +136 -0
  87. package/dist/grid/chrome/GridRowActions.d.ts +32 -0
  88. package/dist/grid/chrome/GridRowActions.js +25 -0
  89. package/dist/grid/chrome/GridRowCells.d.ts +4 -0
  90. package/dist/grid/chrome/GridRowCells.js +133 -0
  91. package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
  92. package/dist/grid/chrome/GridRowGlyph.js +13 -0
  93. package/dist/grid/chrome/GridSelectEditor.d.ts +18 -0
  94. package/dist/grid/chrome/GridSelectEditor.js +49 -0
  95. package/dist/grid/chrome/GridStructure.d.ts +48 -0
  96. package/dist/grid/chrome/GridStructure.js +45 -0
  97. package/dist/grid/chrome/GridTable.d.ts +4 -0
  98. package/dist/grid/chrome/GridTable.js +125 -0
  99. package/dist/grid/chrome/GridTableSurface.d.ts +15 -0
  100. package/dist/grid/chrome/GridTableSurface.js +6 -0
  101. package/dist/grid/chrome/GridTextEditor.d.ts +11 -0
  102. package/dist/grid/chrome/GridTextEditor.js +40 -0
  103. package/dist/grid/chrome/GridValueListEditor.d.ts +18 -0
  104. package/dist/grid/chrome/GridValueListEditor.js +36 -0
  105. package/dist/grid/chrome/StuckMarker.d.ts +16 -0
  106. package/dist/grid/chrome/StuckMarker.js +34 -0
  107. package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
  108. package/dist/grid/chrome/cell-clipboard.js +28 -0
  109. package/dist/grid/chrome/cells.d.ts +21 -0
  110. package/dist/grid/chrome/cells.js +20 -0
  111. package/dist/grid/chrome/checks.d.ts +35 -0
  112. package/dist/grid/chrome/checks.js +22 -0
  113. package/dist/grid/chrome/column-glyph.d.ts +14 -0
  114. package/dist/grid/chrome/column-glyph.js +44 -0
  115. package/dist/grid/chrome/editors.d.ts +9 -0
  116. package/dist/grid/chrome/editors.js +10 -0
  117. package/dist/grid/chrome/grid-cell-classes.d.ts +59 -0
  118. package/dist/grid/chrome/grid-cell-classes.js +30 -0
  119. package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
  120. package/dist/grid/chrome/grid-menu-search.js +7 -0
  121. package/dist/grid/chrome/grid-row-props.d.ts +131 -0
  122. package/dist/grid/chrome/grid-row-props.js +1 -0
  123. package/dist/grid/chrome/grid-styles.d.ts +37 -0
  124. package/dist/grid/chrome/grid-styles.js +8 -0
  125. package/dist/grid/chrome/grid-table-props.d.ts +173 -0
  126. package/dist/grid/chrome/grid-table-props.js +1 -0
  127. package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
  128. package/dist/grid/chrome/useGridBatchApi.js +35 -0
  129. package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
  130. package/dist/grid/chrome/useGridColumnLayout.js +206 -0
  131. package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
  132. package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
  133. package/dist/grid/chrome/useGridKeyboard.d.ts +47 -0
  134. package/dist/grid/chrome/useGridKeyboard.js +274 -0
  135. package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
  136. package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
  137. package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
  138. package/dist/grid/chrome/useGridRailReveal.js +67 -0
  139. package/dist/grid/chrome/useGridRangeActions.d.ts +49 -0
  140. package/dist/grid/chrome/useGridRangeActions.js +188 -0
  141. package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
  142. package/dist/grid/chrome/useGridRangeGestures.js +190 -0
  143. package/dist/grid/chrome/useGridRowContextMenu.d.ts +35 -0
  144. package/dist/grid/chrome/useGridRowContextMenu.js +127 -0
  145. package/dist/grid/chrome/useGridScaleStyles.d.ts +1 -0
  146. package/dist/grid/chrome/useGridScaleStyles.js +29 -0
  147. package/dist/grid/chrome/useGridScrollSync.d.ts +38 -0
  148. package/dist/grid/chrome/useGridScrollSync.js +176 -0
  149. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +55 -0
  150. package/dist/grid/chrome/useGridTableInteractionModel.js +197 -0
  151. package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
  152. package/dist/grid/chrome/useGridTableSelection.js +55 -0
  153. package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
  154. package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
  155. package/dist/grid/core/clipboard-model.d.ts +81 -0
  156. package/dist/grid/core/clipboard-model.js +291 -0
  157. package/dist/grid/core/column-values.d.ts +27 -0
  158. package/dist/grid/core/column-values.js +76 -0
  159. package/dist/grid/core/commit-model.d.ts +34 -0
  160. package/dist/grid/core/commit-model.js +3 -0
  161. package/dist/grid/core/coordinates.d.ts +48 -0
  162. package/dist/grid/core/coordinates.js +27 -0
  163. package/dist/grid/core/edit-values.d.ts +9 -0
  164. package/dist/grid/core/edit-values.js +1 -0
  165. package/dist/grid/core/editing-controller.d.ts +59 -0
  166. package/dist/grid/core/editing-controller.js +240 -0
  167. package/dist/grid/core/editing-model.d.ts +78 -0
  168. package/dist/grid/core/editing-model.js +136 -0
  169. package/dist/grid/core/grid-scale.d.ts +14 -0
  170. package/dist/grid/core/grid-scale.js +8 -0
  171. package/dist/grid/core/nav.d.ts +94 -0
  172. package/dist/grid/core/nav.js +92 -0
  173. package/dist/grid/core/pending-reconciliation.d.ts +50 -0
  174. package/dist/grid/core/pending-reconciliation.js +49 -0
  175. package/dist/grid/core/range-model.d.ts +25 -0
  176. package/dist/grid/core/range-model.js +59 -0
  177. package/dist/grid/core/spreadsheet-operations.d.ts +85 -0
  178. package/dist/grid/core/spreadsheet-operations.js +253 -0
  179. package/dist/grid/core/useGridEditing.d.ts +43 -0
  180. package/dist/grid/core/useGridEditing.js +90 -0
  181. package/dist/grid/core/useGridRange.d.ts +20 -0
  182. package/dist/grid/core/useGridRange.js +24 -0
  183. package/dist/grid/core/value-equality.d.ts +32 -0
  184. package/dist/grid/core/value-equality.js +34 -0
  185. package/dist/grid/index.d.ts +18 -0
  186. package/dist/grid/index.js +5 -0
  187. package/dist/grid/useGridTablePrefs.d.ts +50 -0
  188. package/dist/grid/useGridTablePrefs.js +101 -0
  189. package/dist/index.d.ts +0 -1
  190. package/dist/index.js +0 -1
  191. package/dist/internal/viewport.d.ts +5 -0
  192. package/dist/internal/viewport.js +29 -0
  193. package/dist/model/column-capabilities.d.ts +2 -2
  194. package/dist/model/column-state.d.ts +1 -1
  195. package/dist/model/density.js +3 -3
  196. package/dist/model/filter-capabilities.d.ts +1 -1
  197. package/dist/model/filter-capabilities.js +1 -1
  198. package/dist/model/index.d.ts +4 -6
  199. package/dist/model/index.js +0 -1
  200. package/dist/model/preferences.d.ts +7 -3
  201. package/dist/provider/ViewsProvider.d.ts +1 -1
  202. package/dist/provider/ViewsProvider.js +5 -1
  203. package/dist/provider/components.d.ts +16 -8
  204. package/dist/provider/context.d.ts +3 -2
  205. package/dist/provider/menu-groups.d.ts +8 -0
  206. package/dist/provider/menu-groups.js +38 -0
  207. package/dist/provider/ports.d.ts +22 -0
  208. package/dist/provider/ports.js +1 -0
  209. package/dist/react.d.ts +1 -1
  210. package/docs/contract.md +128 -56
  211. package/docs/getting-started.md +250 -0
  212. package/docs/guides/atoms.md +245 -0
  213. package/docs/guides/cells.md +302 -0
  214. package/docs/guides/columns.md +412 -0
  215. package/docs/guides/display.md +203 -0
  216. package/docs/guides/editors.md +404 -0
  217. package/docs/guides/ports.md +246 -0
  218. package/docs/guides/selection.md +270 -0
  219. package/docs/guides/the-grid.md +677 -0
  220. package/docs/guides/the-provider.md +446 -0
  221. package/docs/index.md +50 -0
  222. package/docs/install.md +9 -47
  223. package/docs/reference/cells.md +28 -0
  224. package/docs/reference/display.md +42 -0
  225. package/docs/reference/editors-chips.md +6 -0
  226. package/docs/reference/editors-date.md +6 -0
  227. package/docs/reference/editors-location.md +10 -0
  228. package/docs/reference/editors-name.md +6 -0
  229. package/docs/reference/editors-number.md +11 -0
  230. package/docs/reference/editors-open-values.md +9 -0
  231. package/docs/reference/editors-range.md +6 -0
  232. package/docs/reference/editors-relation.md +9 -0
  233. package/docs/reference/editors-select.md +8 -0
  234. package/docs/reference/editors-session.md +9 -0
  235. package/docs/reference/editors-value-list.md +6 -0
  236. package/docs/reference/editors.md +5 -0
  237. package/docs/reference/grid.md +39 -0
  238. package/docs/reference/react.md +86 -0
  239. package/docs/reference/selection.md +33 -0
  240. package/docs/reference/views.md +601 -0
  241. package/package.json +7 -3
  242. package/skills/views/SKILL.md +20 -5
  243. package/dist/filters/types.d.ts +0 -27
  244. package/dist/filters/types.js +0 -1
  245. package/dist/model/filter-pushdown.d.ts +0 -106
  246. package/dist/model/filter-pushdown.js +0 -147
@@ -0,0 +1,446 @@
1
+ # The provider
2
+
3
+ Every view reads what it takes from its app, other than its own props, from one `ViewsProvider` above it: your field conventions, your primitives, your icons, your services, your wording and how your numbers read. This page covers mounting it, writing the adapter that hands it your primitives, mapping your icons by meaning, wording the package's messages in your language, and changing how values print.
4
+
5
+ ## Mount it once
6
+
7
+ `ViewsProvider` sits once at your app's client root, above every view. It takes four things and the children: `components` (your primitives), `icons` (your glyphs by meaning), `ports` (your toast, haptics, clipboard, per-device store and, optionally, a confirm dialog; [ports](ports.md)) and `conventions`. Three more are optional: `atoms`, `messages` and `presentation`.
8
+
9
+ Each piece lives in a module of its own, which the sections below write. Here they are declared, so the page compiles without them.
10
+
11
+ ```tsx
12
+ import assert from "node:assert/strict";
13
+ import type { ReactNode } from "react";
14
+ import { defineConventions } from "@viewkitjs/fields";
15
+ import { ViewsProvider, type ViewsComponents, type ViewsIcons, type ViewsPorts } from "@viewkitjs/views/react";
16
+
17
+ declare const viewsComponents: ViewsComponents; // your adapter: "The components map" below
18
+ declare const viewsIcons: ViewsIcons; // your icon library, by meaning
19
+ declare const viewsPorts: ViewsPorts; // your services: the ports guide
20
+
21
+ const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
22
+
23
+ export function AppViews({ children }: { children: ReactNode }) {
24
+ return (
25
+ <ViewsProvider components={viewsComponents} icons={viewsIcons} ports={viewsPorts} conventions={conventions}>
26
+ {children}
27
+ </ViewsProvider>
28
+ );
29
+ }
30
+ ```
31
+
32
+ The provider hands its views one value for each distinct set of inputs, so pass objects that live as long as the app: a components map, an icons map or an atoms object built anew on each render re-renders every view.
33
+
34
+ ## Conventions
35
+
36
+ `conventions` is the same `FieldConventions` object you hand `@viewkitjs/fields`. Every value a view draws reads through it: numbers, dates and durations in its `locale`, instants in its `timeZone`, a phone of its `region` written as at home. Fields' own words, such as how long ago something was, resolve through its `messages`; only the strings the views package owns go through the provider's `messages` (below).
37
+
38
+ A request that carries its own locale adds it with `with`, which returns a new object and keeps everything it doesn't name:
39
+
40
+ ```tsx
41
+ const romanian = conventions.with({ locale: "ro-RO" });
42
+
43
+ assert.equal(romanian.locale, "ro-RO");
44
+ assert.equal(romanian.timeZone, "Europe/Bucharest"); // kept
45
+ assert.equal(conventions.locale, "en-GB"); // the app's own, untouched
46
+ ```
47
+
48
+ ## The components map
49
+
50
+ The package draws nothing with a UI library of its own. `ViewsComponents`, from `@viewkitjs/views/react`, is the map you hand it: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. The [contract](../contract.md#the-components-map) says what each slot must accept; the [`@viewkitjs/views/react` reference](../reference/react.md) lists every prop.
51
+
52
+ The shapes are Base UI's, and the types promise three things:
53
+
54
+ - **A controlled `open`, with `onOpenChange(open, details)`.** The package decides when a popover, a menu or a sheet is open. `details.reason` says why it closed, by Base UI's names: `trigger-press`, `outside-press`, `escape-key`, `focus-out`, `item-press`, `close-press` or `swipe`, and `none` for any other.
55
+ - **An `anchor`, not a trigger child.** The popover and the menu open at an element, a ref to one, or a point (a right-click). Nothing is wrapped.
56
+ - **No `asChild`.** The tooltip is the one slot that wraps, and it takes the element it wraps as `children`.
57
+
58
+ So an app on Base UI wraps its own copies thinly, and an app on Radix maps the difference in its adapter. The package ships none of these primitives and depends on neither library.
59
+
60
+ ### An adapter over Radix
61
+
62
+ Radix opens a popover from a trigger and reports no close reasons. The adapter answers both. It hands Radix's `Anchor` a virtual ref, an object whose `getBoundingClientRect` measures the package's anchor, whichever of the three it is. It records the reason in the handler Radix calls just before it closes. And it turns the package's two vetoes, `onOutsidePress` and `onEscape`, into `preventDefault` on the event Radix hands that handler.
63
+
64
+ Your Radix popover copy is declared here, by the parts and props Radix gives it.
65
+
66
+ ```tsx
67
+ import {
68
+ Fragment,
69
+ useMemo,
70
+ useRef,
71
+ type ComponentPropsWithoutRef,
72
+ type ComponentType,
73
+ type RefObject,
74
+ } from "react";
75
+ import type {
76
+ ViewsAlign,
77
+ ViewsAnchor,
78
+ ViewsCloseReason,
79
+ ViewsMenuItem,
80
+ ViewsPopoverProps,
81
+ ViewsSide,
82
+ } from "@viewkitjs/views/react";
83
+
84
+ type Measurable = { getBoundingClientRect(): DOMRect };
85
+
86
+ declare const RadixPopover: {
87
+ Root: ComponentType<{ open: boolean; onOpenChange: (open: boolean) => void; children: ReactNode }>;
88
+ Anchor: ComponentType<{ virtualRef: RefObject<Measurable> }>;
89
+ Portal: ComponentType<{ children: ReactNode }>;
90
+ Content: ComponentType<
91
+ ComponentPropsWithoutRef<"div"> & {
92
+ side?: ViewsSide;
93
+ align?: ViewsAlign;
94
+ sideOffset?: number;
95
+ alignOffset?: number;
96
+ onOpenAutoFocus?: (event: Event) => void;
97
+ onEscapeKeyDown?: (event: KeyboardEvent) => void;
98
+ onPointerDownOutside?: (event: CustomEvent<{ originalEvent: PointerEvent }>) => void;
99
+ onFocusOutside?: (event: CustomEvent<{ originalEvent: FocusEvent }>) => void;
100
+ }
101
+ >;
102
+ };
103
+
104
+ // Your menu panel's classes, laid over the card popover when the package asks for `chrome: "menu"`.
105
+ const MENU_SURFACE = "w-auto p-0";
106
+
107
+ function measurable(anchor: NonNullable<ViewsAnchor>): Measurable {
108
+ if ("current" in anchor) {
109
+ // A ref: read when Radix measures, by which time the element is there.
110
+ const ref = anchor;
111
+ return { getBoundingClientRect: () => ref.current?.getBoundingClientRect() ?? new DOMRect() };
112
+ }
113
+ if ("getBoundingClientRect" in anchor) return anchor; // an element
114
+ const { x, y } = anchor; // a point: a right-click
115
+ return { getBoundingClientRect: () => new DOMRect(x, y, 0, 0) };
116
+ }
117
+
118
+ export function Popover({
119
+ open,
120
+ onOpenChange,
121
+ anchor,
122
+ side,
123
+ align,
124
+ sideOffset,
125
+ alignOffset,
126
+ initialFocus = true,
127
+ onOutsidePress,
128
+ onEscape,
129
+ chrome = "panel",
130
+ onPanelClick,
131
+ panelData,
132
+ style,
133
+ className,
134
+ children,
135
+ }: ViewsPopoverProps) {
136
+ const reason = useRef<ViewsCloseReason>("none");
137
+ const pressVetoed = useRef(false);
138
+ const virtualRef = useMemo(() => (anchor === null ? null : { current: measurable(anchor) }), [anchor]);
139
+
140
+ return (
141
+ <RadixPopover.Root
142
+ open={open}
143
+ onOpenChange={(next) => {
144
+ onOpenChange(next, { reason: reason.current });
145
+ reason.current = "none";
146
+ }}
147
+ >
148
+ {virtualRef && <RadixPopover.Anchor virtualRef={virtualRef} />}
149
+ <RadixPopover.Portal>
150
+ <RadixPopover.Content
151
+ side={side}
152
+ align={align}
153
+ sideOffset={sideOffset}
154
+ alignOffset={alignOffset}
155
+ onOpenAutoFocus={(event) => {
156
+ if (!initialFocus) event.preventDefault();
157
+ }}
158
+ onEscapeKeyDown={(event) => {
159
+ if (onEscape?.(event) === false) event.preventDefault();
160
+ else reason.current = "escape-key";
161
+ }}
162
+ onPointerDownOutside={(event) => {
163
+ pressVetoed.current = onOutsidePress?.(event.detail.originalEvent) === false;
164
+ if (pressVetoed.current) event.preventDefault();
165
+ else reason.current = "outside-press";
166
+ }}
167
+ onFocusOutside={(event) => {
168
+ // The focus a vetoed press moves is refused with it; a Tab out closes.
169
+ if (pressVetoed.current) event.preventDefault();
170
+ else reason.current = "focus-out";
171
+ pressVetoed.current = false;
172
+ }}
173
+ onClick={onPanelClick}
174
+ style={style}
175
+ className={chrome === "menu" ? `${MENU_SURFACE} ${className ?? ""}` : className}
176
+ {...panelData}
177
+ >
178
+ {children}
179
+ </RadixPopover.Content>
180
+ </RadixPopover.Portal>
181
+ </RadixPopover.Root>
182
+ );
183
+ }
184
+ ```
185
+
186
+ `panelData` lands on the popup element itself, so the package's own selectors find it, and `onPanelClick` stops a click inside the popup there: a popup is a portal, so without it the click bubbles through React to the row the popover opened from.
187
+
188
+ ### An adapter over Base UI
189
+
190
+ Base UI already speaks the map's shapes: its root's `onOpenChange` hands a reason, and its positioner takes an anchor. The adapter is mostly a pass-through. The one translation is the reason: Base UI has more of them than the contract names, and every reason the contract doesn't name is `none`.
191
+
192
+ ```tsx
193
+ const CLOSE_REASONS: readonly ViewsCloseReason[] = [
194
+ "trigger-press",
195
+ "outside-press",
196
+ "escape-key",
197
+ "focus-out",
198
+ "item-press",
199
+ "close-press",
200
+ "swipe",
201
+ ];
202
+
203
+ function closeReason(reason: string): ViewsCloseReason {
204
+ return CLOSE_REASONS.find((known) => known === reason) ?? "none";
205
+ }
206
+
207
+ assert.equal(closeReason("escape-key"), "escape-key");
208
+ assert.equal(closeReason("trigger-hover"), "none"); // a reason the contract doesn't name
209
+ ```
210
+
211
+ The menu is built from Base UI's root, positioner and popup, the anchor handed to the positioner. It has no trigger, because the package opens it, and no flyouts: a row with `children` is a group, its rows drawn in place under its label. Your Base UI menu copy is declared here.
212
+
213
+ ```tsx
214
+ type BaseAnchor = Element | RefObject<Element | null> | Measurable | null;
215
+
216
+ declare const BaseMenu: {
217
+ Root: ComponentType<{
218
+ open: boolean;
219
+ onOpenChange: (open: boolean, details: { reason: string }) => void;
220
+ children: ReactNode;
221
+ }>;
222
+ Portal: ComponentType<{ children: ReactNode }>;
223
+ Positioner: ComponentType<{ anchor: BaseAnchor; side?: ViewsSide; align?: ViewsAlign; children: ReactNode }>;
224
+ Popup: ComponentType<{ className?: string; children: ReactNode }>;
225
+ Group: ComponentType<{ children: ReactNode }>;
226
+ GroupLabel: ComponentType<{ children: ReactNode }>;
227
+ Item: ComponentType<{ disabled?: boolean; onClick?: () => void; children: ReactNode }>;
228
+ Separator: ComponentType;
229
+ };
230
+
231
+ function positionerAnchor(anchor: ViewsAnchor): BaseAnchor {
232
+ if (anchor === null) return null;
233
+ if ("x" in anchor) {
234
+ const { x, y } = anchor;
235
+ return { getBoundingClientRect: () => new DOMRect(x, y, 0, 0) };
236
+ }
237
+ return anchor;
238
+ }
239
+
240
+ function MenuRows({ items }: { items: ViewsMenuItem[] }) {
241
+ return (
242
+ <>
243
+ {items.map((item) => (
244
+ <Fragment key={item.key}>
245
+ {item.separatorBefore && <BaseMenu.Separator />}
246
+ {item.children ? (
247
+ <BaseMenu.Group>
248
+ <BaseMenu.GroupLabel>{item.label}</BaseMenu.GroupLabel>
249
+ <MenuRows items={item.children} />
250
+ </BaseMenu.Group>
251
+ ) : (
252
+ <BaseMenu.Item
253
+ disabled={item.disabled}
254
+ onClick={item.onSelect}
255
+ data-destructive={item.destructive || undefined}
256
+ data-checked={item.checked || undefined}
257
+ >
258
+ {item.icon}
259
+ {item.href ? <a href={item.href}>{item.label}</a> : item.label}
260
+ {item.shortcut && <kbd>{item.shortcut}</kbd>}
261
+ </BaseMenu.Item>
262
+ )}
263
+ </Fragment>
264
+ ))}
265
+ </>
266
+ );
267
+ }
268
+
269
+ export const Menu: ViewsComponents["Menu"] = ({ open, onOpenChange, anchor, items, side, align, className }) => (
270
+ <BaseMenu.Root open={open} onOpenChange={(next, details) => onOpenChange(next, { reason: closeReason(details.reason) })}>
271
+ <BaseMenu.Portal>
272
+ <BaseMenu.Positioner anchor={positionerAnchor(anchor)} side={side} align={align}>
273
+ <BaseMenu.Popup className={className}>
274
+ <MenuRows items={items} />
275
+ </BaseMenu.Popup>
276
+ </BaseMenu.Positioner>
277
+ </BaseMenu.Portal>
278
+ </BaseMenu.Root>
279
+ );
280
+ ```
281
+
282
+ A disabled group needs nothing from you: the provider wraps your `Menu` and hands it the rows under a disabled group already `disabled`, at every depth, so each row is drawn by its own flag. A `checked` row is drawn with your tick (here a `data-checked` your styles read) and closes the menu like any other row; a `shortcut` is a hint drawn at the row's end, never a key the menu binds.
283
+
284
+ Each piece goes into your map under its name, in a module of its own, so the map is one object for the app's life.
285
+
286
+ ### Where a copy stops short
287
+
288
+ The rest of the map is your copies, handed through. A few slots ask for something a stock copy may not have:
289
+
290
+ - **The popover's `chrome: "menu"`** is your menu panel's surface: no inset, because the list inside carries its own, and no card width, because it is as wide as its list. Where your copy has only the card popover, lay your menu classes over it, as the Radix adapter does.
291
+ - **The popover's `initialFocus={false}`** keeps focus where it was when the popup opens. The editor inside focuses its own input without scrolling, so your popup may place itself however it likes.
292
+ - **The press veto.** Where your popover closes on the focus an outside press moves, before the press's own event reaches it, keep the last press and ask `onOutsidePress` with it; when the veto refuses, refuse that focus-out too. A Tab out closes without asking.
293
+ - **The command item's `chosen`.** Colour the item as your chosen row; the package's row inside draws the check. Where your copy's item draws a tick of its own, hide it.
294
+ - **The command input's `chrome: "bare"`** is the input alone, without the search row's glyph and divider. Where your copy has only the search row, reach the command library's own input.
295
+ - **The sheet's `snap`** (`full`, `half`, `peek`, `auto`) is a hint: map it onto your drawer's snap points, or ignore it.
296
+ - **The calendar's `locale`** is the conventions' locale, for its month and weekday names and the day its week starts. Your calendar may keep its own.
297
+ - **`AppIcon`** is your own icon component by your own names, for the glyphs a host declares (a row's icon, a binding's icon). Rows are measured as they mount, so it must draw on the first paint: map the names from a static record, never icons loaded on demand.
298
+ - **`Markdown`** is your markdown renderer, handed the stored text whole as `source`. The package parses no markdown.
299
+ - **Stacking.** The package sets no stacking order. Your popups sit above your own modals and drawers, and a popup opened later sits above the one it opened from; a positioner your copy holds at a lower layer leaves the popup under a modal.
300
+ - **Tooltips.** Mount one tooltip provider above the views; a tooltip never mounts its own.
301
+
302
+ The contract's [Writing an adapter](../contract.md#writing-an-adapter) holds the same points as a checklist.
303
+
304
+ ## Icons by meaning
305
+
306
+ The rendering asks for its glyphs by what they mean (`sortAsc`, `relation`, `more`, `warning`), never by a library's name. `ICON_NAMES`, from `@viewkitjs/views`, lists them all, and `ViewsIcons` is a record with one component per name, each taking a `className`. Because it is a full record, a meaning the contract adds fails your compile until you map it.
307
+
308
+ Most libraries name many of these the same way; spell out the ones yours names differently.
309
+
310
+ ```tsx
311
+ import { ICON_NAMES, type ViewsIconName } from "@viewkitjs/views";
312
+ import type { ViewsIconProps } from "@viewkitjs/views/react";
313
+
314
+ // Your icon library: one component that draws a glyph by its own name. Declared here.
315
+ declare const Glyph: ComponentType<{ name: string; className?: string }>;
316
+
317
+ const GLYPH_OF: Partial<Record<ViewsIconName, string>> = {
318
+ longText: "align-left",
319
+ sortAsc: "arrow-up",
320
+ sortDesc: "arrow-down",
321
+ more: "ellipsis",
322
+ selectRow: "square-check",
323
+ chevronDown: "chevron-down",
324
+ chevronRight: "chevron-right",
325
+ };
326
+
327
+ export const icons = Object.fromEntries(
328
+ ICON_NAMES.map((name) => {
329
+ const glyph = GLYPH_OF[name] ?? name;
330
+ const Icon = ({ className }: ViewsIconProps) => <Glyph name={glyph} className={className} />;
331
+ return [name, Icon];
332
+ })
333
+ ) as ViewsIcons;
334
+
335
+ assert.equal(Object.keys(icons).length, ICON_NAMES.length);
336
+ assert.ok(ICON_NAMES.includes("sortAsc") && ICON_NAMES.includes("relation"));
337
+ ```
338
+
339
+ These are the package's glyphs. The ones a host names itself, a row's icon or a binding's, go through `AppIcon` in the components map.
340
+
341
+ ## Messages
342
+
343
+ The package words only its own strings. They are a closed list of messages, each a `key` under `views.grid.*`, `views.editors.*`, `views.menus.*` or `views.display.*` and, where the sentence carries something, its `values`: `{ key: "views.menus.group-by", values: { field: "Stage" } }`. The [contract](../contract.md#message-keys) lists every key with its English. A string `@viewkitjs/fields` already keys stays a fields message, worded through the conventions.
344
+
345
+ `messages` is a `ViewsMessageResolver`, a function from a `ViewsMessage` to its text. It defaults to `resolveViewsMessage`, the package's English. The provider doesn't fall back for you: a resolver that words only some keys calls `resolveViewsMessage` for the rest.
346
+
347
+ With next-intl, scope the translator to a `views` namespace in your catalog and read each key without its `views.` prefix. A translator over the root of a typed catalog can overflow TypeScript, hence the namespace.
348
+
349
+ ```tsx
350
+ import { resolveViewsMessage, type ViewsMessage, type ViewsMessageResolver } from "@viewkitjs/views";
351
+
352
+ // What next-intl's `useTranslations("views")` returns, as far as the resolver needs it.
353
+ type ViewsTranslator = {
354
+ has(key: string): boolean;
355
+ (key: string, values?: Record<string, string | number>): string;
356
+ };
357
+
358
+ function messagesFrom(t: ViewsTranslator): ViewsMessageResolver {
359
+ return (message: ViewsMessage) => {
360
+ const key = message.key.slice("views.".length);
361
+ return t.has(key) ? t(key, "values" in message ? message.values : undefined) : resolveViewsMessage(message);
362
+ };
363
+ }
364
+ ```
365
+
366
+ A small catalog shows what it does: a key the catalog words reads in its language, with its values in place, and a key it leaves out reads in the package's English.
367
+
368
+ ```tsx
369
+ const ROMANIAN: Record<string, string> = {
370
+ "menus.sort-asc": "Sortează crescător",
371
+ "menus.group-by": "Grupează după {field}",
372
+ };
373
+ const romanianT: ViewsTranslator = Object.assign(
374
+ (key: string, values?: Record<string, string | number>) =>
375
+ ROMANIAN[key].replace(/\{(\w+)\}/g, (_match, name: string) => String(values?.[name] ?? "")),
376
+ { has: (key: string) => key in ROMANIAN }
377
+ );
378
+ const romanianMessages = messagesFrom(romanianT);
379
+
380
+ assert.equal(romanianMessages({ key: "views.menus.sort-asc" }), "Sortează crescător");
381
+ assert.equal(romanianMessages({ key: "views.menus.group-by", values: { field: "Etapă" } }), "Grupează după Etapă");
382
+ assert.equal(romanianMessages({ key: "views.menus.sort-desc" }), "Sort descending"); // not in the catalog
383
+ ```
384
+
385
+ In the app, the resolver is built where the translator is, and kept while the translator is the same, so the provider's value holds still:
386
+
387
+ ```tsx
388
+ declare function useTranslations(namespace: "views"): ViewsTranslator; // next-intl's
389
+
390
+ export function TranslatedViews({ children }: { children: ReactNode }) {
391
+ const t = useTranslations("views");
392
+ const messages = useMemo(() => messagesFrom(t), [t]);
393
+ return (
394
+ <ViewsProvider
395
+ components={viewsComponents}
396
+ icons={viewsIcons}
397
+ ports={viewsPorts}
398
+ conventions={conventions}
399
+ messages={messages}
400
+ >
401
+ {children}
402
+ </ViewsProvider>
403
+ );
404
+ }
405
+ ```
406
+
407
+ A resolver written as a `switch` on `message.key` with no `default` is exhaustive: when the list gains a key, it fails to compile until you word it.
408
+
409
+ ## Presentation
410
+
411
+ Numbers, dates and durations read in the conventions' locale by default. To print them your own way, hand `presentation`: a function that takes the package's defaults, a `FieldPresentation`, and returns yours. A `FieldPresentation` holds one formatter each for a number, a duration, a calendar day, an instant and the two relative forms, plus fields' message resolver. Replace the ones you want and spread the rest.
412
+
413
+ Import only the `FieldPresentation` type. The provider calls your function where a value is drawn, handing it the defaults, so the module that mounts the provider pulls in none of the display.
414
+
415
+ ```tsx
416
+ import type { FieldPresentation } from "@viewkitjs/views/display";
417
+
418
+ // A duration that neither its field nor the person gave a style reads as a clock: 2:30.
419
+ export const presentation = (defaults: FieldPresentation): FieldPresentation => ({
420
+ ...defaults,
421
+ duration: (input) => defaults.duration({ ...input, style: input.style ?? "clock" }),
422
+ });
423
+ ```
424
+
425
+ Hand it as `presentation={presentation}`, a function that lives as long as the app. Here it is called with the package's defaults by hand, to show what it does:
426
+
427
+ ```tsx
428
+ import { DEFAULT_FIELD_PRESENTATION } from "@viewkitjs/views/display";
429
+
430
+ const printed = presentation(DEFAULT_FIELD_PRESENTATION);
431
+ const viewer = { locale: "en-GB", now: new Date() };
432
+
433
+ assert.equal(printed.duration({ milliseconds: 150_000, context: viewer }), "2:30");
434
+ assert.equal(printed.duration({ milliseconds: 150_000, style: "units", context: viewer }), "2m 30s"); // a chosen style wins
435
+ ```
436
+
437
+ ## Atoms
438
+
439
+ The rows, tick boxes, badges, tags, menus and waits every view is built from ship as defaults drawn from your theme; swap any of them through `atoms`, a module-level object such as `atoms={{ Tag: MyTag }}`. [Atoms](atoms.md) covers each.
440
+
441
+ ## Next
442
+
443
+ - [Ports](ports.md): your toast, haptics, clipboard, per-device store and confirm dialog
444
+ - [Atoms](atoms.md): the pieces every view is built from, and swapping them for your own
445
+ - [The display](display.md): one renderer per field type, and the string formatters
446
+ - [The rendering contract](../contract.md): every slot, state, token, component, port, icon and message key
package/docs/index.md ADDED
@@ -0,0 +1,50 @@
1
+ # ViewKit views — documentation
2
+
3
+ `@viewkitjs/views` draws and edits the values `@viewkitjs/fields` defines: the display, the editors, cells, selection and the grid. It ships no UI library of its own. Your app hands in its primitives through a components map, its icons by meaning, its services as ports and its wording as messages, so every view wears your app's look. These pages take you from install to a grid on screen, explain each concept, and list every export.
4
+
5
+ Every example on these pages is compiled and run against the packed package before each release.
6
+
7
+ ## Start here
8
+
9
+ - [Getting started](getting-started.md): install, fields bound to your rows, columns, your primitives, the provider and the grid
10
+ - [Install](install.md): the Tailwind line and the colour block that make the rendering look like your app
11
+
12
+ ## Guides
13
+
14
+ Setting it up:
15
+
16
+ - [The provider](guides/the-provider.md): mounting it once, your adapter over your own primitives, icons, messages and presentation
17
+ - [Ports](guides/ports.md): your toast, haptics, clipboard, per-device store and confirm dialog
18
+ - [Atoms](guides/atoms.md): the small pieces every view is built from, and swapping them for your own
19
+
20
+ Drawing and editing values:
21
+
22
+ - [The display](guides/display.md): one renderer per field type, and the string formatters
23
+ - [Editors and the edit session](guides/editors.md): one editor per field type, what an editor owns and what its host owns
24
+ - [Columns](guides/columns.md): a field bound to your row, the column built from it, and what may be done to it
25
+ - [Cells](guides/cells.md): a column's value drawn in a cell, outside the grid too
26
+ - [Selection](guides/selection.md): a list's selection, its checkbox, drag-select and the row-click rules
27
+
28
+ The grid:
29
+
30
+ - [The grid](guides/the-grid.md): grouping, sorting, writes, preferences, figures and the editing rules
31
+
32
+ Reference material:
33
+
34
+ - [The rendering contract](contract.md): every public name (slots, states, tokens, the components map, atoms, ports, icons, message keys) and what each door holds
35
+ - [Reshaping a view](reshaping.md): the cheapest change first, from a theme to a copy of the rendering
36
+
37
+ ## Reference
38
+
39
+ One page per door. Each lists every name the door exports.
40
+
41
+ - [`@viewkitjs/views`](reference/views.md): the rendering contract and the model: columns, preferences, filters, figures, groups, bindings and money
42
+ - [`@viewkitjs/views/react`](reference/react.md): the provider, the adapter's types, ports and atoms
43
+ - [`@viewkitjs/views/display`](reference/display.md): a stored value drawn, and the string formatters
44
+ - [`@viewkitjs/views/editors`](reference/editors.md): the edit registry
45
+ - [`/editors/select`](reference/editors-select.md), [`/editors/relation`](reference/editors-relation.md), [`/editors/number`](reference/editors-number.md), [`/editors/range`](reference/editors-range.md), [`/editors/name`](reference/editors-name.md), [`/editors/location`](reference/editors-location.md), [`/editors/value-list`](reference/editors-value-list.md), [`/editors/date`](reference/editors-date.md), [`/editors/chips`](reference/editors-chips.md): one editor each
46
+ - [`/editors/session`](reference/editors-session.md): the anchored edit session every host shares
47
+ - [`/editors/open-values`](reference/editors-open-values.md): an open field's values carried to its editors
48
+ - [`@viewkitjs/views/cells`](reference/cells.md): a column's typed cell
49
+ - [`@viewkitjs/views/selection`](reference/selection.md): a list's selection
50
+ - [`@viewkitjs/views/grid`](reference/grid.md): the grid, its props and the helpers a host shares with it
package/docs/install.md CHANGED
@@ -54,52 +54,14 @@
54
54
  grid sits flush with its container.
55
55
 
56
56
  4. **Mount the provider once**, above every view, with your primitives, your ports, your icons and
57
- your field conventions; your own atoms and wording are optional:
57
+ your field conventions; your own atoms, wording and number formats are optional.
58
+ [The provider guide](guides/the-provider.md) shows it, with your messages through a translator
59
+ scoped to the `views` namespace and `presentation` for your own number and date formats.
58
60
 
59
- ```tsx
60
- "use client";
61
- import { ViewsProvider } from "@viewkitjs/views/react";
62
- import { viewsComponents } from "./views-components"; // your adapter over your shadcn copies
63
- import { viewsIcons } from "./views-icons"; // your icon library, by meaning
64
- import { viewsPorts } from "./views-ports"; // toast, haptics, clipboard, viewPrefs
65
- import { conventions } from "./field-conventions"; // the same object you hand @viewkitjs/fields
61
+ 5. **Write the adapter.** The [contract](contract.md) names the eleven components and what each must
62
+ accept; `ViewsComponents`, from `@viewkitjs/views/react`, is the type. An app on Base UI wraps its
63
+ shadcn copies thinly; an app on Radix maps `anchor` to its anchor with a virtual ref and
64
+ `onOpenChange` to its own. [The provider guide](guides/the-provider.md) walks through both, and
65
+ the contract's "Writing an adapter" says what to do where a copy stops short.
66
66
 
67
- export function AppViews({ children }: { children: React.ReactNode }) {
68
- return (
69
- <ViewsProvider
70
- components={viewsComponents}
71
- icons={viewsIcons}
72
- ports={viewsPorts}
73
- conventions={conventions}
74
- >
75
- {children}
76
- </ViewsProvider>
77
- );
78
- }
79
- ```
80
-
81
- The package ships default atoms — a row, a tick box, a status badge and marker, a tag, and the
82
- rest `docs/contract.md` names — drawn from your theme. Swap any of them with your own through `atoms` (a module-level object):
83
- `atoms={{ Tag: MyTag }}`. Its own strings resolve through `messages`, which defaults to the package's
84
- English. With next-intl, a translator scoped to the `views` namespace, each key read without its
85
- `views.` prefix, and `resolveViewsMessage` from `@viewkitjs/views` for any key your catalog leaves out:
86
-
87
- ```tsx
88
- const t = useTranslations("views");
89
- const messages = (m: ViewsMessage) => {
90
- const key = m.key.slice("views.".length);
91
- return t.has(key) ? t(key, "values" in m ? m.values : undefined) : resolveViewsMessage(m);
92
- };
93
- ```
94
-
95
- A root translator over a typed catalog can overflow TypeScript, hence the namespace.
96
-
97
- Numbers, dates and durations read in your conventions' locale. To print them your own way — a
98
- currency's symbol, a date's order — hand `presentation`, a function that takes the package's
99
- defaults and returns yours: `(defaults) => ({ ...defaults, number: … })`. Import only the
100
- `FieldPresentation` type, so the module that mounts the provider pulls in none of the display.
101
-
102
- 5. **Write the adapter.** `docs/contract.md` names the eleven components and what each must accept;
103
- `ViewsComponents`, from `@viewkitjs/views/react`, is the type. An app on Base UI wraps its shadcn copies thinly, as
104
- `docs/contract.md`'s "Writing an adapter" says where a copy stops short; an app on Radix maps
105
- `anchor` to `Anchor` with a virtual ref and `onOpenChange` to its own.
67
+ From here, [getting started](getting-started.md) puts a grid on screen.
@@ -0,0 +1,28 @@
1
+ # `@viewkitjs/views/cells`
2
+
3
+ Import from `@viewkitjs/views/cells` to draw a column's cell: a column, its row and the reader's overrides, handed to the field display, and the string formatters that take a column rather than a field. The door carries no client directive; each file behind it that renders or reads the provider carries its own. A column's glyph stays your app's, and so do the `CommandMenu` a command cell opens and the `RelationLink` a relation chip goes through (the provider's atoms).
4
+
5
+ ## Drawing a cell
6
+
7
+ Guide: [cells](../guides/cells.md).
8
+
9
+ - `renderTypedCellValue` — draws one typed cell: takes a column (`ListColumn`), its row and optional `GridCellOptions`. The value is `valueOverride` when it is defined, else the column's accessor. An empty value draws `null` (a boolean draws its off state; a name draws the column's `nameFallback` words), and so does a column with no type. A `title` column draws the list's title cell, the hotspot that opens the row, with the column's `indicator` beside the name. Any other column hands its `field`, or one `legacyFieldFromColumn` builds, to `renderFieldValue`. A `command` column handed `commandItems` opens your `CommandMenu` atom: one trigger around the value, or a chevron beside a relation, user, link, email, phone or domain, which stay their own control. A relation chip goes where `onOpenRelation` says, else where your `RelationLink` atom says, and is inert under `slotOwnsClick`.
10
+ - `renderIdentityValue` — draws an identity's value without the title cell, for a host that draws the name in its own chrome. A number, percent, currency, date, datetime or name draws through its field; anything else as its text. It returns `null` for an empty value unless the column gives the row a name fallback.
11
+ - `GridCellOptions` — what a surface tells a cell, all optional.
12
+ - The formatting: `presentation` and `viewer`.
13
+ - The reader's overrides: `optionColors`, `dateStyle`, `durationStyle`, `decimals`, `withTime`, `percentDisplay` and `wrap` (text wraps instead of truncating).
14
+ - The row's answers: `currency` (the code a value is in when the caller knows it and the column does not), `valueOverride` (a pending value, which wins over the accessor; only typed cells honour it) and `markerReason`.
15
+ - The verbs: `onResolve` (clears a marker), `onToggle` (flips a checkbox or icon boolean; its presence makes it clickable), `commandItems` (a command column's verbs for this row; without them the cell is a read-only badge) and `onOpenRelation` (opens the record a chip points at, handed the clicked value, for a list whose relations go somewhere your app-wide answer cannot know).
16
+ - The host's: `entityIcon` (your glyph for an entity kind) and `slotOwnsClick` (a host whose own element is the button: every cell draws bare content).
17
+
18
+ ## Column-shaped text
19
+
20
+ - `formatDate` — a date column's value as text: takes the value, the column, a date style override, a show-time override and the viewer. The overrides win over the column's `format`. A date column, or a derived field whose result is a day, reads as a calendar day; anything else as an instant.
21
+ - `formatNumber` — a number as a column prints it, for a footer total that must match its cells: takes the value, the column and options that include the viewer. The column's format is read through `legacyNumberLikeFormat`, so a percent or currency column prints as one.
22
+ - `useCellFormat` — reads what the two formatters need from the provider: `{ viewer, presentation }`. The viewer is built from the provider's conventions and wording on each render, with that render's `now`; `presentation` is the provider's `presentation` applied to the defaults, or `undefined` when it has none.
23
+ - `resolveRowCurrency` — returns the options with `currency` set to the code this row's money value is in: the column's `currencyAccessor` answer for the row, else, for a column a currency field backs, the code its format names. The options come back unchanged when neither gives one.
24
+
25
+ ## A column no registry field backs
26
+
27
+ - `legacyFieldFromColumn` — reads a column as a field definition, for display only: the same type, the column's label, and what a field requires that a column never had to say (a select's option labels from their values, a status option's `muted` slot, a multiselect open to custom values, a boolean's missing word as Yes or No, a currency's code from the column's format or `EUR`). It carries no write policy and no validation; whether the column is editable stays the column's answer. It throws `FieldDefinitionError` for a column with no type and for a `title` column, which is a role, not a storage type.
28
+ - `legacyNumberLikeFormat` — the column's number format as a `NumberLikeFormat`, read off its type: a percent column as `style: "percent"`, a currency column as `style: "currency"` with its code (`EUR` when it names none), anything else as plain or duration. `undefined` for a plain column with no format.
@@ -0,0 +1,42 @@
1
+ # `@viewkitjs/views/display`
2
+
3
+ Import from `@viewkitjs/views/display` to draw one field's value anywhere you hold a field definition and a value, or to print it as text. One renderer per storage type, keyed by the field's type, so a grid cell, a board card and a detail row read a value the same way. The door carries no client directive, so a server module may reach its string formatters; every file behind it that renders carries its own. A rendered value reads the provider's conventions, wording and presentation, so draw it under `ViewsProvider`; a string formatter handed no viewer reads the neutral conventions (`DEFAULT_CONVENTIONS`), never the runtime's locale or zone. What a field cannot know stays your app's: where a relation chip goes, the glyph of an entity kind, a boolean's icon, and the row's own answers (its currency, the words for an empty name). The [contract](../contract.md) names the slots and tokens the display paints with.
4
+
5
+ ## Drawing a value
6
+
7
+ Guide: [display](../guides/display.md).
8
+
9
+ - `renderFieldValue` — the entry point: takes a field, its value and optional `DisplayOptions`, and returns what to draw for it. It returns `null` for an empty value (`null`, `""` or an empty array), except a boolean, which draws its off state, and a name handed `nameFallback`, which draws those words. Anything else goes to the field type's core in `DISPLAY_CORES`.
10
+ - `DISPLAY_CORES` — the table of renderers, one per field type, typed so a field type without a core fails to compile. `date` and `datetime` share one core. A lookup, a formula and a one-figure rollup draw as their result's shape; a rollup grouped by a field draws its parts beside its headline. A core does not skip empty values itself; `renderFieldValue` does that before it dispatches.
11
+ - `DisplayCore` — the type of one renderer: `(field, value, opts?) => ReactNode`, for a field definition of one type.
12
+ - `DisplayOptions` — what a surface tells a renderer that the field cannot know. Every member is optional; with none, a value draws in its field's own defaults.
13
+ - The formatting: `presentation` and `viewer`, which win over the provider's.
14
+ - The reader's overrides: `dateStyle`, `durationStyle`, `decimals`, `withTime` (wins over the field's `withTime`), `percentDisplay` (wins over the field's `format.display`), and `wrap` (`true` clamps text to three lines, `"full"` shows it whole; see `cellTextClass`).
15
+ - The row's answers: `currency` (the code this value is in), `nameFallback` (the words for an empty name), `optionColors` (a reader's colour per option) and `labelFallback` (a label for a select value no option names; without it the value draws as the muted unknown chip).
16
+ - A boolean's: `booleanIcon` (the two-state glyph), `marker`, `markerReason` and `onResolve` (the marker style's words, reason and clearing verb), `onToggle` (its presence makes a checkbox or icon boolean clickable; without it the glyph is plain) and `booleanDisabled` (keeps the control's shape, disabled).
17
+ - A relation's: `entityIcon` (your glyph for an entity kind) and `relationWrap` (where a chip goes; absent, the chip is inert).
18
+ - The host's slot: `slotOwnsClick`, set by a host whose own element is the button, such as a calendar card. Every core then draws bare content: an overflow count as plain text, a boolean with no toggle.
19
+ - `RelationWrap` — the type of `relationWrap`: `(relation, chip) => ReactNode`. The core draws the chip (its icon and label); your function wraps it in your own link or button, since where a record opens is your app's.
20
+ - `MultiValueCell` — the layout for a value that holds several: several emails, phones, links or domains, a multiselect, the far side of a relation. It takes `items` (one drawn node per value), and optionally `details` (a word beside each value in the list, never in the cell), `wrap`, `title` (the native hover text) and `slotOwnsClick`. It shows one value, or three when wrapped, then a `+N` count that opens every value in a read-only list in the components map's `Popover`, drawn with the `List` and `Row` atoms. With `slotOwnsClick` the count is plain text and nothing opens. No items draws nothing.
21
+
22
+ ## Formatting a value as text
23
+
24
+ - `formatDateValue` — prints a date or an instant: takes the value, the date style (`short` when none), whether to show the time, the kind (`"datetime"` by default; `"date"` reads a `YYYY-MM-DD` day key) and options carrying `presentation` and `viewer`. A `Date` handed for a day is read as its calendar day. A value that does not parse comes back as its own text, never "Invalid Date".
25
+ - `formatNumberValue` — prints a number in the style its format names (plain, duration, percent or currency): takes the value, a `NumberLikeFormat` (plain when none) and options (`decimals`, `currency`, `durationStyle`, `presentation`, `viewer`), which win over the format. A duration reads the value in its stored unit (milliseconds, or seconds when the format says so) and picks its own precision. A currency code comes from the options, then the format, then `EUR`. A `signed` format prints `+ ` or `− ` before the absolute value.
26
+ - `formatMoney` — writes an amount in its own currency, as a money cell does: takes the amount, the currency, the decimals (two by default) and options carrying `presentation` and `viewer`, and prints through `formatNumberValue`, so the amount reads in the viewer's locale and your presentation's look. With no options it takes the default presentation and the neutral conventions (`en-GB`). An absent currency is read as EUR and an absent amount as zero; a code `Intl` refuses is written as the code before the number.
27
+ - `NumberLikeFormat` — what `formatNumberValue` accepts: a number field's format, a percent format with `style: "percent"`, or a currency format with `style: "currency"` and an optional code. Wider than a number field's own format, so one function prints a footer total, a live format preview and all three numeric types.
28
+ - `webHref` — where a web address goes: the trimmed text when its scheme is http, https or ftp; `https:` before an address that opens with `//`; `https://` before a bare host. It returns `null` for empty text and for any other scheme (`javascript:`, `data:`), and for a host written with a port (`example.com:8080`), which reads as a scheme. Plain, so a server module may use it.
29
+
30
+ ## The viewer and the presentation
31
+
32
+ - `FieldViewerContext` — who is reading: `locale`, `now`, and optionally `timeZone`, `region` (a phone of that country is written as at home), `fieldMessages` (fields' words, fields' English by default) and `messages` (the package's words, its English by default).
33
+ - `viewerFrom` — builds a `FieldViewerContext` from your conventions: their locale, zone, region and messages, with the package's words (`resolveViewsMessage` unless you pass a resolver) and `now` (the current moment unless you pass one).
34
+ - `FieldPresentation` — every formatter a value is printed through, so your app can replace how numbers, durations and dates read: `message`, `number`, `duration`, `calendarDay`, `instant`, `relativeCalendarDay` and `relativeInstant`, each handed the viewer. The provider's `presentation` option returns one, given the defaults.
35
+ - `DEFAULT_FIELD_PRESENTATION` — the package's own `FieldPresentation`. Numbers print through `Intl.NumberFormat` in the viewer's locale; a percent, stored as 0 to 100, prints as it is with `%`; a currency defaults to `EUR` with two decimals. Days print `short` ("27 Sep", the year added when it is not the current one), `long` ("27 September 2026") or `numeric` ("27/09/2026"), a time ("14:05") after a comma, in the viewer's zone. Relative styles say "just now", "5m ago", "in 1d", and "today", "yesterday" or "tomorrow" for a day. Month names and relative words come from the viewer's messages.
36
+
37
+ ## Paint for your own cells
38
+
39
+ - `CellSuffix` — the small, subtle unit after a value (a "/mo" after a price), as a component around its children, so every suffix reads alike.
40
+ - `cellTextClass` — the classes for text longer than its box: one truncated line by default, up to three wrapped lines for `true`, the whole value with its newlines for `"full"`.
41
+ - `CHIP_BASE` — the class string of a relation chip's row (icon and label in one line), shared by the inert chip and the default `RelationLink` atom.
42
+ - `CHIP_INTERACTIVE` — `CHIP_BASE` made a link or a button: it inherits the surrounding text colour, so an `<a>` and a `<button>` read the same, and its label turns the brand colour and underlines on its own hover. For a `relationWrap` or a `RelationLink` that wraps the chip in your control.