foldkit-mixins-ui 0.25.0 → 0.27.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 (1255) hide show
  1. package/README.md +2978 -888
  2. package/dist/accordion/state.d.ts +36 -0
  3. package/dist/accordion/state.d.ts.map +1 -0
  4. package/dist/accordion/state.js +35 -0
  5. package/dist/accordion/state.js.map +1 -0
  6. package/dist/accordion/toggled.d.ts +11 -0
  7. package/dist/accordion/toggled.d.ts.map +1 -0
  8. package/dist/accordion/toggled.js +17 -0
  9. package/dist/accordion/toggled.js.map +1 -0
  10. package/dist/accordion.d.ts +26 -11
  11. package/dist/accordion.d.ts.map +1 -1
  12. package/dist/accordion.js +26 -17
  13. package/dist/accordion.js.map +1 -1
  14. package/dist/adornments.d.ts +42 -0
  15. package/dist/adornments.d.ts.map +1 -0
  16. package/dist/adornments.js +35 -0
  17. package/dist/adornments.js.map +1 -0
  18. package/dist/alert.d.ts +35 -5
  19. package/dist/alert.d.ts.map +1 -1
  20. package/dist/alert.js +22 -5
  21. package/dist/alert.js.map +1 -1
  22. package/dist/anchor.d.ts +16 -3
  23. package/dist/anchor.d.ts.map +1 -1
  24. package/dist/anchor.js +123 -12
  25. package/dist/anchor.js.map +1 -1
  26. package/dist/angleSlider.d.ts +28 -3
  27. package/dist/angleSlider.d.ts.map +1 -1
  28. package/dist/angleSlider.js +19 -5
  29. package/dist/angleSlider.js.map +1 -1
  30. package/dist/appShell.d.ts +34 -5
  31. package/dist/appShell.d.ts.map +1 -1
  32. package/dist/appShell.js +23 -6
  33. package/dist/appShell.js.map +1 -1
  34. package/dist/aspectRatio.d.ts +9 -0
  35. package/dist/aspectRatio.d.ts.map +1 -1
  36. package/dist/aspectRatio.js +4 -1
  37. package/dist/aspectRatio.js.map +1 -1
  38. package/dist/avatar/picture.d.ts +15 -0
  39. package/dist/avatar/picture.d.ts.map +1 -0
  40. package/dist/avatar/picture.js +19 -0
  41. package/dist/avatar/picture.js.map +1 -0
  42. package/dist/avatar.d.ts +81 -28
  43. package/dist/avatar.d.ts.map +1 -1
  44. package/dist/avatar.js +54 -27
  45. package/dist/avatar.js.map +1 -1
  46. package/dist/badge.d.ts +40 -10
  47. package/dist/badge.d.ts.map +1 -1
  48. package/dist/badge.js +39 -6
  49. package/dist/badge.js.map +1 -1
  50. package/dist/breadcrumb/menu.d.ts +29 -0
  51. package/dist/breadcrumb/menu.d.ts.map +1 -0
  52. package/dist/breadcrumb/menu.js +30 -0
  53. package/dist/breadcrumb/menu.js.map +1 -0
  54. package/dist/breadcrumb.d.ts +57 -29
  55. package/dist/breadcrumb.d.ts.map +1 -1
  56. package/dist/breadcrumb.js +63 -45
  57. package/dist/breadcrumb.js.map +1 -1
  58. package/dist/bundles/accordion.d.ts +19 -0
  59. package/dist/bundles/accordion.d.ts.map +1 -0
  60. package/dist/bundles/accordion.js +20 -0
  61. package/dist/bundles/accordion.js.map +1 -0
  62. package/dist/bundles/angleSlider.d.ts +37 -0
  63. package/dist/bundles/angleSlider.d.ts.map +1 -0
  64. package/dist/bundles/angleSlider.js +46 -0
  65. package/dist/bundles/angleSlider.js.map +1 -0
  66. package/dist/bundles/calendar.d.ts +1245 -0
  67. package/dist/bundles/calendar.d.ts.map +1 -0
  68. package/dist/bundles/calendar.js +26 -0
  69. package/dist/bundles/calendar.js.map +1 -0
  70. package/dist/bundles/carousel.d.ts +50 -0
  71. package/dist/bundles/carousel.d.ts.map +1 -0
  72. package/dist/bundles/carousel.js +31 -0
  73. package/dist/bundles/carousel.js.map +1 -0
  74. package/dist/bundles/cascadeSelect.d.ts +80 -0
  75. package/dist/bundles/cascadeSelect.d.ts.map +1 -0
  76. package/dist/bundles/cascadeSelect.js +66 -0
  77. package/dist/bundles/cascadeSelect.js.map +1 -0
  78. package/dist/bundles/colorPicker.d.ts +78 -0
  79. package/dist/bundles/colorPicker.d.ts.map +1 -0
  80. package/dist/bundles/colorPicker.js +42 -0
  81. package/dist/bundles/colorPicker.js.map +1 -0
  82. package/dist/bundles/combobox.d.ts +135 -0
  83. package/dist/bundles/combobox.d.ts.map +1 -0
  84. package/dist/bundles/combobox.js +74 -0
  85. package/dist/bundles/combobox.js.map +1 -0
  86. package/dist/bundles/datePicker.d.ts +911 -0
  87. package/dist/bundles/datePicker.d.ts.map +1 -0
  88. package/dist/bundles/datePicker.js +25 -0
  89. package/dist/bundles/datePicker.js.map +1 -0
  90. package/dist/bundles/dialog.d.ts +71 -0
  91. package/dist/bundles/dialog.d.ts.map +1 -0
  92. package/dist/bundles/dialog.js +45 -0
  93. package/dist/bundles/dialog.js.map +1 -0
  94. package/dist/bundles/disclosure.d.ts +17 -0
  95. package/dist/bundles/disclosure.d.ts.map +1 -0
  96. package/dist/bundles/disclosure.js +20 -0
  97. package/dist/bundles/disclosure.js.map +1 -0
  98. package/dist/bundles/drawer.d.ts +76 -0
  99. package/dist/bundles/drawer.d.ts.map +1 -0
  100. package/dist/bundles/drawer.js +39 -0
  101. package/dist/bundles/drawer.js.map +1 -0
  102. package/dist/bundles/fileDrop.d.ts +29 -0
  103. package/dist/bundles/fileDrop.d.ts.map +1 -0
  104. package/dist/bundles/fileDrop.js +36 -0
  105. package/dist/bundles/fileDrop.js.map +1 -0
  106. package/dist/bundles/fileUpload.d.ts +183 -0
  107. package/dist/bundles/fileUpload.d.ts.map +1 -0
  108. package/dist/bundles/fileUpload.js +45 -0
  109. package/dist/bundles/fileUpload.js.map +1 -0
  110. package/dist/bundles/floatingPanel.d.ts +197 -0
  111. package/dist/bundles/floatingPanel.d.ts.map +1 -0
  112. package/dist/bundles/floatingPanel.js +52 -0
  113. package/dist/bundles/floatingPanel.js.map +1 -0
  114. package/dist/bundles/hoverIntent.d.ts +98 -0
  115. package/dist/bundles/hoverIntent.d.ts.map +1 -0
  116. package/dist/bundles/hoverIntent.js +28 -0
  117. package/dist/bundles/hoverIntent.js.map +1 -0
  118. package/dist/bundles/imageCropper.d.ts +136 -0
  119. package/dist/bundles/imageCropper.d.ts.map +1 -0
  120. package/dist/bundles/imageCropper.js +48 -0
  121. package/dist/bundles/imageCropper.js.map +1 -0
  122. package/dist/bundles/index.d.ts +42 -0
  123. package/dist/bundles/index.js +42 -0
  124. package/dist/bundles/inputCopy.d.ts +24 -0
  125. package/dist/bundles/inputCopy.d.ts.map +1 -0
  126. package/dist/bundles/inputCopy.js +21 -0
  127. package/dist/bundles/inputCopy.js.map +1 -0
  128. package/dist/bundles/listbox.d.ts +120 -0
  129. package/dist/bundles/listbox.d.ts.map +1 -0
  130. package/dist/bundles/listbox.js +52 -0
  131. package/dist/bundles/listbox.js.map +1 -0
  132. package/dist/bundles/marquee.d.ts +27 -0
  133. package/dist/bundles/marquee.d.ts.map +1 -0
  134. package/dist/bundles/marquee.js +25 -0
  135. package/dist/bundles/marquee.js.map +1 -0
  136. package/dist/bundles/menu.d.ts +310 -0
  137. package/dist/bundles/menu.d.ts.map +1 -0
  138. package/dist/bundles/menu.js +34 -0
  139. package/dist/bundles/menu.js.map +1 -0
  140. package/dist/bundles/menubar.d.ts +145 -0
  141. package/dist/bundles/menubar.d.ts.map +1 -0
  142. package/dist/bundles/menubar.js +28 -0
  143. package/dist/bundles/menubar.js.map +1 -0
  144. package/dist/bundles/messageScroller.d.ts +29 -0
  145. package/dist/bundles/messageScroller.d.ts.map +1 -0
  146. package/dist/bundles/messageScroller.js +24 -0
  147. package/dist/bundles/messageScroller.js.map +1 -0
  148. package/dist/bundles/nav.d.ts +39 -0
  149. package/dist/bundles/nav.d.ts.map +1 -0
  150. package/dist/bundles/nav.js +22 -0
  151. package/dist/bundles/nav.js.map +1 -0
  152. package/dist/bundles/passwordInput.d.ts +19 -0
  153. package/dist/bundles/passwordInput.d.ts.map +1 -0
  154. package/dist/bundles/passwordInput.js +20 -0
  155. package/dist/bundles/passwordInput.js.map +1 -0
  156. package/dist/bundles/picker.d.ts +211 -0
  157. package/dist/bundles/picker.d.ts.map +1 -0
  158. package/dist/bundles/picker.js +48 -0
  159. package/dist/bundles/picker.js.map +1 -0
  160. package/dist/bundles/popover.d.ts +212 -0
  161. package/dist/bundles/popover.d.ts.map +1 -0
  162. package/dist/bundles/popover.js +34 -0
  163. package/dist/bundles/popover.js.map +1 -0
  164. package/dist/bundles/radioGroup.d.ts +27 -0
  165. package/dist/bundles/radioGroup.d.ts.map +1 -0
  166. package/dist/bundles/radioGroup.js +19 -0
  167. package/dist/bundles/radioGroup.js.map +1 -0
  168. package/dist/bundles/resizable.d.ts +44 -0
  169. package/dist/bundles/resizable.d.ts.map +1 -0
  170. package/dist/bundles/resizable.js +34 -0
  171. package/dist/bundles/resizable.js.map +1 -0
  172. package/dist/bundles/sheet.d.ts +104 -0
  173. package/dist/bundles/sheet.d.ts.map +1 -0
  174. package/dist/bundles/sheet.js +47 -0
  175. package/dist/bundles/sheet.js.map +1 -0
  176. package/dist/bundles/signaturePad.d.ts +111 -0
  177. package/dist/bundles/signaturePad.d.ts.map +1 -0
  178. package/dist/bundles/signaturePad.js +48 -0
  179. package/dist/bundles/signaturePad.js.map +1 -0
  180. package/dist/bundles/tabs.d.ts +31 -0
  181. package/dist/bundles/tabs.d.ts.map +1 -0
  182. package/dist/bundles/tabs.js +20 -0
  183. package/dist/bundles/tabs.js.map +1 -0
  184. package/dist/bundles/tagsInput.d.ts +50 -0
  185. package/dist/bundles/tagsInput.d.ts.map +1 -0
  186. package/dist/bundles/tagsInput.js +29 -0
  187. package/dist/bundles/tagsInput.js.map +1 -0
  188. package/dist/bundles/thinkingSteps.d.ts +21 -0
  189. package/dist/bundles/thinkingSteps.d.ts.map +1 -0
  190. package/dist/bundles/thinkingSteps.js +19 -0
  191. package/dist/bundles/thinkingSteps.js.map +1 -0
  192. package/dist/bundles/timer.d.ts +34 -0
  193. package/dist/bundles/timer.d.ts.map +1 -0
  194. package/dist/bundles/timer.js +42 -0
  195. package/dist/bundles/timer.js.map +1 -0
  196. package/dist/bundles/toast.d.ts +132 -0
  197. package/dist/bundles/toast.d.ts.map +1 -0
  198. package/dist/bundles/toast.js +42 -0
  199. package/dist/bundles/toast.js.map +1 -0
  200. package/dist/bundles/toolbar.d.ts +15 -0
  201. package/dist/bundles/toolbar.d.ts.map +1 -0
  202. package/dist/bundles/toolbar.js +21 -0
  203. package/dist/bundles/toolbar.js.map +1 -0
  204. package/dist/bundles/tooltip.d.ts +43 -0
  205. package/dist/bundles/tooltip.d.ts.map +1 -0
  206. package/dist/bundles/tooltip.js +25 -0
  207. package/dist/bundles/tooltip.js.map +1 -0
  208. package/dist/bundles/tour.d.ts +87 -0
  209. package/dist/bundles/tour.d.ts.map +1 -0
  210. package/dist/bundles/tour.js +26 -0
  211. package/dist/bundles/tour.js.map +1 -0
  212. package/dist/bundles/treeView.d.ts +56 -0
  213. package/dist/bundles/treeView.d.ts.map +1 -0
  214. package/dist/bundles/treeView.js +46 -0
  215. package/dist/bundles/treeView.js.map +1 -0
  216. package/dist/bundles/virtualList.d.ts +688 -0
  217. package/dist/bundles/virtualList.d.ts.map +1 -0
  218. package/dist/bundles/virtualList.js +57 -0
  219. package/dist/bundles/virtualList.js.map +1 -0
  220. package/dist/bundles/windowList.d.ts +80 -0
  221. package/dist/bundles/windowList.d.ts.map +1 -0
  222. package/dist/bundles/windowList.js +37 -0
  223. package/dist/bundles/windowList.js.map +1 -0
  224. package/dist/button.d.ts +80 -12
  225. package/dist/button.d.ts.map +1 -1
  226. package/dist/button.js +65 -20
  227. package/dist/button.js.map +1 -1
  228. package/dist/buttonGroup.d.ts +2 -2
  229. package/dist/buttonGroup.js +5 -2
  230. package/dist/buttonGroup.js.map +1 -1
  231. package/dist/calendar/layout.d.ts +78 -0
  232. package/dist/calendar/layout.d.ts.map +1 -0
  233. package/dist/calendar/layout.js +78 -0
  234. package/dist/calendar/layout.js.map +1 -0
  235. package/dist/calendar/selection.d.ts +85 -0
  236. package/dist/calendar/selection.d.ts.map +1 -0
  237. package/dist/calendar/selection.js +136 -0
  238. package/dist/calendar/selection.js.map +1 -0
  239. package/dist/calendar/shown.d.ts +36 -0
  240. package/dist/calendar/shown.d.ts.map +1 -0
  241. package/dist/calendar/shown.js +52 -0
  242. package/dist/calendar/shown.js.map +1 -0
  243. package/dist/calendar/state.d.ts +579 -0
  244. package/dist/calendar/state.d.ts.map +1 -0
  245. package/dist/calendar/state.js +174 -0
  246. package/dist/calendar/state.js.map +1 -0
  247. package/dist/calendar/view.d.ts +71 -0
  248. package/dist/calendar/view.d.ts.map +1 -0
  249. package/dist/calendar/view.js +81 -0
  250. package/dist/calendar/view.js.map +1 -0
  251. package/dist/calendar.d.ts +44 -114
  252. package/dist/calendar.d.ts.map +1 -1
  253. package/dist/calendar.js +66 -182
  254. package/dist/calendar.js.map +1 -1
  255. package/dist/card/fluid.d.ts +11 -0
  256. package/dist/card/fluid.d.ts.map +1 -0
  257. package/dist/card/fluid.js +31 -0
  258. package/dist/card/fluid.js.map +1 -0
  259. package/dist/card.d.ts +70 -33
  260. package/dist/card.d.ts.map +1 -1
  261. package/dist/card.js +65 -57
  262. package/dist/card.js.map +1 -1
  263. package/dist/carousel.d.ts +54 -17
  264. package/dist/carousel.d.ts.map +1 -1
  265. package/dist/carousel.js +64 -27
  266. package/dist/carousel.js.map +1 -1
  267. package/dist/cascadeSelect.d.ts +89 -8
  268. package/dist/cascadeSelect.d.ts.map +1 -1
  269. package/dist/cascadeSelect.js +171 -61
  270. package/dist/cascadeSelect.js.map +1 -1
  271. package/dist/chart/area.d.ts +10 -0
  272. package/dist/chart/area.d.ts.map +1 -0
  273. package/dist/chart/area.js +11 -0
  274. package/dist/chart/area.js.map +1 -0
  275. package/dist/chart/bars.d.ts +13 -0
  276. package/dist/chart/bars.d.ts.map +1 -0
  277. package/dist/chart/bars.js +35 -0
  278. package/dist/chart/bars.js.map +1 -0
  279. package/dist/chart/cartesian.d.ts +52 -0
  280. package/dist/chart/cartesian.d.ts.map +1 -0
  281. package/dist/chart/cartesian.js +132 -0
  282. package/dist/chart/cartesian.js.map +1 -0
  283. package/dist/chart/donut.d.ts +20 -0
  284. package/dist/chart/donut.d.ts.map +1 -0
  285. package/dist/chart/donut.js +44 -0
  286. package/dist/chart/donut.js.map +1 -0
  287. package/dist/chart/kind.d.ts +62 -0
  288. package/dist/chart/kind.d.ts.map +1 -0
  289. package/dist/chart/kind.js +8 -0
  290. package/dist/chart/kind.js.map +1 -0
  291. package/dist/chart/line.d.ts +5 -0
  292. package/dist/chart/line.d.ts.map +1 -0
  293. package/dist/chart/line.js +11 -0
  294. package/dist/chart/line.js.map +1 -0
  295. package/dist/chart/paths.d.ts +15 -0
  296. package/dist/chart/paths.d.ts.map +1 -0
  297. package/dist/chart/paths.js +36 -0
  298. package/dist/chart/paths.js.map +1 -0
  299. package/dist/chart/scale.d.ts +10 -4
  300. package/dist/chart/scale.d.ts.map +1 -1
  301. package/dist/chart/scale.js +31 -12
  302. package/dist/chart/scale.js.map +1 -1
  303. package/dist/chart/slots.d.ts +72 -0
  304. package/dist/chart/slots.d.ts.map +1 -0
  305. package/dist/chart/slots.js +90 -0
  306. package/dist/chart/slots.js.map +1 -0
  307. package/dist/chart.d.ts +24 -110
  308. package/dist/chart.d.ts.map +1 -1
  309. package/dist/chart.js +46 -268
  310. package/dist/chart.js.map +1 -1
  311. package/dist/chatMessage.d.ts +55 -6
  312. package/dist/chatMessage.d.ts.map +1 -1
  313. package/dist/chatMessage.js +69 -6
  314. package/dist/chatMessage.js.map +1 -1
  315. package/dist/checkbox/slots.d.ts +19 -0
  316. package/dist/checkbox/slots.d.ts.map +1 -0
  317. package/dist/checkbox/slots.js +38 -0
  318. package/dist/checkbox/slots.js.map +1 -0
  319. package/dist/checkbox/view.d.ts +52 -0
  320. package/dist/checkbox/view.d.ts.map +1 -0
  321. package/dist/checkbox/view.js +50 -0
  322. package/dist/checkbox/view.js.map +1 -0
  323. package/dist/checkbox.d.ts +4 -13
  324. package/dist/checkbox.d.ts.map +1 -1
  325. package/dist/checkbox.js +4 -29
  326. package/dist/checkbox.js.map +1 -1
  327. package/dist/checkboxGroup.d.ts +26 -6
  328. package/dist/checkboxGroup.d.ts.map +1 -1
  329. package/dist/checkboxGroup.js +34 -6
  330. package/dist/checkboxGroup.js.map +1 -1
  331. package/dist/choice/many.d.ts +4 -0
  332. package/dist/choice/many.d.ts.map +1 -0
  333. package/dist/choice/many.js +23 -0
  334. package/dist/choice/many.js.map +1 -0
  335. package/dist/choice/one.d.ts +5 -0
  336. package/dist/choice/one.d.ts.map +1 -0
  337. package/dist/choice/one.js +25 -0
  338. package/dist/choice/one.js.map +1 -0
  339. package/dist/choice/text.d.ts +8 -0
  340. package/dist/choice/text.d.ts.map +1 -0
  341. package/dist/choice/text.js +23 -0
  342. package/dist/choice/text.js.map +1 -0
  343. package/dist/choice.d.ts +36 -0
  344. package/dist/choice.d.ts.map +1 -0
  345. package/dist/choice.js +28 -0
  346. package/dist/choice.js.map +1 -0
  347. package/dist/codeBlock/follow.d.ts +8 -0
  348. package/dist/codeBlock/follow.d.ts.map +1 -0
  349. package/dist/codeBlock/follow.js +47 -0
  350. package/dist/codeBlock/follow.js.map +1 -0
  351. package/dist/codeBlock/slots.d.ts +30 -0
  352. package/dist/codeBlock/slots.d.ts.map +1 -0
  353. package/dist/codeBlock/slots.js +47 -0
  354. package/dist/codeBlock/slots.js.map +1 -0
  355. package/dist/codeBlock.d.ts +52 -25
  356. package/dist/codeBlock.d.ts.map +1 -1
  357. package/dist/codeBlock.js +80 -26
  358. package/dist/codeBlock.js.map +1 -1
  359. package/dist/colorPicker/popover.d.ts +28 -0
  360. package/dist/colorPicker/popover.d.ts.map +1 -0
  361. package/dist/colorPicker/popover.js +56 -0
  362. package/dist/colorPicker/popover.js.map +1 -0
  363. package/dist/colorPicker.d.ts +66 -31
  364. package/dist/colorPicker.d.ts.map +1 -1
  365. package/dist/colorPicker.js +35 -63
  366. package/dist/colorPicker.js.map +1 -1
  367. package/dist/combobox/filters.d.ts +9 -0
  368. package/dist/combobox/filters.d.ts.map +1 -0
  369. package/dist/combobox/filters.js +12 -0
  370. package/dist/combobox/filters.js.map +1 -0
  371. package/dist/combobox/fluid.d.ts +9 -0
  372. package/dist/combobox/fluid.d.ts.map +1 -0
  373. package/dist/combobox/fluid.js +29 -0
  374. package/dist/combobox/fluid.js.map +1 -0
  375. package/dist/combobox/overlayBars.d.ts +8 -0
  376. package/dist/combobox/overlayBars.d.ts.map +1 -0
  377. package/dist/combobox/overlayBars.js +17 -0
  378. package/dist/combobox/overlayBars.js.map +1 -0
  379. package/dist/combobox/slots.d.ts +57 -0
  380. package/dist/combobox/slots.d.ts.map +1 -0
  381. package/dist/combobox/slots.js +114 -0
  382. package/dist/combobox/slots.js.map +1 -0
  383. package/dist/combobox/view.d.ts +88 -0
  384. package/dist/combobox/view.d.ts.map +1 -0
  385. package/dist/combobox/view.js +87 -0
  386. package/dist/combobox/view.js.map +1 -0
  387. package/dist/combobox/words.d.ts +10 -0
  388. package/dist/combobox/words.d.ts.map +1 -0
  389. package/dist/combobox/words.js +9 -0
  390. package/dist/combobox/words.js.map +1 -0
  391. package/dist/combobox.d.ts +17 -71
  392. package/dist/combobox.d.ts.map +1 -1
  393. package/dist/combobox.js +17 -144
  394. package/dist/combobox.js.map +1 -1
  395. package/dist/comboboxShared.d.ts +14 -9
  396. package/dist/comboboxShared.d.ts.map +1 -1
  397. package/dist/comboboxShared.js +53 -33
  398. package/dist/comboboxShared.js.map +1 -1
  399. package/dist/command/overlayBars.d.ts +8 -0
  400. package/dist/command/overlayBars.d.ts.map +1 -0
  401. package/dist/command/overlayBars.js +17 -0
  402. package/dist/command/overlayBars.js.map +1 -0
  403. package/dist/command/slots.d.ts +56 -0
  404. package/dist/command/slots.d.ts.map +1 -0
  405. package/dist/command/slots.js +80 -0
  406. package/dist/command/slots.js.map +1 -0
  407. package/dist/command/words.d.ts +10 -0
  408. package/dist/command/words.d.ts.map +1 -0
  409. package/dist/command/words.js +9 -0
  410. package/dist/command/words.js.map +1 -0
  411. package/dist/command.d.ts +51 -66
  412. package/dist/command.d.ts.map +1 -1
  413. package/dist/command.js +94 -109
  414. package/dist/command.js.map +1 -1
  415. package/dist/configure.d.ts +28 -0
  416. package/dist/configure.d.ts.map +1 -0
  417. package/dist/configure.js +38 -0
  418. package/dist/configure.js.map +1 -0
  419. package/dist/datePicker/state.d.ts +504 -0
  420. package/dist/datePicker/state.d.ts.map +1 -0
  421. package/dist/datePicker/state.js +157 -0
  422. package/dist/datePicker/state.js.map +1 -0
  423. package/dist/datePicker/view.d.ts +66 -0
  424. package/dist/datePicker/view.d.ts.map +1 -0
  425. package/dist/datePicker/view.js +79 -0
  426. package/dist/datePicker/view.js.map +1 -0
  427. package/dist/datePicker.d.ts +16 -9
  428. package/dist/datePicker.d.ts.map +1 -1
  429. package/dist/datePicker.js +15 -9
  430. package/dist/datePicker.js.map +1 -1
  431. package/dist/datePickerView.d.ts +28 -28
  432. package/dist/datePickerView.js +4 -4
  433. package/dist/datePickerView.js.map +1 -1
  434. package/dist/dialog/focusReturn.d.ts +11 -0
  435. package/dist/dialog/focusReturn.d.ts.map +1 -0
  436. package/dist/dialog/focusReturn.js +20 -0
  437. package/dist/dialog/focusReturn.js.map +1 -0
  438. package/dist/dialog/keyboard.d.ts +8 -0
  439. package/dist/dialog/keyboard.d.ts.map +1 -0
  440. package/dist/dialog/keyboard.js +17 -0
  441. package/dist/dialog/keyboard.js.map +1 -0
  442. package/dist/dialog/overlayBars.d.ts +7 -0
  443. package/dist/dialog/overlayBars.d.ts.map +1 -0
  444. package/dist/dialog/overlayBars.js +16 -0
  445. package/dist/dialog/overlayBars.js.map +1 -0
  446. package/dist/dialog/slots.d.ts +42 -0
  447. package/dist/dialog/slots.d.ts.map +1 -0
  448. package/dist/dialog/slots.js +64 -0
  449. package/dist/dialog/slots.js.map +1 -0
  450. package/dist/dialog.d.ts +51 -56
  451. package/dist/dialog.d.ts.map +1 -1
  452. package/dist/dialog.js +82 -75
  453. package/dist/dialog.js.map +1 -1
  454. package/dist/disclosure/slots.d.ts +12 -0
  455. package/dist/disclosure/slots.d.ts.map +1 -0
  456. package/dist/disclosure/slots.js +24 -0
  457. package/dist/disclosure/slots.js.map +1 -0
  458. package/dist/disclosure/state.d.ts +31 -0
  459. package/dist/disclosure/state.d.ts.map +1 -0
  460. package/dist/disclosure/state.js +26 -0
  461. package/dist/disclosure/state.js.map +1 -0
  462. package/dist/disclosure/view.d.ts +37 -0
  463. package/dist/disclosure/view.d.ts.map +1 -0
  464. package/dist/disclosure/view.js +33 -0
  465. package/dist/disclosure/view.js.map +1 -0
  466. package/dist/disclosure.d.ts +4 -5
  467. package/dist/disclosure.d.ts.map +1 -1
  468. package/dist/disclosure.js +4 -15
  469. package/dist/disclosure.js.map +1 -1
  470. package/dist/drawer/keepFocus.d.ts +2 -0
  471. package/dist/drawer/keepFocus.d.ts.map +1 -0
  472. package/dist/drawer/keepFocus.js +35 -0
  473. package/dist/drawer/keepFocus.js.map +1 -0
  474. package/dist/drawer/slots.d.ts +9 -0
  475. package/dist/drawer/slots.d.ts.map +1 -0
  476. package/dist/drawer/slots.js +16 -0
  477. package/dist/drawer/slots.js.map +1 -0
  478. package/dist/drawer.d.ts +11 -15
  479. package/dist/drawer.d.ts.map +1 -1
  480. package/dist/drawer.js +8 -17
  481. package/dist/drawer.js.map +1 -1
  482. package/dist/empty.d.ts +9 -0
  483. package/dist/empty.d.ts.map +1 -1
  484. package/dist/empty.js +4 -1
  485. package/dist/empty.js.map +1 -1
  486. package/dist/field.d.ts +7 -0
  487. package/dist/field.d.ts.map +1 -1
  488. package/dist/field.js +7 -1
  489. package/dist/field.js.map +1 -1
  490. package/dist/fieldShell.d.ts +75 -0
  491. package/dist/fieldShell.d.ts.map +1 -0
  492. package/dist/fieldShell.js +61 -0
  493. package/dist/fieldShell.js.map +1 -0
  494. package/dist/fieldset.d.ts +20 -2
  495. package/dist/fieldset.d.ts.map +1 -1
  496. package/dist/fieldset.js +15 -1
  497. package/dist/fieldset.js.map +1 -1
  498. package/dist/figure.d.ts +9 -0
  499. package/dist/figure.d.ts.map +1 -1
  500. package/dist/figure.js +4 -1
  501. package/dist/figure.js.map +1 -1
  502. package/dist/fileDrop.d.ts +8 -0
  503. package/dist/fileDrop.d.ts.map +1 -1
  504. package/dist/fileDrop.js +6 -1
  505. package/dist/fileDrop.js.map +1 -1
  506. package/dist/fileInput.d.ts +129 -0
  507. package/dist/fileInput.d.ts.map +1 -0
  508. package/dist/fileInput.js +151 -0
  509. package/dist/fileInput.js.map +1 -0
  510. package/dist/fileUpload/progress.d.ts +22 -0
  511. package/dist/fileUpload/progress.d.ts.map +1 -0
  512. package/dist/fileUpload/progress.js +34 -0
  513. package/dist/fileUpload/progress.js.map +1 -0
  514. package/dist/fileUpload/sort.d.ts +10 -0
  515. package/dist/fileUpload/sort.d.ts.map +1 -0
  516. package/dist/fileUpload/sort.js +22 -0
  517. package/dist/fileUpload/sort.js.map +1 -0
  518. package/dist/fileUpload.d.ts +641 -0
  519. package/dist/fileUpload.d.ts.map +1 -0
  520. package/dist/fileUpload.js +1004 -0
  521. package/dist/fileUpload.js.map +1 -0
  522. package/dist/floatingPanel/focusReturn.d.ts +10 -0
  523. package/dist/floatingPanel/focusReturn.d.ts.map +1 -0
  524. package/dist/floatingPanel/focusReturn.js +19 -0
  525. package/dist/floatingPanel/focusReturn.js.map +1 -0
  526. package/dist/floatingPanel/slots.d.ts +26 -0
  527. package/dist/floatingPanel/slots.d.ts.map +1 -0
  528. package/dist/floatingPanel/slots.js +61 -0
  529. package/dist/floatingPanel/slots.js.map +1 -0
  530. package/dist/floatingPanel.d.ts +141 -74
  531. package/dist/floatingPanel.d.ts.map +1 -1
  532. package/dist/floatingPanel.js +306 -169
  533. package/dist/floatingPanel.js.map +1 -1
  534. package/dist/frame.d.ts +53 -0
  535. package/dist/frame.d.ts.map +1 -0
  536. package/dist/frame.js +50 -0
  537. package/dist/frame.js.map +1 -0
  538. package/dist/hoverIntent.d.ts +5 -1
  539. package/dist/hoverIntent.d.ts.map +1 -1
  540. package/dist/hoverIntent.js +13 -3
  541. package/dist/hoverIntent.js.map +1 -1
  542. package/dist/icon.d.ts +31 -14
  543. package/dist/icon.d.ts.map +1 -1
  544. package/dist/icon.js +11 -8
  545. package/dist/icon.js.map +1 -1
  546. package/dist/image/audit.d.ts +10 -0
  547. package/dist/image/audit.d.ts.map +1 -0
  548. package/dist/image/audit.js +50 -0
  549. package/dist/image/audit.js.map +1 -0
  550. package/dist/image/slots.d.ts +18 -0
  551. package/dist/image/slots.d.ts.map +1 -0
  552. package/dist/image/slots.js +21 -0
  553. package/dist/image/slots.js.map +1 -0
  554. package/dist/image/watchLoad.d.ts +9 -0
  555. package/dist/image/watchLoad.d.ts.map +1 -0
  556. package/dist/image/watchLoad.js +45 -0
  557. package/dist/image/watchLoad.js.map +1 -0
  558. package/dist/image.d.ts +23 -36
  559. package/dist/image.d.ts.map +1 -1
  560. package/dist/image.js +22 -100
  561. package/dist/image.js.map +1 -1
  562. package/dist/imageAttributes.d.ts +1 -1
  563. package/dist/imageCropper/zoomSlider.d.ts +10 -0
  564. package/dist/imageCropper/zoomSlider.d.ts.map +1 -0
  565. package/dist/imageCropper/zoomSlider.js +14 -0
  566. package/dist/imageCropper/zoomSlider.js.map +1 -0
  567. package/dist/imageCropper.d.ts +46 -10
  568. package/dist/imageCropper.d.ts.map +1 -1
  569. package/dist/imageCropper.js +26 -17
  570. package/dist/imageCropper.js.map +1 -1
  571. package/dist/index.d.ts +63 -41
  572. package/dist/index.js +25 -8
  573. package/dist/input.d.ts +64 -14
  574. package/dist/input.d.ts.map +1 -1
  575. package/dist/input.js +61 -24
  576. package/dist/input.js.map +1 -1
  577. package/dist/inputCopy.d.ts +29 -6
  578. package/dist/inputCopy.d.ts.map +1 -1
  579. package/dist/inputCopy.js +65 -18
  580. package/dist/inputCopy.js.map +1 -1
  581. package/dist/item.d.ts +37 -5
  582. package/dist/item.d.ts.map +1 -1
  583. package/dist/item.js +38 -7
  584. package/dist/item.js.map +1 -1
  585. package/dist/kbd.d.ts +3 -2
  586. package/dist/kbd.d.ts.map +1 -1
  587. package/dist/kbd.js.map +1 -1
  588. package/dist/label.d.ts +45 -8
  589. package/dist/label.d.ts.map +1 -1
  590. package/dist/label.js +26 -6
  591. package/dist/label.js.map +1 -1
  592. package/dist/listbox/fluid.d.ts +9 -0
  593. package/dist/listbox/fluid.d.ts.map +1 -0
  594. package/dist/listbox/fluid.js +29 -0
  595. package/dist/listbox/fluid.js.map +1 -0
  596. package/dist/listbox/overlayBars.d.ts +8 -0
  597. package/dist/listbox/overlayBars.d.ts.map +1 -0
  598. package/dist/listbox/overlayBars.js +17 -0
  599. package/dist/listbox/overlayBars.js.map +1 -0
  600. package/dist/listbox/slots.d.ts +52 -0
  601. package/dist/listbox/slots.d.ts.map +1 -0
  602. package/dist/listbox/slots.js +94 -0
  603. package/dist/listbox/slots.js.map +1 -0
  604. package/dist/listbox/view.d.ts +88 -0
  605. package/dist/listbox/view.d.ts.map +1 -0
  606. package/dist/listbox/view.js +93 -0
  607. package/dist/listbox/view.js.map +1 -0
  608. package/dist/listbox/words.d.ts +8 -0
  609. package/dist/listbox/words.d.ts.map +1 -0
  610. package/dist/listbox/words.js +6 -0
  611. package/dist/listbox/words.js.map +1 -0
  612. package/dist/listbox.d.ts +22 -74
  613. package/dist/listbox.d.ts.map +1 -1
  614. package/dist/listbox.js +20 -130
  615. package/dist/listbox.js.map +1 -1
  616. package/dist/listboxShared.d.ts.map +1 -1
  617. package/dist/listboxShared.js +99 -74
  618. package/dist/listboxShared.js.map +1 -1
  619. package/dist/listboxView.d.ts.map +1 -1
  620. package/dist/listboxView.js.map +1 -1
  621. package/dist/marquee.d.ts +10 -5
  622. package/dist/marquee.d.ts.map +1 -1
  623. package/dist/marquee.js +28 -6
  624. package/dist/marquee.js.map +1 -1
  625. package/dist/menu/fluid.d.ts +8 -0
  626. package/dist/menu/fluid.d.ts.map +1 -0
  627. package/dist/menu/fluid.js +23 -0
  628. package/dist/menu/fluid.js.map +1 -0
  629. package/dist/menu/overlayBars.d.ts +8 -0
  630. package/dist/menu/overlayBars.d.ts.map +1 -0
  631. package/dist/menu/overlayBars.js +17 -0
  632. package/dist/menu/overlayBars.js.map +1 -0
  633. package/dist/menu/slots.d.ts +53 -0
  634. package/dist/menu/slots.d.ts.map +1 -0
  635. package/dist/menu/slots.js +94 -0
  636. package/dist/menu/slots.js.map +1 -0
  637. package/dist/menu.d.ts +81 -80
  638. package/dist/menu.d.ts.map +1 -1
  639. package/dist/menu.js +79 -199
  640. package/dist/menu.js.map +1 -1
  641. package/dist/menuView.d.ts.map +1 -1
  642. package/dist/menuView.js +34 -9
  643. package/dist/menuView.js.map +1 -1
  644. package/dist/menubar.d.ts +42 -10
  645. package/dist/menubar.d.ts.map +1 -1
  646. package/dist/menubar.js +49 -22
  647. package/dist/menubar.js.map +1 -1
  648. package/dist/messageScroller.d.ts +52 -11
  649. package/dist/messageScroller.d.ts.map +1 -1
  650. package/dist/messageScroller.js +65 -17
  651. package/dist/messageScroller.js.map +1 -1
  652. package/dist/meter.d.ts +4 -0
  653. package/dist/meter.d.ts.map +1 -1
  654. package/dist/meter.js +21 -1
  655. package/dist/meter.js.map +1 -1
  656. package/dist/nav.d.ts +48 -6
  657. package/dist/nav.d.ts.map +1 -1
  658. package/dist/nav.js +108 -33
  659. package/dist/nav.js.map +1 -1
  660. package/dist/numberField.d.ts +55 -8
  661. package/dist/numberField.d.ts.map +1 -1
  662. package/dist/numberField.js +89 -19
  663. package/dist/numberField.js.map +1 -1
  664. package/dist/otpField.d.ts +15 -1
  665. package/dist/otpField.d.ts.map +1 -1
  666. package/dist/otpField.js +19 -4
  667. package/dist/otpField.js.map +1 -1
  668. package/dist/pagination.d.ts +58 -16
  669. package/dist/pagination.d.ts.map +1 -1
  670. package/dist/pagination.js +78 -27
  671. package/dist/pagination.js.map +1 -1
  672. package/dist/passwordInput.d.ts +64 -13
  673. package/dist/passwordInput.d.ts.map +1 -1
  674. package/dist/passwordInput.js +90 -30
  675. package/dist/passwordInput.js.map +1 -1
  676. package/dist/patterns.d.ts +237 -15
  677. package/dist/patterns.d.ts.map +1 -1
  678. package/dist/patterns.js +451 -66
  679. package/dist/patterns.js.map +1 -1
  680. package/dist/picker.d.ts +82 -16
  681. package/dist/picker.d.ts.map +1 -1
  682. package/dist/picker.js +163 -67
  683. package/dist/picker.js.map +1 -1
  684. package/dist/popover.d.ts +1 -1
  685. package/dist/popupView.d.ts +3 -0
  686. package/dist/popupView.d.ts.map +1 -1
  687. package/dist/popupView.js +5 -1
  688. package/dist/popupView.js.map +1 -1
  689. package/dist/press.d.ts +23 -0
  690. package/dist/press.d.ts.map +1 -0
  691. package/dist/press.js +29 -0
  692. package/dist/press.js.map +1 -0
  693. package/dist/progress.d.ts +3 -2
  694. package/dist/progress.d.ts.map +1 -1
  695. package/dist/progress.js.map +1 -1
  696. package/dist/qrCode.d.ts +11 -2
  697. package/dist/qrCode.d.ts.map +1 -1
  698. package/dist/qrCode.js +10 -3
  699. package/dist/qrCode.js.map +1 -1
  700. package/dist/questionnaire.d.ts +15 -12
  701. package/dist/questionnaire.d.ts.map +1 -1
  702. package/dist/questionnaire.js +23 -12
  703. package/dist/questionnaire.js.map +1 -1
  704. package/dist/radioGroup/readingKeys.d.ts +11 -0
  705. package/dist/radioGroup/readingKeys.d.ts.map +1 -0
  706. package/dist/radioGroup/readingKeys.js +48 -0
  707. package/dist/radioGroup/readingKeys.js.map +1 -0
  708. package/dist/radioGroup/slots.d.ts +34 -0
  709. package/dist/radioGroup/slots.d.ts.map +1 -0
  710. package/dist/radioGroup/slots.js +58 -0
  711. package/dist/radioGroup/slots.js.map +1 -0
  712. package/dist/radioGroup/view.d.ts +55 -0
  713. package/dist/radioGroup/view.d.ts.map +1 -0
  714. package/dist/radioGroup/view.js +65 -0
  715. package/dist/radioGroup/view.js.map +1 -0
  716. package/dist/radioGroup.d.ts +12 -35
  717. package/dist/radioGroup.d.ts.map +1 -1
  718. package/dist/radioGroup.js +12 -57
  719. package/dist/radioGroup.js.map +1 -1
  720. package/dist/rating/words.d.ts +14 -0
  721. package/dist/rating/words.d.ts.map +1 -0
  722. package/dist/rating/words.js +11 -0
  723. package/dist/rating/words.js.map +1 -0
  724. package/dist/rating.d.ts +25 -16
  725. package/dist/rating.d.ts.map +1 -1
  726. package/dist/rating.js +52 -46
  727. package/dist/rating.js.map +1 -1
  728. package/dist/recipes/accordion.d.ts +7 -4
  729. package/dist/recipes/accordion.d.ts.map +1 -1
  730. package/dist/recipes/accordion.js +28 -9
  731. package/dist/recipes/accordion.js.map +1 -1
  732. package/dist/recipes/alert.d.ts +7 -1
  733. package/dist/recipes/alert.d.ts.map +1 -1
  734. package/dist/recipes/alert.js +18 -8
  735. package/dist/recipes/alert.js.map +1 -1
  736. package/dist/recipes/angleSlider.d.ts +2 -2
  737. package/dist/recipes/appShell.d.ts +2 -1
  738. package/dist/recipes/appShell.d.ts.map +1 -1
  739. package/dist/recipes/appShell.js +33 -1
  740. package/dist/recipes/appShell.js.map +1 -1
  741. package/dist/recipes/avatar.d.ts +8 -1
  742. package/dist/recipes/avatar.d.ts.map +1 -1
  743. package/dist/recipes/avatar.js +51 -8
  744. package/dist/recipes/avatar.js.map +1 -1
  745. package/dist/recipes/badge.d.ts +39 -13
  746. package/dist/recipes/badge.d.ts.map +1 -1
  747. package/dist/recipes/badge.js +126 -52
  748. package/dist/recipes/badge.js.map +1 -1
  749. package/dist/recipes/breadcrumb.d.ts +16 -4
  750. package/dist/recipes/breadcrumb.d.ts.map +1 -1
  751. package/dist/recipes/breadcrumb.js +68 -21
  752. package/dist/recipes/breadcrumb.js.map +1 -1
  753. package/dist/recipes/button.d.ts +15 -1
  754. package/dist/recipes/button.d.ts.map +1 -1
  755. package/dist/recipes/button.js +52 -5
  756. package/dist/recipes/button.js.map +1 -1
  757. package/dist/recipes/buttonGroup.d.ts +1 -1
  758. package/dist/recipes/calendar.d.ts +10 -1
  759. package/dist/recipes/calendar.d.ts.map +1 -1
  760. package/dist/recipes/calendar.js +34 -6
  761. package/dist/recipes/calendar.js.map +1 -1
  762. package/dist/recipes/card.d.ts +18 -0
  763. package/dist/recipes/card.d.ts.map +1 -1
  764. package/dist/recipes/card.js +65 -6
  765. package/dist/recipes/card.js.map +1 -1
  766. package/dist/recipes/carousel.d.ts.map +1 -1
  767. package/dist/recipes/carousel.js +2 -2
  768. package/dist/recipes/carousel.js.map +1 -1
  769. package/dist/recipes/cascadeSelect.d.ts +5 -1
  770. package/dist/recipes/cascadeSelect.d.ts.map +1 -1
  771. package/dist/recipes/cascadeSelect.js +13 -31
  772. package/dist/recipes/cascadeSelect.js.map +1 -1
  773. package/dist/recipes/chart.d.ts.map +1 -1
  774. package/dist/recipes/chart.js +2 -1
  775. package/dist/recipes/chart.js.map +1 -1
  776. package/dist/recipes/chatMessage.d.ts +10 -1
  777. package/dist/recipes/chatMessage.d.ts.map +1 -1
  778. package/dist/recipes/chatMessage.js +34 -1
  779. package/dist/recipes/chatMessage.js.map +1 -1
  780. package/dist/recipes/checkboxGroup.d.ts +10 -2
  781. package/dist/recipes/checkboxGroup.d.ts.map +1 -1
  782. package/dist/recipes/checkboxGroup.js +38 -4
  783. package/dist/recipes/checkboxGroup.js.map +1 -1
  784. package/dist/recipes/codeBlock.d.ts +20 -1
  785. package/dist/recipes/codeBlock.d.ts.map +1 -1
  786. package/dist/recipes/codeBlock.js +176 -67
  787. package/dist/recipes/codeBlock.js.map +1 -1
  788. package/dist/recipes/colorPicker.d.ts +2 -2
  789. package/dist/recipes/combobox.d.ts +7 -1
  790. package/dist/recipes/combobox.d.ts.map +1 -1
  791. package/dist/recipes/combobox.js +9 -21
  792. package/dist/recipes/combobox.js.map +1 -1
  793. package/dist/recipes/command.d.ts.map +1 -1
  794. package/dist/recipes/command.js +2 -2
  795. package/dist/recipes/command.js.map +1 -1
  796. package/dist/recipes/datePicker.d.ts +1 -0
  797. package/dist/recipes/datePicker.d.ts.map +1 -1
  798. package/dist/recipes/datePicker.js +5 -2
  799. package/dist/recipes/datePicker.js.map +1 -1
  800. package/dist/recipes/design.d.ts +46 -0
  801. package/dist/recipes/design.d.ts.map +1 -1
  802. package/dist/recipes/design.js +49 -16
  803. package/dist/recipes/design.js.map +1 -1
  804. package/dist/recipes/dialog.d.ts +38 -2
  805. package/dist/recipes/dialog.d.ts.map +1 -1
  806. package/dist/recipes/dialog.js +43 -18
  807. package/dist/recipes/dialog.js.map +1 -1
  808. package/dist/recipes/disclosure.d.ts +4 -1
  809. package/dist/recipes/disclosure.d.ts.map +1 -1
  810. package/dist/recipes/disclosure.js +14 -2
  811. package/dist/recipes/disclosure.js.map +1 -1
  812. package/dist/recipes/drawer.d.ts.map +1 -1
  813. package/dist/recipes/drawer.js +6 -1
  814. package/dist/recipes/drawer.js.map +1 -1
  815. package/dist/recipes/field.d.ts +57 -26
  816. package/dist/recipes/field.d.ts.map +1 -1
  817. package/dist/recipes/field.js +124 -25
  818. package/dist/recipes/field.js.map +1 -1
  819. package/dist/recipes/fieldShell.d.ts +12 -0
  820. package/dist/recipes/fieldShell.d.ts.map +1 -0
  821. package/dist/recipes/fieldShell.js +71 -0
  822. package/dist/recipes/fieldShell.js.map +1 -0
  823. package/dist/recipes/figure.d.ts +6 -0
  824. package/dist/recipes/figure.d.ts.map +1 -1
  825. package/dist/recipes/figure.js +14 -5
  826. package/dist/recipes/figure.js.map +1 -1
  827. package/dist/recipes/fileDrop.js +7 -1
  828. package/dist/recipes/fileDrop.js.map +1 -1
  829. package/dist/recipes/fileInput.d.ts +23 -0
  830. package/dist/recipes/fileInput.d.ts.map +1 -0
  831. package/dist/recipes/fileInput.js +92 -0
  832. package/dist/recipes/fileInput.js.map +1 -0
  833. package/dist/recipes/fileUpload.d.ts +86 -0
  834. package/dist/recipes/fileUpload.d.ts.map +1 -0
  835. package/dist/recipes/fileUpload.js +401 -0
  836. package/dist/recipes/fileUpload.js.map +1 -0
  837. package/dist/recipes/floatingPanel.d.ts +1 -1
  838. package/dist/recipes/floatingPanel.js +2 -2
  839. package/dist/recipes/floatingPanel.js.map +1 -1
  840. package/dist/recipes/frame.d.ts +51 -0
  841. package/dist/recipes/frame.d.ts.map +1 -0
  842. package/dist/recipes/frame.js +105 -0
  843. package/dist/recipes/frame.js.map +1 -0
  844. package/dist/recipes/icon.d.ts +50 -1
  845. package/dist/recipes/icon.d.ts.map +1 -1
  846. package/dist/recipes/icon.js +107 -21
  847. package/dist/recipes/icon.js.map +1 -1
  848. package/dist/recipes/imageCropper.d.ts +1 -0
  849. package/dist/recipes/imageCropper.d.ts.map +1 -1
  850. package/dist/recipes/imageCropper.js +7 -3
  851. package/dist/recipes/imageCropper.js.map +1 -1
  852. package/dist/recipes/index.d.ts +13 -6
  853. package/dist/recipes/index.js +12 -6
  854. package/dist/recipes/inputCopy.d.ts +5 -2
  855. package/dist/recipes/inputCopy.d.ts.map +1 -1
  856. package/dist/recipes/inputCopy.js +7 -3
  857. package/dist/recipes/inputCopy.js.map +1 -1
  858. package/dist/recipes/item.d.ts +7 -1
  859. package/dist/recipes/item.d.ts.map +1 -1
  860. package/dist/recipes/item.js +20 -0
  861. package/dist/recipes/item.js.map +1 -1
  862. package/dist/recipes/kbd.js +4 -0
  863. package/dist/recipes/kbd.js.map +1 -1
  864. package/dist/recipes/label.d.ts +4 -1
  865. package/dist/recipes/label.d.ts.map +1 -1
  866. package/dist/recipes/label.js +32 -9
  867. package/dist/recipes/label.js.map +1 -1
  868. package/dist/recipes/listbox.d.ts +7 -1
  869. package/dist/recipes/listbox.d.ts.map +1 -1
  870. package/dist/recipes/listbox.js +46 -7
  871. package/dist/recipes/listbox.js.map +1 -1
  872. package/dist/recipes/menu.d.ts +5 -1
  873. package/dist/recipes/menu.d.ts.map +1 -1
  874. package/dist/recipes/menu.js +26 -2
  875. package/dist/recipes/menu.js.map +1 -1
  876. package/dist/recipes/menubar.d.ts +5 -1
  877. package/dist/recipes/menubar.d.ts.map +1 -1
  878. package/dist/recipes/menubar.js +4 -3
  879. package/dist/recipes/menubar.js.map +1 -1
  880. package/dist/recipes/meter.d.ts +11 -1
  881. package/dist/recipes/meter.d.ts.map +1 -1
  882. package/dist/recipes/meter.js +60 -26
  883. package/dist/recipes/meter.js.map +1 -1
  884. package/dist/recipes/nav.d.ts +11 -3
  885. package/dist/recipes/nav.d.ts.map +1 -1
  886. package/dist/recipes/nav.js +56 -22
  887. package/dist/recipes/nav.js.map +1 -1
  888. package/dist/recipes/numberField.d.ts +16 -2
  889. package/dist/recipes/numberField.d.ts.map +1 -1
  890. package/dist/recipes/numberField.js +66 -49
  891. package/dist/recipes/numberField.js.map +1 -1
  892. package/dist/recipes/otpField.d.ts +1 -1
  893. package/dist/recipes/otpField.js +5 -5
  894. package/dist/recipes/otpField.js.map +1 -1
  895. package/dist/recipes/pagination.d.ts +26 -6
  896. package/dist/recipes/pagination.d.ts.map +1 -1
  897. package/dist/recipes/pagination.js +42 -13
  898. package/dist/recipes/pagination.js.map +1 -1
  899. package/dist/recipes/passwordInput.d.ts +7 -3
  900. package/dist/recipes/passwordInput.d.ts.map +1 -1
  901. package/dist/recipes/passwordInput.js +11 -4
  902. package/dist/recipes/passwordInput.js.map +1 -1
  903. package/dist/recipes/picker.d.ts +9 -6
  904. package/dist/recipes/picker.d.ts.map +1 -1
  905. package/dist/recipes/picker.js +18 -7
  906. package/dist/recipes/picker.js.map +1 -1
  907. package/dist/recipes/popover.d.ts.map +1 -1
  908. package/dist/recipes/popover.js +6 -3
  909. package/dist/recipes/popover.js.map +1 -1
  910. package/dist/recipes/popup.d.ts +11 -0
  911. package/dist/recipes/popup.d.ts.map +1 -1
  912. package/dist/recipes/popup.js +22 -8
  913. package/dist/recipes/popup.js.map +1 -1
  914. package/dist/recipes/progress.d.ts +1 -1
  915. package/dist/recipes/progress.d.ts.map +1 -1
  916. package/dist/recipes/progress.js +5 -4
  917. package/dist/recipes/progress.js.map +1 -1
  918. package/dist/recipes/radio.d.ts +20 -3
  919. package/dist/recipes/radio.d.ts.map +1 -1
  920. package/dist/recipes/radio.js +47 -4
  921. package/dist/recipes/radio.js.map +1 -1
  922. package/dist/recipes/rating.d.ts +12 -3
  923. package/dist/recipes/rating.d.ts.map +1 -1
  924. package/dist/recipes/rating.js +4 -1
  925. package/dist/recipes/rating.js.map +1 -1
  926. package/dist/recipes/resizable.d.ts +4 -1
  927. package/dist/recipes/resizable.d.ts.map +1 -1
  928. package/dist/recipes/resizable.js +19 -2
  929. package/dist/recipes/resizable.js.map +1 -1
  930. package/dist/recipes/scrollArea.d.ts +7 -1
  931. package/dist/recipes/scrollArea.d.ts.map +1 -1
  932. package/dist/recipes/scrollArea.js +26 -17
  933. package/dist/recipes/scrollArea.js.map +1 -1
  934. package/dist/recipes/searchField.d.ts +41 -0
  935. package/dist/recipes/searchField.d.ts.map +1 -0
  936. package/dist/recipes/searchField.js +96 -0
  937. package/dist/recipes/searchField.js.map +1 -0
  938. package/dist/recipes/segmented.d.ts +3 -2
  939. package/dist/recipes/segmented.d.ts.map +1 -1
  940. package/dist/recipes/segmented.js +9 -5
  941. package/dist/recipes/segmented.js.map +1 -1
  942. package/dist/recipes/select.d.ts +3 -0
  943. package/dist/recipes/select.d.ts.map +1 -1
  944. package/dist/recipes/select.js +3 -3
  945. package/dist/recipes/select.js.map +1 -1
  946. package/dist/recipes/sheet.d.ts +16 -3
  947. package/dist/recipes/sheet.d.ts.map +1 -1
  948. package/dist/recipes/sheet.js +29 -10
  949. package/dist/recipes/sheet.js.map +1 -1
  950. package/dist/recipes/sidebar.d.ts +2 -1
  951. package/dist/recipes/sidebar.d.ts.map +1 -1
  952. package/dist/recipes/sidebar.js +8 -1
  953. package/dist/recipes/sidebar.js.map +1 -1
  954. package/dist/recipes/signaturePad.d.ts +3 -1
  955. package/dist/recipes/signaturePad.d.ts.map +1 -1
  956. package/dist/recipes/signaturePad.js +1 -0
  957. package/dist/recipes/signaturePad.js.map +1 -1
  958. package/dist/recipes/skeleton.d.ts.map +1 -1
  959. package/dist/recipes/skeleton.js +5 -5
  960. package/dist/recipes/skeleton.js.map +1 -1
  961. package/dist/recipes/slider.d.ts +4 -3
  962. package/dist/recipes/slider.d.ts.map +1 -1
  963. package/dist/recipes/slider.js +8 -0
  964. package/dist/recipes/slider.js.map +1 -1
  965. package/dist/recipes/spinner.d.ts +12 -0
  966. package/dist/recipes/spinner.d.ts.map +1 -1
  967. package/dist/recipes/spinner.js +5 -1
  968. package/dist/recipes/spinner.js.map +1 -1
  969. package/dist/recipes/steps.d.ts +14 -1
  970. package/dist/recipes/steps.d.ts.map +1 -1
  971. package/dist/recipes/steps.js +43 -1
  972. package/dist/recipes/steps.js.map +1 -1
  973. package/dist/recipes/table.d.ts +23 -2
  974. package/dist/recipes/table.d.ts.map +1 -1
  975. package/dist/recipes/table.js +30 -2
  976. package/dist/recipes/table.js.map +1 -1
  977. package/dist/recipes/tabs.d.ts +3 -2
  978. package/dist/recipes/tabs.d.ts.map +1 -1
  979. package/dist/recipes/tabs.js +9 -1
  980. package/dist/recipes/tabs.js.map +1 -1
  981. package/dist/recipes/tagsInput.d.ts +18 -1
  982. package/dist/recipes/tagsInput.d.ts.map +1 -1
  983. package/dist/recipes/tagsInput.js +46 -15
  984. package/dist/recipes/tagsInput.js.map +1 -1
  985. package/dist/recipes/thinkingSteps.d.ts +5 -2
  986. package/dist/recipes/thinkingSteps.d.ts.map +1 -1
  987. package/dist/recipes/thinkingSteps.js +26 -2
  988. package/dist/recipes/thinkingSteps.js.map +1 -1
  989. package/dist/recipes/timer.js +1 -1
  990. package/dist/recipes/timer.js.map +1 -1
  991. package/dist/recipes/toast.d.ts +10 -1
  992. package/dist/recipes/toast.d.ts.map +1 -1
  993. package/dist/recipes/toast.js +46 -3
  994. package/dist/recipes/toast.js.map +1 -1
  995. package/dist/recipes/toggle.d.ts +46 -4
  996. package/dist/recipes/toggle.d.ts.map +1 -1
  997. package/dist/recipes/toggle.js +92 -10
  998. package/dist/recipes/toggle.js.map +1 -1
  999. package/dist/recipes/toolbar.d.ts +18 -0
  1000. package/dist/recipes/toolbar.d.ts.map +1 -0
  1001. package/dist/recipes/toolbar.js +53 -0
  1002. package/dist/recipes/toolbar.js.map +1 -0
  1003. package/dist/recipes/tooltip.d.ts.map +1 -1
  1004. package/dist/recipes/tooltip.js.map +1 -1
  1005. package/dist/recipes/tour.js +1 -1
  1006. package/dist/recipes/tour.js.map +1 -1
  1007. package/dist/recipes/treeView.d.ts +4 -2
  1008. package/dist/recipes/treeView.d.ts.map +1 -1
  1009. package/dist/recipes/treeView.js +14 -1
  1010. package/dist/recipes/treeView.js.map +1 -1
  1011. package/dist/recipes/typography.d.ts +1 -49
  1012. package/dist/recipes/typography.d.ts.map +1 -1
  1013. package/dist/recipes/typography.js +66 -65
  1014. package/dist/recipes/typography.js.map +1 -1
  1015. package/dist/recipes/virtualList.js +1 -1
  1016. package/dist/recipes/virtualList.js.map +1 -1
  1017. package/dist/resizable.d.ts +31 -2
  1018. package/dist/resizable.d.ts.map +1 -1
  1019. package/dist/resizable.js +75 -24
  1020. package/dist/resizable.js.map +1 -1
  1021. package/dist/rowContent.d.ts +16 -0
  1022. package/dist/rowContent.d.ts.map +1 -0
  1023. package/dist/rowContent.js +1 -0
  1024. package/dist/scrollArea/overlayBars.d.ts +8 -0
  1025. package/dist/scrollArea/overlayBars.d.ts.map +1 -0
  1026. package/dist/scrollArea/overlayBars.js +17 -0
  1027. package/dist/scrollArea/overlayBars.js.map +1 -0
  1028. package/dist/scrollArea/slots.d.ts +12 -0
  1029. package/dist/scrollArea/slots.d.ts.map +1 -0
  1030. package/dist/scrollArea/slots.js +18 -0
  1031. package/dist/scrollArea/slots.js.map +1 -0
  1032. package/dist/scrollArea.d.ts +27 -17
  1033. package/dist/scrollArea.d.ts.map +1 -1
  1034. package/dist/scrollArea.js +11 -26
  1035. package/dist/scrollArea.js.map +1 -1
  1036. package/dist/searchField.d.ts +102 -0
  1037. package/dist/searchField.d.ts.map +1 -0
  1038. package/dist/searchField.js +117 -0
  1039. package/dist/searchField.js.map +1 -0
  1040. package/dist/segmented/fluid.d.ts +9 -0
  1041. package/dist/segmented/fluid.d.ts.map +1 -0
  1042. package/dist/segmented/fluid.js +36 -0
  1043. package/dist/segmented/fluid.js.map +1 -0
  1044. package/dist/segmented/slots.d.ts +28 -0
  1045. package/dist/segmented/slots.d.ts.map +1 -0
  1046. package/dist/segmented/slots.js +52 -0
  1047. package/dist/segmented/slots.js.map +1 -0
  1048. package/dist/segmented.d.ts +46 -40
  1049. package/dist/segmented.d.ts.map +1 -1
  1050. package/dist/segmented.js +78 -77
  1051. package/dist/segmented.js.map +1 -1
  1052. package/dist/select/slots.d.ts +17 -0
  1053. package/dist/select/slots.d.ts.map +1 -0
  1054. package/dist/select/slots.js +29 -0
  1055. package/dist/select/slots.js.map +1 -0
  1056. package/dist/select/view.d.ts +51 -0
  1057. package/dist/select/view.d.ts.map +1 -0
  1058. package/dist/select/view.js +53 -0
  1059. package/dist/select/view.js.map +1 -0
  1060. package/dist/select.d.ts +4 -12
  1061. package/dist/select.d.ts.map +1 -1
  1062. package/dist/select.js +4 -22
  1063. package/dist/select.js.map +1 -1
  1064. package/dist/sheet.d.ts +21 -27
  1065. package/dist/sheet.d.ts.map +1 -1
  1066. package/dist/sheet.js +53 -35
  1067. package/dist/sheet.js.map +1 -1
  1068. package/dist/sidebar/fluid.d.ts +9 -0
  1069. package/dist/sidebar/fluid.d.ts.map +1 -0
  1070. package/dist/sidebar/fluid.js +28 -0
  1071. package/dist/sidebar/fluid.js.map +1 -0
  1072. package/dist/sidebar/slots.d.ts +44 -0
  1073. package/dist/sidebar/slots.d.ts.map +1 -0
  1074. package/dist/sidebar/slots.js +70 -0
  1075. package/dist/sidebar/slots.js.map +1 -0
  1076. package/dist/sidebar.d.ts +30 -82
  1077. package/dist/sidebar.d.ts.map +1 -1
  1078. package/dist/sidebar.js +53 -133
  1079. package/dist/sidebar.js.map +1 -1
  1080. package/dist/signaturePad.d.ts +66 -7
  1081. package/dist/signaturePad.d.ts.map +1 -1
  1082. package/dist/signaturePad.js +85 -18
  1083. package/dist/signaturePad.js.map +1 -1
  1084. package/dist/skeleton.d.ts +29 -5
  1085. package/dist/skeleton.d.ts.map +1 -1
  1086. package/dist/skeleton.js +24 -5
  1087. package/dist/skeleton.js.map +1 -1
  1088. package/dist/slider.d.ts +54 -9
  1089. package/dist/slider.d.ts.map +1 -1
  1090. package/dist/slider.js +125 -61
  1091. package/dist/slider.js.map +1 -1
  1092. package/dist/spinner.d.ts +1 -1
  1093. package/dist/spinner.js +1 -1
  1094. package/dist/spinner.js.map +1 -1
  1095. package/dist/splitter.d.ts +27 -0
  1096. package/dist/splitter.d.ts.map +1 -0
  1097. package/dist/splitter.js +30 -0
  1098. package/dist/splitter.js.map +1 -0
  1099. package/dist/steps.d.ts +41 -0
  1100. package/dist/steps.d.ts.map +1 -1
  1101. package/dist/steps.js +35 -4
  1102. package/dist/steps.js.map +1 -1
  1103. package/dist/swipe.d.ts +26 -0
  1104. package/dist/swipe.d.ts.map +1 -0
  1105. package/dist/swipe.js +29 -0
  1106. package/dist/swipe.js.map +1 -0
  1107. package/dist/switch/draggable.d.ts +11 -0
  1108. package/dist/switch/draggable.d.ts.map +1 -0
  1109. package/dist/switch/draggable.js +144 -0
  1110. package/dist/switch/draggable.js.map +1 -0
  1111. package/dist/switch/slots.d.ts +16 -0
  1112. package/dist/switch/slots.d.ts.map +1 -0
  1113. package/dist/switch/slots.js +35 -0
  1114. package/dist/switch/slots.js.map +1 -0
  1115. package/dist/switch/view.d.ts +50 -0
  1116. package/dist/switch/view.d.ts.map +1 -0
  1117. package/dist/switch/view.js +49 -0
  1118. package/dist/switch/view.js.map +1 -0
  1119. package/dist/switch.d.ts +5 -19
  1120. package/dist/switch.d.ts.map +1 -1
  1121. package/dist/switch.js +5 -151
  1122. package/dist/switch.js.map +1 -1
  1123. package/dist/table/checkboxes.d.ts +10 -0
  1124. package/dist/table/checkboxes.d.ts.map +1 -0
  1125. package/dist/table/checkboxes.js +18 -0
  1126. package/dist/table/checkboxes.js.map +1 -0
  1127. package/dist/table/fluid.d.ts +10 -0
  1128. package/dist/table/fluid.d.ts.map +1 -0
  1129. package/dist/table/fluid.js +30 -0
  1130. package/dist/table/fluid.js.map +1 -0
  1131. package/dist/table.d.ts +102 -30
  1132. package/dist/table.d.ts.map +1 -1
  1133. package/dist/table.js +57 -39
  1134. package/dist/table.js.map +1 -1
  1135. package/dist/tabs/fluid.d.ts +10 -0
  1136. package/dist/tabs/fluid.d.ts.map +1 -0
  1137. package/dist/tabs/fluid.js +37 -0
  1138. package/dist/tabs/fluid.js.map +1 -0
  1139. package/dist/tabs/readingKeys.d.ts +11 -0
  1140. package/dist/tabs/readingKeys.d.ts.map +1 -0
  1141. package/dist/tabs/readingKeys.js +20 -0
  1142. package/dist/tabs/readingKeys.js.map +1 -0
  1143. package/dist/tabs/slots.d.ts +31 -0
  1144. package/dist/tabs/slots.d.ts.map +1 -0
  1145. package/dist/tabs/slots.js +52 -0
  1146. package/dist/tabs/slots.js.map +1 -0
  1147. package/dist/tabs.d.ts +73 -46
  1148. package/dist/tabs.d.ts.map +1 -1
  1149. package/dist/tabs.js +80 -99
  1150. package/dist/tabs.js.map +1 -1
  1151. package/dist/tagsInput.d.ts +83 -15
  1152. package/dist/tagsInput.d.ts.map +1 -1
  1153. package/dist/tagsInput.js +206 -47
  1154. package/dist/tagsInput.js.map +1 -1
  1155. package/dist/textarea.d.ts +13 -1
  1156. package/dist/textarea.d.ts.map +1 -1
  1157. package/dist/textarea.js +19 -8
  1158. package/dist/textarea.js.map +1 -1
  1159. package/dist/thinkingIndicator.d.ts +13 -0
  1160. package/dist/thinkingIndicator.d.ts.map +1 -1
  1161. package/dist/thinkingIndicator.js +8 -1
  1162. package/dist/thinkingIndicator.js.map +1 -1
  1163. package/dist/thinkingSteps/state.d.ts +44 -0
  1164. package/dist/thinkingSteps/state.d.ts.map +1 -0
  1165. package/dist/thinkingSteps/state.js +56 -0
  1166. package/dist/thinkingSteps/state.js.map +1 -0
  1167. package/dist/thinkingSteps.d.ts +73 -15
  1168. package/dist/thinkingSteps.d.ts.map +1 -1
  1169. package/dist/thinkingSteps.js +60 -30
  1170. package/dist/thinkingSteps.js.map +1 -1
  1171. package/dist/timer.d.ts +19 -3
  1172. package/dist/timer.d.ts.map +1 -1
  1173. package/dist/timer.js +13 -6
  1174. package/dist/timer.js.map +1 -1
  1175. package/dist/toast/keepFocus.d.ts +10 -0
  1176. package/dist/toast/keepFocus.d.ts.map +1 -0
  1177. package/dist/toast/keepFocus.js +30 -0
  1178. package/dist/toast/keepFocus.js.map +1 -0
  1179. package/dist/toast/slots.d.ts +36 -0
  1180. package/dist/toast/slots.d.ts.map +1 -0
  1181. package/dist/toast/slots.js +61 -0
  1182. package/dist/toast/slots.js.map +1 -0
  1183. package/dist/toast.d.ts +50 -37
  1184. package/dist/toast.d.ts.map +1 -1
  1185. package/dist/toast.js +64 -69
  1186. package/dist/toast.js.map +1 -1
  1187. package/dist/toastView.d.ts +77 -0
  1188. package/dist/toastView.d.ts.map +1 -1
  1189. package/dist/toastView.js +15 -1
  1190. package/dist/toastView.js.map +1 -1
  1191. package/dist/toggleRow.d.ts +41 -0
  1192. package/dist/toggleRow.d.ts.map +1 -0
  1193. package/dist/toggleRow.js +41 -0
  1194. package/dist/toggleRow.js.map +1 -0
  1195. package/dist/toolbar.d.ts +149 -0
  1196. package/dist/toolbar.d.ts.map +1 -0
  1197. package/dist/toolbar.js +205 -0
  1198. package/dist/toolbar.js.map +1 -0
  1199. package/dist/tour/advanceOnClick.d.ts +14 -0
  1200. package/dist/tour/advanceOnClick.d.ts.map +1 -0
  1201. package/dist/tour/advanceOnClick.js +27 -0
  1202. package/dist/tour/advanceOnClick.js.map +1 -0
  1203. package/dist/tour/focusReturn.d.ts +10 -0
  1204. package/dist/tour/focusReturn.d.ts.map +1 -0
  1205. package/dist/tour/focusReturn.js +19 -0
  1206. package/dist/tour/focusReturn.js.map +1 -0
  1207. package/dist/tour/message.d.ts +20 -0
  1208. package/dist/tour/message.d.ts.map +1 -0
  1209. package/dist/tour/message.js +21 -0
  1210. package/dist/tour/message.js.map +1 -0
  1211. package/dist/tour/slots.d.ts +21 -0
  1212. package/dist/tour/slots.d.ts.map +1 -0
  1213. package/dist/tour/slots.js +40 -0
  1214. package/dist/tour/slots.js.map +1 -0
  1215. package/dist/tour.d.ts +84 -103
  1216. package/dist/tour.d.ts.map +1 -1
  1217. package/dist/tour.js +103 -151
  1218. package/dist/tour.js.map +1 -1
  1219. package/dist/treeView/fluid.d.ts +8 -0
  1220. package/dist/treeView/fluid.d.ts.map +1 -0
  1221. package/dist/treeView/fluid.js +24 -0
  1222. package/dist/treeView/fluid.js.map +1 -0
  1223. package/dist/treeView/slots.d.ts +24 -0
  1224. package/dist/treeView/slots.d.ts.map +1 -0
  1225. package/dist/treeView/slots.js +53 -0
  1226. package/dist/treeView/slots.js.map +1 -0
  1227. package/dist/treeView.d.ts +61 -50
  1228. package/dist/treeView.d.ts.map +1 -1
  1229. package/dist/treeView.js +102 -96
  1230. package/dist/treeView.js.map +1 -1
  1231. package/dist/typography.d.ts +14 -6
  1232. package/dist/typography.d.ts.map +1 -1
  1233. package/dist/typography.js +10 -9
  1234. package/dist/typography.js.map +1 -1
  1235. package/dist/virtualList/overlayBars.d.ts +8 -0
  1236. package/dist/virtualList/overlayBars.d.ts.map +1 -0
  1237. package/dist/virtualList/overlayBars.js +17 -0
  1238. package/dist/virtualList/overlayBars.js.map +1 -0
  1239. package/dist/virtualList/slots.d.ts +13 -0
  1240. package/dist/virtualList/slots.d.ts.map +1 -0
  1241. package/dist/virtualList/slots.js +16 -0
  1242. package/dist/virtualList/slots.js.map +1 -0
  1243. package/dist/virtualList.d.ts +4 -28
  1244. package/dist/virtualList.d.ts.map +1 -1
  1245. package/dist/virtualList.js +3 -32
  1246. package/dist/virtualList.js.map +1 -1
  1247. package/dist/windowList.d.ts +76 -6
  1248. package/dist/windowList.d.ts.map +1 -1
  1249. package/dist/windowList.js +319 -32
  1250. package/dist/windowList.js.map +1 -1
  1251. package/dist/words.d.ts +16 -0
  1252. package/dist/words.d.ts.map +1 -0
  1253. package/dist/words.js +27 -0
  1254. package/dist/words.js.map +1 -0
  1255. package/package.json +11 -9
package/README.md CHANGED
@@ -1,43 +1,35 @@
1
1
  # `foldkit-mixins-ui`
2
2
 
3
- Adapts [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui) render seams into
4
- [`foldkit-mixins`](../mixins) slots.
5
-
6
- Use it when an `@foldkit/ui` component already owns the difficult state and
7
- accessibility behavior, but you want callers to style or decorate the component
8
- through a typed extension contract instead of copying its markup or manually
9
- merging attribute arrays.
10
-
11
- The ownership rule stays simple:
12
-
13
- ```text
14
- @foldkit/ui
15
- owns component state
16
- owns accessibility behavior
17
- owns its base attributes
18
-
19
- foldkit-mixins-ui
20
- names the component's public attribute bundles as Slots
21
-
22
- foldkit-mixins
23
- safely merges Style + Behavior into those Slots
24
- ```
25
-
26
- Three kinds of thing live here:
27
-
28
- - **Adapters** add no state and no renderer of their own. They name an
29
- `@foldkit/ui` component's bundles as Slots and run the Mixins resolver over
30
- them: Button, Dialog, Popover, Tooltip, Tabs, Listbox, Combobox and more.
31
- - **Stateless views** draw a vocabulary from what the application passes and
32
- keep nothing: Card, Badge, Item, Avatar, Command, Slider, PasswordInput.
33
- - **Components with a small Model of their own**: Menu, Menubar, Toast,
34
- Sheet, Picker, WindowList, Drawer, TagsInput, TreeView, Carousel, Resizable, ColorPicker, InputCopy,
35
- MessageScroller, Questionnaire, AngleSlider, Timer, Marquee, ImageCropper,
36
- SignaturePad, Chart, CascadeSelect, FloatingPanel and Tour.
37
- The Model holds interaction state only (what is open, a drag, a countdown,
38
- a draft), and the application keeps it and folds it with the component's
39
- `update`, as it folds an `@foldkit/ui` Submodel. The value chosen stays
40
- the application's.
3
+ The widget catalog of Foldkit Plus: about ninety styled, accessible widgets
4
+ (buttons, fields, menus, dialogs, tables, charts, a chat vocabulary) in two
5
+ families. **Adapters** take a component [`@foldkit/ui`](https://www.npmjs.com/package/@foldkit/ui)
6
+ already owns, name its attribute bundles as typed [`foldkit-mixins`](../mixins)
7
+ Slots, and run the Mixins resolver over them, so a caller styles or decorates the
8
+ component without copying its markup or merging attribute arrays by hand.
9
+ **Views and components** are this package's own, where upstream has none. A
10
+ recipe (`Recipes.X`) gives either family a look from the theme's tokens.
11
+
12
+ Every value belongs to the application's Model: what is chosen, typed, checked
13
+ or sorted. A widget's `view` is a pure function from those values to markup. The
14
+ few widgets that keep a small Model of their own hold interaction state only
15
+ (what is open, a drag, a countdown, a draft); the application places that Model
16
+ and folds it with the widget's `update`, as it folds an `@foldkit/ui` Submodel.
17
+
18
+ A widget's `view` also reads nothing from the environment (no `window`,
19
+ `navigator`, feature test, clock or default locale): a server and a browser must
20
+ draw the same markup from the same Model, or a server-rendered page is rebuilt
21
+ when it takes over. A fact about the environment, such as whether the browser has
22
+ an eyedropper, is an input the application keeps in its Model, read once in `init`
23
+ or by a Command after hydration (see [ColorPicker](#colorpicker)).
24
+
25
+ - `@foldkit/ui` owns component state, accessibility behavior and base attributes.
26
+ - `foldkit-mixins` owns Slot, Style and Behavior and the resolver that merges them
27
+ safely.
28
+ - `foldkit-primitives` owns the interaction primitives widgets compose (focus
29
+ recovery, roving tab stops, drags, scroll bars, clipboard).
30
+ - `foldkit-mixins-ui` names the bundles as Slots, draws the widgets that have no
31
+ upstream, and ships their recipes and accessibility patterns.
32
+ - The application owns the values, and every transition of them.
41
33
 
42
34
  Every shipped recipe is on the website's
43
35
  [component pages](https://foldkit-plus.pages.dev/components), each with its
@@ -45,64 +37,108 @@ variants to pick and the code that draws it, and
45
37
  [Create a theme](https://foldkit-plus.pages.dev/create) turns the theme's knobs
46
38
  over all of them at once.
47
39
 
48
- ## The mental model
49
-
50
- An `@foldkit/ui` component commonly hands its caller one or more attribute
51
- bundles:
40
+ ## When to use it
52
41
 
53
- ```text
54
- roles
55
- aria-*
56
- tabindex
57
- event handlers
58
- ChildAttributes
59
- ...
60
- ```
42
+ Use this package when:
61
43
 
62
- Those bundles are meaningful, but a raw array is not a public customization
63
- contract. A caller can accidentally add a second `OnClick`, replace something
64
- structural, or repeat bespoke merge code at every call site.
44
+ - you want a styled, accessible widget from the catalog below;
45
+ - you already use `@foldkit/ui` and want reusable styling, ARIA decoration,
46
+ analytics or element-level behavior around one of its components, through its
47
+ consumer render seam (`toView`);
48
+ - you want conflicts diagnosed rather than resolved by attribute order.
65
49
 
66
- `foldkit-mixins-ui` gives each supported bundle a stable Slot name:
50
+ It does not own application state. A Mixins `Behavior` contributes
51
+ element-level attributes and optional Mount behavior; it is not a hidden state
52
+ container. If you are building your own view rather than adapting a widget,
53
+ publish Slots directly with [`foldkit-mixins`](../mixins); for Slot / Style /
54
+ Behavior itself, read [Inside-out view composition](../../docs/mixins.md) first.
55
+ [Authoring components](../../docs/authoring-components.md) builds such a view from
56
+ primitives step by step, and lists what a widget for this catalog must carry.
67
57
 
68
- ```text
69
- @foldkit/ui component
70
- |
71
- | attribute bundles
72
- v
73
- foldkit-mixins-ui Slots
74
- |
75
- | Style + Behavior
76
- v
77
- foldkit-mixins resolver
78
- |
79
- v
80
- component-owned attrs + safe additions
81
- ```
58
+ ## The mental model
82
59
 
83
- So the component author keeps control of the component, while callers get a
84
- typed place to extend it.
60
+ An `@foldkit/ui` component hands its caller attribute bundles (roles, `aria-*`,
61
+ `tabindex`, event handlers, `ChildAttribute`s). A raw array is not a public
62
+ customization contract: a caller can add a second `OnClick`, replace something
63
+ structural, or repeat merge code at every call site. `foldkit-mixins-ui` gives
64
+ each bundle a stable Slot name. Style and Behavior attach to those Slots, and the
65
+ `foldkit-mixins` resolver merges them into the component's own attributes plus the
66
+ caller's safe additions.
67
+
68
+ The component keeps control of the component, and callers get a typed place to
69
+ extend it. A view of this package's own draws its markup through the same Slots,
70
+ so one extension contract covers both families.
71
+
72
+ ## Look, state, drawing, features: one factory each
73
+
74
+ A variation of a widget is a call with options, never a copied file. A widget
75
+ is made of four kinds of fact, and each has one place it is given:
76
+
77
+ - **Look** is CSS over fixed markup. `Recipes.X(selection)` picks values on
78
+ axes, `.extend` adjusts them and `.add` gives a recipe an axis or a value it
79
+ lacks ([Recipes](#recipes)).
80
+ - **State** is a Model and the Messages that change it, and it is the
81
+ application's: `X.init` and `X.update` for the widgets that keep interaction
82
+ state, folded by hand or placed as `Bundles.X`. The value a user chose stays
83
+ in the application's Model, unless its type is the widget's own (a
84
+ Calendar's selection).
85
+ - **Drawing** is markup, ARIA, events and words. `X.view(options, h)` draws,
86
+ and `X.configure({ base, presets })` returns a `view` with the options that
87
+ never change at a call site given once. Fixed text is `words`, an object of
88
+ strings with `{blanks}` (`'Remove {tag}'`), never a function.
89
+ - **Features** are code most pages never need: another widget, a Behavior
90
+ with a Mount, a second way to choose. A feature is a value the application
91
+ imports and passes (`fluid: Table.fluid`, `kind: Chart.bars`,
92
+ `choice: Combobox.many(items)`), so a page that never names it never ships
93
+ it. A boolean that switches code on is the one thing an option is not.
94
+
95
+ An option is therefore one of three things: **data** (text, a Message, an
96
+ `Html` you drew, a function you wrote), **a passed value** (a feature, above),
97
+ or **composition** (a widget with state of its own, placed beside this one and
98
+ drawn into a slot option such as `aside`, `footer`, `trailing` or `content`).
85
99
 
86
- ## When to use it
100
+ ```ts standalone
101
+ import type { Html, HtmlBuilder } from 'foldkit/html'
102
+ import { defineMessageUnion } from 'foldkit/message'
103
+ import { Style } from 'foldkit-mixins'
104
+ import { Recipes, Table, TableSlots } from 'foldkit-mixins-ui'
87
105
 
88
- Use this package when:
106
+ const Message = defineMessageUnion({ Noop: {} })
107
+ type Message = typeof Message.Type
89
108
 
90
- - you already use `@foldkit/ui`;
91
- - the component exposes a consumer render seam such as `toView`;
92
- - you want reusable styling, ARIA decoration, analytics, or element-level
93
- behavior around that component;
94
- - you want conflicts to be diagnosed rather than resolved by attribute order.
109
+ interface Product {
110
+ readonly name: string
111
+ readonly price: string
112
+ }
95
113
 
96
- Do **not** use it to add application/component state. State belongs in the
97
- component's Submodel or the application Model. A Mixins `Behavior` contributes
98
- element-level attributes and optional Mount behavior; it is not a hidden state
99
- container.
114
+ // Look: compiled once, at module scope.
115
+ const ProductsStyle = Style.forSlots(TableSlots)(Recipes.Table({ density: 'compact' }))
100
116
 
101
- If you are building your own view rather than adapting `@foldkit/ui`, publish
102
- Slots directly with [`foldkit-mixins`](../mixins).
117
+ // Drawing: `fluid` is a passed value, `words` is text with blanks.
118
+ export const products = (rows: ReadonlyArray<Product>, h: HtmlBuilder<Message>): Html =>
119
+ Table.view(
120
+ {
121
+ columns: [
122
+ { header: 'Product', rowHeader: true, value: row => row.name },
123
+ { header: 'Price', numeric: true, value: row => row.price },
124
+ ],
125
+ rows,
126
+ rowKey: row => row.name,
127
+ fluid: Table.fluid,
128
+ words: { selectAll: 'Choose every product' },
129
+ style: ProductsStyle,
130
+ },
131
+ h,
132
+ )
133
+ ```
103
134
 
104
- For Slot / Style / Behavior itself, read [Inside-out view
105
- composition](../../docs/mixins.md) first.
135
+ `Table.configure({ base, presets })` would state `style`, `fluid` and `words`
136
+ once and leave `columns` and `rows` to each call. About fifty widgets have a
137
+ `configure`, and about forty keep state that `Bundles` places; Dialog,
138
+ Popover, Tooltip, HoverIntent and FileDrop stay adapters over `@foldkit/ui`,
139
+ because what they hold is your own content, and have a Bundle for their state
140
+ only. [One factory for each part](#one-factory-for-each-part) shows each with
141
+ code.
106
142
 
107
143
  ## Install
108
144
 
@@ -110,14 +146,14 @@ composition](../../docs/mixins.md) first.
110
146
  pnpm add foldkit-mixins foldkit-mixins-ui foldkit-primitives @foldkit/ui
111
147
  ```
112
148
 
113
- `foldkit`, `effect`, `foldkit-mixins`, `foldkit-primitives` and `@foldkit/ui` are peer dependencies.
149
+ `foldkit`, `effect`, `foldkit-mixins`, `foldkit-primitives` and `@foldkit/ui` are peer dependencies. So is `foldkit-bundle`, which only `Bundles` imports: add it when you place one ([State: fold it by hand, or place a Bundle](#state-fold-it-by-hand-or-place-a-bundle)).
114
150
 
115
151
  ## Sixty seconds: style a Button without copying it
116
152
 
117
153
  Start with a normal `@foldkit/ui` Button. The adapter publishes its consumer
118
154
  attribute bundle as the `button` Slot.
119
155
 
120
- ```ts
156
+ ```ts standalone
121
157
  import type { HtmlBuilder } from 'foldkit/html'
122
158
  import { defineMessageUnion } from 'foldkit/message'
123
159
  import * as UiButton from '@foldkit/ui/button'
@@ -147,39 +183,21 @@ The important line is:
147
183
  toView: Button.toView(mixins, { h }, draw)
148
184
  ```
149
185
 
150
- Conceptually:
151
-
152
- ```text
153
- attributes from @foldkit/ui
154
- +
155
- Style / Behavior mixins
156
- |
157
- v
158
- Button.toView(...)
159
- |
160
- v
161
- draw(resolved slot arrays)
162
- ```
163
-
164
- The caller never copies Button's internal behavior and never has to know how to
165
- merge its handlers/ARIA/structural attributes safely.
166
-
167
- ## Follow the click
186
+ `Button.toView(...)` takes the attributes from `@foldkit/ui` and your Style and
187
+ Behavior mixins, and calls `draw` with the resolved slot arrays.
168
188
 
169
189
  `UiButton.view` builds the component's base attributes, including the click
170
190
  Message, and calls `toView` with them. `Button.toView` applies the style to
171
191
  those attributes and hands the result to `draw`, which puts it on the actual
172
- element with `h.button`. Clicking emits `Saved` to the parent update. The name
173
- `Saved` is just the example's Message name—it does not mean this adapter wrote
174
- anything to storage.
175
-
176
- `toView` performs no I/O and holds nothing: it is a pure function from the
177
- component's bundles to your markup, run on every render.
192
+ element with `h.button`. Clicking emits `Saved` to the parent update. `toView`
193
+ performs no I/O and holds nothing: it is a pure function from the component's
194
+ bundles to your markup, run on every render, and the caller never copies the
195
+ button's behavior or merges its handlers and ARIA by hand.
178
196
 
179
- Start by adding a class. Then add a non-conflicting attribute if needed.
180
- Do not install another `OnClick` to intercept the component: the resolver
181
- rejects competing event owners. Put every resolved bundle on its element,
182
- adding your own attributes beside it where you need them:
197
+ Start by adding a class. Then add a non-conflicting attribute if needed. Do not
198
+ install another `OnClick` to intercept the component: the resolver rejects
199
+ competing event owners. Put every resolved bundle on its element, adding your
200
+ own attributes beside it where you need them:
183
201
 
184
202
  ```ts
185
203
  import * as UiInput from '@foldkit/ui/input'
@@ -199,7 +217,9 @@ const zipInput = (h: HtmlBuilder<Message>) =>
199
217
  )
200
218
  ```
201
219
 
202
- ## `toView` and `resolve`
220
+ ## Core concepts
221
+
222
+ ### `toView` and `resolve`
203
223
 
204
224
  Every component adapter (all but Anchor, which is a Behavior) has both:
205
225
 
@@ -212,18 +232,15 @@ Adapter.resolve(attributes, mixins, { h, input? }) -> the resolved bundles
212
232
  path. It fits a stateless component's `view` and a Submodel's `viewInputs`
213
233
  alike. The Message type comes from `h`, and a Submodel's value type (a
214
234
  RadioGroup's or Tabs' `Value`) from where the `toView` goes, so neither needs
215
- writing out.
235
+ writing out. `input` is whatever attached Style/Behavior callbacks are allowed
236
+ to read (often a Surface's projected Model); leave it out when no Mixin reads one.
216
237
 
217
238
  Every view takes the view's `h` last, as Foldkit's own views do. At runtime it
218
- is the same builder everywhere; its type is the point: it carries the Message
219
- the part of the app being drawn can route (the root's, or a Submodel's own), so
220
- a handler built for another part's Message is a compile error where it is
221
- written. Pass it down as a parameter and never keep it, as Foldkit asks: a
222
- builder kept and used in another frame builds handlers that frame cannot
223
- deliver.
224
-
225
- A button drawn as a button needs no `draw` at all. `Button.view` takes the
226
- label, a style, and `@foldkit/ui`'s own config:
239
+ is the same builder everywhere; its type carries the Message the part of the app
240
+ being drawn can route (the root's, or a Submodel's own), so a handler built for
241
+ another part's Message is a compile error where it is written. Pass it down as a
242
+ parameter and never keep it: a builder kept and used in another frame builds
243
+ handlers that frame cannot deliver.
227
244
 
228
245
  <!-- docs-check standalone
229
246
  import { Schema } from 'effect'
@@ -275,6 +292,127 @@ declare const model: { readonly marks: ReadonlyArray<string> }
275
292
  declare const iconUrl: (name: string) => string
276
293
  -->
277
294
 
295
+ `resolve` is the seam underneath, for bundles already in hand: a view that
296
+ receives a Tabs `render` as its input, or a Calendar whose Mixins read the
297
+ mode it is showing, which is only known once the attributes arrive:
298
+
299
+ ```ts
300
+ import type { CalendarAttributes } from '@foldkit/ui/calendar'
301
+ import { Calendar, CalendarSlots } from 'foldkit-mixins-ui'
302
+
303
+ const CalendarStyle = Style.forSlots(CalendarSlots)({
304
+ root: Style.whenInput<CalendarAttributes['_tag']>(mode => mode === 'Years', Style.class('years')),
305
+ })
306
+
307
+ const resolveCalendar = (attributes: CalendarAttributes, h: HtmlBuilder<Message>) =>
308
+ Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
309
+ ```
310
+
311
+ `resolve` returns the shape the component passed to its render callback with
312
+ the published bundles resolved; values that are not Slots (`animatePanel`,
313
+ `isVisible`, `activeIndex`, `selectedValue`) pass through untouched. Each
314
+ adapter names what it returns (`ResolvedButton<Message>`, `ResolvedInput`,
315
+ `ResolvedDialog`, `ResolvedRadioGroup<Value, Message>`, `ResolvedTabs`,
316
+ `ResolvedCalendar`, `ResolvedMenu` with `ResolvedMenuGroup` and
317
+ `ResolvedMenuItem`, and so on), so a helper that draws part of a component is
318
+ typed without `ReturnType`. `ResolvedTextarea`'s `textarea` bundle is typed for
319
+ `h.textarea`, which refuses `InnerHTML`; the resolver refuses an `InnerHTML` from
320
+ any Mixin, so no cast is needed. Each adapter is both a namespace
321
+ (`Button.toView`, `Button.resolve`) and a flat Slot export (`ButtonSlots`).
322
+
323
+ ### What the resolver protects
324
+
325
+ This package delegates merge semantics to `foldkit-mixins`; it does not
326
+ concatenate arrays. The resolver guarantees that:
327
+
328
+ - component/base attributes survive;
329
+ - `ChildAttribute`s survive by identity, preserving Submodel routing;
330
+ - classes are additive, and inline declarations merge by property;
331
+ - an event or scalar attribute has one owner, so a Behavior cannot silently
332
+ install a competing `OnClick` at a Slot whose component owns the click;
333
+ - structural attributes remain protected;
334
+ - conflicting ownership produces a `DiagnosticError`, never an accidental
335
+ second handler.
336
+
337
+ That is the main reason to use an adapter instead of another `className` or
338
+ `attributes` escape hatch.
339
+
340
+ ### Submodel components remain Submodels
341
+
342
+ Dialog, Popover, Tooltip, Tabs, RadioGroup, Calendar and Menu publish
343
+ `ChildAttribute`s that carry the child state machine's dispatcher. The resolver
344
+ preserves them, so adapting the render seam does not flatten or bypass the child
345
+ boundary. Per-item components return structured groups rather than one flat
346
+ array, and the adapter keeps that shape: one Slot contribution applies to each
347
+ repeated item while every item's base attributes keep their own event ownership.
348
+
349
+ ```text
350
+ Tabs -> { tablist, tabs, activeIndex }
351
+ RadioGroup -> { group, options, selectedValue, hiddenInput }
352
+ Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
353
+ Menu -> { wrapper, button, backdrop, items, scroll, groups, isVisible }
354
+ Toast -> { container, entries }
355
+ Listbox -> { wrapper, button, backdrop, items, scroll, groups, hiddenInputs, isVisible }
356
+ Combobox -> { wrapper, inputWrapper, input, toggleButton, backdrop, items, scroll, groups, hiddenInputs, isVisible }
357
+ ```
358
+
359
+ ## Finding a widget
360
+
361
+ | I need... | Use |
362
+ | --- | --- |
363
+ | a button, toggle button or icon button; a row of them | [Button](#buttons-actions-and-commands), ButtonGroup, [Toolbar](#toolbar) |
364
+ | a command palette | Command in a Dialog |
365
+ | a text field, a textarea, a password, a search box | [Input, Textarea](#text-and-number-fields), PasswordInput, [SearchField](#searchfield) |
366
+ | a number, a one-time code, tags, a copyable value | NumberField, OtpField, TagsInput, InputCopy |
367
+ | a file picker, a drop zone, files that are listed, checked, previewed and sent | [FileInput](#fileinput) (a native picker you own), FileDrop, [FileUpload](#fileupload) |
368
+ | on or off; one of a few; several of a few | Switch, Checkbox, CheckboxGroup, RadioGroup, Segmented |
369
+ | one from a long list; a path through nested options | Select, Listbox, Combobox, Picker, CascadeSelect |
370
+ | a number, a range, a rating, an angle, a color | Slider, NumberField, Rating, AngleSlider, ColorPicker |
371
+ | a date or a range of dates | Calendar, DatePicker |
372
+ | a dialog, a sheet, a docked drawer | [Dialog](#dialog) (with `focusReturn`), Sheet, Drawer |
373
+ | a popover, a tooltip, a hover card, a floating window, a guided tour | Popover, Tooltip, HoverIntent, FloatingPanel, Tour |
374
+ | a menu, a context menu, a menu bar | Menu, Menubar |
375
+ | tabs, site navigation, breadcrumbs, pages, a stepper | Tabs, Nav, Breadcrumb, Pagination, Steps |
376
+ | an app frame, a sidebar, an accordion, a tree | AppShell, Sidebar, Accordion, TreeView |
377
+ | a table, a card, a list row, an avatar | Table, Card, Item, Avatar |
378
+ | an alert, a toast, a progress bar, a loading state | Alert, Toast, Progress, Meter, Spinner, Skeleton |
379
+ | a very long list | VirtualList, WindowList |
380
+ | a chat | ChatMessage, MessageScroller, ThinkingIndicator, ThinkingSteps, Questionnaire |
381
+ | a widget's state placed in my Model without writing its fold | [`Bundles.X`](#state-fold-it-by-hand-or-place-a-bundle) |
382
+ | a widget's look, words and mixins stated once | [`X.configure`](#drawing-configure-once-call-with-what-differs), [`Recipes.X`](#recipes) |
383
+ | my own keyboard shortcut on a widget | [Application key routes](#application-key-routes) |
384
+ | focus that survives removing what had it | [Focus after removal](#focus-after-removal) |
385
+ | a form that submits natively | [Form participation](#form-participation) |
386
+ | a right-to-left page | [Right to left](#right-to-left) |
387
+
388
+ Each group below is a table (the widget, what it is and its call, its recipe
389
+ axes and Slots) and notes on the widgets whose behavior needs more than a line.
390
+ A row says `A small Model` where the widget keeps interaction state for the
391
+ application to place and fold with its `update`; the rest keep nothing. Every
392
+ view takes an optional `style` of its Slots and `mixins` beside it, and `h` last.
393
+ Style the Slots with the matching recipe ([Recipes](#recipes)); hide text with
394
+ `U.srOnly` from `foldkit-mixins/utilities`; name a control with
395
+ `FieldAssociation`, whose derived id `Label.view` takes.
396
+
397
+ Behavior shared by many widgets is described once, in [Mechanisms shared by many
398
+ widgets](#mechanisms-shared-by-many-widgets), and the rows link to it: application
399
+ key routes (`routes`), focus after removal, form participation (`name`),
400
+ right to left (`direction`), exits and reduced motion, the opt-in Mounts
401
+ (`fluid`, `overlayBars`) and the top layer.
402
+
403
+ ## Buttons, actions and commands
404
+
405
+ | Widget | What it is | Recipe and Slots |
406
+ | --- | --- | --- |
407
+ | `Button` | Adapter over `@foldkit/ui`'s Button. `Button.view({ label, style, type?, disabled?, invalid?, busy?, pressed?, icon?, trailing?, description?, mark?, href?, external?, words?, onClick?, attributes?, mixins? }, h)`; `Button.toView` for your own `draw`. `disabled` writes `aria-disabled`, not `disabled`; `pressed` makes it a toggle (`aria-pressed`); an `icon` draws before the label, hidden from assistive technology. A button presses or it is a link: `href` draws an anchor and takes no `type` or `onClick`. | `tone`: `accent` (default), `neutral`, `danger`; `variant`: `solid` (default), `outline`, `ghost`, `primary`, `link`, `icon`; `size`: `xs`, `sm`, `md`, `lg`; `shape: 'square'`. Slots `button`, `icon`, `content`, `description`, `trailing`, `mark`. |
408
+ | `ButtonGroup` | `{ label, items, orientation?, separated? }`. A `role="group"` that joins its items: borders overlap by one and only the outer corners stay round. An item is the caller's button, field or Menu (a wrapper passes the corners to the face it holds), or a string drawn in the `text` box (a count, a field's prefix). `orientation: 'vertical'` stacks them; `separated` draws a rule on every seam, for solid buttons whose fills meet. `Segmented` is the control that selects. | `size` (`sm`, `md`, `lg`, for every item with no size of its own); `width: 'fill'` spans the container, a field taking what the buttons leave. Slots `root`, `separator`, `text`. |
409
+ | `Toolbar` | The APG's toolbar: one tab stop over controls you draw, the arrows along its orientation, Home and End. See [Toolbar](#toolbar). `Toolbar.view({ id, label, items, roving, onFocus, orientation?, direction?, loop?, disabled?, routes? }, h)`. | `size` is Button's ladder step, set on the toolbar. Slots `root`, `group`, `separator`. |
410
+ | `Command` | shadcn's Command and Fluid's CommandMenu: a search field over a list of grouped, filterable rows. `{ id, label, placeholder?, groups, query, onQuery, active, onActive, onRun, loading?, words?, page?, routes?, hints?, kbd? }`. `Command.configure({ base, presets })` fixes the placeholder, words, hints, `kbd`, style and mixins once. See [Command](#command). | `frame`: `card` (default) or `bare`, for inside a dialog. Slots `root`, `search`, `crumbs`, `crumb`, `input`, `list`, `group`, `heading`, `item`, `icon`, `text`, `label`, `description`, `shortcut`, `chevron`, `status`, `empty`, `loading`, `frame`, `bar`, `thumb`, `footer`, `hint`. |
411
+ | `Kbd` | `{ key }` names a key, as text or as a drawing (an arrow, a modifier's glyph; it carries its own label); `Kbd.combo({ keys, joiner? }, h)` draws several in one `kbd`. | No axis. Slots `key`, `combo`, `joiner`. |
412
+
413
+ A button drawn as a button needs no `draw` at all. `Button.view` takes the
414
+ label, a style, and `@foldkit/ui`'s own config:
415
+
278
416
  ```ts
279
417
  import { Button } from 'foldkit-mixins-ui'
280
418
 
@@ -297,21 +435,165 @@ form, on Enter or a press: refuse the submit in `update` while it should not
297
435
  go.
298
436
 
299
437
  `attributes: { button?, icon? }` adds what another component hands a slot,
300
- after the button's own: a Dialog's `initialFocus`, so the dialog opens on
301
- that button (`attributes: { button: dialog.initialFocus }`). A class among
302
- them replaces the button's, as a later attribute list does.
438
+ before the mixins resolve, as `PasswordInput.view`'s do: a Dialog's
439
+ `initialFocus`, so the dialog opens on that button (`attributes: { button:
440
+ dialog.initialFocus }`). A class among them joins the style's, and an event or
441
+ attribute a mixin owns is a conflict. `Recipes.Button({ variant: 'icon' })`
442
+ shows the icon alone, the label still the button's name; `shape: 'square'` draws
443
+ any other variant as that square (an outlined icon button in a toolbar). A toggle
444
+ button, shadcn's Toggle, is a Button with `pressed`, and each variant has its on
445
+ look.
446
+
447
+ `trailing` draws after the label (a chevron, a count, a `Kbd.combo`); it is read as
448
+ drawn, so a decorative one carries its own `aria-hidden`. `description` is a second line
449
+ under the label, and both name the button. `mark` is a Badge or a dot on the button's
450
+ corner, on the end side whatever the writing direction. `invalid` writes `data-invalid` and
451
+ turns the button's colours to the danger tone: not `aria-invalid`, which a button's role
452
+ does not take, so the reason is text the application draws. `busy` writes `aria-busy` and
453
+ `data-busy`, and a press does nothing while it is on (a `type: 'submit'` button stops
454
+ submitting too); it stays focusable. There is no `loading` option that draws a spinner,
455
+ since that would put Spinner in every page that draws a button: compose
456
+ `icon: Spinner.view(...)`. `href` draws an anchor with the button's look; `external` opens
457
+ a new tab and says so (`words.external`, default `'Opens in a new tab'`), and a disabled
458
+ link has no `href`. `Recipes.Button({ variant: 'link' })` is the look of a link in running
459
+ text; `size: 'xs'` is a step below `sm`.
460
+
461
+ ### Toolbar
462
+
463
+ A `Toolbar` is one tab stop over a row of controls you draw. It owns the keys
464
+ (the arrows along its orientation, Home and End) and hands each control the
465
+ attributes of its stop; you own which control holds the stop, so Tab comes back
466
+ to the control focused last, and you draw the controls. `Toolbar.view` draws
467
+ the toolbar and does no I/O; focus moves in the browser, and `onFocus` reports
468
+ where it went.
469
+
470
+ `items` are, in order, controls `{ id, disabled?, draw }`, where `draw`
471
+ receives `{ attributes, disabled }` and puts `attributes` (the id, the
472
+ `tabindex` and a focus report) on the one focusable element and draws it off when
473
+ `disabled`; groups `{ label, controls, disabled? }`, a named `role="group"`; and
474
+ the word `'separator'`, a rule between sets. `roving` is a placed
475
+ `RovingTabindex`'s slice (`{ current }`) and `onFocus(id)` is answered with its
476
+ `Focused`. A disabled control (its own, its group's, or the toolbar's) is skipped
477
+ by the arrows and never holds the tab stop; `Toolbar.controlId(toolbarId, id)` is
478
+ the id a control draws, for a Command that focuses it. A focused text field,
479
+ textarea, select or range keeps the keys it uses, so the arrows leave a text field
480
+ only from the edge they point at: place a field last, or leave it with Tab. A key
481
+ pressed in something the toolbar did not draw, such as a menu's rows, is left to
482
+ it.
483
+
484
+ ```ts
485
+ import { Toolbar, ToolbarSlots } from 'foldkit-mixins-ui'
486
+
487
+ const BarModel = Schema.Struct({ stop: Schema.NullOr(Schema.String), bold: Schema.Boolean })
488
+ const BarMessage = defineMessageUnion({ Focused: { id: Schema.String }, ToggledBold: {} })
489
+ type BarMessage = typeof BarMessage.Type
303
490
 
304
- An `icon` (an `svg`) draws before the label in the `icon` slot, hidden from
305
- assistive technology; `Recipes.Button({ variant: 'icon' })` shows the icon
306
- alone, the label still the button's name. `shape: 'square'` draws any other
307
- variant as that square (an outlined icon button in a toolbar).
491
+ const BarStyle = Style.forSlots(ToolbarSlots)(Recipes.Toolbar({}))
492
+ const ToolStyle = Style.forSlots(ButtonSlots)(
493
+ Recipes.Button({ tone: 'neutral', variant: 'outline' }),
494
+ )
308
495
 
309
- A toggle button, shadcn's Toggle, is a Button with `pressed`: it writes
310
- `aria-pressed`, and each variant has its on look.
496
+ const barView = (model: typeof BarModel.Type, h: HtmlBuilder<BarMessage>) =>
497
+ Toolbar.view(
498
+ {
499
+ id: 'format',
500
+ label: 'Formatting',
501
+ roving: { current: model.stop },
502
+ onFocus: id => BarMessage.Focused({ id }),
503
+ items: [
504
+ {
505
+ id: 'bold',
506
+ draw: control =>
507
+ Button.view(
508
+ {
509
+ label: 'Bold',
510
+ pressed: model.bold,
511
+ onClick: BarMessage.ToggledBold(),
512
+ attributes: { button: control.attributes },
513
+ style: ToolStyle,
514
+ },
515
+ h,
516
+ ),
517
+ },
518
+ 'separator',
519
+ {
520
+ id: 'link',
521
+ disabled: true,
522
+ draw: control =>
523
+ Button.view(
524
+ {
525
+ label: 'Link',
526
+ disabled: control.disabled,
527
+ attributes: { button: control.attributes },
528
+ style: ToolStyle,
529
+ },
530
+ h,
531
+ ),
532
+ },
533
+ ],
534
+ style: BarStyle,
535
+ },
536
+ h,
537
+ )
538
+ ```
311
539
 
312
- An input or a textarea places its own bundles, so its `view` takes a `draw`.
313
- `Input.view` and `Textarea.view` take the value and Messages, a style, and
314
- `@foldkit/ui`'s own config (`type` and `placeholder`, `rows` for a textarea):
540
+ `roving` is the `{ current }` slice of a `RovingTabindex`: kept by hand here, or placed
541
+ as `Bundles.Toolbar` (`Bundle.withChild('bar', Bundles.Toolbar, { args: { current? } })`),
542
+ whose Model is passed as `roving` and whose Message `Toolbar.focused(wrap)` builds for
543
+ `onFocus`: `onFocus: Toolbar.focused(message => GotBar({ message }))`. Otherwise
544
+ `onFocus(id)` is answered by setting it. `Toolbar.configure({ base, presets })` returns a
545
+ `view` with `orientation`, `direction`, `loop` and the look given once, as every
546
+ `configure` does. `control.attributes` goes on the one focusable element, and `control.disabled`
547
+ says to draw it off: the arrows skip it. `routes` are
548
+ [application key routes](#application-key-routes) whose `input` is `undefined`.
549
+
550
+ ### Command
551
+
552
+ The field points at the highlighted row through `aria-activedescendant`; ↑ and ↓
553
+ wrap through enabled rows, PageUp and PageDown move the highlight ten rows and
554
+ stop at the ends, Enter runs the highlighted one, and Home and End stay the
555
+ field's caret keys. Rows never re-sort, and a filtered-away highlight moves to
556
+ the first enabled row. A row is `{ value, label, description?, keywords?,
557
+ shortcut?, icon?, opensPage?, disabled? }`; a `shortcut` is a tuple of keys
558
+ (`['⌘', 'K']`) drawn as Kbd with `kbd` and reads left to right on a right-to-left
559
+ page. `page: { trail, onBack }` draws the pages stepped into as crumbs before the
560
+ field, and Backspace in an empty field sends `onBack`; a row with `opensPage` has
561
+ a chevron. `loading: true` says `words.loading` and marks the list
562
+ `aria-busy`, its rows still shown, and a list nothing matches says `words.empty`
563
+ (`Command.words` are the defaults, `Loading…` and `No results.`); `hints` are a
564
+ footer of keys.
565
+
566
+ `Command.hotkey(message)` is ⌘K or Ctrl+K anywhere, for an application to lift
567
+ with `Subscription.persistentEntry` and open its Dialog on; `Command.filtered(groups,
568
+ query)` is what a query leaves. `Command.keepActiveInView` beside the style
569
+ scrolls the highlighted row into view as the keys move it; like the other Mounts
570
+ that send no Message it is a mixin, off by default. The list stands in a `frame`
571
+ beside its bar, which `Command.overlayBars` drives (see [Overlay scroll
572
+ bars](#overlay-scroll-bars)). `routes` are [application key
573
+ routes](#application-key-routes) whose `handle` reads a `CommandKeyInput` of the
574
+ query, the highlighted row and the rows the keys step through.
575
+
576
+ ## Text and number fields
577
+
578
+ | Widget | What it is | Recipe and Slots |
579
+ | --- | --- | --- |
580
+ | `Input` | Adapter over `@foldkit/ui`'s Input. `Input.view({ id, value, onInput, type?, placeholder?, name?, readOnly?, required?, autocomplete?, inputMode?, maxLength?, disabled?, invalid?, attributes?, style, label, description?, labelAside?, start?, end? }, h)` draws the field; with `draw` in place of `label` the application places the bundles; `Input.field` draws a whole field from a `FieldValidation.Field`. | `size`: `sm`, `md`, `lg`; `variant`: `outline` (default), `filled`, `ghost`, `underline`. Slots `input`, `label`, `description`, `root`, `header`, `labelAside`, `group`, `start`, `end`. |
581
+ | `Textarea` | `Textarea.view` takes the same and `rows`, `maxRows`, `maxLength`, `count`; `Textarea.field` is the whole field. | `size` and `variant` as Input's; `resize`: `auto` (default), `vertical`, `none`. Slots `textarea`, `label`, `description`, `count`, `frame`, `footer`, `meta`. |
582
+ | `PasswordInput` | `PasswordInput.view({ id, label, value, onInput, visible, onToggle, autocomplete?, description?, labelAside?, start?, end?, words?, invalid?, disabled?, name?, required?, attributes? }, h)`: a password field whose toggle (`aria-pressed`, `aria-controls`, one fixed name) shows it as text. `autocomplete` is `current-password` (default) or `new-password`; spellcheck and autocorrect stay off. `strength` is a gauge the app draws (`Meter.view(…, h)`) under the field, so a page with none ships no Meter; `requirements` are `{ label, met }[]` (`PasswordRequirement`), each read as met or not (`words.met`, `words.unmet`); `capsLock: { on, onKey }` says Caps Lock is on, politely, `onKey` given `capsLockOf(key, modifiers)` for each key (an `Option`). The application owns the text; the flag and the Caps Lock reading are the field's own small Model (`PasswordInput.init`, `update`, `Bundles.PasswordInput`), handed to the view by `...PasswordInput.controls(model, onMessage)`. `words`: `toggle`, `capsLock`, `met`, `unmet`. | `size` (`sm`, `md`, `lg`). Input's pieces in InputGroup's box; the eye is `Icons.glyph` by `aria-pressed`. Slots `root`, `label`, `header`, `labelAside`, `group`, `start`, `end`, `input`, `toggle`, `description`, `strength`, `requirements`, `requirement`, `requirementState`, `capsLock`. |
583
+ | `SearchField` | A native `type="search"` input named by `label`, with a clear button only while there is text. `SearchField.view({ id, label, value, onInput, clear?: { onClear, content? }, start?, end?, busy?, placeholder?, invalid?, disabled?, words?, routes?, style?, mixins? }, h)`. See [SearchField](#searchfield). | `size` and `variant` (`outline`, `filled`, `ghost`, `underline`) are Input's axes. One box (`group`) with a magnifier in `start` while it is empty, the clear button after the input (mirrored right to left), the browser's own cancel button hidden. Slots `root`, `group`, `start`, `end`, `input`, `clear`. |
584
+ | `NumberField` | The APG's editable spinbutton. `{ id, label, description?, value, onChange, min?, max?, step?, page?, locale?, name?, required?, disabled?, invalid?, readOnly?, start?, end?, words? }`, or `format` with `parse` in place of `locale`. `value` is an `Option<number>`: none is an empty field (no `aria-valuenow`, the steppers start from the bounds), and clearing the text sends `onChange(Option.none())`. `NumberField.parseNumber(text, locale?)` reads text as that locale writes a number; `NumberField.settled(value, bounds)` clamps onto the step. | `steppers`: `split` (default: a button at each side of the number), `end` (both after it) or `none`. Slots `root`, `label`, `group`, `start`, `end`, `input`, `decrement`, `increment`, `description`. `invalid` draws the error edge and marks the input; `readOnly` leaves it readable and selectable with its steppers disabled; `words` (`decrease`, `increase`) names the steppers; `start` and `end` go around the number inside the box. |
585
+ | `OtpField` | shadcn's input-otp: one real input (`autocomplete="one-time-code"`, paste and Backspace the browser's) over cells that mirror it, the next marked `data-next`. `{ id?, name?, label, value, onChange, length?, pattern?, groups?, mask?, disabled?, readOnly?, invalid? }` (`mask: true` makes the input a password field and shows a dot in each filled cell, or the string given); `OtpField.kept(text, length, pattern)` filters a code. | No axis. Slots `root`, `input`, `group`, `cell`, `separator`. |
586
+ | `TagsInput` | Zag's tags input. A small Model: `TagsInput.init({ id, tags?, delimiter?, max? })`, folded with `TagsInput.update` (which returns a focus Command). `TagsInput.view({ model, onMessage, label, placeholder?, name?, disabled?, direction?, addOnBlur?, routes?, words? }, h)`. See [TagsInput](#tagsinput). | No axis; `data-disabled` on `control`. Slots `root`, `label`, `control`, `list`, `tag`, `remove`, `input`, `message`, `hiddenInput`. |
587
+ | `InputCopy` | A read-only value with a copy button (Zag's clipboard). A small Model for the copied and failed marks. `InputCopy.view({ id, label, value, copied, failed?, onCopy, words?, copyContent?, start?, end? }, h)`; `Bundles.InputCopy` (args `{ resetAfter? }`) packages the Model. `words`: `copy`, `copied`, `failed`. `copyContent` is drawn in the button in place of its words, which stay in it for a screen reader. | No axis. Slots `root`, `label`, `group`, `start`, `end`, `input`, `button`, `buttonText`, `status`. |
588
+ | `Label` | `{ for, text, required?, optional?, disabled?, invalid?, trailing?, words? }`: a `label` that names a control by `for` (the id `FieldAssociation` derived). `required` draws a star the screen reader skips and `optional` the words `(optional)` that are read, after the text (`words`: `required`, `optional`); a field is one or the other. `disabled` and `invalid` mark the label (`data-disabled`, `data-invalid`) and do nothing to the control. `trailing` stands beside the label in a row with it, not inside it. | No axis. Slots `label`, `marker`, `trailing`, `root`. |
589
+ | `Field` | The shell around a control you drew: `Field.view({ id, label, control, description?, errors?, required? or optional?, orientation?, labelAside?, words?, style? }, h)`. The label names the control by `id`; `required` draws a mark hidden from a reader, `optional` words that are read (`words`: `required`, `optional`); `errors` are lines in an alert under the control; `orientation` is `vertical` (default) or `horizontal`. The control is drawn first, so it cannot know the shell's ids: give it `Field.describedBy(h, id, { description, errors })` as attributes. The shell owns no state. | Slots `root`, `header`, `label`, `marker`, `labelAside`, `control`, `description`, `errors`, `error`. `data-orientation` and `data-invalid` are on `root`. |
590
+ | `Fieldset` | Adapter: a `fieldset`, its `legend` and a `description`. `Fieldset.view({ id, legend, content, description?, disabled?, style?, mixins? }, h)` draws it with the `content` you drew; `toView` stays for one drawn as something else. | `variant`: `plain` (default, no box), `bordered`, `filled`. The recipe floats the legend into the group, so a box drawn round it holds the legend; a boxed group pads its fields, and a control in it takes a corner concentric with the box's; a disabled fieldset dims its legend and description. Slots `fieldset`, `legend`, `description`. |
591
+ | `FileInput` | A file picker, not a drop zone: a native `type="file"` input and the button that labels it. The application owns the files. See [FileInput](#fileinput). | `size` is Button's ladder step. Slots `root`, `input`, `trigger`, `description`, `list`, `item`, `name`, `remove`. |
592
+ | `FileUpload` | A field of files with a status each: a native `type="file"` input and the picker that labels it (`layout`: `button`, `zone`, `avatar`, `cover`), drop, previews, refusals, lanes for sending, `parts` for a layout of your own. A small Model: `FileUpload.Model`, `init`, `update`, placed by the application. See [FileUpload](#fileupload). | `layout`; `list`: `rows` (default), `grid`; `size` is Button's ladder step. Slots `root`, `input`, `picker`, `prompt`, `browse`, `constraints`, `description`, `picture`, `status`, `errors`, `error`, `summary`, `clear`, `list`, `item`, `preview`, `name`, `meta`, `state`, `progress`, `actions`, `retry`, `remove`, `grip`. |
593
+ | `FileDrop` | Adapter over `@foldkit/ui/fileDrop`: a drop zone. `FileDrop.Message` is upstream's four Messages over a `File` codec that needs no decoding services (upstream types its files as `Schema<File>`, whose services are `unknown`, so a Message holding it could not be a `Bundle.parent`'s); `FileDrop.update` of upstream takes it as it is. `Bundles.FileDrop` places upstream's Model with `{ id }` as its args and reports a drop in `onOut` as `FileDrop.OutMessage`, `ReceivedFiles { files }` or `RejectedNonFiles`; draw the placed Model through `h.submodel` with upstream's `view` and `FileDrop.toView`. | The recipe rings the zone while its input has keyboard focus (a press does not) and dims a disabled one. Slots `root`, `input`. |
594
+
595
+ `Input.view` and `Textarea.view` place their own bundles, so each takes a
596
+ `draw`:
315
597
 
316
598
  ```ts
317
599
  import { Input } from 'foldkit-mixins-ui'
@@ -331,67 +613,54 @@ const emailField = (value: string, h: HtmlBuilder<Message>) =>
331
613
  )
332
614
  ```
333
615
 
334
- A closure is not data, so a page that answers before its script runs
335
- (`foldkit-ssr`'s [resumable pages](https://github.com/doeixd/foldkit-plus/blob/main/packages/ssr/README.md#resumable-pages-answering-before-the-runtime-boots))
336
- cannot write it into the server's markup. There, give `onInput` the
337
- `OnInput` attribute the resumable builder makes from a Message member; the
338
- view adds it as it would the closure, and `KeepTyped` keeps what is typed
339
- before the script runs:
616
+ Given a `label` instead of a `draw`, `Input.view` draws the field itself: the
617
+ label, the control, and the `description` under it, linked to it. `start` and
618
+ `end` are drawn inside the field's box beside the control, and `labelAside`
619
+ stands beside the label, not inside it:
340
620
 
341
621
  ```ts
342
- import { Resume } from 'foldkit-ssr/client'
622
+ import { Input } from 'foldkit-mixins-ui'
343
623
 
344
- const resumableEmail = (value: string, h: HtmlBuilder<Message>) => {
345
- const rh = Resume.builder(h)
346
- return Input.view(
624
+ const siteField = (value: string, h: HtmlBuilder<Message>) =>
625
+ Input.view(
347
626
  {
348
- id: 'email',
627
+ id: 'site',
628
+ label: 'Website',
629
+ description: 'Without the scheme.',
349
630
  value,
350
- onInput: rh.OnInput(Message.TypedEmail),
351
- type: 'email',
352
- draw: ({ input, label }) =>
353
- rh.div([], [rh.label(label, ['Email']), rh.input([...input, rh.KeepTyped()])]),
631
+ onInput: value => Message.TypedTitle({ value }),
632
+ start: h.span([], ['https://']),
633
+ end: h.span([], ['.com']),
634
+ style: FieldStyle,
354
635
  },
355
- rh,
636
+ h,
356
637
  )
357
- }
358
638
  ```
359
639
 
360
- `PasswordInput` draws its own input, so `KeepTyped` goes in its
361
- `attributes`, which adds to a Slot before the mixins resolve. Give it only
362
- while the field is enabled: a disabled field sends nothing, and the server
363
- refuses a kept field with nothing to replay (`UnkeepableField`).
364
-
365
- ```ts
366
- import { PasswordInput } from 'foldkit-mixins-ui'
367
-
368
- const resumablePassword = (password: string, shown: boolean, h: HtmlBuilder<Message>) => {
369
- const rh = Resume.builder(h)
370
- return PasswordInput.view(
371
- {
372
- id: 'password',
373
- label: 'Password',
374
- value: password,
375
- onInput: rh.OnInput(Message.TypedPassword),
376
- visible: shown,
377
- onToggle: Message.ToggledPassword(),
378
- attributes: { input: [rh.KeepTyped()] },
379
- },
380
- rh,
381
- )
382
- }
383
- ```
640
+ The box is the `group` Slot (`data-field-group`): it carries the border, the
641
+ focus ring while the control has focus, and the dimming of a disabled field,
642
+ and the control inside goes borderless. With neither `start` nor `end` no group
643
+ is drawn and the control keeps its own border. SearchField, PasswordInput,
644
+ InputCopy and NumberField take the same two options. `variant` is `outline`,
645
+ `filled`, `ghost` or `underline`.
646
+
647
+ Beyond `type` and `placeholder`, `Input.view` takes `name`, `readOnly`, `required`,
648
+ `autocomplete`, `inputMode` and `maxLength`, so a form that submits natively needs
649
+ no hand-drawn `input`, and `attributes: { input?, label?, description? }` adds
650
+ what another component hands a slot (a blur handler, `aria-busy`) before the
651
+ mixins resolve. `Textarea.view` takes `name`, `required`, `autocomplete` and
652
+ `attributes` the same way. A field's description (`Input.field`'s and
653
+ `Textarea.field`'s) is an always-drawn `role="status"` span, even with nothing to
654
+ say, since a live region announces only what is put into it.
384
655
 
385
656
  `Input.field` and `Textarea.field` draw a whole field from a
386
657
  `FieldValidation.Field`: the value, its first error or checking mark as the
387
658
  description, and `aria-invalid` where the field is invalid. `changed` maps the
388
659
  typed value to a Message; `label` is the text over the control; and `draw`
389
- places the resolved `label`, `control`, and `description` bundles (the default
660
+ places the resolved `label`, `control` and `description` bundles (the default
390
661
  stacks them):
391
662
 
392
663
  ```ts
393
- import { Input } from 'foldkit-mixins-ui'
394
-
395
664
  const titleField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message>) =>
396
665
  Input.field(
397
666
  { id: 'title', label: 'Title', field, changed: value => Message.TypedTitle({ value }) },
@@ -399,17 +668,18 @@ const titleField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message
399
668
  )
400
669
  ```
401
670
 
402
- A textarea also takes what more than one line wants. The recipe's `resize` is
403
- how it changes size: `auto` (the default) grows with its text from `rows`
404
- lines (two unless given) to `maxRows`, then scrolls; `vertical` stays `rows`
405
- lines tall and the reader drags it; `none` holds it. A `maxLength` caps the
406
- text and counts toward it under the field, in the warning's ink from nine
407
- tenths and the error's at the limit, and the count describes the textarea.
408
- A `footer` draws the field as one box, a row of controls under the text and
409
- the count at its end:
671
+ ### Textarea
672
+
673
+ A textarea also takes what more than one line wants. The recipe's `resize` is how
674
+ it changes size: `auto` (the default) grows with its text from `rows` lines (two
675
+ unless given) to `maxRows`, then scrolls; `vertical` stays `rows` lines tall and
676
+ the reader drags it; `none` holds it. A `maxLength` caps the text and counts
677
+ toward it under the field, in the warning's ink from nine tenths and the error's
678
+ at the limit, and the count describes the textarea. A `footer` draws the field as
679
+ one box, a row of controls under the text and the count at its end:
410
680
 
411
681
  ```ts
412
- import { Button, Textarea } from 'foldkit-mixins-ui'
682
+ import { Textarea } from 'foldkit-mixins-ui'
413
683
 
414
684
  const replyField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message>) =>
415
685
  Textarea.field(
@@ -428,490 +698,1926 @@ const replyField = (field: FieldValidation.Field<string>, h: HtmlBuilder<Message
428
698
  )
429
699
  ```
430
700
 
431
- `Textarea.view` takes the same `rows`, `maxRows`, `maxLength`, and `count`,
432
- and hands `draw` the `count`, `frame`, `footer` and `meta` bundles to place;
433
- `Textarea.countOf(value, maxLength)` is the count's text. `resize: 'auto'`
434
- rests on CSS `field-sizing`, which sizes the width by the text too where
435
- nothing else gives one (it keeps at least 20 columns); a browser without it
436
- keeps the textarea at its fewest lines, scrolling.
701
+ `Textarea.view` takes the same `rows`, `maxRows`, `maxLength` and `count`, and
702
+ hands `draw` the `count`, `frame`, `footer` and `meta` bundles to place;
703
+ `Textarea.countOf(value, maxLength)` is the count's text. `resize: 'auto'` rests
704
+ on CSS `field-sizing`, which sizes the width by the text too where nothing else
705
+ gives one (it keeps at least 20 columns); a browser without it keeps the
706
+ textarea at its fewest lines, scrolling.
707
+
708
+ ### SearchField
709
+
710
+ A native `type="search"` input (role `searchbox`) named by `label`, since a
711
+ search field wears no visible label, and a clear button drawn only while there is
712
+ text. The view keeps nothing: the application owns the text, `onInput` reports
713
+ typing, and `clear: { onClear, content? }` is what the button and Escape send; a
714
+ field given no `clear` has neither. `content` is drawn in the button in place of
715
+ the cross. Escape acts only on a
716
+ field with text, so on an empty one it still reaches an enclosing dialog.
717
+ `start` and `end` are drawn inside the field's box beside the input (a field
718
+ with no `start` draws a magnifier there), and `busy` sets `aria-busy` and
719
+ `data-busy` while a search runs: compose a spinner into `end`.
720
+ Pressing the button removes it and the focus it held, so answer `onClear` with the
721
+ `SearchField.Focus({ id })` Command, which puts focus back on the input and
722
+ answers `SearchField.Message.CompletedFocus` (`SearchField.inputId(id)` is the
723
+ input's id). `words: { clear? }` renames the button (default `Clear search`). A
724
+ disabled field takes no text or keys and draws no button. `routes` are
725
+ [application key routes](#application-key-routes) whose `input` is the field's
726
+ text.
437
727
 
438
- `resolve` is the seam underneath, for bundles already in hand: a view that
439
- receives a Tabs `render` as its input, or a Calendar whose Mixins read the
440
- mode it is showing, which is only known once the attributes arrive:
441
728
  ```ts
442
- import type { CalendarAttributes } from '@foldkit/ui/calendar'
443
- import { Calendar, CalendarSlots } from 'foldkit-mixins-ui'
444
-
445
- const CalendarStyle = Style.forSlots(CalendarSlots)({
446
- root: Style.whenInput<CalendarAttributes['_tag']>(mode => mode === 'Years', Style.class('years')),
729
+ import { Option } from 'effect'
730
+ import { Behaviors } from 'foldkit-mixins'
731
+ import { SearchField, SearchFieldSlots } from 'foldkit-mixins-ui'
732
+
733
+ const Search = defineMessageUnion({
734
+ Typed: { text: Schema.String },
735
+ Cleared: {},
736
+ OpenedResults: {},
447
737
  })
738
+ type Search = typeof Search.Type
448
739
 
449
- const resolveCalendar = (attributes: CalendarAttributes, h: HtmlBuilder<Message>) =>
450
- Calendar.resolve(attributes, [CalendarStyle.mixin], { input: attributes._tag, h })
451
- ```
452
-
453
- ## What `resolve` does
454
-
455
- `resolve(attributes, mixins, { input, h })` receives the shaped value the
456
- component passed to its render callback and returns the same shape with published
457
- attribute bundles resolved through Mixins.
740
+ const { Keys } = Behaviors
458
741
 
459
- For a simple Button:
742
+ // ArrowDown opens the results, but only once there is text to search for.
743
+ const openResults: SearchField.Route<Search> = Keys.route('Open results', {
744
+ on: [Keys.chord('ArrowDown')],
745
+ handle: ({ input }) => (input === '' ? Option.none() : Option.some(Search.OpenedResults())),
746
+ })
460
747
 
461
- ```text
462
- { button: baseAttributes }
463
- |
464
- v
465
- Button.resolve(...)
466
- |
467
- v
468
- { button: resolvedAttributes }
748
+ const searchView = (text: string, h: HtmlBuilder<Search>) =>
749
+ SearchField.view(
750
+ {
751
+ id: 'find',
752
+ label: 'Search products',
753
+ value: text,
754
+ onInput: text => Search.Typed({ text }),
755
+ clear: { onClear: Search.Cleared() },
756
+ routes: [openResults],
757
+ style: Style.forSlots(SearchFieldSlots)(Recipes.SearchField({})),
758
+ },
759
+ h,
760
+ )
469
761
  ```
470
762
 
471
- For richer components, non-slot values pass through untouched. Values such as
472
- `animatePanel`, `isVisible`, `activeIndex`, or `selectedValue` remain component
473
- data rather than becoming Mixins slots.
763
+ The search `update` answers `Cleared` with `SearchField.Focus({ id: 'find' })`.
764
+
765
+ ### TagsInput
766
+
767
+ The tags are a list of chips named by the label, each with a `Remove <tag>`
768
+ button (`words.remove` names it, `words.mark` is its `×`), then a text input. Enter or the
769
+ delimiter (default `,`) adds the draft split at the delimiter and trimmed,
770
+ refusing empty and repeated parts and parts past `max`: a refusal
771
+ (`TagsInput.Refusal`: `Repeat`, `Empty`, `Full`) is said in a polite `message`
772
+ (worded by `words.repeat`, `words.empty` and `words.full`) and shakes the field
773
+ once, the shake travel-aware. Words are text with blanks, `{tag}` and `{max}`;
774
+ `TagsInput.words` holds the English defaults and `words` takes any of them.
775
+ `addOnBlur` adds the draft when the input loses focus (off by default).
776
+
777
+ Backspace in an empty input removes the last tag (`Message.BackspacedEmpty`, sent
778
+ only when the input itself holds no text, so text typed since the last frame is
779
+ edited, not skipped). The chips are one roving tab stop (`Model.chip`, set by
780
+ `Message.FocusMoved`): ArrowLeft and ArrowRight, swapped by `direction: 'rtl'`,
781
+ move among them, Home and End go to the ends, Backspace and Delete remove the
782
+ focused one, ArrowRight past the last returns to the input, and ArrowLeft from the
783
+ start of the input's text, with nothing selected, enters the last chip. A removal,
784
+ by button or key, focuses the chip that takes its place, else the one before it,
785
+ else the input, through the Command `update` returns. The input's keys are
786
+ `Behaviors.Keys` routes; `routes` adds the application's, and one on Enter, the
787
+ delimiter or Backspace is a `mixins:key-conflict`. With `name`, one hidden input
788
+ per tag, so a form submits the tags and not the draft.
789
+
790
+ ### FileInput
791
+
792
+ A `FileInput` is a native file input and the button that labels it, so a press on
793
+ the button and Enter or Space on the focused input open the browser's dialog with
794
+ no script. The application owns the chosen files, `File`s compared by identity:
795
+ fold a pick in with `FileInput.added(files, picked, { multiple })` (a single field
796
+ takes the newest pick, `multiple` appends and skips a file already held by name,
797
+ size, type and modification time), and answer `onChange` and `onRemove` with the
798
+ `FileInput.Sync({ id, files })` Command, which writes the list back into the input
799
+ so a surrounding form submits exactly the list shown (Foldkit empties the input
800
+ after each pick; an empty list resets its value, so a removed file can be chosen
801
+ again). Answer `onRemove` with `FileInput.Focus({ id })` as well, which puts focus
802
+ on the input, since the button that held it left with its row, as
803
+ `SearchField.Focus` does; both answer `CompletedSync` and `CompletedFocus`, which
804
+ `...FileInput.cases` adds to your Message union (a missing one is a type error where
805
+ you return the Command). Each row has a `remove` button named `Remove {name}` (`words: {
806
+ remove? }`). `name`, `accept`, `multiple` and `required` are the native
807
+ attributes; `invalid` is `aria-invalid`, and `description` is read after the name.
808
+ A disabled field takes no pick and its rows no remove.
809
+
810
+ Keeping the `File`s in the Model or a Message (`Schema.instanceOf(File)`) has a cost under
811
+ `vite dev`: a `File` is not JSON, and Foldkit's dev-tools relay, which exists only where
812
+ `import.meta.hot` does, has been seen to reject with `SchemaError: Expected JSON value` as an
813
+ unhandled rejection. A production build has no relay; a test that fails on page errors (an
814
+ end-to-end run against `vite dev`) should expect it.
474
815
 
475
- `input` is whatever attached Style/Behavior callbacks are allowed to read. In a
476
- feature view that is often the Surface's projected Model; leave it out when no
477
- attached Mixin reads one.
478
-
479
- What `resolve` returns (and `draw` receives) has a name for each adapter:
480
- `ResolvedButton<Message>`, `ResolvedInput<Message>`, `ResolvedDialog<Message>`,
481
- `ResolvedRadioGroup<Value, Message>` and `ResolvedRadioOption<Value, Message>`,
482
- `ResolvedTabs<Value, Message>`, `ResolvedCalendar<Message>`,
483
- `ResolvedMenu<Message>` (with `ResolvedMenuGroup`/`ResolvedMenuItem` per
484
- entry), and so on, so a
485
- helper that draws part of a component can be typed without `ReturnType`.
486
- `ResolvedTextarea`'s `textarea` bundle is typed for `h.textarea`, which refuses
487
- `InnerHTML`; the resolver refuses an `InnerHTML` from any Mixin, so no cast is
488
- needed.
489
-
490
- Every adapter is available as both a component namespace (`Button.toView`,
491
- `Button.resolve`, `Button.ButtonSlots`) and flat Slot exports such as
492
- `ButtonSlots`.
493
-
494
- ## What the resolver protects
495
-
496
- This package delegates merge semantics to core `foldkit-mixins`; it does not
497
- simply concatenate arrays.
816
+ ```ts
817
+ import { modifyFields } from 'foldkit/struct'
818
+ import type { Return } from 'foldkit/update'
819
+ import { FileInput, FileInputSlots } from 'foldkit-mixins-ui'
820
+
821
+ const FilesModel = Schema.Struct({ files: Schema.Array(Schema.instanceOf(File)) })
822
+ const FilesMessage = defineMessageUnion({
823
+ Picked: { files: Schema.Array(Schema.instanceOf(File)) },
824
+ Removed: { file: Schema.instanceOf(File) },
825
+ ...FileInput.cases,
826
+ })
827
+ type FilesMessage = typeof FilesMessage.Type
828
+
829
+ const FileFieldStyle = Style.forSlots(FileInputSlots)(Recipes.FileInput({}))
830
+
831
+ const filesUpdate = (
832
+ model: typeof FilesModel.Type,
833
+ message: FilesMessage,
834
+ ): Return<typeof FilesModel.Type, FilesMessage> =>
835
+ FilesMessage.match(message, {
836
+ Picked: ({ files }) => {
837
+ const next = FileInput.added(model.files, files, { multiple: true })
838
+ return {
839
+ model: modifyFields(model, { files: () => next }),
840
+ commands: [FileInput.Sync({ id: 'cv', files: next })],
841
+ }
842
+ },
843
+ Removed: ({ file }) => {
844
+ const next = model.files.filter(each => each !== file)
845
+ return {
846
+ model: modifyFields(model, { files: () => next }),
847
+ commands: [FileInput.Sync({ id: 'cv', files: next }), FileInput.Focus({ id: 'cv' })],
848
+ }
849
+ },
850
+ CompletedSync: () => ({ model }),
851
+ CompletedFocus: () => ({ model }),
852
+ })
498
853
 
499
- The resolver guarantees that:
854
+ const filesView = (model: typeof FilesModel.Type, h: HtmlBuilder<FilesMessage>) =>
855
+ FileInput.view(
856
+ {
857
+ id: 'cv',
858
+ label: 'Attach files',
859
+ name: 'attachments',
860
+ multiple: true,
861
+ files: model.files,
862
+ onChange: files => FilesMessage.Picked({ files }),
863
+ onRemove: file => FilesMessage.Removed({ file }),
864
+ style: FileFieldStyle,
865
+ },
866
+ h,
867
+ )
868
+ ```
500
869
 
501
- - component/base attributes survive;
502
- - `ChildAttribute`s survive by identity, preserving Submodel routing;
503
- - classes are additive;
504
- - inline declarations merge by property;
505
- - an event or scalar attribute has one owner;
506
- - structural attributes remain protected;
507
- - conflicting ownership produces a `DiagnosticError` rather than an accidental
508
- second handler.
870
+ Nothing here reads the input: the browser's dialog, the native input and the form
871
+ are the platform's, and the view declares them. `Sync` and `Focus` are the only
872
+ calls that touch the page.
509
873
 
510
- For example, if the Button already owns its click transition, a Behavior cannot
511
- silently install a competing `OnClick` at the same Slot.
874
+ ### FileUpload
512
875
 
513
- That is the main reason to use this adapter instead of another `className` or
514
- `attributes` escape hatch.
876
+ A `FileUpload` is a field that holds files and says what became of each: chosen by the
877
+ dialog, dropped or pasted, judged against limits (kind, size, count, duplicates), listed
878
+ with a thumbnail, and, when the application asks, sent. Its `Model` and `update` are the
879
+ whole machine, which the application places and folds as it places `TagsInput`; the
880
+ view draws them.
515
881
 
516
- ## Submodel components remain Submodels
882
+ Choose by what you need to own:
517
883
 
518
- Some `@foldkit/ui` components publish `ChildAttribute`s carrying the child
519
- state-machine dispatcher.
884
+ | You need | Use |
885
+ | --- | --- |
886
+ | a native picker whose `File[]` you keep, with no checks, drop, previews or status | [FileInput](#fileinput) |
887
+ | a drop zone over `@foldkit/ui`'s Submodel | `FileDrop` |
888
+ | files judged, listed, previewed, dropped, removed, retried, optionally sent and sorted | `FileUpload` |
520
889
 
521
- The resolver preserves those attributes, so adapting the render seam does **not**
522
- flatten or bypass the child boundary:
890
+ It owns the list and each entry's status. It does not own the transport (the
891
+ application's Subscription sends a file and answers in its own Messages), the order
892
+ (the application places `Reorder`), or the bytes of an uploaded file (a `Stored` entry
893
+ holds an address).
523
894
 
524
895
  ```text
525
- parent view
526
- |
527
- resolved Slot attrs
528
- |
529
- ChildAttribute
530
- |
531
- component Submodel dispatcher
896
+ Offered -> validate -> Held | Queued -> Uploading(lane) -> Done | Failed -> Retried
532
897
  ```
533
898
 
534
- Dialog, Popover, Tooltip, Tabs, RadioGroup, Calendar, and Menu all rely on this
535
- behavior.
536
-
537
- Per-item components can also return structured groups rather than one flat Slot
538
- array. The adapter preserves that shape. For example:
899
+ A picked, dropped or pasted batch is one `Offered` Message. `update` checks each file
900
+ (kind, then size, then duplicate), refuses a whole batch that would pass `maxFiles`, and
901
+ lists the rest `Held`, or `Queued` when the field has `lanes`. A queued file starts as a
902
+ lane frees. The Model keeps each `File` and writes the list back into the native input
903
+ after every change (`FileInput.Sync`), so a plain form post carries exactly the local
904
+ files, dropped ones included.
539
905
 
540
- ```text
541
- Tabs -> { tablist, tabs, activeIndex }
542
- RadioGroup -> { group, options, selectedValue, hiddenInput }
543
- Calendar -> ResolvedDays | ResolvedMonths | ResolvedYears
544
- Menu -> { wrapper, button, backdrop, items, scroll, groups, isVisible }
545
- Toast -> { container, entries }
546
- Listbox -> { wrapper, button, backdrop, items, scroll, groups, hiddenInputs, isVisible }
547
- Combobox -> { wrapper, inputWrapper, input, toggleButton, backdrop, items, scroll, groups, hiddenInputs, isVisible }
548
- ```
906
+ Place it in the application's Model and wrap its Messages:
549
907
 
550
- One Slot contribution can apply to each repeated item while every item's base
551
- attributes keep their own event ownership.
908
+ ```ts
909
+ import * as Command from 'foldkit/command'
910
+ import { FileUpload, FileUploadSlots } from 'foldkit-mixins-ui'
911
+
912
+ const UpModel = Schema.Struct({ upload: FileUpload.Model })
913
+ type UpModel = typeof UpModel.Type
914
+ const UpMessage = defineMessageUnion({ GotUpload: { message: FileUpload.Message } })
915
+ type UpMessage = typeof UpMessage.Type
916
+
917
+ const upInit = (): UpModel => ({
918
+ upload: FileUpload.init({
919
+ id: 'documents',
920
+ multiple: true,
921
+ accept: ['.pdf', 'image/*'],
922
+ maxFiles: 5,
923
+ maxSize: 5_000_000,
924
+ }),
925
+ })
552
926
 
553
- ## Supported components
927
+ const upUpdate = (model: UpModel, message: UpMessage): Return<UpModel, UpMessage> =>
928
+ UpMessage.match(message, {
929
+ GotUpload: ({ message: inner }) => {
930
+ const { model: upload, commands } = FileUpload.update(model.upload, inner)
931
+ return {
932
+ model: upload === model.upload ? model : modifyFields(model, { upload: () => upload }),
933
+ commands: Command.mapMessages(commands ?? [], next => UpMessage.GotUpload({ message: next })),
934
+ }
935
+ },
936
+ })
554
937
 
555
- This is reference material; you do not need to memorize it to understand the
556
- adapter.
938
+ const UpStyle = Style.forSlots(FileUploadSlots)(Recipes.FileUpload({ layout: 'zone' }))
557
939
 
558
- | Component | Slots |
559
- | --- | --- |
560
- | Button | `button` |
561
- | Input | `input`, `label`, `description` |
562
- | Textarea | `textarea`, `label`, `description`, `count`, `frame`, `footer`, `meta` |
563
- | Select | `select`, `label`, `description`. The native `<select>`; the recipe draws its own chevron and mutes a chosen placeholder. For icons, descriptions, groups or a check in the list, draw a Listbox as a custom select with `Listbox.parts` (below) |
564
- | Checkbox | `checkbox`, `label`, `description`, `hiddenInput` |
565
- | Switch | `button`, `label`, `description`, `hiddenInput`. `Switch.draggable(onToggle)` beside the style lets the thumb be dragged: it follows the pointer past 4px, and on release `onToggle` is sent for the side its middle is on (nothing when that is the side it began on); a click after a drag is swallowed, right to left mirrors it, and a disabled or read-only switch does not drag. Pass the `onToggle` the view was given |
566
- | Fieldset | `fieldset`, `legend`, `description`. The recipe floats the legend into the group, so a box drawn round it holds the legend, and a disabled fieldset dims its legend and description beside the controls the browser disables. Recipe `variant`: `plain` (default, no box), `bordered`, `filled`; a boxed group pads its fields, and a control in it takes a corner concentric with the box's |
567
- | Disclosure | `button`, `panel`. The recipe draws the button as a row with a chevron of its own (down shut, up once `data-open`) and the panel's box; draw the panel only while open, or through upstream's `animatePanel`, which keeps a shut panel inert and moves its height itself by an inline transition, which the recipe overrides with an important rule so the `motion` knob scales it and reduced motion snaps it. Recipe `variant`: `plain` (default), `bordered` (one box round the button and the panel, whose lower corners square onto the panel while open), `ghost` (filled under the pointer); `indicator`: `chevron` (default), `none` |
568
- | Dialog | `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton`, and this package's `handle` (the Sheet's grabber, `aria-hidden`), `body`, `scroll`, `scrollBar`, `scrollThumb` and `footer`: draw `scroll` and its bar inside `body` and the answers in `footer`, and a body taller than the screen scrolls under the title while the footer stays (`Dialog.overlayBars` beside the style draws the overlay bar). `Dialog.keyboard` among the mixins of a dialog or sheet that holds a field measures the on-screen keyboard on the panel, and the recipes keep the panel above it (a Dialog shrinks, a bottom Sheet stands on it): iOS Safari and Chrome on Android otherwise leave it under the keys. An alert dialog is this one with `role: 'alertdialog'` in its context (`Dialog.toView(mixins, { h, role: 'alertdialog' }, draw)`), which puts `role="alertdialog"` on the `dialog` bundle; draw no close button, and drop the Messages `Dialog.isDismissal` names (Escape, the backdrop, the close button) in `update`, so only its own buttons, closing with `@foldkit/ui`'s `close`, answer it. `covered: true` in the context marks the panel `data-covered`, for a dialog another was opened from (draw the second inside the first's `dialog`, beside its panel), and the recipe steps it back; `attributes` adds to a bundle before the mixins resolve. Recipe `size`: `sm`, `md` (default), `lg`, `xl`, `full`; `title`: `shown` (default) or `hidden`, which leaves the heading to a screen reader alone (it still names the dialog, as `display: none` would not). The backdrop is the `overlay.scrim` token |
569
- | Popover | `button`, `panel`, `backdrop`, `arrow`, and this package's `layer`, drawn around the panel to show it in the top layer (see [The top layer](#the-top-layer)); `Popover.anchor(config?)` is the placement. Recipe `arrow`: `shown` (default), `none` |
570
- | Tooltip | `trigger`, `panel`, `arrow`, and this package's `layer`. `Tooltip.toView(mixins, { h, id }, draw)` takes the Tooltip's id (`model.id`), whose trigger the arrow points at; `Tooltip.anchor(config?)` is the placement, above by default. Recipe `arrow`: `shown` (default), `none` |
571
- | HoverIntent | `trigger`, `panel`, `arrow` (open and close delays with intent, for a hover card or a menu). `anchored: { id, anchor? }` in the context anchors the panel to the trigger in the top layer (`HoverIntent.anchor()` unless given), the trigger taking `HoverIntent.triggerId(id)` |
572
- | Tabs | `tablist`, `tab`, `panel`, and this package's `indicator` and `highlight` (drawn first in the tablist, for `Tabs.fluid`). and this package's `item`, `label`, `icon` and `close`: a tab is a flex row, so draw its words in `label` (`h.span(label, [words])`) and an icon in `icon`, a Badge after them for a count. `TabsContext.close: { onClose }` makes tabs closable: each gets a close button (no tab stop, hidden from assistive technology) and Delete, named in `aria-keyshortcuts`; answer with `Tabs.closing(tabs, chosen, closed)`, which gives the tabs left, the tab chosen and the index to focus with `FocusTab`. `Tabs.readingKeys` beside the style reads the arrow keys by the tablist's direction (see [Right to left](#right-to-left)). Recipe axes `variant`: `line` (default), `pill`; `size`: `sm`, `md`, `lg`; `overflow: 'scroll'` (one line, its edges fading) or `'wrap'` (a grid of equal columns that fills the row and falls to fewer columns, no tab cut off; a column is no narrower than three control heights; `.extend` the tablist's `--_fk-tab-min` to change it); pill-only `selection`: `raised` (default) or `tint`; upstream's `orientation: 'Vertical'` stands the rule at the tabs' inline end |
573
- | RadioGroup | `group`, `option`, `label`, `description`, `hiddenInput`, and this package's `card`. Upstream's `option` is a `button` and its `label` bundle only an id, so a bare `label` takes no press: draw each row as a `label` element around its `option`, carrying the option's `card` bundle (`h.label(option.card, [h.button(option.option, []), …])`), and the browser sends a press on the words to the radio. `card` is `data-checked` while its option is. The recipe stacks the group unless `aria-orientation` is `horizontal`, and a row wraps. `variant: 'card'` frames each card and fills the one whose radio is checked. `tone`: `accent` (default), `neutral`; `size`: `sm`, `md`, `lg`. `RadioGroup.readingKeys` as Tabs' |
574
- | Anchor | a Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id; `Anchor.topLayer(mount)` shows an in-place panel in the top layer around it (see [The top layer](#the-top-layer)) |
575
- | Calendar | `root`, `header` (the heading's row, this package's own), `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton`. `Calendar.readingKeys` as Tabs' |
576
- | Menu | `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, and this package's `rows`, `highlight`, `scrollBar` and `scrollThumb` (while the panel has a `scroll`), `label`, `sub` and `chevron` (the component's rows) (over the `MenuView` fork; see [Why some components needed a fork](#why-some-components-needed-a-fork)) |
577
- | FileDrop | `root`, `input`. `FileDrop.Message` is `@foldkit/ui/fileDrop`'s four Messages over a `File` codec that needs no decoding services: upstream's own types its files as `Schema<File>`, whose services are `unknown`, so a Message holding it cannot be a `Bundle.parent`'s. `FileDrop.update` of upstream takes it as it is |
578
- | Toast | `container`, `entry` (over the `ToastView` fork; the dismiss control stays inside the consumer's `entryToView`), and the slots the `Toast` component draws (see the vocabulary below) |
579
- | Listbox | `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, and this package's `rows`, `highlight`, `indicator`, `scrollBar`, `scrollThumb`, and an option's and the trigger's parts (`itemIcon`, `itemLabel`, `itemDescription`, `itemCheck`, `value`, `valueText`, `chevron`, …) (over the `ListboxView` fork; single and multi share one transcription). A custom select is a Listbox drawn with `Listbox.parts(mixins, { h })`: `part.option({ label, description?, icon? })` as an item's content and `part.trigger(chosen, placeholder)` as the button's, its value or the placeholder (muted, `data-placeholder`) and a chevron. Recipe axes `width`: `auto` (default) or `trigger`; `check`: `end` (default), `start`, `none`; `trigger`: `outline` (default), `filled`, `ghost`; `size`: `sm`, `md`, `lg` |
580
- | Combobox | `wrapper`, `inputWrapper`, `input`, `toggleButton`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, and this package's `rows`, `highlight`, `indicator`, `scrollBar`, `scrollThumb`, `chips`, `chip`, `chipRemove`, `clearButton`, `empty` and an option's parts (over the `ComboboxView` fork; single and multi share one transcription). The view inputs add `chips: { label?, removeLabel? }` (each chosen value a chip in the field, its remove button choosing it again, which a multiple combobox toggles off: with `ComboboxView.Multi`, a tags field with suggestions), `clearContent` and `clearLabel` (a clear button while the field has text) and `empty` (shown, as a polite status, in the list's place while open with nothing to list; a loading line too). `Combobox.parts(mixins, { h }).option(content, query)` marks the typed text in an option's label. Recipe axis `width`: `trigger` (default) or `auto` |
581
- | DatePicker | `trigger`, `panel`, `backdrop` (over the `DatePickerView` fork, which keeps upstream's Popover+Calendar composition and seams only the popover assembly). A range or many days in the popover: see [Why some components needed a fork](#why-some-components-needed-a-fork) |
582
-
583
- A disclosure with its recipe: the recipe draws the button and the panel's box,
584
- and `animatePanel` keeps the shut panel inert and moves its height.
940
+ const upView = (model: UpModel, h: HtmlBuilder<UpMessage>) =>
941
+ FileUpload.view(
942
+ {
943
+ model: model.upload,
944
+ onMessage: message => UpMessage.GotUpload({ message }),
945
+ label: 'browse',
946
+ name: 'documents',
947
+ words: { prompt: 'Drop files here or' },
948
+ style: UpStyle,
949
+ },
950
+ h,
951
+ )
952
+ ```
585
953
 
586
- <!-- docs-check
587
- declare const ToggledDetails: (payload: { readonly isOpen: boolean }) => Message
588
- -->
954
+ `init` refuses an `accept` token that is not `.ext`, `type/*` or `type/subtype`, a
955
+ negative or fractional `maxSize`, `maxFiles` or `lanes`, a `maxFiles` without `multiple`,
956
+ and several `initial` files without it. `update` returns an `OutMessage`: `Picked`
957
+ (the ids added and replaced, and every `Refusal`) after an offer, `Removed` after a
958
+ removal. A no-op returns the Model it was given.
959
+
960
+ **The picker.** The `input` is a native `type="file"` drawn first, a transparent pixel
961
+ rather than hidden, and the `picker` is its `label`, always its next sibling. A press
962
+ on the picker, and Enter or Space on the focused input, open the browser's dialog with
963
+ no script between; the picker rings on keyboard focus. The picker also owns the four
964
+ drag events and `data-dragging`. `Recipes.FileUpload`'s `layout` (`button`, `zone`,
965
+ `avatar`, `cover`) only restyles it. What is drawn follows what the view is given, not
966
+ the recipe: `words.prompt` draws a drop zone's invitation, `picture` draws the
967
+ single-image face, `description` and the limits draw their paragraphs. The input is
968
+ named by the picker's words (`prompt` and `label`), so give `label` the words that name
969
+ the files.
970
+
971
+ **Refusals and the live region.** Each refusal names its file and is listed in
972
+ `errors`, which is not live; one polite `status` region, drawn always, says each change
973
+ once (`3 added`, `Removed a.png`, `a.png uploaded`) and never says a percentage. Two
974
+ identical notices in a row are not spoken twice. `words` holds every sentence, with
975
+ `{name}`, `{count}`, `{max}`, `{size}` and `{reason}` standing for what it is about.
976
+
977
+ **Previews.** An added image asks for an object URL through a Command and shows it in
978
+ the row's `preview`. `FileUpload.released(model)` revokes every URL: call it from the
979
+ Message that drops the widget (a route change, a dialog closing). Nothing revokes on
980
+ unmount, so without it the URLs live until the document unloads.
981
+
982
+ **A single image.** Give `picture` a function from the first entry's address to what the
983
+ picker holds. The list is not drawn, and the one file's Remove button follows the
984
+ picker, over its corner in `avatar` and `cover`:
589
985
 
590
986
  ```ts
591
- import { Disclosure as UiDisclosure } from '@foldkit/ui'
592
- import { Style } from 'foldkit-mixins'
593
- import { Disclosure, DisclosureSlots, Recipes } from 'foldkit-mixins-ui'
987
+ const UpAvatarStyle = Style.forSlots(FileUploadSlots)(Recipes.FileUpload({ layout: 'avatar' }))
594
988
 
595
- const DetailsStyle = Style.forSlots(DisclosureSlots)(Recipes.Disclosure({ variant: 'bordered' }))
596
-
597
- const details = (isOpen: boolean, h: HtmlBuilder<Message>) =>
598
- UiDisclosure.view(
989
+ const upAvatar = (model: UpModel, h: HtmlBuilder<UpMessage>) =>
990
+ FileUpload.view(
599
991
  {
600
- id: 'details',
601
- isOpen,
602
- onToggle: isOpen => ToggledDetails({ isOpen }),
603
- toView: attributes => {
604
- const disclosure = Disclosure.resolve(attributes, [DetailsStyle.mixin], {
605
- input: undefined,
606
- h,
607
- })
608
- return h.div(
609
- [],
610
- [
611
- h.button(disclosure.button, ['Shipping details']),
612
- disclosure.animatePanel(h.div(disclosure.panel, ['Shipped in two days.'])),
613
- ],
614
- )
615
- },
992
+ model: model.upload,
993
+ onMessage: message => UpMessage.GotUpload({ message }),
994
+ label: 'Change photo',
995
+ picture: url =>
996
+ Option.match(url, {
997
+ onNone: () => h.span([], ['No photo']),
998
+ onSome: src => h.img([h.Src(src), h.Alt('')]),
999
+ }),
1000
+ style: UpAvatarStyle,
616
1001
  },
617
1002
  h,
618
1003
  )
619
1004
  ```
620
1005
 
621
- ## Views and components of this package
622
-
623
- These views take no `@foldkit/ui` bundle. Call `X.view(options, h)`. Most own no
624
- Model and no Message; the components among them that keep a small Model
625
- (Menu, Menubar, Toast, Sheet, Picker, WindowList, Drawer, TagsInput, TreeView, Carousel, Resizable,
626
- ColorPicker, InputCopy, MessageScroller, Questionnaire, AngleSlider, Timer,
627
- Marquee, ImageCropper, SignaturePad, Chart, CascadeSelect, FloatingPanel,
628
- Tour) say so, with its `init` and `update`.
629
- Every one takes an optional `style` of its slots and `mixins` beside it. Style
630
- the slots with the matching recipe. Hide text with `U.srOnly` from
631
- `foldkit-mixins/utilities`. Name a control with `FieldAssociation`;
632
- `Label.view` takes the id that derived.
1006
+ **Uploads.** `init({ lanes })` sends that many files at once; `0` sends nothing and
1007
+ every file stays `Held`. A queued file takes the first free lane, and a lane number holds
1008
+ for the whole send, so one Subscription entry per lane never restarts another's upload.
1009
+ The application supplies the send (`foldkit-media/browser`'s `uploadFile`, a hand-written
1010
+ stream, a simulation) and answers in its own Messages, which fold `Progressed`,
1011
+ `Succeeded` or `Failed` back into the widget. `FileUpload.lanes` makes every lane's
1012
+ entry for a count, so the entries cannot be fewer than `lanes`: take the count from the
1013
+ one constant that feeds both.
633
1014
 
634
1015
  ```ts
635
- import { parse } from 'foldkit-media/icons'
636
- import { Style } from 'foldkit-mixins'
637
- import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
1016
+ import { Stream } from 'effect'
1017
+
1018
+ const UP_LANES = 2
1019
+
1020
+ const upSubscriptions = FileUpload.lanes<UpModel, UpMessage>({
1021
+ count: UP_LANES,
1022
+ model: parent => parent.upload,
1023
+ send: job =>
1024
+ Stream.make(
1025
+ UpMessage.GotUpload({
1026
+ message: FileUpload.Message.Succeeded({
1027
+ id: job.id,
1028
+ attempt: job.attempt,
1029
+ url: Option.none(),
1030
+ }),
1031
+ }),
1032
+ ),
1033
+ })
1034
+ ```
638
1035
 
639
- const Frame = Style.forSlots(AspectRatioSlots)(Recipes.AspectRatio({ ratio: 'video' }))
640
- const Mark = Style.forSlots(IconSlots)(Recipes.Icon({ size: 'sm' }))
1036
+ (`FileUpload.lane({ lane, model, send })` is one lane's entry, for an application that
1037
+ names its Subscription entries itself.) Removing an uploading entry empties its lane, the
1038
+ entry's dependency changes and the request aborts: the same button reads `Cancel {name}`
1039
+ while a file uploads. A `Failed` answer says whether it may be `retryable`; `Retried`
1040
+ queues it again, as a new `attempt`. A Message of another attempt, or of an entry that
1041
+ is gone, changes nothing.
641
1042
 
642
- // `h` is the view's builder. `content` is `Html`.
643
- AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
1043
+ Progress is a value the application builds, so a field that sends nothing never loads the
1044
+ Progress widget. Give the view `progress` and an uploading row draws a bar (or, with
1045
+ `Recipes.Progress({ shape: 'ring' })`, a ring) named by `Uploading {name}`; without it
1046
+ the row says the same in its state text:
644
1047
 
645
- // An icon as data: an import from `virtual:foldkit-icons/…`, or parsed by a script.
646
- const check = parse('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>', 'check')
647
- Icon.view({ icon: check, label: 'Done', style: Mark }, h)
648
- Icon.view({ icon: check, style: Mark }, h)
1048
+ ```ts
1049
+ import { FileUploadProgress, ProgressSlots } from 'foldkit-mixins-ui'
1050
+
1051
+ const UpBar = FileUploadProgress.make({
1052
+ style: Style.forSlots(ProgressSlots)(Recipes.Progress({})),
1053
+ })
1054
+ // FileUpload.view({ ..., progress: UpBar }, h)
649
1055
  ```
650
1056
 
651
- A `label` makes the icon `role="img"`. Without one the glyph is `aria-hidden`.
652
- `Icon.view` draws the `IconData` as inline SVG with `foldkit-media`'s
653
- `Icon.draw` (ids of its own; `key` parts two copies of one icon) and fills its
654
- glyph with it, so the recipe's size is the drawing's.
655
- `Icons.glyph` is the other tool: a mask on an element that already exists.
1057
+ **Pieces.** `FileUpload.parts(options, h)` returns the drawings `view` assembles, apart:
1058
+ `input`, `picker`, `errors`, `status`, `summary` and an `items` entry per file with its
1059
+ `preview`, `name`, `meta`, `state`, `progress`, `actions` and `grip` (an uploading row with `progress` draws no state text). Lay them into
1060
+ `Table.view` or `Card.view` yourself; `view` is written in terms of `parts`, so there is
1061
+ one drawing.
1062
+
1063
+ **Placed and configured.** `Bundles.FileUpload` is the same `init` and `update` for
1064
+ `foldkit-bundle`, with `init`'s options as the args. It reports `Picked` and `Removed`,
1065
+ which a placement answers with `onOut` or `Bundle.ignore`, and it sends nothing: an
1066
+ application with `lanes` still adds `FileUpload.lanes` to its own Subscriptions.
1067
+ `FileUpload.configure({ base, presets })` returns `{ view, parts }` bound to what a site
1068
+ gives once: `style`, `words`, `picture`, `itemActions`, `progress` and `mixins`. `sort`
1069
+ reads the Model at each draw and `routes` hold Messages, so both stay at the call.
1070
+
1071
+ **Sorting.** Order is the application's: it places `Reorder` as documented for
1072
+ primitives and hands the Behavior to the view as `sort: { input, mixin }`, which draws a
1073
+ grip per row, marks the list `data-sortable` and reads `input` for the Behavior. The widget
1074
+ imports neither Reorder nor its pointer drag, so a field with no sorting loads neither. The
1075
+ application's `onOut` applies the `Moved` fact with `FileUpload.ordered` and reads every fact
1076
+ out through the one live region with `FileUpload.announce`. A keyed move drops the browser's
1077
+ focus, so beside the widget's own focus Commands add `FileUploadSort.keepFocus` to `mixins`
1078
+ (it keeps a grip's focus and covers `without`); it is a module of its own because it loads
1079
+ `FocusRecovery`.
656
1080
 
657
- | View | Call | Recipe |
658
- | --- | --- | --- |
659
- | `Accordion` | `{ id, items: { id, title, content, disabled? }[], open, onToggle, headingLevel? }`; `Accordion.toggled(open, id, { multiple?, collapsible? })` is the transition `update` applies, the open ids being the application's. Each trigger is a button in a heading naming its panel; a shut panel stays drawn and `inert`. The panel opens on a `0fr`-`1fr` grid row, the chevron turns, and the open title turns semibold in its own width. The view takes an `icon` in place of the recipe's. | `variant`: `plain` (default), `bordered`, `separated`, `filled`, `ghost`; `separators`: `on` (default, between sections only), `off`; `indicator`: `chevron` (default), `plus`; `indicatorPosition`: `end` (default), `start`; `active`: `none` (default), `trigger`, `item` (the open section tinted). Slots `root`, `item`, `heading`, `trigger`, `label`, `chevron`, `icon`, `panel`, `body`, `content`. |
660
- | `Alert` | `{ layout, title, description?, icon?, actions?, onDismiss?, dismissLabel? }`, and by `layout`: `'inline'` takes `assertive?` and is a live region inside the content, of something that just happened (`role="alert"` when assertive, `role="status"` otherwise); `'banner'` takes `label` and is a full-width strip across a page or a section, there on load, so a `section` landmark named by `label` rather than a live region, which would say nothing on load. Each action is `{ label, href }` (a link) or `{ label, onClick }` (a button); `onDismiss` draws a close button named `Dismiss <title>` inline, `Dismiss <label>` as a banner. The icon is `aria-hidden`. Whether it shows is the application's. The root writes `data-layout` and `data-dismissible`. | `tone`: `info` (default), `success`, `warning`, `error`; `emphasis`: `subtle` (default, the family's tint) or `bold` (its fill). Slots `root`, `icon`, `title`, `description`, `actions`, `action`, `dismiss`. |
661
- | `AngleSlider` | After Zag's: a dial in degrees, 0 at the top and clockwise. `AngleSlider.init({ id, value? })` is the angle and the drag, folded with `AngleSlider.update(layout)`, where `layout` (`step`, `largeStep`, `marks`, `restrictToMarks`) is the object the view spreads in too: `AngleSlider.view({ ...layout, model, onMessage, label, name?, format?, valueText?, showValue?, disabled?, readOnly?, invalid?, style? }, h)`. A press or drag on the dial sends `Pointed` and `Released`; the APG's slider keys reach `update` as what was pressed, and go round past 0. A `name` draws a hidden input for a form. | `tone`, `track` (`ring`, `plain`, `disc`), `value` (`inside`, `below`), `size`. Slots `root`, `label`, `control`, `needle`, `thumb`, `markers`, `marker`, `markerLabel`, `value`, `input`. |
662
- | `AppShell` | An application's page frame: `AppShell.view({ title, brand?, status?, actions?, side?, footer?, mainId?, words? }, main, h)`. A skip link to the main region, a header bar (the banner) with the title and, at its end, `status` and `actions` (components: `Segmented`, `Badge`, `Avatar`), an optional side column for a `Sidebar`'s view, the main region (`id` `main` by default, focusable by script so the skip link moves focus there), and a footer. It holds no state and sends no Message; a `Sidebar` in `side` brings its own navigation landmark, collapse and phone Sheet. The header and the side column stay in view while the page scrolls; below `md` the side column, by then a Sidebar's opener, sits at the start of the header's row. `Patterns.AppShell` is its contract. | `width`: `full` (default) or `contained` (the main region's content kept to the theme's `width.page`, centred). Slots `root`, `skip`, `header`, `brand`, `mark`, `title`, `status`, `actions`, `side`, `main`, `footer`. |
663
- | `AspectRatio` | `{ content? }`. Slot `frame`. | `ratio`: `square` (default), `video` (16/9), `portrait` (3/4). The corner reads `radius`. |
664
- | `Avatar` | `{ name, src?, initials?, status?, statusLabel? }`. The root is one `role="img"` named by the person (and the status, "Ada Lovelace, Online"); initials show until the picture covers them, the picture's alt empty. `status` (`online`, `away`, `busy`, `offline`) is a dot on the lower end corner. `src` may be an `AvatarPicture` (`{ asset, provider, width }` from `foldkit-media`): the picture is drawn with its 1x and 2x candidates at `width` CSS pixels, and a provider with no URL for it leaves the initials. `Avatar.widthOf(size)` is a size's width in CSS pixels, for that `width`. `Avatar.group({ people, max?, label?, moreLabel?, style?, avatarStyle? })` overlaps them, each ringed in the page, and counts the rest as one more avatar. An avatar beside a name and a line is an `Item` with the avatar as its media. | `size`: `xs`, `sm`, `md` (default), `lg`, `xl`; `shape`: `circle` (default), `rounded`, `square`; `color`: `neutral` (default) or `name` (initials in a hue from the name); `ring`: `none`, `page`, `accent`. Slots `root`, `fallback`, `image`, `status`. `Recipes.AvatarGroup({ overlap: 'tight' \| 'loose' \| 'none' })` over `AvatarGroupSlots` (`root`). |
665
- | `Figure` | `{ content, caption? }`: a `figure` holding its content (an `Image.view`, a chart, a code block), then its caption in a `figcaption`, which names the figure for assistive technology by itself; no caption, no `figcaption`. | `align`: `start` (default) or `center`. The caption is the `caption` role, muted. Slots `root`, `caption`. |
666
- | `Image` | `{ asset, provider, layout, alt, priority?, sizes? }` from `foldkit-media`: a `picture` with a `source` per format the provider offers and an `img` with its candidates, `sizes`, `width` and `height` (the box is held before the file arrives), lazy unless `priority` (then `fetchpriority="high"`). `alt` is what the image shows in words (a string, or `Image.described(text)`) or `Image.decorative` (`alt=""`, `role="presentation"`), never omitted. `Provider.hosted` takes only a `HashedAsset`, so facts without a content hash are a type error there. The `img` carries `--fk-image-ratio`, `--fk-image-placeholder` (none behind a transparent image) and `data-layout` (`fixed`, `constrained`, `full`); a provider with no URL for the image leaves an empty frame marked `data-unavailable`. An unavailable image keeps its box and is `role="img"` named by its alt text (hidden when decorative). `--fk-image-focus` places a crop at the asset's focal point. `placeholder: 'detail' | 'average'` chooses how much of a ThumbHash to paint; by default the picture for `priority`, the color otherwise. `Image.watchLoad`, beside the style, marks the `img`'s `data-state` (`loading`, `loaded`, `failed`); the recipe hides a failed image, keeping its box. `Image.audit`, beside the style in a development build, warns in the console of an image drawn wider than its file (blurry) or far narrower (wasted bytes), and of more than one image drawn with `priority`. `Image.preloadsIn` is a `foldkit-ssr` `Head`: the `<link rel="preload">` of each image the rendered page drew with `priority`. | `fit`: `cover` (default) or `contain`; `edge`: `none` (default) or `line` (the faint inset line); `ratio`: `auto` (default), `square`, `video` (16:9), `portrait` (3:4), cropped at the asset's focal point (an unavailable image holds the cropped box); `radius`: `none` (default), `sm`, `md`, `lg`, `full`. The placeholder paints the `img`'s background. Slots `frame`, `source`, `image`. |
667
- | `Badge` | `{ text, tone? }` writes `data-tone`. | `Recipes.Badge({ attribute, tones, appearance? })` maps that attribute; values outside the map keep the base. `appearance`: `tinted` (default), `dot`, `outline`, `solid`. Slot `badge`. |
668
- | `Breadcrumb` | `{ steps: { label, href?, current?, icon? }[], separator?, collapse? }`. `current` is text with `aria-current="page"`; the others are links. An `icon` draws before its label, hidden from assistive technology. `separator` is drawn between steps in place of the recipe's; `collapse: { max, onExpand, label? }` folds the middle of a long trail into an ellipsis (`Breadcrumb.collapsedOf(steps, max)` is the split). `collapse: { max, menu: { model, onMessage, mixins } }` makes the ellipsis open a Menu of the hidden steps instead: the Menu's Model is the application's, built from `Breadcrumb.menuRows(steps, max)`, and `Breadcrumb.chosen(steps, max, value)` is the step a row leads to. | `separator`: `slash` (default), `chevron` or `dot`, drawn where the view is given no `separator` of its own. Slots `root`, `list`, `item`, `link`, `current`, `icon`, `separator`, `ellipsis`, `dots`. |
669
- | `ButtonGroup` | `{ label, items, orientation?, separated? }`. `role="group"`, joining its items: borders overlap by one and only the outer corners stay round. An item is the caller's button, field or Menu (a wrapper passes the corners to the face it holds), or a string, drawn in the `text` box (a count, a field's prefix). `orientation: 'vertical'` stacks them; `separated` draws a rule on every seam, for solid buttons whose fills meet. A hovered or focused item rises over its neighbour. `Segmented` is the control that selects. | `size`: `sm`, `md`, `lg`, for every item with no size of its own; `width: 'fill'` spans the container, a field taking what the buttons leave. Slots `root`, `separator`, `text`. |
670
- | `Calendar` | One date system, inline: `Calendar.Selection` is `Single`, `Range` or `Multiple`, owned by the application (`Calendar.empty(mode)`, fold each `SelectedDate` through `Calendar.picked`, `Calendar.isComplete` says when a picker may close). Spread `Calendar.inputs(selection, mixins, { h })` into upstream `Calendar.view`'s inputs: its `toView` (`Calendar.toView(selection, mixins, { h })`) marks each chosen day `aria-selected`, a range's ends `data-selected` with `data-range-start`/`data-range-end` and every day between `data-in-range`, and its `maybeSelectedDate` (`Calendar.selectedDate(selection)`, a Single selection's day) agrees with it. The grid of a Range or Multiple selection is `aria-multiselectable`. A selection in a popover is the DatePicker's. Options, the fourth argument of `toView`, `inputs` and `resolve` (`CalendarOptions`): `weekNumbers`, `caption: 'label'` or `dropdowns: { model, onShow }` (month and year selects; answer `onShow` with `Calendar.show`), `paging` with `Calendar.alongside(model, other, offset)` for two months side by side, `preview: { date, onPreview }` for a range under the pointer, and `detail: date => Option<string>` for a line under a day's number (a price, "2 events") that describes its button; `ResolvedDayCell.detail` holds it. `ResolvedDays`' paging buttons are `Option`s and its heading is a `caption` (`Grid`, `Label`, `Dropdowns`). Presets: `Calendar.lastDays`, `nextDays`, `monthOf`, `day`, drawn by `Calendar.presetsView`. `Calendar.localeOf('de-DE')` reads upstream's `locale` from Intl. | `size` (the Calendar's); `outside`: `shown` (default), `hidden`; `detail`: `text` (a taller rounded day holding the line), `dot` (the line as a dot, its words left to a screen reader), unset by default. Slots `CalendarSlots`. |
671
- | `Card` | `{ title?, description?, content?, image?, media?, action?, footer?, press?, label?, selected?, disabled?, dismiss? }`. `press` is `{ onClick }` or `{ href, external? }`: one button or link stretched over the card, named by `label` or the title (a pressable card with neither throws); `action`, `footer` and the dismiss button stay pressable above it. `selected` is `aria-pressed` on the button, `aria-current` on the link. `dismiss: { onDismiss, label?, always? }` is revealed on hover and focus unless `always`, and always on a touch screen. The root carries `data-selected`, `data-disabled`, `data-pressable`, `data-dismissible` (the header then keeps clear of the button). | `orientation`: `stacked` (default), `inline` (image or media leading, footer trailing). An `image` bleeds to the card's edges (16:9 when stacked); `media` puts a bare icon (`svg`, `img`) in a tile and lets anything else, an Avatar say, lead at its own size. `surface`: `outlined` (default), `elevated`, `filled`, `plain`. `padding`: `compact`, `comfortable` (default), `roomy`, `flush`. `elevation`: `0` to `3`, a step of the surface ladder (lighter in a dark scheme; a contact and an ambient shadow in a light one). `lift`: `none` (default) or `hover`, a lift under the pointer that `travel` stills (not in a `Card.group` with a highlight, which is the hover there). `Card.overlay` is the stretched press control, shared with Item. Slots `root`, `image`, `media`, `header`, `title`, `description`, `action`, `content`, `footer`, `overlay`, `dismiss`. |
672
- | `Card.group` | `{ cards: (CardView & { key })[], columns?, fluidHover?, label?, cardStyle? }`. A keyed list of cards in up to `columns` (default 1), which wraps to fewer where a column would be narrower than the recipe's `minColumn`; the root carries `--fk-card-columns` and `data-card-fluid`. With `fluidHover` (default) one highlight follows the pointer to the nearest card through `FluidHover` from `foldkit-primitives/dom`, reading both directions when there is more than one column, and a press in a gap presses the highlighted card. `cardStyle` styles every card that names no style of its own. | `Recipes.CardGroup`: `layout`: `divided` (default, hairlines between cards, wherever the row wraps), `separated` (apart, for cards with a surface). `minColumn`: `none`, `sm`, `md` (default), `lg`, the narrowest a column may be (10, 14, 18rem); `none` keeps every column at any width. `border`: `none` (default), `outlined`. The highlight is a film over the card the pointer is on, and is that card's hover: a card in a group with one draws no hover of its own, whatever its `surface`. Divided cards are usually `surface: 'plain'`. Slots `root`, `list`, `item`, `highlight`. |
673
- | `Carousel` | The APG carousel: `Carousel.init({ id, index?, autoplay?, delay? })`, folded with `Carousel.update({ count, perView?, loop? })`, drawn with `Carousel.view({ label, model, slides, onMessage, loop?, perView?, picker?, thumbnails?, slideLabel?, previousLabel?, nextLabel?, pickerLabel?, rotationLabels?, style? }, h)`. A group with `aria-roledescription="carousel"`, each slide a group named "2 of 5"; previous and next (`aria-disabled` at the ends unless `loop`), a dot per place the track can rest (or `thumbnails` in their place), and a polite status naming the slide shown. The track is a CSS scroll-snap scroller, so swipes move it natively, and `ScrollSettle` reports where a swipe rests, so the dots follow the finger. Every press, swipe and timer reaches `update`, which returns the `Carousel.ShowSlide` Command that scrolls the track: do not keep the slide yourself. With `autoplay` it moves on every `delay` (4s), the current dot filling as it waits; it pauses under the pointer, stops when focus arrives by the keys, quiets its status while it rotates, and draws the APG's rotation button first. | `peek`: `none` (default) or `edge`. Slots `root`, `track`, `slide`, `controls`, `rotation`, `previous`, `next`, `picker`, `dot`, `thumbnail`, `status`. |
674
- | `CascadeSelect` | After Zag's: one value chosen as a path of ids through nested options. `CascadeSelect.init({ id })` holds the chosen path and the one the keys are on while open, folded with `CascadeSelect.update(config)` (`config` is `{ nodes, parents?, closeOnSelect?, loop? }`, the same object the view takes): `CascadeSelect.view({ model, config, onMessage, label, placeholder?, levels?, layout?, expandOn?, clearable?, separator?, name?, disabled?, invalid?, direction?, style? }, h)`. The trigger is a combobox opening a top-layer APG tree, a column per level or one level at a time (`layout: 'drill'`; the columns also drill in on their own when they would not fit the window, measured as the popup opens); the arrows move within and between levels (swapped right to left), Home, End and a letter jump, Enter and Space choose, and only an option without children is chosen unless `parents` allows any. | `size`, `trigger` (`outline`, `filled`, `ghost`), `width` (`trigger`, `auto`). Slots `root`, `trigger`, `valueText`, `chevron`, `clear`, `input`, `layer`, `backdrop`, `panel`, `column`, `heading`, `back`, `item`, `itemText`, `branch`. |
675
- | `Chart` | After shadcn's Chart: `Chart.view({ id, label, kind: 'bar' \| 'line' \| 'area', categories, series: [{ name, values, color? }], model, onMessage, description?, format?, legend?, table?, categoryLabel?, style? }, h)`, or `kind: 'donut'` with `slices: [{ name, value, color? }]` and `totalLabel?`. The value axis's ticks are round and reach both ends, zero included; the plot is drawn in percentages, so it fills its container's width with nothing measured and renders the same on a server. `Chart.Model` (`Chart.init()`, folded with `Chart.update`) holds the lit point: the pointer lights a category's band and its tooltip, and the plot is a tab stop whose arrows, Home and End step through the points while a polite status says each. The drawing is hidden from assistive technology, which reads a data table, visually hidden unless `table: 'shown'`. Series take `chart-1` to `chart-5` in order, or the `color` they name; a sixth series throws. | `height` (`sm`, `md`, `lg`), `grid` (`lines`, `zero`), `indicator` (`dot`, `line`). Slots `root`, `title`, `description`, `legend`, `legendItem`, `swatch`, `body`, `yAxis`, `xAxis`, `yTick`, `xTick`, `plot`, `canvas`, `paths`, `grid`, `cursor`, `bar`, `line`, `area`, `dot`, `slice`, `band`, `center`, `centerValue`, `centerLabel`, `tooltip` and its parts, `status`, `table` and its parts. |
676
- | `ChatMessage` | One message of a chat: `ChatMessage.view({ from, content, author?, avatar?, time?, status?, onRetry?, actions?, pinActions?, streaming?, style? }, h)`, `from` being `user`, `assistant` or `system`. The user's sits at the end in a bubble, an answer as text at the start. `status` is `sending`, `sent` or `failed`, which draws a retry; `actions` are named buttons (`{ key, label, onClick, icon?, pressed?, disabled? }`) shown on hover and focus unless pinned. A streamed answer is the same message drawn again with more `content` and `streaming: true` (`aria-busy`); its body wraps with `text-wrap: wrap`, so no earlier word moves line. `ChatMessage.group({ items, continues?, style?, messageStyle? }, h)` draws a run, a sender's following messages continued. Markdown is the application's to render (`foldkit-richtext-markdown`'s `parse`, `foldkit-richtext-dom/view`'s `renderDocument`). | `layout` (`chat`, `thread`), `bubble` (`muted`, `accent`), `content` (`text`, `markdown`). `Recipes.ChatMessageGroup` for the group. Slots `root`, `avatar`, `main`, `header`, `author`, `time`, `bubble`, `body`, `footer`, `status`, `retry`, `actions`, `action`. |
677
- | `CheckboxGroup` | `{ id, legend, options: { value, label, description?, disabled? }[], checked, onToggle, error?, selectAll? }`; `toggled(checked, value)` is one option's transition, `coverage(options, checked)` is `none` \| `some` \| `all` (a disabled option counts for neither), and `setEnabled(options, checked, on)` is every enabled option or none, a disabled one keeping the state `checked` gives it. `selectAll: { label, onSet }` draws a first row whose checkbox is checked, `mixed` or unchecked by `coverage` and controls every option; a press sends `onSet` with `setEnabled`'s values, on unless all already are. A `fieldset` named by its `legend`, each option the APG's checkbox (`role="checkbox"`) named by a `label` for it, so a press on the words toggles it. `error` is shown under the options and the group is `aria-invalid`, described by it. | `variant`: `plain` (default), `list` (checked rows fill, and merge where they stand together; a vertical list has no gap, or the block would split). `orientation`: `vertical` (default), `horizontal` (a wrapping row). The checkbox sits on the label's row, so a description does not pull it down. Slots `root`, `legend`, `options`, `option`, `checkbox`, `label`, `description`, `error`. |
678
- | `CodeBlock` | `{ code, tokens?, language?, title?, lineNumbers?, copy? }`. `tokens` are `{ from, to, kind }`, as `foldkit-richtext-code` and `foldkit-richtext-code-shiki` tokenizers return them; each is drawn with `data-kind`, and a token out of order or outside the code throws. The block's text is the code exactly. `copy: { onCopy?, copied? }`: `onCopy` gets the code, so run `copyText` from `foldkit-primitives`; without it the button has no handler, for a page whose script copies. `CodeBlock.linesOf` is the cut. | No axis. Colors each kind from the theme's `syntax` group; `data-line-numbers` numbers lines, `data-copied` marks a copy done. Slots `root`, `header`, `title`, `copy`, `body`, `code`, `line`, `token`. |
679
- | `ColorPicker` | After ReUI's: a saturation and brightness area, hue and alpha Sliders, an eyedropper where the browser has one (`ColorPicker.Eyedrop`, `canEyedrop`), text in hex, rgb, hsl or oklch, and `presets` as a radio group of swatches. The color, its format and a draft being typed are `ColorPicker.Model` (`init({ id, color?, format? })`), folded with `ColorPicker.update`: keys and drags reach `update` as what was pressed, so fast keys each step from the last color. Drawn with `ColorPicker.view({ model, onMessage, label, presets?, alpha?, eyedropper?, labels?, disabled?, style?, slider? }, h)`; `ColorPicker.popover({ ...options, popover, onPopover, anchor?, popoverMixins? }, h)` draws it behind a swatch in a Popover made with `contentFocus: true` (it throws for one without): the panel opens on the area's thumb, a press or a drag inside never closes it, whatever opened it, and focus leaving it closes one the keys or a finger opened (a mouse's stays open, as upstream's Popover does). `ColorPicker.color('#3b82f6')` reads a literal in code (it throws on a typo); `format`, `parse` (an `Option`) and `toOklch` are pure. | `size`. Its Sliders take `Recipes.Slider({ track: 'paint', label: 'hidden' })`. Slots `root`, `label`, `area`, `areaThumb`, `controls`, `eyedropper`, `channels`, `channel`, `swatch`, `fields`, `format`, `input`, `presets`, `preset`, `picker`, `trigger`, `value`. |
680
- | `Command` | `{ id, label, placeholder?, groups: { heading?, items: { value, label, description?, keywords?, shortcut?, icon?, opensPage?, disabled? }[] }[], query, onQuery, active, onActive, onRun, empty?, loading?, page?, hints?, kbd? }`, a `shortcut` being a tuple of keys (`['⌘', 'K']`) drawn as Kbd with `kbd`. `page: { trail, onBack }` draws the pages stepped into as crumbs before the field, and Backspace in an empty field sends `onBack`; a row with `opensPage` has a chevron. `loading` says it and marks the list `aria-busy`, its rows still shown; `hints` are a footer of keys. `Command.hotkey(message)` is ⌘K or Ctrl+K anywhere, for an application to lift with `Subscription.persistentEntry` and open its Dialog on; `Command.filtered(groups, query)` is what a query leaves. shadcn's Command and Fluid's CommandMenu: the field points at the highlighted row through `aria-activedescendant`, ↑ and ↓ wrap through enabled rows, Enter runs the highlighted one; rows never re-sort, and a filtered-away highlight moves to the first enabled row. The list stands in a `frame` beside its bar, which `Command.overlayBars` drives (see [Overlay scroll bars](#overlay-scroll-bars)). A shortcut reads left to right on a right-to-left page. | `frame`: `card` (default) or `bare`, for inside a dialog. Slots `root`, `search`, `crumbs`, `crumb`, `input`, `list`, `group`, `heading`, `item`, `icon`, `text`, `label`, `description`, `shortcut`, `chevron`, `status`, `empty`, `loading`, `frame`, `bar`, `thumb`, `footer`, `hint`. |
681
- | `Empty` | `{ title, description?, icon?, action? }`. The title takes the `subtitle` role; the icon is `aria-hidden`. | `media`: `icon` (default), `illustration`; `frame`: `none` (default), `dashed`, `filled`; `tone`: `neutral` (default), `danger`; `size`: `compact`, `comfortable` (default). Slots `root`, `icon`, `title`, `description`, `action`. |
682
- | `FloatingPanel` | After Zag's: a non-modal window. `FloatingPanel.init({ id, rect, open? })` holds its rect, stage and a drag, folded with `FloatingPanel.update(limits)` (`min`, `max`, `grid`, `overflow`); `FloatingPanel.open(model, { opener })` focuses it and `close` gives focus back. `FloatingPanel.view({ model, onMessage, title, content, order?, draggable?, resizable?, closeOnEscape?, step?, direction?, labels?, style? }, h)`: the drag trigger moves it and eight edges resize it, kept within the viewport; the arrows move it from the drag trigger and resize it from the bottom-end corner; minimize, maximize, restore and close. A press or focus inside returns the `Raised` OutMessage, which the application folds into the `order` its panels stack by with `FloatingPanel.raise(order, id)`. | `header`. Slots `root`, `boundary`, `panel`, `header`, `dragTrigger`, `title`, `controls`, `minimize`, `maximize`, `restore`, `close`, `body`, `handle`. |
683
- | `HoverCard` (recipe) | Styles `@foldkit/ui`'s HoverIntent (`HoverIntentSlots`): a trigger read as a link, a raised panel fading in on the fast tier as it is drawn. Place the panel with `HoverIntent.toView`'s `anchored`, which shows it in the top layer with an `arrow`; the open and close delays are HoverIntent's (200ms and 300ms by default). | No axis. Slots `trigger`, `panel`, `arrow`. |
684
- | `Icon` | `{ content, label? }`. A `label` is `role="img"`; without one the glyph is `aria-hidden`. `foldkit-media`'s `Icon.draw(icon, h)` is an `IconData`'s inline SVG for `content`, which the glyph fills. | `size`: `sm`, `md`, `lg` on the type scale; none (the default) stands on the size ladder, 16px or 14px compact. Slot `glyph`. |
685
- | `ImageCropper` | After Zag's: the image fitted in a viewport, a selection that a drag moves (`Move`) and eight handles resize, zoom by a Slider, the wheel, two fingers spread or pinched, and `+`/`-` with the selection kept where it is on screen, a pan of the zoomed image, quarter turns, an aspect lock and a round crop. `ImageCropper.init({ id, aspect?, shape?, crop?, min?, maxZoom? })` holds the crop, in the turned image's pixels, folded with `ImageCropper.update`; keys (arrows, Shift ×10, Alt to resize) step by screen pixels. Drawn with `ImageCropper.view({ model, onMessage, label, src, crossOrigin?, controls?, labels?, disabled?, style?, slider? }, h)`. `ImageCropper.crop(model)` is the crop in whole pixels (an `Option`); `RequestedExport({ type, quality })` returns the `Export` Command, answered by `Exported({ url, width, height })` or `FailedExport`. | `guides`, `handles` (`all`, `corners`), `viewport` (`landscape`, `wide`, `square`). Its zoom takes `Recipes.Slider({ label: 'hidden' })`. Slots `root`, `label`, `viewport`, `stage`, `pan`, `image`, `selection`, `guides`, `handle`, `controls`, `zoom`, `rotate`, `reset`. |
686
- | `InputCopy` | A read-only value with a copy button, Zag's clipboard: `InputCopy.view({ id, label, value, copied, onCopy, copyLabel?, copiedLabel?, style? }, h)`. The view is stateless: answer `onCopy` with the `InputCopy.Copy({ text })` Command, which yields `foldkit-primitives/dom`'s `ClipboardMessage` (`Copied` or `CopyFailed`, never a throw); `copied` is the application's, and `InputCopy.Model` keeps it: `InputCopy.init({ resetAfter? })` (default 2000ms), folded with `InputCopy.update`, where `Copied` on `ClipboardMessage.Copied` shows it copied and starts the `Reset` Command that sets it back unless a later copy came first; pass `model.copied`. The button is named `Copy <label>`; copied, it reads `Copied` and a polite status region says so. | No axis. Slots `root`, `label`, `group`, `input`, `button`, `status`. |
687
- | `Item` | The row primitive: `{ content?, media?, title?, description?, actions?, press?, label?, selected?, disabled? }`; `content` follows the title and description. `press` is `{ onClick }` or `{ href }`, one control stretched over the row (`overlay`, as a Card's) and named by `label` or the title, `actions` staying pressable above it; `selected` is `aria-pressed` or `aria-current`. `Item.group({ items: (ItemView & { key })[], label?, style?, itemStyle? })` is a list of them. Field is for form controls. | `variant`: `plain` (default), `outline`, `muted`; `density`: `comfortable` (default), `compact`; `media`: `plain` (default), `icon`, `image`. Slots `root`, `media`, `content`, `title`, `description`, `actions`, `overlay`. `Recipes.ItemGroup({ layout: 'divided' \| 'separated' })` over `ItemGroupSlots` (`root`, `row`). |
688
- | `Kbd` | `{ key }`. Names the key. `Kbd.combo({ keys, joiner? }, h)` draws several in one `kbd`, with an optional joiner between them. | No axis. Slots `key`, `combo`, `joiner`. |
689
- | `Label` | `{ for, text }`. `for` is the control's id. | No axis. Slot `label`. |
690
- | `Marquee` | After Zag's: content that scrolls on without a seam. `Marquee.init({ id })` holds what it measured and whether it is paused, folded with `Marquee.update`; `Marquee.view({ model, onMessage, label, items, side?, speed?, autoFill?, repeat?, delay?, loopCount?, style? }, h)` measures its content (`Resize`) and draws copies to fill the viewport, `inert` after the first. A pointer, focus or its pause press (WCAG 2.2.2) holds it; `Marquee.Message.Paused()` holds it from outside. Its motion is CSS, and under reduced motion the viewport scrolls instead. | `spacing`, `edges` (`fade`, `none`). Slots `root`, `viewport`, `content`, `item`, `pause`. |
691
- | `Menu` | One menu, opened three ways: `Menu.init(id, rows, { isAnimated?, isModal? })` (a row with `items` hosts a submenu, one level deep; `isAnimated` gives the menu's and its submenus' panels upstream's transition marks, for the recipe's fade, and `isModal` makes the rest of the page inert while the menu is open), folded with `Menu.update`, drawn with `Menu.view({ model, rows, buttonContent, onMessage, opensAt?, direction?, isRowDisabled?, mixins, submenuMixins? }, h)`, the style being one of the `mixins` (`[MenuStyle.mixin]`). By a button (`opensAt` unset); at a point (`opensAt: 'point'`, with `Menu.target(onMessage, h)` on the area: a right press records its point and the `contextmenu` after it opens the menu there; a finger or a pen held there `Menu.HOLD_MS`, 500ms, opens it too, as iOS fires no `contextmenu`, while one that moves 10px is a scroll; give the area `-webkit-touch-callout: none` and `user-select: none`, or iOS shows its own callout over it). A row is an `ItemRow` (`{ label }`), a `CheckRow` (`check: 'checkbox' \| 'radio'`, `checked`: `menuitemcheckbox` or `menuitemradio` with `aria-checked`; choosing it sends `Selected` and leaves the menu open, the application keeping `checked`, a radio row's group being the rows of its `group`), or a `SubmenuRow` (`items`). Any row may name a `group` (rows next to each other with one group stand under its heading, a separator between groups), a `shortcut` (keys drawn at the row's end as Kbd with the view's `kbd`, named in `aria-keyshortcuts`; the menu binds nothing) and `tone: 'destructive'` (`data-tone`). A submenu's row is a `menuitem` with `aria-haspopup="menu"` and `aria-expanded`; ArrowRight, Enter or Space opens it on its first row, ArrowLeft or Escape closes it back to the row (under `direction: 'rtl'`, drawn as the root's `dir`, the submenu opens on the left, its chevron points there, and the arrows swap), a pointer resting 150ms opens it, and choosing a leaf closes everything. `Selected` names the value and the submenu it came from. Pass `Menu.fluid` beside the style (in `submenuMixins`, not `mixins`, where rows open submenus). Its panels, submenus included, draw in the top layer. A `@foldkit/ui` Menu the application folds itself, for typed items or groups, is drawn through the panel adapter instead, and opens at a point with `Menu.drawAtPoint` and `Menu.pointTarget` (see [Why some components needed a fork](#why-some-components-needed-a-fork)). | No axis. Slots `MenuSlots`. |
692
- | `Menubar` | A row of `@foldkit/ui` Menus, shadcn's and the APG's menubar: `Menubar.view({ label, model, menus, onMessage, direction?, style?, menuMixins }, h)`, each menu's `{ label, rows, isRowDisabled? }` taking a Menu's rows (none opening a submenu), its Model (`Menubar.init(ids, { isAnimated?, isModal? })`) folded with `Menubar.update`, whose `Selected` OutMessage names the menu and the row. One trigger is the tab stop; ArrowLeft/ArrowRight (Home/End while all are shut) move it, swapped under `direction: 'rtl'` (drawn as the bar's `dir`), and with a menu open they open the next on its first row. While one is open, pointing at another opens it, and opening any shuts the rest. `Recipes.MenubarMenu` is the Menu recipe with a bar's flat triggers. | No axis. Slots `bar`, `menu`; each menu's are `MenuSlots`. |
693
- | `MessageScroller` | A conversation's log that follows the newest message while the reader is at the end and stops when they scroll up. `MessageScroller.init({ id })` holds only whether it follows and how many arrived unseen; the scroll position is the browser's, read by its `FollowEnd` Mount. Fold `MessageScroller.update`, and send `Message.Appended({ count })` when your update appends messages (not when it loads older ones, which it holds in place). `MessageScroller.view({ model, label, content, onMessage, jumpLabel?, unseenLabel?, style?, areaStyle?, areaMixins? }, h)` draws a named `role="log"` in a ScrollArea, with a jump button counting what arrived while away; give its parent a height. | No axis. Slots `root`, `log`, `jump`, `count`. |
694
- | `Meter` | `@foldkit/ui`'s Meter: `Meter.view({ id, label, value, min?, max?, low?, high?, optimum?, valueText?, style? }, h)` draws a `meter` named by its label. The root says how good the value is as `data-level` (`good`, `fair`, `poor`), as the HTML meter judges it; `Meter.levelOf` is that judgment. A measurement, where `Progress` is work. | No axis; the fill takes success, warning or error by level. Slots `root`, `label`, `track`, `fill`. |
695
- | `Nav` | Two layers. `Nav.toView(mixins, { h }, label, draw?)` styles `@foldkit/ui`'s stateless Nav, drawing `nav > ul > li > a` with the current link `aria-current="page"`. `Nav.view({ model, entries, label, onMessage, orientation?, direction?, mixins? }, h)` is a navigation menu: links and triggers whose panels of link columns (`groups` of `{ label, href, description?, current? }`) show in the top layer, with the APG's disclosure-navigation keys (Escape, ArrowDown into a panel, the arrows, Home and End along the row; a press outside and focus leaving close it); which panel shows is `Nav.init(id)`'s Model, folded with `Nav.update`. `Nav.fluid` beside the style glides a line to the current link and a faint pill to the one the pointer nears. | `indicator`: `underline` (default), `pill`; `orientation: 'vertical'` is a column whose panels open beside it. Slots `nav`, `list`, `item`, `link`, `trigger`, `chevron`, `panel`, `groups`, `group`, `heading`, `links`, `panelItem`, `panelLink`, `title`, `description`, `indicator`, `highlight`. |
696
- | `NumberField` | `{ id, label, description?, value, onChange, min?, max?, step?, page?, format?, disabled? }`; `NumberField.settled(value, bounds)` clamps a value onto its step. The APG's editable spinbutton: an input with `role="spinbutton"` that the arrows, PageUp and PageDown, Home and End step, a typed number committing on change, between steppers out of the tab order that disable at their bound. | No axis. Slots `root`, `label`, `group`, `input`, `decrement`, `increment`, `description`. |
697
- | `OtpField` | `{ label, value, onChange, length?, pattern?, groups?, disabled? }`; `OtpField.kept(text, length, pattern)` filters a code. shadcn's input-otp: one real input (`autocomplete="one-time-code"`, paste and Backspace the browser's) over cells that mirror it, the next cell marked `data-next` for its caret. | No axis. Slots `root`, `input`, `group`, `cell`, `separator`. |
698
- | `Pagination` | `{ page, pageCount, onPage, label?, siblings?, boundaries?, numbered?, ends?, range? }`. Fewer than two pages draws nothing. `Pagination.itemsOf(page, pageCount, window?)` is the stops; `Pagination.summaryOf(page, { total, perPage, text? })` is `"1–10 of 97"`, drawn before the stops when `range` is given. `range.choose: { sizes, onPerPage, label? }` adds a select of rows per page (labelled `Rows per page` by default) that sends `onPerPage` with the size; the application sets `perPage` and a page that keeps its rows in view. `numbered: false` leaves previous and next alone; `ends` draws first and last. The current stop holds ` / 12` in a `pageCount` span hidden from assistive technology. | `compact`: `narrow` (default, below a 30rem window), `always` or `never`. Compact shows only the current number, with its ` / 12`, and no ellipses. The current stop reads `aria-current`. Slots `root`, `summary`, `perPage`, `perPageSelect`, `first`, `prev`, `next`, `last`, `page`, `pageCount`, `ellipsis`. |
699
- | `PasswordInput` | `PasswordInput.view({ id, label, value, onInput, visible, onToggle, autocomplete?, toggleLabel?, description?, invalid?, disabled?, attributes? }, h)`: a password field whose toggle button (`aria-pressed`, `aria-controls`, one fixed name) shows it as text. `autocomplete` is `current-password` (default) or `new-password`; spellcheck and autocorrect stay off. `strength` is a gauge the app draws (`Meter.view(…, h)`), placed under the field, so a page with none ships no Meter; `requirements` are `{ label, met }[]` (`PasswordRequirement`), listed and each read as met or not (`requirementStates`); `capsLock: { on, onKey }` says Caps Lock is on, politely, `onKey` given `capsLockOf(key, modifiers)` for each key (an `Option`: none for a key that says nothing of it). The app owns the text, the flag and the Caps Lock reading. `onInput` is a closure or a resumable builder's `OnInput` attribute, and `attributes` adds to any Slot (`{ input: [rh.KeepTyped()] }`), as the resumable examples above show. | `size` (`sm`, `md`, `lg`). Input's pieces in InputGroup's box; the eye is `Icons.glyph` by `aria-pressed`. Slots `root`, `label`, `group`, `input`, `toggle`, `description`, `strength`, `requirements`, `requirement`, `requirementState`, `capsLock`. |
700
- | `Progress` | `@foldkit/ui`'s Progress: `Progress.view({ id, label, value, min?, max?, valueText?, style? }, h)` draws a `progressbar` named by its label. `value` is an `Option`; none is indeterminate, and the bar's fill sweeps toward the inline end, leftward right to left. The root carries the share done as `--fk-progress`. `showValue` draws the value (`valueText`, else a percentage) at the end of a bar's label line and inside a ring. A `value` given as `ProgressSection`s is one stacked bar of toned parts, read aloud as their sum; `buffer` draws how far the work could go behind the fill; `segments` cuts the track into steps. | `shape`: `bar` (default) or `ring`, Circular Progress; `tone`: `accent`, `neutral`, `success`, `warning`, `error`, `info` (Meter's tokens); `stripes`: `none` (default), `still`, `moving` (travel-aware); `size`: `sm`, `md`, `lg`. Slots `root`, `label`, `track`, `indicator`. |
701
- | `QrCode` | After Zag's: `QrCode.view({ id, value, label?, level?, quietZone?, overlay?, tooLong?, style? }, h)`, one `img` named `QR code: <value>` (or `label`), every dark module one SVG `path` over a background that carries the quiet zone. `level` is the error correction, `M` by default and `H` under an `overlay` (a logo at the centre). `QrCode.encode(text, level)` gives the matrix, none when no version holds the text, and `pathOf` its path; both are pure. `QrCode.Download({ id, format, filename, pixels })` saves the drawn code as PNG or SVG in the colors it shows; the overlay is not in the file. | `scheme` (`light`, dark on light on any page, or `page`), `size`. Slots `root`, `frame`, `background`, `pattern`, `overlay`, `fallback`. |
702
- | `Questionnaire` | An assistant's questions answered in the chat. `Questionnaire.init({ id, questions, layout? })` with `Questionnaire.single`, `multiple` and `text` questions (`Question` is a Schema, so a tool's input decodes into it), folded with `Questionnaire.update`, which says what is missing and focuses it, and returns `OutMessage.Answered({ answers })` once every required question is answered; the form then gives way to a summary. `Questionnaire.view({ model, onMessage, title?, style?, radioGroup?, checkboxGroup?, input?, textarea?, button?, submitButton? }, h)`: the controls are the package's RadioGroup, CheckboxGroup, Input and Textarea, each taking its own style. | `variant` (`plain`, `card`), `actions` (`end`, `start`). Slots `root`, `title`, `progress`, `question`, `prompt`, `words`, `field`, `other`, `otherLabel`, `error`, `actions`, `summary`, `asked`, `answer`. |
703
- | `Rating` | `Rating.view({ id, label, value, onChange, max?, starLabel?, readOnly?, disabled?, style? }, h)`: a `radiogroup` of native radios named by its label, one per star under one name, so the browser's arrows move the choice and a form submits it. `value` is an `Option`; none is unrated. Read-only, it is one `img` whose name says the rating. `precision: 0.5` draws two radios a star; a read-only value of any fraction fills its last star part way. `onClear` is sent by a press on the star already chosen; `showValue` shows `starLabel` of the rating beside the stars, so a word per value is one function. Home and End go to the ends through the `Rating.Ends` Mount (resolve it in a Scene test with a choice's Message). A read-only rating (`readOnly: true`) takes no `onChange`. | `tone`: `warning` (default, gold), `accent` or `error`; `glyph`: `star` (default), `heart`, `circle`, or `--_fk-rating-shape`; `size`: `sm`, `md`, `lg`. Stars are a CSS `clip-path` on each radio's `::before`; pointing previews the rating. Slots `root`, `label`, `star`. |
704
- | `Resizable` | `Resizable.Model` (`init(share)`), its `Message` and `update(model, message, bounds)`, which the application keeps and folds; `Resizable.view({ model, onMessage, label, first, second, orientation?, direction?, min?, max?, step? })`. shadcn's Resizable and the APG's window splitter: the handle is a `separator` with its value, stepped by the arrows and sent to the bounds by Home and End; a drag follows the `Move` Mount from where it began over the group the `Resize` Mount measured. Under `direction: 'rtl'`, drawn as the root's `dir`, the first panel is on the right, so ArrowLeft and a drag to the left grow it. `collapsible: 'first' | 'second'` (with `collapsedTo`) collapses that panel on Enter or a double-click and puts it back where it was, easing there while a drag follows the pointer at once; pass the same bounds to `update` and the view. A split fills its panel, so splits nest either way. | `handle`: `line` (default; a thicker accent line under the pointer) or `grip` (a pill of dots); `data-orientation` lays it out. Slots `root`, `first`, `handle`, `second`. |
705
- | `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin, on `viewport` or `root`; a width goes on `root`, which the viewport fills and the bars lie over. The viewport is tabbable. A bar per axis is drawn beside the viewport, and `ScrollArea.overlayBars` beside the style lays them over its edge, driven by `ScrollBars` from `foldkit-primitives/dom`: a thumb that rests 4px wide, widens to 6px under the pointer, and fades once scrolling and the pointer rest; a coarse pointer keeps the browser's bar. See [Overlay scroll bars](#overlay-scroll-bars). | `orientation`: `vertical` (default), `horizontal`, `both`; `vertical` and `horizontal` fade the content toward an edge with more past it and draw a hairline there. Slots `root`, `viewport`, `bar`, `thumb`. |
706
- | `Separator` | `{ orientation?, label?, decorative? }`, horizontal by default. A `label` sits between two drawn rules and is read as text; `decorative` is `role="none"`. The rule and a label's frame carry `data-orientation`, which the recipe reads, so one style draws both orientations. A vertical rule stretches across a flex or grid row, short of it by the inset, and elsewhere (running text) stands as tall as the letters. | `line`: `solid`, `dashed`, `dotted`; `thickness`: `thin`, `thick`; `spacing`: `none`, `sm`, `md`, `lg`; `inset`: `none`, `sm`, `md`. The line is a border in `outline.default`, which a dark page shows. Slots `rule`, `root`, `label`. |
707
- | `Drawer` | A panel docked to the bottom of the screen that peeks or opens beside the page, not over it: no focus trap, backdrop or scroll lock, so the page under it stays live (a modal one is the `Sheet`). `Drawer.init({ id, open?, swipe? })` (down by default), folded with `Drawer.update`, opened with `Drawer.open` and `Drawer.close`, drawn with `Drawer.view({ model, onMessage, labels: { open, closed }, style?, mixins?, draw }, h)`, `draw` laying out `panel`, `handle`, `body` (the body may sit below what else peeks with the handle) and, optionally, `grip`, more to drag it by (a row of tabs: vertical swipes drag it, sideways ones still scroll). A drag follows the finger and lets go open or down by its speed, then by how far it came. `swipe: { from?, flickSpeed?, closeShare? }` says how it is swiped: a finger drags it from anywhere on the panel (`from: 'panel'`, the default), yielding to content that can still scroll its way, so a long one scrolls back to its top and then goes, and a field or `data-no-swipe` starts no drag; a mouse drags it by the handle, and `from: 'handle'` keeps every pointer there. A release faster than `flickSpeed` (0.4px/ms) is a flick, and a slow one goes once dragged `closeShare` (a quarter) of the panel. A click or Enter on the handle toggles it, and the click a browser sends after a drag does not. The panel's inline style is the drag's: set `--fk-drawer-peek` (default 5rem) and `--fk-drawer-height` (default 70dvh) on an ancestor or in a style. | `Recipes.Drawer`: `dock`: `always` (default), `below-lg` or `below-xl`, above which the panel is the column it sits in, with no handle. The handle's bar bends into a chevron going down, with the finger while dragged. Slots `panel`, `handle`, `body`, `grip`. The handle is a 44px target drawn tight to its bar, and the peek stays above the home indicator. |
708
- | `Sheet` | A Dialog a finger drags, vaul's Drawer: `Sheet.init({ id, side?, points?, opensAt?, dismissible?, isAnimated?, swipe? })`, folded with `Sheet.update` and opened with `Sheet.open` and `Sheet.close` (each also reporting the Dialog's `Opened` or `Closed`), drawn with `Sheet.view({ model, onMessage, mixins, hasDescription?, covered?, scalesPage?, draw }, h)`, `draw` laying out `DialogSlots`' bundles with `h.div(sheet.handle)` in the panel. The panel stands on `side`'s edge (`data-side`); a drag follows the pointer and settles at the nearest of `points` (the share of the panel shown, ascending; a top or bottom sheet with a point below 1 takes its `size`'s full height, so a short one still shows its start, and below its highest point its content holds still, so a swipe up raises it), or, flicked or dragged far enough past the first, closes it, unless `dismissible: false`. `swipe: { from?, flickSpeed?, closeShare? }` says how it is swiped: a finger drags it from anywhere on the panel (`from: 'panel'`, the default), yielding to content that can still scroll its way, so a long one scrolls back to its top and then goes, and a field or `data-no-swipe` starts no drag; a mouse drags it by the handle, and `from: 'handle'` keeps every pointer there. A release faster than `flickSpeed` (0.4px/ms) is a flick, and a slow one goes once dragged `closeShare` (a quarter) of the panel. The Dialog keeps focus, Escape and scroll lock. `scalesPage` with `Recipes.sheetPage` on the page beside the sheet, never around it, steps the page back while it is open. | `Recipes.Sheet`: `size`: `sm`, `md` (default), `lg`, `full`; `handle`: `bar` (default) or `none`; `title`: `shown` (default) or `hidden`. Slots are `DialogSlots`. The panel's padding keeps clear of the safe areas (`Theme.tokens.safe`) on the sides it touches. |
709
- | `Picker` | A select that is a dropdown on a desktop and a bottom sheet on a phone, with one Model and one set of Messages whatever the width: `Picker.init({ id, sheet? })` (upstream's Listbox Model and a `Sheet`'s), folded with `Picker.update`, which returns `Picker.OutMessage.Chose({ value })` for a choice made either way, drawn with `Picker.view({ model, onMessage, label, options, value, placeholder, anchor?, style?, mixins?, listbox?, sheet? }, h)`. The application keeps the value (`Option`), as with the Listbox; `options` are `{ value, label, description?, icon? }`, `Value` inferred from them. Both halves are drawn and the recipe shows one, so nothing reads the width: the Listbox (its panel kept in place) at or above the breakpoint, and below it an opener whose Sheet lists the options as a listbox, the chosen one (or the first) focused, the arrows, Home and End moving focus, Enter, Space or a tap choosing and closing it. Opening the Sheet closes a Listbox left open. `listbox` takes `Recipes.Listbox`, which also draws the options' and the trigger's content (`Listbox.parts`), and `sheet` takes `Recipes.Sheet`. | `Recipes.Picker`: `sheetBelow`: `sm`, `md` (default) or `lg`, the theme's breakpoint below which the Sheet's half shows; `trigger`: `outline` (default), `filled`, `ghost`, the opener's look, as the Listbox's; `size`: `sm`, `md`, `lg`. Slots `root`, `dropdown`, `opener`, `list`, `option`. |
710
- | `Sidebar` | shadcn's sidebar with Fluid's collapse, keeping a Model: `Sidebar.init({ id, rows, open?, collapsed?, side?, width? })` (a Tooltip per row id, and the phone's Sheet), folded with `Sidebar.update`, drawn with `Sidebar.view({ model, onMessage, label, groups, header?, footer?, direction?, collapse?, style?, mixins?, tooltip?, sheet? }, h)`. `groups` are `{ id, title?, collapsible?, action?, rows }`, a row a `SidebarLink` (`{ id, label, href, current?, icon?, badge?, action? }`) or a `SidebarBranch` of nested links (`items`). An `action` (`SidebarAction`: `{ label, icon, message }`) is a button at a titled group's heading or beside a link, where it takes the badge's place under the pointer (both show on a touch screen). Groups and branches open like an accordion's, several at once; the current page is `aria-current` and `Sidebar.fluid` glides a marker to it. `collapse: 'offcanvas'` (default) takes the whole column off the page; `'icons'` leaves a rail of icons named in Tooltips (`tooltip`, a Tooltip style). With `sheet` (a Sheet style), an opener shows it in a Sheet on a phone. Shut groups and a collapsed column stay drawn and `inert`. `Sidebar.init({ width: { size?, min?, max? } })` makes the column resizable, its width in the Model: a `resize` handle on its edge drags it, the arrows step it, Enter or a double-click collapses it, and dragged below half `min` it collapses, coming back at the width the drag began at. | `variant`: `sidebar` (flush with the page's edge, the default), `floating` (a card lifted off it), `inset` (no edge, on the surface it stands on, for a page drawn as a card beside it); on a phone with a Sheet the column is its opener alone. Slots `root`, `header`, `footer`, `opener`, `title`, `toggle`, `nav`, `section`, `heading`, `trigger`, `chevron`, `links`, `item`, `branch`, `link`, `icon`, `mark`, `detail`, `label`, `badge`, `action`, `tip`, `indicator`, `highlight`, `resize`. |
711
- | `SignaturePad` | After Zag's: strokes drawn by one pointer over a dashed line and "Sign here", undo, clear, and a typed name instead. `SignaturePad.init({ id, pen? })` holds the strokes (points with pressure, in the pad's coordinates), folded with `SignaturePad.update`. Drawn with `SignaturePad.view({ model, onMessage, label, fallback?, labels?, disabled?, style? }, h)`. `pathOf(stroke, pen)` and `toSvg(model, { color?, font? })` are pure; `RequestedPng({ scale, background })` returns `ExportPng`, answered by `ExportedPng({ url, width, height })` or `FailedExport`. | `surface` (`plain`, `muted`, `dashed`), `size`. Slots `root`, `label`, `control`, `segments`, `stroke`, `guide`, `placeholder`, `typedName`, `controls`, `undo`, `clear`, `fallback`, `fallbackLabel`, `input`. |
712
- | `Skeleton` | `{ label? }`, `role="status"`, a bar a film of the text. `Skeleton.lines({ lines, label? })`, `avatarRow`, `card` and `tableRow({ columns })` draw the shapes content takes, in a `group`. | `shape`: `bar` (default), `circle`; `animation`: `pulse` (default), `shimmer`, `none`. Slots `bar`, `group`. |
713
- | `Slider` | `Slider.view({ id, label, value, onChange, min?, max?, step?, format?, marks?, showValue?, name?, disabled?, style? }, h)`, where `value` is a number or a `{ low, high }` range and `onChange` is handed the same kind. Native `input type="range"` thumbs, so drag, keys, right to left and the form value are the browser's. One number is one thumb across the track, named by the label; a press anywhere on the track moves it. A range is a `group` named by its label holding two thumbs named by `thumbLabels` (default `Minimum` and `Maximum`), each bounded by the other (the low one's `max` is the high value), so the browser stops a drag or a key at the other thumb; `Slider.moved(range, 'low' \| 'high', value, bounds)` snaps, bounds and orders a range, and returns the same range when nothing changed. `marks` are values dotted on the track (`data-filled` where the fill covers them) and `showValue` draws each value, both hidden from assistive technology, which hears `aria-valuetext`. `@foldkit/ui`'s Slider is not adapted: draw its Submodel with Slots of your own. `orientation: 'vertical'` stands it upright; `ticks` dots every step; a mark may be `{ value, label }` (`SliderMark`), its words under the track, those at either end flush with its ends rather than hanging past them. | `tone`: `accent` (default) or `neutral`; `size`: `sm`, `md` (default), `lg`, the thumb's edge; `track`: `thick` (default; the fill reaches each thumb's far edge, Fluid's look), `thin` or `paint` (a track a holder paints, as the color picker's); `value`: `above` (default), `inside` (widens the thumb into a pill; best at `md` or `lg`) or `end` (at the end of the label's row); `label`: `shown` (default) or `hidden`. A Slider is at least 12rem wide; a holder that lays it narrower sets `--fk-slider-min-length`, as the ColorPicker's channels do. Slots `root`, `label`, `control`, `track`, `fill`, `mark`, `value`, `thumb`. |
714
- | `Spinner` | `{ label?, showLabel? }`. `role="status"`; `showLabel` draws the label beside the wheel. A turn is about 720ms times `travel`. | `kind`: `ring` (default), `dots`, `bars`, `pulse`, `orbit`; `size`: `sm`, `md` (default), `lg`; `tone`: `accent` (default), `neutral`, `current`. Slots `wheel`, `part`, `root`, `text`. |
715
- | `Steps` | `Steps.view({ label, steps: { title, description?, icon?, content? }[], current, onSelect?, style? }, h)`: a stepper, an ordered list named by `label`. The step at `current` is `aria-current="step"`, those before it `data-state="complete"` (a check replaces the number), those after `upcoming`. An `icon` stands in the marker for its number; `content` follows the step, beside the line in a vertical stepper. With `onSelect(index)`, completed steps are buttons for going back; steps ahead never are. The application owns `current`. `progress` (0 to 1) fills the connector after the current step when the recipe's connector is a progress bar. | `orientation`: `horizontal` (default) or `vertical`; `size`: `xs`, `sm`, `md`, `lg` (the Avatar's sizes; unset, 1.75rem); `marker`: `number` or `dot`; `connector`: `line` or `progress`. A horizontal row narrower than 32rem shows only the current step's words, wrapping inside an even share so the markers stay evenly spaced (a word longer than 40% of the row is cut), and narrower than 17rem draws them on a line of their own under the markers. Slots `root`, `item`, `step`, `trigger`, `marker`, `number` (the figure in a marker with no icon, trimmed to its digits so it centers in any face), `text`, `title`, `description`, `content`, `connector`. |
716
- | `Table` | The presentational table: `{ columns: { header, value, numeric?, sortKey? }[], rows, rowKey?, caption?, fluid?, sort?, selection?, expansion?, empty? }`. A column with a `sortKey` heads with a button that sends `sort.onSort(column)`, and the sorted column carries `aria-sort`; `Table.nextSort(sort, column)` cycles ascending, descending and none. `selection` puts a checkbox on every row and one in the heading, mixed while only some are chosen; `expansion` opens a row's detail in a row below it (`aria-expanded`, `aria-controls`); `empty` stands across the table while there are no rows (an `Empty.view`). The sort, the chosen and the open rows are the application's. It stands in a `frame`, which scrolls sideways when the table is wider than the screen (under a `static` header; a `sticky` one sticks to the application's scroller, which scrolls it). With `fluid`, one highlight behind the body rows follows the pointer, skipping detail and empty rows. Filtering, column reorder and resize, and virtualized rows stay with `foldkit-data-grid`. | `rows`: `lined`, `striped`, `plain`; `density`: `compact`, `regular`, `comfortable` (none set follows the region); `header`: `static`, `sticky`. Slots `frame`, `highlight` (with `fluid`), `root`, `caption`, `head`, `headerRow`, `headerCell`, `sortButton`, `sortIcon`, `body`, `row`, `cell`, `controlCell`, `checkboxLabel`, `expandButton`, `expandIcon`, `detailRow`, `detailCell`, `emptyRow`, `emptyCell`. |
717
- | `TagsInput` | Zag's tags input, a small Model of its own: `TagsInput.init({ id, tags?, delimiter?, max? })`, folded with `TagsInput.update` (which returns a focus Command), drawn with `TagsInput.view({ model, onMessage, label, placeholder?, disabled? }, h)`. The tags are a list of chips named by the label, each with a `Remove <tag>` button, then a text input. Enter or the delimiter (default `,`) adds the draft split at the delimiter and trimmed, refusing empty and repeated parts, and parts past `max`: a refusal (`TagsInput.Refusal`: `Repeat`, `Empty`, `Full`) is said in a polite `message` (worded by `refusalText`) and shakes the field once, the shake travel-aware; Backspace on an empty draft removes the last tag; a removal returns focus to the input. Keys reach `update`, which decides from its own draft. | No axis; `data-disabled` on `control`. Slots `root`, `label`, `control`, `list`, `tag`, `remove`, `input`, `message`. |
718
- | `ThinkingIndicator` | An assistant at work: `ThinkingIndicator.view({ label?, detail?, active?, icon?, style? }, h)` draws dots, a pulse or the view's icon beside words a band of light sweeps, and a detail line, in a polite status. Keep it drawn with `active: false` before work starts, so what it says when it starts is announced. Every movement holds under reduced motion. | `mark` (`dots`, `pulse`, `none`), `label` (`shimmer`, `plain`, `hidden`), `tone` (`muted`, `accent`). Slots `root`, `mark`, `dot`, `icon`, `label`, `detail`. |
719
- | `ThinkingSteps` | The trace of what an assistant did: `ThinkingSteps.view({ id, steps, open, onToggle, duration?, summary?, openSteps?, onToggleStep?, stateWords?, style? }, h)`. Each step is `{ id, title, state, duration?, detail?, icon?, steps? }`, `state` being `pending`, `running`, `done` or `failed`, said in words too. The button says the running step's title, or "Thought for 4s". Its openness is yours, an `Option<boolean>`: none opens it while a step runs and shuts it once all are done, and the press sends the state the reader asked for. `openSteps` and `onToggleStep` make each step's detail collapsible (`Accordion.toggled`). | `variant` (`plain`, `card`), `connector` (`line`, `none`). Slots `root`, `trigger`, `summary`, `chevron`, `panel`, `list`, `step`, `head`, `marker`, `title`, `state`, `duration`, `body`, `detail`. |
720
- | `Timer` | After Zag's: a countdown (`Timer.init({ id, countdown: true, duration })`) or a stopwatch (`Timer.init({ id, interval? })`), folded with `Timer.update`, whose Commands (`Timer.Stamp`, `Timer.Tick`) read Effect's `Clock`, so TestClock drives a run. `Timer.view({ model, onMessage, label, units?, separator?, labels?, style? }, h)`: a `role="timer"` with each unit in a Slot, one press that says what comes next, and reset. `Timer.phase(model)` is `idle`, `running`, `paused` or `done`; to start at once, return `Timer.update(model, Timer.Message.Pressed({ action: 'start' }))` from `init`. | `tone`, `look`, `progress`, `size`. Slots `root`, `label`, `area`, `item`, `separator`, `controls`, `action`. |
721
- | `Toast` | A stack of toasts, Sonner's: `Toast.init(id, { position?, direction?, duration?, max?, threshold? })`, folded with `Toast.update`, whose `Acted` OutMessage names a pressed action; `Toast.show(model, { type?, title, description?, action?, duration? })` returns the stack and the new toast's `id`, `Toast.settle(model, id, input)` turns a toast (a `loading` one, a promise's) into its outcome, and `Toast.dismiss(model, id)` takes it away; draw it with `Toast.view({ model, onMessage, label?, closeLabel?, expand?, icons?, style? }, h)`. The newest stand in front, spread out while the pointer or focus holds the stack, at most `max` (3) showing; a held stack or a hidden page pauses every countdown, keeping the time left; a swipe toward the edge past `threshold` dismisses one. A toast is spoken in a polite region, an error in an assertive one. A promise toast is `show` with `type: 'loading'`, the work run as a Command, and `settle` on the toast's `id` when its Message comes back. `ToastView` is the fork for toasts that carry their own payload. | `tone`: `plain` (default) or `rich` (each type on its tint). Slots `container`, `entry`, `list`, `icon`, `body`, `title`, `description`, `action`, `close`, `status`, `alert`. |
722
- | `Tour` | Steps anchored beside their targets in the top layer, over a dim with a cutout the target's presses reach. `Tour.init({ id })`, started with `Tour.start(model, config, { opener })` and folded with `Tour.update(config)` (`config` is `{ steps: [{ title, description, target?, placement? }] }`); `Tour.view({ model, config, onMessage, padding?, interactive?, dismissOnOutside?, closeOnEscape?, labels?, direction?, style? }, h)`. The target scrolls into view; Next, Back and the arrows move on, Escape and Skip end it with focus back to the opener, and `update` returns `Ended { completed }`. A step without a target, or whose target is missing, stands in the middle. | No axis. Slots `layer`, `blocker`, `spotlight`, `panel`, `arrow`, `progress`, `title`, `description`, `actions`, `back`, `next`, `skip`. |
723
- | `TreeView` | The APG's and Zag's tree view, a small Model of its own: `TreeView.init({ id, open?, checked? })`, folded with `TreeView.update(nodes, { checkable? })` (curried over the tree, flattened once), drawn with `TreeView.view({ label, model, nodes, onMessage, direction?, style?, mixins? }, h)` over nodes `{ id, label, children?, disabled?, icon?, openIcon? }`. `checkable` (on the view and `update`) gives each row a box: the Model's `checked` holds the leaves, a branch reads checked, mixed or not from them (`TreeView.checksOf`), and Space checks the current row in `update`. One tab stop; Up/Down move through the rows showing, stepping over shut and disabled ones; Right opens or steps in, Left shuts or steps out (swapped under `direction: 'rtl'`, drawn as the root's `dir`); Home/End; a character moves to the next showing row that starts with it; Enter, Space or a click chooses a row and opens or shuts a branch. Keys reach `update`, which decides from its own Model and sends a focus Command. Each item carries `--fk-tree-level`; a shut group stays drawn and `inert`. | `guides`: `none` (default) or `lines`, a guide down each open branch; `data-state` on a branch `item` and its `group`. Slots `root`, `item`, `row`, `chevron`, `checkbox`, `icon`, `label`, `group`. |
724
- | `Typography` | `{ level, text }`. The level chooses the element (`h1`–`h4`, `lead`, `body`, `small`, `muted`, `quote`, `code`, and the interface roles `display`, `title`, `subtitle`, `caption`, `micro` as paragraphs). | `level`, same set; a role is its size and leading on the size ladder. Defaults to `body`. Slot `text`. |
725
- | `VirtualList` | `@foldkit/ui`'s virtual list: `VirtualList.view({ model, items, itemToKey, itemToView, onMessage, overscan?, itemToRowHeightPx? \| dynamicRowHeights?, style?, mixins? }, h)` draws only the rows in view. Its Model is upstream's (`@foldkit/ui/virtualList`'s `init`), kept by the application and folded with that module's `update`. A row's mixins may style it, not handle its events, since it is drawn inside the list's submodel. A bar is drawn beside the list, and `VirtualList.overlayBars` lays it over the list's edge: `root` runs `ScrollBars` for upstream's list, which holds a Mount of its own. | No axis. Slots `root` (the box it scrolls within: 18rem tall by default and as wide as its container, offering 20rem where the container takes its width from it, so the rows drawn as it scrolls never resize it), `row`, `bar`, `thumb`. |
726
- | `WindowList` | A virtual list that scrolls with the window: `WindowList.init({ id, estimatedHeight, unmeasured?, overscan?, viewportHeight?, from? })`, folded with `WindowList.update`, drawn with `WindowList.view({ model, items, itemToKey, itemToView, onMessage, label?, style?, mixins? }, h)`. It draws the rows in view of the document's viewport between spacers as tall as the rest, so the page keeps its own scrolling: the browser restores its offset, a `sticky` header above the list sticks, and Space and End move it. Its one Mount on `root`, `WindowList.Track`, reads where the viewport lies over the list on every scroll, resize and resize of the page (`WindowViewport`), so content above it, or growing above it, counts, and measures each drawn row's border box (`MeasureRows`; space rows with padding: a row is `flow-root`). The rows already drawn when it starts are read at once, so no row leaves before its height is known. A row not yet measured counts `estimatedHeight`, or with `unmeasured: 'mean'` the mean of the rows measured above 0: for rows whose height the window's width decides, which `init` cannot know. A Scene test of a page drawing the list resolves it with `Scene.Mount.resolveAll(WindowList.resolveTrack(onMessage, WindowList.Message.Placed({ top, height })))`, the reading going through the view's own `onMessage`. `WindowList.windowOf(model, keys)` is which rows are drawn, for loading what is in view, and `WindowList.keep(model, keys)` drops the heights of rows that left; a row still drawn is measured again only when it resizes, so keep the keys of the rows drawn. A server's page opens the list at a row with `from` (a page's `?from=`): the window starts at that row, with no overscan above it, and the rows above take no room until `Track` places the list, which gives them their room and scrolls the window by what that moved the first row drawn, so a reader sees the same rows before and after the runtime takes the page over. The first `Placed` sets `from` back to 0, and the list follows the window. For a page without scripts, `WindowList.pageOf(model, keys)` is `{ start, end, previous, next }`: the rows drawn and, as `Option`s, the rows the pages either side open at (`previous` the first whose window reaches this one's start), for links that set `?from=`. Use `VirtualList` for a list in a box of its own. | `Recipes.WindowList`: no look, only the spacers hidden where no script runs (`Utilities.scriptedOnly`), so the rows a server drew lie in the page's flow; `.extend` it with the list's look. Slots `root` (`role="list"`), `spacer` (`data-edge` `start` or `end`, hidden from assistive technology), `row` (`role="listitem"`). |
1081
+ ```ts
1082
+ import { Bundle } from 'foldkit-bundle'
1083
+ import { Reorder } from 'foldkit-primitives/interaction'
1084
+ import { FileUploadSort } from 'foldkit-mixins-ui'
1085
+
1086
+ const SortRows = Bundle.declare(Reorder.bundle, 'rows')
1087
+ const SortModel = Schema.Struct({ ...SortRows.fields, upload: FileUpload.Model })
1088
+ type SortModel = typeof SortModel.Type
1089
+ const SortMessage = defineMessageUnion({
1090
+ ...SortRows.cases,
1091
+ GotUpload: { message: FileUpload.Message },
1092
+ })
1093
+ type SortMessage = typeof SortMessage.Type
1094
+
1095
+ const SortAssembly = Bundle.parent({ Model: SortModel, Message: SortMessage }).assemble(
1096
+ Bundle.parent({ Model: SortModel, Message: SortMessage }).at(SortRows, {
1097
+ onOut: (fact: Reorder.OutMessage) => (model: SortModel) => {
1098
+ const label = (id: string) => model.upload.entries.find(entry => entry.id === id)?.name ?? id
1099
+ const said = FileUpload.announce(model.upload, Reorder.announcement(fact, { label }))
1100
+ return {
1101
+ model: Reorder.OutMessage.match(fact, {
1102
+ Moved: move =>
1103
+ modifyFields(model, {
1104
+ upload: () =>
1105
+ FileUpload.ordered(said, Reorder.apply(FileUpload.ids(model.upload), move)),
1106
+ }),
1107
+ PickedUp: () => modifyFields(model, { upload: () => said }),
1108
+ PassedOver: () => modifyFields(model, { upload: () => said }),
1109
+ PutBack: () => modifyFields(model, { upload: () => said }),
1110
+ }),
1111
+ }
1112
+ },
1113
+ }),
1114
+ )
727
1115
 
728
- ## Recipes
1116
+ const Sorting = Reorder.behavior(SortRows)(FileUploadSlots)<SortModel, SortMessage>({
1117
+ container: 'list',
1118
+ item: 'item',
1119
+ handle: 'grip',
1120
+ items: model => FileUpload.ids(model.upload),
1121
+ orientation: 'both',
1122
+ })
1123
+ // FileUpload.view({ ..., sort: { input: model, mixin: Sorting.mixin }, mixins: FileUploadSort.keepFocus }, h)
1124
+ ```
729
1125
 
730
- The adapters only name slots. `Recipes` gives those slots, and the vocabulary
731
- above, a look: one `Style.recipeFor` per contract, built on the tokens of
732
- `foldkit-mixins/theme`.
733
- Select variants, hand the pieces to `Style.forSlots`, and attach the result
734
- like any other Style:
1126
+ **Keys.** Enter and Space belong to the dialog, and Backspace and Delete on the input
1127
+ remove the last file; `routes` takes the rest. A route on one of those four throws
1128
+ `mixins:key-conflict`, and `FileUpload.conflict(routes)` returns that diagnostic without
1129
+ drawing.
1130
+
1131
+ **Forms.** `name` goes on the real input, and `Sync` runs after every change. A `Stored`
1132
+ entry is not in the input: post its address with a hidden input of your own. Give no
1133
+ `name` when `lanes` sends the bytes. `required` is the native attribute, and a field with
1134
+ only stored files fails it, since the input holds none. `disabled` disables the input
1135
+ and the buttons; `readOnly` draws no picker, remove or grip and keeps the input out of
1136
+ the tab order, so a form still posts.
1137
+
1138
+ **Failure and recovery.** A Model holding a `Local` entry is not JSON: `settled(model)`
1139
+ turns uploaded entries into stored ones, drops every other local file and clears
1140
+ `dragging`, the refusals, the notice and the previews, and the result encodes and decodes.
1141
+ A removed entry takes its button, so focus moves by Command to the next entry's remove
1142
+ button, else the previous, else the input; `FileUpload.without(model, ids)` removes for
1143
+ the application and moves no focus. Dropping files, writing `input.files` and the
1144
+ synthetic drop are proven in Chromium only.
1145
+
1146
+ ### Other fields
1147
+
1148
+ - **NumberField.** What the field draws is what it accepts: `locale` draws and
1149
+ reads that locale's marks (`de-DE`: `1.234,5`); `format` with its `parse`
1150
+ (`Option.none()` for text that is no number, which leaves the value as it was)
1151
+ is for anything else; with neither it is `String` and a plain number. Arrows,
1152
+ PageUp and PageDown, Home and End step it, a typed number commits on change, and
1153
+ the steppers sit out of the tab order and disable at their bound. `name` submits
1154
+ the text the field shows; `required` is the native `required` with
1155
+ `aria-required`.
1156
+ - **OtpField.** `id` names the input for a label or a form, `readOnly` lets the
1157
+ code be read and copied, and `invalid` marks the input `aria-invalid` and each
1158
+ cell `data-invalid`.
1159
+ - **InputCopy.** The view is stateless; answer `onCopy` with the
1160
+ `InputCopy.Copy({ text })` Command, which yields `foldkit-primitives/dom`'s
1161
+ `ClipboardMessage` (`Copied` or `CopyFailed`, never a throw). `InputCopy.Model`
1162
+ keeps the marks: `InputCopy.init({ resetAfter? })` (default 2000ms), folded with
1163
+ `InputCopy.update`, where `Copied` shows it copied and starts the `Reset` Command
1164
+ that sets it back unless a later copy came first, and `Failed` does the same for
1165
+ a refused copy (`failed`, never together with `copied`). Pass `model.copied` and
1166
+ `failed: model.failed`; the status region says `words.failed` (default `Copy
1167
+ failed`) while the button carries `data-failed`. The button is named `Copy
1168
+ <label>`; copied, it reads `Copied` and a polite status region says so.
1169
+ - **PasswordInput.** `onInput` is a closure or a resumable builder's `OnInput`
1170
+ attribute, and `attributes` adds to any Slot (`{ input: [rh.KeepTyped()] }`), as
1171
+ [Form participation](#form-participation) shows.
1172
+
1173
+ ## Choosing a value
1174
+
1175
+ The application keeps the chosen value in its Model. The widgets that submit
1176
+ natively take a `name` (see [Form participation](#form-participation)).
1177
+
1178
+ | Widget | What it is | Recipe and Slots |
1179
+ | --- | --- | --- |
1180
+ | `Checkbox` | `Checkbox.view({ id, checked, onToggle, label, description?, position?, labelAside?, indeterminate?, disabled?, readOnly?, invalid?, name?, value? }, h)` draws the row: the box, its label and a line of description that also describes it; `position: 'end'` puts the words first, `labelAside` is a slot beside the label (a Badge, a Tooltip's trigger). `Checkbox.configure({ base, presets })` states the look once. `Checkbox.toView` stays the adapter, for a layout of your own. | `tone`: `accent` (default), `neutral` (checked in the page's ink), `danger`; `size`; `variant`: `plain` (default), `card` (the row boxed and filled while checked, one press target); `shape`: `square` (default), `round`. Slots `root`, `text`, `heading`, `aside`, `checkbox`, `label`, `description`, `hiddenInput`. |
1181
+ | `CheckboxGroup` | `{ id, legend, options, checked, onToggle, error?, name?, selectAll? }`, each option `RowContent` (`{ value, label, description?, icon?, trailing?, content?, disabled? }`: `description` is text or Html, `icon` a mark inside the label, `trailing` a badge or count after it, `content` the words of your own drawing, `label` still the name). `variant: 'card'` boxes each row and stretches its label over it, so a press anywhere on it chooses it. `CheckboxGroup.configure`. A `fieldset` named by its `legend`, each option the APG's checkbox named by a `label` for it, so a press on the words toggles it. `toggled(checked, value)` is one option's transition; `coverage(options, checked)` is `none`, `some` or `all` (a disabled option counts for neither); `setEnabled(options, checked, on)` is every enabled option or none, a disabled one keeping the state `checked` gives it. `selectAll: { label, onSet }` draws a first row checked, `mixed` or unchecked by `coverage` that controls every option; a press sends `onSet` with `setEnabled`'s values, on unless all already are. `error` is shown under the options: the `fieldset` is described by it and each checkbox is `aria-invalid`. | `variant`: `plain` (default), `list` (checked rows fill, and merge where they stand together); `orientation`: `vertical` (default), `horizontal` (a wrapping row). The checkbox sits on the label's row, so a description does not pull it down. Slots `root`, `legend`, `options`, `option`, `checkbox`, `label`, `description`, `error`. |
1182
+ | `Switch` | `Switch.view({ id, checked, onToggle, label, description?, position?, labelAside?, disabled?, readOnly?, invalid?, name?, value? }, h)`, as the Checkbox's without `indeterminate`; `Switch.configure`. `Switch.draggable(onToggle)` beside the style lets the thumb be dragged; it lives in a file of its own, so a page that never names it ships no part of it. An invalid switch's track is ringed. `Switch.toView` is the adapter. | `tone`: `accent` (default), `neutral`, `danger`; `size`; `variant`: `plain`, `card` as Checkbox. Slots `root`, `text`, `heading`, `aside`, `button`, `label`, `description`, `hiddenInput`. |
1183
+ | `RadioGroup` | `RadioGroup.view({ model, onMessage, legend, options, value, orientation?, hideLegend?, disabled?, readOnly?, invalid?, error?, name? }, h)` over the focus cursor `Bundles.RadioGroup` holds; `options` are `{ value, label, description?, icon?, trailing?, content?, disabled? }` (`RowContent`) and `value` is the application's `Option`, set from the `Selected` the Bundle reports. An `error` draws under the group, makes it `aria-invalid` and describes it. `RadioGroup.configure`. `RadioGroup.readingKeys` reads both arrow pairs whichever way the group stands (see [Right to left](#right-to-left)) and lives in a file of its own. `RadioGroup.toView` is the adapter: each row a `label` around its `option`, carrying the `card` bundle. | `variant`: `plain` (default), `card` (frames each card, filling the checked one); `tone`: `accent` (default), `neutral`, `danger`; `layout`: `stacked` (default), `grid` (rows in columns that fill the room); `size`. The recipe stacks the group unless `aria-orientation` is `horizontal`, and a row wraps. Slots `root`, `legend`, `text`, `group`, `option`, `label`, `description`, `icon`, `trailing`, `error`, `hiddenInput`, `card`. |
1184
+ | `Segmented` | A tray of buttons where pressing selects. `Segmented.view({ id, label, options: { value, label, icon?, iconOnly?, disabled? }[], pressed, onPress, multiple?, orientation?, direction?, name?, disabled? }, h)`; `Segmented.toggled(pressed, value, { multiple, optional })` is the transition `update` applies; `Segmented.configure`. `multiple` is a toggle group, `orientation: 'vertical'` stacks it. `Segmented.fluid` (the gliding pill) is a file of its own. See [Segmented](#segmented). | `tray`: `tray` (default, muted), `plain`, `underline`; `size`: `xs`, `sm`, `md`, `lg`; `width: 'fill'`. Slots `group`, `option`, `label`, `icon`, `content`, `indicator`, `highlight`, `hiddenInput`. |
1185
+ | `Select` | `Select.view({ id, label, options, value?, onChange?, placeholder?, description?, disabled?, invalid?, name? }, h)` draws the native `<select>` from `options: { value, label, group?, disabled? }[]` (neighbours with one `group` sit under an `optgroup`); `Select.configure`. `Select.toView` is the adapter. For icons, descriptions or a check in the list, draw a Listbox as a custom select with `Listbox.parts`. | `size`: `sm`, `md` (default), `lg`; `variant`: `outline` (default), `filled`. Slots `root`, `select`, `label`, `description`. |
1186
+ | `Listbox` | A custom select. `Listbox.view({ model, onMessage, label, choice, value, items?, option?, groupBy?, heading?, placeholder?, trigger?, clear?, disabled?, invalid?, readOnly?, name?, anchor?, direction?, words?, style?, mixins? }, h)` draws it over the interaction state `Bundles.Listbox` holds and a value the application owns, read through a `Choice` (`Listbox.one(items)`, `Listbox.many(items)`, or your own); a row is `RowContent`. The trigger is named "label: chosen rows" and shows the chosen row's icon and label, several labels joined, or the placeholder, muted; `trigger: rows => Html` draws something else for them (a stack of dots). `clear: { onClear, content? }` draws a button inside the trigger while something is chosen, and sends the application's own Message, since the value is the application's. `Listbox.configure({ base, presets })` binds `placeholder`, `anchor`, `direction`, `words`, `style` and `mixins`. A closed listbox submits its value under `name`. `Listbox.fluid` and `Listbox.overlayBars` are files of their own. `Listbox.toView`, `resolve` and `parts` are the adapter over a fork (see [Why some components needed a fork](#why-some-components-needed-a-fork)) for a drawing of your own: `parts(mixins, { h }).option(rowContent)` draws a row and `.trigger(chosenRows, placeholder, shown?)` the button's content. An invalid trigger writes `aria-invalid` and draws the error edge, a disabled one shows no hover, and a portaled panel carries the `direction`. | `width`: `auto` (default), `trigger`; `check`: `end` (default), `start`, `none`; `trigger`: `outline` (default), `filled`, `ghost`; `size`. Slots `root`, `wrapper`, `button`, `clear`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, `rows`, `highlight`, `indicator`, `scrollBar`, `scrollThumb`, the option's and trigger's parts (`itemIcon`, `itemLabel`, `itemDescription`, `itemTrailing`, `itemCheck`, `value`, `valueText`, `chevron`, …). |
1187
+ | `Combobox` | Adapter over a fork, single and multi. `Combobox.view({ model, onMessage, label, choice, value, … }, h)` draws it from options ([State](#state-fold-it-by-hand-or-place-a-bundle)). On the adapter, the view inputs add `chips: {}` (each chosen value a chip in the field, labelled by `itemToDisplayText`, its remove button choosing it again; with `ComboboxView.Multi`, a tags field with suggestions), `clearContent` and `clearLabel` (a clear button while the field has text; `clearContent: null` draws a cross), `words: { clear?, remove? }`, and `empty` (shown, as a polite status, in the list's place while open with nothing to list; a loading line too). `Combobox.parts(mixins, { h }).option(content, query)` draws a `RowContent` and marks the typed text in its label. A closed combobox submits its value under `formName` too. Home and End move the caret in the text: the list's ends are not bound to them. An invalid combobox writes `aria-invalid` on the input and draws the error edge on the field; the clear button is a touch-sized target. | `width`: `trigger` (default), `auto`; `size`. Slots as the Listbox's with `wrapper`, `inputWrapper`, `input`, `toggleButton`, `chips`, `chip`, `chipRemove`, `clearButton`, `empty`, `itemTrailing`. |
1188
+ | `Picker` | A select that is a dropdown on a desktop and a bottom sheet on a phone, with one Model and one set of Messages whatever the width. `Picker.view({ model, onMessage, label, choice, value, items?, option?, groupBy?, heading?, placeholder?, clear?, disabled?, invalid?, name?, anchor?, words?, style?, mixins?, listbox?, sheet?, routes? }, h)` takes the Listbox's `choice` (`Picker.one(items)`, or your own choice of at most one item) and draws both halves from it; `Bundles.Picker` holds the state and reports the `Selected` a choice in either half is. `Picker.configure({ base, presets })`. A small Model remains for the hand-written fold: `Picker.init({ id, sheet? })` and `Picker.update`, which returns `Picker.OutMessage.Chose({ value })`. See [Picker](#picker). | `sheetBelow`: `sm`, `md` (default), `lg`; `trigger`: `outline` (default), `filled`, `ghost`; `size`. Slots `root`, `dropdown`, `opener`, `list`, `option`, `group`, `heading`. |
1189
+ | `CascadeSelect` | After Zag's: one value chosen as a path of ids through nested options. The path is the widget's own value: `Bundles.CascadeSelect` holds it (and the path the keys are on) with the options, `config: { nodes, parents?, loop?, closeOnSelect?, inline? }`, as its args, and reports `Changed` when it moves; `helpers.set(path)` sets it from the parent and reports nothing. `CascadeSelect.view({ model, config, onMessage, label, placeholder?, levels?, layout?, expandOn?, separator?, triggerText?, clear?, option?, name?, disabled?, invalid?, direction?, words?, routes?, style? }, h)`; `option: node => RowContent` draws a row's icon, description and trailing part, `triggerText` the trigger's text for the chosen labels, `config.inline` the tree in place with no trigger. `CascadeSelect.configure`. A hand-written fold stays: `CascadeSelect.init`, `update(config)`. See [CascadeSelect](#cascadeselect). | `size`; `trigger`: `outline`, `filled`, `ghost`; `width`: `trigger`, `auto`. Slots `root`, `trigger`, `valueText`, `chevron`, `clear`, `input`, `layer`, `backdrop`, `panel`, `column`, `heading`, `back`, `item`, `itemIcon`, `itemText`, `itemLabel`, `itemDescription`, `itemTrailing`, `branch`. |
1190
+ | `Slider` | Native `input type="range"` thumbs, so drag, keys, right to left and the form value are the browser's. `Slider.view({ id, label, value, onChange, onCommit?, description?, min?, max?, step?, format?, marks?, showValue?, name?, disabled?, orientation?, ticks?, words? }, h)`; `value` is a number, a `{ low, high }` range or a list of numbers (a thumb each, stopping at its neighbours), and `onChange` is handed the same kind. `words` names a range's thumbs (`low`, `high`) and a list's (`thumb`, with `{index}` and `{count}`). `Slider.configure`. See [Slider](#slider). | `tone`: `accent` (default), `neutral`; `size`: `sm`, `md` (default), `lg`; `track`: `thick` (default), `thin`, `paint`; `value`: `above` (default), `inside`, `end`; `label`: `shown` (default), `hidden`. Slots `root`, `label`, `description`, `control`, `track`, `fill`, `mark`, `value`, `thumb`. |
1191
+ | `AngleSlider` | After Zag's: a dial in degrees, 0 at the top and clockwise. A small Model: `AngleSlider.init({ id, value? })` is the angle and the drag, folded with `AngleSlider.update(layout)`, where `layout` (`step`, `largeStep`, `marks`, `restrictToMarks`) is the object the view spreads in too; `Bundles.AngleSlider` packages both, with the layout as its args (`Bundles.AngleSlider.with({ id, ...layout })`), and `AngleSlider.configure` states the look, layout and `words` (`degrees`, the angle read aloud) once. `AngleSlider.view({ ...layout, model, onMessage, label, name?, format?, valueText?, showValue?, disabled?, readOnly?, invalid? }, h)`. A press or drag sends `Pointed` and `Released`; the APG's slider keys reach `update` as what was pressed, and go round past 0. | `tone`; `track`: `ring`, `plain`, `disc`; `value`: `inside`, `below`; `size`. Slots `root`, `label`, `control`, `needle`, `thumb`, `markers`, `marker`, `markerLabel`, `value`, `input`. |
1192
+ | `Rating` | A `radiogroup` of native radios named by its label, one per star under one name, so the browser's arrows move the choice and a form submits it. `Rating.view({ id, label, value, onChange, max?, labels?, words?, readOnly?, disabled?, name?, precision?, onClear?, showValue? }, h)`; `value` is an `Option`, none is unrated. `words` is the text with blanks (`one`, `other`, `rated`, `notRated`); `labels` names each whole number of stars. Read-only, it is one `img` whose name says the rating, and takes no `onChange`. `Rating.configure`. | `tone`: `warning` (default, gold), `accent`, `danger`, `success`, `info`, `neutral`; `glyph`: `star` (default), `heart`, `circle`; `size`. Slots `root`, `label`, `star`. |
1193
+ | `ColorPicker` | After ReUI's: a saturation and brightness area, hue and alpha Sliders, an eyedropper when the application asks for one (`eyedropper`, default `false`), text in hex, rgb, hsl or oklch, and `presets` as a radio group of swatches. A small Model: `ColorPicker.init({ id, color?, format? })` holds the color, its format and a draft being typed, folded with `ColorPicker.update`. `ColorPicker.view({ model, onMessage, label, presets?, alpha?, eyedropper?, words?, disabled?, slider?, style?, mixins? }, h)`; `ColorPicker.popover({ ...options, popover, onPopover, anchor?, popoverMixins? }, h)` draws it behind a swatch in a Popover. See [ColorPicker](#colorpicker). | `size`. Its Sliders take `Recipes.Slider({ track: 'paint', label: 'hidden' })`. Slots `root`, `label`, `area`, `areaThumb`, `controls`, `eyedropper`, `channels`, `channel`, `swatch`, `fields`, `format`, `input`, `presets`, `preset`, `picker`, `trigger`, `value`. |
1194
+ | `Calendar` | One date system, inline. `Calendar.Selection` is `Single`, `Range` or `Multiple`, held by the Calendar's state (`Bundles.Calendar`), or by the application on the adapter rung. See [Calendar and DatePicker](#calendar-and-datepicker). | `size`; `outside`: `shown` (default), `hidden`; `detail`: `text`, `dot`, unset by default. Slots `frame`, `body`, `main`, `months`, `todayButton`, `aside`, `footer` (what `Calendar.view` lays around the months), `root`, `header`, `grid`, `headerRow`, `previousMonthButton`, `nextMonthButton`, `headingButton`, `previousPageButton`, `nextPageButton`, `columnHeader`, `weekRow`, `dayCell`, `dayButton`, `monthCell`, `monthButton`, `yearCell`, `yearButton`. |
1195
+ | `DatePicker` | A Calendar in a popover, over a fork that keeps upstream's Popover and Calendar composition. A date, a range or many days. See [Calendar and DatePicker](#calendar-and-datepicker). | Slots `wrapper`, `trigger`, `panel`, `backdrop`. |
1196
+
1197
+ ### Segmented
1198
+
1199
+ A single choice (the default) is a radio group: a `role="radiogroup"` of
1200
+ `role="radio"` options with `aria-checked`, one tab stop, and the arrows, Home and
1201
+ End move the choice and the focus. It requires `id`, which prefixes the options'
1202
+ ids, since the arrows move focus by them; `direction: 'rtl'` swaps ArrowLeft and
1203
+ ArrowRight. With `multiple: true` it is a toggle group, shadcn's and Zag's: a
1204
+ `role="group"` of `aria-pressed` buttons, each a tab stop and each filling itself
1205
+ (draw it without `Segmented.fluid`, whose pill marks one). `name` submits the
1206
+ chosen values as hidden inputs; `disabled` turns the group off (`aria-disabled`,
1207
+ no key or press taken). An option takes an `icon`, alone with `iconOnly` (named by
1208
+ `aria-label` and `title`). Its `indicator` and `highlight` Slots, drawn first in
1209
+ the group and given `Segmented.fluid`, slide the pressed option's pill to a new
1210
+ press and move the hover to the option the pointer is on (see [Fluid
1211
+ highlights](#fluid-highlights)); until it runs the pressed option fills itself.
1212
+
1213
+ The recipe: the chosen option takes the accent's tint, flat; that rule lives on the group, in
1214
+ `variants`, so icon tiles take the group piece alone, and an icon button's own background, a
1215
+ variant too, does not hide it. `tray` is a muted tray, a plain row (which sets no `display`: the
1216
+ Builder owns its narrow tabs' visibility; its options tint themselves on hover as every hover is)
1217
+ or an `underline`, each as wide as its options (`width: 'fill'` for a strip as wide as its
1218
+ container). `size` steps the tray and its options on the ladder (`xs` a half step below compact,
1219
+ 24px), the tray's inset counted in, so a tray is as tall as a button beside it.
1220
+
1221
+ The recipe's tray and size are selected per slot:
735
1222
 
736
1223
  ```ts
737
- import { Layers, Style } from 'foldkit-mixins'
738
- import { Theme } from 'foldkit-mixins/theme'
739
- import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
740
-
741
- const DeleteStyle = Style.forSlots(ButtonSlots)(
742
- Recipes.Button({ tone: 'danger', variant: 'outline', size: 'sm' }),
1224
+ const SegmentedStyle = Style.forSlots(SegmentedSlots)(
1225
+ {
1226
+ group: Recipes.Segmented({ tray: 'plain', size: 'sm' }).group,
1227
+ option: Recipes.Segmented({ tray: 'plain', size: 'sm' }).option,
1228
+ },
1229
+ { layer: Layers.standard.layer('app') },
743
1230
  )
1231
+ ```
744
1232
 
745
- const L = Layers.standard
746
- const theme = Theme.make({ accent: { hue: 280, chroma: 0.15, lightness: 60 } })
1233
+ Then a toggle group draws the options from the application's pressed values:
747
1234
 
748
- export const sheet = Style.stylesheet(
749
- L.declare,
750
- L.in('theme', Theme.root(Theme.standard(theme))),
751
- DeleteStyle,
1235
+ ```ts
1236
+ Segmented.view(
1237
+ {
1238
+ multiple: true,
1239
+ label: 'Text style',
1240
+ options: [
1241
+ { value: 'bold', label: 'Bold' },
1242
+ { value: 'italic', label: 'Italic' },
1243
+ ],
1244
+ pressed: model.marks,
1245
+ onPress: mark => Message.ToggledMark({ mark }),
1246
+ style: SegmentedStyle,
1247
+ },
1248
+ h,
752
1249
  )
1250
+ // in update: modifyFields(model, { marks: () => Segmented.toggled(model.marks, mark, { multiple: true }) })
753
1251
  ```
754
1252
 
755
- `DeleteStyle.mixin` then goes to `Button.toView` as in the first example.
1253
+ ### Switch and Checkbox
1254
+
1255
+ `Checkbox.view` and `Switch.view` draw the whole row from options: the control,
1256
+ its label, a line of description that also describes it, and a `labelAside` slot
1257
+ beside the label. The row carries `data-checked`, `data-disabled`, `data-invalid`
1258
+ and `data-position` for the recipe, so `variant: 'card'` (the row boxed, filled
1259
+ while checked, one press target with the label stretched over it) is CSS over the
1260
+ same markup. `Checkbox.toView` and `Switch.toView` stay the adapters, for a
1261
+ layout of your own.
1262
+
1263
+ `Switch.draggable(onToggle)` beside the style lets the thumb be dragged: it
1264
+ follows the pointer past 4px, and on release `onToggle` is sent for the side its
1265
+ middle is on (nothing when that is the side it began on); a click after a drag is
1266
+ swallowed, right to left mirrors it, and a disabled or read-only switch does not
1267
+ drag. The thumb is held where it was let go for 300ms or until `aria-checked`
1268
+ changes, so an `update` that refuses the toggle sends it back. Pass the
1269
+ `onToggle` the view was given.
1270
+
1271
+ ### Picker
1272
+
1273
+ Both halves are drawn and the recipe shows one, so nothing reads the width: the
1274
+ Listbox (its panel kept in place) at or above the breakpoint, and below it an
1275
+ opener whose Sheet lists the options as a listbox, the chosen one (or the first)
1276
+ focused, the arrows, Home and End moving focus, Enter, Space or a tap choosing and
1277
+ closing it. The application keeps the value, read through the Listbox's `Choice`, and
1278
+ `Value` is inferred from the `choice` (`Picker.one(items)`: at most one item,
1279
+ since the Sheet closes at a pick). Rows are `RowContent`; `groupBy` and `heading`
1280
+ group them in the dropdown and in the Sheet; `clear` draws the Listbox's button
1281
+ beside the trigger and beside the opener; `name` submits the choice once.
1282
+ Opening the Sheet closes a Listbox left open. `listbox` takes `Recipes.Listbox`, which also draws the options' and the
1283
+ trigger's content (`Listbox.parts`), and `sheet` takes `Recipes.Sheet`. `routes`
1284
+ are [application key routes](#application-key-routes) on a Sheet option
1285
+ (`item.index` is its place); the dropdown's keys are the Listbox's.
1286
+
1287
+ ### CascadeSelect
1288
+
1289
+ The trigger is a combobox opening a top-layer APG tree, a column per level or one
1290
+ level at a time (`layout: 'drill'`; the columns also drill in on their own when
1291
+ they would not fit the window, measured as the popup opens). `config` is `{ nodes,
1292
+ parents?, closeOnSelect?, loop? }`, the same object the view takes; only an
1293
+ option without children is chosen unless `parents` allows any. The arrows move
1294
+ within and between levels (swapped right to left), Home and End jump to the ends,
1295
+ letters typed within half a second find the row whose label starts with them
1296
+ (`CascadeSelect.Model.typeahead`, cleared by the `QueryExpired` Message), Enter and
1297
+ Space choose (Space opens the closed trigger too). With `name` a form submits one
1298
+ hidden `input` per level of the path (an id may hold any character, so no
1299
+ separator joins them), or one empty input when nothing is chosen.
1300
+
1301
+ The chosen path is the widget's own value, so `Bundles.CascadeSelect` holds it: its
1302
+ args are `{ id, value?, config }`, the `config` object the view takes too, and it
1303
+ reports `Changed { value }` when the path moves (answer `Bundle.ignore` where the
1304
+ parent only reads `model.<field>.value`). `helpers.set(path)` is how the parent
1305
+ writes it: an empty path clears, a path that cannot be chosen is ignored, and
1306
+ nothing is reported. The fixed text is `words` (`placeholder`, `clear`, `back` with
1307
+ `{label}`), and `clear: true` (or `{ content }`) draws the button that empties the
1308
+ value. `option: node => RowContent` draws a row's `icon`, `description` and
1309
+ `trailing` (its `disabled` is the node's); `triggerText: labels => string` collapses a
1310
+ long path on the trigger; `config.inline` draws the tree in place, always open,
1311
+ with no trigger, which Tab focuses (pass the same `config` to `init` or the
1312
+ Bundle). Not built: several chosen paths (a tree with indeterminate branches), a
1313
+ search field in the panel, a footer or side panel, and a loading level.
1314
+
1315
+ ### Slider
1316
+
1317
+ `onCommit` is sent with the value when the reader lets go (the range input's
1318
+ native `change`, which fires on release after a drag and on each key press, where
1319
+ `onChange` has sent every step on the way), and `description` is a line under the
1320
+ slider that each thumb is described by. One number is one thumb across the track,
1321
+ named by the label; a press anywhere on the track moves it. A range is a `group`
1322
+ named by its label holding two thumbs named by `words.low` and `words.high`
1323
+ (default `Minimum` and `Maximum`), each bounded by the other, so the browser stops a drag or a key at
1324
+ the other thumb; `Slider.moved(range, 'low' | 'high', value, bounds)` snaps,
1325
+ bounds and orders a range, and returns the same range when nothing changed.
1326
+ `marks` are values dotted on the track (`data-filled` where the fill covers
1327
+ them) and `showValue` draws each value, both hidden from assistive technology,
1328
+ which hears `aria-valuetext`; a mark may be `{ value, label }` (`SliderMark`), its
1329
+ words under the track, those at either end flush with its ends. `orientation:
1330
+ 'vertical'` stands it upright; `ticks` dots every step. A Slider is at least 12rem
1331
+ wide; a holder that lays it narrower sets `--fk-slider-min-length`. `@foldkit/ui`'s
1332
+ Slider is not adapted: draw its Submodel with Slots of your own.
1333
+
1334
+ ### Rating
1335
+
1336
+ `precision: 0.5` draws two radios a star; a read-only value of any fraction fills
1337
+ its last star part way. `onClear` is sent by a press on the star already chosen;
1338
+ `showValue` shows the rating beside the stars, said as `words` or `labels` say it. Home and End on a
1339
+ star are a key route that focuses the first or last star by its id
1340
+ (`<id>-<value>`) and chooses it, as the arrows would; a read-only or disabled
1341
+ rating draws no route. `name` defaults to `id`. Its tones are the shared `Recipes.Tone` vocabulary.
1342
+
1343
+ ### ColorPicker
1344
+
1345
+ Keys and drags reach `update` as what was pressed, so fast keys each step from the
1346
+ last color. `ColorPicker.popover` takes a Popover made with `contentFocus: true`
1347
+ (it throws for one without): the panel opens on the area's thumb, a press or a
1348
+ drag inside never closes it, and focus leaving it closes one the keys or a finger
1349
+ opened (a mouse's stays open, as upstream's Popover does). `popover` is a file of
1350
+ its own, so a page drawing the picker inline keeps neither upstream's Popover nor
1351
+ its anchoring. The picker's own words are `words` (`ColorPicker.words`: `area`,
1352
+ `saturation`, `brightness`, `hue`, `alpha`, `format`, `input`, `eyedropper`,
1353
+ `presets`), `Bundles.ColorPicker.with({ id, color?, format? })` places its state and
1354
+ reports `Changed { color }`, and `ColorPicker.configure({ base, presets })` fixes the
1355
+ swatches, the sliders' look and the words once.
1356
+
1357
+ The view reads nothing from the environment, so the eyedropper button is the
1358
+ `eyedropper` input, `false` by default on a server and in a browser alike.
1359
+ `ColorPicker.canEyedrop()` is the pure feature test; call it where the
1360
+ application learns its environment and keep the answer in the Model. An
1361
+ application that only runs in a browser reads it in `init`:
756
1362
 
757
- What a recipe assumes and does:
1363
+ ```ts
1364
+ import { Schema } from 'effect'
1365
+ import { ColorPicker } from 'foldkit-mixins-ui'
758
1366
 
759
- - **The page ships the tokens.** Every value is a `var(--fk-…)` reference to
760
- the shipped tokens (`Theme.standard`), so another theme's knobs restyle
761
- every recipe with no new CSS.
762
- - **Bases sit in `components`, variants in `variants`** of `Layers.standard`,
763
- so an application's `app` layer overrides both without specificity fights.
764
- Every declaration is a layered rule and none is inline style, since inline
765
- style beats every layer and could not be overridden this way:
1367
+ const PickerModel = Schema.Struct({ picker: ColorPicker.Model, eyedropper: Schema.Boolean })
766
1368
 
767
- ```ts
768
- const Red = Style.forSlots(ButtonSlots)(
769
- { button: Style.self({ background: 'red' }) },
770
- { layer: L.layer('app') },
771
- )
772
- // Style.stylesheet(L.declare, …, DeleteStyle, Red): Red's background wins.
773
- ```
774
- - **Controls stand on one size ladder.** A button, a field, a select, a tab,
775
- a segmented control, a table row and the rows of a menu, listbox or
776
- combobox are all one rung tall: 36px by default and 28px compact, their
777
- padding, gap and text stepping with them (`Theme.ladder`, read on the
778
- element). `--fk-knob-step: 1` on any element makes everything inside it
779
- compact, the popups it opens included when they stay in the page (an
780
- anchor's `portal: false`, as the gallery's do); upstream portals a panel
781
- out of the page by default, where no region reaches it. A recipe's `size`
782
- (`sm` compact, `md` default, `lg` a half step up at 40px) sets the step on
783
- its own element and beats the region, and a popup's sets it on its panel
784
- too, so it holds portaled or not; unset, which is the default, follows the
785
- region. An icon, checkbox, radio or switch with no size stands on the
786
- ladder's icon rung, 16px or 14px compact.
787
- - **Text comes in roles.** `Theme.role(name)` is a size and its leading,
788
- stepping with the ladder: `display`, `title`, `subtitle`, `body` (a
789
- control's text, 14px on 20), `caption` (badges, tooltips, a table's
790
- headings) and `micro` (keycaps). A tab's and a segmented option's label is
791
- trimmed to its capitals (`text-box`), centering it optically; a pressed
792
- segmented option and a chosen card title turn semibold without moving
793
- anything (the card writes its title in `data-label`; give an option its
794
- text there, `h.DataAttribute('label', 'Week')`, and draw its words in the
795
- `label` Slot, which holds the trim: on the option itself, the hidden copy
796
- took the trim's lower half); and a field's text is 16px on a coarse
797
- pointer, so iOS Safari does not zoom the page into it.
798
- - **A state is a tint, not a surface.** An unfilled control's hover is a
799
- faint film of the state ink over whatever is under it, so it reads on a
800
- muted page, a colored band or an inverted panel; a press lays that film
801
- stronger (`state.press`, 1.75 of the hover's). The ink is the theme's
802
- `--fk-state-ink` (`state.ink`: the element's own text, or the accent's ink
803
- under `surface.hover: 'accent'`) unless a painted surface above names its paint
804
- in the local `--_fk-state-ink`: the accent and danger tones name their
805
- fill, a subtle alert band its ink and a bold one its fill, so a hover on
806
- blue is a deeper blue. The neutral and ink tones name the theme's ink back,
807
- so a neutral control on a band does not take the band's hue, and one
808
- `surface.hover` choice reaches every component. The neutral button is
809
- see-through (`state.tint`), and images carry a hairline inside their edge
810
- (`state.edge`). A popup's rows round concentrically inside its panel
811
- (`Theme.nested`), as a segmented option does inside its tray. A fluid
812
- highlight — Table's, Segmented's, pill Tabs', Nav's, TreeView's, a Card
813
- group's — lays that same film, so `surface.hover` and
814
- `surface.hoverStrength` move it with every other hover.
815
- - **Popups and dialogs enter and leave** when drawn with `@foldkit/ui`'s
816
- `isAnimated` (the Menu component's `Menu.init(id, rows, { isAnimated:
817
- true })`): a popup fades and grows on the fast tier, from the side its
818
- anchor placed it on, and a dialog on the slow one, each leaving on the
819
- quicker exit.
820
- - **A press gives.** Held, every button scales to 98% (the 2% multiplied by
821
- `travel`, so reduced motion holds its size). A solid or primary button's
822
- fill also deepens to its family's `active` and clears the 1px border of its
823
- own color that it stands in, so the fill draws in by 1px a side; an
824
- outline, ghost or icon button lays a deeper film of its tone's ink. A
825
- pressed toggle (`aria-pressed="true"`) rests on its tone's fill, a solid
826
- one on the `active` fill; hovered, a solid toggle keeps it and an unfilled
827
- one takes its tone's hover fill; held, it deepens to the `active` fill; and
828
- its text stays the fill's throughout. A hovered row, tab, menu item or
829
- accordion row darkens while the press is held, and a fluid highlight darkens
830
- with the item it lights (`FluidHover` marks the container `data-fluid-held`).
831
- Chosen rows next to each other in a multiple listbox or
832
- combobox merge into one block. A disabled control fades by
833
- `state.disabledOpacity` (half by default), so one page shows one fade.
834
- - **Raised surfaces nest.** Popups, popovers, date picker panels and toasts
835
- sit two levels above what holds them and dialogs four (`Theme.raise`), each
836
- painted for its level, so a popover in a dialog lands above the dialog: a
837
- step lighter in a dark scheme, the same flat surface with its own shadow in
838
- a light one.
839
- - **State comes from the component's own attributes.** Checked, selected, and
840
- disabled looks read `aria-checked`, `aria-selected`, and `aria-disabled`,
841
- which `@foldkit/ui` already writes; no `whenInput` is needed.
842
- - **Tone and variant are independent.** A tone sets a few private custom
843
- properties that `solid`, `outline`, and `ghost` read — except `primary`,
844
- which is ink by definition, and `icon`, a square one rung of the size
845
- ladder on a side. A tone
846
- also carries the line an `outline` draws: the fill, or for `neutral`, whose
847
- fill is a quiet grey, the page's default line. A neutral Checkbox or Switch
848
- that is on is in the page's ink, not the neutral grey, so it stands out
849
- without a color.
850
- - **On a colored band, unfilled buttons take the band's color.** `outline` and
851
- `ghost` draw their text in the tone's ink, which reads on the page's surface
852
- and not on a band of the accent. A band sets
853
- `Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for its
854
- headings, and their text is the band's.
855
-
856
- Adjust a recipe with `extend` instead of forking it. Base pieces compose per
857
- slot, a variant's pieces compose over the shipped ones, and compounds append:
1369
+ const initPicker = () => ({
1370
+ model: {
1371
+ picker: ColorPicker.init({ id: 'accent' }),
1372
+ eyedropper: ColorPicker.canEyedrop(),
1373
+ },
1374
+ })
1375
+ ```
1376
+
1377
+ A server-rendered application starts `false`, so the served markup and the
1378
+ browser's first render agree, and learns the answer after it has taken over, so
1379
+ the button appears instead of the picker's controls being rebuilt:
858
1380
 
859
1381
  ```ts
860
- const BrandButton = Recipes.Button.extend({
861
- base: { button: Style.class('brand-button') },
862
- variants: { size: { lg: { button: Style.class('brand-button-lg') } } },
1382
+ import { Effect, Schema } from 'effect'
1383
+ import * as Command from 'foldkit/command'
1384
+ import { defineMessageUnion } from 'foldkit/message'
1385
+ import { ColorPicker } from 'foldkit-mixins-ui'
1386
+
1387
+ const EyedropperMessage = defineMessageUnion({
1388
+ LearnedEyedropper: { available: Schema.Boolean },
863
1389
  })
1390
+
1391
+ // Send it from the Command that starts the application, with the first frame drawn.
1392
+ const LearnEyedropperCommand = Command.define('LearnEyedropper', {
1393
+ messages: [EyedropperMessage.LearnedEyedropper],
1394
+ execute: Effect.sync(() =>
1395
+ EyedropperMessage.LearnedEyedropper({ available: ColorPicker.canEyedrop() }),
1396
+ ),
1397
+ })
1398
+ ```
1399
+
1400
+ Either way the view is given `eyedropper: model.eyedropper`. Pressing the button
1401
+ runs `ColorPicker.Eyedrop`, which answers `CancelledEyedropper` and nothing else
1402
+ when the runtime has no eyedropper or the user closes it: a cancel changes
1403
+ nothing and shows nothing.
1404
+
1405
+ `ColorPicker.color('#3b82f6')` reads a literal in code (it throws on a typo);
1406
+ `format`, `parse` (an `Option`) and `toOklch` are pure. `ColorPicker.Eyedrop` and
1407
+ `canEyedrop` are the eyedropper's Command and check.
1408
+
1409
+ ### Calendar and DatePicker
1410
+
1411
+ A Calendar's value is a `Calendar.Selection`: `Single`, `Range` or `Multiple`,
1412
+ a type of the Calendar's own, so the Calendar's state holds it. `Calendar.init`
1413
+ makes that state (the month shown, a second month, the selection, a range's
1414
+ hover preview), `Calendar.update` folds it, and `Calendar.view(options, h)`
1415
+ draws it. `Bundles.Calendar` is the same `init` and `update` for
1416
+ `foldkit-bundle`; [State](#state-fold-it-by-hand-or-place-a-bundle) has a whole
1417
+ example.
1418
+
1419
+ - **Args** (`Calendar.Args`, also `init`'s options): `id`, `today`, and
1420
+ optionally `selection` (default `Calendar.empty('Single')`), `months` (`1` or
1421
+ `2`), `minDate`, `maxDate`, `disabledDaysOfWeek`, `disabledDates` and `locale`
1422
+ (`Calendar.localeOf('de-DE')` reads one from Intl).
1423
+ - **Reading the value**: `Calendar.selectedDate` (a Single's day), `rangeOf`
1424
+ (a range with both ends), `datesOf` (every day held, in order), `firstDate`,
1425
+ `isComplete`. The Bundle reports `Changed { selection }` whenever the
1426
+ selection holds other days; its `set` helper, and `Calendar.set(model,
1427
+ selection)`, set it from the parent and report nothing.
1428
+ - **View options**, all optional beyond `model`, `onMessage` and `label` (the
1429
+ group's name): `weekNumbers`; `caption`: `'grid'` (the default heading
1430
+ button, which opens the month and year grids), `'label'`, or `{ dropdowns: {
1431
+ years?, month? } }`, where `month: 'label'` writes the month as text beside a
1432
+ select of years; `paging`: `'both'`, `'previous'`, `'next'`, `'none'`, or
1433
+ `'end'` for both buttons after the caption; `today: { label, selects? }`, a
1434
+ button that turns back to today's month and, with `selects`, picks it;
1435
+ `presets`, a list of `{ label, selection }` built with `Calendar.lastDays`,
1436
+ `nextDays`, `monthOf` and `day`, or written by hand; `detail: date =>
1437
+ Option<string>`, a line under a day's number; `aside` and `footer`, drawings
1438
+ of the application's own placed beside and under the months; `words`
1439
+ (`Calendar.words` lists them; `{month}`, `{date}`, `{year}`, `{from}` and
1440
+ `{to}` are filled); `style` and `mixins`.
1441
+ - **Two months** share one selection and page together: the previous button is
1442
+ on the first, the next on the second, and dropdowns are on the first.
1443
+ - **A time list, an event list, a second field** is another widget with its own
1444
+ state, drawn into `aside` or `footer`. The Calendar places it and knows
1445
+ nothing of it.
1446
+ - **`Calendar.configure({ base, presets })`** binds `weekNumbers`, `caption`,
1447
+ `paging`, `today`, `presets`, `detail`, `words`, `style` and `mixins`
1448
+ ([Drawing](#drawing-configure-once-call-with-what-differs)). Its `presets`
1449
+ key names sets of options; the view option `presets` lists selections.
1450
+ - **What it costs**: a page that draws through the adapter below keeps neither
1451
+ the state nor this view. Upstream's month and year grids ship with every
1452
+ calendar, since they are inside upstream's one Model and view; `caption:
1453
+ 'label'` hides them and cannot drop them.
1454
+
1455
+ A DatePicker is the same Calendar in a popover, with the same split.
1456
+ `DatePicker.init(args)` makes its state (upstream's picker, the selection, a
1457
+ range's preview), `DatePicker.fold(model, message)` folds it, and
1458
+ `Bundles.DatePicker` packages both; it reports `Changed { selection }` as the
1459
+ Calendar's Bundle does. `DatePicker.view(options, h)` draws it:
1460
+
1461
+ - **`trigger: selection => string`** is the trigger's text, required: a date,
1462
+ both ends of a range, or a prompt. `label` names the trigger.
1463
+ - **`name`** submits each chosen day as an ISO date, a range's start then its
1464
+ end; **`disabled`** and **`anchor`** are the popover's (the default stands
1465
+ under the trigger's start and is not portaled).
1466
+ - **The Calendar's options go to the panel**: `weekNumbers`, `caption`,
1467
+ `paging`, `today`, `presets`, `detail`, `aside`, `footer` and `words`. A
1468
+ picker holds one month.
1469
+ - **Two styles**: `style` of `DatePickerSlots` (wrapper, trigger, panel, backdrop) and
1470
+ `calendarStyle` of `CalendarSlots`, with `calendarMixins` beside it.
1471
+ - **Closing** is the arg `closes`. `'complete'` (the default) closes the
1472
+ popover on the pick, or the preset, that makes the selection whole: a day,
1473
+ or a range's second end. `'manual'` closes on none, which a picker with a
1474
+ time list in `aside` needs. Escape, a press outside and the trigger close it
1475
+ either way.
1476
+ - **`DatePicker.configure({ base, presets })`** binds everything but the
1477
+ wiring, `trigger`, `name`, `disabled` and the two drawings.
1478
+ - The state's fold is `fold` because `DatePicker.update(selection, closes?)`
1479
+ is the adapter's, below.
1480
+
1481
+ The adapter is the rung below, for a calendar an application draws or folds
1482
+ itself. Fold each `SelectedDate` through `Calendar.picked`; `Calendar.empty(mode)` starts
1483
+ a selection and `Calendar.isComplete` says when a picker may close. Spread
1484
+ `Calendar.inputs(selection, mixins, { h })` into upstream `Calendar.view`'s
1485
+ inputs: its `toView` (`Calendar.toView(selection, mixins, { h })`) marks each
1486
+ chosen day `aria-selected`, a range's ends `data-selected` with
1487
+ `data-range-start`/`data-range-end` and every day between `data-in-range`, and its
1488
+ `maybeSelectedDate` (`Calendar.selectedDate(selection)`, a Single selection's day)
1489
+ agrees with it. The grid of a Range or Multiple selection is
1490
+ `aria-multiselectable`. `Calendar.localeOf('de-DE')` reads upstream's `locale`
1491
+ from Intl.
1492
+
1493
+ Options, the fourth argument of `toView`, `inputs` and `resolve`
1494
+ (`CalendarOptions`): `weekNumbers`, `caption: 'label'` or `dropdowns: { model,
1495
+ onShow, years?, month?, words? }` (month and year selects; answer `onShow` with
1496
+ `Calendar.show`), `paging`
1497
+ with `Calendar.alongside(model, other, offset)` for two months side by side,
1498
+ `preview: { date, onPreview }` for a range under the pointer, and `detail: date =>
1499
+ Option<string>` for a line under a day's number (a price, "2 events") that
1500
+ describes its button (`ResolvedDayCell.detail`). `ResolvedDays`' paging buttons
1501
+ are `Option`s, `pagingAtEnd` says both stand after the caption, and its heading
1502
+ is a `caption` of four kinds (`Grid`, `Label`, `Dropdowns`, `YearDropdown`).
1503
+ Presets: `Calendar.lastDays`,
1504
+ `nextDays`, `monthOf`, `day`, drawn by `Calendar.presetsView`.
1505
+
1506
+ A DatePicker also picks a whole `Calendar.Selection`. Fold it with
1507
+ `DatePicker.update(selection, closes?)`, given the selection the application keeps:
1508
+ upstream closes the popover on every day picked, and this keeps it open while the
1509
+ day leaves the selection unfinished (a range's first end, any day of a Multiple
1510
+ selection), reporting `SelectedDate` either way for the application to fold
1511
+ through `Calendar.picked`. Draw it with `DatePickerView.view` taking `selection`
1512
+ and `triggerContent: selection => Html` in place of upstream's
1513
+ `maybeSelectedDate` and `triggerContent`, and `toCalendarView:
1514
+ Calendar.toView(selection, mixins, { h })`. Its `toView` takes no builder of the
1515
+ application's: `DatePicker.toView(mixins, (resolved, h) => …)` hands `draw` the
1516
+ date picker's builder. Under `name`, each chosen day is a hidden input of its own,
1517
+ in order (a range's start, then its end), so `FormData.getAll(name)` reads
1518
+ `[start, end]`; nothing chosen submits the name once, empty.
1519
+
1520
+ ## Menus and overlays
1521
+
1522
+ Panels that stay where they are drawn go in the browser's top layer (see [The top
1523
+ layer](#the-top-layer)). Dialogs, sheets, tours and floating panels return focus
1524
+ by [`focusReturn`](#focus-after-removal); the popups enter and leave as
1525
+ [Exits and reduced motion](#exits-and-reduced-motion) describes.
1526
+
1527
+ | Widget | What it is | Recipe and Slots |
1528
+ | --- | --- | --- |
1529
+ | `Menu` | One menu opened three ways: by a button, at a point (a context menu) or from a long press. A small Model: `Menu.init(id, rows, { isAnimated?, isModal? })`, folded with `Menu.update`. `Menu.view({ model, rows, buttonContent, onMessage, opensAt?, direction?, anchor?, header?, footer?, isRowDisabled?, mixins, submenuMixins? }, h)`, the style being one of the `mixins` (`[MenuStyle.mixin]`). `Bundles.Menu.with({ id, rows, isAnimated?, isModal? })` holds the state (it reads the rows' structure only) and answers `Selected`; `Menu.configure({ base, presets })` fixes the look, `anchor` and `direction` once. See [Menu](#menu). | No axis. Slots `wrapper`, `button`, `backdrop`, `items`, `scroll`, `item`, `group`, `heading`, `separator`, `rows`, `highlight`, `scrollBar`, `scrollThumb`, `label`, `sub`, `chevron`, `check`, `shortcut`, `icon`, `hint`. |
1530
+ | `Menubar` | A row of Menus, shadcn's and the APG's menubar. A small Model: `Menubar.init(ids, { isAnimated?, isModal? })`, folded with `Menubar.update`, whose `Selected` OutMessage names the menu and the row's `value`. `Menubar.view({ label, model, menus, onMessage, direction?, anchor?, routes?, style?, menuMixins? }, h)` (`Bundles.Menubar.with({ ids, isAnimated?, isModal? })` places the Model and reports `Selected` with the menu's index; `Menubar.configure({ base, presets })`), each menu `{ label, rows, isRowDisabled?, header?, footer? }` taking a Menu's rows (none opening a submenu). One trigger is the tab stop; ArrowLeft/ArrowRight (Home/End while all are shut) move it, and with a menu open they open the next on its first row. While one is open, pointing at another opens it, and opening any shuts the rest. | No axis. `Recipes.MenubarMenu` is the Menu recipe with a bar's flat triggers. Slots `bar`, `menu`; each menu's are `MenuSlots`. |
1531
+ | `Dialog` | Adapter over `@foldkit/ui`'s Dialog. See [Dialog](#dialog). | `size`: `sm`, `md` (default), `lg`, `xl`, `full`; `title`: `shown`, `hidden`; `close`: `corner`, `none`; `motion`: `standard`, `none`. Slots `dialog`, `backdrop`, `panel`, `title`, `description`, `initialFocus`, `closeButton`, `handle`, `body`, `scroll`, `scrollBar`, `scrollThumb`, `footer`. |
1532
+ | `Sheet` | A Dialog a finger drags, vaul's Drawer. A small Model: `Sheet.init({ id, side?, points?, opensAt?, dismissible?, isAnimated?, swipe? })`, folded with `Sheet.update`, opened with `Sheet.open` and `Sheet.close`. `Sheet.view({ model, onMessage, style?, mixins?, words?, hasDescription?, covered?, scalesPage?, draw }, h)`. See [Sheet and Drawer](#sheet-and-drawer). | `Recipes.Sheet`: `size`: `sm`, `md` (default), `lg`, `full`; `handle`: `bar` (default), `none`; `title`; `close` and `motion`, as on `Recipes.Dialog`. Slots are `DialogSlots`. |
1533
+ | `Drawer` | A panel docked to the bottom of the screen that peeks or opens beside the page, not over it: no focus trap, backdrop or scroll lock, so the page under it stays live (a modal one is the `Sheet`). A small Model: `Drawer.init({ id, open?, swipe? })`, folded with `Drawer.update`, opened with `Drawer.open` and `Drawer.close`. `Drawer.view({ model, onMessage, label, style?, mixins?, draw }, h)`. | `Recipes.Drawer`: `dock`: `always` (default), `below-lg`, `below-xl`, above which the panel is the column it sits in, with no handle. Slots `panel`, `handle`, `body`, `grip`. |
1534
+ | `Popover` | Adapter. `Popover.anchor(config?)` is the placement. The panel grows from the side it opened on and, with the Popover's `isAnimated`, fades out as it leaves; the open button keeps the hover film. | `arrow`: `shown` (default), `none`. Slots `button`, `panel`, `backdrop`, `arrow`, `layer`. |
1535
+ | `Tooltip` | Adapter. `Tooltip.toView(mixins, { h, id }, draw)` takes the Tooltip's id (`model.id`), whose trigger the arrow points at; `Tooltip.anchor(config?)` is the placement, above by default. | `arrow`: `shown` (default), `none`. Slots `trigger`, `panel`, `arrow`, `layer`. |
1536
+ | `HoverIntent` | Adapter: open and close delays with intent (200ms and 300ms by default), for a hover card or a menu. `anchored: { id, anchor? }` in the context anchors the panel to the trigger in the top layer (`HoverIntent.anchor()` unless given); the trigger takes `HoverIntent.triggerId(id)`, `aria-expanded` and, while open, `aria-describedby` naming the panel, whose id is `HoverIntent.panelId(id)`. `HoverCard` is its recipe. | `HoverCard`: no axis; a trigger read as a link, a raised panel fading in on the fast tier. Slots `trigger`, `panel`, `arrow`. |
1537
+ | `Anchor` | A Mount and a Behavior over `@foldkit/ui/anchor`: `Anchor.behavior(Slots)({ floating, config })` positions a floating slot against a button by id; `Anchor.topLayer(mount)` shows an in-place panel in the top layer around it. | |
1538
+ | `FloatingPanel` | After Zag's: a non-modal window. A small Model: `FloatingPanel.init({ id, rect, open?, min?, max?, grid?, overflow? })` holds its rect, stage, limits and a drag, folded with `FloatingPanel.update()`, or placed with `Bundles.FloatingPanel`; `FloatingPanel.open(model)` focuses it, `openBeside(model, openerId)` opens it beside an element and `close` closes it. `FloatingPanel.view({ model, onMessage, title, content, order?, draggable?, resizable?, closeOnEscape?, controls?, routes?, step?, direction?, words? }, h)`, and `FloatingPanel.configure`. See [FloatingPanel](#floatingpanel). | `header`. Slots `root`, `boundary`, `panel`, `header`, `dragTrigger`, `title`, `controls`, `minimize`, `maximize`, `restore`, `close`, `body`, `handle`. |
1539
+ | `Tour` | Steps anchored beside their targets in the top layer, over a dim with a cutout the target's presses reach. A small Model: `Tour.init({ id, steps })` (a step `{ title, description, target?, placement? }`), started with `Tour.start(model)` and folded with `Tour.update()`, or placed with `Bundles.Tour`. `Tour.view({ model, onMessage, content?, advanceOnClick?, padding?, interactive?, dismissOnOutside?, closeOnEscape?, routes?, words?, direction? }, h)`, and `Tour.configure`. | No axis. Slots `layer`, `blocker`, `spotlight`, `panel`, `arrow`, `progress`, `title`, `description`, `actions`, `back`, `next`, `skip`. |
1540
+
1541
+ ### Menu
1542
+
1543
+ `anchor` is merged over the default `{ placement: 'bottom-start', gap: 4, padding: 8, portal: false }` (no gap at a point): `{ placement: 'top-end' }`. `header` and `footer` are Html drawn in the panel above and below the rows, in the `header` and `footer` slots, and are no row. A row's `content` Html is drawn in place of its words; `label` stays its name and typeahead key.
1544
+
1545
+ A row is an `ItemRow` (`{ value, label }`: the `value` names the row, unique among
1546
+ the menu's rows and their submenus' items, and is what `isRowDisabled`,
1547
+ `Selected` and `Menu.checkChosen` use; the `label` is what is drawn and what
1548
+ typeahead matches, so two rows may read alike; type the values by a union with
1549
+ `Row<'a' | 'b'>`), a `CheckRow` (`check: 'checkbox' | 'radio'`, `checked`:
1550
+ `menuitemcheckbox` or `menuitemradio` with `aria-checked`; choosing it sends
1551
+ `Selected` and leaves the menu open, the application keeping `checked`, a radio
1552
+ row's group being the rows of its `group`), or a `SubmenuRow` (`items`, each an
1553
+ `ItemRow`, one level deep, and `isItemDisabled?` asked of their values). Any row
1554
+ may name a `group` (rows next to each other with one group stand under its
1555
+ heading, a separator between groups), a `shortcut` (keys drawn at the row's end as
1556
+ Kbd with the view's `kbd`, named in `aria-keyshortcuts`; the menu binds nothing),
1557
+ an `icon` (an `Html` drawn before the label in the `icon` slot, hidden from
1558
+ assistive technology), a `hint` (a quiet note at the end of the row, before the
1559
+ shortcut, in the `hint` slot) and `tone: 'destructive'` (`data-tone`). A
1560
+ submenu's items take the same parts.
1561
+
1562
+ A submenu's row is a `menuitem` with `aria-haspopup="menu"` and `aria-expanded`;
1563
+ ArrowRight, Enter or Space opens it on its first row, ArrowLeft or Escape closes
1564
+ it back to the row (under `direction: 'rtl'` the submenu opens on the left and the
1565
+ arrows swap), a pointer resting 150ms opens it, and choosing a leaf closes
1566
+ everything. `Selected` names the row's `value` and the `value` of the submenu's row
1567
+ it came from. `isAnimated` gives the panels upstream's transition marks, for the
1568
+ recipe's fade; `isModal` makes the rest of the page inert while the menu is open.
1569
+ Pass `Menu.fluid` beside the style (in `submenuMixins`, not `mixins`, where rows
1570
+ open submenus).
1571
+
1572
+ `opensAt: 'point'`, with `Menu.target(onMessage, h)` on the area, is a context
1573
+ menu: a right press records its point and the `contextmenu` after it opens the
1574
+ menu there; a finger or a pen held there `Menu.HOLD_MS` (500ms) opens it too, as
1575
+ iOS fires no `contextmenu`, while one that moves 10px is a scroll. Give the area
1576
+ `-webkit-touch-callout: none` and `user-select: none`, or iOS shows its own callout
1577
+ over it. A `@foldkit/ui` Menu the application folds itself, for typed items or
1578
+ groups, is drawn through the panel adapter instead, and opens at a point with
1579
+ `Menu.drawAtPoint` and `Menu.pointTarget` (see [Why some components needed a
1580
+ fork](#why-some-components-needed-a-fork)).
1581
+
1582
+ ### Dialog
1583
+
1584
+ Slots beyond upstream's are this package's: `handle` (the Sheet's grabber,
1585
+ `aria-hidden` unless the Sheet has more than one point, when it is a separator),
1586
+ `body`, `scroll`, `scrollBar`, `scrollThumb` and `footer`. Draw `scroll` and its bar
1587
+ inside `body` and the answers in `footer`, and a body taller than the screen
1588
+ scrolls under the title while the footer stays (`Dialog.overlayBars` beside the
1589
+ style draws the overlay bar).
1590
+
1591
+ - **Context.** `attributes` adds to a bundle before the mixins resolve.
1592
+ `covered: true` marks the panel `data-covered`, for a dialog another was opened
1593
+ from (draw the second inside the first's `dialog`, beside its panel), and the
1594
+ recipe steps it back. `isLeaving: Dialog.isLeaving(model)` draws the panel
1595
+ `inert` for the rest of its exit, so no press or key acts on it (upstream takes
1596
+ the backdrop and close button out of a leaving dialog but leaves the
1597
+ application's own controls live); the Sheet does this itself.
1598
+ - **Alert dialog.** `role: 'alertdialog'` in the context
1599
+ (`Dialog.toView(mixins, { h, role: 'alertdialog' }, draw)`) puts
1600
+ `role="alertdialog"` on the `dialog` bundle. Draw no close button, and drop the
1601
+ Messages `Dialog.isDismissal` names (Escape, the backdrop, the close button) in
1602
+ `update`, so only its own buttons, closing with `@foldkit/ui`'s `close`, answer it.
1603
+ - **Focus.** `Dialog.focusReturn` among the mixins gives focus a place to go when
1604
+ the opener is gone as the dialog closes (see [Focus after
1605
+ removal](#focus-after-removal)). `Dialog.update(model, message)` and
1606
+ `Dialog.open(model)` are `@foldkit/ui`'s `update` and `open` plus one repair: an
1607
+ open that meets the exit (the dialog opened again while it leaves) puts focus back
1608
+ inside it, on the `focusSelector`, the initial-focus mark, else the first control,
1609
+ which a bare upstream `open` does not.
1610
+ - **On-screen keyboard.** `Dialog.keyboard` among the mixins of a dialog or sheet
1611
+ that holds a field measures the keyboard on the panel, and the recipes keep the
1612
+ panel above it (a Dialog shrinks, a bottom Sheet stands on it): iOS Safari and
1613
+ Chrome on Android otherwise leave it under the keys.
1614
+ - **Recipe.** `title: 'hidden'` leaves the heading to a screen reader alone (it
1615
+ still names the dialog, as `display: none` would not). `close: 'none'` leaves the
1616
+ `closeButton` Slot unstyled for an application whose own buttons carry it (the
1617
+ Slot is still the Dialog's, with its `RequestedClose`). `motion: 'none'` opens,
1618
+ closes and steps back at once, backdrop and panel alike, whatever the `motion`
1619
+ knob (reduced motion is as it was). The backdrop is the `overlay.scrim` token.
1620
+
1621
+ ```ts
1622
+ import * as UiDialog from '@foldkit/ui/dialog'
1623
+ import { Dialog, DialogSlots } from 'foldkit-mixins-ui'
1624
+
1625
+ const DialogStyle = Style.forSlots(DialogSlots)(Recipes.Dialog({ size: 'sm' }))
1626
+
1627
+ // The dialog's Model and Messages are @foldkit/ui's: the application folds them
1628
+ // with `Dialog.update`, and opens it with `Dialog.open`.
1629
+ const confirmDialog = (
1630
+ model: UiDialog.Model,
1631
+ toMessage: (message: UiDialog.Message) => Message,
1632
+ h: HtmlBuilder<Message>,
1633
+ ) =>
1634
+ h.submodel({
1635
+ slotId: model.id,
1636
+ model,
1637
+ view: UiDialog.view,
1638
+ viewInputs: {
1639
+ toView: Dialog.toView(
1640
+ [DialogStyle.mixin, ...Dialog.focusReturn],
1641
+ { h, isLeaving: Dialog.isLeaving(model) },
1642
+ dialog =>
1643
+ h.dialog(
1644
+ dialog.dialog,
1645
+ dialog.isVisible
1646
+ ? [
1647
+ h.div(dialog.backdrop),
1648
+ h.div(dialog.panel, [
1649
+ h.h2(dialog.title, ['Discard changes?']),
1650
+ h.div(dialog.footer, [h.button(dialog.closeButton, ['Cancel'])]),
1651
+ ]),
1652
+ ]
1653
+ : [],
1654
+ ),
1655
+ ),
1656
+ },
1657
+ toParentMessage: toMessage,
1658
+ })
864
1659
  ```
865
1660
 
866
- `Recipes.Badge` is a function rather than a variant selection: one style serves
867
- badges in every state, so every tone is present at once and there is no axis
868
- to select. It takes the attribute carrying the value and the value-to-tone
869
- map; values the map leaves out keep the base pill:
1661
+ ### Sheet and Drawer
1662
+
1663
+ **Sheet.** `draw` lays out `DialogSlots`' bundles with `h.div(sheet.handle)` in
1664
+ the panel. The panel stands on `side`'s edge (`data-side`); a drag follows the
1665
+ pointer and settles at the nearest of `points` (the share of the panel shown,
1666
+ ascending; a top or bottom sheet with a point below 1 takes its `size`'s full
1667
+ height, and below its highest point its content holds still, so a swipe up raises
1668
+ it), or, flicked or dragged far enough past the first, closes it, unless
1669
+ `dismissible: false`. The Dialog keeps focus, Escape and scroll lock. With more
1670
+ than one point the handle is a focusable `separator` named by `words.handle`
1671
+ (default `Resize sheet`), its `aria-valuenow` the percent shown: the arrow keys
1672
+ along the edge (the one toward the page raises it: ArrowUp on a bottom sheet,
1673
+ ArrowDown on a top one, ArrowLeft on a right one, ArrowRight on a left one), Home
1674
+ and End step between the points through `Message.SnappedTo { at }` (an index into
1675
+ `points`) and stop at the ends, and Escape still closes; an opened sheet with
1676
+ points takes focus on the handle unless the panel has an initial-focus element.
1677
+ With one point the handle stays decoration, `aria-hidden`; with `handle: 'none'`
1678
+ an application moves the sheet with `SnappedTo` from a control of its own. A
1679
+ leaving Sheet's panel is `inert` until it is gone, and `Sheet.open` is
1680
+ `Dialog.open`'s, so a Sheet opened again while it leaves takes focus back; one
1681
+ whose opener is gone as it closes returns focus through `Dialog.focusReturn`
1682
+ among its mixins. `scalesPage` with `Recipes.sheetPage` on the page beside the
1683
+ sheet, never around it, steps the page back while it is open. The slide and its
1684
+ exit run on `Theme.tokens.motion.sheet` and `sheet-exit`, which default to the
1685
+ `slow` tier and its exit and are multiplied by `travel`: an application that
1686
+ keeps another timing sets them in its tokens (`Theme.define({ motion: { sheet:
1687
+ '500ms', 'sheet-exit': '500ms' } })`), and `sheetPage` follows `sheet`. The panel's
1688
+ padding keeps clear of the safe areas (`Theme.tokens.safe`) on the sides it touches.
1689
+
1690
+ **Swiping (Sheet and Drawer).** `swipe: { from?, flickSpeed?, closeShare? }` says
1691
+ how it is swiped: a finger drags it from anywhere on the panel (`from: 'panel'`, the
1692
+ default), yielding to content that can still scroll its way, so a long one scrolls
1693
+ back to its top and then goes, and a field or `data-no-swipe` starts no drag; a
1694
+ mouse drags it by the handle, and `from: 'handle'` keeps every pointer there. A
1695
+ release faster than `flickSpeed` (0.4px/ms) is a flick, and a slow one goes once
1696
+ dragged `closeShare` (a quarter) of the panel.
1697
+
1698
+ **Drawer.** `draw` lays out `panel`, `handle`, `body` (the body may sit below what
1699
+ else peeks with the handle) and, optionally, `grip`, more to drag it by (a row of
1700
+ tabs: vertical swipes drag it, sideways ones still scroll). A drag follows the
1701
+ finger and lets go open or down by its speed, then by how far it came. A click or
1702
+ Enter on the handle toggles it, and the click a browser sends after a drag does
1703
+ not. `label` names the handle once, and its `aria-expanded` says whether the panel
1704
+ is open, so the name does not change with the state. The body is hidden
1705
+ (`visibility: hidden`) when the slide ends, not as it starts. `Drawer.keepFocus`
1706
+ beside the style moves focus to the handle when the drawer closes with focus in its
1707
+ body, which the hidden body would otherwise drop to the page. The panel's inline
1708
+ style is the drag's: set `--fk-drawer-peek` (default 5rem) and
1709
+ `--fk-drawer-height` (default 70dvh) on an ancestor or in a style. The handle is a
1710
+ 44px target drawn tight to its bar, and the peek stays above the home indicator.
1711
+
1712
+ ### FloatingPanel
1713
+
1714
+ The drag trigger (`role="button"`, named `Move <title>`) moves the panel and eight
1715
+ edges resize it, kept within the viewport; the arrows move it from the drag
1716
+ trigger and resize it from the bottom-end corner; minimize, maximize, restore and
1717
+ close. A press or focus inside returns the `Raised` OutMessage, which the
1718
+ application folds into the `order` its panels stack by with
1719
+ `FloatingPanel.raise(order, id)`. `routes` are [application key
1720
+ routes](#application-key-routes) beside Escape (unless `closeOnEscape` is false);
1721
+ the arrows on the drag trigger and the corner are the panel's own, and a press they
1722
+ handled still reaches the panel. `FloatingPanel.focusReturn` is opt-in and is the
1723
+ one way focus returns.
1724
+
1725
+ The limits (`min`, `max`, `grid`, `overflow`) are `init`'s options and live in the
1726
+ Model, so `FloatingPanel.update()` reads the one copy; `update(limits)` still
1727
+ overrides them for a call. `Bundles.FloatingPanel` places the window with `init`'s
1728
+ options as its args and reports `Raised` in `onOut`; its helpers are `open`,
1729
+ `close`, `openBeside(openerId, { side?, gap? })` and `dock(edge, thickness)`.
1730
+ `openBeside` (also a function of the module) reads the opener's box in a Command
1731
+ and answers `Placed`, which puts the panel there within the limits and the
1732
+ viewport; `rectBeside(anchor, size, options)` is the pure rule, for a place of your
1733
+ own. `Docked { edge, thickness }` lays the panel along an edge of the viewport as
1734
+ measured when it lands; it stays a window and drags away. `controls` names the
1735
+ header's buttons (default all three; restore appears with whichever stage was
1736
+ reached), `words` their names and the drag trigger's and corner's (`Move {title}`,
1737
+ `Resize {title}`), and `FloatingPanel.configure({ base, presets })` fixes the look,
1738
+ words, controls and mixins once.
870
1739
 
871
1740
  ```ts
872
- const EntryStyle = Style.forSlots(EntrySlots)(
1741
+ import { Schema } from 'effect'
1742
+ import { Bundle } from 'foldkit-bundle'
1743
+ import { Bundles, FloatingPanel } from 'foldkit-mixins-ui'
1744
+
1745
+ const Windows = Bundle.compose({ order: Schema.Array(Schema.String) }).pipe(
1746
+ Bundle.withChild('notes', Bundles.FloatingPanel, {
1747
+ args: { id: 'notes', rect: { x: 80, y: 120, width: 320, height: 220 }, grid: 20 },
1748
+ onOut: out => model => ({
1749
+ model: { ...model, order: FloatingPanel.raise(model.order, out.id) },
1750
+ }),
1751
+ }),
1752
+ )
1753
+ ```
1754
+
1755
+ ### Tour
1756
+
1757
+ The target scrolls into view; Next, Back and the arrows move on, Escape and Skip
1758
+ end it, and `update` returns `Ended { completed }`. A step without a target, or
1759
+ whose target is missing, stands in the middle. `routes` are [application key
1760
+ routes](#application-key-routes) on a step, such as a digit jumping to that step,
1761
+ beside the arrows and, unless `closeOnEscape` is false, Escape. `Tour.focusReturn`
1762
+ is opt-in and is the one way focus returns: ending the tour gives focus back to what
1763
+ had it before it started.
1764
+
1765
+ The steps are data in the Model (`init`'s `steps`), so `update()`, `start(model)`
1766
+ and the view read one copy; `update(config)`, `start(model, config)` and the view's
1767
+ `config` override it for a call. `Bundles.Tour` places it with `{ id, steps? }` as
1768
+ its args, reports `Ended` in `onOut`, and `helpers.start` starts it. `content(step,
1769
+ index)` draws a step's words as Html in their place (a key to press, a list), still
1770
+ describing the step's dialog. `advanceOnClick: Tour.advanceOnClick` moves the tour on
1771
+ when the reader presses the step's target through the cutout (not with `interactive:
1772
+ false`); it is a value in a file of its own, so a tour without it loads no listener.
1773
+ `words` (`Tour.words`) are the buttons' names and the step's place, `{step} of
1774
+ {count}`; `Tour.configure({ base, presets })` fixes the look, words and mixins once.
1775
+
1776
+ ### Popover, Tooltip and Hover Card
1777
+
1778
+ Popover, Tooltip and Hover Card are drawn by upstream views whose Mounts this
1779
+ package cannot wrap, so their panels go in the top layer by an element of their
1780
+ own (see [The top layer](#the-top-layer)). A Popover's `layer` Slot, `Popover.anchor()`
1781
+ and `Tooltip.anchor()` give `portal: false` and the placement: 12px and 8px off the
1782
+ trigger, 8px inside the viewport, flipping and shifting. Each draws an `arrow` slot
1783
+ in its panel that points at the trigger.
1784
+
1785
+ **State as Bundles.** Every overlay's state is a Bundle, one file apiece:
1786
+ `Bundles.Dialog.with({ id, isAnimated?, focusSelector?, dismissible? })`,
1787
+ `Bundles.Sheet`, `Bundles.Drawer`, `Bundles.Popover`, `Bundles.Tooltip` (`showDelay`
1788
+ in milliseconds) and `Bundles.HoverIntent` (`openDelay`, `closeDelay`). The upstream
1789
+ ones report `Opened` and `Closed` (a Tooltip `Shown` and `Hidden`) for `onOut`, and
1790
+ `helpers.open` and `helpers.close` are for a control of the application's. A Dialog
1791
+ that is not `dismissible` drops the `RequestedClose` that Escape, the backdrop and
1792
+ its close button send, so only an answer closes it, through `helpers.close`: an
1793
+ alert dialog is that, with `role: 'alertdialog'` in `Dialog.toView`'s context. A
1794
+ Sheet opened by the Dialog's own `RequestedOpen` rests at its `opensAt` point, as
1795
+ `helpers.open` does. Pass `isAnimated: true` and the panel stays drawn while it
1796
+ leaves, so the recipe's fade runs on the way out as on the way in. The drawing
1797
+ stays the adapter's: what a dialog or a popover holds is the application's
1798
+ content, so the examples compose it rather than pass it as options. `Dialog`'s
1799
+ `overlayBars`, `keyboard` and `focusReturn`, `Drawer.keepFocus` and `Toast.keepFocus`
1800
+ are files of their own, so a page that never names one keeps neither its Mount nor
1801
+ the primitive it runs. A Drawer imports no Sheet and no Dialog (`swipe.ts` holds
1802
+ what the two share).
1803
+
1804
+ ## Navigation and structure
1805
+
1806
+ | Widget | What it is | Recipe and Slots |
1807
+ | --- | --- | --- |
1808
+ | `Tabs` | `Tabs.view({ model, onMessage, label, tabs: { value, label, icon?, trailing?, disabled?, panel? }[], value, orientation?, close?, routes? }, h)` draws the tablist and the chosen row's panel; `Bundles.Tabs.with({ id, activationMode? })` holds the focus cursor and reports `Selected`, the chosen `value` being the application's. `Tabs.configure({ base, presets })`. Below it, the adapter: a tab is a flex row, so draw its words in `label` (`h.span(label, [words])`), an icon in `icon`, a Badge after them for a count. `TabsContext.close: { onClose }` makes tabs closable; `TabsContext.routes` takes [application key routes](#application-key-routes). `Tabs.readingKeys` beside the style reads the arrow keys by the tablist's direction. See [Tabs](#tabs). | `variant`: `line` (default), `pill`; `size`; `overflow`: `scroll`, `wrap`; pill-only `selection`: `raised` (default), `tint`; upstream's `orientation: 'Vertical'`. Slots `root`, `tablist`, `tab`, `panel`, `indicator`, `highlight`, `item`, `label`, `icon`, `close`. |
1809
+ | `Nav` | Two layers. `Nav.toView(mixins, { h }, label, draw?)` styles `@foldkit/ui`'s stateless Nav (`nav > ul > li > a`, the current link `aria-current="page"`). `Nav.view({ model, entries, label, onMessage, orientation?, direction?, routes?, panelRoutes?, mixins? }, h)` is a navigation menu with panels of link columns; a link and a panel link take `icon` (Html before the words, in the `icon` slot, hidden from assistive technology) and a panel takes `footer` (Html after its groups, in the `panelFooter` slot). A small Model: `Nav.init(id)`, folded with `Nav.update`, or placed as `Bundles.Nav.with({ id })`; `Nav.configure({ base, presets })`. See [Nav](#nav). | `indicator`: `underline` (default), `pill`; `panel`: `list` (default), `grid` (the groups in equal columns); `orientation: 'vertical'`. Slots `nav`, `list`, `item`, `link`, `trigger`, `chevron`, `panel`, `groups`, `group`, `heading`, `links`, `panelItem`, `panelLink`, `icon`, `panelFooter`, `title`, `description`, `indicator`, `highlight`. |
1810
+ | `Breadcrumb` | `{ words?, steps: { label, href?, current?, icon?, trailing?, labelHidden? }[], separator?, collapse? }`. `words` is `{ label, more, ellipsis }` (defaults `Breadcrumb.words`, merged word by word): the landmark's name (`Breadcrumb`), the ellipsis's name (`Show {count} more`, `{count}` the hidden steps) and its mark (`…`). `current` is text with `aria-current="page"`; the others are links. `trailing` draws after the label (a count), in the `trailing` slot; `labelHidden` draws no words, and the label is the step's accessible name, for an `icon` that says it. `collapse: { max, onExpand }` folds the middle of a long trail into an ellipsis (`Breadcrumb.collapsedOf(steps, max)` is the split); `collapse: BreadcrumbMenu.make({ max, menu: { model, onMessage, mixins } })` makes the ellipsis open a Menu of the hidden steps (a value from its own module, so a trail that opens none loads no Menu; any `CollapseFeature`, `{ max, draw }`, is the same seam for a fold of your own), built from `Breadcrumb.menuRows(steps, max)`, with `Breadcrumb.chosen(steps, max, value)` the step a row leads to (a row's value is its step's place among the hidden steps, so two steps of one label are two rows). | `item`: `plain` (default), `pill`, `button`. `separator`: `slash` (default), `chevron`, `dot`. The separator is drawn after each step but the last, so a wrapped trail never begins a line with one. Slots `root`, `list`, `item`, `link`, `current`, `icon`, `trailing`, `separator`, `ellipsis`, `dots`. |
1811
+ | `Pagination` | `{ page, pageCount, onPage, siblings?, boundaries?, numbered?, ends?, icons?, range?, words? }`. `Pagination.itemsOf(page, pageCount, window?)` is the stops; `Pagination.summaryOf(page, { total, perPage }, summary?)` is `"1–10 of 97"`, drawn before the stops when `range` is given. See [Pagination](#pagination). | `compact`: `narrow` (default, below a 30rem window), `always`, `never`; `shape`: `square` (default), `round`; `treatment`: `ghost` (default), `outline`. Slots `root`, `summary`, `perPage`, `perPageSelect`, `first`, `prev`, `next`, `last`, `page`, `pageCount`, `ellipsis`. |
1812
+ | `Steps` | A stepper, an ordered list named by `label`. `Steps.view({ label, steps: { title, description?, icon?, content?, state?, trailing? }[], current, onSelect?, words?, progress? }, h)`. The step at `current` is `aria-current="step"`, those before it `data-state="complete"` (a check replaces the number), those after `upcoming`. With `onSelect(index)`, completed steps are buttons for going back; steps ahead never are. The application owns `current`. | `orientation`: `horizontal` (default), `vertical`; `size`: `xs`, `sm`, `md`, `lg`; `marker`: `number`, `dot`; `connector`: `line`, `progress`, `segments`; `labels`: `current`, `hidden`. Slots `root`, `item`, `step`, `trigger`, `marker`, `number`, `text`, `title`, `state`, `description`, `content`, `trailing`, `connector`. |
1813
+ | `Sidebar` | shadcn's sidebar with Fluid's collapse. A small Model: `Sidebar.init({ id, rows, open?, collapsed?, side?, width? })`, folded with `Sidebar.update`. `Sidebar.view({ model, onMessage, label, groups, header?, footer?, direction?, collapse?, words?, style?, mixins?, tooltip?, sheet? }, h)`. See [Sidebar](#sidebar). | `variant`: `sidebar` (flush with the page's edge, the default), `floating`, `inset`. Slots `root`, `header`, `footer`, `opener`, `title`, `toggle`, `nav`, `section`, `heading`, `trigger`, `chevron`, `links`, `item`, `branch`, `link`, `icon`, `mark`, `detail`, `label`, `badge`, `action`, `tip`, `indicator`, `highlight`, `resize`, `trailing`. |
1814
+ | `AppShell` | An application's page frame: `AppShell.view({ title, main, brand?, status?, actions?, side?, aside?, asideLabel?, footer?, mainId?, words? }, h)`, and `AppShell.configure({ base, presets })` for the look, `mainId` and words said once. A skip link to the main region, a header bar (the banner) with the title and, at its end, `status` and `actions`, an optional side column for a `Sidebar`'s view, the main region (`id` `main` by default, focusable by script so the skip link moves focus there), an `aside` column at its end (a contents list or details, an `aside` landmark named by `asideLabel`, pinned under the header and below the main region on a phone), and a footer. It holds no state and sends no Message. The header and the side column stay in view while the page scrolls; below `md` the side column sits at the start of the header's row. `Patterns.AppShell` is its contract. | `width`: `full` (default), `contained` (the main region's content kept to the theme's `width.page`). Slots `root`, `skip`, `header`, `brand`, `mark`, `title`, `status`, `actions`, `side`, `main`, `aside`, `footer`. |
1815
+ | `Accordion` | `{ id, items: { id, title, content, disabled? }[], open, onToggle, headingLevel? }`; `Accordion.toggled(open, id, { multiple?, collapsible? })` is the transition `update` applies, the open ids being the application's. Each trigger is a button in a heading naming its panel; a shut panel stays drawn and `inert`. A panel shuts over the time it opens in (default the theme's `moderate`), so switching sections moves both together; `--fk-collapse-duration` sets both and `--fk-collapse-close-duration` the shutting alone, each a time of the theme (`var(--fk-motion-slow)`) so the `motion` and `travel` knobs still apply. TreeView, Sidebar and ThinkingSteps groups share the two properties. The view takes an `icon` in place of the recipe's. An item may also carry `icon` (Html before its title) and `trailing` (after it: a badge, a role); its `title` stays text. `Bundles.Accordion.with({ open?, multiple?, collapsible? })` keeps the open ids and the two rules once, `Accordion.controls(model, onMessage)` is spread into the view, and `Accordion.configure({ base, presets })` fixes the look and heading level. | `variant`: `plain` (default), `bordered`, `separated`, `filled`, `ghost`; `separators`: `on`, `off`; `indicator`: `chevron`, `plus`; `indicatorPosition`: `end`, `start`; `active`: `none`, `trigger`, `item`. Slots `root`, `item`, `heading`, `trigger`, `leading`, `label`, `trailing`, `chevron`, `icon`, `panel`, `body`, `content`. |
1816
+ | `Disclosure` | `Disclosure.view({ id, isOpen, onToggle, label, content, icon?, peek?, disabled? }, h)` draws the button, its icon and label, and the panel; `@foldkit/ui`'s disclosure keeps no state, so `Bundles.Disclosure.with({ isOpen? })` holds the flag and `Disclosure.controls(model, onMessage)` is spread into the view. `peek` keeps a height of the shut panel as an inert preview. `Disclosure.configure({ base, presets })` binds the look. `toView` is the adapter for a layout of your own. Draw the panel only while open, or through upstream's `animatePanel`, which keeps a shut panel inert and moves its height itself by an inline transition that the recipe overrides with an important rule, so the `motion` knob scales it and reduced motion snaps it. | `variant`: `plain` (default), `bordered`, `ghost`; `indicator`: `chevron` (default), `none`. Slots `root`, `button`, `icon`, `label`, `panel`. |
1817
+ | `TreeView` | The APG's and Zag's tree view. A small Model: `TreeView.init({ id, open?, checked?, checkable? })`, folded with `TreeView.update(nodes)` (curried over the tree, flattened once); `checkable` lives in the Model, so `update` and the view read it from one place (each still accepts it as an override). `Bundles.TreeView.with({ id, nodes, open?, checked?, checkable? })` holds the tree's structure and builds `update` once. `TreeView.view({ label, model, nodes, onMessage, direction?, style?, mixins? }, h)` over nodes `{ id, label, children?, disabled?, icon?, openIcon?, content?, trailing?, action? }`: `content` is drawn in place of the label's text (the label still names the row and is what typing matches), `trailing` after it and `action` at the row's end. `TreeView.configure({ base, presets })` binds the look and glide. See [TreeView](#treeview). | `guides`: `none` (default), `lines`; `data-state` on a branch `item` and its `group`. Each item carries `--fk-tree-level`. Slots `root`, `item`, `row`, `chevron`, `checkbox`, `icon`, `label`, `trailing`, `action`, `group`. |
1818
+
1819
+ ### Tabs
1820
+
1821
+ `Tabs.view` is the usual drawing (rows with a mark, words, a trailing Html and a panel; `orientation: 'vertical'` lays the panel beside the tabs; `close` and `routes` as below); it takes `mixins: [...Tabs.fluid]` as a value, so a page that never passes it never loads what glides the indicator. Its `root` slot holds the tablist and the panel. `Tabs.toView` stays the lower rung for a drawing of your own.
1822
+
1823
+ `TabsContext.close: { onClose }` gives each tab a close button (no tab stop, hidden
1824
+ from assistive technology) and Delete, named in `aria-keyshortcuts`; answer with
1825
+ `Tabs.closing(tabs, chosen, closed)`, which gives the tabs left, the tab chosen
1826
+ and the index to focus with `FocusTab`. `TabsContext.routes` takes keys the
1827
+ application answers on a tab, such as F2 renaming it, beside Delete: the input is
1828
+ the tab's `TabInfo`, and a tab with no key to answer draws no keydown at all.
1829
+ `overflow: 'scroll'` is one line with its edges fading; `'wrap'` is a grid of equal
1830
+ columns that fills the row and falls to fewer columns, no tab cut off (a column is
1831
+ no narrower than three control heights; `.extend` the tablist's `--_fk-tab-min` to
1832
+ change it). `selection: 'tint'` is the accent's tint and ink instead of the raised
1833
+ pill, as a pressed Segmented option is; upstream's `orientation: 'Vertical'` stands
1834
+ the rule at the tabs' inline end. `Tabs.fluid` glides the indicator (see [Fluid
1835
+ highlights](#fluid-highlights)).
1836
+
1837
+ ### Nav
1838
+
1839
+ The navigation menu shows its panels in the top layer, with the APG's
1840
+ disclosure-navigation keys (Escape, ArrowDown into a panel, the arrows, Home and End
1841
+ along the row; a press outside and focus leaving close it). A trigger names its
1842
+ panel in `aria-controls` only while the panel is drawn, and links are keyed by place
1843
+ as well as address, so two links to one address do not collide. A panel's `groups`
1844
+ are `{ label, href, description?, current? }` columns. `routes` takes
1845
+ [application key routes](#application-key-routes) on the top-level links and
1846
+ triggers, beside the row's own: the input is the entry and `item.index` its place;
1847
+ `panelRoutes` takes keys on a panel's links, where the input is the link and
1848
+ `item.index` its place among the panel's links. `Nav.fluid` glides a line to the
1849
+ current link and a faint pill to the one the pointer nears.
1850
+
1851
+ ### Pagination
1852
+
1853
+ Fewer than two pages draws no stops; with a `range` it still draws the summary and
1854
+ the page-size select. `range.choose: { sizes, onPerPage }` adds a select of
1855
+ rows per page (labelled `words.perPage`, `Rows per page`) that sends `onPerPage` with the
1856
+ size; the application sets `perPage` and a page that keeps its rows in view.
1857
+ `numbered: false` leaves previous and next alone; `ends` draws first and last.
1858
+ `icons: { first?, previous?, next?, last? }` draws an Html in place of a stop's word, which stays the button's accessible name.
1859
+ `Pagination.configure({ base, presets })` fixes the style, words, windows, `ends`, `numbered` and `icons` once.
1860
+ `words: { label, first, previous, next, last, stop, ellipsis, ofCount, perPage, summary }` (`Pagination.words`, merged word by word) is every word it says, as text with blanks: `stop` is `"{word} page"` (each stop's name), `ofCount` ` / {count}`, `summary` `"{from}–{to} of {total}"`, for another
1861
+ language. A stop at an end is `aria-disabled`, not `disabled`, so it keeps focus and
1862
+ sends nothing. The current stop reads `aria-current` and holds ` / 12` in a
1863
+ `pageCount` span hidden from assistive technology; compact shows only that stop and
1864
+ no ellipses.
1865
+
1866
+ ### Steps
1867
+
1868
+ The marker is hidden from assistive technology, so `words: { complete?, current?,
1869
+ upcoming? }` (defaults `Steps.words`: `Completed`, an empty word that says nothing,
1870
+ `Upcoming`; the current step's `aria-current="step"` already says it) say each step's state in text after its
1871
+ title, in the `state` slot. `progress` (0 to 1) fills the connector after the
1872
+ current step when the recipe's connector is a progress bar. A horizontal row
1873
+ narrower than 32rem shows only the current step's words, wrapping inside an even
1874
+ share so the markers stay evenly spaced (a word longer than 40% of the row is cut),
1875
+ and narrower than 17rem draws them on a line of their own under the markers.
1876
+
1877
+ A step may state its own `state` (`complete`, `current`, `upcoming`, `loading` or `error`) over the one
1878
+ `current` gives it: a later step already complete, the one being taken `loading`, a step that
1879
+ `error`ed. `aria-current` still follows `current`, and each state has a word (`loading`: `In progress`,
1880
+ `error`: `Failed`). A step's `trailing` Html (a time, a badge) ends its row in the `trailing` slot, and
1881
+ the recipe's `labels: 'current'` keeps only the current step's words beside its marker, `'hidden'` none,
1882
+ the rest left to a screen reader. `Steps.configure({ base, presets })` fixes the style and words once.
1883
+
1884
+ ### Sidebar
1885
+
1886
+ `groups` are `{ id, title?, collapsible?, action?, rows }`, a row a `SidebarLink` (`{
1887
+ id, label, href, current?, icon?, badge?, action? }`) or a `SidebarBranch` of nested
1888
+ links (`items`). An `action` (`SidebarAction`: `{ label, icon, message }`) is a button
1889
+ at a titled group's heading or beside a link, where it takes the badge's place under
1890
+ the pointer (both show on a touch screen). Groups and branches open like an
1891
+ accordion's, several at once; the current page is `aria-current` and `Sidebar.fluid`
1892
+ glides a marker to it. `collapse: 'offcanvas'` (default) takes the whole column off
1893
+ the page; `'icons'` leaves a rail of icons named in Tooltips (`tooltip`, a Tooltip
1894
+ style; a rail that draws a row `init`'s `rows` did not list throws, since a Tooltip
1895
+ is state only `init` can make). With `sheet` (a Sheet style), an opener shows it in a
1896
+ Sheet on a phone. Shut groups and a collapsed column stay drawn and `inert`.
1897
+ `Sidebar.init({ width: { size?, min?, max? } })` makes the column resizable, its
1898
+ width in the Model: a `resize` handle on its edge drags it, the arrows step it, Home
1899
+ collapses it (a collapsed one leaves the key alone) and End goes to the widest, Enter
1900
+ or a double-click collapses it, and dragged below half `min` it collapses, coming
1901
+ back at the width the drag began at.
1902
+
1903
+ A row and a nested link take `RowContent`'s parts: `content` drawn in place of the
1904
+ label's text (the label still names it), and `trailing` Html at its end in a
1905
+ `trailing` Slot (a key, a status dot), which gives way to the row's action under the
1906
+ pointer as the badge does. `words` (`Sidebar.words`: `show`, `hide`, `open`,
1907
+ `resize`, each with `{label}`) name the toggle, the phone's opener and the resize
1908
+ handle. A group shuts over the time it opens in. `Sidebar.fluid` and the Slots are
1909
+ files of their own, so a sidebar without the glide keeps no `FluidHover`.
1910
+
1911
+ ### TreeView
1912
+
1913
+ One tab stop; Up/Down move through the rows showing, stepping over shut and disabled
1914
+ ones; Right opens or steps in, Left shuts or steps out (swapped under `direction:
1915
+ 'rtl'`); Home/End; letters typed within 500ms of each other find the next showing row
1916
+ whose label starts with all of them (`TreeView.Model.typeahead`, cleared by the
1917
+ `QueryExpired` Message, which an application that wraps the Messages passes through to
1918
+ `update`); `*` opens every row beside the current one that holds rows; Enter, Space or
1919
+ a click chooses a row and opens or shuts a branch. Keys reach `update`, which decides
1920
+ from its own Model and sends a focus Command. A shut group stays drawn and `inert`.
1921
+
1922
+ `checkable` (on the view and `update`) gives each row a box: the Model's `checked`
1923
+ holds the leaves, a branch reads checked, mixed or not from them
1924
+ (`TreeView.checksOf`), and Space checks the current row in `update`. The Model's
1925
+ `checked` is the one owner: the checked rows that hold no rows. An application that
1926
+ stores or sends another shape converts at the edge, with two pure functions over the
1927
+ same `nodes`, `TreeView.checkedAs(nodes, checked, 'leaf' | 'branch' | 'trunk')` and
1928
+ `TreeView.leavesOf(nodes, value)`:
1929
+
1930
+ ```ts
1931
+ import { TreeView, type TreeNode } from 'foldkit-mixins-ui'
1932
+
1933
+ const nodes: ReadonlyArray<TreeNode> = [
873
1934
  {
874
- badge: Recipes.Badge({
875
- attribute: 'data-state',
876
- tones: { Published: 'success', Changed: 'warning' },
877
- }).badge,
1935
+ id: 'src',
1936
+ label: 'src',
1937
+ children: [
1938
+ { id: 'button', label: 'button.ts' },
1939
+ { id: 'tree', label: 'tree.ts' },
1940
+ ],
878
1941
  },
879
- )
1942
+ { id: 'readme', label: 'README.md' },
1943
+ ]
1944
+
1945
+ TreeView.checkedAs(nodes, ['button', 'tree', 'readme'], 'branch') // ['src', 'button', 'tree', 'readme']
1946
+ TreeView.checkedAs(nodes, ['button', 'tree', 'readme'], 'trunk') // ['src', 'readme']
1947
+
1948
+ const seeded = TreeView.init({ id: 'files', checked: TreeView.leavesOf(nodes, ['src']) })
1949
+ // seeded.checked is ['button', 'tree']
880
1950
  ```
881
1951
 
882
- Like the variant recipes it reads the shipped tokens and
883
- keeps the base in `components` with each tone in `variants`. A toned pill is
884
- grounded on its tone's `subtle`, which keeps the tone's hue over a tinted page.
1952
+ A row holding rows is listed once every row it holds that holds none is checked, a
1953
+ disabled one included. Ids the tree does not hold are left out of both. Independent
1954
+ checks that do not cascade, and branches whose rows are not loaded yet, are not
1955
+ modelled.
1956
+
1957
+ ### Disclosure
1958
+
1959
+ `Disclosure.view` draws the button and the panel from options (see its row above);
1960
+ the adapter below is the rung for a layout of your own. The recipe draws the button
1961
+ and the panel's box, and `animatePanel` keeps the shut panel inert and moves its
1962
+ height.
885
1963
 
886
- `Recipes.InputGroup` draws a text field with a prefix or suffix, such as an
887
- address's `/`, as one box: `group` carries the border, its hover and the
888
- focus ring (while the control inside has focus), `affix` sits inside it,
889
- muted, and `control` makes the input inside borderless. They are pieces for
890
- your own group, affix and control slots, as `foldkit-mixins-form`'s field
891
- publishes them:
1964
+ <!-- docs-check
1965
+ declare const ToggledDetails: (payload: { readonly isOpen: boolean }) => Message
1966
+ -->
892
1967
 
893
1968
  ```ts
894
- const AddressStyle = Style.forSlots(FieldSlots)({
895
- group: Recipes.InputGroup.group,
896
- affix: Recipes.InputGroup.affix,
897
- text: Style.compose(Recipes.Input({}).input, Recipes.InputGroup.control),
1969
+ import { Disclosure as UiDisclosure } from '@foldkit/ui'
1970
+ import { Style } from 'foldkit-mixins'
1971
+ import { Disclosure, DisclosureSlots, Recipes } from 'foldkit-mixins-ui'
1972
+
1973
+ const DetailsStyle = Style.forSlots(DisclosureSlots)(Recipes.Disclosure({ variant: 'bordered' }))
1974
+
1975
+ const details = (isOpen: boolean, h: HtmlBuilder<Message>) =>
1976
+ UiDisclosure.view(
1977
+ {
1978
+ id: 'details',
1979
+ isOpen,
1980
+ onToggle: isOpen => ToggledDetails({ isOpen }),
1981
+ toView: attributes => {
1982
+ const disclosure = Disclosure.resolve(attributes, [DetailsStyle.mixin], {
1983
+ input: undefined,
1984
+ h,
1985
+ })
1986
+ return h.div(
1987
+ [],
1988
+ [
1989
+ h.button(disclosure.button, ['Shipping details']),
1990
+ disclosure.animatePanel(h.div(disclosure.panel, ['Shipped in two days.'])),
1991
+ ],
1992
+ )
1993
+ },
1994
+ },
1995
+ h,
1996
+ )
1997
+ ```
1998
+
1999
+ ## Showing content
2000
+
2001
+ Stateless views: they draw what the application passes and keep nothing. Hide text
2002
+ with `U.srOnly` from `foldkit-mixins/utilities`.
2003
+
2004
+ | Widget | What it is | Recipe and Slots |
2005
+ | --- | --- | --- |
2006
+ | `Table` | The presentational table. `Table.view({ columns: { header, value, numeric?, sortKey?, rowHeader? }[], rows, rowKey?, caption?, fluid?, words?, sort?, selection?, expansion?, empty? }, h)`. A column's `header` is text or markup, its `footer` draws a totals row, and its `value` returns text or markup. Sorting, selection and expansion are the application's. `fluid: Table.fluid` and `selection.control: Table.checkboxes(style?)` are values you pass: a table that passes neither loads neither the pointer highlight nor Checkbox. `Table.configure` binds a look, words and highlight once. See [Table](#table). | `rows`: `lined`, `striped`, `plain`; `density`: `compact`, `regular`, `comfortable`; `header`: `static`, `sticky`, `hidden` (headings for a screen reader alone); `borders`: `rows`, `cells`; `layout`: `auto`, `fixed`. Slots `frame`, `highlight`, `root`, `caption`, `head`, `headerRow`, `foot`, `footerRow`, `footerCell`, `headerCell`, `sortButton`, `sortIcon`, `body`, `row`, `cell`, `control`, `controlCell`, `checkboxLabel`, `expandButton`, `expandIcon`, `detailRow`, `detailCell`, `emptyRow`, `emptyCell`. |
2007
+ | `Card` | `{ title?, description?, content?, image?, media?, action?, footer?, press?, label?, selected?, disabled?, dismiss?, headingLevel?, recoveryPart?, words? }`. `press` is `Press`: `{ onClick }` or `{ href, external? }`, the one type Item shares. `words`: `dismiss` (`'Dismiss {name}'`, `{name}` the title or label), `dismissAlone`, `dismissMark` and `newTab`. `Card.configure({ base, presets })` returns `{ view, group }`. See [Card and Item](#card-and-item). | `orientation`: `stacked`, `inline`, `overlay` (the image fills the card, the text lies over it on a fade to the card's surface); `surface`: `outlined`, `elevated`, `filled`, `plain`; `padding`: `compact`, `comfortable`, `roomy`, `flush`; `elevation`: `0` to `3`; `divide`: `none`, `header`, `sections` (a hairline edge to edge); `lift`: `none`, `hover`, `zoom` (the picture grows inside its frame). Slots `root`, `image`, `media`, `header`, `title`, `description`, `action`, `content`, `footer`, `overlay`, `dismiss`. |
2008
+ | `Card.group` | `{ cards: (CardView & { key })[], columns?, fluid?, label?, wrap?, cardStyle? }`: a keyed list of cards in up to `columns` (default 1), wrapping to fewer where a column would be narrower than the recipe's `minColumn`. Given `fluid: Card.fluid` (from `card/fluid.ts`, so a page that never names it ships no `FluidHover`), one highlight follows the pointer and a press in a gap presses the highlighted card; without it the group draws no highlight and each card hovers on its own. `wrap(card, source)` draws around each card, such as a link. | `Recipes.CardGroup`: `layout`: `divided` (default), `separated`; `minColumn`: `none`, `sm`, `md` (default), `lg`; `border`: `none`, `outlined`. The highlight is a film over the card the pointer is on, and is that card's hover. Slots `root`, `list`, `item`, `highlight`. |
2009
+ | `Item` | The row primitive: `{ header?, media?, title?, description?, content?, actions?, footer?, press?, label?, selected?, disabled?, words? }`; `content` follows the title and description, and `header` and `footer` are bands across the row, pressable above a pressable one. `words.newTab` says what a link opening a new tab says. `Item.group({ items: (ItemView & { key })[], label?, wrap?, style?, itemStyle? })` is a list of them; `wrap(row, source)` draws around each row. `Item.configure({ base, presets })` returns `{ view, group }`. Field is for form controls. | `variant`: `plain`, `outline`, `muted`; `density`: `comfortable`, `compact`, `roomy`; `media`: `plain`, `icon`, `image`. Slots `root`, `header`, `media`, `content`, `title`, `description`, `actions`, `footer`, `overlay`. `Recipes.ItemGroup({ layout: 'divided' \| 'separated' })` over `ItemGroupSlots` (`root`, `row`). |
2010
+ | `Avatar` | `{ name, src?, picture?, initials?, status?, badges?, words? }`. The root is one `role="img"` named by the person (and the status, "Ada Lovelace, Online"); initials show until the picture covers them. `status` is `online`, `away`, `busy`, `offline`, read from `words`. `src` is a URL; `picture` is a value, `Avatar.picture({ asset, provider, width })` from `foldkit-media` (a file of its own, so a page that passes `src` as text ships no media code), drawn with its 1x and 2x candidates at `width` CSS pixels; a provider with no URL for it leaves the initials. Give one of the two. `Avatar.widthOf(size)` is a size's width in CSS pixels. `Avatar.group({ people, max?, label?, words?, rest?, wrap?, style?, avatarStyle? })` overlaps them and counts the rest as one more avatar (`words.more`, `'{count} more'`); `rest(count)` is what the `+N` disc holds in place of its text, an icon say; `wrap(avatar, person)` draws around each avatar, such as a Tooltip's trigger. `badges: [{ content, place, label? }]` puts a mark on a corner (`top-start`, `top-end`, `bottom-start`, `bottom-end`; the bottom end is the status dot's), hidden from assistive technology, its `label` read with the name. `Avatar.configure({ base, presets })` returns `{ view, group }`. | `size`: `xs` to `xl`; `shape`: `circle`, `rounded`, `square`; `color`: `neutral`, `name` (initials in a hue from the name); `ring`: `none`, `page`, `accent`. Slots `root`, `fallback`, `image`, `status`, `badge`. `Recipes.AvatarGroup({ overlap: 'tight' \| 'loose' \| 'none', lift: 'none' \| 'hover' })` over `AvatarGroupSlots` (`root`); `lift: 'hover'` raises the avatar under the pointer, which `travel` stills. |
2011
+ | `Badge` | `{ text, tone?, icon?, onDismiss?, href?, external?, words? }` writes `data-tone`; `onDismiss` draws a dismiss button, `href` draws a link (never both). | `Recipes.Badge({ appearance?, size? })`: `appearance` `tinted` (default), `dot`, `outline`, `solid`; `size` `sm`, `md`, `lg`. The tone is the word the badge carries (`accent`, `neutral`, `info`, `success`, `warning`, `danger`); `Recipes.badgeTones(attribute, map)` through `extend` maps an attribute of your own. Slots `badge`, `icon`, `dismiss`. |
2012
+ | `Typography` | `{ level, text }` or `{ level, content }`, where `content` is a list of text and `Html` (a link, emphasis) in place of `text`. The level chooses the element (`h1`–`h4`, `lead`, `body`, `small`, `muted`, `quote`, `code`, and the interface roles `display`, `title`, `subtitle`, `caption`, `micro` as paragraphs) and is written as `data-level`. | No `level` axis: the recipe reads `data-level`, so the view's level is the one fact; a role is its size and leading on the size ladder. Slot `text`. |
2013
+ | `Separator` | `{ orientation?, label?, decorative? }`, horizontal by default. A `label` sits between two drawn rules and is read as text; `decorative` is `role="none"`. One style draws both orientations. A vertical rule stretches across a flex or grid row, short of it by the inset, and elsewhere (running text) stands as tall as the letters. | `line`: `solid`, `dashed`, `dotted`; `thickness`: `thin`, `thick`; `spacing`: `none`, `sm`, `md`, `lg`; `inset`: `none`, `sm`, `md`. Slots `rule`, `root`, `label`. |
2014
+ | `Empty` | `{ title, description?, icon?, action? }`. The title takes the `subtitle` role; the icon is `aria-hidden`. `Empty.configure({ base, presets })` binds a look once. | `media`: `icon`, `illustration`; `frame`: `none`, `dashed`, `filled`; `tone`: `neutral`, `danger`; `size`: `compact`, `comfortable`. Slots `root`, `icon`, `title`, `description`, `action`. |
2015
+ | `Skeleton` | `{ label?, inline?, block? }`: `role="status"` named by `label`, and `aria-hidden` without one, so a page of placeholders is not a page of empty live regions. `inline` and `block` are CSS lengths of a lone bar (`--fk-skeleton-inline`, `--fk-skeleton-block`). `Skeleton.lines({ lines, label? })`, `avatarRow`, `card` and `tableRow({ columns })` draw the shapes content takes, in a `group`. `Skeleton.configure({ base, presets })` returns all five with one look. | `shape`: `bar`, `circle`; `animation`: `pulse`, `shimmer`, `none`. Slots `bar`, `group`. |
2016
+ | `Carousel` | The APG carousel. A small Model: `Carousel.init({ id, count?, perView?, loop?, index?, autoplay?, delay?, reducedMotion? })`, folded with `Carousel.update()`: the layout (`count`, `perView`, `loop`) is kept in the Model, so `update` and the view read it from one place (`update(layout)` and the view's `perView` and `loop` still override). `Bundles.Carousel.with({ id, count, ... })` places it. `Carousel.view({ label, model, slides, onMessage, loop?, perView?, picker?, thumbnails?, words? }, h)`, `words` being `Carousel.words`' `slide` (with `{index}` and `{count}`), `previous`, `next`, `picker`, `stop` and `start`, merged key by key; `Carousel.configure({ base, presets })` binds them with the look. See [Carousel](#carousel). | `peek`: `none`, `edge`. Slots `root`, `track`, `slide`, `controls`, `rotation`, `previous`, `next`, `picker`, `dot`, `thumbnail`, `status`. |
2017
+ | `Marquee` | After Zag's: content that scrolls on without a seam. A small Model: `Marquee.init({ id })` holds what it measured and whether it is paused, folded with `Marquee.update`. `Bundles.Marquee` places it with `{ id, paused? }` as its args, and reports nothing. `Marquee.view({ model, onMessage, label, items, side?, speed?, autoFill?, repeat?, delay?, loopCount?, words? }, h)` measures its content (`Resize`) and draws copies to fill the viewport, `inert` after the first and drawn without their `id`s, so a document holds each once. A pointer, focus or its pause press (WCAG 2.2.2) holds it; `Marquee.Message.Paused()` holds it from outside. Its motion is CSS, and under reduced motion the viewport scrolls instead. | `spacing`; `edges`: `fade`, `none`. Slots `root`, `viewport`, `content`, `item`, `pause`. |
2018
+
2019
+ ### Images, icons and codes
2020
+
2021
+ | Widget | What it is | Recipe and Slots |
2022
+ | --- | --- | --- |
2023
+ | `Image` | `{ asset, provider, layout, alt, priority?, sizes? }` from `foldkit-media`. `Image.watchLoad` and `Image.audit` are mixins in files of their own (`image/watchLoad.ts`, `image/audit.ts`), so a page that names neither ships neither. `Image.configure({ base, presets })` binds a layout and a look; a use with no layout from any layer throws. See [Image](#image). | `fit`: `cover`, `contain`; `edge`: `none`, `line`; `ratio`: `auto`, `square`, `video`, `portrait`; `radius`. Slots `frame`, `source`, `image`. |
2024
+ | `Figure` | `{ content, caption? }`: a `figure` holding its content (an `Image.view`, a chart, a code block), then its caption in a `figcaption`, which names the figure for assistive technology by itself; no caption, no `figcaption`. `Figure.configure({ base, presets })` binds a look once. | `align`: `start`, `center`; `caption`: `after` (default), `before` (the caption is drawn above by CSS `order`; the markup keeps it after the content, so a screen reader reads it there). Slots `root`, `caption`. |
2025
+ | `Frame` | `{ title?, headingLevel?, description?, action?, panels, footer? }`: a tray holding several things that belong together, each in a panel of its own (a few Alerts, a list of Items, an accordion's items); the frame places what it is given and understands none of it. `Frame.configure({ base, presets })` binds a look once. Reach for `Card` when there is one thing to hold. | `variant`: `muted` (default, a quiet step off the page), `outline`, `plain`; `padding`: `comfortable` (default), `none` where the panel's content draws its own room; `spacing`: `compact`, `comfortable`, `roomy`; `radius`: `md`, `lg`, `none`. Slots `root`, `header`, `title`, `description`, `action`, `panels`, `panel`, `footer`. |
2026
+ | `AspectRatio` | `{ content? }`. `AspectRatio.configure({ base, presets })` binds a look (a ratio) once. | `ratio`: `square` (default), `video` (16/9), `portrait` (3/4); another ratio is `Recipes.AspectRatio.add({ ratio: { cinema: { frame: Style.self({ aspectRatio: '21 / 9' }) } } })`. The corner reads `radius`. Slot `frame`. |
2027
+ | `Icon` | `{ icon, label?, key?, mark?, style?, mixins? }` or `{ glyph, label?, mark? }`: an `IconData` drawn as inline SVG with `foldkit-media`'s `Icon.draw`, or a drawing of your own (initials, a count, an emoji) in the box; one or the other. A `label` makes it `role="img"`; without one the glyph is `aria-hidden`. `key` parts two copies of one icon on a page. `mark` is a Badge or a dot on the corner, inside the image. | `size`: `xs`, `sm`, `md`, `lg`, `xl` on the type scale; none (the default) stands on the size ladder. `surface`: `outline`, `soft`, `solid`, `raised` makes the box a tile twice the icon's size; `tone`: `accent`, `neutral`, `info`, `success`, `warning`, `danger`; `shape`: `circle`, `square`. Slots `glyph`, `mark`. |
2028
+ | `CodeBlock` | `{ code, tokens?, language?, title?, lineNumbers?, startLine?, gutter?, marks?, wrap?, collapsed?, onLineSelect?, lineAction?, copy?, words? }`. `tokens` are `{ from, to, kind }`, as `foldkit-richtext-code` and `foldkit-richtext-code-shiki` tokenizers return them; each is drawn with `data-kind`, and a token out of order or outside the code throws. Every line number the block hands out counts from `startLine` (default 1). `marks: [{ line, kind }]` writes `data-mark` on a whole line (`added`, `removed`, `highlight`, `error`, `warning`, `dim`, `selected`, or a kind of your own; a mark off the code, or two on a line, throws); `gutter(line)` is a line's gutter text in place of its number (a patch's `+`, two columns of numbers); `wrap` wraps long lines; `collapsed: { lines, onExpand }` draws the first lines and a button that sends `onExpand` (`words.expand`, `{count}`), the expanded state the application's; `onLineSelect(line)` makes each gutter a button (`words.selectLine`, pressed on a line marked `selected`); `lineAction(line)` is an `Option` of Html at the line's end. The gutter draws from `data-number`, so the block's text is the code exactly, bar what `lineAction` adds. `copy: { onCopy?, copied? }`: `onCopy` gets the code, so run `copyText` from `foldkit-primitives`; without it the button has no handler, for a page whose script copies. `CodeBlock.follow`, passed in `mixins`, keeps a growing block's end in view while the reader is at it. `CodeBlock.linesOf` is the cut; a final line break is not a numbered line, and a copy is announced in the `status` slot. | `header`: `bar` (default) or `float` (no bar; the copy button pins to the code's corner); `scheme`: `page` (default) or `dark`. Colors each kind from the theme's `syntax` group and tints each line by its mark across the row; `data-copied` marks a copy done. Slots `root`, `header`, `title`, `copy`, `status`, `body`, `code`, `line`, `gutter`, `token`, `lineAction`, `expand`. |
2029
+ | `QrCode` | After Zag's: `QrCode.view({ id, value, label?, level?, quietZone?, overlay?, words?, style? }, h)`, one `img` named `QR code: <value>` (or `label`), every dark module one SVG `path` over a background that carries the quiet zone. `level` is the error correction, `M` by default and `H` under an `overlay` (a logo at the centre). `QrCode.encode(text, level)` gives the matrix, none when no version holds the text, and `pathOf` its path; both are pure. `QrCode.Download({ id, format, filename, pixels })` saves the drawn code as PNG or SVG in the colors it shows; the overlay is not in the file. | `scheme`: `light` (dark on light on any page), `page`; `size`. Slots `root`, `frame`, `background`, `pattern`, `overlay`, `fallback`. |
2030
+ | `Chart` | After shadcn's Chart. A small Model for the lit point: `Chart.init()`, folded with `Chart.update`. `Chart.view({ id, label, kind, categories, series: [{ name, values, color? }], model, onMessage, description?, format?, legend?, table?, categoryLabel? }, h)`, where `kind` is a value you pass: `Chart.bars` (`stack?`), `Chart.line` (`curve?`, `markers?`) or `Chart.area` (`stack?`, `curve?`, `markers?`), or `Chart.donut` with `slices: [{ name, value, color? }]`, `totalLabel?` and `hole?` (`0` is a pie). A page ships the kinds it names. A `ChartKind` of your own is an object with `entries`, `points`, `head` and `draw`, and gets the title, legend, status line and data table from the chart. See [Chart](#chart). | `height`: `sm`, `md`, `lg`; `grid`: `lines`, `zero`; `indicator`: `dot`, `line`. Slots `root`, `title`, `description`, `legend`, `legendItem`, `swatch`, `body`, `yAxis`, `xAxis`, `yTick`, `xTick`, `plot`, `canvas`, `paths`, `grid`, `cursor`, `bar`, `line`, `area`, `dot`, `slice`, `band`, `center`, `centerValue`, `centerLabel`, `tooltip` and its parts, `status`, `table` and its parts. |
2031
+ | `ImageCropper` | After Zag's: the image fitted in a viewport, a selection that a drag moves and eight handles resize, zoom by a Slider, the wheel, two fingers or `+`/`-`, a pan of the zoomed image, quarter turns, an aspect lock and a round crop. A small Model: `ImageCropper.init({ id, aspect?, shape?, crop?, min?, maxZoom? })` holds the crop, in the turned image's pixels, folded with `ImageCropper.update`. `Bundles.ImageCropper` places it with `init`'s options as its args; an export the application asks for (`RequestedExport`, sent to the placed child) comes back in `onOut` as `ImageCropper.OutMessage`, `Exported { url, width, height }` or `FailedExport { reason }`. `ImageCropper.view({ model, onMessage, label, src, crossOrigin?, controls?, zoom?, words?, disabled? }, h)`. `zoom: ImageCropper.zoomSlider(style?)` draws the zoom Slider, and a cropper given none draws none and ships no Slider (the wheel and `+`/`-` still zoom). `ImageCropper.crop(model)` is the crop in whole pixels (an `Option`); `RequestedExport({ type, quality })` returns the `Export` Command, answered by `Exported({ url, width, height })` or `FailedExport`. Keys (arrows, Shift ×10, Alt to resize) step by screen pixels. | `guides`; `handles`: `all`, `corners`; `viewport`: `landscape`, `wide`, `square`. `zoomSlider`'s style takes `Recipes.Slider({ label: 'hidden' })`. Slots `root`, `label`, `viewport`, `stage`, `pan`, `image`, `selection`, `guides`, `handle`, `controls`, `zoom`, `rotate`, `reset`. |
2032
+ | `SignaturePad` | After Zag's: strokes drawn by one pointer over a dashed line and "Sign here", undo, redo, clear, and a typed name instead. A small Model: `SignaturePad.init({ id, pen?, pointers? })` holds the strokes (points with pressure, in the pad's coordinates) and what undo took, for redo (a new stroke or a clear forgets it), folded with `SignaturePad.update`. `pointers` are the kinds that may draw (`'mouse' | 'pen' | 'touch'`, default all), so `['pen']` ignores a resting palm. `Bundles.SignaturePad` places it with `{ id, pen?, pointers? }` as its args; a PNG the application asks for (`RequestedPng`) comes back in `onOut` as `SignaturePad.OutMessage`, `ExportedPng { url, width, height }` or `FailedExport { reason }`. `SignaturePad.view({ model, onMessage, label, fallback?, name?, words?, disabled? }, h)`. `name` submits the signature with a form, as the SVG `toSvg` writes (empty while there is none). `pathOf(stroke, pen)` and `toSvg(model, { color?, font? })` are pure; `RequestedPng({ scale, background })` returns `ExportPng`, answered by `ExportedPng({ url, width, height })` or `FailedExport`. | `surface`: `plain`, `muted`, `dashed`; `size`. Slots `root`, `label`, `control`, `segments`, `stroke`, `guide`, `placeholder`, `typedName`, `controls`, `undo`, `redo`, `clear`, `fallback`, `fallbackLabel`, `input`, `hiddenInput`. |
2033
+
2034
+ ```ts
2035
+ import { parse } from 'foldkit-media/icons'
2036
+ import { Style } from 'foldkit-mixins'
2037
+ import { AspectRatio, AspectRatioSlots, Icon, IconSlots, Recipes } from 'foldkit-mixins-ui'
2038
+
2039
+ const Frame = Style.forSlots(AspectRatioSlots)(Recipes.AspectRatio({ ratio: 'video' }))
2040
+ const Mark = Style.forSlots(IconSlots)(Recipes.Icon({ size: 'sm' }))
2041
+
2042
+ // `h` is the view's builder. `content` is `Html`.
2043
+ AspectRatio.view({ content: h.span([], ['poster']), style: Frame }, h)
2044
+
2045
+ // An icon as data: an import from `virtual:foldkit-icons/…`, or parsed by a script.
2046
+ const check = parse('<svg viewBox="0 0 24 24" fill="none" stroke="currentColor"><path d="M20 6 9 17l-5-5"/></svg>', 'check')
2047
+ Icon.view({ icon: check, label: 'Done', style: Mark }, h)
2048
+ Icon.view({ icon: check, style: Mark }, h)
2049
+ ```
2050
+
2051
+ `Icons.glyph` is the other tool: a mask on an element that already exists.
2052
+
2053
+ ### Table
2054
+
2055
+ A column with `rowHeader` draws its cells as `th scope="row"`, so a screen reader
2056
+ names a row by it. A column with a `sortKey` heads with a button that sends
2057
+ `sort.onSort(column)`, and the sorted column carries `aria-sort`;
2058
+ `Table.nextSort(sort, column)` cycles ascending, descending and none. A column's
2059
+ `sortKey` keeps the literal it is written as, so `onSort` receives `'name' | 'price'`
2060
+ and not a `string`: a Message field of `Schema.Literals(['name', 'price'])` needs no guard
2061
+ in `update`. Columns written in the call infer it; columns hoisted into a constant go
2062
+ through `Table.defineColumns<Row>()([...])` (or `as const`), and a call that names its
2063
+ type arguments (`Table.view<Row, Message>`) gets `string`. `selection`
2064
+ puts a checkbox on every row and one in the heading, mixed while only some are
2065
+ chosen; `expansion` opens a row's detail in a row below it (`aria-expanded`,
2066
+ `aria-controls`; its buttons' column is headed `Details` for a screen reader,
2067
+ `words.details` renames it); `empty` stands across the table while there are no rows
2068
+ (an `Empty.view`). The sort, the chosen and the open rows are the application's. The
2069
+ table stands in a `frame`, which scrolls sideways when the table is wider than the
2070
+ screen (under a `static` header; a `sticky` one sticks to the application's scroller,
2071
+ which scrolls it). With `fluid: Table.fluid`, one highlight behind the body rows follows the
2072
+ pointer, skipping detail and empty rows. Filtering, column reorder and resize, and
2073
+ virtualized rows stay with `foldkit-data-grid`. A selection draws its boxes through `control: Table.checkboxes(style?)`, which is where Checkbox is imported, and one of your own is an object with a `draw`. A column's `footer` draws a totals row after the body, its control columns left blank; a `header` that is markup holds an icon beside the words; the recipe's `header: 'hidden'` keeps the headings for a screen reader (a table read down its first column), `borders: 'cells'` boxes the cells and `layout: 'fixed'` gives each column an equal share.
2074
+
2075
+ A keyed row that a re-sort moves is taken out of the tree and put back, which
2076
+ blurs the control focused inside it. `FocusRecovery.behavior(TableSlots)({ owner: 'frame',
2077
+ parts: { expandButton: ['same'], sortButton: ['same'], control: ['same'] } })`, given
2078
+ in `mixins`, finds the control again at its new place. A control you draw in a cell is
2079
+ a part when you mark it: `h.DataAttribute(FOCUS_MARK.part, 'control')` and
2080
+ `h.DataAttribute(FOCUS_MARK.key, rowKey)` (`FOCUS_MARK` is from `foldkit-primitives/dom`).
2081
+
2082
+ ```ts
2083
+ import { Option } from 'effect'
2084
+ import { Table, TableSlots } from 'foldkit-mixins-ui'
2085
+
2086
+ interface Product {
2087
+ readonly name: string
2088
+ readonly price: string
2089
+ }
2090
+
2091
+ const Sort = defineMessageUnion({ Sorted: { column: Schema.Literal('name') } })
2092
+ type Sort = typeof Sort.Type
2093
+
2094
+ const ProductsStyle = Style.forSlots(TableSlots)(Recipes.Table({}))
2095
+
2096
+ const productsTable = (
2097
+ rows: ReadonlyArray<Product>,
2098
+ sorted: Option.Option<Table.TableSort<'name'>>,
2099
+ h: HtmlBuilder<Sort>,
2100
+ ) =>
2101
+ Table.view(
2102
+ {
2103
+ columns: [
2104
+ { header: 'Product', sortKey: 'name', rowHeader: true, value: row => row.name },
2105
+ { header: 'Price', numeric: true, value: row => row.price },
2106
+ ],
2107
+ rows,
2108
+ rowKey: row => row.name,
2109
+ sort: { by: sorted, onSort: column => Sort.Sorted({ column }) },
2110
+ style: ProductsStyle,
2111
+ },
2112
+ h,
2113
+ )
2114
+ // in update, on Sorted: modifyFields(model, { sorted: () => Table.nextSort(model.sorted, column) })
2115
+ ```
2116
+
2117
+ ### Card and Item
2118
+
2119
+ `press` is `{ onClick }` or `{ href, external? }`: one button or link stretched over
2120
+ the card (`overlay`, from `press.ts`, shared with Item; its type is `Press`), named by `label` or the title (a pressable
2121
+ card with neither throws); `action`, `footer` and the dismiss button stay pressable
2122
+ above it. `selected` is `aria-pressed` on the button, `aria-current="page"` on the
2123
+ link. `headingLevel` (2 to 6, default 3) is the level of the title's heading. A
2124
+ `disabled` card's overlay is `aria-disabled` and sends nothing, so it stays focusable
2125
+ (a link loses its `href`). `dismiss: { onDismiss, always? }` is revealed on
2126
+ hover and focus unless `always`, and always on a touch screen; its name and mark are
2127
+ `words.dismiss` and `words.dismissMark`. `recoveryPart` marks
2128
+ the dismiss button as a `FocusRecovery` part (see [Focus after
2129
+ removal](#focus-after-removal)). The root carries `data-selected`, `data-disabled`,
2130
+ `data-pressable` and `data-dismissible` (the header then keeps clear of the button).
2131
+
2132
+ In the recipe an `image` bleeds to the card's edges (16:9 when stacked); `media`
2133
+ puts a bare icon (`svg`, `img`) in a tile and lets anything else, an Avatar say, lead
2134
+ at its own size. `elevation` is a step of the surface ladder (lighter in a dark
2135
+ scheme; a contact and an ambient shadow in a light one). `lift: 'hover'` lifts under
2136
+ the pointer, which `travel` stills (not in a `Card.group` given `fluid: Card.fluid`, whose
2137
+ highlight is the hover there). In a group, a card draws no hover of its own, whatever its
2138
+ `surface`; divided cards are usually `surface: 'plain'`.
2139
+
2140
+ An `Item`'s `press` is the same stretched control, named by `label` or the title, with
2141
+ `actions` staying pressable above it; `selected` is `aria-pressed` or `aria-current`.
2142
+ An avatar beside a name and a line is an Item with the avatar as its media. `header` and
2143
+ `footer` are bands across the row above the overlay, for a heading or a note that holds
2144
+ controls of its own. An Item page does not ship `Card` or `FluidHover`: both read
2145
+ `press.ts`.
2146
+
2147
+ ### Carousel
2148
+
2149
+ Previous and next are `aria-disabled` at the ends unless `loop`; a dot per place the
2150
+ track can rest (or `thumbnails` in their place) and a polite status name the slide
2151
+ shown. Each slide is a group named "2 of 5". The track is a CSS scroll-snap scroller,
2152
+ so swipes move it natively, and `ScrollSettle` reports where a swipe rests, so the
2153
+ dots follow the finger. Every press, swipe and timer reaches `update`, which returns
2154
+ the `Carousel.ShowSlide` Command that scrolls the track: do not keep the slide
2155
+ yourself. With `autoplay` it moves on every `delay` (4s), the current dot filling as
2156
+ it waits; it pauses under the pointer, stops when focus arrives by the keys, quiets
2157
+ its status while it rotates, and draws the APG's rotation button first.
2158
+ `reducedMotion` in `init` (the application's reading of `prefers-reduced-motion`,
2159
+ from its flags or a `MediaQuery`; `init` stays pure so a server's Model equals the
2160
+ client's) starts an autoplaying carousel stopped, with the rotation button to start
2161
+ it. A slide out of view is `inert`, so its content takes no focus, which would scroll
2162
+ the track.
2163
+
2164
+ ### Image
2165
+
2166
+ A `picture` with a `source` per format the provider offers and an `img` with its
2167
+ candidates, `sizes`, `width` and `height` (the box is held before the file arrives),
2168
+ lazy unless `priority` (then `fetchpriority="high"`). `alt` is what the image shows in
2169
+ words (a string, or `Image.described(text)`) or `Image.decorative` (`alt=""`,
2170
+ `role="presentation"`), never omitted. `Provider.hosted` takes only a `HashedAsset`, so
2171
+ facts without a content hash are a type error there. The `img` carries
2172
+ `--fk-image-ratio`, `--fk-image-placeholder` (none behind a transparent image) and
2173
+ `data-layout` (`fixed`, `constrained`, `full`); a provider with no URL for the image
2174
+ leaves an empty frame marked `data-unavailable`, which keeps its box and is
2175
+ `role="img"` named by its alt text (hidden when decorative). `--fk-image-focus` places
2176
+ a crop at the asset's focal point. `placeholder: 'detail' | 'average'` chooses how much
2177
+ of a ThumbHash to paint; by default the picture for `priority`, the color otherwise.
2178
+ `Image.watchLoad`, beside the style, marks the `img`'s `data-state` (`loading`,
2179
+ `loaded`, `failed`); the recipe hides a failed image, keeping its box. `Image.audit`,
2180
+ beside the style in a development build, warns in the console of an image drawn wider
2181
+ than its file (blurry) or far narrower (wasted bytes), and of more than one image drawn
2182
+ with `priority`. `Image.preloadsIn` is a `foldkit-ssr` `Head`: the `<link
2183
+ rel="preload">` of each image the rendered page drew with `priority`.
2184
+
2185
+ ### Chart
2186
+
2187
+ The value axis's ticks are round and reach both ends, zero included; the plot is drawn
2188
+ in percentages, so it fills its container's width with nothing measured and renders the
2189
+ same on a server. The pointer lights a category's band and its tooltip, and the plot is
2190
+ a tab stop whose arrows, Home and End step through the points while a polite status says
2191
+ each. The drawing is hidden from assistive technology, which reads a data table,
2192
+ visually hidden unless `table: 'shown'`. Series take `chart-1` to `chart-5` in order, or
2193
+ the `color` they name; a sixth series throws. `kind` is a value you import, so a page ships the kinds it draws: `Chart.bars` (`stack: true` puts one series on another), `Chart.line` and `Chart.area` (`curve: 'step'` runs level to the next category before it rises; `markers: 'always'` puts a dot on every point; an area takes `stack`), and `Chart.donut` (`hole: 0` is a pie, with no total in it). A kind of your own is a `ChartKind`: its `entries`, `points` and `head` say what the legend, the status line and the data table read, and its `draw` is given a `ChartFrame` (the lit point, the legend, the plot's attributes and a `pointer(at)` attribute) and returns the plot, so the title, the legend placement, the status and the table stay the chart's.
2194
+
2195
+ ## Feedback and status
2196
+
2197
+ | Widget | What it is | Recipe and Slots |
2198
+ | --- | --- | --- |
2199
+ | `Alert` | `{ layout, title, description?, icon?, actions?, onDismiss?, words?, recoveryPart? }`, and by `layout`: `'inline'` takes `assertive?` and is a live region inside the content, of something that just happened (`role="alert"` when assertive, `role="status"` otherwise); `'banner'` takes `label` and is a full-width strip across a page or a section, there on load, so a `section` landmark named by `label` rather than a live region, which would say nothing on load. Each action is `{ label, href }` (a link) or `{ label, onClick }` (a button); `onDismiss` draws a close button named by `words.dismiss` (`'Dismiss {name}'`, `{name}` the title inline and the label as a banner) with the mark `words.dismissMark`. The icon is `aria-hidden`; whether it shows is the application's. The root writes `data-layout` and `data-dismissible`. `recoveryPart`: see [Focus after removal](#focus-after-removal). `Alert.configure({ base, presets })` binds a look and words. | `tone`: `info` (default), `success`, `warning`, `danger`, `neutral`, `accent`; `emphasis`: `subtle` (default, the family's tint), `bold` (its fill; the neutral tone inverts the page). Slots `root`, `icon`, `title`, `description`, `actions`, `action`, `dismiss`. |
2200
+ | `Toast` | A stack of toasts, Sonner's. A small Model: `Toast.init(id, { position?, direction?, duration?, max?, threshold? })`, folded with `Toast.update`, whose `Acted` OutMessage names a pressed action. `Toast.show(model, { type?, title, description?, actions?, cancel?, duration? })` returns the stack and the new toast's `id`; `Toast.settle(model, id, input)` turns a toast into its outcome; `Toast.dismiss(model, id)` takes it away; `Toast.nextId(model)` is the id the next `show` will give. `Toast.view({ model, onMessage, label?, words?, expand?, icons? }, h)`, with `Toast.configure({ base, presets })` and `Bundles.Toast.with({ id, position?, direction?, duration?, max?, threshold? })`, whose `helpers` are `show`, `settle` and `dismiss`. Adapter over the `ToastView` fork for toasts that carry their own payload. See [Toast](#toast). | `tone`: `plain` (default), `invert` (the text's ink as the card), `rich` (each type on its tint). Slots `container`, `entry`, `list`, `icon`, `body`, `title`, `description`, `actions`, `action`, `cancel`, `close`, `status`, `alert`. |
2201
+ | `Progress` | `@foldkit/ui`'s Progress. `Progress.view({ id, label, value, min?, max?, valueText?, showValue?, buffer?, segments? }, h)` draws a `progressbar` named by its label. `value` is an `Option`; none is indeterminate, and the bar's fill sweeps toward the inline end, leftward right to left. The root carries the share done as `--fk-progress`. `showValue` draws the value (`valueText`, else a percentage) at the end of a bar's label line and inside a ring. A `value` given as `ProgressSection`s is one stacked bar of toned parts, read aloud as their sum; `buffer` draws how far the work could go behind the fill; `segments` cuts the track into steps. | `shape`: `bar` (default), `ring`; `tone`: `accent`, `neutral`, `success`, `warning`, `danger`, `info`; `stripes`: `none`, `still`, `moving` (travel-aware); `size`. Slots `root`, `label`, `track`, `indicator`. |
2202
+ | `Meter` | `@foldkit/ui`'s Meter, a measurement where `Progress` is work. `Meter.view({ id, label, value, min?, max?, low?, high?, optimum?, valueText?, orientation?, segments? }, h)` draws a `meter` named by its label. `orientation: 'vertical'` stands the track upright (its length `--fk-meter-length`, 8rem), the fill growing from its block end; `segments` (an integer of at least 2) cuts the track into equal steps. The root says how good the value is as `data-level` (`good`, `fair`, `poor`), as the HTML meter judges it; `Meter.levelOf` is that judgment. | `size`: `sm`, `md`, `lg` (the track's thickness); the fill takes success, warning or error by level. Slots `root`, `label`, `track`, `fill`. |
2203
+ | `Spinner` | `{ label?, showLabel? }`. `role="status"` named by `label`, and `aria-hidden` without one; `showLabel` draws the label beside the wheel. A turn is about 720ms times `travel`. | `kind`: `ring` (default), `dots`, `bars`, `pulse`, `orbit`; `size`; `tone`: `accent`, `neutral`, `current`, and the status tones `info`, `success`, `warning`, `danger`. Slots `wheel`, `part`, `root`, `text`. |
2204
+ | `Timer` | After Zag's: a countdown (`Timer.init({ id, countdown: true, duration })`) or a stopwatch (`Timer.init({ id, interval? })`), folded with `Timer.update`, whose Commands (`Timer.Stamp`, `Timer.Tick`) read Effect's `Clock`, so TestClock drives a run. `Timer.view({ model, onMessage, label, units?, separator?, controls?, words? }, h)`: a `role="timer"` with each unit in a Slot, one press that says what comes next, and reset; `words` renames the presses (`Timer.words` are the defaults). `Bundles.Timer.with({ id, countdown?, duration?, interval? })` places the state (a countdown without a `duration` throws at placement), and `Timer.configure({ base, presets })` fixes the look, units and words once. `Timer.phase(model)` is `idle`, `running`, `paused` or `done`; to start at once, return `Timer.update(model, Timer.Message.Pressed({ action: 'start' }))` from `init`. | `tone`, `look`, `progress`, `size`. Slots `root`, `label`, `area`, `item`, `separator`, `controls`, `action`. |
2205
+
2206
+ ### Toast
2207
+
2208
+ The newest stand in front, spread out while the pointer or focus holds the stack, at
2209
+ most `max` (3) showing; a held stack or a hidden page pauses every countdown, keeping
2210
+ the time left; a swipe toward the edge past `threshold` dismisses one. A toast is
2211
+ spoken in a polite region, an error in an assertive one, each toast a keyed child of
2212
+ its own (the regions are not atomic), so one added beside another, or with the same
2213
+ words, is still read by itself. A toast takes `actions` (each a `{ label, value }`
2214
+ that dismisses it and says its `value` in `Acted`) and a `cancel` (words for a button
2215
+ that only dismisses it), drawn in an `actions` row before the close button. A toast
2216
+ that is already leaving does not act again when an action is pressed. A promise toast
2217
+ is `show` with `type: 'loading'`, the work run as a Command, and `settle` on the
2218
+ toast's `id` when its Message comes back; through `Bundles.Toast` the helpers return
2219
+ no id, so read `Toast.nextId(model)` before `show`. `words` is `{ label, close }`
2220
+ (`Toast.words`); `tone: 'invert'` is the text's ink as the card, as Sonner's inverted
2221
+ toasts. A payload toast that shows progress replaces what an entry holds with
2222
+ `ToastView.make(schema).revise(model, entryId, payload)`, keeping its place,
2223
+ animation and dismissal timing; upstream has no such operation.
2224
+ `ToastView` binds upstream's `Toast.make` for the payload and swaps in the
2225
+ transcribed view; the dismiss control stays inside the consumer's `entryToView`, so it
2226
+ is content, not a slot. `Toast.keepFocus` hands focus from a dismissed toast to a
2227
+ neighbour (see [Focus after removal](#focus-after-removal)).
2228
+
2229
+ ## Long lists and scrolling
2230
+
2231
+ | Widget | What it is | Recipe and Slots |
2232
+ | --- | --- | --- |
2233
+ | `ScrollArea` | `{ content }`. The height that makes it scroll is the caller's mixin, on `viewport` or `root`; a width goes on `root`, which the viewport fills and the bars lie over. The viewport is tabbable; a `label` makes it a `region` landmark of that name. A bar per axis is drawn beside the viewport, and `ScrollArea.overlayBars` lays them over its edge (see [Overlay scroll bars](#overlay-scroll-bars)). `overlayBars` lives in `scrollArea/overlayBars.ts`, so a page that never names it ships no `ScrollBars`. `ScrollArea.configure({ base, presets })` binds the look and the mixins (height, bars). | `orientation`: `vertical` (default), `horizontal`, `both`; `vertical` and `horizontal` fade the content toward an edge with more past it and draw a hairline there. `gutter`: `auto` (default), `stable` (`scrollbar-gutter: stable`, so content does not shift as a bar appears). Slots `root`, `viewport`, `bar`, `thumb`. |
2234
+ | `Resizable` | shadcn's Resizable and the APG's window splitter. A small Model: `Resizable.init(share, bounds?)`, its `Message`, and `update(model, message, bounds?)`; the bounds (`min`, `max`, `step`, `collapsible`, `collapsedTo`) are kept in `Model.bounds`, so `update` and the view read the one copy (a call's own bounds still win). `Bundles.Resizable.with({ share?, min?, max?, step?, collapsible?, collapsedTo? })` places it. `Resizable.view({ model, onMessage, id?, label, first, second, orientation?, direction?, min?, max?, step?, collapsible?, collapsedTo? })`. `Resizable.configure({ base, presets })` binds the look and orientation. See [Resizable](#resizable). | `handle`: `line` (default), `grip`, `pill` (a capsule that takes the accent while held); `data-orientation` lays it out. Slots `root`, `first`, `handle`, `second`. |
2235
+ | `VirtualList` | `@foldkit/ui`'s virtual list. `VirtualList.view({ model, items, itemToKey, itemToView, onMessage, overscan?, itemToRowHeightPx? \| dynamicRowHeights? }, h)` draws only the rows in view. Its Model is upstream's (`@foldkit/ui/virtualList`'s `init`), kept by the application and folded with that module's `update`, or placed with `Bundles.VirtualList` (args `{ id, rowHeightPx, initialScrollTop?, followEnd?, nearEndPx? }`), which with `nearEndPx` reports `NearEnd` when a scroll brings the list's end that close to the view, for loading the next page. A row's mixins may style it, not handle its events, since it is drawn inside the list's submodel. A bar is drawn beside the list, and `VirtualList.overlayBars` (a file of its own) lays it over the list's edge. It keeps no row drawn once it leaves the window, the one holding focus included, which `WindowList` does. | No axis. Slots `root` (the box it scrolls within: 18rem tall by default and as wide as its container, offering 20rem where the container takes its width from it), `row`, `bar`, `thumb`. |
2236
+ | `WindowList` | A virtual list that scrolls with the window. A small Model: `WindowList.init({ id, estimatedHeight, unmeasured?, overscan?, viewportHeight?, from? })`, folded with `WindowList.update`, which returns an `Update.Return` (the model and, for a `Found` match, the `Reveal` Command), so the application's own `update` returns the commands too; or placed with `Bundles.WindowList` (`init`'s options as args, `helpers.reveal(index, align?)`). `WindowList.view({ model, items, itemToKey, itemToView, onMessage, label?, findable? }, h)`. See [WindowList](#windowlist). | `Recipes.WindowList`: no look, only the spacers hidden where no script runs (`Utilities.scriptedOnly`); `.extend` it with the list's look. Slots `root` (`role="list"`), `spacer` (`data-edge` `start` or `end`, hidden from assistive technology), `row` (`role="listitem"`). |
2237
+
2238
+ ### Resizable
2239
+
2240
+ The handle is a `separator` with its value, stepped by the arrows and sent to the
2241
+ bounds by Home and End (a `collapsible` panel collapses when the key reaches its
2242
+ side, as the APG asks, and a collapsed one leaves the key alone); with an `id` the
2243
+ handle's `aria-controls` names the first panel; a drag follows the `Move` Mount from
2244
+ where it began over the group the `Resize` Mount measured. Under `direction: 'rtl'`
2245
+ the first panel is on the right, so ArrowLeft and a drag to the left grow it.
2246
+ `collapsible: 'first' | 'second'` (with `collapsedTo`) collapses that panel on Enter or
2247
+ a double-click and puts it back where it was, easing there while a drag follows the
2248
+ pointer at once; the bounds `init` was given are read by both `update` and the view. A split fills its
2249
+ panel, so splits nest either way.
2250
+
2251
+ ### WindowList
2252
+
2253
+ It draws the rows in view of the document's viewport between spacers as tall as the
2254
+ rest, so the page keeps its own scrolling: the browser restores its offset, a `sticky`
2255
+ header above the list sticks, and Space and End move it. Use `VirtualList` for a list
2256
+ in a box of its own.
2257
+
2258
+ - **Measuring.** Its one Mount on `root`, `WindowList.Track`, reads where the viewport
2259
+ lies over the list on every scroll, resize and resize of the page (`WindowViewport`),
2260
+ so content above it, or growing above it, counts, and measures each drawn row's border
2261
+ box (`MeasureRows`; space rows with padding: a row is `flow-root`). The rows already
2262
+ drawn when it starts are read at once, so no row leaves before its height is known. A
2263
+ row not yet measured counts `estimatedHeight`, or with `unmeasured: 'mean'` the mean of
2264
+ the rows measured above 0: for rows whose height the window's width decides, which
2265
+ `init` cannot know. A row still drawn is measured again only when it resizes, so keep
2266
+ the keys of the rows drawn: `WindowList.windowOf(model, keys)` is which rows are drawn,
2267
+ for loading what is in view, and `WindowList.keep(model, keys)` drops the heights of
2268
+ rows that left. A Scene test of a page drawing the list resolves it with
2269
+ `Scene.Mount.resolveAll(WindowList.resolveTrack(onMessage,
2270
+ WindowList.Message.Placed({ top, height })))`, the reading going through the view's own
2271
+ `onMessage`.
2272
+ - **Held row.** A row holding focus stays drawn beside the window while it is scrolled
2273
+ out (`Message.Focused` reports it as `Model.held`, `WindowList.heldRow(model, keys)` is
2274
+ its index, and `keep` retains its height), so the reader keeps their place in the tab
2275
+ order; `VirtualList` keeps neither.
2276
+ - **Reveal.** `WindowList.reveal(model, index, align?)` is the `Reveal` Command that
2277
+ scrolls the page until row `index` is drawn and shown, however far outside the window
2278
+ (`align`: `nearest` by default, `start`, `center` or `end`); return it from an
2279
+ `update`, and it answers `Message.CompletedReveal`.
2280
+ - **Find in page.** `findable: (item, index) => text` lets the browser's find in page
2281
+ match rows that are not drawn: each row outside the window is a `hidden="until-found"`
2282
+ stand-in holding that text in the spacers, which keep their height, and a match
2283
+ (`Message.Found`) reveals its row. It costs a node and a text node per row, so it is
2284
+ for lists of thousands; it is drawn once the runtime has placed the list and only where
2285
+ `WindowList.supportsFindable()` says the browser finds hidden text.
2286
+ - **Server pages.** A server's page opens the list at a row with `from` (a page's
2287
+ `?from=`): the window starts at that row, with no overscan above it, and the rows above
2288
+ take no room until `Track` places the list, which gives them their room and scrolls the
2289
+ window by what that moved the first row drawn, so a reader sees the same rows before and
2290
+ after the runtime takes the page over. The first `Placed` sets `from` back to 0, and
2291
+ the list follows the window. For a page without scripts, `WindowList.pageOf(model,
2292
+ keys)` is `{ start, end, previous, next }`: the rows drawn and, as `Option`s, the rows
2293
+ the pages either side open at (`previous` the first whose window reaches this one's
2294
+ start), for links that set `?from=`.
2295
+
2296
+ ## Chat
2297
+
2298
+ | Widget | What it is | Recipe and Slots |
2299
+ | --- | --- | --- |
2300
+ | `ChatMessage` | One message of a chat. `ChatMessage.view({ from, content, author?, avatar?, time?, status?, onRetry?, actions?, reactions?, pinActions?, streaming?, words? }, h)`, `from` being `user`, `assistant` or `system`. The user's sits at the end in a bubble, an answer as text at the start. `status` is `sending`, `sent` or `failed`, which draws a retry; `actions` are named buttons (`{ key, label, onClick, icon?, pressed?, disabled? }`) shown on hover and focus unless pinned. A streamed answer is the same message drawn again with more `content` and `streaming: true` (`aria-busy`); its body wraps with `text-wrap: wrap`, so no earlier word moves line. `ChatMessage.group({ items, continues?, style?, messageStyle? }, h)` draws a run, a sender's following messages continued. Markdown is the application's to render (`foldkit-richtext-markdown`'s `parse`, `foldkit-richtext-dom/view`'s `renderDocument`). | `layout`: `chat`, `thread`; `bubble`: `muted`, `accent`, `outline`, `ghost`; `content`: `text`, `markdown`. `Recipes.ChatMessageGroup` for the group. Slots `root`, `avatar`, `main`, `header`, `author`, `time`, `bubble`, `body`, `footer`, `status`, `retry`, `actions`, `action`, `reactions`, `reaction`, `reactionCount`. `ChatMessage.configure({ base, presets })` gives `{ view, group }`. |
2301
+ | `MessageScroller` | A conversation's log that follows the newest message while the reader is at the end. A small Model: `MessageScroller.init({ id, opens? })` (`end` by default, `start` for a transcript) holds only whether it follows and how many arrived unseen; the scroll position is the browser's, read by its `FollowEnd` Mount. Fold `MessageScroller.update` (or place `Bundles.MessageScroller.with({ id, opens? })`), and send `Message.Appended({ count })` when your update appends messages (not when it loads older ones, which it holds in place). `MessageScroller.view({ model, label, content, onMessage, words?, areaStyle?, areaMixins? }, h)` draws a named `role="log"` in a ScrollArea, with a jump button counting what arrived while away; give its parent a height. | No axis. Slots `root`, `log`, `jump`, `count`. |
2302
+ | `ThinkingIndicator` | An assistant at work: `ThinkingIndicator.view({ label?, detail?, active?, icon? }, h)` draws dots, a pulse or the view's icon beside words a band of light sweeps, and a detail line, in a polite status. Keep it drawn with `active: false` before work starts, so what it says when it starts is announced. Every movement holds under reduced motion. | `mark`: `dots`, `pulse`, `none`; `label`: `shimmer`, `plain`, `hidden`; `tone`: `muted`, `accent`. Slots `root`, `mark`, `dot`, `icon`, `label`, `detail`. |
2303
+ | `ThinkingSteps` | The trace of what an assistant did. `ThinkingSteps.view({ id, steps, open, onToggle, duration?, summary?, openSteps?, onToggleStep?, words?, trigger? }, h)`. Each step is `{ id, title, state, duration?, detail?, icon?, steps? }`, `state` being `pending`, `running`, `done`, `failed` or `skipped`, said in words too; `href` makes the title a link (such a step never toggles), `trailing` draws beside the row, outside its button. `trigger: 'none'` draws the steps as a plain list. `Bundles.ThinkingSteps.with({ openSteps?, multiple? })` keeps the open state, and `ThinkingSteps.controls(model, onMessage)` feeds the view. The button says the running step's title, or "Thought for 4s". Its openness is an `Option<boolean>`: none opens it while a step runs and shuts it once all are done, and the press sends the state the reader asked for. `openSteps` and `onToggleStep` make each step's detail collapsible. | `variant`: `plain`, `card`; `connector`: `line`, `none`. Slots `root`, `trigger`, `summary`, `chevron`, `panel`, `list`, `step`, `row`, `head`, `marker`, `title`, `link`, `state`, `duration`, `trailing`, `body`, `detail`. |
2304
+ | `Questionnaire` | An assistant's questions answered in the chat. A small Model: `Questionnaire.init({ id, questions, layout? })` with `Questionnaire.single`, `multiple` and `text` questions (`Question` is a Schema, so a tool's input decodes into it), folded with `Questionnaire.update`, which says what is missing and focuses it, and returns `OutMessage.Answered({ answers })` once every required question is answered; the form then gives way to a summary. `Questionnaire.view({ model, onMessage, title?, words?, style?, mixins?, radioGroup?, checkboxGroup?, input?, textarea?, button?, submitButton? }, h)`: the controls are the package's RadioGroup, CheckboxGroup, Input and Textarea, each taking its own style. | `variant`: `plain`, `card`; `actions`: `end`, `start`. Slots `root`, `title`, `progress`, `question`, `prompt`, `words`, `field`, `other`, `otherLabel`, `error`, `actions`, `summary`, `asked`, `answer`. |
2305
+
2306
+ ### MessageScroller
2307
+
2308
+ The log follows the newest message while the reader is at the end and stops when they
2309
+ scroll up, or when an upward wheel or ArrowUp, PageUp or Home arrives before that
2310
+ scroll. A Ctrl wheel, a wheel over a nested element that can scroll up itself, and a
2311
+ key another handler prevented, with Ctrl, Meta or Alt down, or typed into an input,
2312
+ textarea, select or editable element, do not count. A shorter viewport stays at the
2313
+ end while following. The messages and the text of a streamed answer are the
2314
+ application's.
2315
+
2316
+ ## Mechanisms shared by many widgets
2317
+
2318
+ Each of these is described here once; the catalog rows link to it.
2319
+
2320
+ ### Application key routes
2321
+
2322
+ A widget's own keys are `Behaviors.Keys` routes on one keydown owner, and the widgets
2323
+ below take a `routes` option for keys the application answers itself (F2 renaming a
2324
+ tab, Ctrl+A choosing every option, ArrowDown opening results). A route is built with
2325
+ `Keys.route(name, { on: [Keys.chord('ArrowDown')], handle })` from
2326
+ `foldkit-mixins`' `Behaviors`: `handle` receives the press (`key`, `modifiers`, the
2327
+ widget's `input` and, for a repeated slot, `item`) and returns an `Option` of a Message,
2328
+ or of `Keys.focus(id, message)` to move focus as well; `Option.none()` declines the
2329
+ press.
2330
+
2331
+ A route on a gesture another route on the same owner already takes throws
2332
+ `mixins:key-conflict`, naming both. `Keys.first(a, b)` is the way to let two routes
2333
+ declare one chord: `a` is asked first, and `b` only when `a` does not take the press or
2334
+ declines it.
2335
+
2336
+ | Widget | Keys the application's routes sit beside | The route's `input` |
2337
+ | --- | --- | --- |
2338
+ | `Command` | The field's: arrows, PageUp/PageDown, Enter; Home and End are the caret's. | `CommandKeyInput`: the query, the highlighted row and the rows the keys step through (`CommandRoute`). |
2339
+ | `SearchField` | Escape, which acts only on a field with text. | The field's text. |
2340
+ | `Menubar` | The arrows, Home and End. | Not read. |
2341
+ | `CascadeSelect` | On the open panel: the arrows, Home, End, Enter, Escape and every printable character (Space included, which still chooses). The closed trigger's keys are not open to routes. | `undefined` |
2342
+ | `Tour` | The arrows and, unless `closeOnEscape` is false, Escape. | `undefined` |
2343
+ | `FloatingPanel` | Escape (unless `closeOnEscape` is false); the arrows on the drag trigger and the corner are the panel's own, and a press they handled still reaches the panel. | `undefined` |
2344
+ | `Picker` | On a Sheet option: the arrows, Home and End (`item.index` is its place). The dropdown's keys are the Listbox's. | `undefined` |
2345
+ | `Nav` | `routes`: the row's own keys on the top-level links and triggers; `panelRoutes`: a panel's links. | `routes`: the entry, `item.index` its place; `panelRoutes`: the link, `item.index` its place among the panel's links. |
2346
+ | `Tabs` | `TabsContext.routes`: Delete, when tabs are closable. A tab with no key to answer draws no keydown at all. | The tab's `TabInfo`. |
2347
+ | `TagsInput` | The input's: Enter, the delimiter and Backspace. | The tags Model. |
2348
+ | `FileUpload` | The input's: Enter and Space (the dialog's, never routed) and Backspace and Delete (the last file). `FileUpload.conflict(routes)` names a clash. | The `FileUpload.Model`. |
2349
+ | `Toolbar` | The arrows, Home and End. | `undefined` |
2350
+
2351
+ ```ts
2352
+ // ArrowDown asks the first route; when there is no text to search for it declines, and
2353
+ // the second moves focus into the results list and sends the same Message.
2354
+ const toResults: SearchField.Route<Search> = Keys.route('Focus results', {
2355
+ on: [Keys.chord('ArrowDown')],
2356
+ handle: () => Option.some(Keys.focus('results', Search.OpenedResults())),
898
2357
  })
2358
+
2359
+ const searchWithFocus = (text: string, h: HtmlBuilder<Search>) =>
2360
+ SearchField.view(
2361
+ {
2362
+ id: 'find',
2363
+ label: 'Search products',
2364
+ value: text,
2365
+ onInput: text => Search.Typed({ text }),
2366
+ clear: { onClear: Search.Cleared() },
2367
+ routes: [Keys.first(openResults, toResults)],
2368
+ },
2369
+ h,
2370
+ )
2371
+ ```
2372
+
2373
+ #### Checking routes without drawing
2374
+
2375
+ Each of these widgets exports `conflict(routes, input?)`: the `mixins:key-conflict` that
2376
+ drawing it with `routes` would throw, as an `Option` of the diagnostic, for a screen
2377
+ where a user rebinds keys and the candidate set must be judged before anything is drawn.
2378
+ It asks `Keys.conflict` of the widget's own routes and `routes` together, the own routes
2379
+ being the list the view itself draws, so it names the same two routes the view would,
2380
+ and also reports two application routes on one gesture. It reads gestures only: no
2381
+ handler runs and nothing is drawn.
2382
+
2383
+ `input` is the part of the view's options that decides which keys the widget owns, with
2384
+ the view's defaults. A widget whose own keys never vary takes `routes` alone. One that
2385
+ draws nothing while closed (`Tour`, `FloatingPanel`, the `CascadeSelect` panel) is
2386
+ checked as open, since a route that clashes in any state is a clash.
2387
+
2388
+ | Widget | `input` |
2389
+ | --- | --- |
2390
+ | `Command`, `SearchField`, `CascadeSelect`, `Picker` | none |
2391
+ | `Menubar` | `{ direction? }`: the same keys clash either way, and `'rtl'` changes which own route the diagnostic names. |
2392
+ | `Tour`, `FloatingPanel` | `{ closeOnEscape? }`: Escape is the widget's only while it is not `false`. |
2393
+ | `Toolbar` | `{ orientation? }`, default `'horizontal'`: the arrows along it. |
2394
+ | `Tabs` | `{ close? }`: Delete is the tabs' own key only when they are closable. |
2395
+ | `TagsInput` | `{ delimiter?, direction? }`: the Model's delimiter, default `,`, and which arrow enters the chips. |
2396
+ | `Nav` | `{ panelRoutes? }`: `routes` is checked against the row's keys, then `panelRoutes` against a panel's links'. |
2397
+
2398
+ ```ts
2399
+ // Escape is the field's own key, so this candidate is refused with the diagnostic that
2400
+ // drawing the field with it would throw; a free key gives `Option.none()`.
2401
+ const candidate: SearchField.Route<Search> = Keys.route('Open results', {
2402
+ on: [Keys.chord('Escape')],
2403
+ handle: () => Option.some(Search.OpenedResults()),
2404
+ })
2405
+ const refusal = Option.map(SearchField.conflict([candidate]), diagnostic => diagnostic.message)
2406
+ ```
2407
+
2408
+ ### Focus after removal
2409
+
2410
+ When the element that held focus leaves the page, the browser drops focus to `body`.
2411
+ Three mechanisms keep it, all opt-in because none sends a Message, which a Scene test
2412
+ of every page drawing the widget would otherwise have to resolve.
2413
+
2414
+ - **A neighbour takes it** (`FocusRecovery`, from `foldkit-primitives/interaction`).
2415
+ `FocusRecovery.behavior(Slots)({ owner, parts, parent? })` on the slot that holds
2416
+ the repeated items (the `owner`) marks each `parts` slot and names where focus goes
2417
+ when that part is removed, hidden, made `inert` or `disabled`: steps tried in order
2418
+ (`same`, `next`, `previous`, `parent`, `stop`, `{ part }`, `owner`) until one can take
2419
+ it, and focus that was moved elsewhere is never taken. The widgets that draw a
2420
+ removable control take the part's name: `recoveryPart` on `Alert` and `Card` marks
2421
+ their dismiss button, and `Toast.keepFocus` is such a behavior on the
2422
+ toast container: from a dismissed toast's close button focus goes to the close
2423
+ button of the toast behind it, else the one in front, and from an action to a
2424
+ neighbour's action, else a close button; with no toast left, focus is not moved.
2425
+ Without `recoveryPart`, dismissing one drops focus to the page.
2426
+ - **The opener gets it back** (`focusReturn`). `Dialog.focusReturn`,
2427
+ `Tour.focusReturn` and `FloatingPanel.focusReturn` (a Sheet takes the Dialog's) give
2428
+ focus back to what had it before the widget opened, by `FocusReturn`'s rules when
2429
+ that is gone: an element with the opener's id, its `FocusRecovery` fallback steps,
2430
+ the dialog below, then the page's first tabbable element. The Tour and the
2431
+ FloatingPanel keep no opener of their own; upstream's Dialog return goes to the
2432
+ opener and, with none, to `body`.
2433
+ - **A control takes it** (`keepFocus`, a Command). `Drawer.keepFocus` moves focus to
2434
+ the handle when the drawer closes with focus in its body, which the hidden body would
2435
+ otherwise drop to the page. `SearchField.Focus` and `FileInput.Focus` put focus back
2436
+ on the input after the button that held it left, and `TagsInput.update` returns a
2437
+ focus Command after a removal. `FileUpload.update` does the same: the next entry's remove
2438
+ button, else the previous, else the input, and after a retry the entry's remove button;
2439
+ `FileUploadSort.keepFocus` (opt-in, in `mixins`) covers what no widget Message causes.
2440
+
2441
+ ```ts
2442
+ import { Alert } from 'foldkit-mixins-ui'
2443
+ import { FocusRecovery } from 'foldkit-primitives/interaction'
2444
+ import { SlotView } from 'foldkit-mixins'
2445
+
2446
+ const AlertListSlots = Slots.define({ list: Container, item: Container })
2447
+ const Dismissal = defineMessageUnion({ Dismissed: { name: Schema.String } })
2448
+ type Dismissal = typeof Dismissal.Type
2449
+
2450
+ // Dismissing an alert hands its focus to the next one, else the previous one.
2451
+ const alertList = (names: ReadonlyArray<string>, h: HtmlBuilder<Dismissal>) => {
2452
+ const builders = SlotView.buildersFor(
2453
+ AlertListSlots,
2454
+ [
2455
+ FocusRecovery.behavior(AlertListSlots)<undefined, Dismissal>({
2456
+ owner: 'list',
2457
+ parts: { item: ['next', 'previous'] },
2458
+ }).mixin,
2459
+ ],
2460
+ { input: undefined, h },
2461
+ )
2462
+ return h.div(
2463
+ builders.list.attrs(),
2464
+ names.map(name =>
2465
+ h.keyed('div')(
2466
+ name,
2467
+ [],
2468
+ [
2469
+ Alert.view(
2470
+ {
2471
+ layout: 'inline',
2472
+ title: name,
2473
+ onDismiss: Dismissal.Dismissed({ name }),
2474
+ recoveryPart: 'item',
2475
+ },
2476
+ h,
2477
+ ),
2478
+ ],
2479
+ ),
2480
+ ),
2481
+ )
2482
+ }
2483
+ ```
2484
+
2485
+ ### Form participation
2486
+
2487
+ Widgets that carry a value take `name` and put it where a form reads it, so a form that
2488
+ submits natively needs no hand-drawn input:
2489
+
2490
+ | Widget | What `name` submits |
2491
+ | --- | --- |
2492
+ | `Input`, `Textarea`, `PasswordInput` | The text. Input also takes the native `required`, `readOnly`, `autocomplete`, `inputMode` and `maxLength`; Textarea `required` and `autocomplete`; PasswordInput `required`. |
2493
+ | `NumberField` | The text the field shows. |
2494
+ | `OtpField` | The code. |
2495
+ | `Slider`, `AngleSlider` | The slider's value (a range submits both, low first); the angle's hidden input. |
2496
+ | `Rating` | The native radio's value (`name` defaults to `id`). |
2497
+ | `CheckboxGroup` | One hidden input per checked value, in the options' order. |
2498
+ | `Segmented` | One hidden input per chosen value, in the options' order. |
2499
+ | `TagsInput` | One hidden input per tag, not the draft. |
2500
+ | `CascadeSelect` | One hidden input per level of the chosen path, or one empty input. |
2501
+ | `DatePicker` | One hidden input per chosen day; a range's start then its end. |
2502
+ | `FileInput` | The files, through the native input that `FileInput.Sync` keeps equal to the list. |
2503
+ | `FileUpload` | The local files, through the native input that `Sync` keeps equal to the list; stored files are not in it. |
2504
+ | `Checkbox`, `Switch`, `RadioGroup`, `Listbox`, `Combobox` | Their `hiddenInput` Slots (`hiddenInputs` for the popups). |
2505
+
2506
+ A `disabled` Button is `aria-disabled`, not `disabled`, and still submits: refuse the
2507
+ submit in `update`.
2508
+
2509
+ What reaches server markup is data, not closures. A page that answers before its script
2510
+ runs (`foldkit-ssr`'s [resumable
2511
+ pages](https://github.com/doeixd/foldkit-plus/blob/main/packages/ssr/README.md#resumable-pages-answering-before-the-runtime-boots))
2512
+ cannot write a closure into the server's markup. There, give `onInput` the `OnInput`
2513
+ attribute the resumable builder makes from a Message member; the view adds it as it
2514
+ would the closure, and `KeepTyped` keeps what is typed before the script runs:
2515
+
2516
+ ```ts
2517
+ import { Resume } from 'foldkit-ssr/client'
2518
+
2519
+ const resumableEmail = (value: string, h: HtmlBuilder<Message>) => {
2520
+ const rh = Resume.builder(h)
2521
+ return Input.view(
2522
+ {
2523
+ id: 'email',
2524
+ value,
2525
+ onInput: rh.OnInput(Message.TypedEmail),
2526
+ type: 'email',
2527
+ draw: ({ input, label }) =>
2528
+ rh.div([], [rh.label(label, ['Email']), rh.input([...input, rh.KeepTyped()])]),
2529
+ },
2530
+ rh,
2531
+ )
2532
+ }
899
2533
  ```
900
2534
 
901
- `control` is in `variants`, so it wins over a `components` look on the same
902
- slot; over a look of your own in a later layer, say the same in that layer.
2535
+ `PasswordInput` draws its own input, so `KeepTyped` goes in its `attributes`, which adds
2536
+ to a Slot before the mixins resolve. Give it only while the field is enabled: a disabled
2537
+ field sends nothing, and the server refuses a kept field with nothing to replay
2538
+ (`UnkeepableField`).
903
2539
 
904
- `Recipes.Calendar` styles `CalendarSlots` in every mode: days in seven
905
- columns, months and years in three, each button reading its state off the
906
- cell (`data-today`, `data-selected`, `data-focused`, `data-outside-month`,
907
- `data-disabled`). Each cell is a rung of the size ladder, so `size`
908
- (`sm`, `md`) or the region steps it. It draws no card, so the same style serves a calendar on the page
909
- and one in a date picker's panel.
2540
+ ```ts
2541
+ import { PasswordInput } from 'foldkit-mixins-ui'
2542
+
2543
+ const resumablePassword = (password: string, shown: boolean, h: HtmlBuilder<Message>) => {
2544
+ const rh = Resume.builder(h)
2545
+ return PasswordInput.view(
2546
+ {
2547
+ id: 'password',
2548
+ label: 'Password',
2549
+ value: password,
2550
+ onInput: rh.OnInput(Message.TypedPassword),
2551
+ visible: shown,
2552
+ onToggle: Message.ToggledPassword(),
2553
+ attributes: { input: [rh.KeepTyped()] },
2554
+ },
2555
+ rh,
2556
+ )
2557
+ }
2558
+ ```
2559
+
2560
+ ### Right to left
2561
+
2562
+ Logical properties carry most of the recipes, and a few things follow the direction
2563
+ explicitly:
2564
+
2565
+ - **A `direction` view option.** Menu, Menubar, Nav, TreeView, Resizable, Segmented,
2566
+ Toolbar, TagsInput, CascadeSelect, FloatingPanel, Tour, Sidebar and a horizontal
2567
+ Listbox take `direction?: 'ltr' | 'rtl'` (a Toast stack takes it in `init`). Under
2568
+ `'rtl'` the view swaps ArrowLeft and ArrowRight before building its Message, so
2569
+ Messages and `update` stay in reading order, and draws the direction as its root's
2570
+ `dir`, so the CSS (a submenu's side, a chevron) reads what the keys read. Unset, the
2571
+ keys read left to right and the page's `dir` stands.
2572
+ - **`readingKeys` for upstream's keys.** Tabs, RadioGroup and Calendar handle their
2573
+ arrows in upstream bundles no view option reaches, so `Tabs.readingKeys`,
2574
+ `RadioGroup.readingKeys` and `Calendar.readingKeys`, passed beside the style, are a
2575
+ Mount that reads each arrow by the element's own `:dir()` before upstream's handler
2576
+ sees it. They are opt-in for the reason `fluid` is (see [Fluid
2577
+ highlights](#fluid-highlights)). `RadioGroup.readingKeys` reads both arrow pairs
2578
+ whichever way the group stands (ArrowRight and ArrowDown go on, ArrowLeft and ArrowUp
2579
+ back; the horizontal pair swapped on a right-to-left page).
2580
+ - **Indicators.** `Segmented.fluid`, `Tabs.fluid` and `Nav.fluid` measure their
2581
+ indicator again when a `dir` anywhere in the document changes, since flipping it moves
2582
+ the items without resizing anything.
2583
+
2584
+ ```ts
2585
+ Tabs.toView([TabsStyle.mixin, Tabs.readingKeys], { h }, ({ tablist, tabs }) =>
2586
+ h.div(tablist, tabs.map(tab => h.button(tab.tab, [tab.value]))),
2587
+ )
2588
+ ```
910
2589
 
911
- Tabs glide when drawn with their `indicator` and `highlight` and given
912
- `Tabs.fluid` beside the style. `Tabs.fluid` measures the chosen tab on the
913
- tablist (`Measure`) and moves one highlight to the tab nearest the pointer
914
- (`FluidHover`), born at the chosen tab and returning to it:
2590
+ ### Exits and reduced motion
2591
+
2592
+ A popup or dialog enters and leaves when drawn with `@foldkit/ui`'s `isAnimated`
2593
+ (`Menu.init(id, rows, { isAnimated: true })`, a Popover's `isAnimated`): a popup fades and
2594
+ grows on the fast tier, from the side its anchor placed it on, and a dialog on the slow
2595
+ one, each leaving on the quicker exit. A leaving Dialog is drawn `inert` with
2596
+ `isLeaving: Dialog.isLeaving(model)` in its context, and the Sheet does so itself; a
2597
+ Disclosure's `animatePanel` moves the panel's height, which the recipe scales by the
2598
+ `motion` knob. `Recipes.Dialog({ motion: 'none' })` (and the Sheet's) opens, closes and
2599
+ steps back at once.
2600
+
2601
+ Durations are the theme's: the `motion` knob multiplies them (`'0'` stills every recipe
2602
+ transition), and a duration of something that moves or resizes is also multiplied by
2603
+ `travel`, which reduced motion zeroes so that fades stay. A Marquee's viewport scrolls
2604
+ instead of moving under reduced motion, a ThinkingIndicator holds every movement, and a
2605
+ Carousel's `init` takes the application's reading of `prefers-reduced-motion` and starts
2606
+ an autoplaying carousel stopped.
2607
+
2608
+ ### Fluid highlights
2609
+
2610
+ Tabs, Segmented, Nav, Sidebar, TreeView, Menu, Listbox and Combobox take a `fluid` mixin
2611
+ list beside the style that glides one highlight, or an indicator, to the item the
2612
+ pointer is near and back to the chosen one; a Table and a Card group take `fluid:
2613
+ Table.fluid` and `fluid: Card.fluid`, values passed the same way. A Mount does the measuring and moves it. It
2614
+ is off by default because a Scene test resolves every Mount with a Message and these
2615
+ send none, so a default would burden the tests of every page that drew one; the same
2616
+ reason makes `readingKeys`, `keepFocus`, `focusReturn`, `keepActiveInView` and the
2617
+ `overlayBars` opt-in mixins.
2618
+
2619
+ `Tabs.fluid` measures the chosen tab on the tablist (`Measure`) and moves one highlight
2620
+ to the tab nearest the pointer (`FluidHover`), born at the chosen tab and returning to it:
915
2621
 
916
2622
  ```ts
917
2623
  Tabs.toView([TabsStyle.mixin, ...Tabs.fluid], { h }, ({ tablist, indicator, highlight, tabs }) =>
@@ -919,25 +2625,21 @@ Tabs.toView([TabsStyle.mixin, ...Tabs.fluid], { h }, ({ tablist, indicator, high
919
2625
  )
920
2626
  ```
921
2627
 
922
- The recipe draws the `line` variant's rule or the `pill` variant's pill on the
923
- indicator, which springs to a new choice, and dims the pill while another tab
924
- is hovered. Until `Tabs.fluid` runs, as before a page hydrates, the indicator
925
- and highlight show nothing and the chosen tab marks itself: the recipe reads
926
- the `data-fluid-hover` attribute FluidHover sets while it runs. (`Tabs.fluid`
927
- is opt-in because a Scene test resolves every Mount with a Message, and these
928
- send none.)
929
-
930
- Menus, listboxes and comboboxes draw their panels in the palette's `popup`
931
- tokens, so a theme's `menu: { accent, color }` (a bold accent row, an
932
- inverted or translucent panel) restyles all three. They take the same opt-in: `Menu.fluid`,
933
- `Listbox.fluid` and `Combobox.fluid`, beside the style in `toView`. The open
934
- panel's rows sit in a `rows` box of this package's (the panel carries
935
- upstream's anchor, and an element holds one Mount), with a `highlight` first
936
- in it that follows the pointer, and the keys, which mark a row `data-active`;
937
- a listbox or combobox adds an `indicator` that glides to the chosen row. The
938
- default draw places all three, and the rows drop their own hover and chosen
939
- fill while the highlight runs. A press in a gap presses the lit row, except in
940
- a combobox, whose field keeps focus.
2628
+ The recipe draws the `line` variant's rule or the `pill` variant's pill on the indicator,
2629
+ which springs to a new choice, and dims the pill while another tab is hovered. Until
2630
+ `Tabs.fluid` runs, as before a page hydrates, the indicator and highlight show nothing and
2631
+ the chosen tab marks itself: the recipe reads the `data-fluid-hover` attribute FluidHover
2632
+ sets while it runs.
2633
+
2634
+ Menus, listboxes and comboboxes draw their panels in the palette's `popup` tokens, so a
2635
+ theme's `menu: { accent, color }` (a bold accent row; a panel on the page's surface by default, or inverted or translucent)
2636
+ restyles all three, and they take `Menu.fluid`, `Listbox.fluid` and `Combobox.fluid`
2637
+ beside the style in `toView`. The open panel's rows sit in a `rows` box of this package's
2638
+ (the panel carries upstream's anchor, and an element holds one Mount), with a `highlight`
2639
+ first in it that follows the pointer, and the keys, which mark a row `data-active`; a
2640
+ listbox or combobox adds an `indicator` that glides to the chosen row. The default draw
2641
+ places all three, and the rows drop their own hover and chosen fill while the highlight
2642
+ runs. A press in a gap presses the lit row, except in a combobox, whose field keeps focus.
941
2643
 
942
2644
  ```ts
943
2645
  Menu.toView([MenuStyle.mixin, ...Menu.fluid], { h })
@@ -945,26 +2647,22 @@ Menu.toView([MenuStyle.mixin, ...Menu.fluid], { h })
945
2647
 
946
2648
  ### Overlay scroll bars
947
2649
 
948
- The scrolling recipes share one overlay bar, after Fluid Functionalism's: a
949
- 10px bar over the scroller's edge holding a thumb that rests 4px wide in a
950
- faint ink of the text, 2px off the edge, widens to 6px under the pointer and
951
- darkens while dragged. It fades in on `motion.moderate` while the box scrolls
952
- or the pointer moves over it, and out on `moderate-exit` once both rest, after
953
- a `moderate` delay that lets a widened thumb narrow first. The widening
954
- travels, so reduced motion keeps the fades alone. `ScrollBars` from
955
- `foldkit-primitives/dom` drives it and sends no Message; the bar is how it
956
- looks, the Mount only where the box is scrolled. On a coarse pointer the Mount
957
- does nothing, and the browser's bar, with its physics, stays; before it runs,
958
- as before a page hydrates, so does the browser's bar.
959
-
960
- Every one is the same shape, a mixin list passed beside the style:
961
- `ScrollArea.overlayBars`, `Command.overlayBars` and `VirtualList.overlayBars`
962
- in the view's `mixins`, and `Menu.overlayBars`, `Listbox.overlayBars` and
963
- `Combobox.overlayBars` in `toView`'s for a popup whose list scrolls: upstream
964
- draws that `scroll` region only when given `itemsScrollClassName` or
965
- `itemsScrollAttributes`, and its class joins the recipe's. Like `fluid`, it is off by default: a Scene test
966
- resolves every Mount with a Message, and this one sends none, so a default
967
- would burden the tests of every page that drew one.
2650
+ The scrolling recipes share one overlay bar, after Fluid Functionalism's: a 10px bar over
2651
+ the scroller's edge holding a thumb that rests 4px wide in a faint ink of the text, 2px
2652
+ off the edge, widens to 6px under the pointer and darkens while dragged. It fades in on
2653
+ `motion.moderate` while the box scrolls or the pointer moves over it, and out on
2654
+ `moderate-exit` once both rest, after a `moderate` delay that lets a widened thumb narrow
2655
+ first. The widening travels, so reduced motion keeps the fades alone. `ScrollBars` from
2656
+ `foldkit-primitives/dom` drives it and sends no Message; the bar is how it looks, the
2657
+ Mount only where the box is scrolled. On a coarse pointer the Mount does nothing, and the
2658
+ browser's bar, with its physics, stays; before it runs, as before a page hydrates, so does
2659
+ the browser's bar.
2660
+
2661
+ Every one is the same shape, a mixin list passed beside the style: `ScrollArea.overlayBars`,
2662
+ `Command.overlayBars`, `Dialog.overlayBars` and `VirtualList.overlayBars` in the view's
2663
+ `mixins`, and `Menu.overlayBars`, `Listbox.overlayBars` and `Combobox.overlayBars` in
2664
+ `toView`'s for a popup whose list scrolls: upstream draws that `scroll` region only when
2665
+ given `itemsScrollClassName` or `itemsScrollAttributes`, and its class joins the recipe's.
968
2666
 
969
2667
  ```ts
970
2668
  ScrollArea.view(
@@ -978,216 +2676,634 @@ ScrollArea.view(
978
2676
  Listbox.toView([ListboxStyle.mixin, ...Listbox.fluid, ...Listbox.overlayBars], { h })
979
2677
  ```
980
2678
 
981
- The bar is a Slot of each component's own (`bar` and `thumb`; a popup's
982
- `scrollBar` and `scrollThumb`), beside the scroller rather than inside it, so
983
- the scroller's edge fade does not erase it. ScrollArea, Command and
984
- VirtualList always draw it, and a popup whenever its panel has a `scroll`;
985
- the recipe leaves it undrawn until `ScrollBars` marks it scrollable. A ScrollArea also marks an edge
986
- with more past it with a hairline (`Utilities.scrollDivider` on `root`,
987
- `Utilities.scrollTimeline` on `viewport`), drawn where the browser lets a
988
- parent read a child's scroll timeline (`timeline-scope`).
989
-
990
- `Recipes.Tabs({ variant: 'pill' })`'s chosen tab is a raised surface with a
991
- hairline edge and shadow on the tray, in the default text colour;
992
- `selection: 'tint'` is the accent's tint and ink instead, as a pressed Segmented
993
- option is. To look at every recipe in every variant and
994
- state at once, in both schemes, write the specimen page:
995
- `pnpm --filter foldkit-mixins-ui specimen <out.html> [hue]`.
996
-
997
- `Recipes.Segmented` is a tray of toggle buttons where pressing selects — plain
998
- buttons, not `Tabs` (the group is `role="group"`, each option `aria-pressed`).
999
- The pressed option takes the accent's tint, flat: that rule lives on the
1000
- group, in `variants`, so icon tiles take the group piece alone, and an icon
1001
- button's own background, a variant too, does not hide it. `tray` is a muted tray, a plain row (which
1002
- sets no `display`: the Builder owns its narrow tabs' visibility) or an `underline`, each as wide as its options (`width: 'fill'` for a strip as wide as its container); an option takes an `icon`, alone with `iconOnly` (named by `aria-label` and `title`); `size` steps
1003
- the tray and its options on the ladder (`xs` a half step below compact, 24px), the
1004
- tray's inset counted in, so a tray is as tall as a button beside it. Its `indicator` and `highlight` slots, drawn first in the group
1005
- and given `Segmented.fluid`, slide the pressed option's pill to a new press
1006
- and move the hover to the option the pointer is on, tinted as every hover is
1007
- (the theme's `surface.hover` and `surface.hoverStrength`; a plain tray's
1008
- options tint themselves the same); until it runs the pressed option fills
1009
- itself:
2679
+ The bar is a Slot of each component's own (`bar` and `thumb`; a popup's `scrollBar` and
2680
+ `scrollThumb`), beside the scroller rather than inside it, so the scroller's edge fade
2681
+ does not erase it. ScrollArea, Command and VirtualList always draw it, and a popup
2682
+ whenever its panel has a `scroll`; the recipe leaves it undrawn until `ScrollBars` marks
2683
+ it scrollable. A ScrollArea also marks an edge with more past it with a hairline
2684
+ (`Utilities.scrollDivider` on `root`, `Utilities.scrollTimeline` on `viewport`), drawn
2685
+ where the browser lets a parent read a child's scroll timeline (`timeline-scope`).
2686
+
2687
+ ### The top layer
2688
+
2689
+ The panels of Menu (submenus included), Menubar, Listbox and Combobox that stay where they
2690
+ are drawn (an anchor's `portal: false`) draw in the browser's top layer, so no stacking
2691
+ context or ancestor `overflow` reaches them. Such a panel carries `popover="manual"`, and
2692
+ its anchor Mount is wrapped in `Anchor.topLayer`, which shows the panel as a popover around
2693
+ the Mount's own acquire and hides it once the Mount releases; the wrapper keeps the Mount's
2694
+ name, args and Messages, so a Scene test still resolves it, and the node stays where the
2695
+ runtime drew it. Light dismiss stays the application's Messages.
2696
+
2697
+ - The panel sets `inset: auto`: the anchor writes only `left` and `top`, and the browser's
2698
+ `inset: 0` would otherwise leave `right: 0` winning right to left.
2699
+ - An unstyled panel keeps the browser's popover border, padding and `Canvas` fill. Every
2700
+ recipe's panel replaces them; an inline reset would beat the recipes.
2701
+ - `Anchor.topLayer` does nothing where the popover API or the element's `popover`
2702
+ attribute is missing (jsdom, a server render, a panel drawn without it), and the anchor
2703
+ places the panel in the page.
2704
+ - A panel that upstream portals keeps upstream's behavior, since moving a shown popover
2705
+ hides it again.
2706
+
2707
+ Popover, Tooltip and Hover Card are drawn by upstream views whose Mounts this package cannot
2708
+ wrap, so their panels go in the top layer another way: `Anchor.layer(h)`, the `layer` slot of
2709
+ `PopoverSlots` and `TooltipSlots`, is an element drawn around the panel that shows itself as a
2710
+ popover, and the panel inside keeps upstream's anchor (`Popover.anchor()` and
2711
+ `Tooltip.anchor()` give `portal: false` and the placement: 12px and 8px off the trigger, 8px
2712
+ inside the viewport, flipping and shifting). A Hover Card's panel is anchored in the top layer
2713
+ by `HoverIntent.toView(mixins, { h, anchored: { id, anchor? } }, draw)`, which gives the
2714
+ trigger `HoverIntent.triggerId(id)`. The DatePicker's panel and modal dialogs are not in the
2715
+ top layer.
2716
+
2717
+ A box of your own whose Mount is not `TopLayer` takes `Anchor.layerBox(h, style?)`: the same
2718
+ box without the Mount, for a Mount wrapped in `Anchor.topLayer` that sends Messages (Cascade
2719
+ Select's and Tour's do), so a Scene test can resolve it. Its inline style takes `style` too,
2720
+ since a second `h.Style` on the element would replace the first.
2721
+
2722
+ The popups' recipes take a `width` axis. `trigger` sets the panel's minimum width to its
2723
+ trigger's (`--button-width`, which upstream's anchor publishes once it has placed the panel),
2724
+ in place of the panel's 14rem minimum, so a narrow trigger gets a panel as narrow; `auto`
2725
+ keeps the 14rem. Combobox defaults to `trigger`, Listbox to `auto`.
2726
+
2727
+ ### Accessibility patterns
2728
+
2729
+ Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the slots a widget of
2730
+ that kind must publish and what each must expose. The catalog lists them with a `tier`
2731
+ (`stateful` for a Submodel, `stateless` for a decorated native control), the ARIA `roles`
2732
+ involved, and the platform `floor`: what the widget relies on the browser for (`focus-trap`,
2733
+ `escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here reimplements it and a
2734
+ reader or an agent can ask.
1010
2735
 
1011
2736
  ```ts
1012
- const SegmentedStyle = Style.forSlots(SegmentedSlots)(
2737
+ import { A11y } from 'foldkit-mixins'
2738
+ import { Patterns } from 'foldkit-mixins-ui'
2739
+
2740
+ A11y.validate(Patterns.Tabs, MyTabsSlots) // [] when a custom tabs view publishes what tabs need
2741
+ Patterns.catalog.find(entry => entry.name === 'dialog')?.floor // ['focus-trap', 'escape-dismiss', ...]
2742
+ ```
2743
+
2744
+ A test iterates the catalog and validates each adapter's own Slots and `support` against its
2745
+ pattern, so an adapter cannot drift from the contract it claims. The patterns are written
2746
+ separately from the Slots, which is what makes the check mean something.
2747
+
2748
+ Where a pattern names obligations (who navigates, who makes an item reachable, who activates
2749
+ it, who names it), the entry's `support` lists who provides each: Mixins that contribute
2750
+ nothing, made with `A11y.base` (the widget's own markup or the upstream bundle it draws, named
2751
+ by source file) or `A11y.native` (what a native element does by itself). An adapter draws
2752
+ through `resolveFor`, so it has no view for `A11y.check` to read; the gate attaches `support`
2753
+ to a view over the adapter's Slots and `check` judges it, so an obligation nobody provides is
2754
+ a failure, and so is a provider nothing needs. These are claims found in source, not a
2755
+ rendered check; the rendered check is `Conformance` from `foldkit-mixins/testing`. Pagination,
2756
+ breadcrumb, table, scroll area, drawer, hover intent, picker, button group, window list, card,
2757
+ search field, toolbar and file input are in the catalog beside the older widgets, and a
2758
+ published `*Slots` that is neither in the catalog nor on the gate's list of Slots with nothing
2759
+ to require fails the gate. None of this is a WCAG claim.
2760
+
2761
+ ### Touch targets and icons
2762
+
2763
+ `Touch` and `Icons` are style mechanisms, not components: no slots, no views. Compose them into
2764
+ your own slots. The recipes' own controls already stand 44px tall where the pointer is coarse:
2765
+ `Defaults.reset` sets `--fk-touch-floor` there, and a control's height on the size ladder is at
2766
+ least that (a region that must stay dense sets it to `0px`). For your own slots, `Touch.target`
2767
+ floors one control at 44px where the pointer is coarse; `Touch.targets` floors every boxed
2768
+ control a region draws. `Icons.glyph(size)` draws the icon in `--icon` before the element's
2769
+ words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from an attribute's value, where
2770
+ `icons` maps each value to its resolved `url(…)`:
2771
+
2772
+ ```ts
2773
+ const TileStyle = Style.forSlots(TileSlots)(
1013
2774
  {
1014
- group: Recipes.Segmented({ tray: 'plain', size: 'sm' }).group,
1015
- option: Recipes.Segmented({ tray: 'plain', size: 'sm' }).option,
2775
+ tile: Style.compose(
2776
+ Touch.target,
2777
+ Icons.glyph('1rem'),
2778
+ Icons.byAttribute('data-block', { Hero: iconUrl('hero') }),
2779
+ ),
1016
2780
  },
1017
- { layer: L.layer('app') },
2781
+ { layer: Layers.standard.layer('app') },
1018
2782
  )
1019
2783
  ```
1020
2784
 
1021
- `Segmented.view` draws the options in one call from the application's
1022
- pressed values, and `Segmented.toggled(pressed, value, { multiple, optional })`
1023
- is the transition `update` applies. With `multiple` it is a toggle group,
1024
- shadcn's and Zag's: any number pressed, each filling itself (draw it without
1025
- `Segmented.fluid`, whose pill marks one):
2785
+ The icons the components draw themselves (a search field's magnifier, a toast's mark, a locked
2786
+ cell's padlock) are the theme's `icon` tokens: Heroicons' outline set (MIT), restroked to 2px,
2787
+ by default. An application's own pack replaces them as its own tokens: `AppStyle.make({ theme,
2788
+ tokens: Icons.tokens(pack, { width?, corners? }) })`, where `pack` holds an `IconData` for each
2789
+ name the components draw (`ChromeIcon` from `foldkit-mixins/theme`; one missing is a type
2790
+ error), and the stroke is redrawn into each mask, which CSS cannot reach once it is a `url()`.
2791
+
2792
+ ## Recipes
2793
+
2794
+ The adapters only name slots. `Recipes` gives those slots, and the views above, a look:
2795
+ one `Style.recipeFor` per contract, built on the tokens of `foldkit-mixins/theme`. Select
2796
+ variants (an axis's values are listed in the catalog rows), hand the pieces to
2797
+ `Style.forSlots`, and attach the result like any other Style:
1026
2798
 
1027
2799
  ```ts
1028
- Segmented.view(
1029
- {
1030
- label: 'Text style',
1031
- options: [
1032
- { value: 'bold', label: 'Bold' },
1033
- { value: 'italic', label: 'Italic' },
1034
- ],
1035
- pressed: model.marks,
1036
- onPress: mark => Message.ToggledMark({ mark }),
1037
- style: SegmentedStyle,
1038
- },
1039
- h,
2800
+ import { Layers, Style } from 'foldkit-mixins'
2801
+ import { Theme } from 'foldkit-mixins/theme'
2802
+ import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
2803
+
2804
+ const DeleteStyle = Style.forSlots(ButtonSlots)(
2805
+ Recipes.Button({ tone: 'danger', variant: 'outline', size: 'sm' }),
2806
+ )
2807
+
2808
+ const L = Layers.standard
2809
+ const theme = Theme.make({ accent: { hue: 280, chroma: 0.15, lightness: 60 } })
2810
+
2811
+ export const sheet = Style.stylesheet(
2812
+ L.declare,
2813
+ L.in('theme', Theme.root(Theme.standard(theme))),
2814
+ DeleteStyle,
1040
2815
  )
1041
- // in update: modifyFields(model, { marks: () => Segmented.toggled(model.marks, mark, { multiple: true }) })
1042
2816
  ```
1043
2817
 
1044
- ### The top layer
2818
+ `DeleteStyle.mixin` then goes to `Button.toView` as in the first example. What a recipe
2819
+ assumes and does:
1045
2820
 
1046
- The panels of Menu (submenus included), Menubar, Listbox and Combobox that
1047
- stay where they are drawn (an anchor's `portal: false`) draw in the
1048
- browser's top layer, so no stacking context or ancestor `overflow` reaches
1049
- them. Such a panel carries `popover="manual"`, and its anchor Mount is
1050
- wrapped in `Anchor.topLayer`, which shows the panel as a popover around the
1051
- Mount's own acquire and hides it once the Mount releases; the wrapper keeps
1052
- the Mount's name, args and Messages, so a Scene test still resolves it, and
1053
- the node stays where the runtime drew it. Light dismiss stays the
1054
- application's Messages.
1055
-
1056
- - The panel sets `inset: auto`: the anchor writes only `left` and `top`, and
1057
- the browser's `inset: 0` would otherwise leave `right: 0` winning right to
1058
- left.
1059
- - An unstyled panel keeps the browser's popover border, padding and
1060
- `Canvas` fill. Every recipe's panel replaces them; an inline reset would
1061
- beat the recipes.
1062
- - `Anchor.topLayer` does nothing where the popover API or the element's
1063
- `popover` attribute is missing (jsdom, a server render, a panel drawn
1064
- without it), and the anchor places the panel in the page.
1065
- - A panel that upstream portals keeps upstream's behavior, since moving a
1066
- shown popover hides it again.
2821
+ - **The page ships the tokens.** Every value is a `var(--fk-…)` reference to the shipped
2822
+ tokens (`Theme.standard`), so another theme's knobs restyle every recipe with no new
2823
+ CSS.
2824
+ - **Bases sit in `components`, variants in `variants`** of `Layers.standard`, so an
2825
+ application's `app` layer overrides both without specificity fights. Every declaration
2826
+ is a layered rule and none is inline style, since inline style beats every layer and
2827
+ could not be overridden this way:
1067
2828
 
1068
- Popover, Tooltip and Hover Card are drawn by upstream views whose Mounts this
1069
- package cannot wrap, so their panels go in the top layer another way:
1070
- `Anchor.layer(h)`, the `layer` slot of `PopoverSlots` and `TooltipSlots`, is
1071
- an element drawn around the panel that shows itself as a popover, and the
1072
- panel inside keeps upstream's anchor (`Popover.anchor()` and
1073
- `Tooltip.anchor()` give `portal: false` and the placement: 12px and 8px
1074
- off the trigger, 8px inside the viewport, flipping and shifting). A Hover
1075
- Card's panel is anchored in the top layer by `HoverIntent.toView(mixins, {
1076
- h, anchored: { id, anchor? } }, draw)`, which gives the trigger
1077
- `HoverIntent.triggerId(id)`. Each draws an `arrow` slot in its panel that
1078
- points at the trigger. The DatePicker's panel and modal dialogs are not in
1079
- the top layer.
1080
-
1081
- A box of your own whose Mount is not `TopLayer` takes `Anchor.layerBox(h,
1082
- style?)`: the same box without the Mount, for a Mount wrapped in
1083
- `Anchor.topLayer` that sends Messages (Cascade Select's and Tour's do), so a
1084
- Scene test can resolve it. Its inline style takes `style` too, since a
1085
- second `h.Style` on the element would replace the first.
1086
-
1087
- The popups' recipes take a `width` axis. `trigger` sets the panel's minimum
1088
- width to its trigger's (`--button-width`, which upstream's anchor publishes
1089
- once it has placed the panel), in place of the panel's 14rem minimum, so a
1090
- narrow trigger gets a panel as narrow; `auto` keeps the 14rem. Combobox
1091
- defaults to `trigger`, Listbox to `auto`.
2829
+ ```ts
2830
+ const Red = Style.forSlots(ButtonSlots)(
2831
+ { button: Style.self({ background: 'red' }) },
2832
+ { layer: L.layer('app') },
2833
+ )
2834
+ // Style.stylesheet(L.declare, …, DeleteStyle, Red): Red's background wins.
2835
+ ```
2836
+ - **Controls stand on one size ladder.** A button, a field, a select, a tab, a segmented
2837
+ control, a table row and the rows of a menu, listbox or combobox are all one rung tall:
2838
+ 36px by default and 28px compact, their padding, gap and text stepping with them
2839
+ (`Theme.ladder`, read on the element). `--fk-knob-step: 1` on any element makes
2840
+ everything inside it compact, the popups it opens included when they stay in the page (an
2841
+ anchor's `portal: false`, as the gallery's do); a panel upstream portals out of the page
2842
+ (the default of its own anchor) is given the region's custom properties as it leaves, so
2843
+ the region reaches it too, unless the panel sets the property itself. That holds for
2844
+ Menu, Listbox, Combobox and the `Anchor` Mount; a Popover or Tooltip with `portal: true`
2845
+ is not supported (draw it in place, as `anchor()` does). A recipe's `size` (`sm` compact,
2846
+ `md` default, `lg` a half step up at 40px) sets the step on its own element and beats the
2847
+ region, and a popup's sets it on its panel too, so it holds portaled or not; unset, which
2848
+ is the default, follows the region. An icon, checkbox, radio or switch with no size stands
2849
+ on the ladder's icon rung, 16px or 14px compact.
2850
+ - **Text comes in roles.** `Theme.role(name)` is a size and its leading, stepping with the
2851
+ ladder: `display`, `title`, `subtitle`, `body` (a control's text, 14px on 20), `caption`
2852
+ (badges, tooltips, a table's headings) and `micro` (keycaps). A tab's and a segmented
2853
+ option's label is trimmed to its capitals (`text-box`), centering it optically; a pressed
2854
+ segmented option and a chosen card title turn semibold without moving anything (the card
2855
+ writes its title in `data-label`; give an option its text there,
2856
+ `h.DataAttribute('label', 'Week')`, and draw its words in the `label` Slot, which holds the
2857
+ trim: on the option itself, the hidden copy took the trim's lower half); and a field's text
2858
+ is 16px on a coarse pointer, so iOS Safari does not zoom the page into it.
2859
+ - **A state is a tint, not a surface.** An unfilled control's hover is a faint film of the
2860
+ state ink over whatever is under it, so it reads on a muted page, a colored band or an
2861
+ inverted panel; a press lays that film stronger (`state.press`, 1.75 of the hover's). The
2862
+ ink is the theme's `--fk-state-ink` (`state.ink`: the element's own text, or the accent's
2863
+ ink under `surface.hover: 'accent'`) unless a painted surface above names its paint in the
2864
+ local `--_fk-state-ink`: the accent and danger tones name their fill, a subtle alert band
2865
+ its ink and a bold one its fill, so a hover on blue is a deeper blue. The neutral and ink
2866
+ tones name the theme's ink back, so a neutral control on a band does not take the band's
2867
+ hue, and one `surface.hover` choice reaches every component. The neutral button is
2868
+ see-through (`state.tint`), and images carry a hairline inside their edge (`state.edge`). A
2869
+ popup's rows round concentrically inside its panel (`Theme.nested`), as a segmented option
2870
+ does inside its tray. A fluid highlight (Table's, Segmented's, pill Tabs', Nav's,
2871
+ TreeView's, a Card group's) lays that same film, so `surface.hover` and
2872
+ `surface.hoverStrength` move it with every other hover.
2873
+ - **A press gives.** Held, every button scales to 98% (the 2% multiplied by `travel`, so
2874
+ reduced motion holds its size). A solid or primary button's fill also deepens to its
2875
+ family's `active` and clears the 1px border of its own color that it stands in, so the fill
2876
+ draws in by 1px a side; an outline, ghost or icon button lays a deeper film of its tone's
2877
+ ink. A pressed toggle (`aria-pressed="true"`) rests on its tone's fill, a solid one on the
2878
+ `active` fill; hovered, a solid toggle keeps it and an unfilled one takes its tone's hover
2879
+ fill; held, it deepens to the `active` fill; and its text stays the fill's throughout. A
2880
+ hovered row, tab, menu item or accordion row darkens while the press is held, and a fluid
2881
+ highlight darkens with the item it lights (`FluidHover` marks the container
2882
+ `data-fluid-held`). Chosen rows next to each other in a multiple listbox or combobox merge
2883
+ into one block. A disabled control fades by `state.disabledOpacity` (half by default), so
2884
+ one page shows one fade.
2885
+ - **Raised surfaces nest.** Popups, popovers, date picker panels and toasts sit two levels
2886
+ above what holds them and dialogs four (`Theme.raise`), each painted for its level, so a
2887
+ popover in a dialog lands above the dialog: a step lighter in a dark scheme, the same flat
2888
+ surface with its own shadow in a light one.
2889
+ - **State comes from the component's own attributes.** Checked, selected and disabled looks
2890
+ read `aria-checked`, `aria-selected` and `aria-disabled`, which `@foldkit/ui` already
2891
+ writes; no `whenInput` is needed.
2892
+ - **Tone and variant are independent.** A tone sets a few private custom properties that
2893
+ `solid`, `outline` and `ghost` read — except `primary`, which is ink by definition, and
2894
+ `icon`, a square one rung of the size ladder on a side. A tone also carries the line an
2895
+ `outline` draws: the fill, or for `neutral`, whose fill is a quiet grey, the page's default
2896
+ line. A neutral Checkbox or Switch that is on is in the page's ink, not the neutral grey, so
2897
+ it stands out without a color.
2898
+ - **On a colored band, unfilled buttons take the band's color.** `outline` and `ghost` draw
2899
+ their text in the tone's ink, which reads on the page's surface and not on a band of the
2900
+ accent. A band sets `Style.vars({ '--fk-ink': 'currentColor' })`, beside `--fk-heading` for
2901
+ its headings, and their text is the band's.
2902
+
2903
+ Adjust a recipe with `extend` instead of forking it. Base pieces compose per slot, a
2904
+ variant's pieces compose over the shipped ones, and compounds append:
1092
2905
 
1093
- ### Right to left
2906
+ ```ts
2907
+ const BrandButton = Recipes.Button.extend({
2908
+ base: { button: Style.class('brand-button') },
2909
+ variants: { size: { lg: { button: Style.class('brand-button-lg') } } },
2910
+ })
2911
+ ```
1094
2912
 
1095
- Logical properties carry most of the recipes, and a few things follow the
1096
- direction explicitly:
1097
-
1098
- - **A `direction` view option.** Menu, Menubar, TreeView, Resizable and a
1099
- horizontal Listbox take `direction?: 'ltr' | 'rtl'`. Under `'rtl'` the
1100
- view swaps ArrowLeft and ArrowRight before building its Message, so
1101
- Messages and `update` stay in reading order, and draws the direction as
1102
- its root's `dir`, so the CSS (a submenu's side, a chevron) reads what the
1103
- keys read. Unset, the keys read left to right and the page's `dir` stands.
1104
- - **`readingKeys` for upstream's keys.** Tabs, RadioGroup and Calendar handle
1105
- their arrows in upstream bundles no view option reaches, so
1106
- `Tabs.readingKeys`, `RadioGroup.readingKeys` and `Calendar.readingKeys`,
1107
- passed beside the style, are a Mount that reads each arrow by the
1108
- element's own `:dir()` before upstream's handler sees it. They are opt-in
1109
- for the reason `fluid` is: a Scene test must resolve every Mount with a
1110
- Message, and these send none.
1111
- - **Indicators.** `Segmented.fluid`, `Tabs.fluid` and `Nav.fluid` measure
1112
- their indicator again when a `dir` anywhere in the document changes, since
1113
- flipping it moves the items without resizing anything.
1114
-
1115
- ## Mechanisms
1116
-
1117
- `Touch` and `Icons` are style mechanisms, not components: no slots, no views.
1118
- Compose them into your own slots. The recipes' own controls already stand
1119
- 44px tall where the pointer is coarse: `Defaults.reset` sets
1120
- `--fk-touch-floor` there, and a control's height on the size ladder is at
1121
- least that (a region that must stay dense sets it to `0px`). For your own
1122
- slots, `Touch.target` floors one control at 44px where the pointer is coarse;
1123
- `Touch.targets` floors every boxed control a region draws. `Icons.glyph(size)` draws the icon in `--icon` before the
1124
- element's words, and `Icons.byAttribute(attribute, icons)` sets `--icon` from
1125
- an attribute's value, where `icons` maps each value to its resolved `url(…)`:
2913
+ `Recipes.Badge` is a recipe of two axes, `appearance` and `size`. The tone is not an axis: the view
2914
+ writes it as `data-tone`, so one style serves badges of every tone, and the six names of the tone
2915
+ vocabulary are in the recipe. A badge toned by an attribute the application already writes maps its
2916
+ values with `Recipes.badgeTones` through `extend`; a value the map leaves out keeps the base pill.
2917
+ `Recipes.Badge.add` gives it a size or an appearance of your own. A toned pill is grounded on its
2918
+ tone's `subtle`, which keeps the tone's hue over a tinted page:
1126
2919
 
1127
2920
  ```ts
1128
- const TileStyle = Style.forSlots(TileSlots)(
1129
- {
1130
- tile: Style.compose(
1131
- Touch.target,
1132
- Icons.glyph('1rem'),
1133
- Icons.byAttribute('data-block', { Hero: iconUrl('hero') }),
1134
- ),
1135
- },
1136
- { layer: L.layer('app') },
1137
- )
2921
+ const EntryStyle = Style.forSlots(EntrySlots)({
2922
+ badge: Recipes.Badge.extend({
2923
+ base: {
2924
+ badge: Recipes.badgeTones('data-state', { Published: 'success', Changed: 'warning' }),
2925
+ },
2926
+ })().badge,
2927
+ })
1138
2928
  ```
1139
2929
 
1140
- The icons the components draw themselves (a search field's magnifier, a
1141
- toast's mark, a locked cell's padlock) are the theme's `icon` tokens:
1142
- Heroicons' outline set (MIT), restroked to 2px, by default. An application's
1143
- own pack replaces them as its own tokens:
1144
- `AppStyle.make({ theme, tokens: Icons.tokens(pack, { width?, corners? }) })`,
1145
- where `pack` holds an `IconData` for each name the components draw
1146
- (`ChromeIcon` from `foldkit-mixins/theme`; one missing is a type error), and
1147
- the stroke is redrawn into each mask, which CSS cannot reach once it is a
1148
- `url()`.
1149
-
1150
- ## Accessibility patterns
1151
-
1152
- Every adapter has an `A11y.pattern` beside its Slots, under `Patterns`: the
1153
- slots a widget of that kind must publish and what each must expose. The
1154
- catalog lists them with a `tier` (`stateful` for a Submodel, `stateless` for
1155
- a decorated native control), the ARIA `roles` involved, and the platform
1156
- `floor`: what the widget relies on the browser for (`focus-trap`,
1157
- `escape-dismiss`, `top-layer`, `form-submission`, ...), so nothing here
1158
- reimplements it and a reader or an agent can ask.
2930
+ `Badge.view({ text, icon, onDismiss })` draws an icon before the text and a dismiss button named by
2931
+ `words.dismiss` (`'Dismiss {text}'`); `{ text, href, external }` draws the pill as a link. A link
2932
+ holds no dismiss button, and the types refuse both.
2933
+
2934
+ `Recipes.InputGroup` draws a text field with a prefix or suffix, such as an address's `/`, as one
2935
+ box: `group` carries the border, its hover and the focus ring (while the control inside has
2936
+ focus), `affix` sits inside it, muted, and `control` makes the input inside borderless. They are
2937
+ pieces for your own group, affix and control slots, as `foldkit-mixins-form`'s field publishes
2938
+ them. `control` is in `variants`, so it wins over a `components` look on the same slot; over a
2939
+ look of your own in a later layer, say the same in that layer:
1159
2940
 
1160
2941
  ```ts
1161
- import { A11y } from 'foldkit-mixins'
1162
- import { Patterns } from 'foldkit-mixins-ui'
2942
+ const AddressStyle = Style.forSlots(FieldSlots)({
2943
+ group: Recipes.InputGroup.group,
2944
+ affix: Recipes.InputGroup.affix,
2945
+ text: Style.compose(Recipes.Input({}).input, Recipes.InputGroup.control),
2946
+ })
2947
+ ```
1163
2948
 
1164
- A11y.validate(Patterns.Tabs, MyTabsSlots) // [] when a custom tabs view publishes what tabs need
1165
- Patterns.catalog.find(entry => entry.name === 'dialog')?.floor // ['focus-trap', 'escape-dismiss', ...]
2949
+ `Recipes.Calendar` styles `CalendarSlots` in every mode: days in seven columns, months and years
2950
+ in three, each button reading its state off the cell (`data-today`, `data-selected`,
2951
+ `data-focused`, `data-outside-month`, `data-disabled`). Each cell is a rung of the size ladder,
2952
+ so `size` (`sm`, `md`) or the region steps it. It draws no card, so the same style serves a
2953
+ calendar on the page and one in a date picker's panel. `Recipes.Tabs({ variant: 'pill' })`'s
2954
+ chosen tab is a raised surface with a hairline edge and shadow on the tray, in the default text
2955
+ colour. To look at every recipe in every variant and state at once, in both schemes, write the
2956
+ specimen page: `pnpm --filter foldkit-mixins-ui specimen <out.html> [hue]`.
2957
+
2958
+ ## One factory for each part
2959
+
2960
+ A widget's look, state, drawing and features each have one place they are
2961
+ given ([Look, state, drawing, features](#look-state-drawing-features-one-factory-each)).
2962
+ This section shows each with code.
2963
+
2964
+ ### State: fold it by hand, or place a Bundle
2965
+
2966
+ A stateful widget exports `Model`, `Message`, `init` and `update`. The
2967
+ application keeps the Model in a field of its own, wraps the widget's Messages
2968
+ in one of its own, and folds them. Written out, for a field of tags:
2969
+
2970
+ ```ts standalone
2971
+ import { Schema } from 'effect'
2972
+ import * as Command from 'foldkit/command'
2973
+ import type { Html, HtmlBuilder } from 'foldkit/html'
2974
+ import { defineMessageUnion } from 'foldkit/message'
2975
+ import { modifyFields } from 'foldkit/struct'
2976
+ import type { Return } from 'foldkit/update'
2977
+ import { TagsInput } from 'foldkit-mixins-ui'
2978
+
2979
+ const Model = Schema.Struct({ labels: TagsInput.Model })
2980
+ type Model = typeof Model.Type
2981
+
2982
+ const Message = defineMessageUnion({ GotLabelsMessage: { message: TagsInput.Message } })
2983
+ type Message = typeof Message.Type
2984
+
2985
+ export const initial: Model = {
2986
+ labels: TagsInput.init({ id: 'labels', tags: ['urgent'], max: 3 }),
2987
+ }
2988
+
2989
+ export const update = (model: Model, message: Message): Return<Model, Message> =>
2990
+ Message.match(message, {
2991
+ GotLabelsMessage: ({ message }) => {
2992
+ const result = TagsInput.update(model.labels, message)
2993
+ // The field's own Commands (it refocuses after a removal) speak its Messages.
2994
+ const commands = Command.mapMessages(result.commands, message =>
2995
+ Message.GotLabelsMessage({ message }),
2996
+ )
2997
+ // Nothing changed: hand back the Model given, so nothing is drawn again.
2998
+ return result.model === model.labels
2999
+ ? { model, commands }
3000
+ : { model: modifyFields(model, { labels: () => result.model }), commands }
3001
+ },
3002
+ })
3003
+
3004
+ export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
3005
+ TagsInput.view(
3006
+ {
3007
+ model: model.labels,
3008
+ onMessage: message => Message.GotLabelsMessage({ message }),
3009
+ label: 'Labels, up to three',
3010
+ },
3011
+ h,
3012
+ )
1166
3013
  ```
1167
3014
 
1168
- A test iterates the catalog and validates each adapter's own Slots against
1169
- its pattern, so an adapter cannot drift from the contract it claims. The
1170
- patterns are written separately from the Slots, which is what makes the
1171
- check mean something.
3015
+ That is the whole of it, and for a page with one or two widgets it is the
3016
+ smaller choice: it adds nothing to the bundle. `Bundles.X` is the same `init`
3017
+ and `update` packaged for
3018
+ [`foldkit-bundle`](https://github.com/doeixd/foldkit-plus/blob/main/packages/bundle/README.md),
3019
+ which derives the field, the wrapper Message and the fold above from one
3020
+ placement:
3021
+
3022
+ ```ts standalone
3023
+ import type { Html, HtmlBuilder } from 'foldkit/html'
3024
+ import { Bundle } from 'foldkit-bundle'
3025
+ import { Bundles, TagsInput } from 'foldkit-mixins-ui'
3026
+
3027
+ const App = Bundle.compose({}).pipe(
3028
+ Bundle.withChild('labels', Bundles.TagsInput, {
3029
+ args: { id: 'labels', tags: ['urgent'], max: 3 },
3030
+ }),
3031
+ )
3032
+ type Model = typeof App.Model.Type
3033
+ type Message = typeof App.Message.Type
3034
+
3035
+ const view = (model: Model, h: HtmlBuilder<Message>): Html =>
3036
+ TagsInput.view(
3037
+ {
3038
+ model: model.labels,
3039
+ onMessage: message => App.Message.GotLabelsMessage({ message }),
3040
+ label: 'Labels, up to three',
3041
+ },
3042
+ h,
3043
+ )
3044
+
3045
+ export const config = App.placements.runtime({ Model: App.Model, initial: {}, view })
3046
+ ```
3047
+
3048
+ The first placement costs a page about 6 kB (brotli) of `foldkit-bundle`; the
3049
+ second and every later one share it. `foldkit-bundle` is a peer dependency:
3050
+ install it when you place a Bundle, and a page that folds by hand never loads
3051
+ it.
3052
+
3053
+ - **A Bundle is headless.** It holds no view; draw the placed Model with the
3054
+ widget's `view`.
3055
+ - **Its `args` are `init`'s options**, checked by a Schema and given to
3056
+ `update` too.
3057
+ - **`Bundles` is a namespace of one file per widget**, as `Recipes` is, so
3058
+ reading `Bundles.TagsInput` keeps that file and no other Bundle.
3059
+
3060
+ Who owns the value follows from its type. Where the value's type is the
3061
+ widget's own (a TagsInput's tags), the Bundle holds it and the application
3062
+ reads it from the placed Model, `model.labels.tags`. Where the type is the
3063
+ application's (the items of a Combobox), the application keeps the value in
3064
+ its own field and the Bundle holds only the interaction: open or closed, the
3065
+ row the keys are on, the text typed. A `Choice` says how that field is read
3066
+ and folded, and the Bundle reports each change for the application to answer:
3067
+
3068
+ ```ts standalone
3069
+ import { Schema } from 'effect'
3070
+ import { Bundle } from 'foldkit-bundle'
3071
+ import type { Html, HtmlBuilder } from 'foldkit/html'
3072
+ import { Bundles, Combobox } from 'foldkit-mixins-ui'
3073
+
3074
+ const cities = ['Lisbon', 'Porto', 'Faro'] as const
3075
+ const City = Combobox.one(cities)
3076
+
3077
+ const App = Bundle.compose({ city: Schema.Option(Schema.Literals(cities)) }).pipe(
3078
+ Bundle.withChild('cityBox', Bundles.Combobox, {
3079
+ args: { id: 'city' },
3080
+ // `out` is a `ChoiceChange`; `City.picked` looks the reported value up
3081
+ // among `cities`, so `city` stays an `Option` of one of them.
3082
+ onOut: out => model => ({ model: { ...model, city: City.picked(model.city, out) } }),
3083
+ }),
3084
+ )
3085
+
3086
+ export const initial = App.placements.initial({ city: City.empty })
3087
+
3088
+ // The same `Choice` reads the field for the drawing: the chosen row, the resting text.
3089
+ export const cityField = (model: typeof App.Model.Type, h: HtmlBuilder<typeof App.Message.Type>): Html =>
3090
+ Combobox.view(
3091
+ {
3092
+ model: model.cityBox,
3093
+ onMessage: message => App.Message.GotCityBoxMessage({ message }),
3094
+ label: 'City',
3095
+ choice: City,
3096
+ value: model.city,
3097
+ filter: Combobox.contains,
3098
+ clear: true,
3099
+ },
3100
+ h,
3101
+ )
3102
+ ```
3103
+
3104
+ `Combobox.one(items)` holds an `Option` of an item, `Combobox.many(items)` a
3105
+ list of them in the order chosen (place the Bundle with `multiple: true`, which
3106
+ its `update` reads: choosing leaves the list open), and `Combobox.text(items)`
3107
+ the typed text itself, with the items as suggestions. Each is a file of its
3108
+ own. `Choice` is an interface you may implement; a rule of your own usually
3109
+ wraps a shipped one:
3110
+
3111
+ ```ts standalone
3112
+ import { Combobox, type Choice } from 'foldkit-mixins-ui'
3113
+
3114
+ /** At most three: a fourth choice leaves the value as it was. */
3115
+ export const upToThree = <Item extends string>(
3116
+ items: ReadonlyArray<Item>,
3117
+ ): Choice<Item, ReadonlyArray<Item>> => {
3118
+ const many = Combobox.many(items)
3119
+ return {
3120
+ ...many,
3121
+ picked: (value, change) => {
3122
+ const next = many.picked(value, change)
3123
+ return next.length > 3 ? value : next
3124
+ },
3125
+ }
3126
+ }
3127
+ ```
3128
+
3129
+ Where the value's type is the widget's own and a parent usually acts on a
3130
+ change, the Bundle reports it. A Calendar holds its `Selection` and reports
3131
+ `Changed`, which a placement answers or ignores by name:
3132
+
3133
+ ```ts standalone
3134
+ import { Option } from 'effect'
3135
+ import { Bundle } from 'foldkit-bundle'
3136
+ import * as Dates from 'foldkit/calendar'
3137
+ import type { Html, HtmlBuilder } from 'foldkit/html'
3138
+ import { Bundles, Calendar } from 'foldkit-mixins-ui'
3139
+
3140
+ const today = Dates.make(2026, 2, 11)
3141
+
3142
+ const App = Bundle.compose({}).pipe(
3143
+ Bundle.withChild('trip', Bundles.Calendar, {
3144
+ // The selection's tag is the mode; `months: 2` draws two side by side.
3145
+ args: { id: 'trip', today, selection: Calendar.empty('Range'), months: 2, minDate: today },
3146
+ // `Changed` carries the new selection; this page only reads it from the Model.
3147
+ onOut: Bundle.ignore,
3148
+ }),
3149
+ )
3150
+ type Model = typeof App.Model.Type
3151
+ type Message = typeof App.Message.Type
3152
+
3153
+ export const nights = (model: Model): number =>
3154
+ Option.match(Calendar.rangeOf(model.trip.selection), {
3155
+ onNone: () => 0,
3156
+ onSome: ({ start, end }) => Dates.daysUntil(start, end),
3157
+ })
3158
+
3159
+ export const view = (model: Model, h: HtmlBuilder<Message>): Html =>
3160
+ Calendar.view(
3161
+ {
3162
+ model: model.trip,
3163
+ onMessage: message => App.Message.GotTripMessage({ message }),
3164
+ label: 'Trip dates',
3165
+ presets: [{ label: 'Next week', selection: Calendar.nextDays(today, 7) }],
3166
+ today: { label: 'This month' },
3167
+ footer: h.p([], [`${nights(model)} nights`]),
3168
+ },
3169
+ h,
3170
+ )
3171
+ ```
3172
+
3173
+ `Combobox.view(options, h)` takes that `choice` and the `value`, and draws
3174
+ the rest from data:
3175
+
3176
+ - **Rows.** `option: item => RowContent` gives a row its `label` (which also
3177
+ names a chip and the resting text), `description`, `icon`, `trailing`,
3178
+ `content` in the label's place, and `disabled`; without it a row is its
3179
+ item. `items` narrows what is offered now (a fetched page); `filter` keeps
3180
+ the rows whose label matches the typed text, with `Combobox.contains` and
3181
+ `Combobox.startsWith` shipped as values, so a page that fetches for the
3182
+ text ships neither. `groupBy` and `heading` group adjacent rows.
3183
+ - **The field.** `placeholder`, `empty` (drawn in the list's place),
3184
+ `clear` (`true` for a button with a drawn cross, or `{ content }`),
3185
+ `chips` for a choice of several, `buttonContent`, `disabled`, `invalid`,
3186
+ `readOnly`, `name`, `openOnFocus`, `anchor`, and `words` (`clear`,
3187
+ `remove`, the second with `{label}`).
3188
+ - **Clearing** empties the field's text through the Combobox's own Message.
3189
+ The value follows through the `Choice`: `Combobox.text` takes the empty
3190
+ text, and a combobox placed with `nullable: true` reports
3191
+ `ClearedSelection` when an emptied field is left.
3192
+ - **A value chosen before the page drew** needs the Bundle's `text` arg (the
3193
+ chosen row's label), since upstream writes the resting text only as the
3194
+ field is left.
3195
+ - **`Combobox.configure({ base, presets })`** binds `filter`, `placeholder`,
3196
+ `chips`, `openOnFocus`, `anchor`, `words`, `style`, `mixins` and `clear:
3197
+ true`.
3198
+ - **`Combobox.fluid` and `Combobox.overlayBars`** are files of their own: a
3199
+ page that passes neither ships neither `FluidHover`, `Measure` nor
3200
+ `ScrollBars`.
3201
+
3202
+ The `toView` adapter and the `ComboboxView` bundles stay as the rung below.
3203
+
3204
+ `Listbox.view(options, h)` and `Picker.view(options, h)` take the same `choice` and
3205
+ `value` and the same `option`, `groupBy`, `heading`, `items`, `placeholder`,
3206
+ `disabled`, `invalid`, `name` and `words` (`clear`, the button's name), over
3207
+ `Bundles.Listbox` and `Bundles.Picker`: a Listbox's `Listbox.one(items)` or
3208
+ `Listbox.many(items)` (`multiple: true` in the Bundle's args, since choosing
3209
+ leaves a multiple list open), a Picker's `Picker.one(items)`. The value is the
3210
+ application's, so `clear` is `{ onClear, content? }`: the button sends the
3211
+ application's own Message, which empties the field through the same choice
3212
+ (`ChoiceChange.ClearedSelection()`). `Listbox.fluid` and `Listbox.overlayBars` are
3213
+ files of their own, like the Combobox's.
3214
+
3215
+ ### Drawing: configure once, call with what differs
3216
+
3217
+ `X.configure({ base, presets })` returns the widget's own `view`, bound to
3218
+ options an application would otherwise repeat at every call: its compiled
3219
+ style, its words, its mixins, its structural choices.
3220
+
3221
+ ```ts standalone
3222
+ import type { Html, HtmlBuilder } from 'foldkit/html'
3223
+ import { defineMessageUnion } from 'foldkit/message'
3224
+ import { Style } from 'foldkit-mixins'
3225
+ import { Button, ButtonSlots, Recipes } from 'foldkit-mixins-ui'
3226
+
3227
+ const Message = defineMessageUnion({ Saved: {}, Deleted: {} })
3228
+ type Message = typeof Message.Type
3229
+
3230
+ // Styles are compiled once, in a module the build may ship as data.
3231
+ const Quiet = Style.forSlots(ButtonSlots)(Recipes.Button({ tone: 'neutral', variant: 'outline' }))
3232
+ const Danger = Style.forSlots(ButtonSlots)(Recipes.Button({ tone: 'danger' }))
3233
+
3234
+ export const AppButton = Button.configure({
3235
+ base: { style: Quiet },
3236
+ presets: { danger: { style: Danger } },
3237
+ })
3238
+
3239
+ export const actions = (h: HtmlBuilder<Message>): ReadonlyArray<Html> => [
3240
+ AppButton.view({ label: 'Save', onClick: Message.Saved() }, h),
3241
+ AppButton.view({ label: 'Delete', preset: 'danger', onClick: Message.Deleted() }, h),
3242
+ ]
3243
+ ```
3244
+
3245
+ - **The order is `base`, the named preset, the call.** A later one wins per
3246
+ option, so a style given at the call replaces the preset's. Two options
3247
+ merge instead: `mixins` concatenate in that order, and `words` merge word
3248
+ by word. An option given as `undefined` is not given.
3249
+ - **The preset names are the keys you wrote.** `preset: 'dangr'` is a type
3250
+ error, and `preset` is no option at all where `presets` was left out. A
3251
+ name computed at run time that matches none throws, naming the ones
3252
+ declared.
3253
+ - **A preset holds what takes no Message and no state**: `style`, `mixins`,
3254
+ `words` and each widget's own list (`type` for a Button; `placeholder`,
3255
+ `addOnBlur` and `direction` for a TagsInput; `weekNumbers`, `caption`,
3256
+ `paging`, `today`, `presets` and `detail` for a Calendar; `filter`,
3257
+ `placeholder`, `chips`, `openOnFocus`, `anchor` and `clear: true` for a
3258
+ Combobox). `onClick`,
3259
+ `onMessage`, `model`, `label` and anything drawn (`icon`, `aside`, `footer`)
3260
+ stay at the call.
3261
+ - **A preset may hold behaviour.** A mixin with a Mount given in a preset
3262
+ attaches to every use of that preset, and the page ships that Behavior
3263
+ only because the application's own module imported it. A Mount that sends
3264
+ no Message has to be resolved by the application's Scene tests of every
3265
+ page that draws the preset.
3266
+ - **It holds no state.** A widget's starting values are `init`'s options, or
3267
+ a Bundle's `args`.
3268
+
3269
+ ### Look: recipe modules hold style and nothing else
3270
+
3271
+ A shipped recipe module imports style code only: `foldkit-mixins` styles,
3272
+ theme references, other recipes' pieces, icon masks. It never imports a
3273
+ widget, a Behavior or anything with a Mount, which is what lets a build
3274
+ evaluate a style module and ship class names in its place
3275
+ ([Style modules shipped as data](https://github.com/doeixd/foldkit-plus/blob/main/packages/mixins/README.md#style-modules-shipped-as-data)).
3276
+ An axis selects what CSS can express over the same markup. A choice that
3277
+ changes the markup is a view option, which the view writes as a `data-*`
3278
+ attribute for the recipe to read. A look a shipped recipe lacks is added to
3279
+ it, not forked from it:
3280
+
3281
+ ```ts standalone
3282
+ import { Style } from 'foldkit-mixins'
3283
+ import { ButtonSlots, Recipes } from 'foldkit-mixins-ui'
3284
+
3285
+ const Buttons = Recipes.Button.add({
3286
+ tone: { brand: { button: Style.self({ background: 'rebeccapurple', color: 'white' }) } },
3287
+ })
3288
+
3289
+ export const Brand = Style.forSlots(ButtonSlots)(Buttons({ tone: 'brand', variant: 'solid' }))
3290
+ ```
1172
3291
 
1173
3292
  ## Why some components needed a fork
1174
3293
 
1175
- The bridge needs a **consumer-visible attribute bundle**. `Menu`, `Listbox`,
1176
- `ComboBox`, `DatePicker`, and `Toast` build (parts of) their element tree
1177
- internally and expose no `toView`-style seam, so there is nothing for Mixins
1178
- to attach to — a limitation of the exposed render seam, not of Slot
1179
- resolution. Each is transcribed from the pinned `@foldkit/ui` source
1180
- (attributed in its module) with the missing `toView` added, and a parity
1181
- battery draws the fork and upstream's view over the same models; state,
1182
- Messages, update, Commands, and Mounts stay upstream in every case. If
1183
- upstream gains seams, the forks go away.
1184
-
1185
- That seam is what makes a row styleable. Drawn through `@foldkit/ui`'s own
1186
- view, a Menu item or a Listbox or Combobox option takes only a `className`
1187
- (its `itemToConfig`), so no Slot's attributes reach it and no Mixin can land
1188
- on it: the page can style it only from the panel's Slot, with a rule under it
1189
- keyed on the role and the state attributes upstream writes. Drawn through
1190
- the fork, the row is the `item` Slot, styled like any other:
3294
+ The bridge needs a **consumer-visible attribute bundle**. `Menu`, `Listbox`, `ComboBox`,
3295
+ `DatePicker` and `Toast` build (parts of) their element tree internally and expose no
3296
+ `toView`-style seam, so there is nothing for Mixins to attach to: a limitation of the exposed
3297
+ render seam, not of Slot resolution. Each is transcribed from the pinned `@foldkit/ui` source
3298
+ (attributed in its module) with the missing `toView` added, and a parity battery draws the fork
3299
+ and upstream's view over the same models; state, Messages, update, Commands and Mounts stay
3300
+ upstream in every case. If upstream gains seams, the forks go away.
3301
+
3302
+ That seam is what makes a row styleable. Drawn through `@foldkit/ui`'s own view, a Menu item or
3303
+ a Listbox or Combobox option takes only a `className` (its `itemToConfig`), so no Slot's
3304
+ attributes reach it and no Mixin can land on it: the page can style it only from the panel's
3305
+ Slot, with a rule under it keyed on the role and the state attributes upstream writes. Drawn
3306
+ through the fork, the row is the `item` Slot, styled like any other:
1191
3307
 
1192
3308
  ```ts standalone
1193
3309
  import { Capability, Slot, Slots, Style } from 'foldkit-mixins'
@@ -1208,19 +3324,16 @@ const PanelStyle = Style.forSlots(PanelSlots)({
1208
3324
  })
1209
3325
  ```
1210
3326
 
1211
- The second keeps the rule in the panel's layer and reads only what
1212
- `@foldkit/ui` publishes (`role`, `data-active`, `data-selected`,
1213
- `data-disabled`), but no Behavior or Mount can reach the row that way. Use
1214
- it for a port that keeps upstream's view; draw through the adapter otherwise.
1215
-
1216
- `Listbox`, `Combobox` and `Calendar` draw the standard markup from the
1217
- styled bundles when `toView` is given no `draw`; pass a `draw` to arrange the
1218
- parts yourself.
3327
+ The second keeps the rule in the panel's layer and reads only what `@foldkit/ui` publishes
3328
+ (`role`, `data-active`, `data-selected`, `data-disabled`), but no Behavior or Mount can reach the
3329
+ row that way. Use it for a port that keeps upstream's view; draw through the adapter otherwise.
3330
+ `Listbox`, `Combobox` and `Calendar` draw the standard markup from the styled bundles when
3331
+ `toView` is given no `draw`; pass a `draw` to arrange the parts yourself.
1219
3332
 
1220
3333
  **The Menu is three layers**, each built on the one before:
1221
3334
 
1222
3335
  ```text
1223
- Menu.init / update / view the component: string rows, submenus, a point
3336
+ Menu.init / update / view the component: rows with values, submenus, a point
1224
3337
  |
1225
3338
  MenuSlots, Menu.resolve, the panel adapter: styles any @foldkit/ui Menu
1226
3339
  Menu.toView, fluid, drawn through the fork, whoever keeps its Model
@@ -1230,72 +3343,49 @@ pointTarget
1230
3343
  MenuView the fork: @foldkit/ui/menu's view with a toView
1231
3344
  ```
1232
3345
 
1233
- `MenuView` is the fork; the Menu's Model, `update` and Mounts are upstream's.
1234
- The panel adapter styles a Menu drawn through it: `Menu.toView(mixins, { h },
1235
- draw?)` is that Menu's `toView`, and without a `draw` draws the panel through
1236
- `drawMenu` (`Menu.toView([MenuStyle.mixin], { h })` is a whole styled menu).
1237
- Menubar draws its menus this way, and so does an application that folds
1238
- `@foldkit/ui`'s Menu itself, for typed items or groups, which the component's
1239
- rows do not have. Such a Menu opens at a point with `Menu.drawAtPoint(point,
1240
- h)` as `toView`'s `draw` (its button becomes a mark of no size at `point`, an
1241
- `Option`, which the anchor places the rows against, so give the anchor `gap:
1242
- 0`) and `Menu.pointTarget({ onPress, onOpen }, h)` on the area: a right press
1243
- sends `onPress` with its point, which the application keeps, and the
1244
- `contextmenu` after it (or Shift+F10, or the ContextMenu key) sends `onOpen`,
1245
- which the application answers with the Menu's own `Opened` Message, the
1246
- browser's menu kept shut. A finger's press sends `onPress` too, so Android's
1247
- `contextmenu` for a held finger opens under it; iOS fires none, which the
1248
- component's `Menu.target` answers by opening on the hold itself. The component (`Menu.init/update/view`, in the table above) is
1249
- this package's own, drawn through the adapter, as the Slider is; its
1250
- `Menu.target` is `pointTarget` wired to its own Messages.
1251
-
1252
- `ToastView` follows the fork's shape: `ToastView.make` binds upstream's
1253
- `Toast.make` for the payload and swaps in the transcribed view; the dismiss
1254
- control stays inside the consumer's `entryToView`, so it is content, not a
1255
- slot. `Listbox` forks both variants over one shared transcription
1256
- (`ListboxView.create` and `ListboxView.Multi.create` bind the upstream
1257
- bundles; the single and multi Models are structurally identical, so the
1258
- single adaptor maps `maybeSelectedValue` to `selectedValues` exactly as
1259
- upstream's does). The forks add one view input upstream lacks, `direction?:
1260
- 'ltr' | 'rtl'`: under `'rtl'` a horizontal listbox's ArrowLeft moves to the
1261
- next item. `Combobox` follows the same shape over its own shared
1262
- transcription (`ComboboxView.create` / `ComboboxView.Multi.create`).
1263
-
1264
- `DatePicker`'s bundles mix the popover's pre-bound groups with the date
1265
- picker's own attributes, so they speak only the date picker's Message. Its
1266
- `toView` therefore takes no builder of the application's:
1267
- `DatePicker.toView(mixins, (resolved, h) => …)` hands `draw` the date
1268
- picker's builder, and without a `draw` draws upstream's markup.
1269
-
1270
- A DatePicker also picks a whole `Calendar.Selection`, a range or many days.
1271
- Fold it with `DatePicker.update(selection)`, given the selection the
1272
- application keeps: upstream closes the popover on every day picked, and this
1273
- keeps it open while the day leaves the selection unfinished (a range's first
1274
- end, any day of a Multiple selection), reporting `SelectedDate` either way for
1275
- the application to fold through `Calendar.picked`. Draw it with
1276
- `DatePickerView.view` taking `selection` and `triggerContent: selection =>
1277
- Html` in place of upstream's `maybeSelectedDate` and `triggerContent`, and
1278
- `toCalendarView: Calendar.toView(selection, mixins, { h })`. Under `name`,
1279
- each chosen day is a hidden input of its own, in order (a range's start,
1280
- then its end), so `FormData.getAll(name)` reads `[start, end]`; nothing chosen
1281
- submits the name once, empty.
1282
-
1283
- `DragAndDrop` and `Animation` do not have adapters here yet.
1284
-
1285
- ## Status
3346
+ `MenuView` is the fork; the Menu's Model, `update` and Mounts are upstream's. The panel adapter
3347
+ styles a Menu drawn through it: `Menu.toView(mixins, { h }, draw?)` is that Menu's `toView`, and
3348
+ without a `draw` draws the panel through `drawMenu` (`Menu.toView([MenuStyle.mixin], { h })` is a
3349
+ whole styled menu). Menubar draws its menus this way, and so does an application that folds
3350
+ `@foldkit/ui`'s Menu itself, for typed items or groups, which the component's rows do not have.
3351
+ Such a Menu opens at a point with `Menu.drawAtPoint(point, h)` as `toView`'s `draw` (its button
3352
+ becomes a mark of no size at `point`, an `Option`, which the anchor places the rows against, so
3353
+ give the anchor `gap: 0`) and `Menu.pointTarget({ onPress, onOpen }, h)` on the area: a right
3354
+ press sends `onPress` with its point, which the application keeps, and the `contextmenu` after it
3355
+ (or Shift+F10, or the ContextMenu key) sends `onOpen`, which the application answers with the
3356
+ Menu's own `Opened` Message, the browser's menu kept shut. A finger's press sends `onPress` too,
3357
+ so Android's `contextmenu` for a held finger opens under it; iOS fires none, which the
3358
+ component's `Menu.target` answers by opening on the hold itself. The component is this package's
3359
+ own, drawn through the adapter, as the Slider is; its `Menu.target` is `pointTarget` wired to its
3360
+ own Messages.
3361
+
3362
+ `ToastView` follows the fork's shape: `ToastView.make` binds upstream's `Toast.make` for the
3363
+ payload and swaps in the transcribed view. `Listbox` forks both variants over one shared
3364
+ transcription (`ListboxView.create` and `ListboxView.Multi.create` bind the upstream bundles; the
3365
+ single and multi Models are structurally identical, so the single adaptor maps
3366
+ `maybeSelectedValue` to `selectedValues` exactly as upstream's does). The forks add one view input
3367
+ upstream lacks, `direction?: 'ltr' | 'rtl'`: under `'rtl'` a horizontal listbox's ArrowLeft moves
3368
+ to the next item. `Combobox` follows the same shape over its own shared transcription
3369
+ (`ComboboxView.create` / `ComboboxView.Multi.create`). `DatePicker`'s bundles mix the popover's
3370
+ pre-bound groups with the date picker's own attributes, so they speak only the date picker's
3371
+ Message: its `toView` takes no builder of the application's, and without a `draw` draws upstream's
3372
+ markup. `DragAndDrop` and `Animation` do not have adapters here yet.
3373
+
3374
+ ## Limits and status
1286
3375
 
1287
3376
  The API is still settling in the `0.x` series. This package should stay small:
1288
3377
 
1289
3378
  ```text
1290
3379
  component state / accessibility -> @foldkit/ui
1291
3380
  merge semantics -> foldkit-mixins
1292
- adapter metadata -> foldkit-mixins-ui
3381
+ adapter metadata, widgets -> foldkit-mixins-ui
1293
3382
  ```
1294
3383
 
1295
- The components that keep a Model here (Menu, Toast, Sheet and the rest) do
1296
- so where `@foldkit/ui` has no such component, or composes one beneath them
1297
- (a Sheet is a Dialog, a Menubar a row of Menus); when upstream gains one,
1298
- the adapter is the better home.
3384
+ The components that keep a Model here (Menu, Toast, Sheet and the rest) do so where
3385
+ `@foldkit/ui` has no such component, or composes one beneath them (a Sheet is a Dialog, a Menubar
3386
+ a row of Menus); when upstream gains one, the adapter is the better home. The recipes assume the
3387
+ page ships the theme's tokens; a widget never reads a value out of a theme. Accessibility
3388
+ `support` entries are claims found in source, not a WCAG conformance statement.
1299
3389
 
1300
3390
  ## See also
1301
3391