@viewkitjs/views 0.2.0 → 0.3.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 (292) hide show
  1. package/CHANGELOG.md +571 -0
  2. package/README.md +5 -3
  3. package/dist/atoms/LoadMore.js +11 -1
  4. package/dist/atoms/RowMenu.js +5 -2
  5. package/dist/cells/cell-format.d.ts +3 -3
  6. package/dist/cells/cell-title.d.ts +1 -2
  7. package/dist/cells/cell-title.js +2 -2
  8. package/dist/cells/cell-values.js +6 -3
  9. package/dist/contract.d.ts +50 -9
  10. package/dist/contract.js +33 -5
  11. package/dist/display/converted.d.ts +19 -0
  12. package/dist/display/converted.js +12 -0
  13. package/dist/display/index.d.ts +1 -0
  14. package/dist/display/index.js +1 -0
  15. package/dist/display/link-click.d.ts +11 -0
  16. package/dist/display/link-click.js +3 -0
  17. package/dist/display/link.js +7 -3
  18. package/dist/display/multi-value.d.ts +1 -1
  19. package/dist/display/multi-value.js +1 -1
  20. package/dist/display/options.d.ts +7 -1
  21. package/dist/display/phone.js +3 -1
  22. package/dist/editors/ChipsEditor.d.ts +9 -4
  23. package/dist/editors/ChipsEditor.js +6 -2
  24. package/dist/editors/DateEditor.d.ts +21 -6
  25. package/dist/editors/DateEditor.js +118 -30
  26. package/dist/editors/EditorPanel.d.ts +61 -0
  27. package/dist/editors/EditorPanel.js +54 -0
  28. package/dist/editors/LocationEditor.d.ts +3 -0
  29. package/dist/editors/LocationEditor.js +14 -6
  30. package/dist/editors/NameEditor.d.ts +3 -0
  31. package/dist/editors/NameEditor.js +11 -7
  32. package/dist/editors/NumberEditor.d.ts +3 -0
  33. package/dist/editors/NumberEditor.js +6 -6
  34. package/dist/editors/RangeEditor.d.ts +16 -1
  35. package/dist/editors/RangeEditor.js +21 -5
  36. package/dist/editors/RelationEditor.d.ts +13 -28
  37. package/dist/editors/RelationEditor.js +17 -40
  38. package/dist/editors/RelationSetEditor.d.ts +53 -0
  39. package/dist/editors/RelationSetEditor.js +112 -0
  40. package/dist/editors/SelectEditor.d.ts +21 -3
  41. package/dist/editors/SelectEditor.js +55 -9
  42. package/dist/editors/TextEditor.d.ts +51 -0
  43. package/dist/editors/TextEditor.js +81 -0
  44. package/dist/editors/ValueListEditor.d.ts +3 -0
  45. package/dist/editors/ValueListEditor.js +4 -2
  46. package/dist/editors/edit-cores.d.ts +12 -9
  47. package/dist/editors/edit-cores.js +7 -6
  48. package/dist/editors/edit-session.d.ts +21 -11
  49. package/dist/editors/edit-session.js +19 -5
  50. package/dist/editors/keep-inside.d.ts +12 -0
  51. package/dist/editors/keep-inside.js +20 -0
  52. package/dist/editors/open-value.d.ts +21 -0
  53. package/dist/editors/open-value.js +36 -0
  54. package/dist/editors/open-values.d.ts +4 -0
  55. package/dist/editors/open-values.js +7 -0
  56. package/dist/editors/relation-kinds.d.ts +7 -0
  57. package/dist/editors/relation-kinds.js +21 -0
  58. package/dist/editors/relation-panel.d.ts +69 -0
  59. package/dist/editors/relation-panel.js +40 -0
  60. package/dist/field-row/FieldNoteLine.d.ts +14 -0
  61. package/dist/field-row/FieldNoteLine.js +14 -0
  62. package/dist/field-row/FieldRow.d.ts +73 -0
  63. package/dist/field-row/FieldRow.js +157 -0
  64. package/dist/field-row/FieldRowLane.d.ts +19 -0
  65. package/dist/field-row/FieldRowLane.js +11 -0
  66. package/dist/field-row/editors/RowChipsEditor.d.ts +11 -0
  67. package/dist/field-row/editors/RowChipsEditor.js +25 -0
  68. package/dist/field-row/editors/RowDateEditor.d.ts +16 -0
  69. package/dist/field-row/editors/RowDateEditor.js +18 -0
  70. package/dist/field-row/editors/RowEditor.d.ts +39 -0
  71. package/dist/field-row/editors/RowEditor.js +64 -0
  72. package/dist/field-row/editors/RowNameEditor.d.ts +4 -0
  73. package/dist/field-row/editors/RowNameEditor.js +15 -0
  74. package/dist/field-row/editors/RowNumberEditor.d.ts +12 -0
  75. package/dist/field-row/editors/RowNumberEditor.js +18 -0
  76. package/dist/field-row/editors/RowPlaceEditor.d.ts +8 -0
  77. package/dist/field-row/editors/RowPlaceEditor.js +18 -0
  78. package/dist/field-row/editors/RowRangeEditor.d.ts +4 -0
  79. package/dist/field-row/editors/RowRangeEditor.js +15 -0
  80. package/dist/field-row/editors/RowRelationEditor.d.ts +20 -0
  81. package/dist/field-row/editors/RowRelationEditor.js +77 -0
  82. package/dist/field-row/editors/RowSelectEditor.d.ts +13 -0
  83. package/dist/field-row/editors/RowSelectEditor.js +23 -0
  84. package/dist/field-row/editors/RowTextEditor.d.ts +15 -0
  85. package/dist/field-row/editors/RowTextEditor.js +16 -0
  86. package/dist/field-row/editors/RowValueListEditor.d.ts +4 -0
  87. package/dist/field-row/editors/RowValueListEditor.js +21 -0
  88. package/dist/field-row/editors/host.d.ts +59 -0
  89. package/dist/field-row/editors/host.js +1 -0
  90. package/dist/field-row/editors/row-session.d.ts +49 -0
  91. package/dist/field-row/editors/row-session.js +49 -0
  92. package/dist/field-row/index.d.ts +5 -0
  93. package/dist/field-row/index.js +5 -0
  94. package/dist/field-row/row-target.d.ts +20 -0
  95. package/dist/field-row/row-target.js +3 -0
  96. package/dist/field-row/useFieldWrite.d.ts +45 -0
  97. package/dist/field-row/useFieldWrite.js +190 -0
  98. package/dist/field-row/useRowSettlement.d.ts +33 -0
  99. package/dist/field-row/useRowSettlement.js +23 -0
  100. package/dist/fields/binding.d.ts +6 -1
  101. package/dist/fields/binding.js +13 -6
  102. package/dist/fields/edit-core-types.d.ts +9 -9
  103. package/dist/fields/edit-core-types.js +6 -6
  104. package/dist/fields/money.d.ts +5 -0
  105. package/dist/fields/money.js +10 -0
  106. package/dist/fields/number-edit.d.ts +6 -0
  107. package/dist/fields/number-edit.js +4 -0
  108. package/dist/fields/prepare-write.js +6 -1
  109. package/dist/fields/relation-source-types.d.ts +12 -0
  110. package/dist/fields/write-target.d.ts +50 -0
  111. package/dist/fields/write-target.js +10 -0
  112. package/dist/grid/chrome/GridAddColumn.js +1 -1
  113. package/dist/grid/chrome/GridAggregateMenu.d.ts +1 -1
  114. package/dist/grid/chrome/GridAggregateMenu.js +8 -6
  115. package/dist/grid/chrome/GridCellEditors.d.ts +7 -0
  116. package/dist/grid/chrome/GridCellEditors.js +87 -16
  117. package/dist/grid/chrome/GridCellOutline.d.ts +22 -43
  118. package/dist/grid/chrome/GridCellOutline.js +2 -7
  119. package/dist/grid/chrome/GridChipsEditor.d.ts +16 -6
  120. package/dist/grid/chrome/GridChipsEditor.js +21 -26
  121. package/dist/grid/chrome/GridColumnMenu.d.ts +1 -1
  122. package/dist/grid/chrome/GridColumnMenu.js +7 -3
  123. package/dist/grid/chrome/GridDateEditor.d.ts +23 -11
  124. package/dist/grid/chrome/GridDateEditor.js +13 -25
  125. package/dist/grid/chrome/GridFooter.d.ts +12 -2
  126. package/dist/grid/chrome/GridFooter.js +10 -6
  127. package/dist/grid/chrome/GridGroupMenu.js +20 -13
  128. package/dist/grid/chrome/GridHeader.d.ts +9 -4
  129. package/dist/grid/chrome/GridHeader.js +15 -10
  130. package/dist/grid/chrome/GridLongTextEditor.d.ts +28 -9
  131. package/dist/grid/chrome/GridLongTextEditor.js +16 -74
  132. package/dist/grid/chrome/GridNameEditor.d.ts +11 -6
  133. package/dist/grid/chrome/GridNameEditor.js +12 -27
  134. package/dist/grid/chrome/GridNumberEditor.d.ts +20 -6
  135. package/dist/grid/chrome/GridNumberEditor.js +46 -20
  136. package/dist/grid/chrome/GridPlaceEditor.d.ts +26 -0
  137. package/dist/grid/chrome/GridPlaceEditor.js +22 -0
  138. package/dist/grid/chrome/GridRangeEditor.d.ts +15 -5
  139. package/dist/grid/chrome/GridRangeEditor.js +16 -20
  140. package/dist/grid/chrome/GridRelationEditor.d.ts +38 -14
  141. package/dist/grid/chrome/GridRelationEditor.js +86 -24
  142. package/dist/grid/chrome/GridRow.d.ts +7 -1
  143. package/dist/grid/chrome/GridRow.js +57 -14
  144. package/dist/grid/chrome/GridRowActions.js +1 -1
  145. package/dist/grid/chrome/GridRowCells.js +18 -23
  146. package/dist/grid/chrome/GridSelectEditor.d.ts +19 -4
  147. package/dist/grid/chrome/GridSelectEditor.js +21 -27
  148. package/dist/grid/chrome/GridStructure.d.ts +9 -10
  149. package/dist/grid/chrome/GridStructure.js +10 -14
  150. package/dist/grid/chrome/GridTable.js +97 -30
  151. package/dist/grid/chrome/GridTableSurface.d.ts +39 -2
  152. package/dist/grid/chrome/GridTableSurface.js +12 -3
  153. package/dist/grid/chrome/GridTextEditor.d.ts +35 -1
  154. package/dist/grid/chrome/GridTextEditor.js +35 -37
  155. package/dist/grid/chrome/GridValueListEditor.d.ts +15 -3
  156. package/dist/grid/chrome/GridValueListEditor.js +10 -27
  157. package/dist/grid/chrome/cell-cut-off.d.ts +11 -0
  158. package/dist/grid/chrome/cell-cut-off.js +20 -0
  159. package/dist/grid/chrome/cells.js +1 -2
  160. package/dist/grid/chrome/checks.d.ts +2 -5
  161. package/dist/grid/chrome/checks.js +15 -5
  162. package/dist/grid/chrome/editors.d.ts +1 -1
  163. package/dist/grid/chrome/editors.js +1 -1
  164. package/dist/grid/chrome/grid-cell-classes.d.ts +2 -8
  165. package/dist/grid/chrome/grid-cell-classes.js +10 -8
  166. package/dist/grid/chrome/grid-cell-link.d.ts +13 -0
  167. package/dist/grid/chrome/grid-cell-link.js +9 -0
  168. package/dist/grid/chrome/grid-edit-session.d.ts +63 -0
  169. package/dist/grid/chrome/grid-edit-session.js +118 -0
  170. package/dist/grid/chrome/grid-hover.d.ts +60 -0
  171. package/dist/grid/chrome/grid-hover.js +81 -0
  172. package/dist/grid/chrome/grid-menu-focus.d.ts +43 -0
  173. package/dist/grid/chrome/grid-menu-focus.js +93 -0
  174. package/dist/grid/chrome/grid-row-menu-key.d.ts +15 -0
  175. package/dist/grid/chrome/grid-row-menu-key.js +36 -0
  176. package/dist/grid/chrome/grid-row-props.d.ts +16 -4
  177. package/dist/grid/chrome/grid-row-window.d.ts +61 -0
  178. package/dist/grid/chrome/grid-row-window.js +212 -0
  179. package/dist/grid/chrome/grid-scroll-owner.d.ts +38 -0
  180. package/dist/grid/chrome/grid-scroll-owner.js +75 -0
  181. package/dist/grid/chrome/grid-styles.d.ts +4 -1
  182. package/dist/grid/chrome/grid-styles.js +1 -0
  183. package/dist/grid/chrome/grid-table-props.d.ts +2 -3
  184. package/dist/grid/chrome/useGridFocus.d.ts +45 -0
  185. package/dist/grid/chrome/useGridFocus.js +122 -0
  186. package/dist/grid/chrome/useGridKeyboard.d.ts +21 -4
  187. package/dist/grid/chrome/useGridKeyboard.js +214 -38
  188. package/dist/grid/chrome/useGridRangeActions.d.ts +3 -1
  189. package/dist/grid/chrome/useGridRangeActions.js +17 -10
  190. package/dist/grid/chrome/useGridRangeGestures.js +68 -21
  191. package/dist/grid/chrome/useGridRowContextMenu.d.ts +4 -2
  192. package/dist/grid/chrome/useGridRowContextMenu.js +28 -2
  193. package/dist/grid/chrome/useGridScaleStyles.d.ts +3 -1
  194. package/dist/grid/chrome/useGridScaleStyles.js +6 -7
  195. package/dist/grid/chrome/useGridScrollArea.d.ts +21 -0
  196. package/dist/grid/chrome/useGridScrollArea.js +65 -0
  197. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +28 -5
  198. package/dist/grid/chrome/useGridTableInteractionModel.js +66 -14
  199. package/dist/grid/chrome/useHeaderDragReorder.d.ts +2 -2
  200. package/dist/grid/core/clipboard-model.d.ts +2 -0
  201. package/dist/grid/core/clipboard-model.js +1 -1
  202. package/dist/grid/core/commit-model.d.ts +7 -0
  203. package/dist/grid/core/edge-scroll.d.ts +21 -0
  204. package/dist/grid/core/edge-scroll.js +23 -0
  205. package/dist/grid/core/editing-controller.d.ts +2 -1
  206. package/dist/grid/core/editing-controller.js +35 -9
  207. package/dist/grid/core/editing-model.d.ts +9 -0
  208. package/dist/grid/core/editing-model.js +12 -0
  209. package/dist/grid/core/flat-rows.d.ts +35 -0
  210. package/dist/grid/core/flat-rows.js +20 -0
  211. package/dist/grid/core/grid-aria.d.ts +27 -0
  212. package/dist/grid/core/grid-aria.js +39 -0
  213. package/dist/grid/core/grid-focus.d.ts +54 -0
  214. package/dist/grid/core/grid-focus.js +148 -0
  215. package/dist/grid/core/nav.d.ts +2 -2
  216. package/dist/grid/core/pending-reconciliation.d.ts +3 -0
  217. package/dist/grid/core/pending-reconciliation.js +5 -3
  218. package/dist/grid/core/row-window.d.ts +40 -0
  219. package/dist/grid/core/row-window.js +43 -0
  220. package/dist/grid/core/spreadsheet-operations.d.ts +17 -1
  221. package/dist/grid/core/spreadsheet-operations.js +33 -6
  222. package/dist/grid/core/useGridEditing.d.ts +3 -0
  223. package/dist/grid/core/useGridEditing.js +6 -3
  224. package/dist/grid/core/value-equality.d.ts +23 -1
  225. package/dist/grid/core/value-equality.js +46 -0
  226. package/dist/grid/useGridTablePrefs.d.ts +0 -1
  227. package/dist/grid/useGridTablePrefs.js +1 -3
  228. package/dist/index.d.ts +1 -0
  229. package/dist/index.js +1 -0
  230. package/dist/internal/viewport.d.ts +0 -2
  231. package/dist/internal/viewport.js +0 -14
  232. package/dist/model/column-capabilities.d.ts +2 -1
  233. package/dist/model/column-capabilities.js +28 -8
  234. package/dist/model/column-from.js +3 -0
  235. package/dist/model/column-inspect.d.ts +10 -2
  236. package/dist/model/column-inspect.js +9 -0
  237. package/dist/model/column-schema.d.ts +6 -1
  238. package/dist/model/column-types.d.ts +3 -1
  239. package/dist/model/column-types.js +1 -1
  240. package/dist/model/preferences.d.ts +0 -4
  241. package/dist/model/preferences.js +0 -1
  242. package/dist/model/prefs-buckets.d.ts +0 -1
  243. package/dist/model/prefs-buckets.js +0 -3
  244. package/dist/model/render-count.d.ts +6 -0
  245. package/dist/model/render-count.js +11 -0
  246. package/dist/provider/ViewsProvider.d.ts +5 -1
  247. package/dist/provider/ViewsProvider.js +9 -3
  248. package/dist/provider/components.d.ts +19 -1
  249. package/dist/provider/components.js +4 -2
  250. package/dist/provider/context.d.ts +5 -2
  251. package/dist/provider/desktop.d.ts +9 -0
  252. package/dist/provider/desktop.js +22 -0
  253. package/dist/provider/plain-input.d.ts +8 -0
  254. package/dist/provider/plain-input.js +5 -0
  255. package/dist/react.d.ts +2 -1
  256. package/dist/react.js +1 -0
  257. package/dist/selection/SelectCheckbox.d.ts +3 -1
  258. package/dist/selection/SelectCheckbox.js +2 -2
  259. package/dist/selection/useCheckDragSelect.js +6 -5
  260. package/docs/contract.md +93 -35
  261. package/docs/guides/atoms.md +1 -1
  262. package/docs/guides/cells.md +2 -2
  263. package/docs/guides/columns.md +3 -2
  264. package/docs/guides/display.md +1 -0
  265. package/docs/guides/editors.md +71 -13
  266. package/docs/guides/the-grid.md +32 -13
  267. package/docs/guides/the-provider.md +3 -1
  268. package/docs/index.md +3 -1
  269. package/docs/install.md +1 -1
  270. package/docs/reference/cells.md +1 -1
  271. package/docs/reference/display.md +3 -1
  272. package/docs/reference/editors-chips.md +2 -2
  273. package/docs/reference/editors-date.md +3 -3
  274. package/docs/reference/editors-location.md +1 -1
  275. package/docs/reference/editors-number.md +1 -1
  276. package/docs/reference/editors-open-values.md +1 -0
  277. package/docs/reference/editors-panel.md +12 -0
  278. package/docs/reference/editors-range.md +1 -1
  279. package/docs/reference/editors-relation.md +6 -3
  280. package/docs/reference/editors-select.md +3 -2
  281. package/docs/reference/editors-session.md +4 -2
  282. package/docs/reference/editors-text.md +9 -0
  283. package/docs/reference/editors-value-list.md +1 -1
  284. package/docs/reference/editors.md +2 -2
  285. package/docs/reference/field-row.md +16 -0
  286. package/docs/reference/grid.md +3 -3
  287. package/docs/reference/react.md +8 -5
  288. package/docs/reference/views.md +36 -15
  289. package/package.json +23 -4
  290. package/skills/views/SKILL.md +4 -4
  291. package/dist/grid/chrome/useGridScrollSync.d.ts +0 -38
  292. package/dist/grid/chrome/useGridScrollSync.js +0 -176
