@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,412 @@
1
+ # Columns
2
+
3
+ A field says what a value is; a column is how one list draws it. Between the two sits a binding: how that field reads and writes on your row. This page covers the binding and the checks it is held to when your module loads, the column `columnFrom` derives from it, what a column carries, the two questions every surface asks before it writes, and the field that is changed only by verbs.
4
+
5
+ ## The registry and the row
6
+
7
+ Every example on this page binds one registry of deals. The fields come from `@viewkitjs/fields`, whose own guides cover each type; here they are chosen to show each kind of column: a title, a per-row currency, a status, a relation, a boolean, a value nobody edits, a value changed by verbs, and a worked-out figure.
8
+
9
+ ```ts
10
+ import assert from "node:assert/strict";
11
+ import { defineFields, FieldDefinitionError, type NumberCommit } from "@viewkitjs/fields";
12
+
13
+ const DEAL_FIELDS = defineFields({
14
+ entity: "deal",
15
+ identity: "title",
16
+ fields: {
17
+ title: { type: "text", label: "Title", required: true },
18
+ value: { type: "currency", label: "Value", code: { field: "currency" }, nullable: true },
19
+ currency: {
20
+ type: "select",
21
+ label: "Currency",
22
+ options: [
23
+ { value: "EUR", label: "EUR" },
24
+ { value: "USD", label: "USD" },
25
+ ],
26
+ },
27
+ stage: {
28
+ type: "status",
29
+ label: "Stage",
30
+ options: [
31
+ { value: "lead", label: "Lead", slot: "pending" },
32
+ { value: "qualified", label: "Qualified", slot: "running" },
33
+ { value: "proposal", label: "Proposal", slot: "primary" },
34
+ ],
35
+ },
36
+ client: { type: "relation", label: "Client", nullable: true, relation: { kind: "company" } },
37
+ priority: { type: "boolean", label: "Priority" },
38
+ reference: { type: "text", label: "Reference", edit: { mutability: "never" } },
39
+ outcome: {
40
+ type: "status",
41
+ label: "Outcome",
42
+ options: [
43
+ { value: "open", label: "Open", slot: "pending" },
44
+ { value: "won", label: "Won", slot: "success" },
45
+ { value: "lost", label: "Lost", slot: "error" },
46
+ ],
47
+ edit: { mutability: "command" },
48
+ },
49
+ weighted: {
50
+ type: "formula",
51
+ label: "Weighted value",
52
+ from: "the value and the stage",
53
+ result: { type: "number" },
54
+ },
55
+ },
56
+ });
57
+
58
+ type Deal = {
59
+ id: string;
60
+ title: string;
61
+ value: number | null;
62
+ currency: string;
63
+ stage: string;
64
+ clientId: string | null;
65
+ clientName: string | null;
66
+ priority: boolean;
67
+ reference: string;
68
+ outcome: string;
69
+ weighted: number | null;
70
+ };
71
+
72
+ const deal: Deal = {
73
+ id: "d1",
74
+ title: "Acme renewal",
75
+ value: 1200,
76
+ currency: "USD",
77
+ stage: "qualified",
78
+ clientId: "c1",
79
+ clientName: "Acme",
80
+ priority: false,
81
+ reference: "D-0001",
82
+ outcome: "open",
83
+ weighted: 600,
84
+ };
85
+ ```
86
+
87
+ ## A binding: how a field reads and writes on your row
88
+
89
+ `bindFields(registry, specs)` binds every field of a registry at once, and refuses a registry with a field left unbound; `bindField(field, spec)` binds one. A spec says:
90
+
91
+ - `read(row)`: the value a surface draws. A relation reads its resolved `{ id, label }`.
92
+ - `editRead(row)`: the stored value, when it differs from the one drawn: a relation's id, or a raw value behind a fallback. An editor opens on it.
93
+ - `write(row, commit)`: maps what an editor commits onto the body of your own request, as a `FieldPatch` (`{ body, storedValue?, settlement? }`), or refuses with `{ skip: true, reason }`. No surface shows that reason for you: `prepareFieldWrite` (below) turns it into `{ ok: false, reason }`, and in a grid your `onCellCommit` throws it, so the cell rolls back, and shows it through your own toast ([the grid](the-grid.md#writes)). Leave `write` out and the field is read-only on every surface.
94
+ - `unit`: for a money field whose currency comes from the row: `read(row)` gives the row's currency and `options` the currencies a person may pick, so the amount's editor offers a currency picker beside the number.
95
+ - `relation`: a writable relation's candidates, either `{ kind: "static", items }` (a list you already hold) or `{ kind: "remote", search }` (a search your app runs, a page at a time).
96
+ - `icon`: your own icon name for the field, drawn by your `AppIcon`; the type's glyph when absent.
97
+ - `labels: false`: on a field that holds several values, this row keeps only the values, so its editor offers no label box.
98
+ - `ratio`: a ratio formula's two parts, read off the row, which the footer sums before it divides.
99
+ - `history`: an undo adapter (`fieldHistory({ capture, equals, restore })`) for a write that changes more than the field's own value. It needs a `write`.
100
+
101
+ A number, a percent or an amount commits a `NumberCommit`, `{ value, unit? }`, from the editor and from a paste alike: `unit` is the currency the person picked, and an emptied box, on a field that may be emptied, commits `value: null`. Its `write` says what it stores in `storedValue`.
102
+
103
+ A clear is the one commit in another shape. Delete, Cut and Clear on a field that may be emptied commit `""` for a number, a date, a text, a select and most other types (a relation commits `null`, a multiselect `[]`, a boolean `false`), so a `write` that casts the commit to its usual shape reads a clear as nonsense. Map `""` to what your row stores for nothing, here `null`, since the value is `nullable`. A text box emptied commits `""` as well, even on a required field, so `title` refuses it.
104
+
105
+ ```ts
106
+ import {
107
+ bindField,
108
+ bindFields,
109
+ bindingWritable,
110
+ checkBinding,
111
+ FieldBindingError,
112
+ prepareFieldWrite,
113
+ type RelationCandidate,
114
+ } from "@viewkitjs/views";
115
+
116
+ const COMPANIES: RelationCandidate[] = [
117
+ { id: "c1", label: "Acme" },
118
+ { id: "c2", label: "Globex" },
119
+ ];
120
+
121
+ const DEAL_BINDINGS = bindFields<Deal, typeof DEAL_FIELDS>(DEAL_FIELDS, {
122
+ title: {
123
+ read: (row) => row.title,
124
+ // Required: an emptied box is refused rather than stored.
125
+ write: (_row, commit) =>
126
+ commit === "" ? { skip: true, reason: "A deal needs a title." } : { body: { title: commit } },
127
+ },
128
+ value: {
129
+ read: (row) => row.value,
130
+ unit: { read: (row) => row.currency, options: ["EUR", "USD"] },
131
+ write: (_row, commit) => {
132
+ // A clear commits "", not a NumberCommit.
133
+ if (commit === "") return { body: { value: null }, storedValue: null };
134
+ const { value, unit } = commit as NumberCommit;
135
+ return { body: unit ? { value, currency: unit } : { value }, storedValue: value };
136
+ },
137
+ },
138
+ currency: { read: (row) => row.currency, write: (_row, commit) => ({ body: { currency: commit } }) },
139
+ stage: {
140
+ read: (row) => row.stage,
141
+ // A refusal that depends on the row: the field allows "proposal", this deal can't take it yet.
142
+ write: (row, commit) =>
143
+ commit === "proposal" && row.value === null
144
+ ? { skip: true, reason: "A proposal needs a value." }
145
+ : { body: { stage: commit } },
146
+ },
147
+ client: {
148
+ read: (row) => (row.clientId ? { id: row.clientId, label: row.clientName ?? "" } : null),
149
+ editRead: (row) => row.clientId,
150
+ relation: { kind: "static", items: COMPANIES },
151
+ icon: "building",
152
+ write: (_row, commit) => ({ body: { client_id: commit } }),
153
+ },
154
+ priority: { read: (row) => row.priority, write: (_row, commit) => ({ body: { priority: commit } }) },
155
+ reference: { read: (row) => row.reference },
156
+ outcome: { read: (row) => row.outcome },
157
+ weighted: { read: (row) => row.weighted },
158
+ });
159
+
160
+ assert.deepEqual(DEAL_BINDINGS.value.write?.(deal, { value: 900, unit: "EUR" }), {
161
+ body: { value: 900, currency: "EUR" },
162
+ storedValue: 900,
163
+ });
164
+ assert.deepEqual(DEAL_BINDINGS.value.write?.(deal, ""), { body: { value: null }, storedValue: null });
165
+ assert.deepEqual(DEAL_BINDINGS.stage.write?.({ ...deal, value: null }, "proposal"), {
166
+ skip: true,
167
+ reason: "A proposal needs a value.",
168
+ });
169
+ ```
170
+
171
+ `bindingWritable(binding)` is the binding's answer to "may this be written at all": a `write` was declared and the field's mutability is `"always"`. A field with no `write`, a value nobody edits and a field changed by verbs all answer `false`.
172
+
173
+ ```ts
174
+ assert.equal(bindingWritable(DEAL_BINDINGS.title), true);
175
+ assert.equal(bindingWritable(DEAL_BINDINGS.reference), false);
176
+ assert.equal(bindingWritable(DEAL_BINDINGS.outcome), false);
177
+ ```
178
+
179
+ `prepareFieldWrite(binding, row, commit)` runs the path a write takes before your request: the field's own acceptance of the commit, then your `write`. It answers `{ ok: true, body, storedValue }` or `{ ok: false, reason }`.
180
+
181
+ ```ts
182
+ assert.deepEqual(prepareFieldWrite(DEAL_BINDINGS.stage, deal, "proposal"), {
183
+ ok: true,
184
+ body: { stage: "proposal" },
185
+ storedValue: "proposal",
186
+ });
187
+ assert.deepEqual(prepareFieldWrite(DEAL_BINDINGS.stage, { ...deal, value: null }, "proposal"), {
188
+ ok: false,
189
+ reason: "A proposal needs a value.",
190
+ });
191
+ ```
192
+
193
+ ### The checks a binding is held to
194
+
195
+ `bindField` and `bindFields` run `checkBinding` on every binding they make, and it throws `FieldBindingError`, so a binding that contradicts its field fails when your module loads rather than on the first edit. It refuses:
196
+
197
+ - a `write` on a field whose mutability is `"create"` or `"never"`, and on a `"command"` field, whose verbs write it;
198
+ - a `history` without a `write`;
199
+ - a `unit` on anything but a currency or a number, and a writable per-row-currency amount without one;
200
+ - `relation` candidates on anything but a relation or a member field, and a writable relation without them;
201
+ - a writable relation that stores its kind beside the id, which these editors can't commit;
202
+ - a ratio formula without its `ratio` readers, and `ratio` readers on anything else;
203
+ - `labels` on a field that holds one value.
204
+
205
+ ```ts
206
+ assert.throws(
207
+ () => checkBinding({ field: DEAL_FIELDS.reference, read: (row: Deal) => row.reference, write: () => ({ body: {} }) }),
208
+ FieldBindingError
209
+ );
210
+ assert.throws(
211
+ () => bindField<Deal, typeof DEAL_FIELDS.reference>(DEAL_FIELDS.reference, {
212
+ read: (row) => row.reference,
213
+ write: () => ({ body: {} }),
214
+ }),
215
+ /a never-only field takes no write/
216
+ );
217
+ assert.throws(
218
+ () => bindField<Deal, typeof DEAL_FIELDS.value>(DEAL_FIELDS.value, {
219
+ read: (row) => row.value,
220
+ write: (_row, commit) => ({ body: { value: commit } }),
221
+ }),
222
+ /unit/
223
+ );
224
+ ```
225
+
226
+ ## A column: the binding plus what only the surface knows
227
+
228
+ `columnFrom(binding, presentation)` turns a binding into a column. From the field and the binding it derives:
229
+
230
+ - `type`: the field's value type, a worked-out field's result type, or `"title"` for the registry's identity field.
231
+ - `options`: a select's or a status's options, archived ones included, so a row that holds one still draws it.
232
+ - `format`: what the field states (decimals, a fixed currency, a date's style), plus `decimals: 0` on an integer field.
233
+ - `align`: `"right"` for a figure (a number, a percent, an amount), so a column of them reads down the decimal point.
234
+ - `editable`: `true` when the binding is writable and the type has an editor (or is a boolean, which writes from its display).
235
+ - `clearable`: `true` when the field is nullable or emptiable.
236
+ - the readers, carried from the binding: `accessor` from `read`, `editAccessor` from `editRead`, `editUnit` and `currencyAccessor` from `unit`, `relation` from the candidates.
237
+ - `custom` for a worked-out field (the sentence it is computed from), `command` for a field changed by verbs, `ratio` from the binding, and `field` and `binding` themselves.
238
+
239
+ The presentation adds what neither knows: the column's `id` and `width` (both required), and any of `header` (the field's label otherwise), `align`, `defaultHidden`, `sortKey`, `render`, `actions`, `defaultAggregate`, `grid` (a minimum and maximum width), `card` (where it lands on a card), format keys of its own, and an `accessor` of its own (or `null` for a cell that draws itself).
240
+
241
+ ```ts
242
+ import {
243
+ columnEffectiveWritable,
244
+ columnFrom,
245
+ columnWritable,
246
+ gridColumnHasEditor,
247
+ gridEditorKind,
248
+ type ListColumn,
249
+ } from "@viewkitjs/views";
250
+
251
+ const titleColumn = columnFrom(DEAL_BINDINGS.title, { id: "title", width: 240 });
252
+ const valueColumn = columnFrom(DEAL_BINDINGS.value, { id: "value", width: 120 });
253
+ const stageColumn = columnFrom(DEAL_BINDINGS.stage, { id: "stage", width: 140 });
254
+ const clientColumn = columnFrom(DEAL_BINDINGS.client, { id: "client", width: 180 });
255
+ const priorityColumn = columnFrom(DEAL_BINDINGS.priority, { id: "priority", width: 90 });
256
+ const referenceColumn = columnFrom(DEAL_BINDINGS.reference, { id: "reference", width: 120 });
257
+ const outcomeColumn = columnFrom(DEAL_BINDINGS.outcome, { id: "outcome", width: 120 });
258
+ const weightedColumn = columnFrom(DEAL_BINDINGS.weighted, { id: "weighted", width: 120, header: "Weighted" });
259
+
260
+ const columns: ListColumn<Deal>[] = [
261
+ titleColumn,
262
+ valueColumn,
263
+ stageColumn,
264
+ clientColumn,
265
+ priorityColumn,
266
+ referenceColumn,
267
+ outcomeColumn,
268
+ weightedColumn,
269
+ ];
270
+
271
+ assert.equal(titleColumn.type, "title");
272
+ assert.equal(titleColumn.header, "Title");
273
+ assert.equal(titleColumn.accessor?.(deal), "Acme renewal");
274
+
275
+ // A per-row amount: right-aligned, two decimals, and the row's currency beside it.
276
+ assert.equal(valueColumn.type, "currency");
277
+ assert.equal(valueColumn.align, "right");
278
+ assert.deepEqual(valueColumn.format, { decimals: 2 });
279
+ assert.equal(valueColumn.currencyAccessor?.(deal), "USD");
280
+ assert.deepEqual(valueColumn.editUnit?.options, ["EUR", "USD"]);
281
+ assert.equal(valueColumn.clearable, true);
282
+
283
+ assert.deepEqual(
284
+ stageColumn.options?.map((option) => option.value),
285
+ ["lead", "qualified", "proposal"]
286
+ );
287
+
288
+ // A relation draws its label and edits its id, among the candidates.
289
+ assert.deepEqual(clientColumn.accessor?.(deal), { id: "c1", label: "Acme" });
290
+ assert.equal(clientColumn.editAccessor?.(deal), "c1");
291
+ assert.equal(clientColumn.relation?.entity, "company");
292
+ assert.deepEqual(clientColumn.relation?.options, COMPANIES);
293
+
294
+ // A worked-out figure is a figure, and says what it is computed from.
295
+ assert.equal(weightedColumn.type, "number");
296
+ assert.equal(weightedColumn.align, "right");
297
+ assert.equal(weightedColumn.header, "Weighted");
298
+ assert.deepEqual(weightedColumn.custom, { from: "Computed from the value and the stage" });
299
+ ```
300
+
301
+ ### A surface may only subtract
302
+
303
+ `editable` is the binding's answer, and a column may only take it away: `editable: false` declines the edit, and a `reasons.editable` sentence declines it with the words a person sees. A column can never add one. `editable: true` on a binding that can't be written throws `FieldDefinitionError` when the column is built, and so does `editable: true` beside a `reasons.editable`.
304
+
305
+ ```ts
306
+ const stageOnBoard = columnFrom(DEAL_BINDINGS.stage, {
307
+ id: "stage",
308
+ width: 140,
309
+ reasons: { editable: "Stage moves on the board." },
310
+ });
311
+ assert.equal(stageOnBoard.editable, undefined);
312
+ assert.equal(stageOnBoard.reasons?.editable, "Stage moves on the board.");
313
+ assert.equal(columnFrom(DEAL_BINDINGS.stage, { id: "stage", width: 140, editable: false }).editable, undefined);
314
+
315
+ assert.throws(
316
+ () => columnFrom(DEAL_BINDINGS.reference, { id: "reference", width: 120, editable: true }),
317
+ FieldDefinitionError
318
+ );
319
+ ```
320
+
321
+ ## What a column is
322
+
323
+ A column is a `ListColumn<Row>`: one object every view reads, the grid to draw a cell and mount an editor, a card to place a field, a filter to compare values. Beside what `columnFrom` derives, it carries the presentation's keys, `reasons` (why an edit or a clear is refused, as sentences), `field` (the definition, which the write gate asks to accept a value) and `binding` (the reads and the write). Your commit handler finds the binding on the column it is handed and calls its `write`. The [views reference](../reference/views.md) lists every key.
324
+
325
+ ## What may be done to a column
326
+
327
+ Two questions sound alike and are kept apart:
328
+
329
+ - `gridColumnHasEditor(column)`: does a click, a double-click, Enter or typing mount an editor? `gridEditorKind(column)` names which one: `"text"`, `"number"`, `"select"`, `"relation"`, `"chips"` and the rest, or `null`.
330
+ - `columnWritable(column)`: can the column be written by any route: an editor, Delete, Clear, a fill or a paste? A boolean answers `true` with no editor, as it commits from its display. A worked-out value and a field changed by verbs answer `false` whatever else the column says.
331
+
332
+ ```ts
333
+ assert.equal(gridEditorKind(titleColumn), "text");
334
+ assert.equal(gridEditorKind(valueColumn), "number");
335
+ assert.equal(gridEditorKind(clientColumn), "relation");
336
+
337
+ // A boolean writes without an editor.
338
+ assert.equal(gridColumnHasEditor(priorityColumn), false);
339
+ assert.equal(columnWritable(priorityColumn), true);
340
+
341
+ // Nobody edits these.
342
+ assert.equal(columnWritable(referenceColumn), false);
343
+ assert.equal(columnWritable(weightedColumn), false);
344
+ assert.equal(columnWritable(stageOnBoard), false);
345
+
346
+ assert.deepEqual(
347
+ columns.filter((column) => columnWritable(column)).map((column) => column.id),
348
+ ["title", "value", "stage", "client", "priority"]
349
+ );
350
+ ```
351
+
352
+ `columnWritable` reads the declaration alone. A list can also be locked for everyone in a workspace: a `ListSettingsConfig` makes the whole list read-only (`readOnly: true`) or locks one field (`columns: { <field key>: { locked: true } }`). `columnEffectiveWritable(column, config)` folds that in, and it is what every write route asks. Like the presentation, a lock only subtracts. It constrains the interface, never your API, which guards its own writes. The grid takes the config as `listConfig`.
353
+
354
+ ```ts
355
+ assert.equal(columnEffectiveWritable(stageColumn, undefined), true);
356
+ assert.equal(columnEffectiveWritable(stageColumn, { columns: { stage: { locked: true } } }), false);
357
+ assert.equal(columnEffectiveWritable(stageColumn, { readOnly: true }), false);
358
+ assert.equal(columnEffectiveWritable(titleColumn, { columns: { stage: { locked: true } } }), true);
359
+ ```
360
+
361
+ ## A field changed by verbs
362
+
363
+ Some changes are transitions with rules of their own: a lost deal needs a reason, a reopened one clears it. Such a field declares `edit: { mutability: "command" }`, and every surface offers its verbs instead of an editor. Its binding takes no `write` (`checkBinding` refuses one), `bindingWritable` answers `false`, and `columnFrom` marks the column `command` and never `editable`.
364
+
365
+ ```ts
366
+ assert.equal(outcomeColumn.command, true);
367
+ assert.equal(outcomeColumn.editable, undefined);
368
+ assert.equal(gridColumnHasEditor(outcomeColumn), false);
369
+ assert.equal(columnWritable(outcomeColumn), false);
370
+ assert.throws(
371
+ () => bindField<Deal, typeof DEAL_FIELDS.outcome>(DEAL_FIELDS.outcome, {
372
+ read: (row) => row.outcome,
373
+ write: () => ({ body: {} }),
374
+ }),
375
+ /command-only field takes no write/
376
+ );
377
+ ```
378
+
379
+ The verbs are yours: each carries a request, often a dialog, and a refresh. You hand them over as `FieldMenus<Row>`, a field key mapped to a function of the row that returns its `FieldRowMenuItem`s (`label`, `onClick`, and optionally `icon`, `destructive`, `disabled`). Being a function of the row, the menu follows the record's state. The same map goes to every surface that draws the field: `GridTable`'s `commands` prop, and the resolved items as `commandItems` where you draw a cell yourself through `@viewkitjs/views/cells`. So the grid cell, the drawer row and the card open the same menu. A command column handed no verbs reads as a plain value.
380
+
381
+ ```ts
382
+ import type { FieldMenus } from "@viewkitjs/views";
383
+
384
+ declare function closeDeal(id: string, outcome: "won" | "lost"): Promise<void>;
385
+ declare function reopenDeal(id: string): Promise<void>;
386
+
387
+ const DEAL_COMMANDS: FieldMenus<Deal> = {
388
+ outcome: (row) =>
389
+ row.outcome === "open"
390
+ ? [
391
+ { label: "Mark won", onClick: () => void closeDeal(row.id, "won") },
392
+ { label: "Mark lost", destructive: true, onClick: () => void closeDeal(row.id, "lost") },
393
+ ]
394
+ : [{ label: "Reopen", onClick: () => void reopenDeal(row.id) }],
395
+ };
396
+
397
+ assert.deepEqual(
398
+ DEAL_COMMANDS.outcome?.(deal).map((item) => item.label),
399
+ ["Mark won", "Mark lost"]
400
+ );
401
+ assert.deepEqual(
402
+ DEAL_COMMANDS.outcome?.({ ...deal, outcome: "lost" }).map((item) => item.label),
403
+ ["Reopen"]
404
+ );
405
+ ```
406
+
407
+ ## Next
408
+
409
+ - [Selection](selection.md): picking rows, and the batch writes a selection hands your bar
410
+ - [The grid](the-grid.md): grouping, sorting, preferences, figures and writes
411
+ - [`@viewkitjs/views` reference](../reference/views.md): every key of a column, every predicate
412
+ - [The contract](../contract.md): the field changed by verbs, and the value's four shapes
@@ -0,0 +1,203 @@
1
+ # The display
2
+
3
+ A grid cell, a board card and a detail row all draw a stored value, and they draw it the same way because they go through one door: `@viewkitjs/views/display`. This page covers drawing a value with `renderFieldValue`, printing one as text with the string formatters, who the viewer is, what a surface tells the display that the field cannot know, what each field type draws, and how your app replaces the way numbers and dates read.
4
+
5
+ ## Drawing a value
6
+
7
+ `renderFieldValue(field, value, options?)` takes a field from your registry, the value a row holds, and optional `DisplayOptions`, and returns what to draw. An empty value (`null`, `undefined`, `""` or an empty array) draws nothing: the call returns `null`. Two types disagree, on purpose: a boolean draws its off state, since an unset box is what a person clicks to turn it on, and a name handed `nameFallback` draws those words.
8
+
9
+ ```tsx
10
+ import assert from "node:assert/strict";
11
+ import { defineConventions, defineFields } from "@viewkitjs/fields";
12
+ import { renderFieldValue } from "@viewkitjs/views/display";
13
+
14
+ const DEAL_FIELDS = defineFields({
15
+ entity: "deal",
16
+ identity: "title",
17
+ fields: {
18
+ title: { type: "text", label: "Title", required: true },
19
+ contact: { type: "name", label: "Contact" },
20
+ website: { type: "url", label: "Website" },
21
+ closes: { type: "date", label: "Closes", format: { dateStyle: "short" } },
22
+ archived: { type: "boolean", label: "Archived" },
23
+ tags: { type: "multiselect", label: "Tags", vocabulary: "custom-values" },
24
+ },
25
+ });
26
+
27
+ assert.equal(renderFieldValue(DEAL_FIELDS.title, null), null);
28
+ assert.equal(renderFieldValue(DEAL_FIELDS.title, ""), null);
29
+ assert.equal(renderFieldValue(DEAL_FIELDS.tags, []), null);
30
+ // An unset boolean still draws: its empty box is the control.
31
+ assert.notEqual(renderFieldValue(DEAL_FIELDS.archived, null), null);
32
+
33
+ // A name reads as written: the full name, else the given and family names.
34
+ assert.equal(renderFieldValue(DEAL_FIELDS.contact, { full: null, given: "Ada", family: "Lovelace" }), "Ada Lovelace");
35
+ // An empty name draws the words you hand it, or nothing.
36
+ assert.equal(renderFieldValue(DEAL_FIELDS.contact, null, { nameFallback: "ada@example.com" }), "ada@example.com");
37
+ assert.equal(renderFieldValue(DEAL_FIELDS.contact, { full: null, given: null, family: null }), null);
38
+ ```
39
+
40
+ What comes back is usually an element, and most of the elements read the provider while they render: your atoms (a tag, a status badge, a tick box), your components map (a date's tooltip), your conventions and the package's words. So draw a value under `ViewsProvider`, like every other surface. A few types draw with nothing from it, a text value and a link among them:
41
+
42
+ ```tsx
43
+ import { renderToStaticMarkup } from "react-dom/server";
44
+
45
+ const titleHtml = renderToStaticMarkup(<>{renderFieldValue(DEAL_FIELDS.title, "Acme renewal")}</>);
46
+ assert.ok(titleHtml.includes('title="Acme renewal"')); // a clipped value keeps itself as its hover
47
+
48
+ // A web address: the scheme leaves the label and stays in the link.
49
+ const websiteHtml = renderToStaticMarkup(<>{renderFieldValue(DEAL_FIELDS.website, "https://acme.example")}</>);
50
+ assert.ok(websiteHtml.includes('href="https://acme.example"'));
51
+ assert.ok(websiteHtml.includes(">acme.example</a>"));
52
+ ```
53
+
54
+ ## One renderer per storage type
55
+
56
+ `renderFieldValue` skips the empty values, then hands the value to its type's renderer in `DISPLAY_CORES`: a table keyed by every field type fields defines, typed so a type with no renderer fails to compile rather than drawing an empty cell. Each entry is a `DisplayCore`, `(field, value, options?) => ReactNode`. A core does not skip empty values itself, so call `renderFieldValue` unless you mean to.
57
+
58
+ `date` and `datetime` share one core: they differ in what a row holds and in validation, never in how they read. A `lookup` and a `formula` have no look of their own; each draws as the field its result is. A `rollup` draws as its result too, unless it is grouped, when it draws its parts beside its headline.
59
+
60
+ ```tsx
61
+ import { DISPLAY_CORES } from "@viewkitjs/views/display";
62
+
63
+ assert.equal(DISPLAY_CORES.date, DISPLAY_CORES.datetime);
64
+ ```
65
+
66
+ ## What each type draws
67
+
68
+ - **text**: the value on one line, clipped to its box, with the whole value as its hover (a `format.long` field drops the hover, since its editor is where a paragraph is read). `wrap: true` clamps it to three lines, and `wrap: "full"` shows all of it with its newlines.
69
+ - **number**: plain or a duration, in tabular figures. An integer field draws whole numbers whatever the reader's decimals. A `suffix` trails in the small subtle unit style. A `signed` format shows the sign and tints a positive figure as a success, unless its `signedTone` is `neutral`; a field's `bands` tint the figure by the band it falls in, ahead of the sign. A value that is not a number draws as its own text.
70
+ - **currency**: in the field's fixed code, or the code you hand in `currency` (the row's own, for a field whose code comes from the row), which wins. Two decimals unless the field says otherwise or holds whole amounts.
71
+ - **percent**: stored as 0 to 100 and drawn as it is, never multiplied, with its `%` in the unit style. The field's `format.display`, or the reader's `percentDisplay`, adds a bar or a ring.
72
+ - **date** and **datetime**: in the reader's `dateStyle`, else the field's, else `short`; `withTime` from the options wins over the field's, and only an instant has a time. Hovering for a second shows the full date (and time, for an instant) through your components map's `Tooltip`, so a relative "3d ago" can be pinned to a moment. A value that doesn't parse draws as its own text.
73
+ - **boolean**: four looks, the field's `format.style`. `checkbox` (the default) draws the `TickBox` atom, and `icon` your `booleanIcon(on)`; either becomes a real switch only when you hand `onToggle`, and is a plain glyph otherwise. `text` draws the option's label for the value, or the package's words. `marker` draws only when true, as the `StatusMarker` atom with your `marker` words, `markerReason` and `onResolve`.
74
+ - **select**, **status** and **multiselect**: a select is a category and draws the `Tag` atom in its colour (a reader's `optionColors` first, then the option's declared colour, then one derived from the value). A status is a state and draws the `StatusBadge` atom in its option's slot. A multiselect draws a tag per value, through the several-values layout. A value no option names draws as the raw value, muted, with a hover saying it is not an option, unless you hand a `labelFallback`; an open (`custom-values`) vocabulary's values are their own labels. An option's `icon` is drawn through your `AppIcon`.
75
+ - **relation** and **user**: a chip, the record's avatar when it has one, else your `entityIcon(kind)`, else the relation glyph, then its label. Where it goes is yours (`relationWrap`); without one the chip is inert. Several draw through the several-values layout, the lead link first. A user is drawn as a relation to a member, so the two never differ.
76
+ - **url**, **domain**, **email** and **phone**: a url is a link with its scheme off the label, its platform's mark before it (the [`PlatformMark` atom](atoms.md)); a value that is no safe web address draws as text. A domain links to its site and reads no platform from it. An email is a `mailto:` link. A phone is written in its international form, as its country writes it for a viewer in that country (the conventions' `region`) and internationally for anyone else, its extension after it, and dialled through a `tel:` link; a phone stored as typed draws as its text and is marked `data-as-typed`. Several values of one of these draw as the main one and a count.
77
+ - **location**: in a cell, its city and its country; with `wrap: "full"`, the whole place. The country is named in the viewer's language.
78
+ - **name**: the full name as written, else the given and family names, else `nameFallback`, else nothing.
79
+ - **actor**: a chip like a relation's that opens nothing, since an actor records who did something rather than pointing at a record: a member's avatar when your value carries an `avatarUrl` beside it, and your glyph for an automation, an API key or the system.
80
+ - **rich_text**: the first line with words in it, on one line; with `wrap: true`, its plain lines, clamped; with `wrap: "full"`, your components map's `Markdown`, folded past 160px behind Show more.
81
+ - **range**: its two ends as text ("11–50", "10,001+", "up to 50"), then its unit (`%`, its currency code or its suffix) and its period ("/mo").
82
+ - **lookup** and **formula**: as the field their result is. A **rollup** grouped by an option draws a segmented bar beside its headline, and one grouped by time a sparkline, the current bucket faded.
83
+
84
+ A value that holds several, of any of these types, uses `MultiValueCell`: one value, or three when wrapped, then a `+N` count that opens all of them in a list. It is exported for your own cells; [the display reference](../reference/display.md) has its props.
85
+
86
+ ## What the field can't know
87
+
88
+ A field says what the value is. The rest arrives in `DisplayOptions`, from the surface drawing it, and every member is optional: with none, a value draws in its field's own defaults.
89
+
90
+ - The row's answers: `currency` (the code this value is in), `nameFallback` (the words for an empty name, say the person's email), `labelFallback` and `optionColors`.
91
+ - The reader's choices: `dateStyle`, `durationStyle`, `decimals`, `withTime`, `percentDisplay` and `wrap`.
92
+ - A boolean's verbs and words: `onToggle`, `booleanDisabled`, `booleanIcon`, `marker`, `markerReason` and `onResolve`.
93
+ - A relation's: `entityIcon` and `relationWrap`.
94
+ - `slotOwnsClick`, for a host whose own element is already the button, such as a calendar card: every core then draws bare content, with no link, no toggle and a count that opens nothing.
95
+ - `presentation` and `viewer`, which win over the provider's (below).
96
+
97
+ The grid and the other surfaces fill these from your columns. Where you draw a value yourself, you fill them:
98
+
99
+ ```tsx
100
+ import type { ReactNode } from "react";
101
+ import type { DisplayOptions, RelationWrap } from "@viewkitjs/views/display";
102
+
103
+ type DealContact = { name: unknown; email: string };
104
+
105
+ function ContactCell({ contact }: { contact: DealContact }) {
106
+ const options: DisplayOptions = { nameFallback: contact.email, wrap: true };
107
+ return <>{renderFieldValue(DEAL_FIELDS.contact, contact.name, options)}</>;
108
+ }
109
+
110
+ // Where a relation chip goes, for one surface: the chip is drawn, you wrap it.
111
+ const openInDrawer =
112
+ (open: (id: string) => void): RelationWrap =>
113
+ (relation, chip): ReactNode => (
114
+ <button type="button" onClick={() => open(relation.id)}>
115
+ {chip}
116
+ </button>
117
+ );
118
+ ```
119
+
120
+ `relationWrap` is one surface's answer; the `RelationLink` atom is your app's answer everywhere else ([atoms](atoms.md)).
121
+
122
+ ## Printing a value as text
123
+
124
+ A footer total, a column menu's live preview or a server-rendered email need the value as a string, not an element. `formatDateValue` and `formatNumberValue` are those strings, the same ones the cells draw, and the door carries no client directive, so a server module imports them as they are.
125
+
126
+ Both read a viewer: who is reading, in which locale and time zone, at what moment. `viewerFrom(conventions, messages?, now?)` builds one from the conventions you hand fields: their locale, zone, region and wording, with the package's words unless you hand a resolver and the current moment unless you hand one.
127
+
128
+ ```ts
129
+ import { formatDateValue, formatNumberValue, viewerFrom } from "@viewkitjs/views/display";
130
+
131
+ const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
132
+ const now = new Date("2026-09-27T12:00:00Z");
133
+ const viewer = viewerFrom(conventions, undefined, now);
134
+ assert.equal(viewer.timeZone, "Europe/Bucharest");
135
+ ```
136
+
137
+ `formatDateValue(value, dateStyle, withTime?, kind?, options?)` prints a day (`kind: "date"`, a `YYYY-MM-DD` key) or an instant (`"datetime"`, the default). `short` leaves the year off when it is the viewer's current one, `long` always carries it, `numeric` is day, month and year in digits, and a time trails after a comma, in the viewer's zone. `relative` measures a day by calendar days and an instant by elapsed time.
138
+
139
+ ```ts
140
+ assert.equal(formatDateValue("2026-09-24", "short", false, "date", { viewer }), "24 Sep");
141
+ assert.equal(formatDateValue("2025-12-03", "short", false, "date", { viewer }), "03 Dec 2025");
142
+ assert.equal(formatDateValue("2026-09-24", "long", false, "date", { viewer }), "24 September 2026");
143
+ assert.equal(formatDateValue("2026-09-04", "numeric", false, "date", { viewer }), "04/09/2026");
144
+
145
+ // An instant reads in the viewer's zone: 14:05 UTC is 17:05 in Bucharest in September.
146
+ assert.equal(formatDateValue(new Date("2026-09-24T14:05:00Z"), "short", true, "datetime", { viewer }), "24 Sep, 17:05");
147
+
148
+ assert.equal(formatDateValue("2026-09-26", "relative", false, "date", { viewer }), "yesterday");
149
+ assert.equal(formatDateValue("2026-09-30", "relative", false, "date", { viewer }), "in 3d");
150
+ assert.equal(formatDateValue(new Date(now.getTime() - 5 * 60_000), "relative", false, "datetime", { viewer }), "5m ago");
151
+
152
+ // A value that doesn't parse reads as itself.
153
+ assert.equal(formatDateValue("soon", "short", false, "datetime", { viewer }), "soon");
154
+ ```
155
+
156
+ Handed no viewer, a formatter reads the neutral conventions (`en-GB`, UTC), never the runtime's locale or zone, so a server prints the same thing wherever it runs. Pass the viewer whenever you have one:
157
+
158
+ ```ts
159
+ const lateUtc = new Date("2026-09-30T23:30:00Z");
160
+ assert.equal(formatDateValue(lateUtc, "numeric", false, "datetime"), "30/09/2026");
161
+ assert.equal(formatDateValue(lateUtc, "numeric", false, "datetime", { viewer }), "01/10/2026");
162
+ ```
163
+
164
+ `formatNumberValue(value, format?, options?)` prints a number in the style its format names: plain (the default), duration, percent or currency. The format is a number field's own, or `{ style: "percent" }` or `{ style: "currency", currency }` for the other two types (`NumberLikeFormat`). The options' `decimals`, `currency` and `durationStyle` win over the format. A percent is printed as it is stored; a duration reads its value in milliseconds, or seconds when its format says `unit: "s"`, and picks its own precision; a currency with no code anywhere is `EUR`.
165
+
166
+ ```ts
167
+ assert.equal(formatNumberValue(1234.5, undefined, { viewer }), "1,234.5");
168
+ assert.equal(formatNumberValue(1200, { style: "currency", currency: "EUR" }, { viewer }), "€1,200.00");
169
+ assert.equal(formatNumberValue(1200, { style: "currency", currency: "EUR" }, { viewer, decimals: 0 }), "€1,200");
170
+ assert.equal(formatNumberValue(45, { style: "percent" }, { viewer }), "45%");
171
+ assert.equal(formatNumberValue(5_904_000, { style: "duration" }), "98m 24s");
172
+ assert.equal(formatNumberValue(90, { style: "duration", unit: "s" }), "1m 30s");
173
+ assert.equal(formatNumberValue(12, { signed: true }, { viewer }), "+ 12");
174
+ assert.equal(formatNumberValue(-3, { signed: true }, { viewer }), "− 3"); // a true minus sign
175
+ ```
176
+
177
+ Month names and the relative words ("today", "in 3d", "just now") come from the viewer's `messages`, the package's `views.display.*` keys; "5m ago" is fields' own `time.ago`, from the viewer's `fieldMessages`. Hand `viewerFrom` your resolver, and the provider your `messages`, to word them in your language ([the provider](the-provider.md)).
178
+
179
+ ## Your own presentation
180
+
181
+ Every number, duration and date the display prints goes through a `FieldPresentation`: `message`, `number`, `duration`, `calendarDay`, `instant`, `relativeCalendarDay` and `relativeInstant`, each handed the viewer. `DEFAULT_FIELD_PRESENTATION` is the package's. To change how a value reads across your app, start from it and replace what differs:
182
+
183
+ ```ts
184
+ import { DEFAULT_FIELD_PRESENTATION, type FieldPresentation } from "@viewkitjs/views/display";
185
+
186
+ // Days as their ISO key, everything else as the package prints it.
187
+ function appPresentation(defaults: FieldPresentation): FieldPresentation {
188
+ return { ...defaults, calendarDay: ({ day }) => day };
189
+ }
190
+
191
+ const isoDays = appPresentation(DEFAULT_FIELD_PRESENTATION);
192
+ assert.equal(formatDateValue("2026-09-24", "long", false, "date", { presentation: isoDays, viewer }), "2026-09-24");
193
+ assert.equal(formatNumberValue(1234.5, undefined, { presentation: isoDays, viewer }), "1,234.5");
194
+ ```
195
+
196
+ Hand the function itself to the provider, `<ViewsProvider presentation={appPresentation}>`: the provider calls it with the defaults where a value is drawn, so your provider module imports none of the display. Declare it at module level, so it stays the same function between renders. A `presentation` or `viewer` in one call's `DisplayOptions` wins over the provider's; the string formatters, called outside React, take theirs only from their options.
197
+
198
+ ## Next
199
+
200
+ - [Atoms](atoms.md): the tag, badge, tick box and relation link the display draws through
201
+ - [Cells](cells.md): how a grid column fills `DisplayOptions` for each cell
202
+ - [The provider](the-provider.md): your conventions, words and presentation
203
+ - [The display reference](../reference/display.md): every name the door exports