@viewkitjs/views 0.0.0-stage → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (451) hide show
  1. package/CHANGELOG.md +615 -0
  2. package/LICENSE.md +7 -0
  3. package/README.md +99 -2
  4. package/dist/atoms/CommandMenu.d.ts +2 -0
  5. package/dist/atoms/CommandMenu.js +20 -0
  6. package/dist/atoms/List.d.ts +2 -0
  7. package/dist/atoms/List.js +6 -0
  8. package/dist/atoms/LoadMore.d.ts +2 -0
  9. package/dist/atoms/LoadMore.js +25 -0
  10. package/dist/atoms/Loading.d.ts +2 -0
  11. package/dist/atoms/Loading.js +7 -0
  12. package/dist/atoms/PlatformMark.d.ts +2 -0
  13. package/dist/atoms/PlatformMark.js +4 -0
  14. package/dist/atoms/RelationLink.d.ts +2 -0
  15. package/dist/atoms/RelationLink.js +6 -0
  16. package/dist/atoms/Row.d.ts +3 -0
  17. package/dist/atoms/Row.js +30 -0
  18. package/dist/atoms/RowMenu.d.ts +2 -0
  19. package/dist/atoms/RowMenu.js +112 -0
  20. package/dist/atoms/StatusBadge.d.ts +2 -0
  21. package/dist/atoms/StatusBadge.js +7 -0
  22. package/dist/atoms/StatusMarker.d.ts +2 -0
  23. package/dist/atoms/StatusMarker.js +19 -0
  24. package/dist/atoms/Tag.d.ts +2 -0
  25. package/dist/atoms/Tag.js +13 -0
  26. package/dist/atoms/TickBox.d.ts +2 -0
  27. package/dist/atoms/TickBox.js +8 -0
  28. package/dist/atoms/defaults.d.ts +2 -0
  29. package/dist/atoms/defaults.js +27 -0
  30. package/dist/atoms/tones.d.ts +5 -0
  31. package/dist/atoms/tones.js +28 -0
  32. package/dist/atoms/types.d.ts +178 -0
  33. package/dist/atoms/types.js +3 -0
  34. package/dist/cells/cell-format.d.ts +138 -0
  35. package/dist/cells/cell-format.js +16 -0
  36. package/dist/cells/cell-title.d.ts +17 -0
  37. package/dist/cells/cell-title.js +8 -0
  38. package/dist/cells/cell-values.d.ts +28 -0
  39. package/dist/cells/cell-values.js +87 -0
  40. package/dist/cells/index.d.ts +4 -0
  41. package/dist/cells/index.js +4 -0
  42. package/dist/cells/legacy-field.d.ts +52 -0
  43. package/dist/cells/legacy-field.js +164 -0
  44. package/dist/cells/relation-wrap.d.ts +3 -0
  45. package/dist/cells/relation-wrap.js +24 -0
  46. package/dist/cells/use-cell-format.d.ts +5 -0
  47. package/dist/cells/use-cell-format.js +10 -0
  48. package/dist/contract.d.ts +461 -0
  49. package/dist/contract.js +682 -0
  50. package/dist/display/actor.d.ts +4 -0
  51. package/dist/display/actor.js +26 -0
  52. package/dist/display/boolean.d.ts +18 -0
  53. package/dist/display/boolean.js +43 -0
  54. package/dist/display/breakdown.d.ts +15 -0
  55. package/dist/display/breakdown.js +32 -0
  56. package/dist/display/currency.d.ts +9 -0
  57. package/dist/display/currency.js +29 -0
  58. package/dist/display/date.d.ts +12 -0
  59. package/dist/display/date.js +26 -0
  60. package/dist/display/display-cores.d.ts +31 -0
  61. package/dist/display/display-cores.js +57 -0
  62. package/dist/display/entity-chip.d.ts +26 -0
  63. package/dist/display/entity-chip.js +9 -0
  64. package/dist/display/format.d.ts +66 -0
  65. package/dist/display/format.js +190 -0
  66. package/dist/display/index.d.ts +8 -0
  67. package/dist/display/index.js +7 -0
  68. package/dist/display/link.d.ts +29 -0
  69. package/dist/display/link.js +50 -0
  70. package/dist/display/location.d.ts +8 -0
  71. package/dist/display/location.js +22 -0
  72. package/dist/display/multi-value.d.ts +18 -0
  73. package/dist/display/multi-value.js +28 -0
  74. package/dist/display/name.d.ts +6 -0
  75. package/dist/display/name.js +14 -0
  76. package/dist/display/number.d.ts +11 -0
  77. package/dist/display/number.js +27 -0
  78. package/dist/display/options.d.ts +153 -0
  79. package/dist/display/options.js +1 -0
  80. package/dist/display/percent.d.ts +4 -0
  81. package/dist/display/percent.js +40 -0
  82. package/dist/display/phone.d.ts +11 -0
  83. package/dist/display/phone.js +45 -0
  84. package/dist/display/range.d.ts +6 -0
  85. package/dist/display/range.js +29 -0
  86. package/dist/display/relation.d.ts +4 -0
  87. package/dist/display/relation.js +29 -0
  88. package/dist/display/rich-text.d.ts +10 -0
  89. package/dist/display/rich-text.js +34 -0
  90. package/dist/display/select.d.ts +6 -0
  91. package/dist/display/select.js +38 -0
  92. package/dist/display/text-class.d.ts +23 -0
  93. package/dist/display/text-class.js +5 -0
  94. package/dist/display/text.d.ts +19 -0
  95. package/dist/display/text.js +8 -0
  96. package/dist/display/use-display-options.d.ts +2 -0
  97. package/dist/display/use-display-options.js +14 -0
  98. package/dist/display/user.d.ts +11 -0
  99. package/dist/display/user.js +10 -0
  100. package/dist/display/value-list.d.ts +10 -0
  101. package/dist/display/value-list.js +12 -0
  102. package/dist/display/viewer.d.ts +4 -0
  103. package/dist/display/viewer.js +11 -0
  104. package/dist/display/web-href.d.ts +8 -0
  105. package/dist/display/web-href.js +12 -0
  106. package/dist/editors/ChipsEditor.d.ts +59 -0
  107. package/dist/editors/ChipsEditor.js +73 -0
  108. package/dist/editors/DateEditor.d.ts +25 -0
  109. package/dist/editors/DateEditor.js +122 -0
  110. package/dist/editors/LocationEditor.d.ts +22 -0
  111. package/dist/editors/LocationEditor.js +228 -0
  112. package/dist/editors/NameEditor.d.ts +22 -0
  113. package/dist/editors/NameEditor.js +92 -0
  114. package/dist/editors/NumberEditor.d.ts +67 -0
  115. package/dist/editors/NumberEditor.js +86 -0
  116. package/dist/editors/RangeEditor.d.ts +22 -0
  117. package/dist/editors/RangeEditor.js +70 -0
  118. package/dist/editors/RelationEditor.d.ts +65 -0
  119. package/dist/editors/RelationEditor.js +64 -0
  120. package/dist/editors/SelectEditor.d.ts +72 -0
  121. package/dist/editors/SelectEditor.js +59 -0
  122. package/dist/editors/ValueListEditor.d.ts +38 -0
  123. package/dist/editors/ValueListEditor.js +217 -0
  124. package/dist/editors/edit-cores.d.ts +83 -0
  125. package/dist/editors/edit-cores.js +38 -0
  126. package/dist/editors/edit-session.d.ts +74 -0
  127. package/dist/editors/edit-session.js +35 -0
  128. package/dist/editors/open-values.d.ts +28 -0
  129. package/dist/editors/open-values.js +26 -0
  130. package/dist/editors/relation-source.d.ts +66 -0
  131. package/dist/editors/relation-source.js +102 -0
  132. package/dist/fields/binding.d.ts +87 -0
  133. package/dist/fields/binding.js +117 -0
  134. package/dist/fields/currency.d.ts +82 -0
  135. package/dist/fields/currency.js +41 -0
  136. package/dist/fields/denomination.d.ts +42 -0
  137. package/dist/fields/denomination.js +11 -0
  138. package/dist/fields/edit-core-types.d.ts +40 -0
  139. package/dist/fields/edit-core-types.js +29 -0
  140. package/dist/fields/format-knobs.d.ts +34 -0
  141. package/dist/fields/format-knobs.js +36 -0
  142. package/dist/fields/menus.d.ts +28 -0
  143. package/dist/fields/menus.js +1 -0
  144. package/dist/fields/money.d.ts +60 -0
  145. package/dist/fields/money.js +78 -0
  146. package/dist/fields/number-edit.d.ts +11 -0
  147. package/dist/fields/number-edit.js +17 -0
  148. package/dist/fields/prepare-write.d.ts +55 -0
  149. package/dist/fields/prepare-write.js +67 -0
  150. package/dist/fields/relation-source-types.d.ts +54 -0
  151. package/dist/fields/relation-source-types.js +1 -0
  152. package/dist/figures.d.ts +52 -0
  153. package/dist/figures.js +63 -0
  154. package/dist/filters/date-filter.d.ts +2 -0
  155. package/dist/filters/date-filter.js +1 -0
  156. package/dist/filters/filter-model.d.ts +176 -0
  157. package/dist/filters/filter-model.js +41 -0
  158. package/dist/filters/number-filter.d.ts +2 -0
  159. package/dist/filters/number-filter.js +1 -0
  160. package/dist/filters/range-filter.d.ts +2 -0
  161. package/dist/filters/range-filter.js +1 -0
  162. package/dist/filters/registry.d.ts +103 -0
  163. package/dist/filters/registry.js +8 -0
  164. package/dist/filters/relation-filter.d.ts +16 -0
  165. package/dist/filters/relation-filter.js +53 -0
  166. package/dist/filters/text-filter.d.ts +2 -0
  167. package/dist/filters/text-filter.js +1 -0
  168. package/dist/grid/chrome/GridAddColumn.d.ts +11 -0
  169. package/dist/grid/chrome/GridAddColumn.js +29 -0
  170. package/dist/grid/chrome/GridAggregateMenu.d.ts +31 -0
  171. package/dist/grid/chrome/GridAggregateMenu.js +27 -0
  172. package/dist/grid/chrome/GridCellEditors.d.ts +64 -0
  173. package/dist/grid/chrome/GridCellEditors.js +55 -0
  174. package/dist/grid/chrome/GridCellOutline.d.ts +70 -0
  175. package/dist/grid/chrome/GridCellOutline.js +21 -0
  176. package/dist/grid/chrome/GridChipsEditor.d.ts +28 -0
  177. package/dist/grid/chrome/GridChipsEditor.js +40 -0
  178. package/dist/grid/chrome/GridColumnColorSection.d.ts +11 -0
  179. package/dist/grid/chrome/GridColumnColorSection.js +40 -0
  180. package/dist/grid/chrome/GridColumnDateSection.d.ts +23 -0
  181. package/dist/grid/chrome/GridColumnDateSection.js +23 -0
  182. package/dist/grid/chrome/GridColumnDurationSection.d.ts +19 -0
  183. package/dist/grid/chrome/GridColumnDurationSection.js +24 -0
  184. package/dist/grid/chrome/GridColumnMenu.d.ts +101 -0
  185. package/dist/grid/chrome/GridColumnMenu.js +99 -0
  186. package/dist/grid/chrome/GridColumnNumberSection.d.ts +25 -0
  187. package/dist/grid/chrome/GridColumnNumberSection.js +27 -0
  188. package/dist/grid/chrome/GridColumnPercentSection.d.ts +15 -0
  189. package/dist/grid/chrome/GridColumnPercentSection.js +16 -0
  190. package/dist/grid/chrome/GridColumnSortSection.d.ts +18 -0
  191. package/dist/grid/chrome/GridColumnSortSection.js +16 -0
  192. package/dist/grid/chrome/GridDateEditor.d.ts +22 -0
  193. package/dist/grid/chrome/GridDateEditor.js +31 -0
  194. package/dist/grid/chrome/GridFlyout.d.ts +44 -0
  195. package/dist/grid/chrome/GridFlyout.js +80 -0
  196. package/dist/grid/chrome/GridFooter.d.ts +23 -0
  197. package/dist/grid/chrome/GridFooter.js +81 -0
  198. package/dist/grid/chrome/GridGroupMenu.d.ts +37 -0
  199. package/dist/grid/chrome/GridGroupMenu.js +57 -0
  200. package/dist/grid/chrome/GridHeader.d.ts +61 -0
  201. package/dist/grid/chrome/GridHeader.js +37 -0
  202. package/dist/grid/chrome/GridLongTextEditor.d.ts +36 -0
  203. package/dist/grid/chrome/GridLongTextEditor.js +127 -0
  204. package/dist/grid/chrome/GridMenuRow.d.ts +15 -0
  205. package/dist/grid/chrome/GridMenuRow.js +15 -0
  206. package/dist/grid/chrome/GridNameEditor.d.ts +19 -0
  207. package/dist/grid/chrome/GridNameEditor.js +36 -0
  208. package/dist/grid/chrome/GridNumberEditor.d.ts +35 -0
  209. package/dist/grid/chrome/GridNumberEditor.js +25 -0
  210. package/dist/grid/chrome/GridRangeEditor.d.ts +20 -0
  211. package/dist/grid/chrome/GridRangeEditor.js +25 -0
  212. package/dist/grid/chrome/GridRelationEditor.d.ts +21 -0
  213. package/dist/grid/chrome/GridRelationEditor.js +30 -0
  214. package/dist/grid/chrome/GridResizeHandle.d.ts +19 -0
  215. package/dist/grid/chrome/GridResizeHandle.js +19 -0
  216. package/dist/grid/chrome/GridRow.d.ts +25 -0
  217. package/dist/grid/chrome/GridRow.js +136 -0
  218. package/dist/grid/chrome/GridRowActions.d.ts +32 -0
  219. package/dist/grid/chrome/GridRowActions.js +25 -0
  220. package/dist/grid/chrome/GridRowCells.d.ts +4 -0
  221. package/dist/grid/chrome/GridRowCells.js +133 -0
  222. package/dist/grid/chrome/GridRowGlyph.d.ts +12 -0
  223. package/dist/grid/chrome/GridRowGlyph.js +13 -0
  224. package/dist/grid/chrome/GridSelectEditor.d.ts +18 -0
  225. package/dist/grid/chrome/GridSelectEditor.js +49 -0
  226. package/dist/grid/chrome/GridStructure.d.ts +48 -0
  227. package/dist/grid/chrome/GridStructure.js +45 -0
  228. package/dist/grid/chrome/GridTable.d.ts +4 -0
  229. package/dist/grid/chrome/GridTable.js +125 -0
  230. package/dist/grid/chrome/GridTableSurface.d.ts +15 -0
  231. package/dist/grid/chrome/GridTableSurface.js +6 -0
  232. package/dist/grid/chrome/GridTextEditor.d.ts +11 -0
  233. package/dist/grid/chrome/GridTextEditor.js +40 -0
  234. package/dist/grid/chrome/GridValueListEditor.d.ts +18 -0
  235. package/dist/grid/chrome/GridValueListEditor.js +36 -0
  236. package/dist/grid/chrome/StuckMarker.d.ts +16 -0
  237. package/dist/grid/chrome/StuckMarker.js +34 -0
  238. package/dist/grid/chrome/cell-clipboard.d.ts +9 -0
  239. package/dist/grid/chrome/cell-clipboard.js +28 -0
  240. package/dist/grid/chrome/cells.d.ts +21 -0
  241. package/dist/grid/chrome/cells.js +20 -0
  242. package/dist/grid/chrome/checks.d.ts +35 -0
  243. package/dist/grid/chrome/checks.js +22 -0
  244. package/dist/grid/chrome/column-glyph.d.ts +14 -0
  245. package/dist/grid/chrome/column-glyph.js +44 -0
  246. package/dist/grid/chrome/editors.d.ts +9 -0
  247. package/dist/grid/chrome/editors.js +10 -0
  248. package/dist/grid/chrome/grid-cell-classes.d.ts +59 -0
  249. package/dist/grid/chrome/grid-cell-classes.js +30 -0
  250. package/dist/grid/chrome/grid-menu-search.d.ts +7 -0
  251. package/dist/grid/chrome/grid-menu-search.js +7 -0
  252. package/dist/grid/chrome/grid-row-props.d.ts +131 -0
  253. package/dist/grid/chrome/grid-row-props.js +1 -0
  254. package/dist/grid/chrome/grid-styles.d.ts +37 -0
  255. package/dist/grid/chrome/grid-styles.js +8 -0
  256. package/dist/grid/chrome/grid-table-props.d.ts +173 -0
  257. package/dist/grid/chrome/grid-table-props.js +1 -0
  258. package/dist/grid/chrome/useGridBatchApi.d.ts +34 -0
  259. package/dist/grid/chrome/useGridBatchApi.js +35 -0
  260. package/dist/grid/chrome/useGridColumnLayout.d.ts +30 -0
  261. package/dist/grid/chrome/useGridColumnLayout.js +206 -0
  262. package/dist/grid/chrome/useGridHeaderDrag.d.ts +20 -0
  263. package/dist/grid/chrome/useGridHeaderDrag.js +37 -0
  264. package/dist/grid/chrome/useGridKeyboard.d.ts +47 -0
  265. package/dist/grid/chrome/useGridKeyboard.js +274 -0
  266. package/dist/grid/chrome/useGridPendingReconciliation.d.ts +12 -0
  267. package/dist/grid/chrome/useGridPendingReconciliation.js +32 -0
  268. package/dist/grid/chrome/useGridRailReveal.d.ts +57 -0
  269. package/dist/grid/chrome/useGridRailReveal.js +67 -0
  270. package/dist/grid/chrome/useGridRangeActions.d.ts +49 -0
  271. package/dist/grid/chrome/useGridRangeActions.js +188 -0
  272. package/dist/grid/chrome/useGridRangeGestures.d.ts +32 -0
  273. package/dist/grid/chrome/useGridRangeGestures.js +190 -0
  274. package/dist/grid/chrome/useGridRowContextMenu.d.ts +35 -0
  275. package/dist/grid/chrome/useGridRowContextMenu.js +127 -0
  276. package/dist/grid/chrome/useGridScaleStyles.d.ts +1 -0
  277. package/dist/grid/chrome/useGridScaleStyles.js +29 -0
  278. package/dist/grid/chrome/useGridScrollSync.d.ts +38 -0
  279. package/dist/grid/chrome/useGridScrollSync.js +176 -0
  280. package/dist/grid/chrome/useGridTableInteractionModel.d.ts +55 -0
  281. package/dist/grid/chrome/useGridTableInteractionModel.js +197 -0
  282. package/dist/grid/chrome/useGridTableSelection.d.ts +29 -0
  283. package/dist/grid/chrome/useGridTableSelection.js +55 -0
  284. package/dist/grid/chrome/useHeaderDragReorder.d.ts +21 -0
  285. package/dist/grid/chrome/useHeaderDragReorder.js +216 -0
  286. package/dist/grid/core/clipboard-model.d.ts +81 -0
  287. package/dist/grid/core/clipboard-model.js +291 -0
  288. package/dist/grid/core/column-values.d.ts +27 -0
  289. package/dist/grid/core/column-values.js +76 -0
  290. package/dist/grid/core/commit-model.d.ts +34 -0
  291. package/dist/grid/core/commit-model.js +3 -0
  292. package/dist/grid/core/coordinates.d.ts +48 -0
  293. package/dist/grid/core/coordinates.js +27 -0
  294. package/dist/grid/core/edit-values.d.ts +9 -0
  295. package/dist/grid/core/edit-values.js +1 -0
  296. package/dist/grid/core/editing-controller.d.ts +59 -0
  297. package/dist/grid/core/editing-controller.js +240 -0
  298. package/dist/grid/core/editing-model.d.ts +78 -0
  299. package/dist/grid/core/editing-model.js +136 -0
  300. package/dist/grid/core/grid-scale.d.ts +14 -0
  301. package/dist/grid/core/grid-scale.js +8 -0
  302. package/dist/grid/core/nav.d.ts +94 -0
  303. package/dist/grid/core/nav.js +92 -0
  304. package/dist/grid/core/pending-reconciliation.d.ts +50 -0
  305. package/dist/grid/core/pending-reconciliation.js +49 -0
  306. package/dist/grid/core/range-model.d.ts +25 -0
  307. package/dist/grid/core/range-model.js +59 -0
  308. package/dist/grid/core/spreadsheet-operations.d.ts +85 -0
  309. package/dist/grid/core/spreadsheet-operations.js +253 -0
  310. package/dist/grid/core/useGridEditing.d.ts +43 -0
  311. package/dist/grid/core/useGridEditing.js +90 -0
  312. package/dist/grid/core/useGridRange.d.ts +20 -0
  313. package/dist/grid/core/useGridRange.js +24 -0
  314. package/dist/grid/core/value-equality.d.ts +32 -0
  315. package/dist/grid/core/value-equality.js +34 -0
  316. package/dist/grid/index.d.ts +18 -0
  317. package/dist/grid/index.js +5 -0
  318. package/dist/grid/useGridTablePrefs.d.ts +50 -0
  319. package/dist/grid/useGridTablePrefs.js +101 -0
  320. package/dist/grouping/sort-groups.d.ts +18 -0
  321. package/dist/grouping/sort-groups.js +33 -0
  322. package/dist/grouping/types.d.ts +10 -0
  323. package/dist/grouping/types.js +1 -0
  324. package/dist/index.d.ts +28 -0
  325. package/dist/index.js +28 -0
  326. package/dist/internal/chip.d.ts +4 -0
  327. package/dist/internal/chip.js +3 -0
  328. package/dist/internal/cx.d.ts +3 -0
  329. package/dist/internal/cx.js +3 -0
  330. package/dist/internal/viewport.d.ts +5 -0
  331. package/dist/internal/viewport.js +29 -0
  332. package/dist/model/aggregates.d.ts +59 -0
  333. package/dist/model/aggregates.js +186 -0
  334. package/dist/model/card-density.d.ts +8 -0
  335. package/dist/model/card-density.js +10 -0
  336. package/dist/model/card-layout.d.ts +85 -0
  337. package/dist/model/card-layout.js +90 -0
  338. package/dist/model/column-capabilities.d.ts +162 -0
  339. package/dist/model/column-capabilities.js +233 -0
  340. package/dist/model/column-filters.d.ts +106 -0
  341. package/dist/model/column-filters.js +321 -0
  342. package/dist/model/column-format.d.ts +103 -0
  343. package/dist/model/column-format.js +1 -0
  344. package/dist/model/column-from.d.ts +28 -0
  345. package/dist/model/column-from.js +160 -0
  346. package/dist/model/column-inspect.d.ts +18 -0
  347. package/dist/model/column-inspect.js +6 -0
  348. package/dist/model/column-knobs.d.ts +20 -0
  349. package/dist/model/column-knobs.js +16 -0
  350. package/dist/model/column-money.d.ts +13 -0
  351. package/dist/model/column-money.js +27 -0
  352. package/dist/model/column-order.d.ts +36 -0
  353. package/dist/model/column-order.js +68 -0
  354. package/dist/model/column-schema.d.ts +335 -0
  355. package/dist/model/column-schema.js +1 -0
  356. package/dist/model/column-sort.d.ts +17 -0
  357. package/dist/model/column-sort.js +11 -0
  358. package/dist/model/column-state.d.ts +77 -0
  359. package/dist/model/column-state.js +95 -0
  360. package/dist/model/column-types.d.ts +109 -0
  361. package/dist/model/column-types.js +50 -0
  362. package/dist/model/column-warnings.d.ts +44 -0
  363. package/dist/model/column-warnings.js +24 -0
  364. package/dist/model/density.d.ts +3 -0
  365. package/dist/model/density.js +13 -0
  366. package/dist/model/field-type-of.d.ts +21 -0
  367. package/dist/model/field-type-of.js +11 -0
  368. package/dist/model/filter-capabilities.d.ts +1 -0
  369. package/dist/model/filter-capabilities.js +1 -0
  370. package/dist/model/index.d.ts +38 -0
  371. package/dist/model/index.js +20 -0
  372. package/dist/model/part-rows.d.ts +28 -0
  373. package/dist/model/part-rows.js +40 -0
  374. package/dist/model/preferences.d.ts +155 -0
  375. package/dist/model/preferences.js +84 -0
  376. package/dist/model/prefs-buckets.d.ts +173 -0
  377. package/dist/model/prefs-buckets.js +71 -0
  378. package/dist/model/relation-filters.d.ts +45 -0
  379. package/dist/model/relation-filters.js +78 -0
  380. package/dist/model/render-count.d.ts +2 -0
  381. package/dist/model/render-count.js +24 -0
  382. package/dist/model/row-icon.d.ts +23 -0
  383. package/dist/model/row-icon.js +5 -0
  384. package/dist/model/view-rules.d.ts +73 -0
  385. package/dist/model/view-rules.js +216 -0
  386. package/dist/provider/ViewsProvider.d.ts +26 -0
  387. package/dist/provider/ViewsProvider.js +16 -0
  388. package/dist/provider/components.d.ts +230 -0
  389. package/dist/provider/components.js +3 -0
  390. package/dist/provider/context.d.ts +20 -0
  391. package/dist/provider/context.js +10 -0
  392. package/dist/provider/icons.d.ts +6 -0
  393. package/dist/provider/icons.js +1 -0
  394. package/dist/provider/menu-groups.d.ts +8 -0
  395. package/dist/provider/menu-groups.js +38 -0
  396. package/dist/provider/ports.d.ts +57 -0
  397. package/dist/provider/ports.js +9 -0
  398. package/dist/react.d.ts +9 -0
  399. package/dist/react.js +4 -0
  400. package/dist/selection/SelectCheckbox.d.ts +17 -0
  401. package/dist/selection/SelectCheckbox.js +11 -0
  402. package/dist/selection/index.d.ts +7 -0
  403. package/dist/selection/index.js +6 -0
  404. package/dist/selection/model.d.ts +55 -0
  405. package/dist/selection/model.js +86 -0
  406. package/dist/selection/row-click.d.ts +35 -0
  407. package/dist/selection/row-click.js +20 -0
  408. package/dist/selection/types.d.ts +17 -0
  409. package/dist/selection/types.js +1 -0
  410. package/dist/selection/useCheckDragSelect.d.ts +61 -0
  411. package/dist/selection/useCheckDragSelect.js +165 -0
  412. package/dist/selection/useListSelection.d.ts +39 -0
  413. package/dist/selection/useListSelection.js +48 -0
  414. package/dist/selection/useListSelectionShortcuts.d.ts +6 -0
  415. package/dist/selection/useListSelectionShortcuts.js +14 -0
  416. package/dist/selection/useRestIntent.d.ts +18 -0
  417. package/dist/selection/useRestIntent.js +35 -0
  418. package/docs/contract.md +525 -0
  419. package/docs/getting-started.md +250 -0
  420. package/docs/guides/atoms.md +245 -0
  421. package/docs/guides/cells.md +302 -0
  422. package/docs/guides/columns.md +412 -0
  423. package/docs/guides/display.md +203 -0
  424. package/docs/guides/editors.md +404 -0
  425. package/docs/guides/ports.md +246 -0
  426. package/docs/guides/selection.md +270 -0
  427. package/docs/guides/the-grid.md +677 -0
  428. package/docs/guides/the-provider.md +446 -0
  429. package/docs/index.md +50 -0
  430. package/docs/install.md +67 -0
  431. package/docs/reference/cells.md +28 -0
  432. package/docs/reference/display.md +42 -0
  433. package/docs/reference/editors-chips.md +6 -0
  434. package/docs/reference/editors-date.md +6 -0
  435. package/docs/reference/editors-location.md +10 -0
  436. package/docs/reference/editors-name.md +6 -0
  437. package/docs/reference/editors-number.md +11 -0
  438. package/docs/reference/editors-open-values.md +9 -0
  439. package/docs/reference/editors-range.md +6 -0
  440. package/docs/reference/editors-relation.md +9 -0
  441. package/docs/reference/editors-select.md +8 -0
  442. package/docs/reference/editors-session.md +9 -0
  443. package/docs/reference/editors-value-list.md +6 -0
  444. package/docs/reference/editors.md +5 -0
  445. package/docs/reference/grid.md +39 -0
  446. package/docs/reference/react.md +86 -0
  447. package/docs/reference/selection.md +33 -0
  448. package/docs/reference/views.md +601 -0
  449. package/docs/reshaping.md +19 -0
  450. package/package.json +118 -3
  451. package/skills/views/SKILL.md +102 -0