@@ -92,6 +92,7 @@ const deal: Deal = {
92
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
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
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
+ - `region(row)`: the record's country, where a phone typed, pasted or filled without its country code is read: `prepareFieldWrite`, the grid's write gate and its editors read it. Absent, your conventions' region reads it.
95
96
  - `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
97
  - `icon`: your own icon name for the field, drawn by your `AppIcon`; the type's glyph when absent.
97
98
  - `labels: false`: on a field that holds several values, this row keeps only the values, so its editor offers no label box.
@@ -198,7 +199,7 @@ assert.deepEqual(prepareFieldWrite(DEAL_BINDINGS.stage, { ...deal, value: null }
198
199
  - a `history` without a `write`;
199
200
  - a `unit` on anything but a currency or a number, and a writable per-row-currency amount without one;
200
201
  - `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 `create` row on a member field (a member is invited, not created), on anything but a relation, and without a `write`;
202
203
  - a ratio formula without its `ratio` readers, and `ratio` readers on anything else;
203
204
  - `labels` on a field that holds one value.
204
205
 
@@ -233,7 +234,7 @@ assert.throws(
233
234
  - `align`: `"right"` for a figure (a number, a percent, an amount), so a column of them reads down the decimal point.
234
235
  - `editable`: `true` when the binding is writable and the type has an editor (or is a boolean, which writes from its display).
235
236
  - `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
+ - the readers, carried from the binding: `accessor` from `read`, `editAccessor` from `editRead`, `editUnit` and `currencyAccessor` from `unit`, `region` from `region`, `relation` from the candidates.
237
238
  - `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
 
239
240
  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).
@@ -92,6 +92,7 @@ A field says what the value is. The rest arrives in `DisplayOptions`, from the s
92
92
  - A boolean's verbs and words: `onToggle`, `booleanDisabled`, `booleanIcon`, `marker`, `markerReason` and `onResolve`.
93
93
  - A relation's: `entityIcon` and `relationWrap`.
94
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
+ - `hostOwnsPlainClick`, for a host whose plain click on a value is its own, as the grid's click selects its cell: an email, phone, url or domain stays a link, marked `data-cell-link`, but no longer stops its click, so your host decides (the grid follows it only on a ⌘- or Ctrl-click).
95
96
  - `presentation` and `viewer`, which win over the provider's (below).
96
97
 
97
98
  The grid and the other surfaces fill these from your columns. Where you draw a value yourself, you fill them:
@@ -1,24 +1,27 @@
1
1
  # Editors and the edit session
2
2
 
3
- An editor is the panel a person changes a value in: the option list of a status, the calendar of a date, the three boxes of a name. The grid mounts them for you; this page is for when you mount one yourself, in a form field, a drawer row or a card. It covers the table that picks an editor for a type, what each editor commits, what an editor owns against what you own, the session that turns a close into one answer, an open field's values, and where a relation's candidates come from.
3
+ An editor is the panel a person changes a value in: the option list of a status, the calendar of a date, the three boxes of a name. The grid mounts them for you; this page is for when you mount one yourself, in a form field, a drawer row or a card. It covers the table that picks an editor for a type, what each editor commits, what an editor owns against what you own, the session that turns a close into one answer, an open field's values, and where a relation's candidates come from. A record's whole field row, its hosts and its write path included, is ready-made behind `@viewkitjs/views/field-row`.
4
4
 
5
5
  Every block on this page continues the one before, and the whole page runs as written.
6
6
 
7
7
  ## One editor per storage type
8
8
 
9
- `EDIT_CORES`, from `@viewkitjs/views/editors`, holds the editor for every storage type fields declares. It has a member for each type, so a type fields adds that nothing here answers fails to compile. Several types share one editor: `date` and `datetime` share the date editor, `select` and `status` the select editor, `relation` and `user` the relation editor, and `number`, `percent` and `currency` the number editor.
9
+ `EDIT_CORES`, from `@viewkitjs/views/editors`, holds the editor for every storage type fields declares. It has a member for each type, so a type fields adds that nothing here answers fails to compile. Several types share one editor: `date` and `datetime` share the date editor, `select` and `status` the select editor, `relation` and `user` the relation editor, and `number`, `percent` and `currency` the number editor; `text`, `url`, `domain`, `email`, `phone` and `rich_text` share the text editor.
10
10
 
11
- A member that is `null` is a decision: the type has no panel. `text`, `url`, `domain`, `email` and `phone` are a plain input your surface already owns; a `boolean` is edited by its checkbox; an `actor` is set by the system; `rich_text` is markdown in your own text box; `lookup`, `rollup` and `formula` are read-only or derived. `hasEditCore(type)` answers the same question; imported from the root door, `@viewkitjs/views`, it loads no editor, for a host deciding whether to wire one at all.
11
+ A member that is `null` is a decision: the type has no editor of its own. A `boolean` is edited by its checkbox; an `actor` is set by the system; `lookup`, `rollup` and `formula` are read-only or derived. `hasEditCore(type)` answers the same question; imported from the root door, `@viewkitjs/views`, it loads no editor, for a host deciding whether to wire one at all.
12
12
 
13
13
  ```tsx
14
14
  import assert from "node:assert/strict";
15
15
  import { EDIT_CORES, hasEditCore } from "@viewkitjs/views/editors";
16
16
  import { SelectEditor } from "@viewkitjs/views/editors/select";
17
+ import { TextEditor } from "@viewkitjs/views/editors/text";
17
18
 
18
19
  assert.equal(EDIT_CORES.status, EDIT_CORES.select);
19
20
  assert.equal(EDIT_CORES.select, SelectEditor);
20
21
  assert.equal(EDIT_CORES.percent, EDIT_CORES.number);
21
- assert.equal(EDIT_CORES.text, null);
22
+ assert.equal(EDIT_CORES.text, TextEditor);
23
+ assert.equal(EDIT_CORES.phone, TextEditor);
24
+ assert.equal(EDIT_CORES.boolean, null);
22
25
 
23
26
  assert.equal(hasEditCore("currency"), true);
24
27
  assert.equal(hasEditCore("boolean"), false);
@@ -34,20 +37,32 @@ What an editor hands back is a commit, which is not always the shape your row st
34
37
  | Door | Edits | Commits |
35
38
  |---|---|---|
36
39
  | `@viewkitjs/views/editors/select` | `select`, `status` | the picked option's `value`, `""` for None |
37
- | `@viewkitjs/views/editors/relation` | `relation`, `user` | the picked candidate's `id`, `null` for None |
40
+ | `@viewkitjs/views/editors/text` | `text`, `url`, `domain`, `email`, `phone`, `rich_text` | the tidied text: trimmed, rich text only at its edges |
41
+ | `@viewkitjs/views/editors/relation` | `relation`, `user` | the picked candidate's `id`, `null` for None; `RelationSetEditor`, a relation holding several records: the whole set as `RelationDraftLink[]` |
38
42
  | `@viewkitjs/views/editors/number` | `number`, `percent`, `currency` | `{ value, unit }`, the value a number or `null` |
39
43
  | `@viewkitjs/views/editors/range` | `range` | `{ low, high }`, each a number or `null` |
40
44
  | `@viewkitjs/views/editors/name` | `name` | `{ full, given, family }`, or `null` |
41
45
  | `@viewkitjs/views/editors/location` | `location` | the place's parts, or `null` |
42
46
  | `@viewkitjs/views/editors/value-list` | a `multiple` email, phone, url or domain | a list of `{ value, label, main }`, the main one first, or `null` |
43
- | `@viewkitjs/views/editors/date` | `date`, `datetime` | `YYYY-MM-DD`, or `YYYY-MM-DDTHH:MM` with a time |
47
+ | `@viewkitjs/views/editors/date` | `date`, `datetime` | `YYYY-MM-DD`, or `YYYY-MM-DDTHH:MM` with a time; `""` from its Clear row |
44
48
  | `@viewkitjs/views/editors/chips` | `multiselect` | the list of values, a `string[]` |
45
49
 
46
- The value-list editor has no member in `EDIT_CORES`: a list of emails is still an `email` field, whose single value is a plain input. Each editor's reference page has its props and its close rule in full: [select](../reference/editors-select.md), [relation](../reference/editors-relation.md), [number](../reference/editors-number.md), [range](../reference/editors-range.md), [name](../reference/editors-name.md), [location](../reference/editors-location.md), [value list](../reference/editors-value-list.md), [date](../reference/editors-date.md) and [chips](../reference/editors-chips.md).
50
+ The value-list editor has no member in `EDIT_CORES`: a list of emails is still an `email` field, whose single value is a plain input. Each editor's reference page has its props and its close rule in full: [select](../reference/editors-select.md), [text](../reference/editors-text.md), [relation](../reference/editors-relation.md), [number](../reference/editors-number.md), [range](../reference/editors-range.md), [name](../reference/editors-name.md), [location](../reference/editors-location.md), [value list](../reference/editors-value-list.md), [date](../reference/editors-date.md) and [chips](../reference/editors-chips.md).
51
+
52
+ ## A text box
53
+
54
+ `TextEditor`, from `@viewkitjs/views/editors/text`, is the one box for every text-like value: text, a link, an email, a phone, a domain, long text and rich text. It tidies what was typed (trimmed; rich text tidied only at its edges, so its first line keeps its indent), answers `noop` when the tidied text equals the tidied stored value, and brings each type's own phone keyboard (`TEXT_INPUT_TYPE`: a phone `tel`, an email `email`, a link or a domain `url`). A line closes on Enter; a paragraph (`multiline`, the default for rich text) takes Enter as a newline and closes on ⌘ or Ctrl Enter. Escape discards, Tab and Shift-Tab close with their reason, and leaving the box closes it unless you pass `closeOnBlur={false}`, which a host inside a popover or a sheet does, so a tap on ✕ or ✓ is not a close. A line draws through your `Input`; a paragraph is the package's own textarea.
55
+
56
+ ```tsx
57
+ import { TEXT_INPUT_TYPE } from "@viewkitjs/views/editors/text";
58
+
59
+ assert.equal(TEXT_INPUT_TYPE.phone, "tel");
60
+ assert.equal(TEXT_INPUT_TYPE.domain, "url");
61
+ ```
47
62
 
48
63
  ## What an editor owns, and what you own
49
64
 
50
- An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar and decides that every close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
65
+ An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar and decides that Escape discards and every other close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
51
66
 
52
67
  The two speak through one handshake, the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`:
53
68
 
@@ -61,9 +76,9 @@ What an editor never does on its own (write, fetch, toast, decide the popover) i
61
76
 
62
77
  Every host that opens a panel over a value repeats two things, and both are easy to get wrong without seeing it. A close can arrive more than once (your popover reports an Escape, then the closed state it caused), and a session that answers twice writes twice. And the popover has an exit animation: answering at once re-renders the value behind it and unmounts the panel mid-animation.
63
78
 
64
- `useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. It gives you two ways to hear the answer:
79
+ `useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. Escape always throws the edit away: on `close("escape")` the session answers a cancel without asking the editor. It gives you two ways to hear the answer:
65
80
 
66
- - `onAttempt(resolution)` and `onClose()`: the answer is asked synchronously, the moment the close happens, and you send the write right there. Return `{ accepted: false }` to refuse it: the panel stays open, and the next close asks again. On `{ accepted: true }` the popover closes, and `onClose` runs after the exit gap to finish the visual close. Prefer this one.
81
+ - `onAttempt(resolution)` and `onClose()`: the answer is asked synchronously, the moment the close happens, and you send the write right there. Return `{ accepted: false, reason }` to refuse it: the panel stays open, the session hands the reason back as `refusal` until the next attempt, and the next close asks again. On `{ accepted: true }` the popover closes, and `onClose` runs after the exit gap to finish the visual close. Prefer this one.
67
82
  - `onDone(resolution)`: the whole answer, the write included, arrives after the exit gap.
68
83
 
69
84
  The gap is `EDITOR_EXIT_MS` unless you pass `exitMs`. `mapPayload` reshapes a commit before it reaches you, and only a commit: a host that offers None maps the select's `""` to `null` with `mapPayload: (value) => (value === "" ? null : value)`.
@@ -168,7 +183,7 @@ const icons = Object.fromEntries(
168
183
  ) as ViewsIcons;
169
184
  ```
170
185
 
171
- `pickerOptionsFromField` dresses a select's or a status's options the way its cells draw them, so the panel looks like the grid: a status keeps each option's slot, a select takes its category colour. Archived options are left out.
186
+ `pickerOptionsFromField` dresses a select's or a status's options the way its cells draw them, so the panel looks like the grid: a status keeps each option's slot, a select takes its category colour. Archived options are left out. Pass `current`, the value your surface holds, and it is offered after the options when none of them is it, so its own list shows it checked; it is never offered to another record's list.
172
187
 
173
188
  ```tsx
174
189
  import { pickerOptionsFromField, type SelectEditorHandle } from "@viewkitjs/views/editors/select";
@@ -256,6 +271,49 @@ assert.ok(stageHtml.includes("data-chosen")); // the stage the deal holds is che
256
271
 
257
272
  A pick of Won calls `close("pick")`; the editor answers `{ kind: "commit", payload: "won" }`, `saveDeal` sends `{ stage: "won" }`, and 160 milliseconds later `onClosed` runs. A pick of New, which the deal already holds, answers `noop`, and an outside press or Escape answers `cancel`: nothing is sent either way, and the popover still closes.
258
273
 
274
+ ## The panel: a popover on the desktop, a sheet on the phone
275
+
276
+ The host above draws its own popover, so on a phone it still opens a popover. `EditorPanel`, from `@viewkitjs/views/editors/panel`, opens the same editor in your `Popover` on a desktop and your `Sheet` on a phone, by the provider's `desktopQuery` (`(min-width: 1024px)` unless you hand in your own), chosen once when the session opens. It routes every dismissal to the session, so each means the same on every surface:
277
+
278
+ - **Desktop:** the popover's Escape discards. A press outside closes with `"outside"`, which the editor answers by its own rule. A focus leaving the popover with no press (a Tab out of it) closes with `"blur"`, so a host that spends the click after an outside press spends none here. Once the session has closed, a press on the popover while it plays its exit is reported to nothing.
279
+ - **Phone:** the sheet carries the field's name as its title, and a bar with ✕ and ✓. ✕, a swipe and the backdrop change nothing. ✓ closes as done, and a pick in a select saves on its own.
280
+ - **Refusals:** a value your `onAttempt` refuses with a `reason` stays open, and the reason is drawn under the editor.
281
+
282
+ A type-in editor passes `inPlace`: it stays where the value stands, and goes into the sheet on a phone only when its host passes `sheetOnPhone`. The same stage, refusing Lost until the deal has a reason:
283
+
284
+ ```tsx
285
+ import { EditorPanel } from "@viewkitjs/views/editors/panel";
286
+
287
+ function DealStagePanel({ deal, anchor, onClosed }: { deal: Deal; anchor: RefObject<HTMLElement | null>; onClosed: () => void }) {
288
+ const editorRef = useRef<SelectEditorHandle>(null);
289
+ const session = useAnchoredEditSession<string>({
290
+ editorRef,
291
+ onAttempt: (resolution) => {
292
+ if (resolution.kind !== "commit") return { accepted: true };
293
+ if (resolution.payload === "lost") return { accepted: false, reason: "A lost deal needs a reason first" };
294
+ saveDeal(deal.id, { stage: resolution.payload }).catch(showSaveFailed);
295
+ return { accepted: true };
296
+ },
297
+ onClose: onClosed,
298
+ });
299
+
300
+ return (
301
+ <EditorPanel session={session} title="Stage" anchor={anchor} align="start" initialFocus={false} chrome="menu">
302
+ <SelectEditor ref={editorRef} options={stageOptions} initial={deal.stage} onRequestClose={session.close} />
303
+ </EditorPanel>
304
+ );
305
+ }
306
+
307
+ // A server render can't ask the screen, so it draws the desktop's popover.
308
+ const panelHtml = renderToStaticMarkup(
309
+ <ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions}>
310
+ <DealStagePanel deal={acme} anchor={{ current: null }} onClosed={() => {}} />
311
+ </ViewsProvider>
312
+ );
313
+
314
+ assert.ok(panelHtml.includes("Won") && panelHtml.includes("Lost"));
315
+ ```
316
+
259
317
  ## An open field's values
260
318
 
261
319
  An open select or multiselect (`vocabulary: "custom-values"`) has no closed list of options: its values are whatever its records hold, which only your app's data can answer. `OpenValuesProvider`, from `@viewkitjs/views/editors/open-values`, carries them to every editor of the field below it, so a field offers the same values in the grid, a form and a card.
@@ -394,11 +452,11 @@ function CompanyPanel({
394
452
  }
395
453
  ```
396
454
 
397
- On a binding, `relation` carries the same source, and the grid hands it to this editor when a relation cell opens.
455
+ On a binding, `relation` carries the same source, and the grid hands it to this editor when a relation cell opens, or to `RelationSetEditor` when the relation holds several records.
398
456
 
399
457
  ## Next
400
458
 
401
459
  - [Cells](cells.md): drawing a column's value outside the grid
402
460
  - [The contract](../contract.md): the four shapes of a value, what an edit core never does, a command field
403
- - [The session's reference](../reference/editors-session.md) and [open values' reference](../reference/editors-open-values.md)
461
+ - [The session's reference](../reference/editors-session.md), [the panel's reference](../reference/editors-panel.md) and [open values' reference](../reference/editors-open-values.md)
404
462
  - [Getting started](../getting-started.md)
@@ -242,6 +242,7 @@ Collapsing is yours too: `isCollapsed` answers for a group's key and `onToggleGr
242
242
  Editing turns on with `onCellCommit`: without it the grid is read-only, and invites no edit. It is called with the row, the column's id, the value the editor committed and, for an undo or a redo, a `GridCommitContext`. The grid shows the value at once and keeps it while the write runs; how your function ends decides what happens next.
243
243
 
244
244
  - It resolves with nothing, or `{ status: "confirmed" }`: the write landed, and ⌘Z can undo it. `history: { prev, next }` records what undo and redo put back, when what was stored is not what the cell sent; `history: false` keeps no step for this write. `settlement: "requested"` says the row holds the value but the provider behind it has not accepted it yet: the cell keeps its value and wears the pending look until your rows carry it.
245
+ - It resolves with `{ status: "confirmed", stored }`: the write landed, but what your server kept isn't what the cell sent (it stripped an invisible character, read a label as its key, kept `""` as `null`). `stored` is the value as your rows will read it in this column. The cell shows it at once in place of what was typed, ⌘Z restores from it (unless `history` says otherwise), and when your rows carry it the cell clears without a "changed elsewhere". Leave `stored` out and nothing changes: the cell holds what was typed until your rows carry exactly that. On an undo or a redo it is ignored.
245
246
  - It resolves with `{ status: "unconfirmed", history: false }`: nothing says the write landed, and it leaves no step to undo.
246
247
  - It rejects (or throws): the cell rolls back to the value it held. Never swallow a failed request, since the rejection is what rolls the cell back.
247
248
 
@@ -334,7 +335,7 @@ function EditableDeals({ onOpen }: { onOpen: (deal: Deal) => void }) {
334
335
  }
335
336
  ```
336
337
 
337
- Before a value reaches you it has passed the grid's write gate (Editing and writes, below): a value the column refuses is said in a toast through your toast port and never sent, and in a batch a refused cell is dropped while the rest are written.
338
+ Before a value reaches you it has passed the grid's write gate (Editing and writes, below): a value the column refuses is never sent. Most refusals are said in a toast through your toast port. A select, status, date, tags, relation, number or range editor keeps the value open with its reason instead (Editing and writes, below). In a batch a refused cell is dropped while the rest are written.
338
339
 
339
340
  ## Preferences
340
341
 
@@ -363,7 +364,7 @@ function applyPrefsPatch(current: ListViewPrefs, patch: Partial<ListViewPrefs>):
363
364
  return next;
364
365
  }
365
366
 
366
- assert.deepEqual(applyPrefsPatch(LIST_VIEW_PREF_DEFAULTS, { gridWrapCells: true }).gridWrapCells, true);
367
+ assert.deepEqual(applyPrefsPatch(LIST_VIEW_PREF_DEFAULTS, { gridAlwaysCheckboxes: true }).gridAlwaysCheckboxes, true);
367
368
 
368
369
  function useDealPrefs() {
369
370
  const [prefs, setStored] = useState<ListViewPrefs>(LIST_VIEW_PREF_DEFAULTS);
@@ -392,7 +393,7 @@ function DealsWithPrefs({ onOpen }: { onOpen: (deal: Deal) => void }) {
392
393
 
393
394
  The columns' widths, order and visibility travel as `columnState`, a `ListColumnState` (`widths` by column id, `hidden` ids, `visible` ids of columns hidden by default that the person turned on, and `order`), and every change as `onColumnStateChange`; `gridProps` carries both. Resizing, moving and hiding a column, and the header's "+ Add column", which lists the hidden columns, appear only where `onColumnStateChange` is passed, since there would be nowhere to keep them. `renderAddColumn` replaces that last cell with your own, and `renderColumnMenuRows` adds your rows (Edit field, say) to a column's menu above Hide.
394
395
 
395
- `gridProps` also carries the per-person switches: `verticalBorders`, `showRowIcon` (the `rowIcon` you declare, in the title cell), `freezeIdentity` (every column through the title pinned at the left edge), `wrapCells` (up to three lines per cell), `alwaysCheckboxes` and `scale`, the density.
396
+ `gridProps` also carries the per-person switches: `verticalBorders`, `showRowIcon` (the `rowIcon` you declare, in the title cell), `freezeIdentity` (every column through the title pinned at the left edge; off in `LIST_VIEW_PREF_DEFAULTS`, so start your prefs with `gridFreezeIdentity: true` to open it on), `alwaysCheckboxes` and `scale`, the density. Every row is one height, and a cell's text stays on one line.
396
397
 
397
398
  ## Figures
398
399
 
@@ -443,7 +444,7 @@ function DealsWithFigures({ onOpen }: { onOpen: (deal: Deal) => void }) {
443
444
 
444
445
  ## The row's menu and opening a row
445
446
 
446
- A click on the title's text calls `onOpenRow`; a click anywhere else selects the cell. `rowHref` gives a row its own page: a middle-click opens it in a new tab, and the row's menu starts with Open page. `onPrefetchRow` is called on a pointer's intent to open, to warm the row's detail.
447
+ On a desktop, a click on the title's text calls `onOpenRow`, and a click anywhere else selects the cell. Below your provider's `desktopQuery`, a tap anywhere on the title's cell calls `onOpenRow`, and a tap on any other cell opens its editor (The keyboard and the pointer, below). `rowHref` gives a row its own page: a middle-click opens it in a new tab, and the row's menu starts with Open page. `onPrefetchRow` is called on a pointer's intent to open, to warm the row's detail.
447
448
 
448
449
  The row's menu opens on a right-click and from the row's ⋯ at its end. It holds the cell's Copy, Cut, Paste and Clear, the rows your `rowMenu` builds, and Delete when you pass `onRowDelete`. Delete asks your `confirm` port first, with `deleteLabel` as what is deleted, and a delete that rejects says so through your toast port. `contextMenu` replaces `rowMenu` on right-click when the two must differ.
449
450
 
@@ -492,7 +493,7 @@ function DealsWithMenus({ onOpen }: { onOpen: (deal: Deal) => void }) {
492
493
  }
493
494
  ```
494
495
 
495
- `rowActions` adds buttons to a row's title cell, and `rowClassName` a class to a row.
496
+ `rowActions` adds buttons to a row's title cell, drawn on the row under the pointer, and `rowClassName` a class to a row. Each of `rowActions` that applies to a row (a glyph, a click and a label for it) is also a row of that row's menu, after Select, so a key and a right-click reach it; one whose label your `contextMenu` already carries isn't listed twice.
496
497
 
497
498
  ## Format overrides
498
499
 
@@ -545,7 +546,7 @@ The locks constrain the interface, not access: your API still guards its own wri
545
546
 
546
547
  ## Loading more and the empty state
547
548
 
548
- A list that loads its rows a page at a time passes `loadMore`: `hasMore`, `onReveal`, called when the person reaches the end, and an optional `label`. The `LoadMore` atom draws it (the default watches a point past the last row). `renderGroupFooter` draws a group's own continuation after its loaded rows. `emptyState` is drawn under the header when there is nothing to show: no rows in an ungrouped list, no groups in a grouped one.
549
+ A list that loads its rows a page at a time passes `loadMore`: `hasMore`, `onReveal`, called when the person reaches the end, and an optional `label`. The `LoadMore` atom draws it (the default watches a point past the last row). `renderGroupFooter` draws a group's own continuation after its loaded rows. `emptyState` is drawn under the header when there is nothing to show: no rows in an ungrouped list, no groups in a grouped one. The grid keeps it to the width in view, so a table wider than its box still shows the message whole and centred where the person looks; pass it as it is, with no wrapper of your own.
549
550
 
550
551
  ```tsx
551
552
  function PagedDeals({
@@ -598,27 +599,45 @@ assert.deepEqual(gridNormalizeWrite(titleColumn, " Acme renewal ", conventions)
598
599
  assert.equal(gridNormalizeWrite(stageColumn, "maybe", conventions).ok, false);
599
600
  ```
600
601
 
601
- **A set of values.** A `multiselect` opens the chips editor: the chosen values as the cell's own badges with the input among them, the candidates below. It is a draft: adds and removes commit as one write when the panel closes, closing it unchanged writes nothing, and Escape discards it. A vocabulary that is not free-form declares `chips: { normalize }` on its column, the rule that turns what somebody typed into what the field stores.
602
+ **One of a set.** A `select` or a `status` opens the select editor: its options, the cell's value checked, and a pick saves. A column that may be emptied (`clearable`) opens with None first; a required status shows none. Delete still clears a column that may be emptied. A closed list offers its options, and the cell's own value when no option names it, so a stray value shows on the row that holds it and on no other; an open select offers the values its records hold and a row that uses the typed text. A list of more than 8 options opens with a search on top, and a letter typed on the cell opens it already filtered by that letter; a shorter list opens as it is.
602
603
 
603
- **A long text** (a `text` field with `format: { long: true }`, or rich text) opens a panel on the cell: Enter is a newline, ⌘-Enter commits and moves down, Tab commits and moves on, Escape cancels, and a click away commits. Where it cannot be written, the same panel opens read-only (`gridColumnInspectable`).
604
+ **A set of values.** A `multiselect` opens the chips editor: the chosen values as the cell's own badges with the input among them, the candidates below. It is a draft: adds and removes commit as one write when the panel closes or Tab moves on (Shift-Tab to the cell before), closing it unchanged writes nothing, and Escape discards it. Enter adds the highlighted value and keeps the panel open. A closed multiselect offers its options alone and filters them as you type, with no row to add what was typed; a value the cell already holds that no option names stays as a chip and is saved as it is. An open one offers the values on screen and adds what is typed. A vocabulary that is not free-form declares `chips: { normalize }` on its column, the rule that turns what somebody typed into what the field stores.
605
+
606
+ **A day or a moment.** A `date` opens the date editor with its date box and the calendar, no time: a click on a day saves it. A `datetime` keeps its time box (an empty time starts at 00:00) and stays open after a day click, so the time can be set; a click away or Enter saves both. Today, Tomorrow and Next Monday sit above the calendar, each setting its day as a click on the calendar does, a datetime's time kept. A column that may be emptied (`clearable`) ends the editor with a Clear row that empties the date; a required date shows none, and Delete still clears. A character typed on the cell opens the editor with it in the date box, and Enter saves the date it reads. On a phone the day and the time are in one sheet, and ✓ saves both.
607
+
608
+ **A text cell** (text, a link, an email, a phone, a domain) types in the cell through the text editor (`@viewkitjs/views/editors/text`): what was typed is trimmed, an unchanged value writes nothing, and each type brings its own phone keyboard. Enter writes and moves down, Tab writes and moves on, Escape cancels.
609
+
610
+ **A long text** (a `text` field with `format: { long: true }`, or rich text) opens a panel on the cell: Enter is a newline, ⌘ or Ctrl Enter commits and moves down, Tab commits and moves on, Escape cancels, and a click away commits. Where it cannot be written, the same panel opens read-only (`gridColumnInspectable`).
611
+
612
+ **A cut-off text** (a plain text, or a title that is text) opens whole in that panel when its cell cuts it off: a second click, a double-click or Enter shows all of it over the cell, editable where the cell can be written and read-only where it can't. It stays a line: the box wraps, Enter writes and moves down, and a newline is written as a space. Typing a character still replaces the value in the cell, and a text that fits opens in the cell as above. Links, emails, phones and domains keep their one-line box.
613
+
614
+ **On a phone** (narrower than the provider's `desktopQuery`, `(min-width: 1024px)` unless you hand in your own), a text cell and a long text open in a sheet titled with the column's header instead: ✕ and a swipe change nothing, ✓ saves and closes without moving the selection, and the save lands once the sheet has slid away.
604
615
 
605
616
  **The write gate** is `gridNormalizeWrite`, which every write the grid starts passes once: a key, the row's menu, a fill, a paste, a boolean's button. It coerces the value by the column's type, then has the column's field accept it, so a type's write rules are stated once: a marker boolean refuses any write but clear, an email or a url must look like one, a multiselect commits its whole set, trimmed and without duplicates. An emptied value passes unchecked, since `clearable` decides whether a clear may run; a clear reaches you as `""`, except a relation's `null`, a multiselect's `[]` and a boolean's `false` (Writes, above). A refusal is said in a toast and nothing is sent. Undo and redo do not pass the gate: they put a recorded value back as it was.
606
617
 
607
- **A relation** commits the id of the record picked, not the `{ id, label }` its cell draws, so the grid shows no value of its own while the write runs: the cell repaints when your rows come back. A date, a range, a name and a list of values show no value of their own while the write runs either. A place has no editor in the grid: a location column is drawn, never written there.
618
+ **A select, status, date, tags, relation, number, range, place or list-of-values editor** opens through the same panel: your `Popover` on a desktop and your `Sheet` below your `desktopQuery`. Each asks the same gate before it closes, and the list's settings too, so a column locked while its editor is open says the lock in the editor. A value the gate refuses keeps the editor open with its reason, and nothing is sent until the value changes or Escape throws the edit away. Leaving the cell while the reason stands writes nothing, and says the reason in a toast. These editors share the edit session's rules: Escape always discards, and a refused value stays open with its reason. In the place editor's country or region list, Escape first closes the list, back to its boxes. On a desktop a picker opens your `Popover` under its cell, and a number or a range is typed in the cell. Below your provider's `desktopQuery`, each opens in your `Sheet`, a number or a range included, titled with the column's header, with ✕ and ✓, while the cell behind it keeps showing its value. ✕, a swipe and Escape change nothing. ✓ saves, and so does a pick. A value is sent once its popover or sheet has played out; a number or a range typed in the cell is sent at once. A list of values whose every value was removed, or a place whose every part was emptied, on a column that isn't `clearable`, stays open saying the field can't be emptied (the column's `reasons.clearable` when it declares one); Escape still throws the edit away. The name editor still closes and says a refusal in a toast.
619
+
620
+ **The row's country.** A column's `region` (a binding's, carried by `columnFrom`) reads the record's country off the row, and a phone typed, pasted or filled without its country code is read in it, at the gate and in the editors' own check. Absent, the conventions' region reads it.
621
+
622
+ **A relation** commits what its row stores, not the `{ id, label }` its cell draws: the id of the record picked, a ref `{ kind, id }` on a field that names its kinds, or, on a relation holding several records, the whole set (ids, or links with their kind, stored role and one lead where the field leads by a flag), edited in `RelationSetEditor` with the list open and saved as one change on a click outside, Tab or the sheet's ✓. A letter typed on a relation or member cell opens its picker searching for it; on a phone the picker's sheet opens on the list with the keyboard down. A relation whose binding carries `create` offers that row under its candidates, and links what the app's form saves as a change of its own. The grid shows no value of its own while the write runs: the cell repaints when your rows come back. A date, a range, a name, a place and a list of values show no value of their own while the write runs either. A place takes no paste: a text names none of its parts.
608
623
 
609
624
  **A multi-value cell is written whole.** Your `onCellCommit` receives the whole list, never one item added or removed.
610
625
 
611
626
  ## The keyboard and the pointer
612
627
 
613
- Once a pointer has put focus in the grid, the keyboard is a spreadsheet's: the arrows and ⇧-arrows, ⌘A, Home and End, ⌘Home and ⌘End, Tab with the row wrapping, typing to replace, Enter to edit (or to flip a boolean), ⌘C, ⌘X and Delete over a range, ⌘Z and ⇧⌘Z, and pasted tab-separated text. A click selects a cell; a second click on it, a double-click or Enter opens its editor, or a long text's panel. A drag selects a range, and the dot at its corner fills it.
628
+ Tab enters the grid at its focused cell, or at the first cell on screen, and the keyboard is a spreadsheet's: the arrows and ⇧-arrows, ⌘A, Home and End, ⌘Home and ⌘End, Tab with the row wrapping, typing to replace (on a select or a status, typing starts its search), Enter to edit (or to flip a boolean), ⌘C, ⌘X and Delete over a range, ⌘Z and ⇧⌘Z, and pasted tab-separated text. On a desktop, a click selects a cell; a second click on it, a double-click or Enter opens its editor, or the panel of a long text or a cut-off text. An email, a phone, a url or a domain is part of its cell: a click on it selects the cell like any other, and a ⌘-click (Ctrl-click on Windows) follows the link. ⌘X and Delete over a range empty what may be emptied, then say in one toast which fields they left because those can't be empty (`views.grid.clear-required`). A drag selects a range, and the dot at its corner fills it. Below your provider's `desktopQuery`, one tap on a cell opens its editor in your `Sheet`, and a cell that opens nothing is selected and says why. The answer is read at the tap, so a test that clicks the grid answers your desktop query in its `matchMedia` stub to keep a desktop's clicks.
629
+
630
+ Every cell takes the browser's own focus, and the grid's keys listen on the grid itself; only ⌘Z listens on the window, so an undo works wherever focus is, and lands on the cell it changed: selected, and holding the focus unless something outside the grid has it, so the next key moves from there. Tab past the grid's last cell (Shift+Tab before its first) leaves it, and Escape with nothing open clears the cell and lets go of the grid: the next Tab or Shift+Tab leaves. The arrows also reach what surrounds the cells: ↑ from a group's first row lands on its column names, where Enter or Space opens a column's menu with focus on its first row; ↓ from its last row lands on its footer, where Enter or Space opens the figure picker; above the column names is the group's bar, where Enter, Space or ← collapse it and Enter, Space or → open it again, and → on an open bar reaches its ⋯ menu; ← from a row's first column reaches its checkbox, and Space ticks it (the select-all and a group's box the same way from the column names). On a cell, Shift+F10, the menu key, or ⌘⇧\ (Ctrl+Shift+\ off a Mac, as in Google Sheets) opens the row's menu, the one a right-click on that cell opens, under the cell; the grid sends that right-click to your `RowMenu`, and your `Menu` puts focus on its first row. Safari may keep ⌘⇧\ for its own tab overview: there, fn+Shift+F10 opens it. In a column's menu, the figure picker and a group's ⋯ menu, ↓ and ↑ move between the rows, round at either end, and Enter picks the focused one. Past eight sort choices a group's menu lists them under a search, whose own arrows walk its matches: ↓ past the last match goes on to the rows below it, and ↑ from the first of those comes back. That reads the match your `Command` has highlighted from its field's `aria-activedescendant`, as cmdk names it; a list that names none keeps its own arrows, and Tab leaves it. Escape, or a pick, closes a menu and puts focus back on its cell, after your `Popover` or `Menu` has played its exit and left the page. The keyboard, a range, a copy, a clear, a paste and a fill skip a collapsed group's rows, and collapsing a group keeps an edit open in it.
631
+
632
+ A screen reader reads the grid as a grid, or as a tree grid when it is grouped: every row is numbered among all of them (a group's bar, its column names and its footer are rows too, so the total runs a little above the record count), a cell is read with its column's name, a group's bar with its name, its count and whether it is open, and a grouped record with its place in its group. While more rows remain to load, a row reads its number with no total.
614
633
 
615
634
  ## Known gaps
616
635
 
617
- - The grid cannot be entered from the keyboard: focus starts with a pointer, there is no tab stop, and it carries no ARIA grid roles.
618
- - The rows are not virtualised: a row costs about forty nodes, so thousands of rows at once are slow.
636
+ - A row's ⋯ opens by pointer, and its menu (the name's actions among its rows) by a key on a cell (The keyboard and the pointer); a screen reader reaches the ⋯ as the row's last cell.
637
+ - Only the rows on screen are drawn, with ten more each side, so the browser's own find (⌘F) finds only those: your list's own search finds the rest. The focused row, the row being edited and a row whose checkbox holds the focus stay drawn when they scroll away.
619
638
  - On touch, a range drag and fill need a fine pointer: the fill dot is drawn only under `(hover: hover) and (pointer: fine)`.
620
639
  - A cell holding several values is written as a whole set.
621
- - Writes carry no version: when two people edit one row the last write wins, and the grid warns only when a third party's value replaced yours.
640
+ - Writes carry no version: when two people edit one row the last write wins, and the grid warns only when a third party's value replaced yours. A difference of format is not one: `null`, `""` and `[]` are all nothing, so a cell emptied to `""` that your rows read back as `null` clears without a word.
622
641
 
623
642
  ## Styling
624
643
 
@@ -4,7 +4,9 @@ Every view reads what it takes from its app, other than its own props, from one
4
4
 
5
5
  ## Mount it once
6
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`.
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`. Four more are optional: `atoms`, `messages`, `presentation` and `desktopQuery`.
8
+
9
+ `desktopQuery` says which screens are desktops: there an editor opens as a popover, and elsewhere as a sheet. It defaults to `DEFAULT_DESKTOP_QUERY`, `(min-width: 1024px)`; hand in the query your own shell switches on, so the editors and your layout change at the same width. A server render counts as a desktop.
8
10
 
9
11
  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
12
 
package/docs/index.md CHANGED
@@ -42,9 +42,11 @@ One page per door. Each lists every name the door exports.
42
42
  - [`@viewkitjs/views/react`](reference/react.md): the provider, the adapter's types, ports and atoms
43
43
  - [`@viewkitjs/views/display`](reference/display.md): a stored value drawn, and the string formatters
44
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
45
+ - [`/editors/select`](reference/editors-select.md), [`/editors/text`](reference/editors-text.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
46
  - [`/editors/session`](reference/editors-session.md): the anchored edit session every host shares
47
+ - [`/editors/panel`](reference/editors-panel.md): an editor opened as a popover on the desktop and a sheet on the phone
47
48
  - [`/editors/open-values`](reference/editors-open-values.md): an open field's values carried to its editors
49
+ - [`@viewkitjs/views/field-row`](reference/field-row.md): a record's field row, its write path and its hosts
48
50
  - [`@viewkitjs/views/cells`](reference/cells.md): a column's typed cell
49
51
  - [`@viewkitjs/views/selection`](reference/selection.md): a list's selection
50
52
  - [`@viewkitjs/views/grid`](reference/grid.md): the grid, its props and the helpers a host shares with it
package/docs/install.md CHANGED
@@ -59,7 +59,7 @@
59
59
  scoped to the `views` namespace and `presentation` for your own number and date formats.
60
60
 
61
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
62
+ accept, and the optional `Input`; `ViewsComponents`, from `@viewkitjs/views/react`, is the type. An app on Base UI wraps its
63
63
  shadcn copies thinly; an app on Radix maps `anchor` to its anchor with a virtual ref and
64
64
  `onOpenChange` to its own. [The provider guide](guides/the-provider.md) walks through both, and
65
65
  the contract's "Writing an adapter" says what to do where a copy stops short.
@@ -13,7 +13,7 @@ Guide: [cells](../guides/cells.md).
13
13
  - The reader's overrides: `optionColors`, `dateStyle`, `durationStyle`, `decimals`, `withTime`, `percentDisplay` and `wrap` (text wraps instead of truncating).
14
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
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).
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) and `hostOwnsPlainClick` (a host whose plain click on a value is its own: links stay links, marked `data-cell-link`, and let the click through).
17
17
 
18
18
  ## Column-shaped text
19
19
 
@@ -15,9 +15,11 @@ Guide: [display](../guides/display.md).
15
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
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
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.
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. `hostOwnsPlainClick`, set by a host whose plain click on a value is its own, such as the grid: an email, phone, url or domain stays a link, marked `data-cell-link`, not draggable, and lets its click through for the host to decide.
19
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
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
+ - `ConvertedFigure` — a money figure shown in another currency than its record's own, marked: ≈ before its `children`, and a title naming the currency it came `from` ("Converted from USD", the `views.display.converted-from` message). `renderTypedCellValue` draws it around a converted cell, and a field row around a figure its host reads in another currency; an app draws it on a surface of its own.
22
+ - `ConversionLine` — the line under a money editor opened from a converted figure: the marked `figure`, then "as shown" (`views.display.as-shown`), so the record's own amount being edited and the figure the person clicked read as one value. An optional `className` spaces it.
21
23
 
22
24
  ## Formatting a value as text
23
25
 
@@ -2,5 +2,5 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/chips` in a client component: the door opens with the client directive. It holds the editor of a `multiselect` field, a value that is several values. The chosen values stay on screen while you edit them, as the very tags the cell draws, and adds and removes build a draft that commits once when the host closes the panel: several tags are one write and one undo step. A pick adds a value and keeps the panel open, so this editor never sees the `pick` reason. It owns the field of chips, the list and what a close means; its host owns the popover, the anchor and the write. It commits the list of values, a `string[]`. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `ChipsEditor` — the chips panel; its ref is a `ChipsEditorHandle`. Its top zone is a field holding the chosen values as tags, each with its remove, and the input among them, focused without scrolling; Backspace in an empty input takes the last chip. Below it are the values on offer, those not already chosen, filtered on their labels as you type, and a row that adds the typed text when no chosen or offered value is it, ignoring case. It takes `values` (what the cell holds), `suggestions` (what the column already holds, the same list its filter offers), `resolve` (one value's label and colour as a `PickerOption`, including a value just typed), `onRequestClose` (called with `escape`) and `message`, and optionally `normalize`, the rule every added value goes through (default: trimmed).
6
- - `ChipsEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Its close rule is the odd one out: Escape discards, and any other close, an outside click included, commits the list when it differs from `values` (compared as fields compares a list) and is a `noop` when it doesn't.
5
+ - `ChipsEditor` — the chips panel; its ref is a `ChipsEditorHandle`. Its top zone is a field holding the chosen values as tags, each with its remove, and the input among them, focused without scrolling; Backspace in an empty input takes the last chip. Below it are the values on offer, those not already chosen, filtered on their labels as you type, and, unless `creatable` is false, a row that adds the typed text when no chosen or offered value is it, ignoring case. A closed vocabulary passes `creatable={false}`: its search only filters what it offers. Enter adds the highlighted value and keeps the panel open; Tab and Shift-Tab ask the host to close with `tab` and `shift-tab`, and text typed but not added stays out. It takes `values` (what the cell holds), `suggestions` (what the column already holds, the same list its filter offers), `resolve` (one value's label and colour as a `PickerOption`, including a value just typed), `onRequestClose` (called with `escape`, `tab` or `shift-tab`) and `message`, and optionally `normalize`, the rule every added value goes through (default: trimmed), and `creatable` (default true).
6
+ - `ChipsEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Its close rule is the date editor's: Escape discards, and any other close, an outside click included, commits the list when it differs from `values` (compared as fields compares a list) and is a `noop` when it doesn't.
@@ -1,6 +1,6 @@
1
1
  # `@viewkitjs/views/editors/date`
2
2
 
3
- Import from `@viewkitjs/views/editors/date` in a client component: the door opens with the client directive. It holds the editor of a `date` and a `datetime` field: a value bar with a typeable date and a time chip, above your app's calendar. It owns the value bar, the calendar, the lenient reading of a typed date and the draft; its host owns the popover, the anchor and when a close means commit. It commits `YYYY-MM-DD` when no time is set, or `YYYY-MM-DDTHH:MM` in local time. Guide: [editors](../guides/editors.md).
3
+ Import from `@viewkitjs/views/editors/date` in a client component: the door opens with the client directive. It holds the editor of a `date` and a `datetime` field: a value bar with a typeable date and a time chip, three quick days, your app's calendar, and a Clear row where the date may be empty. It owns the value bar, the calendar, the lenient reading of a typed date and the draft; its host owns the popover, the anchor and when a close means commit. It commits `YYYY-MM-DD` when no time is set, `YYYY-MM-DDTHH:MM` in local time, or `""` when the Clear row empties the date. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `DateEditor` — the date panel; its ref is a `DateEditorHandle`. The date box reads a typed date day first and writes it back as `dd/mm/yyyy`; the time chip offers quick picks every 15 minutes; the calendar is the pointer path to the same day, with a year picker from 1900 to ten years ahead (a typed date outside it still lands). It takes `initial` (the stored value, a full ISO string or `YYYY-MM-DD`, which picks the day and the month it opens on), `onRequestClose` (Enter means done and Escape means leave; the panel never closes itself) and `message` (the fields message resolver, defaulting to the provider's conventions). With `timeOptional` the time chip starts empty and stays out of the commit until set; without it the chip carries the stored time, or 00:00, and every commit includes one. With no stored value the box starts on today, and a close with no interaction writes nothing.
6
- - `DateEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. For a date every close means the same thing: commit the draft when it differs from the stored value, `noop` otherwise, with text still typed in the date box read first. It takes the reason and does not read it; telling reasons apart is the host's.
5
+ - `DateEditor` — the date panel; its ref is a `DateEditorHandle`. The date box reads a typed date day first and writes it back as `dd/mm/yyyy`; the time chip offers quick picks every 15 minutes; Today, Tomorrow and Next Monday (a week on when today is a Monday) above the calendar each set their day as a calendar click does; the calendar is the pointer path to the same day, with a year picker from 1900 to ten years ahead (a typed date outside it still lands). It takes `initial` (the stored value, a full ISO string or `YYYY-MM-DD`, which picks the day and the month it opens on; a bare `YYYY-MM-DD` is that day on the device's calendar in every time zone, never midnight UTC), `onRequestClose` (Enter means done, Escape means leave, and `pick` means a choice that ends the edit; Tab from the panel's last control asks to close with `tab`, and Shift-Tab from its first with `shift-tab`, while Tab between its own controls moves as usual, so a popover that keeps the focus in a loop can still be left; the panel never closes itself) and `message` (the fields message resolver, defaulting to the provider's conventions). With `timeOptional` the time chip starts empty and stays out of the commit until set; without it the chip carries the stored time, or 00:00, and every commit includes one. With `dayOnly`, for a calendar-day field, there is no time chip, the commit is the day, and a click on a day or a quick day asks to close with `pick`; without it, a day click keeps the panel open for the time and a quick day keeps the time, and on a desktop either puts the focus back in the date box, so Enter saves the day and time the panel shows. With `clearable` the panel ends with a Clear row: a click asks to close with `pick` and commits `""`, or nothing when there was no date. With `seed` the date box opens holding that text (a character typed on the cell), focused with the caret after it, and read as a typed date. With `focusDate` the date box takes the focus as the panel opens, without scrolling, so Tab walks the panel and leaves from its last control; leave it off on a phone, whose sheet opens with the keyboard down. The time chip's quick-pick closes when Tab leaves the time box, so Tab moves on to the quick days rather than through every quarter hour. With no stored value the box starts on today, and a close with no interaction writes nothing.
6
+ - `DateEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape discards: `"escape"` answers `cancel`. After a click on the Clear row, any other close commits `""`, or is a `noop` when there was no date. Otherwise every other close commits the draft when it differs from the stored value, and is a `noop` otherwise, with text still typed in the date box read first.
@@ -6,5 +6,5 @@ Import from `@viewkitjs/views/editors/location` in a client component: the door
6
6
  - Country: a field that takes the country opens on a searchable country list when its place has none (matched by name, marks ignored, or by code); once picked, the country is a button that opens the list again. Picking another country clears the region and its code.
7
7
  - Region: where the country has a region list, the region is picked from it, storing the region's name and its ISO 3166-2 code; the list loads when the editor lands on that country. A typed region has no code.
8
8
  - Parts: a field limited to some parts edits only those, and a part it names that the country's format has no place for comes after the country's lines, as does a part a stored place holds that its country has no place for.
9
- - Keys: Tab walks the controls; Escape in a list goes back to the boxes, keeping what was typed, and only the first country list, with nothing behind it, closes the editor.
9
+ - Keys: Tab walks the controls; Escape in a list goes back to the boxes, keeping what was typed, and only the first country list, with nothing behind it, closes the editor. A list with boxes behind it carries the panel's `EDITOR_INNER_ESCAPE` mark, so an `EditorPanel` popover leaves that Escape to the list.
10
10
  - `LocationEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels. Each of the field's parts is trimmed, an empty one null; the same stored value as `initial` is a `noop`; every part empty commits null with `allowEmpty` and cancels without it; anything else commits.
@@ -4,7 +4,7 @@ Import from `@viewkitjs/views/editors/number` in a client component: the door op
4
4
 
5
5
  - `NumberEditor` — the number input, focused without scrolling; its ref is a `NumberEditorHandle`. It takes `initial` (the signed stored value), `onRequestClose`, and optionally:
6
6
  - Text: `seed`, the character that opened the editor, replacing the text while `initial` stays the value it compares against; `decimals`, the rounding and the opening precision in the stored unit (default 2, and 0 for a whole-number field); `conventions`, how your people write a number (default: the provider's); `allowEmpty`, which makes a blank input a real null commit.
7
- - Unit: `unit`, the row's currency, drawn as a chip; `unitOptions`, which make the chip a picker; `unitLeft`, the chip before the figure.
7
+ - Unit: `unit`, the row's currency, drawn as a chip; `unitOptions`, which make the chip a picker; `unitLeft`, the chip before the figure; `code`, a fixed currency's code (`numberEditCode`), drawn beside the amount as a unit is and never part of the commit, ignored when `unit` is given.
8
8
  - Duration: `durationUnit`, the unit a duration is stored in. The input then opens as written text (`1m 30s`), reads units, compounds or a bare number of seconds, and commits in that unit.
9
9
  - Layout: `align`, `end` (the default, a right-aligned column) or `start` (a row read left to right, with the chip following the figure).
10
10
  - `NumberEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels. A blank input cancels, or with `allowEmpty` commits a null value (`noop` when it was already empty and the unit is unchanged). Text that is not a number cancels, never clears. The same number at the editor's decimals with the same unit is a `noop`; anything else commits.
@@ -7,3 +7,4 @@ Import from `@viewkitjs/views/editors/open-values` in a client component: the do
7
7
  - `useOpenValues` — the values an open field holds, as the nearest provider knows them, given the field or undefined. It calls the provider's `onWanted` with the field's key when it mounts, and returns an empty list for a closed field, no field or no provider.
8
8
  - `useOpenValuesContext` — the nearest provider's `OpenValues` whole, or undefined: what a host hands `buildRelationFilters` as `farValues`.
9
9
  - `offeredValues` — what an editor offers, each value once: given a field, the known values and those seen on screen (default none), it returns the field's declared options, then the known values, then the seen ones.
10
+ - `takesNewValues` — whether an editor of a field takes a value typed in that no option names: `true` for a select with `vocabulary: "custom-values"` and for a multiselect whose vocabulary is not `"closed"`, the line the field's own rule draws; `false` otherwise. A host passes it as the chips editor's `creatable`.
@@ -0,0 +1,12 @@
1
+ # `@viewkitjs/views/editors/panel`
2
+
3
+ Import from `@viewkitjs/views/editors/panel` in a client component: the door opens with the client directive. It holds where an editor opens, for every surface: your popover on a desktop and your sheet on a phone, from the components map's `Popover` and `Sheet`, or nothing at all for a type-in editor that stays where its value stands. The editor inside never reads which. It takes the session your host opened (`@viewkitjs/views/editors/session`), so the session's rules hold on every surface. Guide: [editors](../guides/editors.md#the-panel-a-popover-on-the-desktop-a-sheet-on-the-phone).
4
+
5
+ - `EditorPanel` — opens the editor it holds. The surface is chosen once, when the session opens, by the provider's `desktopQuery`: a window crossing the desktop width mid-edit keeps the panel it opened in. A panel already open in server-rendered HTML reads the server's answer, a desktop, so mount it on the person's tap, as a host does. What each dismissal means is the panel's, so every host agrees:
6
+ - On a desktop, your `Popover`, opened on `anchor`: its Escape discards, unless it comes from inside an element carrying `EDITOR_INNER_ESCAPE`, which the panel answers `false` to so the popover stays open and the editor closes its own list; and a press outside closes with `"outside"`, which the editor answers by its own rule, while the session is open: a press while the popover plays its exit after a close reaches nothing. Its panel carries `data-slot="vk-editor-panel"`.
7
+ - On a phone, your `Sheet`, titled with `title` (the field's name), and a bar with ✕ (`views.editors.discard`) and ✓ (`views.editors.save`). ✕, a swipe, the backdrop and Escape discard; ✓ closes with `"enter"`, as done; a pick in a select saves on its own. A picker always opens the sheet on a phone. A press inside the sheet stays in it: a click, a double-click or a context menu never bubbles through React's tree to what the panel is drawn in, such as a grid row.
8
+ - A type-in editor (`inPlace`) is drawn where it stands on a desktop, and on a phone too unless its host passes `sheetOnPhone`, which opens it in the sheet.
9
+ - A refusal your `onAttempt` gave (`refusal`) is drawn under the editor, with `role="alert"` and `data-slot="vk-editor-refusal"`, in the popover and the sheet. In place, your own box draws it: pass the children as a function of the `EditorSurface` to know where the editor is.
10
+ - `EditorPanelProps` — what the panel takes: `session` (an `EditSession`, from either mode), `title`, `anchor`, `inPlace` and `sheetOnPhone` (both default false), `snap` (the sheet's hint, default `auto`), the popover's `side`, `align`, `sideOffset`, `alignOffset`, `initialFocus`, `chrome`, `className`, `style` and `panelData`, handed on as they are, `onPanelClick` (a click inside the popover or the sheet; the sheet then keeps it, the popover leaves that to you), and `children`: the editor, or a function of the `EditorSurface` the panel chose.
11
+ - `EditorSurface` — where the panel opened its editor: `popover`, `sheet` or `in-place`. An `in-place` editor is drawn in its value's own box, which the panel scrolls into view as the editor opens, at the nearest edge (`scrollIntoView` with `nearest`), when `anchor` is that box: a box partly past the edge of what scrolls it opens whole.
12
+ - `EDITOR_INNER_ESCAPE` — the attribute name (`data-vk-inner-escape`) an editor puts on an inner level of its own, such as a list opened from its boxes, while Escape there closes that level rather than the edit. A popover that hears Escape on the document before the editor does then leaves it to the editor. The place editor carries it on its country and region lists.
@@ -2,5 +2,5 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/range` in a client component: the door opens with the client directive. It holds the editor of a `range` field: two number boxes, low and high, inline like the number editor. Tab moves from low to high inside the editor, and a blur that lands on the other box is not a close. An empty box is an open end. It owns the two boxes and what a close means; its host owns where it mounts, the write, and keeping the pair in its own columns. It commits a `RangeValue` of `@viewkitjs/fields`, `{ low, high }`, each a number or null. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `RangeEditor` — the two boxes, the low one focused without scrolling; its ref is a `RangeEditorHandle`. It takes `initial` (the stored range, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the low box), `decimals` (default 0), `allowEmpty`, `suffix` (a unit drawn after the high box, such as `%` or a currency code), `align` (`end` by default, or `start`) and `conventions` (how a number is written; default: the provider's).
5
+ - `RangeEditor` — the two boxes, the low one focused without scrolling; its ref is a `RangeEditorHandle`. It takes `initial` (the stored range, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the low box), `decimals` (default 0), `allowEmpty`, `suffix` (a unit drawn after the high box, such as `%` or a currency code), `align` (`end` by default, or `start`), `conventions` (how a number is written; default: the provider's), `bands` (the field's `presets`, listed under the boxes; a click writes the band's ends into the boxes and closes as `pick`, so it is read and judged as typed ends are), `bandsAt` (`popover` by default, a small menu under the boxes; `below`, in the editor's own column, for an editor already in a sheet or a panel) and `boxClassName` (classes for the box holding the two inputs, such as a sheet's field).
6
6
  - `RangeEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels, and so does a box holding text that is not a number. Both ends unchanged as the boxes showed them is a `noop`, so a stored 2.555 that opened as 2.56 writes nothing. Two empty boxes cancel, or commit with `allowEmpty`. A low end above the high end commits as typed, for the host's acceptance to refuse in its own words.
@@ -1,9 +1,12 @@
1
1
  # `@viewkitjs/views/editors/relation`
2
2
 
3
- Import from `@viewkitjs/views/editors/relation` in a client component: the door opens with the client directive. It holds the picker for a link, the editor of a `relation` and a `user` field: search the candidates, pick one, and it replaces the link. The candidates are the host's, through a `RelationSource`: a static list the panel filters on its labels, or a remote search your function answers a page at a time. The panel owns the search box, the rows, the paging (it waits before a typed query searches, drops an answer a newer query superseded, asks for the next page as the end of the list scrolls into view, and says when it is searching, failed or found nothing) and what a close means: a pick is the commit, every other close discards. It never does the asking itself, so access stays in your function's closure. Its host owns the popover, the anchor and the write. It commits the picked id, or null for None. The door also re-exports `RelationCandidate`, `RelationSearch` and `RelationSource`, which are documented with the root door. Guide: [editors](../guides/editors.md).
3
+ Import from `@viewkitjs/views/editors/relation` in a client component: the door opens with the client directive. It holds the picker for a link, the editor of a `relation` and a `user` field: search the candidates, pick one, and it replaces the link; and the editor of a relation holding several records, which adds and removes links with the list open. The candidates are the host's, through a `RelationSource`: a static list the panel filters on its labels, or a remote search your function answers a page at a time. The panel owns the search box, the rows, the paging (it waits before a typed query searches, drops an answer a newer query superseded, asks for the next page as the end of the list scrolls into view, and says when it is searching, failed or found nothing) and, in `RelationEditor`, what a close means: a pick is the commit, every other close discards (`RelationSetEditor` saves on every close but Escape). It never does the asking itself, so access stays in your function's closure. Its host owns the popover, the anchor and the write. It commits the picked id, or null for None. The door also re-exports `RelationCandidate`, `RelationSearch` and `RelationSource`, which are documented with the root door. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `RelationEditor` — the relation-picking panel, built from your app's command list; its ref is a `RelationEditorHandle`. It takes `candidates` (the `RelationSource`), `initial` (the linked id, or null), `clearable` (a None row for a link the surface says is optional, hidden while a query is typed), `onRequestClose` (called with `pick` when someone chooses), `kindGlyph` (the glyph worn by every candidate with no icon of its own; given, every row keeps a glyph lane so the labels line up), `noneLabel` (the surface's words for the None row), `message` (the fields message resolver, defaulting to the provider's conventions) and `creates` (`RelationCreate` rows pinned under the list). A candidate's `sublabel` draws as a muted second line and its `badge` as a small chip at the row's end.
5
+ - `RelationEditor` — the relation-picking panel, built from your app's command list; its ref is a `RelationEditorHandle`. It takes `candidates` (the `RelationSource`), `initial` (the linked id, or null), `clearable` (a None row for a link the surface says is optional, hidden while a query is typed), `onRequestClose` (called with `pick` when someone chooses), `kindGlyph` (the glyph worn by every candidate with no icon of its own; given, every row keeps a glyph lane so the labels line up), `noneLabel` (the surface's words for the None row), `message` (the fields message resolver, defaulting to the provider's conventions), `creates` (`RelationCreate` rows pinned under the list), `seed` (the text the search opens with, such as a letter typed on the cell that opened it) and `focusSearch` (put the caret in the search as the panel opens, without scrolling; off by default, and left off on a phone so its sheet opens with the keyboard down). The list opens with the linked record highlighted, so an Enter pressed at once changes nothing; when a remote page doesn't hold it, nothing is highlighted until a key or typed text moves the highlight; with nothing linked, None or the first candidate; opened with a `seed`, the first match. It asks your command list for that through its root's `defaultValue`; a list that ignores it opens on its first row. A candidate's `sublabel` draws as a muted second line and its `badge` as a small chip at the row's end.
6
6
  - `RelationEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `commit` with the picked id, or null for None, only for `pick` and only when it differs from `initial`; `noop` for a `pick` with nothing picked or the link already held; `cancel` for every other reason.
7
- - `RelationCreate` — a row pinned under the list for a record that isn't in it yet: `label(query)` gives its words from the trimmed query, and `onCreate(query)` runs after the host has been asked to close, so your own create form opens with what was typed. A click on it is a `pick` that resolves `noop`: nothing is written.
7
+ - `RelationCreate` — a row pinned under the list for a record that isn't in it yet: `label(query)` gives its words from the trimmed query, and `onCreate(query)` runs after the host has been asked to close, so your own create form opens with what was typed. In `RelationEditor` a click on it is a `pick` that resolves `noop`: nothing is written. In `RelationSetEditor` it saves the set as it stands first. The grid writes a record your form links on top of that save however soon you call the link, even before the editor has finished closing.
8
8
  - `RELATION_SEARCH_DEBOUNCE_MS` — 200: how many milliseconds a typed query waits before a remote search runs. The empty query runs at once, so the panel opens on a first page.
9
9
  - `RELATION_PAGE_SIZE` — 20: the rows per page when a remote source names no `pageSize`. A page shorter than the size ends the list.
10
+ - `RelationSetEditor` — the editor of a relation holding several records, on the same panel; its ref is a `RelationSetEditorHandle`. It takes `candidates`, `initial` (the linked records as `RelationSetItem`s, in their stored order), `lead` (the field leads by a flag), `onRequestClose` (called with `tab` or `shift-tab` from the search, and with `pick` from a create row), `kindGlyph`, `message`, `creates`, `seed` and `focusSearch`, as `RelationEditor` does. The linked records are drawn first and chosen, whatever page a remote search holds, and filtered by the query on their labels; a click on a candidate adds it to the end of the set, a click on a linked record removes it, and the list stays open. With `lead`, the first link leads: it carries a Lead mark, every other linked record a Make lead action that moves it first, and removing the lead passes it to the next; a set stored with none marked reads its first link as the lead. Space on a highlighted linked record, with the search empty, makes it the lead too; with a query typed, Space types. On open the highlight sits on the first linked record, so an Enter does nothing until the highlight leaves it, by a key, by typing or by the pointer. The editor reads the highlighted record off the search's `aria-activedescendant` and the row's `data-value`, as cmdk sets them; a command list that sets neither keeps the Enter guard until a key or typing moves the highlight, and has no Space for the lead. With `focusSearch`, the caret goes back to the search after every click, so Tab still saves.
11
+ - `RelationSetEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `cancel` for `escape`; for every other reason, `noop` when the set holds the same records in the same order as it opened, else `commit` with the whole set as `RelationDraftLink[]` (from `@viewkitjs/fields`), in order with the lead first: each link's `id`, its `kind` where known, the `role` it was stored with (a new link has none), and with `lead`, `primary` on every link, true on the first.
12
+ - `RelationSetItem` — one linked record as the set editor holds it: a `RelationDraftLink` with the `label` its row shows and an optional `icon`.
@@ -2,7 +2,8 @@
2
2
 
3
3
  Import from `@viewkitjs/views/editors/select` in a client component: the door opens with the client directive. It holds the picker for one value out of a set, the editor of a `select` and a `status` field. The panel draws each option as your app's row with its badge or tag and owns what a close means: a pick is the commit, and every other close discards. Its host owns the popover, the anchor, the exit gap and the write. It commits the picked option's `value`, a string, and `""` for None, which a host maps to null. Guide: [editors](../guides/editors.md).
4
4
 
5
- - `SelectEditor` — the option-picking panel; its ref is a `SelectEditorHandle`. It takes `options` (`PickerOption`s in display order, colours already resolved), `initial` (the value the surface holds, checked in the list), `clearable` (a None row first, for a value the surface says is optional), `onRequestClose` (called with `pick` when someone chooses) and `message` (the fields message resolver, defaulting to the provider's conventions). With `creatable`, for an open select, it adds a search over the option labels and, after the matches, a row that uses the typed text when no option's value is it, ignoring case; Enter picks the first match, and picking the row commits the trimmed text.
5
+ - `SelectEditor` — the option-picking panel; its ref is a `SelectEditorHandle`. It takes `options` (`PickerOption`s in display order, colours already resolved), `initial` (the value the surface holds, checked in the list), `clearable` (a None row first, for a value the surface says is optional), `onRequestClose` (called with `pick` when someone chooses) and `message` (the fields message resolver, defaulting to the provider's conventions). A list of more than `SELECT_SEARCH_PAST` (8) options opens with a search over the option labels, the None row hidden while a query is typed; Enter picks the first match. When it may be emptied, it opens with the value it holds highlighted, or None when it holds nothing, so an Enter pressed at once changes nothing, and the arrows walk every row, None included; opened with a `seed`, on the first match. It asks your command list for that through its root's `defaultValue`; a list that ignores it opens on None. One that can't be emptied opens on its first option. With `creatable`, for an open select, the search is always there and, after the matches, a row uses the typed text when no option's value is it, ignoring case; picking that row commits the trimmed text. `seed` is the text the search opens with (a letter typed on the cell that opened it), ignored by a list with no search; `focusSearch` puts the caret in the search as it opens, without scrolling. `focusList`, for a host opened from the keyboard, gives a plain list the keys: the row it holds takes the focus as it opens (None when it may be emptied and holds nothing, else its first row), ↓ and ↑ move it between the rows, round at either end, and Enter picks the focused row; a list with a search ignores it.
6
6
  - `SelectEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. It answers `commit` with the picked value only for `pick`, and only when the pick differs from `initial` (`""` and null are the same absence); `noop` for a `pick` with nothing picked or the value already held; `cancel` for every other reason, so Escape and an outside click discard.
7
+ - `SELECT_SEARCH_PAST` — the number of options a closed list holds before it opens with a search: 8.
7
8
  - `PickerOption` — one option as the panel draws it: its `value` and `label`, and a `slot` (a status's lifecycle state, drawn as your status badge) or a `color` (a category colour, drawn as your tag), or neither for a plain label. `icon` names your app's glyph, drawn before the label. Colours are resolved by the caller, never by the panel.
8
- - `pickerOptionsFromField` — a select or status field's options dressed the way its cells draw them, so a pick in a form looks like the grid. Archived options are left out. A status keeps each option's slot (`muted` when it names none); a select takes the category colour chain: your `optionColors` overrides, then the field's own colour, then the derived hue. Each option's icon is carried. `extraValues` adds values your rows hold that no option names, labelled with their raw code, so a stray value can be picked back; an archived value stays out.
9
+ - `pickerOptionsFromField` — a select or status field's options dressed the way its cells draw them, so a pick in a form looks like the grid. Archived options are left out. A status keeps each option's slot (`muted` when it names none); a select takes the category colour chain: your `optionColors` overrides, then the field's own colour, then the derived hue. Each option's icon is carried. `extraValues` adds an open select's values, the ones its records hold, labelled with their raw code; an archived value stays out. `current` is the value your surface holds: offered after the options when no active option is it, labelled with its archived option's label or its raw code, so its own list shows it checked. A closed list gets no `extraValues`, so a stray value shows only on the record that holds it.