@viewkitjs/views 0.1.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 (390) hide show
  1. package/CHANGELOG.md +767 -1
  2. package/README.md +92 -41
  3. package/dist/atoms/LoadMore.js +11 -1
  4. package/dist/atoms/Row.js +1 -1
  5. package/dist/atoms/RowMenu.d.ts +1 -1
  6. package/dist/atoms/RowMenu.js +20 -6
  7. package/dist/atoms/types.d.ts +4 -4
  8. package/dist/cells/cell-format.d.ts +3 -3
  9. package/dist/cells/cell-title.d.ts +1 -2
  10. package/dist/cells/cell-title.js +2 -2
  11. package/dist/cells/cell-values.js +6 -3
  12. package/dist/contract.d.ts +79 -8
  13. package/dist/contract.js +55 -8
  14. package/dist/display/converted.d.ts +19 -0
  15. package/dist/display/converted.js +12 -0
  16. package/dist/display/format.d.ts +16 -1
  17. package/dist/display/format.js +10 -1
  18. package/dist/display/index.d.ts +2 -1
  19. package/dist/display/index.js +2 -1
  20. package/dist/display/link-click.d.ts +11 -0
  21. package/dist/display/link-click.js +3 -0
  22. package/dist/display/link.js +12 -6
  23. package/dist/display/location.d.ts +4 -3
  24. package/dist/display/location.js +12 -5
  25. package/dist/display/multi-value.d.ts +1 -1
  26. package/dist/display/multi-value.js +1 -1
  27. package/dist/display/options.d.ts +8 -2
  28. package/dist/display/percent.js +10 -3
  29. package/dist/display/phone.d.ts +2 -1
  30. package/dist/display/phone.js +11 -2
  31. package/dist/display/relation.js +1 -1
  32. package/dist/editors/ChipsEditor.d.ts +9 -4
  33. package/dist/editors/ChipsEditor.js +7 -3
  34. package/dist/editors/DateEditor.d.ts +21 -6
  35. package/dist/editors/DateEditor.js +118 -30
  36. package/dist/editors/EditorPanel.d.ts +61 -0
  37. package/dist/editors/EditorPanel.js +54 -0
  38. package/dist/editors/LocationEditor.d.ts +3 -0
  39. package/dist/editors/LocationEditor.js +28 -21
  40. package/dist/editors/NameEditor.d.ts +3 -0
  41. package/dist/editors/NameEditor.js +15 -10
  42. package/dist/editors/NumberEditor.d.ts +3 -0
  43. package/dist/editors/NumberEditor.js +7 -7
  44. package/dist/editors/RangeEditor.d.ts +16 -1
  45. package/dist/editors/RangeEditor.js +22 -6
  46. package/dist/editors/RelationEditor.d.ts +13 -28
  47. package/dist/editors/RelationEditor.js +17 -40
  48. package/dist/editors/RelationSetEditor.d.ts +53 -0
  49. package/dist/editors/RelationSetEditor.js +112 -0
  50. package/dist/editors/SelectEditor.d.ts +21 -3
  51. package/dist/editors/SelectEditor.js +55 -9
  52. package/dist/editors/TextEditor.d.ts +51 -0
  53. package/dist/editors/TextEditor.js +81 -0
  54. package/dist/editors/ValueListEditor.d.ts +5 -2
  55. package/dist/editors/ValueListEditor.js +11 -9
  56. package/dist/editors/edit-cores.d.ts +13 -10
  57. package/dist/editors/edit-cores.js +7 -6
  58. package/dist/editors/edit-session.d.ts +21 -11
  59. package/dist/editors/edit-session.js +19 -5
  60. package/dist/editors/keep-inside.d.ts +12 -0
  61. package/dist/editors/keep-inside.js +20 -0
  62. package/dist/editors/open-value.d.ts +21 -0
  63. package/dist/editors/open-value.js +36 -0
  64. package/dist/editors/open-values.d.ts +4 -0
  65. package/dist/editors/open-values.js +7 -0
  66. package/dist/editors/relation-kinds.d.ts +7 -0
  67. package/dist/editors/relation-kinds.js +21 -0
  68. package/dist/editors/relation-panel.d.ts +69 -0
  69. package/dist/editors/relation-panel.js +40 -0
  70. package/dist/field-row/FieldNoteLine.d.ts +14 -0
  71. package/dist/field-row/FieldNoteLine.js +14 -0
  72. package/dist/field-row/FieldRow.d.ts +73 -0
  73. package/dist/field-row/FieldRow.js +157 -0
  74. package/dist/field-row/FieldRowLane.d.ts +19 -0
  75. package/dist/field-row/FieldRowLane.js +11 -0
  76. package/dist/field-row/editors/RowChipsEditor.d.ts +11 -0
  77. package/dist/field-row/editors/RowChipsEditor.js +25 -0
  78. package/dist/field-row/editors/RowDateEditor.d.ts +16 -0
  79. package/dist/field-row/editors/RowDateEditor.js +18 -0
  80. package/dist/field-row/editors/RowEditor.d.ts +39 -0
  81. package/dist/field-row/editors/RowEditor.js +64 -0
  82. package/dist/field-row/editors/RowNameEditor.d.ts +4 -0
  83. package/dist/field-row/editors/RowNameEditor.js +15 -0
  84. package/dist/field-row/editors/RowNumberEditor.d.ts +12 -0
  85. package/dist/field-row/editors/RowNumberEditor.js +18 -0
  86. package/dist/field-row/editors/RowPlaceEditor.d.ts +8 -0
  87. package/dist/field-row/editors/RowPlaceEditor.js +18 -0
  88. package/dist/field-row/editors/RowRangeEditor.d.ts +4 -0
  89. package/dist/field-row/editors/RowRangeEditor.js +15 -0
  90. package/dist/field-row/editors/RowRelationEditor.d.ts +20 -0
  91. package/dist/field-row/editors/RowRelationEditor.js +77 -0
  92. package/dist/field-row/editors/RowSelectEditor.d.ts +13 -0
  93. package/dist/field-row/editors/RowSelectEditor.js +23 -0
  94. package/dist/field-row/editors/RowTextEditor.d.ts +15 -0
  95. package/dist/field-row/editors/RowTextEditor.js +16 -0
  96. package/dist/field-row/editors/RowValueListEditor.d.ts +4 -0
  97. package/dist/field-row/editors/RowValueListEditor.js +21 -0
  98. package/dist/field-row/editors/host.d.ts +59 -0
  99. package/dist/field-row/editors/host.js +1 -0
  100. package/dist/field-row/editors/row-session.d.ts +49 -0
  101. package/dist/field-row/editors/row-session.js +49 -0
  102. package/dist/field-row/index.d.ts +5 -0
  103. package/dist/field-row/index.js +5 -0
  104. package/dist/field-row/row-target.d.ts +20 -0
  105. package/dist/field-row/row-target.js +3 -0
  106. package/dist/field-row/useFieldWrite.d.ts +45 -0
  107. package/dist/field-row/useFieldWrite.js +190 -0
  108. package/dist/field-row/useRowSettlement.d.ts +33 -0
  109. package/dist/field-row/useRowSettlement.js +23 -0
  110. package/dist/fields/binding.d.ts +7 -2
  111. package/dist/fields/binding.js +13 -6
  112. package/dist/fields/currency.d.ts +0 -10
  113. package/dist/fields/currency.js +0 -14
  114. package/dist/fields/edit-core-types.d.ts +9 -9
  115. package/dist/fields/edit-core-types.js +6 -6
  116. package/dist/fields/money.d.ts +6 -0
  117. package/dist/fields/money.js +11 -0
  118. package/dist/fields/number-edit.d.ts +6 -0
  119. package/dist/fields/number-edit.js +4 -0
  120. package/dist/fields/prepare-write.js +6 -1
  121. package/dist/fields/relation-source-types.d.ts +12 -0
  122. package/dist/fields/write-target.d.ts +50 -0
  123. package/dist/fields/write-target.js +10 -0
  124. package/dist/filters/filter-model.d.ts +0 -1
  125. package/dist/filters/registry.d.ts +3 -36
  126. package/dist/filters/registry.js +0 -38
  127. package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
  128. package/dist/grid/chrome/GridAddColumn.js +29 -0
  129. package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
  130. package/dist/grid/chrome/GridAggregateMenu.js +29 -0
  131. package/dist/grid/chrome/GridCellEditors.d.ts +71 -0
  132. package/dist/grid/chrome/GridCellEditors.js +126 -0
  133. package/dist/grid/chrome/GridCellOutline.d.ts +49 -0
  134. package/dist/grid/chrome/GridCellOutline.js +16 -0
  135. package/dist/grid/chrome/GridChipsEditor.d.ts +38 -0
  136. package/dist/grid/chrome/GridChipsEditor.js +35 -0
  137. package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
  138. package/dist/grid/chrome/GridColumnColorSection.js +40 -0
  139. package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
  140. package/dist/grid/chrome/GridColumnDateSection.js +23 -0
  141. package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
  142. package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
  143. package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
  144. package/dist/grid/chrome/GridColumnMenu.js +103 -0
  145. package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
  146. package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
  147. package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
  148. package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
  149. package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
  150. package/dist/grid/chrome/GridColumnSortSection.js +16 -0
  151. package/dist/grid/chrome/GridDateEditor.d.ts +34 -0
  152. package/dist/grid/chrome/GridDateEditor.js +19 -0
  153. package/dist/grid/chrome/GridFlyout.d.ts +44 -0
  154. package/dist/grid/chrome/GridFlyout.js +80 -0
  155. package/dist/grid/chrome/GridFooter.d.ts +33 -0
  156. package/dist/grid/chrome/GridFooter.js +85 -0
  157. package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
  158. package/dist/grid/chrome/GridGroupMenu.js +64 -0
  159. package/dist/grid/chrome/GridHeader.d.ts +66 -0
  160. package/dist/grid/chrome/GridHeader.js +42 -0
  161. package/dist/grid/chrome/GridLongTextEditor.d.ts +55 -0
  162. package/dist/grid/chrome/GridLongTextEditor.js +69 -0
  163. package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
  164. package/dist/grid/chrome/GridMenuRow.js +15 -0
  165. package/dist/grid/chrome/GridNameEditor.d.ts +24 -0
  166. package/dist/grid/chrome/GridNameEditor.js +21 -0
  167. package/dist/grid/chrome/GridNumberEditor.d.ts +49 -0
  168. package/dist/grid/chrome/GridNumberEditor.js +51 -0
  169. package/dist/grid/chrome/GridPlaceEditor.d.ts +26 -0
  170. package/dist/grid/chrome/GridPlaceEditor.js +22 -0
  171. package/dist/grid/chrome/GridRangeEditor.d.ts +30 -0
  172. package/dist/grid/chrome/GridRangeEditor.js +21 -0
  173. package/dist/grid/chrome/GridRelationEditor.d.ts +45 -0
  174. package/dist/grid/chrome/GridRelationEditor.js +92 -0
  175. package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
  176. package/dist/grid/chrome/GridResizeHandle.js +19 -0
  177. package/dist/grid/chrome/GridRow.d.ts +31 -0
  178. package/dist/grid/chrome/GridRow.js +179 -0
  179. package/dist/grid/chrome/GridRowActions.d.ts +32 -0
  180. package/dist/grid/chrome/GridRowActions.js +25 -0
  181. package/dist/grid/chrome/GridRowCells.d.ts +4 -0
  182. package/dist/grid/chrome/GridRowCells.js +128 -0
  183. package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
  184. package/dist/grid/chrome/GridRowGlyph.js +13 -0
  185. package/dist/grid/chrome/GridSelectEditor.d.ts +33 -0
  186. package/dist/grid/chrome/GridSelectEditor.js +43 -0
  187. package/dist/grid/chrome/GridStructure.d.ts +47 -0
  188. package/dist/grid/chrome/GridStructure.js +41 -0
  189. package/dist/grid/chrome/GridTable.d.ts +4 -0
  190. package/dist/grid/chrome/GridTable.js +192 -0
  191. package/dist/grid/chrome/GridTableSurface.d.ts +52 -0
  192. package/dist/grid/chrome/GridTableSurface.js +15 -0
  193. package/dist/grid/chrome/GridTextEditor.d.ts +45 -0
  194. package/dist/grid/chrome/GridTextEditor.js +38 -0
  195. package/dist/grid/chrome/GridValueListEditor.d.ts +30 -0
  196. package/dist/grid/chrome/GridValueListEditor.js +19 -0
  197. package/dist/grid/chrome/StuckMarker.d.ts +16 -0
  198. package/dist/grid/chrome/StuckMarker.js +34 -0
  199. package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
  200. package/dist/grid/chrome/cell-clipboard.js +28 -0
  201. package/dist/grid/chrome/cell-cut-off.d.ts +11 -0
  202. package/dist/grid/chrome/cell-cut-off.js +20 -0
  203. package/dist/grid/chrome/cells.d.ts +21 -0
  204. package/dist/grid/chrome/cells.js +19 -0
  205. package/dist/grid/chrome/checks.d.ts +32 -0
  206. package/dist/grid/chrome/checks.js +32 -0
  207. package/dist/grid/chrome/column-glyph.d.ts +14 -0
  208. package/dist/grid/chrome/column-glyph.js +44 -0
  209. package/dist/grid/chrome/editors.d.ts +9 -0
  210. package/dist/grid/chrome/editors.js +10 -0
  211. package/dist/grid/chrome/grid-cell-classes.d.ts +53 -0
  212. package/dist/grid/chrome/grid-cell-classes.js +32 -0
  213. package/dist/grid/chrome/grid-cell-link.d.ts +13 -0
  214. package/dist/grid/chrome/grid-cell-link.js +9 -0
  215. package/dist/grid/chrome/grid-edit-session.d.ts +63 -0
  216. package/dist/grid/chrome/grid-edit-session.js +118 -0
  217. package/dist/grid/chrome/grid-hover.d.ts +60 -0
  218. package/dist/grid/chrome/grid-hover.js +81 -0
  219. package/dist/grid/chrome/grid-menu-focus.d.ts +43 -0
  220. package/dist/grid/chrome/grid-menu-focus.js +93 -0
  221. package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
  222. package/dist/grid/chrome/grid-menu-search.js +7 -0
  223. package/dist/grid/chrome/grid-row-menu-key.d.ts +15 -0
  224. package/dist/grid/chrome/grid-row-menu-key.js +36 -0
  225. package/dist/grid/chrome/grid-row-props.d.ts +143 -0
  226. package/dist/grid/chrome/grid-row-props.js +1 -0
  227. package/dist/grid/chrome/grid-row-window.d.ts +61 -0
  228. package/dist/grid/chrome/grid-row-window.js +212 -0
  229. package/dist/grid/chrome/grid-scroll-owner.d.ts +38 -0
  230. package/dist/grid/chrome/grid-scroll-owner.js +75 -0
  231. package/dist/grid/chrome/grid-styles.d.ts +40 -0
  232. package/dist/grid/chrome/grid-styles.js +9 -0
  233. package/dist/grid/chrome/grid-table-props.d.ts +172 -0
  234. package/dist/grid/chrome/grid-table-props.js +1 -0
  235. package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
  236. package/dist/grid/chrome/useGridBatchApi.js +35 -0
  237. package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
  238. package/dist/grid/chrome/useGridColumnLayout.js +206 -0
  239. package/dist/grid/chrome/useGridFocus.d.ts +45 -0
  240. package/dist/grid/chrome/useGridFocus.js +122 -0
  241. package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
  242. package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
  243. package/dist/grid/chrome/useGridKeyboard.d.ts +64 -0
  244. package/dist/grid/chrome/useGridKeyboard.js +450 -0
  245. package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
  246. package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
  247. package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
  248. package/dist/grid/chrome/useGridRailReveal.js +67 -0
  249. package/dist/grid/chrome/useGridRangeActions.d.ts +51 -0
  250. package/dist/grid/chrome/useGridRangeActions.js +195 -0
  251. package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
  252. package/dist/grid/chrome/useGridRangeGestures.js +237 -0
  253. package/dist/grid/chrome/useGridRowContextMenu.d.ts +37 -0
  254. package/dist/grid/chrome/useGridRowContextMenu.js +153 -0
  255. package/dist/grid/chrome/useGridScaleStyles.d.ts +3 -0
  256. package/dist/grid/chrome/useGridScaleStyles.js +28 -0
  257. package/dist/grid/chrome/useGridScrollArea.d.ts +21 -0
  258. package/dist/grid/chrome/useGridScrollArea.js +65 -0
  259. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +78 -0
  260. package/dist/grid/chrome/useGridTableInteractionModel.js +249 -0
  261. package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
  262. package/dist/grid/chrome/useGridTableSelection.js +55 -0
  263. package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
  264. package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
  265. package/dist/grid/core/clipboard-model.d.ts +83 -0
  266. package/dist/grid/core/clipboard-model.js +291 -0
  267. package/dist/grid/core/column-values.d.ts +27 -0
  268. package/dist/grid/core/column-values.js +76 -0
  269. package/dist/grid/core/commit-model.d.ts +41 -0
  270. package/dist/grid/core/commit-model.js +3 -0
  271. package/dist/grid/core/coordinates.d.ts +48 -0
  272. package/dist/grid/core/coordinates.js +27 -0
  273. package/dist/grid/core/edge-scroll.d.ts +21 -0
  274. package/dist/grid/core/edge-scroll.js +23 -0
  275. package/dist/grid/core/edit-values.d.ts +9 -0
  276. package/dist/grid/core/edit-values.js +1 -0
  277. package/dist/grid/core/editing-controller.d.ts +60 -0
  278. package/dist/grid/core/editing-controller.js +266 -0
  279. package/dist/grid/core/editing-model.d.ts +87 -0
  280. package/dist/grid/core/editing-model.js +148 -0
  281. package/dist/grid/core/flat-rows.d.ts +35 -0
  282. package/dist/grid/core/flat-rows.js +20 -0
  283. package/dist/grid/core/grid-aria.d.ts +27 -0
  284. package/dist/grid/core/grid-aria.js +39 -0
  285. package/dist/grid/core/grid-focus.d.ts +54 -0
  286. package/dist/grid/core/grid-focus.js +148 -0
  287. package/dist/grid/core/grid-scale.d.ts +14 -0
  288. package/dist/grid/core/grid-scale.js +8 -0
  289. package/dist/grid/core/nav.d.ts +94 -0
  290. package/dist/grid/core/nav.js +92 -0
  291. package/dist/grid/core/pending-reconciliation.d.ts +53 -0
  292. package/dist/grid/core/pending-reconciliation.js +51 -0
  293. package/dist/grid/core/range-model.d.ts +25 -0
  294. package/dist/grid/core/range-model.js +59 -0
  295. package/dist/grid/core/row-window.d.ts +40 -0
  296. package/dist/grid/core/row-window.js +43 -0
  297. package/dist/grid/core/spreadsheet-operations.d.ts +101 -0
  298. package/dist/grid/core/spreadsheet-operations.js +280 -0
  299. package/dist/grid/core/useGridEditing.d.ts +46 -0
  300. package/dist/grid/core/useGridEditing.js +93 -0
  301. package/dist/grid/core/useGridRange.d.ts +20 -0
  302. package/dist/grid/core/useGridRange.js +24 -0
  303. package/dist/grid/core/value-equality.d.ts +54 -0
  304. package/dist/grid/core/value-equality.js +80 -0
  305. package/dist/grid/index.d.ts +18 -0
  306. package/dist/grid/index.js +5 -0
  307. package/dist/grid/useGridTablePrefs.d.ts +49 -0
  308. package/dist/grid/useGridTablePrefs.js +99 -0
  309. package/dist/index.d.ts +1 -1
  310. package/dist/index.js +1 -1
  311. package/dist/internal/viewport.d.ts +3 -0
  312. package/dist/internal/viewport.js +15 -0
  313. package/dist/model/column-capabilities.d.ts +3 -2
  314. package/dist/model/column-capabilities.js +28 -8
  315. package/dist/model/column-from.js +3 -0
  316. package/dist/model/column-inspect.d.ts +10 -2
  317. package/dist/model/column-inspect.js +9 -0
  318. package/dist/model/column-schema.d.ts +6 -1
  319. package/dist/model/column-state.d.ts +1 -1
  320. package/dist/model/column-types.d.ts +3 -1
  321. package/dist/model/column-types.js +1 -1
  322. package/dist/model/density.js +3 -3
  323. package/dist/model/filter-capabilities.d.ts +1 -1
  324. package/dist/model/filter-capabilities.js +1 -1
  325. package/dist/model/index.d.ts +4 -6
  326. package/dist/model/index.js +0 -1
  327. package/dist/model/preferences.d.ts +7 -7
  328. package/dist/model/preferences.js +0 -1
  329. package/dist/model/prefs-buckets.d.ts +0 -1
  330. package/dist/model/prefs-buckets.js +0 -3
  331. package/dist/model/render-count.d.ts +6 -0
  332. package/dist/model/render-count.js +11 -0
  333. package/dist/provider/ViewsProvider.d.ts +6 -2
  334. package/dist/provider/ViewsProvider.js +12 -2
  335. package/dist/provider/components.d.ts +35 -9
  336. package/dist/provider/components.js +4 -2
  337. package/dist/provider/context.d.ts +8 -4
  338. package/dist/provider/desktop.d.ts +9 -0
  339. package/dist/provider/desktop.js +22 -0
  340. package/dist/provider/menu-groups.d.ts +8 -0
  341. package/dist/provider/menu-groups.js +38 -0
  342. package/dist/provider/plain-input.d.ts +8 -0
  343. package/dist/provider/plain-input.js +5 -0
  344. package/dist/provider/ports.d.ts +22 -0
  345. package/dist/provider/ports.js +1 -0
  346. package/dist/react.d.ts +3 -2
  347. package/dist/react.js +1 -0
  348. package/dist/selection/SelectCheckbox.d.ts +3 -1
  349. package/dist/selection/SelectCheckbox.js +2 -2
  350. package/dist/selection/useCheckDragSelect.js +6 -5
  351. package/docs/contract.md +202 -72
  352. package/docs/getting-started.md +250 -0
  353. package/docs/guides/atoms.md +245 -0
  354. package/docs/guides/cells.md +302 -0
  355. package/docs/guides/columns.md +413 -0
  356. package/docs/guides/display.md +204 -0
  357. package/docs/guides/editors.md +462 -0
  358. package/docs/guides/ports.md +246 -0
  359. package/docs/guides/selection.md +270 -0
  360. package/docs/guides/the-grid.md +696 -0
  361. package/docs/guides/the-provider.md +448 -0
  362. package/docs/index.md +52 -0
  363. package/docs/install.md +9 -47
  364. package/docs/reference/cells.md +28 -0
  365. package/docs/reference/display.md +44 -0
  366. package/docs/reference/editors-chips.md +6 -0
  367. package/docs/reference/editors-date.md +6 -0
  368. package/docs/reference/editors-location.md +10 -0
  369. package/docs/reference/editors-name.md +6 -0
  370. package/docs/reference/editors-number.md +11 -0
  371. package/docs/reference/editors-open-values.md +10 -0
  372. package/docs/reference/editors-panel.md +12 -0
  373. package/docs/reference/editors-range.md +6 -0
  374. package/docs/reference/editors-relation.md +12 -0
  375. package/docs/reference/editors-select.md +9 -0
  376. package/docs/reference/editors-session.md +11 -0
  377. package/docs/reference/editors-text.md +9 -0
  378. package/docs/reference/editors-value-list.md +6 -0
  379. package/docs/reference/editors.md +5 -0
  380. package/docs/reference/field-row.md +16 -0
  381. package/docs/reference/grid.md +39 -0
  382. package/docs/reference/react.md +89 -0
  383. package/docs/reference/selection.md +33 -0
  384. package/docs/reference/views.md +622 -0
  385. package/package.json +27 -4
  386. package/skills/views/SKILL.md +20 -5
  387. package/dist/filters/types.d.ts +0 -27
  388. package/dist/filters/types.js +0 -1
  389. package/dist/model/filter-pushdown.d.ts +0 -106
  390. package/dist/model/filter-pushdown.js +0 -147
