@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,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
@@ -0,0 +1,270 @@
1
+ # Selection
2
+
3
+ People pick rows to act on several at once: a click with a modifier, a checkbox, a drag down the checkbox lane, select all. `@viewkitjs/views/selection` holds the selection itself and the rules a row follows; the bar a selection opens, and what its verbs do, are your app's. This page builds a plain list that people can select, then hands a selection to the grid, which wires the same pieces itself.
4
+
5
+ ## A list's selection
6
+
7
+ `useListSelection({ orderedIds, retention, resetKey })` keeps a list's selection. `orderedIds` are the row ids in the order the list draws them, after filtering, sorting and grouping: a range runs over that order, and select all selects exactly what is on screen. Keep the array stable between renders (a `useMemo` over your rows).
8
+
9
+ It returns a `UseListSelectionResult`:
10
+
11
+ - `selectedIds`, `count`, `isSelected(id)`;
12
+ - `toggle(id, next?)`, which flips one row (or sets it to `next`) and makes it the range anchor (`anchorId`);
13
+ - `toggleRange(id)`, which adds every row from the anchor to `id`;
14
+ - `toggleMany(ids)`, which selects them all, or clears them when they are all selected already (a group's checkbox);
15
+ - `selectAll()`, `clear()` (which also drops the anchor) and `setSelected(ids)`;
16
+ - `allSelected` and `someSelected`, for a header checkbox and its indeterminate state.
17
+
18
+ Turning a row on or off ticks the provider's `haptics.selection()`, select all gives `haptics.impact("medium")`, and `clear` is silent, as it is also what your batch action calls once it is done. The haptics port is yours, handed to the provider (the [contract](../contract.md) lists the ports).
19
+
20
+ `resetKey` empties the selection when it changes: pass the identity of the view and its filter, so a selection never carries over to rows a person can't see. `retention` says what happens to a selected id that leaves `orderedIds`. `"ordered"`, the default, drops it. `"external"` (a `SelectionRetention`) keeps it, for a selection across a whole query whose rows aren't all loaded. Either way the range anchor has to stay on screen to count.
21
+
22
+ `useEscapeToClear(active, clear)` clears on Escape anywhere in the window while `active` is true.
23
+
24
+ ```tsx
25
+ import { useMemo, useRef, type MouseEvent as ReactMouseEvent, type ReactNode } from "react";
26
+ import {
27
+ preventShiftTextSelect,
28
+ REST_INTENT_MS,
29
+ ROW_CHECK_ATTR,
30
+ ROW_INTERACTIVE_SELECTOR,
31
+ ROW_NO_TEXT_SELECT,
32
+ ROW_OPEN_STOP_SELECTOR,
33
+ SelectCheckbox,
34
+ selectFromClick,
35
+ useCheckDragSelect,
36
+ useEscapeToClear,
37
+ useListSelection,
38
+ useRestIntent,
39
+ type ListBatchApi,
40
+ type ListSelectionConfig,
41
+ type UseListSelectionResult,
42
+ } from "@viewkitjs/views/selection";
43
+
44
+ type Deal = { id: string; title: string; stage: string };
45
+
46
+ // Your app's own routes.
47
+ declare function openDeal(id: string): void;
48
+ declare function prefetchDeal(id: string): void;
49
+
50
+ function useDealSelection(deals: Deal[], filterKey: string) {
51
+ const orderedIds = useMemo(() => deals.map((deal) => deal.id), [deals]);
52
+ const sel = useListSelection({ orderedIds, resetKey: filterKey });
53
+ useEscapeToClear(sel.count > 0, sel.clear);
54
+ return { orderedIds, sel };
55
+ }
56
+ ```
57
+
58
+ ## A row: what a click does
59
+
60
+ A click on a row goes, in order:
61
+
62
+ 1. To a real control inside the row, when it lands on one: `ROW_INTERACTIVE_SELECTOR` matches links, buttons, form controls, elements with a button, switch, checkbox, menu item or tab role, editable content, `[data-popover-trigger]` and `[data-no-nav]`. The control handles it, whether or not the list is selecting.
63
+ 2. To the selection, when it carries a modifier: `selectFromClick(event, id, sel)` toggles the row on Cmd or Ctrl and extends the range on Shift, and returns `true` when it handled the click.
64
+ 3. To the selection again while rows are selected: a plain click toggles the row.
65
+ 4. Nowhere, when it lands in a region marked `data-row-stop` (`ROW_OPEN_STOP_SELECTOR`), such as a trailing menu gutter. It is checked after the toggle, so the region still selects; it only refuses to open the row.
66
+ 5. To opening the row.
67
+
68
+ `preventShiftTextSelect` on the row's `mousedown` stops a Shift-click from selecting text, and `ROW_NO_TEXT_SELECT` is the classes for a selectable row: no text selection, and no long-press callout on iOS.
69
+
70
+ `SelectCheckbox` draws the row's checkbox through your components map's `Checkbox`. It shows while the lane around it, marked with the `group/selzone` class, is hovered, and stays shown while `revealed` or checked. Its `onChange(next, shift)` reads the Shift key off the press that changed it, so a Shift-click on a checkbox extends the range.
71
+
72
+ `useRestIntent(onRest, accepts)` starts reading a record before it is opened: `onRest` runs once a mouse has rested on the row for `REST_INTENT_MS` (100 ms), at most once per visit. A finger, a held button (a drag passing over), a pointer that leaves first, or content portaled out of the row (a menu it opened) starts nothing. `accepts(target, row)` bounds which part of the row counts; it returns two handlers to spread on the row.
73
+
74
+ ```tsx
75
+ function DealRow({ deal, sel }: { deal: Deal; sel: UseListSelectionResult }) {
76
+ const selecting = sel.count > 0;
77
+ const rest = useRestIntent(
78
+ () => prefetchDeal(deal.id),
79
+ (target) => !target.closest(ROW_INTERACTIVE_SELECTOR)
80
+ );
81
+
82
+ const onClick = (event: ReactMouseEvent<HTMLDivElement>) => {
83
+ const target = event.target as Element;
84
+ if (target.closest(ROW_INTERACTIVE_SELECTOR)) return;
85
+ if (selectFromClick(event, deal.id, sel)) return;
86
+ if (selecting) {
87
+ sel.toggle(deal.id);
88
+ return;
89
+ }
90
+ if (target.closest(ROW_OPEN_STOP_SELECTOR)) return;
91
+ openDeal(deal.id);
92
+ };
93
+
94
+ return (
95
+ <div
96
+ data-row-id={deal.id}
97
+ className={ROW_NO_TEXT_SELECT}
98
+ onMouseDown={preventShiftTextSelect}
99
+ onClick={onClick}
100
+ {...rest}
101
+ >
102
+ <div className="group/selzone" data-row-check="">
103
+ <SelectCheckbox
104
+ checked={sel.isSelected(deal.id)}
105
+ revealed={selecting}
106
+ aria-label={`Select ${deal.title}`}
107
+ onChange={(next, shift) => (shift ? sel.toggleRange(deal.id) : sel.toggle(deal.id, next))}
108
+ />
109
+ </div>
110
+ <span>{deal.title}</span>
111
+ <span data-row-stop="">{deal.stage}</span>
112
+ </div>
113
+ );
114
+ }
115
+ ```
116
+
117
+ `selectFromClick` reads only the click's modifier keys and calls the selection's `toggle` or `toggleRange`, so it can be asked directly:
118
+
119
+ ```ts
120
+ import assert from "node:assert/strict";
121
+
122
+ const calls: string[] = [];
123
+ const recorder = {
124
+ toggle: (id: string) => {
125
+ calls.push(`toggle ${id}`);
126
+ },
127
+ toggleRange: (id: string) => {
128
+ calls.push(`range ${id}`);
129
+ },
130
+ };
131
+ const click = (keys: { metaKey?: boolean; ctrlKey?: boolean; shiftKey?: boolean }) =>
132
+ ({ metaKey: false, ctrlKey: false, shiftKey: false, ...keys }) as ReactMouseEvent;
133
+
134
+ assert.equal(selectFromClick(click({ metaKey: true }), "d1", recorder), true);
135
+ assert.equal(selectFromClick(click({ ctrlKey: true }), "d2", recorder), true);
136
+ assert.equal(selectFromClick(click({ shiftKey: true }), "d3", recorder), true);
137
+ // A plain click is not the selection's: the row opens.
138
+ assert.equal(selectFromClick(click({}), "d4", recorder), false);
139
+ assert.deepEqual(calls, ["toggle d1", "toggle d2", "range d3"]);
140
+
141
+ let prevented = 0;
142
+ const press = (shiftKey: boolean) =>
143
+ ({
144
+ shiftKey,
145
+ preventDefault: () => {
146
+ prevented += 1;
147
+ },
148
+ }) as ReactMouseEvent;
149
+ preventShiftTextSelect(press(true));
150
+ preventShiftTextSelect(press(false));
151
+ assert.equal(prevented, 1);
152
+
153
+ assert.equal(ROW_OPEN_STOP_SELECTOR, "[data-row-stop]");
154
+ assert.equal(REST_INTENT_MS, 100);
155
+ ```
156
+
157
+ ## Dragging down the checkbox lane
158
+
159
+ `useCheckDragSelect` lets a mouse drag down the checkbox lane to set a run of rows. The lane is the element carrying `ROW_CHECK_ATTR` (`data-row-check`), inside a row carrying `data-row-id`. The run goes from the row the drag started on to the row under the pointer, and every row in it takes the opposite of the first row's state, so a drag from an unselected row selects and one from a selected row clears. Dragging back restores the rows that fall out of the run to what they were. A move under 4px stays a plain click, and near the scroller's edge the container scrolls so the run can outgrow the screen. A finger's drag stays a scroll.
160
+
161
+ It takes `enabled`, `rootRef` (the container the drag stays within), `rowIds` (the visible order, without rows hidden in collapsed groups), `isSelected`, `setRowSelected(id, next)` and, when a row's `data-row-id` is not the selection's id, `rowIdOf` to map one to the other. It returns `tryArm`, for the container's `onPointerDown` (`true` when it armed, so the event is handled), and `consumeDrag`, for a capture-phase click handler (`true` once after a real drag, so the click that ends it does not toggle the first row again).
162
+
163
+ ```tsx
164
+ assert.equal(ROW_CHECK_ATTR, "data-row-check");
165
+
166
+ function DealList({ deals, filterKey }: { deals: Deal[]; filterKey: string }) {
167
+ const { orderedIds, sel } = useDealSelection(deals, filterKey);
168
+ const rootRef = useRef<HTMLDivElement>(null);
169
+ const drag = useCheckDragSelect({
170
+ enabled: true,
171
+ rootRef,
172
+ rowIds: orderedIds,
173
+ isSelected: sel.isSelected,
174
+ setRowSelected: sel.toggle,
175
+ });
176
+
177
+ return (
178
+ <div
179
+ ref={rootRef}
180
+ onPointerDown={(event) => {
181
+ drag.tryArm(event);
182
+ }}
183
+ onClickCapture={(event) => {
184
+ if (!drag.consumeDrag()) return;
185
+ event.preventDefault();
186
+ event.stopPropagation();
187
+ }}
188
+ >
189
+ {deals.map((deal) => (
190
+ <DealRow key={deal.id} deal={deal} sel={sel} />
191
+ ))}
192
+ <DealsBar sel={sel} />
193
+ </div>
194
+ );
195
+ }
196
+ ```
197
+
198
+ ## The bar is yours
199
+
200
+ What a selection lets a person do (move twelve deals to a stage, export them, delete them) is your app's, and so is the bar that offers it. It reads the selection and acts through your API, then calls `clear`.
201
+
202
+ A renderer with an editing model also hands the bar a `ListBatchApi`: `setColumnValue(rowIds, columnId, value)` writes one column across the rows through the renderer's own write path, and resolves to whether the write landed. The grid's goes through the same gate as a cell edit, so a column that can't be written, or one a workspace locked, resolves `false`, and a selected id whose row isn't loaded is skipped. The plain list above has no editing model, so its bar gets none.
203
+
204
+ ```tsx
205
+ function DealsBar({ sel, batch }: { sel: UseListSelectionResult; batch?: ListBatchApi }) {
206
+ if (sel.count === 0) return null;
207
+ const moveToProposal = async () => {
208
+ const landed = await batch?.setColumnValue([...sel.selectedIds], "stage", "proposal");
209
+ if (landed) sel.clear();
210
+ };
211
+ return (
212
+ <div role="toolbar">
213
+ <span>{sel.count} selected</span>
214
+ {batch ? (
215
+ <button type="button" onClick={() => void moveToProposal()}>
216
+ Move to proposal
217
+ </button>
218
+ ) : null}
219
+ <button type="button" onClick={sel.clear}>
220
+ Clear
221
+ </button>
222
+ </div>
223
+ );
224
+ }
225
+ ```
226
+
227
+ ## The grid takes a selection
228
+
229
+ `GridTable` wires the selection itself when you pass `selection`, a `ListSelectionConfig`: its checkbox rail (Shift on a checkbox extends the range), the drag down the lane (rows in collapsed groups left out), a plain click toggling a row while rows are selected, Escape, and a group's checkbox. One rule differs from a plain list: in the grid a modifier click on a cell is a cell-range gesture, as in a spreadsheet (Shift extends the active range, Cmd or Ctrl adds the cell), so rows are picked from the rail. You give it:
230
+
231
+ - `resetKey`: the selection clears when it changes;
232
+ - `renderBar(sel, batch?)`: your bar, drawn from the selection and, when the grid can write (you passed `onCellCommit`), its `ListBatchApi`. The grid calls it on every render, so the bar draws nothing while `sel.count` is zero;
233
+ - optionally `orderedIds`, when the order a range runs over is not the grid's rows as drawn, and `retention`.
234
+
235
+ ```tsx
236
+ import type { ListColumn } from "@viewkitjs/views";
237
+ import { GridTable, type GridCellCommitFn } from "@viewkitjs/views/grid";
238
+
239
+ // Built with columnFrom, and your commit handler: the getting started page has both.
240
+ declare const DEAL_COLUMNS: ListColumn<Deal>[];
241
+ declare const commitDealCell: GridCellCommitFn<Deal>;
242
+
243
+ function DealsGrid({ deals, filterKey }: { deals: Deal[]; filterKey: string }): ReactNode {
244
+ const selection: ListSelectionConfig = {
245
+ resetKey: filterKey,
246
+ renderBar: (sel, batch) => <DealsBar sel={sel} batch={batch} />,
247
+ };
248
+ return (
249
+ <GridTable
250
+ groups={[{ key: "all", label: null, items: deals }]}
251
+ grouped={false}
252
+ getRowId={(deal) => deal.id}
253
+ columns={DEAL_COLUMNS}
254
+ onOpenRow={(deal) => openDeal(deal.id)}
255
+ onPrefetchRow={(deal) => prefetchDeal(deal.id)}
256
+ onCellCommit={commitDealCell}
257
+ selection={selection}
258
+ />
259
+ );
260
+ }
261
+ ```
262
+
263
+ A person's standing choice to keep the checkboxes shown is `alwaysCheckboxes` on the grid. Leave `selection` out and the grid has no checkboxes and no bar.
264
+
265
+ ## Next
266
+
267
+ - [Columns](columns.md): which columns a batch write can reach
268
+ - [The grid](the-grid.md): grouping, sorting, preferences, figures and writes
269
+ - [`@viewkitjs/views/selection` reference](../reference/selection.md): every name on the door
270
+ - [`@viewkitjs/views/grid` reference](../reference/grid.md): every prop `GridTable` takes