@@ -0,0 +1,404 @@
1
+ # Editors and the edit session
2
+
3
+ An editor is the panel a person changes a value in: the option list of a status, the calendar of a date, the three boxes of a name. The grid mounts them for you; this page is for when you mount one yourself, in a form field, a drawer row or a card. It covers the table that picks an editor for a type, what each editor commits, what an editor owns against what you own, the session that turns a close into one answer, an open field's values, and where a relation's candidates come from.
4
+
5
+ Every block on this page continues the one before, and the whole page runs as written.
6
+
7
+ ## One editor per storage type
8
+
9
+ `EDIT_CORES`, from `@viewkitjs/views/editors`, holds the editor for every storage type fields declares. It has a member for each type, so a type fields adds that nothing here answers fails to compile. Several types share one editor: `date` and `datetime` share the date editor, `select` and `status` the select editor, `relation` and `user` the relation editor, and `number`, `percent` and `currency` the number editor.
10
+
11
+ A member that is `null` is a decision: the type has no panel. `text`, `url`, `domain`, `email` and `phone` are a plain input your surface already owns; a `boolean` is edited by its checkbox; an `actor` is set by the system; `rich_text` is markdown in your own text box; `lookup`, `rollup` and `formula` are read-only or derived. `hasEditCore(type)` answers the same question; imported from the root door, `@viewkitjs/views`, it loads no editor, for a host deciding whether to wire one at all.
12
+
13
+ ```tsx
14
+ import assert from "node:assert/strict";
15
+ import { EDIT_CORES, hasEditCore } from "@viewkitjs/views/editors";
16
+ import { SelectEditor } from "@viewkitjs/views/editors/select";
17
+
18
+ assert.equal(EDIT_CORES.status, EDIT_CORES.select);
19
+ assert.equal(EDIT_CORES.select, SelectEditor);
20
+ assert.equal(EDIT_CORES.percent, EDIT_CORES.number);
21
+ assert.equal(EDIT_CORES.text, null);
22
+
23
+ assert.equal(hasEditCore("currency"), true);
24
+ assert.equal(hasEditCore("boolean"), false);
25
+ assert.equal(hasEditCore("formula"), false);
26
+ ```
27
+
28
+ Each editor also has a door of its own. Import from the editor's door when you need one editor, and from `@viewkitjs/views/editors` only when you need the table.
29
+
30
+ ## What each editor commits
31
+
32
+ What an editor hands back is a commit, which is not always the shape your row stores: a select commits `""` for None, a number commits the figure with its unit. [Four shapes of a value](../contract.md#four-shapes-of-a-value) in the contract names the stored, draft, commit and display shapes, and your binding's `write` is where a commit becomes your request's body.
33
+
34
+ | Door | Edits | Commits |
35
+ |---|---|---|
36
+ | `@viewkitjs/views/editors/select` | `select`, `status` | the picked option's `value`, `""` for None |
37
+ | `@viewkitjs/views/editors/relation` | `relation`, `user` | the picked candidate's `id`, `null` for None |
38
+ | `@viewkitjs/views/editors/number` | `number`, `percent`, `currency` | `{ value, unit }`, the value a number or `null` |
39
+ | `@viewkitjs/views/editors/range` | `range` | `{ low, high }`, each a number or `null` |
40
+ | `@viewkitjs/views/editors/name` | `name` | `{ full, given, family }`, or `null` |
41
+ | `@viewkitjs/views/editors/location` | `location` | the place's parts, or `null` |
42
+ | `@viewkitjs/views/editors/value-list` | a `multiple` email, phone, url or domain | a list of `{ value, label, main }`, the main one first, or `null` |
43
+ | `@viewkitjs/views/editors/date` | `date`, `datetime` | `YYYY-MM-DD`, or `YYYY-MM-DDTHH:MM` with a time |
44
+ | `@viewkitjs/views/editors/chips` | `multiselect` | the list of values, a `string[]` |
45
+
46
+ The value-list editor has no member in `EDIT_CORES`: a list of emails is still an `email` field, whose single value is a plain input. Each editor's reference page has its props and its close rule in full: [select](../reference/editors-select.md), [relation](../reference/editors-relation.md), [number](../reference/editors-number.md), [range](../reference/editors-range.md), [name](../reference/editors-name.md), [location](../reference/editors-location.md), [value list](../reference/editors-value-list.md), [date](../reference/editors-date.md) and [chips](../reference/editors-chips.md).
47
+
48
+ ## What an editor owns, and what you own
49
+
50
+ An editor owns its panel and what a close means. The select editor owns its rows and decides that a pick commits and every other close discards; the date editor owns its value bar and its calendar and decides that every close commits a changed draft. You own everything around the panel: the popover it sits in, the anchor that popover opens on, where focus goes, when a close happens, and the write.
51
+
52
+ The two speak through one handshake, the `CloseReason` and `CloseResolution` of `@viewkitjs/fields`:
53
+
54
+ 1. When the editor sees a key or a pick that means done, it calls your `onRequestClose(reason)`. Your popover's own closes (an outside press, Escape) reach the same place with their own reasons.
55
+ 2. You close, and ask the editor's handle `resolveClose(reason)`.
56
+ 3. It answers `commit` with the value, `cancel`, or `noop` when nothing changed. Asking twice gives the same answer, and it starts no timer.
57
+
58
+ What an editor never does on its own (write, fetch, toast, decide the popover) is listed in [What an edit core never does](../contract.md#what-an-edit-core-never-does). A field whose changes go through the record's own verbs has no editor at all; [A command field](../contract.md#a-command-field) covers what its cell offers instead.
59
+
60
+ ## The anchored edit session
61
+
62
+ Every host that opens a panel over a value repeats two things, and both are easy to get wrong without seeing it. A close can arrive more than once (your popover reports an Escape, then the closed state it caused), and a session that answers twice writes twice. And the popover has an exit animation: answering at once re-renders the value behind it and unmounts the panel mid-animation.
63
+
64
+ `useAnchoredEditSession`, from `@viewkitjs/views/editors/session`, is those two things in one hook. It opens already open, hands you `open` for your popover and `close(reason)` as the one door every close goes through, and counts only the first. It gives you two ways to hear the answer:
65
+
66
+ - `onAttempt(resolution)` and `onClose()`: the answer is asked synchronously, the moment the close happens, and you send the write right there. Return `{ accepted: false }` to refuse it: the panel stays open, and the next close asks again. On `{ accepted: true }` the popover closes, and `onClose` runs after the exit gap to finish the visual close. Prefer this one.
67
+ - `onDone(resolution)`: the whole answer, the write included, arrives after the exit gap.
68
+
69
+ The gap is `EDITOR_EXIT_MS` unless you pass `exitMs`. `mapPayload` reshapes a commit before it reaches you, and only a commit: a host that offers None maps the select's `""` to `null` with `mapPayload: (value) => (value === "" ? null : value)`.
70
+
71
+ ```tsx
72
+ import { EDITOR_EXIT_MS } from "@viewkitjs/views/editors/session";
73
+
74
+ assert.equal(EDITOR_EXIT_MS, 160);
75
+ ```
76
+
77
+ Here is a host: a deal's stage picked in a popover your components map draws, its commit sent through your own save. First the fields and the provider, as in getting started; the components map is plain elements, so the page runs anywhere.
78
+
79
+ ```tsx
80
+ import { defineConventions, defineFields, type CloseReason } from "@viewkitjs/fields";
81
+ import { ICON_NAMES } from "@viewkitjs/views";
82
+ import type { ViewsComponents, ViewsIcons } from "@viewkitjs/views/react";
83
+
84
+ const DEAL_FIELDS = defineFields({
85
+ entity: "deal",
86
+ identity: "title",
87
+ fields: {
88
+ title: { type: "text", label: "Title", required: true },
89
+ stage: {
90
+ type: "status",
91
+ label: "Stage",
92
+ options: [
93
+ { value: "new", label: "New", slot: "pending" },
94
+ { value: "won", label: "Won", slot: "success" },
95
+ { value: "lost", label: "Lost", slot: "error" },
96
+ ],
97
+ },
98
+ industry: {
99
+ type: "select",
100
+ label: "Industry",
101
+ vocabulary: "custom-values",
102
+ options: [{ value: "Software", label: "Software", color: "purple" }],
103
+ },
104
+ },
105
+ });
106
+
107
+ type Deal = { id: string; title: string; stage: string; industry: string | null; companyId: string | null };
108
+
109
+ const conventions = defineConventions({ locale: "en-GB", timeZone: "Europe/Bucharest" });
110
+
111
+ const components: ViewsComponents = {
112
+ Button: ({ children, onClick, disabled, type = "button", className, title }) => (
113
+ <button type={type} onClick={onClick} disabled={disabled} className={className} title={title}>
114
+ {children}
115
+ </button>
116
+ ),
117
+ Popover: ({ open, children, className }) => (open ? <div className={className}>{children}</div> : null),
118
+ Tooltip: ({ children }) => children,
119
+ Checkbox: ({ checked, onCheckedChange, disabled }) => (
120
+ <input
121
+ type="checkbox"
122
+ checked={checked}
123
+ disabled={disabled}
124
+ onChange={(event) => onCheckedChange(event.target.checked, { event: event.nativeEvent })}
125
+ />
126
+ ),
127
+ Menu: ({ open, items }) =>
128
+ open ? (
129
+ <div role="menu">
130
+ {items.map((item) => (
131
+ <button key={item.key} type="button" role="menuitem" onClick={item.onSelect}>
132
+ {item.label}
133
+ </button>
134
+ ))}
135
+ </div>
136
+ ) : null,
137
+ Command: {
138
+ Root: ({ children, className }) => <div className={className}>{children}</div>,
139
+ Input: ({ value, onValueChange, placeholder, ref, onKeyDown }) => (
140
+ <input
141
+ ref={ref}
142
+ value={value}
143
+ placeholder={placeholder}
144
+ onChange={(event) => onValueChange(event.target.value)}
145
+ onKeyDown={onKeyDown}
146
+ />
147
+ ),
148
+ List: ({ children }) => <div role="listbox">{children}</div>,
149
+ Empty: ({ children }) => <div>{children}</div>,
150
+ Group: ({ children }) => <div>{children}</div>,
151
+ Item: ({ value, onSelect, chosen, children }) => (
152
+ <div role="option" aria-selected={chosen === true} onClick={() => onSelect(value)}>
153
+ {children}
154
+ </div>
155
+ ),
156
+ },
157
+ Calendar: ({ value, onChange }) => (
158
+ <input type="date" value={value ?? ""} onChange={(event) => onChange(event.target.value)} />
159
+ ),
160
+ Collapse: ({ open, children }) => (open ? <>{children}</> : null),
161
+ Sheet: ({ open, children }) => (open ? <div role="dialog">{children}</div> : null),
162
+ AppIcon: ({ name, className }) => <i data-icon={name} className={className} />,
163
+ Markdown: ({ source, className }) => <div className={className}>{source}</div>,
164
+ };
165
+
166
+ const icons = Object.fromEntries(
167
+ ICON_NAMES.map((name) => [name, ({ className }: { className?: string }) => <i data-icon={name} className={className} />])
168
+ ) as ViewsIcons;
169
+ ```
170
+
171
+ `pickerOptionsFromField` dresses a select's or a status's options the way its cells draw them, so the panel looks like the grid: a status keeps each option's slot, a select takes its category colour. Archived options are left out.
172
+
173
+ ```tsx
174
+ import { pickerOptionsFromField, type SelectEditorHandle } from "@viewkitjs/views/editors/select";
175
+
176
+ const stageOptions = pickerOptionsFromField(DEAL_FIELDS.stage);
177
+
178
+ assert.deepEqual(stageOptions, [
179
+ { value: "new", label: "New", slot: "pending" },
180
+ { value: "won", label: "Won", slot: "success" },
181
+ { value: "lost", label: "Lost", slot: "error" },
182
+ ]);
183
+ ```
184
+
185
+ The host. Its popover is your components map's, read through `useViews()`; the anchor is whatever element the value sits in. Every close lands in the session's `close`: the editor's pick, your popover's Escape, and its closed state, which follows the Escape and is ignored, because the session has already answered.
186
+
187
+ ```tsx
188
+ import { useRef, type RefObject } from "react";
189
+ import { useViews } from "@viewkitjs/views/react";
190
+ import { useAnchoredEditSession } from "@viewkitjs/views/editors/session";
191
+
192
+ declare function saveDeal(id: string, body: Record<string, unknown>): Promise<void>;
193
+ declare function showSaveFailed(): void;
194
+
195
+ function DealStageEditor({
196
+ deal,
197
+ anchor,
198
+ onClosed,
199
+ }: {
200
+ deal: Deal;
201
+ anchor: RefObject<HTMLElement | null>;
202
+ onClosed: () => void;
203
+ }) {
204
+ const { Popover } = useViews().components;
205
+ const editorRef = useRef<SelectEditorHandle>(null);
206
+ const { open, close } = useAnchoredEditSession<string>({
207
+ editorRef,
208
+ onAttempt: (resolution) => {
209
+ // Asked the moment the close happens: the write leaves at once, the popover closes after.
210
+ if (resolution.kind === "commit") {
211
+ saveDeal(deal.id, { stage: resolution.payload }).catch(showSaveFailed);
212
+ }
213
+ return { accepted: true };
214
+ },
215
+ // After the exit gap: unmount the editor and draw the value again.
216
+ onClose: onClosed,
217
+ });
218
+
219
+ return (
220
+ <Popover
221
+ open={open}
222
+ onOpenChange={(next) => {
223
+ if (!next) close("outside");
224
+ }}
225
+ onEscape={() => close("escape")}
226
+ anchor={anchor}
227
+ align="start"
228
+ // The editor focuses its own input, without scrolling the page.
229
+ initialFocus={false}
230
+ chrome="menu"
231
+ >
232
+ <SelectEditor ref={editorRef} options={stageOptions} initial={deal.stage} onRequestClose={close} />
233
+ </Popover>
234
+ );
235
+ }
236
+ ```
237
+
238
+ Rendered inside the provider, the panel draws each option as your status badge and marks the stage the deal holds.
239
+
240
+ ```tsx
241
+ import { renderToStaticMarkup } from "react-dom/server";
242
+ import { NOOP_PORTS, ViewsProvider } from "@viewkitjs/views/react";
243
+
244
+ const acme: Deal = { id: "d1", title: "Acme renewal", stage: "new", industry: null, companyId: null };
245
+
246
+ const stageHtml = renderToStaticMarkup(
247
+ <ViewsProvider components={components} icons={icons} ports={NOOP_PORTS} conventions={conventions}>
248
+ <DealStageEditor deal={acme} anchor={{ current: null }} onClosed={() => {}} />
249
+ </ViewsProvider>
250
+ );
251
+
252
+ assert.ok(stageHtml.includes("Won") && stageHtml.includes("Lost"));
253
+ assert.ok(stageHtml.includes('data-status="success"')); // each option wears its slot
254
+ assert.ok(stageHtml.includes("data-chosen")); // the stage the deal holds is checked
255
+ ```
256
+
257
+ A pick of Won calls `close("pick")`; the editor answers `{ kind: "commit", payload: "won" }`, `saveDeal` sends `{ stage: "won" }`, and 160 milliseconds later `onClosed` runs. A pick of New, which the deal already holds, answers `noop`, and an outside press or Escape answers `cancel`: nothing is sent either way, and the popover still closes.
258
+
259
+ ## An open field's values
260
+
261
+ An open select or multiselect (`vocabulary: "custom-values"`) has no closed list of options: its values are whatever its records hold, which only your app's data can answer. `OpenValuesProvider`, from `@viewkitjs/views/editors/open-values`, carries them to every editor of the field below it, so a field offers the same values in the grid, a form and a card.
262
+
263
+ You provide the values above a surface: `values`, each field's values by its key, most used first, and `onWanted(fieldKey)`, so you can ask for a field's values when they are first needed. `useOpenValues(field)` is how a host reads them, and it calls `onWanted` once when the host of an open field mounts. Keep `onWanted` stable: a new function each render asks again each render.
264
+
265
+ ```tsx
266
+ import { useCallback, useMemo, useState, type ReactNode } from "react";
267
+ import { OpenValuesProvider, offeredValues, useOpenValues, type OpenValues } from "@viewkitjs/views/editors/open-values";
268
+
269
+ declare function fetchFieldValues(entity: string, fieldKey: string): Promise<string[]>;
270
+
271
+ function DealOpenValues({ children }: { children: ReactNode }) {
272
+ const [values, setValues] = useState<Record<string, string[]>>({});
273
+ const onWanted = useCallback((fieldKey: string) => {
274
+ void fetchFieldValues("deal", fieldKey).then((list) =>
275
+ setValues((current) => ({ ...current, [fieldKey]: list }))
276
+ );
277
+ }, []);
278
+ const openValues = useMemo<OpenValues>(() => ({ values, onWanted }), [values, onWanted]);
279
+ return <OpenValuesProvider value={openValues}>{children}</OpenValuesProvider>;
280
+ }
281
+ ```
282
+
283
+ A closed field, or a host with no provider above it, reads no values and asks for none: its editor offers its declared options.
284
+
285
+ `offeredValues(field, known, seen)` is what a host offers: the field's declared options, then the values the provider knows, then any seen on screen, each once. It is a plain function. `pickerOptionsFromField`'s `extraValues` turns the values no option names into rows labelled with the raw value, coloured by the same rule the cells use.
286
+
287
+ ```tsx
288
+ const offered = offeredValues(DEAL_FIELDS.industry, ["Retail", "Software"], ["Health"]);
289
+ assert.deepEqual(offered, ["Software", "Retail", "Health"]);
290
+
291
+ const industryOptions = pickerOptionsFromField(DEAL_FIELDS.industry, { extraValues: offered });
292
+ assert.deepEqual(
293
+ industryOptions.map((option) => option.label),
294
+ ["Software", "Retail", "Health"]
295
+ );
296
+ assert.equal(industryOptions[0].color, "purple"); // the option's own colour
297
+ ```
298
+
299
+ A host of an open select hands those rows to the select editor with `creatable`, which adds a search over the labels and a row that uses the typed text when no option's value is it:
300
+
301
+ ```tsx
302
+ function IndustryPanel({
303
+ deal,
304
+ seen,
305
+ editorRef,
306
+ onRequestClose,
307
+ }: {
308
+ deal: Deal;
309
+ seen: readonly string[];
310
+ editorRef: RefObject<SelectEditorHandle | null>;
311
+ onRequestClose: (reason: CloseReason) => void;
312
+ }) {
313
+ const known = useOpenValues(DEAL_FIELDS.industry);
314
+ const options = pickerOptionsFromField(DEAL_FIELDS.industry, {
315
+ extraValues: offeredValues(DEAL_FIELDS.industry, known, seen),
316
+ });
317
+ return (
318
+ <SelectEditor ref={editorRef} options={options} initial={deal.industry} creatable onRequestClose={onRequestClose} />
319
+ );
320
+ }
321
+ ```
322
+
323
+ ## A relation's candidates
324
+
325
+ The relation editor never asks for its candidates itself: you hand them in as a `RelationSource`, so who may see what stays in your own function. A source is one of two kinds:
326
+
327
+ - `static`: a list you already hold, whole. The panel filters it on the labels as a person types.
328
+ - `remote`: a search you run. The panel calls it with the empty query the moment it opens, then with each typed query after a pause, then for the next page as the list scrolls to its end, with `offset` the number of rows it already holds. The `AbortSignal` aborts when a newer query replaces it, and a stale answer is dropped.
329
+
330
+ A candidate is an `id` (stored and committed, never shown) and a `label`, with an optional `sublabel` (a muted second line that tells two same-named rows apart), `badge`, `icon`, `avatarUrl` and `kind`.
331
+
332
+ ```tsx
333
+ import {
334
+ RELATION_PAGE_SIZE,
335
+ RELATION_SEARCH_DEBOUNCE_MS,
336
+ RelationEditor,
337
+ type RelationEditorHandle,
338
+ type RelationSource,
339
+ } from "@viewkitjs/views/editors/relation";
340
+
341
+ const OWNERS: RelationSource = {
342
+ kind: "static",
343
+ items: [
344
+ { id: "u1", label: "Ana Pop", sublabel: "ana@example.com" },
345
+ { id: "u2", label: "Ana Pop", sublabel: "ana.pop@example.com" },
346
+ ],
347
+ };
348
+
349
+ declare function searchCompanies(
350
+ query: string,
351
+ offset: number,
352
+ limit: number,
353
+ signal: AbortSignal
354
+ ): Promise<{ id: string; name: string; domain: string | null }[]>;
355
+
356
+ const COMPANIES: RelationSource = {
357
+ kind: "remote",
358
+ pageSize: 25,
359
+ search: async (query, signal, offset) => {
360
+ const rows = await searchCompanies(query, offset, 25, signal);
361
+ return rows.map((row) => ({ id: row.id, label: row.name, sublabel: row.domain ?? undefined }));
362
+ },
363
+ };
364
+
365
+ assert.equal(OWNERS.kind, "static");
366
+ assert.equal(RELATION_SEARCH_DEBOUNCE_MS, 200); // a typed query waits this long
367
+ assert.equal(RELATION_PAGE_SIZE, 20); // a page, when the source names no pageSize
368
+ ```
369
+
370
+ A page shorter than `pageSize` is how the panel knows the list has ended, so `pageSize` must be what your search really asks its route for: a mismatch ends the list early, or asks once more for nothing.
371
+
372
+ The editor itself takes the source as `candidates`, the linked id as `initial`, and `clearable` for a None row. It commits the picked id, or `null` for None, and only on a pick; every other close discards. Its host is the stage host above with `RelationEditorHandle` in place of `SelectEditorHandle`:
373
+
374
+ ```tsx
375
+ function CompanyPanel({
376
+ deal,
377
+ editorRef,
378
+ onRequestClose,
379
+ }: {
380
+ deal: Deal;
381
+ editorRef: RefObject<RelationEditorHandle | null>;
382
+ onRequestClose: (reason: CloseReason) => void;
383
+ }) {
384
+ return (
385
+ <RelationEditor
386
+ ref={editorRef}
387
+ candidates={COMPANIES}
388
+ initial={deal.companyId}
389
+ clearable
390
+ noneLabel="No company"
391
+ onRequestClose={onRequestClose}
392
+ />
393
+ );
394
+ }
395
+ ```
396
+
397
+ On a binding, `relation` carries the same source, and the grid hands it to this editor when a relation cell opens.
398
+
399
+ ## Next
400
+
401
+ - [Cells](cells.md): drawing a column's value outside the grid
402
+ - [The contract](../contract.md): the four shapes of a value, what an edit core never does, a command field
403
+ - [The session's reference](../reference/editors-session.md) and [open values' reference](../reference/editors-open-values.md)
404
+ - [Getting started](../getting-started.md)
@@ -0,0 +1,246 @@
1
+ # Ports
2
+
3
+ A port is a runtime service your app hands the provider: the narrowest surface the rendering needs, named for what it does, so your own toast library, haptics, clipboard helper, storage and dialog each map onto it in a few lines. There are five: `toast`, `haptics`, `clipboard`, `viewPrefs` and, optionally, `confirm`. This page covers what calls each and when, the do-nothing ports to start with, and a port over each of your services.
4
+
5
+ ## Start with nothing
6
+
7
+ `NOOP_PORTS`, from `@viewkitjs/views/react`, answers every port with nothing: the toasts and haptics are empty, the clipboard writes nothing and reads nothing, and the store keeps nothing. It is what a server render, a test or a first mount needs, and it carries no `confirm`.
8
+
9
+ ```tsx
10
+ import assert from "node:assert/strict";
11
+ import {
12
+ NOOP_PORTS,
13
+ useViews,
14
+ type ViewsClipboardPort,
15
+ type ViewsConfirmPort,
16
+ type ViewsHapticsPort,
17
+ type ViewsPorts,
18
+ type ViewsPrefsPort,
19
+ type ViewsToastPort,
20
+ } from "@viewkitjs/views/react";
21
+
22
+ assert.equal(await NOOP_PORTS.clipboard.writeText("Acme renewal"), false); // nothing reached the clipboard
23
+ assert.equal(await NOOP_PORTS.clipboard.readText(), null);
24
+ assert.equal(NOOP_PORTS.viewPrefs.get("vk:example"), undefined);
25
+ assert.equal(NOOP_PORTS.confirm, undefined);
26
+ ```
27
+
28
+ You can replace one port at a time: `{ ...NOOP_PORTS, toast }` is a whole `ViewsPorts`.
29
+
30
+ Your app's own services are declared below, so the page compiles without them: a toast library, the haptics a native shell exposes (none on the web), and a dialog that asks a question and resolves to the answer.
31
+
32
+ ```tsx
33
+ declare const appToast: {
34
+ success(message: string): void;
35
+ error(message: string): void;
36
+ info(message: string): void;
37
+ warning(message: string, options?: { description?: string }): void;
38
+ };
39
+ declare const deviceHaptics: ViewsHapticsPort | null;
40
+ declare function openConfirmDialog(options: {
41
+ title: string;
42
+ description?: string;
43
+ confirmText: string;
44
+ tone: "danger" | "default";
45
+ }): Promise<boolean>;
46
+ ```
47
+
48
+ ## `toast`
49
+
50
+ `success(message)`, `error(message)`, `info(message)` and `warning(message, { description })`, each handed a sentence the package has already worded through your `messages`.
51
+
52
+ The grid speaks through two of them:
53
+
54
+ - **`error`** when it refuses something and says why: an edit or a clear on a cell that can't take one, a value its column can't store, the cells of a paste that could not take their value, a clear over a range with nothing clearable, a delete your app rejected (`views.menus.row-delete-failed`), and the row a person was editing leaving the list (`views.grid.row-left`).
55
+ - **`warning`** when a value changes that the person didn't change: a cell they had edited, saved by someone else in the meantime (`views.grid.changed-elsewhere`, or `views.grid.changed-elsewhere-cells` for several), with a second line in `description` saying the saved value is what shows.
56
+
57
+ `success` and `info` complete the shape, so one object over your toast library serves your own code too.
58
+
59
+ ```tsx
60
+ const toast: ViewsToastPort = {
61
+ success: (message) => appToast.success(message),
62
+ error: (message) => appToast.error(message),
63
+ info: (message) => appToast.info(message),
64
+ warning: (message, options) => appToast.warning(message, { description: options?.description }),
65
+ };
66
+ ```
67
+
68
+ ## `haptics`
69
+
70
+ `selection()`, `impact(style)` with `"light"`, `"medium"` or `"heavy"`, and `notification(type)` with `"success"`, `"warning"` or `"error"`.
71
+
72
+ A list's selection calls them: `selection()` each time a person turns a row on or off, one row, a range or a run of rows, and `impact("medium")` when they select every row. Clearing the selection is silent, because it is also the reset your batch actions call when they finish, where a buzz would land on top of their own toast. `notification` completes the shape.
73
+
74
+ An app without a device hands in no-ops; a native shell hands in its bridge.
75
+
76
+ ```tsx
77
+ const haptics: ViewsHapticsPort = {
78
+ selection: () => deviceHaptics?.selection(),
79
+ impact: (style) => deviceHaptics?.impact(style),
80
+ notification: (type) => deviceHaptics?.notification(type),
81
+ };
82
+ ```
83
+
84
+ ## `clipboard`
85
+
86
+ `writeText(text)` resolves to whether the text reached the clipboard; `readText()` resolves to the clipboard's text, or `null` where reading is refused.
87
+
88
+ The grid calls `writeText` when a person copies or cuts, a cell or a range, from the keyboard or the row's menu. It also keeps its own typed copy of what was copied, so a paste back into a grid keeps the value's type, and still works when the system refused the write. A paste reads the browser's own paste event, so the grid never asks `readText`; it is there for your own code.
89
+
90
+ Over the browser's clipboard, each refusal becomes the answer the port promises rather than a throw:
91
+
92
+ ```tsx
93
+ const clipboard: ViewsClipboardPort = {
94
+ writeText: async (text) => {
95
+ try {
96
+ await navigator.clipboard.writeText(text);
97
+ return true;
98
+ } catch {
99
+ return false;
100
+ }
101
+ },
102
+ readText: async () => {
103
+ try {
104
+ return await navigator.clipboard.readText();
105
+ } catch {
106
+ return null;
107
+ }
108
+ },
109
+ };
110
+ ```
111
+
112
+ ## `viewPrefs`
113
+
114
+ `get(key)`, `set(key, value)` and `subscribe(key, listener)`, which returns the function that unsubscribes: a small store for state kept on one device between visits, below anything a saved view holds, such as a column's width before the view saved one, or a collapsed group. The keys are the package's own, each starting `vk:`, so they sit beside your app's keys in one storage without meeting them.
115
+
116
+ It is not where a person's grid preferences live. Column widths and order in a view, formats, figures and the rest are yours to keep, handed to the grid through `useGridTablePrefs` ([the grid](the-grid.md)). In this release no view reads or writes `viewPrefs`, so `NOOP_PORTS`' store loses nothing; a store that works is ready for when one does.
117
+
118
+ Over `localStorage`, the store reads the storage when it is asked, never when the module loads: a server render has no `localStorage`, and neither has Node. `get` answers the same object until the stored text changes, so a reader built on `useSyncExternalStore` holds still, and a write in another tab reaches the listeners through the browser's `storage` event.
119
+
120
+ ```tsx
121
+ type PrefsStorage = Pick<Storage, "getItem" | "setItem">;
122
+
123
+ function storagePrefs(storage: () => PrefsStorage | undefined): ViewsPrefsPort {
124
+ const listeners = new Map<string, Set<() => void>>();
125
+ const parsed = new Map<string, { raw: string; value: unknown }>();
126
+
127
+ return {
128
+ get: <T,>(key: string): T | undefined => {
129
+ let raw: string | null | undefined;
130
+ try {
131
+ raw = storage()?.getItem(key);
132
+ } catch {
133
+ return undefined; // storage refused: nothing kept
134
+ }
135
+ if (raw == null) return undefined;
136
+ const cached = parsed.get(key);
137
+ if (cached?.raw === raw) return cached.value as T;
138
+ try {
139
+ const value: unknown = JSON.parse(raw);
140
+ parsed.set(key, { raw, value });
141
+ return value as T;
142
+ } catch {
143
+ return undefined;
144
+ }
145
+ },
146
+ set: <T,>(key: string, value: T) => {
147
+ try {
148
+ storage()?.setItem(key, JSON.stringify(value));
149
+ } catch {
150
+ // full or refused: the value isn't kept
151
+ }
152
+ listeners.get(key)?.forEach((listener) => listener());
153
+ },
154
+ subscribe: (key, listener) => {
155
+ const forKey = listeners.get(key) ?? new Set<() => void>();
156
+ forKey.add(listener);
157
+ listeners.set(key, forKey);
158
+ const onStorage = (event: StorageEvent) => {
159
+ if (event.key === key) listener();
160
+ };
161
+ if (typeof window !== "undefined") window.addEventListener("storage", onStorage);
162
+ return () => {
163
+ forKey.delete(listener);
164
+ if (typeof window !== "undefined") window.removeEventListener("storage", onStorage);
165
+ };
166
+ },
167
+ };
168
+ }
169
+
170
+ const viewPrefs = storagePrefs(() => (typeof window === "undefined" ? undefined : window.localStorage));
171
+ ```
172
+
173
+ Handed an in-memory storage, the same store shows what it does:
174
+
175
+ ```tsx
176
+ const memory = new Map<string, string>();
177
+ const memoryPrefs = storagePrefs(() => ({
178
+ getItem: (key) => memory.get(key) ?? null,
179
+ setItem: (key, value) => void memory.set(key, value),
180
+ }));
181
+
182
+ let heard = 0;
183
+ const unsubscribe = memoryPrefs.subscribe("vk:example", () => {
184
+ heard += 1;
185
+ });
186
+ memoryPrefs.set("vk:example", { title: 240 });
187
+
188
+ assert.deepEqual(memoryPrefs.get("vk:example"), { title: 240 });
189
+ assert.equal(memoryPrefs.get("vk:example"), memoryPrefs.get("vk:example")); // the same object until it changes
190
+ assert.equal(heard, 1);
191
+ unsubscribe();
192
+ ```
193
+
194
+ ## `confirm`
195
+
196
+ `confirm(request)` asks a question before an act and resolves to whether the person said yes. The request carries the question as `message`, the yes button's words as `confirmLabel`, what the act is done to as `subject` when the host names it, and `destructive` when the act removes something, so your dialog draws its destructive look.
197
+
198
+ A row's Delete asks it. The default row menu's Delete words the question with `views.menus.row-delete-confirm` ("Delete this row?") and the button with `views.menus.row-delete`, and hands the `deleteLabel` you give the grid, when you give one, as `subject`. A yes runs your delete; a rejection or a throw from your port counts as no, and nothing is deleted.
199
+
200
+ ```tsx
201
+ const confirm: ViewsConfirmPort = ({ message, confirmLabel, subject, destructive }) =>
202
+ openConfirmDialog({
203
+ title: message,
204
+ description: subject,
205
+ confirmText: confirmLabel,
206
+ tone: destructive ? "danger" : "default",
207
+ });
208
+ ```
209
+
210
+ `confirm` is the one optional port. Hand none and the provider asks with the browser's own confirm dialog, showing `message`. It reaches for `window` only when it asks, so a server render with no `confirm` is safe.
211
+
212
+ ## All five together
213
+
214
+ The ports go to the provider as one object that lives as long as the app:
215
+
216
+ ```tsx
217
+ export const viewsPorts: ViewsPorts = { toast, haptics, clipboard, viewPrefs, confirm };
218
+
219
+ assert.deepEqual(Object.keys(viewsPorts), ["toast", "haptics", "clipboard", "viewPrefs", "confirm"]);
220
+ ```
221
+
222
+ ## What a view reads
223
+
224
+ Inside a view, or an atom or component of your own beneath the provider, `useViews().ports` is a `ViewsResolvedPorts`: the ports you handed in, with `confirm` always a function, yours or the browser's. Your own code can ask the same question the package does, without checking whether a dialog was handed in. The package counts a rejection as no; in your own code that choice is yours to make:
225
+
226
+ ```tsx
227
+ export function ArchiveButton({ onArchive }: { onArchive: () => Promise<void> }) {
228
+ const { ports } = useViews();
229
+ const archive = async () => {
230
+ const yes = await ports.confirm({ message: "Archive this deal?", confirmLabel: "Archive" }).catch(() => false);
231
+ if (yes) await onArchive();
232
+ };
233
+ return (
234
+ <button type="button" onClick={archive}>
235
+ Archive
236
+ </button>
237
+ );
238
+ }
239
+ ```
240
+
241
+ ## Next
242
+
243
+ - [The provider](the-provider.md): mounting it, your adapter, your icons and your words
244
+ - [Atoms](atoms.md): the row menu whose Delete asks `confirm`, and swapping it for your own
245
+ - [Selection](selection.md): the selection whose taps reach `haptics`
246
+ - [The rendering contract](../contract.md#ports): the ports' methods, named in one place