@@ -0,0 +1,6 @@
1
+ # `@viewkitjs/views/editors/chips`
2
+
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
+
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.
@@ -0,0 +1,6 @@
1
+ # `@viewkitjs/views/editors/date`
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, 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
+
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.
@@ -0,0 +1,10 @@
1
+ # `@viewkitjs/views/editors/location`
2
+
3
+ Import from `@viewkitjs/views/editors/location` in a client component: the door opens with the client directive. It holds the editor of a `location` field: the country first, then that country's own parts in its own order and with its own words (one country's postal code, county and city on one line, another's city first), the parts the country asks for marked as required and never refused. It owns the boxes, the country list, the region list and what a close means; its host owns the popover, the anchor and the write. It commits a `LocationValue` of `@viewkitjs/fields` holding the field's parts, or null. Guide: [editors](../guides/editors.md).
4
+
5
+ - `LocationEditor` — the place editor; its ref is a `LocationEditorHandle`. It takes `field` (the location field, whose `parts` limit what it edits), `initial` (the stored place, or null) and `onRequestClose`, and optionally `allowEmpty` and `conventions` (whose locale names the countries and picks each country's format; default: the provider's).
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
+ - 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
+ - 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. 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
+ - `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.
@@ -0,0 +1,6 @@
1
+ # `@viewkitjs/views/editors/name`
2
+
3
+ Import from `@viewkitjs/views/editors/name` in a client component: the door opens with the client directive. It holds the editor of a `name` field: three text boxes, given, family and full. Once a part is edited, the full box follows the parts ("given family") while nobody has typed in it, and stops once someone does; a stored full name the parts would not give is the person's own and is left as it is, and an editor closed untouched writes nothing. Tab walks the three boxes, and a blur that lands on another box is not a close. It owns the boxes and what a close means; its host owns where it mounts, the write, and keeping each part in its own column. It commits a `NameValue` of `@viewkitjs/fields`, `{ full, given, family }`, or null. Guide: [editors](../guides/editors.md).
4
+
5
+ - `NameEditor` — the three boxes, the given box focused without scrolling; its ref is a `NameEditorHandle`. It takes `initial` (the stored name, or null) and `onRequestClose`, and optionally `seed` (the character that opened the editor, replacing the given box), `allowEmpty` and `conventions`.
6
+ - `NameEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels. The name is tidied as fields tidies one; the same name as `initial` is a `noop`; three empty boxes commit null with `allowEmpty` and cancel without it; anything else commits.
@@ -0,0 +1,11 @@
1
+ # `@viewkitjs/views/editors/number`
2
+
3
+ Import from `@viewkitjs/views/editors/number` in a client component: the door opens with the client directive. It holds the editor of a `number`, `percent` and `currency` field. It is inline: it replaces the cell's own content rather than opening a panel over it, so its closes are the keyboard's and the blur's (Enter, Tab, Shift-Tab, Escape, a blur) and never `outside`. It owns the input, the reading of what is typed, and the unit chip with its own popover, which never blurs the input into a commit. Its host owns where it mounts and the write. It commits a `NumberEditValue`. Guide: [editors](../guides/editors.md).
4
+
5
+ - `NumberEditor` — the number input, focused without scrolling; its ref is a `NumberEditorHandle`. It takes `initial` (the signed stored value), `onRequestClose`, and optionally:
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; `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
+ - 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
+ - Layout: `align`, `end` (the default, a right-aligned column) or `start` (a row read left to right, with the chip following the figure).
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.
11
+ - `NumberEditValue` — what a number commits: `{ value, unit }`, the value a number or null and the unit the chip shows (the `NumberCommit` of `@viewkitjs/fields`). The host maps it onto its row, such as a unit onto a currency column.
@@ -0,0 +1,10 @@
1
+ # `@viewkitjs/views/editors/open-values`
2
+
3
+ Import from `@viewkitjs/views/editors/open-values` in a client component: the door opens with the client directive. An open pick-list (a field whose vocabulary is `custom-values`) has no options of its own: its values are whatever its records hold, which your app's list answers. This door carries those values to every editor of the field: your app provides them above a surface (a record's panel, a list's body), and the panel row, the grid cell and the card read them, so a field offers the same values wherever it is edited. A host asks for a field's values once, when its editor mounts. A closed field, or no provider, reads none and asks nothing. Guide: [editors](../guides/editors.md).
4
+
5
+ - `OpenValuesProvider` — provides its `value`, an `OpenValues` or undefined, to the editors below it.
6
+ - `OpenValues` — what the provider holds: `values`, field key to the values the list answered for it, most used first; `labels`, field key to value to its name, for the named values of a relation, user or actor field; and `onWanted(fieldKey)`, called when an editor of an open field opens, so your app may fetch its values.
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
+ - `useOpenValuesContext` — the nearest provider's `OpenValues` whole, or undefined: what a host hands `buildRelationFilters` as `farValues`.
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.
@@ -0,0 +1,6 @@
1
+ # `@viewkitjs/views/editors/range`
2
+
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
+
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
+ - `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.
@@ -0,0 +1,12 @@
1
+ # `@viewkitjs/views/editors/relation`
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; 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
+
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
+ - `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. 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
+ - `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
+ - `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`.
@@ -0,0 +1,9 @@
1
+ # `@viewkitjs/views/editors/select`
2
+
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
+
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
+ - `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.
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.
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.
@@ -0,0 +1,11 @@
1
+ # `@viewkitjs/views/editors/session`
2
+
3
+ Import from `@viewkitjs/views/editors/session` in a client component: the door opens with the client directive. It holds the plumbing every host that opens an editor in a panel over a value repeats: the guard that lets a session answer once, and the gap that lets the popover's exit play before the value renders again behind it. A session that answers twice writes twice, and one that answers during its own exit unmounts the panel mid-flight. The host keeps its popover, its anchor, its focus and the shape of what it hands back. It is a door of its own so a host that needs the session does not load the editors. Guide: [editors](../guides/editors.md).
4
+
5
+ - `useAnchoredEditSession` — runs one edit session and returns an `EditSession`, `{ open, close, refusal }`. It opens already open; bind `open` to your popover and route every close to `close(reason)` (the popover's dismiss, the editor's `onRequestClose`, your own keys): only the first one counts. Escape always discards: on `close("escape")` the session answers a cancel without asking the editor. On any other reason it asks the editor's `resolveClose(reason)` through `editorRef` (a `noop` when there is no editor) and passes a commit's value through `mapPayload`, which never sees a cancel or a noop. Then one of two modes:
6
+ - Admitted, the one to prefer: `onAttempt(answer)` is asked at once whether this answer may close and returns an `EditSessionAttempt`. A refusal keeps the session open for another try, and its `reason` comes back as `refusal` until the next attempt; an acceptance closes it and calls `onClose` after the exit gap, a timer cleared if the host unmounts. While `onAttempt` runs the session counts as answered, so a close that arrives during it (a write that moves the focus, and a box that closes on blur) is ignored; a refusal, or an `onAttempt` that throws, opens it again for the next try.
7
+ - Deferred: the session closes at once and hands the answer to `onDone` after the exit gap, for a host whose answer still carries the write.
8
+ - Gap: `exitMs` sets it, defaulting to `EDITOR_EXIT_MS`.
9
+ - `EditSession` — what the session hands its host, and what `EditorPanel` (`@viewkitjs/views/editors/panel`) takes: `open`, `close(reason)`, and `refusal`, the reason the host gave for the last refused attempt until the next one, `null` otherwise and always in the deferred mode.
10
+ - `EditSessionAttempt` — the host's answer to an attempt: `{ accepted: boolean; reason?: string }`. A refusal may say why; the reason is what `refusal` shows.
11
+ - `EDITOR_EXIT_MS` — 160: the milliseconds an anchored host waits between closing its popover and reporting its answer, so the exit animation plays out first.
@@ -0,0 +1,9 @@
1
+ # `@viewkitjs/views/editors/text`
2
+
3
+ Import from `@viewkitjs/views/editors/text` in a client component: the door opens with the client directive. It holds the one editor for every text-like value: `text`, `url`, `domain`, `email`, `phone` and `rich_text`, a line or a paragraph. It tidies what was typed (trimmed; rich text tidied only at its edges, with fields' `normalizeMarkdown`, so its first line keeps its indent), and an unchanged value closes as no save. It owns the box and what a close means; its host owns where it opens (in place, a popover, a sheet), the session and the write. It commits a string. Guide: [editors](../guides/editors.md#a-text-box).
4
+
5
+ - `TextEditor` — the box, focused without scrolling, its caret at the end; its ref is a `TextEditorHandle`. A line draws through the components map's `Input`; a paragraph (`multiline`) is the package's own textarea. Keys: Escape asks `onRequestClose("escape")`; Enter asks `"enter"` (in a paragraph only with ⌘ or Ctrl, and a bare Enter is a newline); Tab and Shift-Tab ask `"tab"` and `"shift-tab"`; leaving the box asks `"blur"` unless `closeOnBlur` is false. The box carries `data-slot="vk-text-editor"`.
6
+ - `TextEditorProps` — `type` (a `TextEditorType`), `initial` (the stored value, `""` when unset), `onRequestClose`, and optionally `seed` (type-to-replace: the draft opens on it, compared against `initial`), `multiline` (a paragraph; the default for rich text), `readOnly` (every close a `noop`), `closeOnBlur` (default true; a host in a popover or a sheet passes false), `label` (the box's accessible name), `chrome` (handed to your `Input`: `bare`, the default, or `field`), `rows` and `maxLines` (a paragraph opens at `rows`, default 1, and grows with its text to `maxLines`, default 12, then scrolls; `maxLines` no greater than `rows` keeps it at `rows`), `className`, `style`, and `boxData` (`data-*` attributes set on the box, over its own slot).
7
+ - `TextEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Read-only answers `noop`; Escape cancels; otherwise the tidied draft against the tidied `initial`: equal is a `noop`, different a `commit` of the tidied draft.
8
+ - `TextEditorType` — the types it edits: `text`, `url`, `domain`, `email`, `phone`, `rich_text`.
9
+ - `TEXT_INPUT_TYPE` — the native input type per `TextEditorType`, the phone keyboard each brings: `text` and `rich_text` `text`, `url` and `domain` `url`, `email` `email`, `phone` `tel`.
@@ -0,0 +1,6 @@
1
+ # `@viewkitjs/views/editors/value-list`
2
+
3
+ Import from `@viewkitjs/views/editors/value-list` in a client component: the door opens with the client directive. It holds the editor of a field holding several values of one kind (a `multiple` email, phone, url or domain field), each with its label and one of them the main one. It is a draft, like the chips editor: the whole list commits once when the host closes it. It owns the rows, the reading of each value and what a close means; its host owns the popover, the anchor and the write. It commits a list of `ValueItem`s of `@viewkitjs/fields`, `{ value, label, main }`, the main one first, or null. Guide: [editors](../guides/editors.md).
4
+
5
+ - `ValueListEditor` — the list of rows; its ref is a `ValueListEditorHandle`. Each row carries its main mark, its value, its label and a remove; an Add row appends an empty one, and an empty list opens on one blank row. Each value is read by its type's own rule (the field's single-value commit: an email's shape, a domain cleaned, a phone read in the region) when focus leaves its row, and a refusal shows under the row. Tab walks each row's mark, value, label and remove, then Add; Enter in a box and Tab out of the editor check every row first and stay open on a refusal. It takes `field`, `initial` (the stored list, as items or as plain values) and `onRequestClose`, and optionally `labels` (default true; false draws no label boxes and commits every label null), `allowEmpty`, `region` (the record's country, where a phone typed without its country code is read; else the conventions' region) and `openLinks` (each stored value carries an open action beside it: mail, call or browse; a row typed over has none until it is saved; default false).
6
+ - `ValueListEditorHandle` — what the host's ref reads: `resolveClose(reason)`, synchronous and safe to ask twice. Escape cancels; any other close keeps what was built. Blank rows are dropped. A row left untouched keeps its stored value exactly as stored, and a row typed in commits its trimmed text for the field's commit to read. With no main mark the first row is the main one. The same values, labels and main as opened is a `noop`; an empty list commits null with `allowEmpty` and cancels without it.
@@ -0,0 +1,5 @@
1
+ # `@viewkitjs/views/editors`
2
+
3
+ The table of editors, one per storage type. The door carries no client directive; each editor file behind it carries its own, and each editor also has a door of its own, which a host imports when it needs one editor and not the table. An editor owns its panel and what a close means. Its host (a grid cell, a form field, a drawer row, a card) owns the popover, the anchor, focus, when to commit, and the write. Every editor speaks the same handshake: when it sees a key or a pick that means done, it calls the host's `onRequestClose(reason)`; the host closes, then asks the editor's handle `resolveClose(reason)`, which answers `commit` with the value, `cancel` or `noop` (the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`). The words an editor draws come from the provider; an editor that takes `message` reads the fields messages from it instead. `hasEditCore`, documented with the root door, says whether a type has an editor of its own without loading any editor. Guide: [editors](../guides/editors.md).
4
+
5
+ - `EDIT_CORES` — the editor for each storage type, one member for every `FieldType`, so a type added to fields with no answer here fails to compile. `date` and `datetime` share `DateEditor`, `select` and `status` share `SelectEditor`, `multiselect` is `ChipsEditor`, `relation` and `user` share `RelationEditor`, `number`, `percent` and `currency` share `NumberEditor`, and `range`, `name` and `location` each have their own, and `text`, `url`, `domain`, `email`, `phone` and `rich_text` share `TextEditor`. A `null` member is a decision, not a gap: a `boolean` is edited by its checkbox, an `actor` is set by the system, and `lookup`, `rollup` and `formula` are read-only or derived. Each member is typed as its editor's props and handle, so binding the wrong editor is a type error. `ValueListEditor`, for a field holding several emails, phones, links or domains, has its own door and no member here.
@@ -0,0 +1,16 @@
1
+ # `@viewkitjs/views/field-row`
2
+
3
+ Import from `@viewkitjs/views/field-row` in a client component, under your `ViewsProvider`: the door opens with the client directive. It holds a record's field row: one field drawn as its label, its value and, on a click, its type's editor in place, and the write path that admits each edit at once, queues one record's writes, settles each on the save's receipt and rolls a failure back. The row knows no entity, only a binding, a value and a commit, so your app builds its record's panel (its sections, its related records) around the rows. It draws with your provider's `Popover`, `Sheet`, `Collapse`, `AppIcon`, icons, `CommandMenu` atom and toast port. The shapes its writes go through (the write target, the receipt, the admission, a value's note, the reconciliation error) are the root door's, described under [A write's target](views.md#a-writes-target), and this door re-exports them. Guide: [editors](../guides/editors.md).
4
+
5
+ - `FieldRow` — one field of a record: a glyph (the binding's `icon` through your `AppIcon`, else the type's icon), the label, and the value drawn by the display. A writable row opens its type's editor on a click, through the editor panel and one edit session: a picker (a select, a date, several tags, a relation or a set of records, several values, a place) anchored under the value in your `Popover` on a desktop and in your `Sheet` on a phone, by the provider's `desktopQuery`; a typed value (text, a number, money, a range, a name) in its own box on every width. Escape always throws the edit away, and a sheet's swipe or ✕ changes nothing. On a desktop, an editor closed by Tab, Shift-Tab, Escape, Enter or a pick puts the focus back on the row's own button, once a write still saving has saved and unless the focus moved meanwhile, so the next Tab moves on from that row; an outside press leaves the focus where it put it. A relation saves what its row stores (an id, a ref with the picked record's kind, or a set of records with its lead); a date field has no time box and ends with a Clear row where it may be empty; several values read a phone typed without its code in the binding's `region`. A value of several parts inside a writable row draws its count as plain text: the row's press opens the editor, which lists them all. A single email, phone, link or domain in a writable row reads as plain text too, with an open action beside the row's button (a mail, a call, the site), and a writable rich text lies over its button, so its links and "Show more" keep their own press while a press on its text edits. A money figure its host reads in another currency than the record's own (it hands the converted figure as `value` and that currency as `opts.currency`) is marked ≈ with the currency it came from, and its editor names it under the record's own amount. A boolean commits from its own control, a `command` field opens its verbs, and a read-only row draws a lock with its reason. A refused commit keeps the editor open with the reason under it, a saved value shows at once and stays until the receipt settles it, and a failed save rolls back with a retry.
6
+ - `FieldRowProps` — the row's props: `binding`, `row`, `value` (the display value), `editValue` (the stored value the editor opens on), `writable`, `ready` (false refuses gestures while the record loads), `unread` (the value isn't read yet, drawn blank), `refusal` (why it's read-only here), `onCommit` (admits or refuses a draft, then settles), `opts` (display options), `menu` (a `command` field's verbs), `meta` (a few words in the value's line), `note` (a sentence under the value, with an optional quote a tap opens) and `kindIcon` (your icon name for a record kind, the glyph a relation's candidates wear; unanswered, they wear the type's glyph).
7
+ - `RowEditor` — the editor a row mounts for its field's type, picked from `ROW_HOSTS`.
8
+ - `ROW_HOSTS` — the host each field type mounts in a row, or `null` for a type the row never opens (a boolean, a derived or system field).
9
+ - `RowEditorProps` — what a host receives: `binding`, `row`, `initial` (the stored value), `anchor` (the value as drawn, kept under an anchored editor), `shown` (the display value, whose labels a set of records opens on), `conversion` (the marked figure, when the row showed the amount converted, which a money host names under it), `onAttempt`, `onClose` (called with a `RowClosed` once the editor's exit has played out), `message` and `kindIcon`.
10
+ - `RowClosed` — what a host's close tells its row: `focusBack`, true when the editor closed from the keys or a pick off a sheet, and the row takes the focus back on its button.
11
+ - `RowEditorAttempt` — the row's answer to a close: `{ accepted: true }`, or `{ accepted: false, reason }`, which keeps the editor open.
12
+ - `RowHostProps` — a host's props: `RowEditorProps` plus the field narrowed to the host's types.
13
+ - `useFieldWrite` — the write path for one record: given `FieldWriteOptions`, it returns `commit(fieldKey, value)`, which answers a `FieldWriteAdmission` at once, and `row`, the latest confirmed row. A commit is refused at once when the guard, a pending reconciliation, the same field still saving, a lock or the binding refuses it. Writes to one record run one at a time, a queued one mapped again at dispatch against the latest row. A failed save toasts through your toast port and rejects, and `refresh` runs in the background after each save.
14
+ - `FieldWriteOptions` — `row`, `rowId`, `bindings`, `write` (an `EntityWriteTarget`), `refresh`, and optionally `locked`, `admit`, `conventions` (default: the provider's), `refusalOf` (reads a failed save's own sentence, shown after the toast's failure line and on the row) and `timing` (follows each edit from its commit to the paint, named `<noun> <fieldKey> drawer edit`).
15
+ - `EditTiming` — what `timing` returns: `mark(step)`, `painted()` and `failed()`.
16
+ - `FieldWriteRefusal` — the error a write rejects with when it is refused with a sentence of its own: by the server (the sentence `refusalOf` read), or at dispatch, when a queued edit is mapped again and the guard, a lock, a missing binding or the binding's write refuses it. The row shows its message.
@@ -0,0 +1,39 @@
1
+ # `@viewkitjs/views/grid`
2
+
3
+ The spreadsheet. The door carries no client directive; every rendering file behind it carries its own. What a column is (its schema, what may be done to it, its filters, its preferences) is the model of the root door, which every view reads; this door holds what a grid alone owns, the renderer and its personal preferences, and the helpers a host's binding shares with it: the commit types, the values a column's filter offers, a cell's copy text and the value an edit starts from, and the title link's class. The selection bar, the house menu rows, the group collapse and the type icons stay your app's: the grid takes them through its props. Guide: [the grid](../guides/the-grid.md).
4
+
5
+ ## The grid
6
+
7
+ - `GridTable` — draws the spreadsheet: rows in their groups under a header whose column menus sort, group, format and hide, a checkbox rail and a ⋯ tail on each row, editors opened over cells, a selected range with copy, paste and undo, and a footer of figures per column. An edit shows in its cell at once and goes to `onCellCommit` (a batch to `onCellsCommit`); a failed write rolls the cell back. While `transitionPending` is true, or for one commit after `transitionKey` changes, it draws your app's loading atom instead of the rows. It takes a `GridTableProps`.
8
+ - `GridTableProps` — what `GridTable` takes, flat, typed over your row. Five are required: `groups` (the rows, as the model's `ListGroup`s), `grouped` (whether they draw as group bands), `getRowId`, `columns` (the model's `ListColumn`s) and `onOpenRow` (what opening a row does: the title's text opens it). The rest are optional:
9
+ - Rows and groups: `rowHref`, `onPrefetchRow` (warm a row's detail on a pointer's intent), `rowClassName`, `rowIcon` and `showRowIcon` (the title cell's glyph, as a descriptor the grid sizes and colours), `onOpenRelation` and `entityIcon` (opening the record a relation cell points at, and the glyph for a kind; without `onOpenRelation`, relation cells are inert), `isCollapsed` and `onToggleGroup` (your group collapse), `renderGroupLabel`, `renderGroupFooter` (a group's paged continuation after its loaded rows), `onHideGroup`, `countOf`, `loadMore` (`hasMore`, `onReveal` and a `label`), `emptyState`, and `transitionKey`, `transitionPending` and `transitionLabel` (a view change: the wait paints before the new rows mount).
10
+ - Row actions and menus: `rowMenu` (a row's items, on right-click and in its ⋯ tail; the same builder a list takes), `contextMenu` (a right-click menu that differs from it), `rowActions` (buttons in the title cell's action lane, before the grid's own Edit), `onRowDelete` and `deleteLabel` (a delete row in the row's menu), `commands` (the verbs a `command` column's cell opens, by field key; without it a command column is a read-only badge) and `selection` (the list's selection; the bar it opens is yours).
11
+ - Sort, group and figures: `sort` (`GridSortState`), `groupBy` (`GridGroupByState`), `sortOptions` (the group band menu's sort, as `GridGroupSortOption`s), `groupSummary` and `onGroupSummaryChange` (which figures ride beside a group's name), `groupFigures` (`GridGroupFigure`s), `countNoun` (`GroupCountNoun`), `aggregates`, `onAggregateChange` and `renderAggregate` (the footer's figure per column), `viewBacked` (a saved view, which changes figures only for field-backed columns) and `defaultCurrency` (the reader's currency, which a money column read as it was entered totals in).
12
+ - Format overrides and their handlers, every map keyed by field key: `optionColors`, `dateStyles`, `durationStyles`, `numberFormats` (decimals null is the field's own), `showTimeOverrides` and `percentDisplays`, each with its `on…Change` handler taking the field key first, and `formatsWritable` (false hides the stored format knobs from the column menu; default true).
13
+ - Columns and preferences: `columnState` and `onColumnStateChange` (order, widths, and which columns show), `renderAddColumn` (your own add-column cell at the header's end; without it, the grid's own lists the hidden columns), `renderColumnMenuRows` (your rows in a column's menu, above Hide), and the per-user toggles `freezeIdentity` (true on the bare prop, but a grid wired through `useGridTablePrefs` takes the preference `gridFreezeIdentity`, false in `LIST_VIEW_PREF_DEFAULTS`, so its identity columns start unfrozen until the person turns it on; start your prefs with `gridFreezeIdentity: true` to open it frozen), `alwaysCheckboxes`, `verticalBorders` and `scale`.
14
+ - Writes: `onCellCommit` (`GridCellCommitFn`) and `onCellsCommit` (`GridCellsCommitFn`).
15
+ - List config: `listConfig` (the settings layer every user of the list inherits, which may only take away from what the columns declare: the table read-only, per-column locks; a constraint on the screen, while your API guards its own writes). The grid only reads it: a surface of your own changes it.
16
+ - `useGridTablePrefs` — wires a list's view preferences to the grid. It takes `prefs` (the list's `ListViewPrefs`), `setPrefs` (stores a patch of them), `columns` (whose money reading the number formats read) and `viewBacked`, and returns `{ gridProps }` to spread on `GridTable`: the borders, row icon, frozen identity, checkboxes and scale, the format overrides, the column state, the group figures and the footer figures, each with the handler that writes it back through `setPrefs`.
17
+
18
+ ## Sort, group and figures
19
+
20
+ - `GridSortState` — the list's sort, as the header menu reads and writes it: `value` (the sort key in force), `dir` and `onChange({ value, dir })`. The menu is a second control for the same stored sort your view's options drive.
21
+ - `GridGroupByState` — the view's grouping, for the header menu's Group by and Ungroup: `fieldKey` (or null) and `onChange(fieldKey)`, null to ungroup. Present on lists backed by a saved view.
22
+ - `GridGroupSortOption` — one sort a group band's menu offers, sorting the rows of every group at once: its `value`, `label` and an optional `defaultDir`.
23
+ - `GridGroupFigure` — one figure a group's header can show: the summary `part` that turns it on, its column's header as its `label`, and `render(group)`, how it draws for a group.
24
+ - `GroupCountNoun` — a group count's noun, `{ one, other }`, so a header reads "2 companies"; without one the count is bare.
25
+
26
+ ## Writes
27
+
28
+ - `GridCellCommitFn` — writes one cell: `(row, columnId, value, context?)`, returning a promise of nothing or a `GridCommitOutcome`. Nothing counts as confirmed; a rejection rolls the cell back. `context` is present on an undo or a redo.
29
+ - `GridCellsCommitFn` — writes several cells at once (a paste, a fill, an undo of several): `(edits)`, each `{ row, columnId, value, context? }`, returning a promise of nothing or one outcome per edit, in order. A failed edit rolls its own cell back. Without it, or for a single cell, the grid calls `GridCellCommitFn` for each.
30
+ - `GridCommitContext` — what a write is: `{ kind: "commit" }`, with `reload: false` when the caller reloads once after a second write, or `{ kind: "restore", expected }`, an undo or a redo writing a value back, `expected` the value the cell is held to before it.
31
+ - `GridCommitOutcome` — how a write ended. `confirmed`, with an optional `history` (false keeps it out of undo, or `{ prev, next }` are the values undo and redo write instead), `settlement` (`requested`: the row holds the value but its provider has not accepted it yet, and the cell says so) and `stored` (what was kept, when it isn't what the cell sent, as the row reads it in this column: the cell shows it in place of what was typed, undo and redo restore from it, and no "changed elsewhere" follows; ignored on an undo or a redo); `unconfirmed`, never in the undo history; or `failed`, with an optional `error`, which rolls the cell back.
32
+
33
+ ## Helpers a binding shares
34
+
35
+ - `deriveGridSelectValues` — the values each select, status and multiselect column offers, given the columns and the rows: column id to values. A status offers its options; a select or multiselect offers its options, then the values the rows hold, each once. Archived values are left out unless `includeArchived` is set, as a filter sets it so a row still holding a retired value can be found.
36
+ - `deriveGridRelationValues` — the relations present in the loaded rows, given the columns and the rows: column id to `ListRelationValue`s, each once, sorted by label, for every relation, user and actor column (an actor's id is its key). It reads the rows, never the candidates a column can link to, so a filter lists only what the table holds.
37
+ - `cellEditBaseline` — the value an edit of a cell starts from: the column's pending value when one is given, else the column's `editAccessor`, else its `accessor`.
38
+ - `cellCopyText` — a cell's value as copied text, given its column and its baseline (from `cellEditBaseline`), which a CSV export can reuse. Empty for no value; a relation or an actor copies as its name, not its id; a select, status or multiselect copies as its options' labels, not their keys; a place, a name and a range copy as their cells write them; a list copies its items joined by commas, several values of one kind their values, the main one first.
39
+ - `GRID_TITLE_LINK_CLASS` — the class that dresses the row-open text inside a title cell (the element carrying `data-cell-open`) as a link on its own hover: the brand colour and an underline.
@@ -0,0 +1,89 @@
1
+ # `@viewkitjs/views/react`
2
+
3
+ Import from `@viewkitjs/views/react` in a client component: the door opens with the client directive, and every name behind it is a client-side thing. It holds the provider your app mounts once above its views, the types your adapter implements (the components map, the icons, the ports), and the atoms the rendering is built from. It also re-exports five names of the root door, `ComponentName`, `PortName`, `ViewsIconName`, `ViewsMessage` and `ViewsMessageResolver`; those are documented on the root's page, [views](views.md), not here. The model half of the package, with no React at runtime, is `@viewkitjs/views`.
4
+
5
+ ## The provider
6
+
7
+ Guide: [the provider](../guides/the-provider.md).
8
+
9
+ - `ViewsProvider` — the provider every view reads: mount it once at your app's client root, above every view, with its components, icons, ports and conventions. It lays your atoms over the defaults, hands your `Menu` its items with every row under a disabled group already disabled, and fills in the browser's own confirm where your ports carry no `confirm`. It hands its views one context value per distinct set of inputs, so pass module-level objects: a new one on each render re-renders every view.
10
+ - `ViewsProviderProps` — what the provider takes. Its optional `desktopQuery` is the media query that means a desktop, so an editor opens as a popover there and as a sheet elsewhere; hand in the one your own shell switches on. Default `DEFAULT_DESKTOP_QUERY`.
11
+ - `DEFAULT_DESKTOP_QUERY` — `(min-width: 1024px)`: the width a desktop starts at when the provider is handed no `desktopQuery`. Where the screen can't be asked (a server render, a browser with no `matchMedia`), it is a desktop.
12
+ - Required: `components` (your primitives, `ViewsComponents`), `icons` (your glyphs by meaning, `ViewsIcons`), `ports` (your runtime services, `ViewsPorts`), `conventions` (the `FieldConventions` of `@viewkitjs/fields` every value is read with) and `children`.
13
+ - Optional: `atoms`, any of your own atoms, each laid over the default of its name; `messages`, your wording for the package's own messages, defaulting to `resolveViewsMessage` (the package's English); `presentation`, `(defaults: FieldPresentation) => FieldPresentation`, how your numbers, dates and durations read: given the package's defaults in the conventions' locale, return yours. It is called where a value is drawn, so your provider imports none of the display.
14
+ - `useViews` — reads the nearest provider's value inside a view or an atom of your own. It throws an error that says where to mount one when no `ViewsProvider` is above it.
15
+ - `ViewsContextValue` — what `useViews` returns: the `components` (your `Menu` wrapped to settle disabled groups), the merged `atoms`, the `icons`, the `ports` as `ViewsResolvedPorts` (`confirm` always a function), the `messages` resolver, the `conventions`, your `presentation` when you handed one, and the `desktopQuery` in force (yours or `DEFAULT_DESKTOP_QUERY`).
16
+ - `NOOP_PORTS` — ports that do nothing, for a server render, a test or an app without a device: the toasts and haptics are empty, the clipboard writes nothing (resolving `false`) and reads `null`, and the prefs store keeps nothing. It carries no `confirm`, so the provider falls back to the browser's.
17
+
18
+ ## The components map
19
+
20
+ The primitives your app hands in, modelled on Base UI's shapes: a controlled `open` with `onOpenChange(open, details)`, an `anchor` rather than a trigger child on the popover and the menu, and no `asChild`. An adapter on Base UI wraps its copies thinly; one on Radix absorbs the difference. The package ships none of them and depends on neither library. The [contract](../contract.md) says what each slot promises and how to write an adapter.
21
+
22
+ - `ViewsComponents` — the map itself, one key per name of the contract's components: `Button`, `Popover`, `Tooltip`, `Checkbox`, `Menu`, `Command` (the command list's parts), `Calendar`, `Collapse`, `Sheet`, `AppIcon` and `Markdown`. `AppIcon` is your own icon component, taking `name` and `className`, for the glyphs a host declares (a row's icon, a binding's icon); it draws on the first paint, because rows are measured as they mount, so map its names from a static record. `Markdown` is your markdown renderer, handed the stored text whole as `source`; the package parses no markdown itself. One key is optional, `Input`: leave it out and the editors draw a plain `<input>`.
23
+ - `ViewsResolvedComponents` — the map as `useViews()` hands it on: yours, with `Input` always there, your own or the plain one.
24
+ - `ViewsButtonProps` — a button: its `children`, `onClick`, `disabled`, a `variant` (`default`, `ghost`, `outline`, `destructive`), a `size` (`default`, `sm`, `icon`), its `type`, a class, `aria-label` and `title`.
25
+ - `ViewsPopoverProps` — a popover opened at an `anchor`, controlled by `open` and `onOpenChange`, placed by `side`, `align`, `sideOffset` and `alignOffset`.
26
+ - Focus: `initialFocus` false keeps focus where it was when the popup opens, for an editor that focuses its own input (with `preventScroll`). Default true.
27
+ - Vetoes: `onOutsidePress` is handed the pointer press, its `target` where it landed, and returns `false` to keep the popup open, also against the focus that press moves; focus leaving by keyboard closes without asking. `onEscape` does the same for Escape.
28
+ - Look: `chrome` is `panel` (your card popover, the default) or `menu` (your menu panel's surface, for a popover that holds a list: no inset, no card width). `onPanelClick` takes a click inside the popup, `panelData` sets `data-*` attributes on it, and `style` carries what a class cannot say, such as a width that follows a cell.
29
+ - `ViewsTooltipProps` — a tooltip around the element it wraps (`children`), showing `content`, with `side`, `align`, `delayMs` and a class. Your app mounts one tooltip provider above the views; a tooltip never mounts its own.
30
+ - `ViewsCheckboxProps` — a checkbox: `checked`, and `indeterminate` for a box ticked partly, whose press hands `true` while `checked` is false. `onCheckedChange` hands the new value and, where your library reports it, `{ event }`, the press that changed it (a list reads its shift key for a range). `partialTone` colours the partial mark, `muted` by default or `brand` for a select-all with a live selection; with `disabled`, a class, `tabIndex` and `aria-label`.
31
+ - `ViewsMenuProps` — a menu opened at an `anchor`, with no trigger child and no flyouts, controlled by `open` and `onOpenChange`, drawing its `items` and placed by `side` and `align`. On Base UI it is the menu's root, positioner and popup, the anchor handed to the positioner.
32
+ - `ViewsMenuItem` — one row of a menu, as data your `Menu` draws: its `key`, `label`, `icon`, `onSelect`, `disabled` and `destructive`, a `separatorBefore`, a `shortcut` hint drawn at its end and never bound, and an `href` that makes it a link (with `onSelect` still firing). A `checked` row is checkable and closes the menu like any row. A row with `children` is a group: its rows drawn in place under its label, never a flyout, its own `onSelect`, `href` and `checked` ignored; a disabled group's rows reach your `Menu` already `disabled`.
33
+ - `ViewsCommandParts` — the command list's parts, the shape cmdk-based copies already have: `Root` (taking `label`, `shouldFilter` false to hand filtering to the host, a scoring `filter`, `loop` to wrap the arrows, and `defaultValue`, the value of the item highlighted as the list opens, none while no item has it), `Input` (a controlled `value` with `onValueChange`, a `placeholder`, `autoFocus`, a `ref`, `onKeyDown`, and `chrome` `search` for your search row or `bare` for the input alone), `List`, `Empty`, `Group` (with a `heading`) and `Item` (a `value`, `onSelect`, `disabled`, and `chosen`, which you colour as your chosen row while the package's row inside draws the check).
34
+ - `ViewsCalendarProps` — a calendar over ISO days (`YYYY-MM-DD`): its `value` and `onChange`, `min` and `max`, a `month` (`YYYY-MM`) controlled with `onMonthChange`, a `captionLayout` of `label` or `dropdown`, the `startMonth` and `endMonth` its pickers offer, and `locale`, the conventions' locale, in which it draws its month and weekday names and starts its week (an adapter may keep its calendar's own). Your date library stays your own.
35
+ - `ViewsCollapseProps` — a box that opens and closes its `children` with `open`, over `durationMs`, with a class and a `clipClassName` on the box that crops the content.
36
+ - `ViewsSheetProps` — a phone sheet, controlled by `open` and `onOpenChange`, with a `title`, a `description`, a class, its `children`, and `snap` (`full`, `half`, `peek`, `auto`), a hint a sheet with no snap points ignores.
37
+ - `ViewsInputProps` — a single-line text box: every prop of an `<input>`, `ref` included, which your element must receive, and `chrome`, `bare` (the default: a grid cell, a panel that frames the box) or `field` (your field's frame).
38
+ - `ViewsAnchor` — where a floating part attaches: an element, a ref to one, a point `{ x, y }` (a context menu), or `null`.
39
+ - `ViewsSide` — the side a floating part opens on: `top`, `right`, `bottom` or `left`.
40
+ - `ViewsAlign` — how a floating part lines up along that side: `start`, `center` or `end`.
41
+ - `ViewsCloseReason` — why a floating part closed, by Base UI's names: `trigger-press`, `outside-press`, `escape-key`, `focus-out`, `item-press`, `close-press` (a close button inside it), `swipe` (a sheet dragged away), and `none` for any other reason your library reports.
42
+ - `ViewsOpenChange` — the `onOpenChange` callback a popover, a menu and a sheet take: the new open state, and optional details carrying its `reason`.
43
+
44
+ ## The icons
45
+
46
+ The glyphs the rendering asks for, by meaning; the names are listed in the [contract](../contract.md). Your app maps each one to a component of its own icon library, and the package imports none.
47
+
48
+ - `ViewsIcons` — the record your app hands the provider: every icon name the contract lists, each to a component taking `ViewsIconProps`.
49
+ - `ViewsIconProps` — what an icon component takes: an optional `className`.
50
+
51
+ ## The ports
52
+
53
+ Guide: [ports](../guides/ports.md).
54
+
55
+ Runtime services your app hands in, each the narrowest surface the rendering needs, so your toast library, haptics module, clipboard helper, per-device store and dialog map onto them in a few lines.
56
+
57
+ - `ViewsPorts` — what the provider's `ports` takes: `toast`, `haptics`, `clipboard` and `viewPrefs`, each required, and `confirm`, optional. Without a `confirm`, a destructive act asks the browser's own confirm with its message.
58
+ - `ViewsToastPort` — the toasts: `success`, `error` and `info`, each taking a message, and `warning`, taking a message and an optional `description` as a second line, for a change the person did not make (a value someone else wrote).
59
+ - `ViewsHapticsPort` — the device's haptics: `selection()`, `impact(style)` (`light`, `medium`, `heavy`) and `notification(type)` (`success`, `warning`, `error`). An app without a device hands in no-ops.
60
+ - `ViewsClipboardPort` — the clipboard: `writeText(text)` resolving to whether the text reached it, and `readText()` resolving to its text, or `null` where reading is refused.
61
+ - `ViewsPrefsPort` — per-device state the grid keeps between visits, such as a column's width before the view saved it or a collapsed group: `get(key)`, `set(key, value)` and `subscribe(key, listener)`, which returns its unsubscribe. The keys are the package's, namespaced `vk:`.
62
+ - `ViewsConfirmPort` — a question asked before an act: takes a `ViewsConfirmRequest` and resolves to whether the person said yes. A rejection or a throw counts as no.
63
+ - `ViewsConfirmRequest` — what the confirm port is asked: the `message` (the package's words, such as `views.menus.row-delete-confirm` before a row's Delete), the yes button's `confirmLabel`, the `subject` the act is done to as the host names it (a row's `deleteLabel`, absent when it names nothing), and `destructive` when the act removes something, so your dialog draws its destructive look.
64
+ - `ViewsResolvedPorts` — the ports as the provider hands them on through `useViews`: your ports, with `confirm` always a function, the browser's where you handed none.
65
+
66
+ ## The atoms
67
+
68
+ Guide: [atoms](../guides/atoms.md).
69
+
70
+ The pieces the rendering is built from, and your app's own pieces it cannot draw itself. Each ships as a default, drawn from your app's colours and marked with its own `data-slot`; your app swaps any of them through the provider's `atoms`, and the rest stay the defaults. A swapped atom marks itself as your app does. The [contract](../contract.md) lists their slots and states.
71
+
72
+ - `DEFAULT_VIEWS_ATOMS` — the atoms every app starts with, one default per name of `ViewsAtoms`; the provider lays your `atoms` over it.
73
+ - `ViewsAtoms` — the full set, one component per atom: `List`, `Row`, `RowContent`, `TickBox`, `StatusBadge`, `StatusMarker`, `Tag`, `CommandMenu`, `RelationLink`, `Loading`, `LoadMore`, `PlatformMark` and `RowMenu`. The provider's `atoms` takes any part of it.
74
+ - `ViewsListProps` — the rows' container, the inset a run of rows sits in inside a panel or a command list's group: its `children` and a class.
75
+ - `ViewsRowContentProps` — a row's inside, all the row is inside a command list's item, which owns the element, the highlight and the keyboard.
76
+ - What it says: a `label` (text truncates to one line, any other node is laid out in a row so it centres; `wrap` lets a long label break), a `description` line under it, a `leading` glyph (with `leadingLane` to keep its width when there is none), `trailing` content after the label, and a `detail` at its right edge in the subtle colour, such as a setting's current choice.
77
+ - How it reads: `chosen` draws a trailing check (a chosen row with a `detail` draws the detail in the brand colour and no check), `chosenTint` false keeps a badge label's own colour, `tone` `muted` for a row that offers rather than lists (none, create, add), and `size` `compact` (13px) or `regular` (your menu size, the default).
78
+ - `ViewsRowProps` — a whole row: everything `ViewsRowContentProps` takes, as a button, or with `interactive` false a static line. It adds `onClick`, `onMouseDown` (for a row inside an editor that keeps its input focused), `disabled`, `title`, a `role` with `aria-selected`, and `opens` and `open` for a row that opens a flyout beside its menu.
79
+ - `ViewsTickBoxProps` — a paint-only tick box: `checked` and a class. The control around it is the caller's.
80
+ - `ViewsStatusBadgeProps` — a pill coloured by a status slot of `@viewkitjs/fields`: its `slot` and `label`, a `leading` mark that replaces the slot's own, a `title`, a `size` (`compact`, 11px, the default, as a status value is drawn in a cell; or `regular`) and a class.
81
+ - `ViewsStatusMarkerProps` — an attention badge that opens its reason in a popover: its `label`, its `title` (the panel's heading and the marker's accessible name), a `slot` (`warning` by default), the `reason`, the `emptyReason` shown when there is none (the package's wording by default), and `onResolve` with its `resolveLabel`; without `onResolve` the marker is read-only.
82
+ - `ViewsTagProps` — a category chip: its `label` and category `color`, a `leading` glyph (an option's icon, drawn by your `AppIcon`), a class, and `onRemove`, which draws a remove control, named by `removeLabel` (the package's wording by default).
83
+ - `ViewsCommandMenuProps` — a `command` cell's verb menu: the `trigger` the cell drew (a button), the host's `items` as `FieldRowMenuItem`s, and `align`. The default is your components map's `Menu`; your app may swap in its own action menu.
84
+ - `ViewsRowMenuProps` — the row's right-click menu, around the row it opens on (`children`): opened by a right-click on the row or by its ⋯, it lists an Open page row for `openHref` (a new tab), the `items` the rendering built, and a Delete row when `onDelete` is given, called with `rowId` once the confirm port says yes, with `deleteLabel` as its `subject`. A delete that rejects says so through the toast port's `error`. `onToggleSelect` flips the row's selection, for an app whose long-press selects; the default doesn't use it, and a long-press on a phone opens nothing.
85
+ - `ViewsRowMenuItem` — one row of the row's menu, the shape a host's own row-menu items already have: a rule (`{ separator: true }`), or a row with its `label`, `icon`, `onClick`, `destructive`, `disabled` and a `shortcut` hint drawn at its end and never bound.
86
+ - `ViewsRelationLinkProps` — where a relation chip goes: the `relation` value and the chip the display drew as `children`, for your app's own link around it. The default goes nowhere, since a relation is a fact as often as a destination.
87
+ - `ViewsLoadingProps` — a wait: `placement` `body` (the whole list reloading) or `footer` (more rows arriving), and the `label` read to assistive technology. The default is a plain ring, larger in the body.
88
+ - `ViewsLoadMoreProps` — how a list asks for its next page once its end comes near: `onReveal`, and an optional `label` drawn while it waits. The default watches a sentinel past the last row, calls `onReveal` as it comes within 600px of the end of what it scrolls in (the grid's own scroll area, else the viewport), and draws your `Loading` (or the label) meanwhile.
89
+ - `ViewsPlatformMarkProps` — a link's platform, drawn before the link: the `platform` (its key says which, its name what to call it) and a class. The default draws nothing, so a link looks plain; the package ships no brand art, so an app that wants marks draws its own.
@@ -0,0 +1,33 @@
1
+ # `@viewkitjs/views/selection`
2
+
3
+ Import from `@viewkitjs/views/selection` to let people pick rows of a list: the selection over the rows' visual order with a range anchor, the row checkbox, the drag down its lane, the rules a row click follows, and the rest that starts a record's read before the click. The door carries no client directive; each hook and component file behind it carries its own, and they read the provider's components and haptics. The bar a selection opens, and what its verbs do, stay your app's.
4
+
5
+ ## The selection
6
+
7
+ Guide: [selection](../guides/selection.md).
8
+
9
+ - `useListSelection` — a list's selection: takes `orderedIds` (the ids in visual order, after filter, sort and grouping), an optional `retention` (`"ordered"` by default) and an optional `resetKey`, and returns a `UseListSelectionResult`. A new `resetKey` empties it. Turning rows on or off ticks the provider's `haptics.selection()`; selecting all gives a medium impact; `clear` is silent.
10
+ - `UseListSelectionResult` — what `useListSelection` returns: `selectedIds`, `count`, `isSelected(id)`, `anchorId`, `allSelected` and `someSelected` (some but not all, for an indeterminate box), and the verbs `toggle(id, next?)` (sets the range anchor), `toggleRange(id)` (adds the run from the anchor to `id`), `toggleMany(ids)` (selects them all, or clears them when all are selected), `selectAll()`, `clear()` (also resets the anchor) and `setSelected(ids)`.
11
+ - `SelectionRetention` — what happens to a selected id that leaves the visual order: `"ordered"` drops it; `"external"` keeps it, for a selection across a whole query whose rows need not all be loaded. Either way the range anchor must stay visible to count.
12
+ - `useEscapeToClear` — while `active` is true, Escape anywhere in the window calls `clear`.
13
+ - `ListSelectionConfig` — what a list or table takes to be selectable (the grid's `selection`): `resetKey` (the selection clears when it changes) and `renderBar` (draws your bar from the selection and, when the renderer can write, a `ListBatchApi`), with optional `orderedIds` and `retention`.
14
+ - `ListBatchApi` — the batch write a renderer with an editing model hands your bar: `setColumnValue(rowIds, columnId, value)`, resolving to whether the write landed. The grid's resolves `false` for a column it cannot write, and skips an id whose row is not loaded.
15
+
16
+ ## Picking rows with the pointer
17
+
18
+ - `selectFromClick` — the modifier click on a row: takes the click, the row's id and the selection's `toggle` and `toggleRange`. Cmd or Ctrl toggles the row, Shift extends the range, and it returns `true` when it handled the click, so your handler stops before opening the row.
19
+ - `preventShiftTextSelect` — a `mousedown` handler that stops a shift-click from selecting text.
20
+ - `SelectCheckbox` — the row checkbox, drawn with the components map's `Checkbox`. It takes `checked`, `revealed`, `onChange(next, shift)` (the shift key read off the press that changed it, for a range), an optional `aria-label` and `className`. It shows only while the lane around it, marked with the `group/selzone` class, is hovered, and stays shown when `revealed` or checked.
21
+ - `useCheckDragSelect` — drag down the checkbox lane to set a run of rows, with the mouse only. It takes `enabled`, `rootRef` (the container the drag stays within), `rowIds` (visible order, without rows in collapsed groups), an optional `rowIdOf` (maps a row's `data-row-id` to a selection id), `isSelected` and `setRowSelected(id, next)`. It returns `tryArm`, called from the container's `onPointerDown` (`true` when it armed, so stop handling the event), and `consumeDrag`, called from a capture-phase click handler (`true` once after a real drag, so swallow that click). The run goes from the row the drag starts on to the row under the pointer, all set to the opposite of the first row's state; dragging back restores rows to what they were. A move under 4px stays a plain click, and near the scroller's edge the container scrolls.
22
+ - `ROW_CHECK_ATTR` — `"data-row-check"`, the attribute on a row's checkbox lane: a drag that starts anywhere in the lane arms `useCheckDragSelect`.
23
+
24
+ ## Row-click rules
25
+
26
+ - `ROW_INTERACTIVE_SELECTOR` — the selector for a real control inside a row (a link, a button, a form control, an element with a button, switch, checkbox, menu item or tab role, editable content, `[data-popover-trigger]`, `[data-no-nav]`). A click on one belongs to the control; a click anywhere else opens the row, or toggles it while selecting.
27
+ - `ROW_OPEN_STOP_SELECTOR` — `"[data-row-stop]"`, for a part of a row that must not open it (a trailing menu gutter) but still toggles it while selecting. Checked after the selection toggle, so it gates only the open.
28
+ - `ROW_NO_TEXT_SELECT` — the classes for a selectable row: no text selection and no long-press callout on iOS, so a long press selects the row without highlighting its text.
29
+
30
+ ## Reading ahead
31
+
32
+ - `useRestIntent` — starts a record's read when a mouse rests on its row: takes `onRest` and an optional `accepts(target, row)` that bounds which part of the row counts, and returns `onPointerOver` and `onPointerLeave` for the row. `onRest` runs once the pointer has stayed over the row for `REST_INTENT_MS`, at most once per visit. A finger, a held button, a pointer that leaves first, or content portaled out of the row starts nothing.
33
+ - `REST_INTENT_MS` — `100`, how long a mouse rests on a row before its record is read.