@zonsh/ui 0.5.0 → 0.6.1

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 (559) hide show
  1. package/CHANGELOG.md +643 -0
  2. package/README.md +49 -21
  3. package/dist/brand.d.ts +3 -0
  4. package/dist/brand.js +7 -0
  5. package/dist/components/_breadcrumb-more.d.ts +6 -0
  6. package/dist/components/_breadcrumb-more.js +5 -0
  7. package/dist/components/_drawing-svg.d.ts +11 -0
  8. package/dist/components/_drawing-svg.js +30 -0
  9. package/dist/components/_media.d.ts +159 -0
  10. package/dist/components/_media.js +266 -0
  11. package/dist/components/_overlay.d.ts +8 -5
  12. package/dist/components/_overlay.js +11 -6
  13. package/dist/components/_scheduler-calendar.d.ts +71 -0
  14. package/dist/components/_scheduler-calendar.js +940 -0
  15. package/dist/components/_scheduler-editor.d.ts +29 -0
  16. package/dist/components/_scheduler-editor.js +111 -0
  17. package/dist/components/_scheduler-menu.d.ts +16 -0
  18. package/dist/components/_scheduler-menu.js +18 -0
  19. package/dist/components/_scheduler-parts.d.ts +164 -0
  20. package/dist/components/_scheduler-parts.js +327 -0
  21. package/dist/components/_suggest-list.d.ts +142 -0
  22. package/dist/components/_suggest-list.js +159 -0
  23. package/dist/components/_toolbar-more.d.ts +24 -0
  24. package/dist/components/_toolbar-more.js +25 -0
  25. package/dist/components/accordion.d.ts +1 -1
  26. package/dist/components/accordion.js +6 -6
  27. package/dist/components/action-sheet.d.ts +88 -0
  28. package/dist/components/action-sheet.js +124 -0
  29. package/dist/components/alert-dialog.js +3 -1
  30. package/dist/components/alert.d.ts +11 -18
  31. package/dist/components/alert.js +9 -6
  32. package/dist/components/app-bar.d.ts +93 -0
  33. package/dist/components/app-bar.js +175 -0
  34. package/dist/components/audio-player.d.ts +134 -0
  35. package/dist/components/audio-player.js +618 -0
  36. package/dist/components/avatar.d.ts +6 -6
  37. package/dist/components/avatar.js +13 -11
  38. package/dist/components/badge.d.ts +12 -12
  39. package/dist/components/badge.js +7 -5
  40. package/dist/components/bottom-nav.d.ts +53 -11
  41. package/dist/components/bottom-nav.js +388 -23
  42. package/dist/components/breadcrumb.d.ts +11 -2
  43. package/dist/components/breadcrumb.js +60 -6
  44. package/dist/components/button-group.js +5 -1
  45. package/dist/components/button.d.ts +23 -6
  46. package/dist/components/button.js +63 -7
  47. package/dist/components/calendar.js +8 -6
  48. package/dist/components/card.d.ts +10 -8
  49. package/dist/components/card.js +15 -14
  50. package/dist/components/carousel.d.ts +2 -2
  51. package/dist/components/carousel.js +21 -8
  52. package/dist/components/chart.d.ts +27 -1
  53. package/dist/components/chart.js +15 -5
  54. package/dist/components/checkbox.js +2 -2
  55. package/dist/components/code-block.d.ts +9 -2
  56. package/dist/components/code-block.js +26 -7
  57. package/dist/components/collapsible.js +3 -3
  58. package/dist/components/color-picker.d.ts +2 -2
  59. package/dist/components/color-picker.js +5 -5
  60. package/dist/components/combobox.d.ts +26 -7
  61. package/dist/components/combobox.js +32 -13
  62. package/dist/components/command.d.ts +29 -5
  63. package/dist/components/command.js +35 -10
  64. package/dist/components/context-menu.d.ts +5 -2
  65. package/dist/components/context-menu.js +24 -3
  66. package/dist/components/conversation.d.ts +1 -1
  67. package/dist/components/conversation.js +67 -13
  68. package/dist/components/copy-button.d.ts +1 -1
  69. package/dist/components/copy-button.js +1 -1
  70. package/dist/components/data-table.d.ts +6 -6
  71. package/dist/components/data-table.js +41 -15
  72. package/dist/components/date-picker.d.ts +31 -9
  73. package/dist/components/date-picker.js +100 -18
  74. package/dist/components/dialog.d.ts +17 -10
  75. package/dist/components/dialog.js +20 -13
  76. package/dist/components/drawer.d.ts +26 -8
  77. package/dist/components/drawer.js +75 -16
  78. package/dist/components/drawing.d.ts +25 -0
  79. package/dist/components/drawing.js +32 -0
  80. package/dist/components/empty.js +2 -2
  81. package/dist/components/feature-list.d.ts +65 -13
  82. package/dist/components/feature-list.js +116 -15
  83. package/dist/components/field.js +2 -2
  84. package/dist/components/file-drop.d.ts +9 -7
  85. package/dist/components/file-drop.js +8 -43
  86. package/dist/components/filter-bar.d.ts +10 -9
  87. package/dist/components/filter-bar.js +42 -25
  88. package/dist/components/graph.d.ts +19 -3
  89. package/dist/components/graph.js +170 -25
  90. package/dist/components/illustration.js +3 -28
  91. package/dist/components/input-group.d.ts +5 -10
  92. package/dist/components/input-group.js +16 -16
  93. package/dist/components/input.d.ts +2 -2
  94. package/dist/components/input.js +3 -3
  95. package/dist/components/item.d.ts +9 -6
  96. package/dist/components/item.js +13 -8
  97. package/dist/components/kbd.d.ts +1 -1
  98. package/dist/components/kbd.js +1 -1
  99. package/dist/components/lightbox.d.ts +76 -9
  100. package/dist/components/lightbox.js +333 -45
  101. package/dist/components/locale.d.ts +6 -6
  102. package/dist/components/logo.d.ts +21 -1
  103. package/dist/components/logo.js +32 -2
  104. package/dist/components/markdown-editor.d.ts +275 -0
  105. package/dist/components/markdown-editor.js +831 -0
  106. package/dist/components/mentions.d.ts +153 -0
  107. package/dist/components/mentions.js +507 -0
  108. package/dist/components/menu.d.ts +2 -1
  109. package/dist/components/menu.js +5 -4
  110. package/dist/components/menubar.d.ts +23 -5
  111. package/dist/components/menubar.js +97 -22
  112. package/dist/components/message.d.ts +62 -11
  113. package/dist/components/message.js +49 -13
  114. package/dist/components/meter.js +1 -1
  115. package/dist/components/money-input.d.ts +1 -1
  116. package/dist/components/money-input.js +1 -1
  117. package/dist/components/native-select.d.ts +2 -2
  118. package/dist/components/native-select.js +4 -4
  119. package/dist/components/navigation-menu.d.ts +3 -1
  120. package/dist/components/navigation-menu.js +23 -12
  121. package/dist/components/number-field.d.ts +2 -9
  122. package/dist/components/number-field.js +86 -36
  123. package/dist/components/number-roll.d.ts +26 -0
  124. package/dist/components/number-roll.js +81 -0
  125. package/dist/components/otp-field.d.ts +1 -1
  126. package/dist/components/otp-field.js +24 -3
  127. package/dist/components/pagination.d.ts +11 -3
  128. package/dist/components/pagination.js +59 -13
  129. package/dist/components/pdf-viewer.d.ts +1 -1
  130. package/dist/components/pdf-viewer.js +8 -8
  131. package/dist/components/phone-input.d.ts +1 -1
  132. package/dist/components/phone-input.js +2 -2
  133. package/dist/components/popover.js +5 -3
  134. package/dist/components/preview-card.d.ts +37 -2
  135. package/dist/components/preview-card.js +226 -2
  136. package/dist/components/progress.js +1 -1
  137. package/dist/components/prompt-input.d.ts +1 -1
  138. package/dist/components/prompt-input.js +24 -14
  139. package/dist/components/pull-to-refresh.d.ts +50 -0
  140. package/dist/components/pull-to-refresh.js +189 -0
  141. package/dist/components/quote.d.ts +6 -1
  142. package/dist/components/quote.js +3 -2
  143. package/dist/components/radio-group.js +1 -1
  144. package/dist/components/rating.d.ts +4 -1
  145. package/dist/components/rating.js +131 -10
  146. package/dist/components/reasoning.d.ts +1 -1
  147. package/dist/components/reasoning.js +7 -3
  148. package/dist/components/resizable.d.ts +1 -1
  149. package/dist/components/resizable.js +2 -2
  150. package/dist/components/response.d.ts +1 -1
  151. package/dist/components/response.js +18 -6
  152. package/dist/components/scheduler.d.ts +352 -0
  153. package/dist/components/scheduler.js +1717 -0
  154. package/dist/components/scroll-area.js +1 -1
  155. package/dist/components/select.d.ts +17 -4
  156. package/dist/components/select.js +140 -9
  157. package/dist/components/separator.d.ts +1 -1
  158. package/dist/components/separator.js +3 -3
  159. package/dist/components/sidebar.d.ts +44 -3
  160. package/dist/components/sidebar.js +57 -17
  161. package/dist/components/site-header.d.ts +18 -13
  162. package/dist/components/site-header.js +23 -11
  163. package/dist/components/skeleton.d.ts +17 -7
  164. package/dist/components/skeleton.js +22 -7
  165. package/dist/components/slider.js +2 -2
  166. package/dist/components/sortable.d.ts +55 -4
  167. package/dist/components/sortable.js +172 -103
  168. package/dist/components/sources.d.ts +1 -1
  169. package/dist/components/sources.js +2 -2
  170. package/dist/components/spinner.d.ts +4 -4
  171. package/dist/components/spinner.js +4 -4
  172. package/dist/components/stat.d.ts +21 -4
  173. package/dist/components/stat.js +17 -8
  174. package/dist/components/stepper.d.ts +1 -1
  175. package/dist/components/stepper.js +8 -7
  176. package/dist/components/suggestions.d.ts +11 -3
  177. package/dist/components/suggestions.js +10 -4
  178. package/dist/components/swipe-actions.d.ts +66 -0
  179. package/dist/components/swipe-actions.js +292 -0
  180. package/dist/components/switch.js +1 -1
  181. package/dist/components/table.d.ts +12 -6
  182. package/dist/components/table.js +78 -30
  183. package/dist/components/tabs.js +7 -4
  184. package/dist/components/tag.d.ts +19 -20
  185. package/dist/components/tag.js +9 -5
  186. package/dist/components/tags-input.d.ts +2 -7
  187. package/dist/components/tags-input.js +11 -8
  188. package/dist/components/textarea.d.ts +3 -2
  189. package/dist/components/textarea.js +4 -3
  190. package/dist/components/theme.d.ts +49 -6
  191. package/dist/components/theme.js +147 -9
  192. package/dist/components/time-field.d.ts +4 -9
  193. package/dist/components/time-field.js +6 -6
  194. package/dist/components/timeline.d.ts +19 -3
  195. package/dist/components/timeline.js +21 -9
  196. package/dist/components/tippy.d.ts +17 -1
  197. package/dist/components/tippy.js +95 -15
  198. package/dist/components/toast.d.ts +2 -7
  199. package/dist/components/toast.js +12 -8
  200. package/dist/components/toggle-group.d.ts +7 -1
  201. package/dist/components/toggle-group.js +16 -5
  202. package/dist/components/toggle.d.ts +2 -2
  203. package/dist/components/toggle.js +3 -2
  204. package/dist/components/tool-call.d.ts +1 -1
  205. package/dist/components/tool-call.js +4 -4
  206. package/dist/components/toolbar.d.ts +57 -4
  207. package/dist/components/toolbar.js +216 -16
  208. package/dist/components/tooltip.d.ts +1 -1
  209. package/dist/components/tooltip.js +4 -2
  210. package/dist/components/tour.d.ts +1 -1
  211. package/dist/components/tour.js +36 -15
  212. package/dist/components/tree.js +5 -5
  213. package/dist/components/typography.d.ts +31 -8
  214. package/dist/components/typography.js +21 -10
  215. package/dist/components/video-player.d.ts +7 -2
  216. package/dist/components/video-player.js +121 -220
  217. package/dist/index.d.ts +99 -92
  218. package/dist/index.js +99 -92
  219. package/dist/lib/calendar.d.ts +153 -0
  220. package/dist/lib/calendar.js +312 -0
  221. package/dist/lib/cn.d.ts +3 -1
  222. package/dist/lib/cn.js +5 -0
  223. package/dist/lib/code-highlight.d.ts +14 -0
  224. package/dist/lib/code-highlight.js +81 -18
  225. package/dist/lib/drag.d.ts +39 -0
  226. package/dist/lib/drag.js +96 -0
  227. package/dist/lib/editorial-assets.js +16 -8
  228. package/dist/lib/figure/figures/automation.js +25 -6
  229. package/dist/lib/figure/figures/bar-chart.js +6 -1
  230. package/dist/lib/figure/figures/brackets-classic.js +4 -1
  231. package/dist/lib/figure/figures/city.js +12 -2
  232. package/dist/lib/figure/figures/conveyor.js +17 -4
  233. package/dist/lib/figure/figures/database.js +5 -2
  234. package/dist/lib/figure/figures/documents.js +11 -3
  235. package/dist/lib/figure/figures/inbox.js +5 -2
  236. package/dist/lib/figure/figures/laptop.js +3 -1
  237. package/dist/lib/figure/figures/pipeline.js +45 -10
  238. package/dist/lib/figure/figures/platform.js +62 -7
  239. package/dist/lib/figure/figures/server.js +21 -5
  240. package/dist/lib/figure/figures/spreadsheet.js +29 -5
  241. package/dist/lib/figure/kernel.d.ts +4 -2
  242. package/dist/lib/figure/kernel.js +10 -5
  243. package/dist/lib/figure/parts.js +6 -2
  244. package/dist/lib/files.d.ts +31 -0
  245. package/dist/lib/files.js +60 -0
  246. package/dist/lib/gesture.d.ts +70 -0
  247. package/dist/lib/gesture.js +141 -0
  248. package/dist/lib/glide.d.ts +5 -0
  249. package/dist/lib/glide.js +9 -1
  250. package/dist/lib/icons.d.ts +1 -0
  251. package/dist/lib/icons.js +6 -0
  252. package/dist/lib/illustration-library.js +1 -6
  253. package/dist/lib/markdown-edit.d.ts +112 -0
  254. package/dist/lib/markdown-edit.js +557 -0
  255. package/dist/lib/markdown-rich-editor.d.ts +188 -0
  256. package/dist/lib/markdown-rich-editor.js +1153 -0
  257. package/dist/lib/markdown-rich.d.ts +63 -0
  258. package/dist/lib/markdown-rich.js +534 -0
  259. package/dist/lib/mentions.d.ts +100 -0
  260. package/dist/lib/mentions.js +246 -0
  261. package/dist/lib/motion.d.ts +18 -0
  262. package/dist/lib/motion.js +43 -5
  263. package/dist/lib/number-roll.d.ts +89 -0
  264. package/dist/lib/number-roll.js +391 -0
  265. package/dist/lib/platform.d.ts +6 -0
  266. package/dist/lib/platform.js +14 -0
  267. package/dist/lib/portal-container.d.ts +9 -0
  268. package/dist/lib/portal-container.js +10 -0
  269. package/dist/lib/press.d.ts +5 -0
  270. package/dist/lib/press.js +186 -0
  271. package/dist/lib/scheduler.d.ts +128 -0
  272. package/dist/lib/scheduler.js +272 -0
  273. package/dist/lib/scroll-edges.d.ts +9 -0
  274. package/dist/lib/scroll-edges.js +50 -0
  275. package/dist/lib/table-fit.d.ts +1 -1
  276. package/dist/lib/table-fit.js +65 -8
  277. package/dist/lib/theme-preset.d.ts +267 -0
  278. package/dist/lib/theme-preset.js +1046 -0
  279. package/dist/lib/theme-script.d.ts +23 -3
  280. package/dist/lib/theme-script.js +17 -5
  281. package/dist/lib/tippy/sprite.d.ts +36 -4
  282. package/dist/lib/tippy/sprite.js +188 -15
  283. package/dist/lib/tone.d.ts +4 -0
  284. package/dist/lib/tone.js +1 -0
  285. package/dist/messages/de.d.ts +3 -3
  286. package/dist/messages/de.js +274 -3
  287. package/dist/skills/zon-ui/SKILL.md +279 -0
  288. package/dist/skills/zon-ui/references/authoring.md +265 -0
  289. package/dist/skills/zon-ui/references/brand.md +416 -0
  290. package/dist/skills/zon-ui/references/components/accordion.md +199 -0
  291. package/dist/skills/zon-ui/references/components/action-sheet.md +268 -0
  292. package/dist/skills/zon-ui/references/components/alert-dialog.md +276 -0
  293. package/dist/skills/zon-ui/references/components/alert.md +167 -0
  294. package/dist/skills/zon-ui/references/components/app-bar.md +307 -0
  295. package/dist/skills/zon-ui/references/components/ascii-field.md +121 -0
  296. package/dist/skills/zon-ui/references/components/aspect-ratio.md +112 -0
  297. package/dist/skills/zon-ui/references/components/audio-player.md +231 -0
  298. package/dist/skills/zon-ui/references/components/avatar.md +98 -0
  299. package/dist/skills/zon-ui/references/components/badge.md +227 -0
  300. package/dist/skills/zon-ui/references/components/bottom-nav.md +709 -0
  301. package/dist/skills/zon-ui/references/components/breadcrumb.md +143 -0
  302. package/dist/skills/zon-ui/references/components/button-group.md +216 -0
  303. package/dist/skills/zon-ui/references/components/button.md +309 -0
  304. package/dist/skills/zon-ui/references/components/calendar.md +296 -0
  305. package/dist/skills/zon-ui/references/components/card.md +158 -0
  306. package/dist/skills/zon-ui/references/components/carousel.md +297 -0
  307. package/dist/skills/zon-ui/references/components/chart.md +739 -0
  308. package/dist/skills/zon-ui/references/components/chat.md +417 -0
  309. package/dist/skills/zon-ui/references/components/checkbox.md +219 -0
  310. package/dist/skills/zon-ui/references/components/code-block.md +143 -0
  311. package/dist/skills/zon-ui/references/components/code-highlight.md +118 -0
  312. package/dist/skills/zon-ui/references/components/collapsible.md +146 -0
  313. package/dist/skills/zon-ui/references/components/color-picker.md +200 -0
  314. package/dist/skills/zon-ui/references/components/combobox.md +455 -0
  315. package/dist/skills/zon-ui/references/components/command.md +326 -0
  316. package/dist/skills/zon-ui/references/components/contact-form.md +562 -0
  317. package/dist/skills/zon-ui/references/components/context-menu.md +159 -0
  318. package/dist/skills/zon-ui/references/components/conversation.md +146 -0
  319. package/dist/skills/zon-ui/references/components/copy-button.md +162 -0
  320. package/dist/skills/zon-ui/references/components/crm.md +1022 -0
  321. package/dist/skills/zon-ui/references/components/dashboard.md +612 -0
  322. package/dist/skills/zon-ui/references/components/data-table.md +776 -0
  323. package/dist/skills/zon-ui/references/components/date-picker.md +444 -0
  324. package/dist/skills/zon-ui/references/components/dialog.md +335 -0
  325. package/dist/skills/zon-ui/references/components/direction.md +165 -0
  326. package/dist/skills/zon-ui/references/components/drawer.md +276 -0
  327. package/dist/skills/zon-ui/references/components/drawing.md +94 -0
  328. package/dist/skills/zon-ui/references/components/empty.md +225 -0
  329. package/dist/skills/zon-ui/references/components/feature-list.md +412 -0
  330. package/dist/skills/zon-ui/references/components/field.md +209 -0
  331. package/dist/skills/zon-ui/references/components/file-drop.md +234 -0
  332. package/dist/skills/zon-ui/references/components/filter-bar.md +485 -0
  333. package/dist/skills/zon-ui/references/components/form.md +970 -0
  334. package/dist/skills/zon-ui/references/components/graph.md +339 -0
  335. package/dist/skills/zon-ui/references/components/illustration.md +497 -0
  336. package/dist/skills/zon-ui/references/components/inbox.md +263 -0
  337. package/dist/skills/zon-ui/references/components/input-group.md +339 -0
  338. package/dist/skills/zon-ui/references/components/input.md +189 -0
  339. package/dist/skills/zon-ui/references/components/item.md +277 -0
  340. package/dist/skills/zon-ui/references/components/kanban.md +626 -0
  341. package/dist/skills/zon-ui/references/components/kbd.md +116 -0
  342. package/dist/skills/zon-ui/references/components/label.md +104 -0
  343. package/dist/skills/zon-ui/references/components/layout.md +291 -0
  344. package/dist/skills/zon-ui/references/components/lightbox.md +235 -0
  345. package/dist/skills/zon-ui/references/components/locale.md +279 -0
  346. package/dist/skills/zon-ui/references/components/logo.md +257 -0
  347. package/dist/skills/zon-ui/references/components/markdown-editor.md +558 -0
  348. package/dist/skills/zon-ui/references/components/mentions.md +512 -0
  349. package/dist/skills/zon-ui/references/components/menu.md +218 -0
  350. package/dist/skills/zon-ui/references/components/menubar.md +292 -0
  351. package/dist/skills/zon-ui/references/components/message.md +243 -0
  352. package/dist/skills/zon-ui/references/components/meter.md +105 -0
  353. package/dist/skills/zon-ui/references/components/money-input.md +333 -0
  354. package/dist/skills/zon-ui/references/components/native-select.md +197 -0
  355. package/dist/skills/zon-ui/references/components/navigation-menu.md +253 -0
  356. package/dist/skills/zon-ui/references/components/number-field.md +210 -0
  357. package/dist/skills/zon-ui/references/components/number-roll.md +175 -0
  358. package/dist/skills/zon-ui/references/components/onboarding.md +896 -0
  359. package/dist/skills/zon-ui/references/components/otp-field.md +166 -0
  360. package/dist/skills/zon-ui/references/components/pagination.md +109 -0
  361. package/dist/skills/zon-ui/references/components/pdf-viewer.md +177 -0
  362. package/dist/skills/zon-ui/references/components/phone-input.md +252 -0
  363. package/dist/skills/zon-ui/references/components/popover.md +176 -0
  364. package/dist/skills/zon-ui/references/components/preview-card.md +193 -0
  365. package/dist/skills/zon-ui/references/components/pricing.md +724 -0
  366. package/dist/skills/zon-ui/references/components/progress.md +92 -0
  367. package/dist/skills/zon-ui/references/components/prompt-input.md +307 -0
  368. package/dist/skills/zon-ui/references/components/pull-to-refresh.md +188 -0
  369. package/dist/skills/zon-ui/references/components/quote.md +115 -0
  370. package/dist/skills/zon-ui/references/components/radio-group.md +215 -0
  371. package/dist/skills/zon-ui/references/components/rating.md +260 -0
  372. package/dist/skills/zon-ui/references/components/reasoning.md +102 -0
  373. package/dist/skills/zon-ui/references/components/resizable.md +213 -0
  374. package/dist/skills/zon-ui/references/components/response.md +170 -0
  375. package/dist/skills/zon-ui/references/components/scheduler.md +732 -0
  376. package/dist/skills/zon-ui/references/components/scroll-area.md +122 -0
  377. package/dist/skills/zon-ui/references/components/select.md +351 -0
  378. package/dist/skills/zon-ui/references/components/separator.md +103 -0
  379. package/dist/skills/zon-ui/references/components/settings.md +793 -0
  380. package/dist/skills/zon-ui/references/components/shop.md +1715 -0
  381. package/dist/skills/zon-ui/references/components/sidebar.md +813 -0
  382. package/dist/skills/zon-ui/references/components/sign-in.md +1639 -0
  383. package/dist/skills/zon-ui/references/components/site-header.md +303 -0
  384. package/dist/skills/zon-ui/references/components/skeleton.md +256 -0
  385. package/dist/skills/zon-ui/references/components/slider.md +172 -0
  386. package/dist/skills/zon-ui/references/components/sortable.md +405 -0
  387. package/dist/skills/zon-ui/references/components/sources.md +106 -0
  388. package/dist/skills/zon-ui/references/components/spinner.md +222 -0
  389. package/dist/skills/zon-ui/references/components/stat.md +267 -0
  390. package/dist/skills/zon-ui/references/components/stepper.md +285 -0
  391. package/dist/skills/zon-ui/references/components/suggestions.md +146 -0
  392. package/dist/skills/zon-ui/references/components/swipe-actions.md +344 -0
  393. package/dist/skills/zon-ui/references/components/switch.md +160 -0
  394. package/dist/skills/zon-ui/references/components/table.md +999 -0
  395. package/dist/skills/zon-ui/references/components/tabs.md +258 -0
  396. package/dist/skills/zon-ui/references/components/tag.md +115 -0
  397. package/dist/skills/zon-ui/references/components/tags-input.md +216 -0
  398. package/dist/skills/zon-ui/references/components/textarea.md +95 -0
  399. package/dist/skills/zon-ui/references/components/theme-editor.md +3940 -0
  400. package/dist/skills/zon-ui/references/components/theme.md +362 -0
  401. package/dist/skills/zon-ui/references/components/time-field.md +222 -0
  402. package/dist/skills/zon-ui/references/components/timeline.md +285 -0
  403. package/dist/skills/zon-ui/references/components/tippy.md +243 -0
  404. package/dist/skills/zon-ui/references/components/toast.md +220 -0
  405. package/dist/skills/zon-ui/references/components/toggle-group.md +261 -0
  406. package/dist/skills/zon-ui/references/components/toggle.md +167 -0
  407. package/dist/skills/zon-ui/references/components/tool-call.md +146 -0
  408. package/dist/skills/zon-ui/references/components/toolbar.md +260 -0
  409. package/dist/skills/zon-ui/references/components/tooltip.md +172 -0
  410. package/dist/skills/zon-ui/references/components/tour.md +423 -0
  411. package/dist/skills/zon-ui/references/components/tree.md +481 -0
  412. package/dist/skills/zon-ui/references/components/typography.md +347 -0
  413. package/dist/skills/zon-ui/references/components/video-player.md +386 -0
  414. package/dist/skills/zon-ui/references/marketing.md +467 -0
  415. package/dist/skills/zon-ui/references/motion.md +455 -0
  416. package/dist/skills/zon-ui/references/recipes.md +1232 -0
  417. package/dist/skills/zon-ui/references/tokens.md +866 -0
  418. package/dist/sources/accordion.css +4 -0
  419. package/dist/sources/action-sheet.css +11 -0
  420. package/dist/sources/alert-dialog.css +6 -0
  421. package/dist/sources/alert.css +3 -0
  422. package/dist/sources/app-bar.css +14 -0
  423. package/dist/sources/ascii-field.css +3 -0
  424. package/dist/sources/aspect-ratio.css +3 -0
  425. package/dist/sources/audio-player.css +20 -0
  426. package/dist/sources/avatar.css +3 -0
  427. package/dist/sources/badge.css +3 -0
  428. package/dist/sources/bottom-nav.css +9 -0
  429. package/dist/sources/breadcrumb.css +14 -0
  430. package/dist/sources/button-group.css +3 -0
  431. package/dist/sources/button.css +9 -0
  432. package/dist/sources/calendar.css +13 -0
  433. package/dist/sources/card.css +3 -0
  434. package/dist/sources/carousel.css +11 -0
  435. package/dist/sources/chart.css +5 -0
  436. package/dist/sources/checkbox.css +6 -0
  437. package/dist/sources/code-block.css +13 -0
  438. package/dist/sources/collapsible.css +4 -0
  439. package/dist/sources/color-picker.css +13 -0
  440. package/dist/sources/combobox.css +13 -0
  441. package/dist/sources/command.css +13 -0
  442. package/dist/sources/context-menu.css +12 -0
  443. package/dist/sources/conversation.css +10 -0
  444. package/dist/sources/copy-button.css +10 -0
  445. package/dist/sources/data-table.css +27 -0
  446. package/dist/sources/date-picker.css +20 -0
  447. package/dist/sources/dialog.css +9 -0
  448. package/dist/sources/direction.css +2 -0
  449. package/dist/sources/drawer.css +9 -0
  450. package/dist/sources/drawing.css +5 -0
  451. package/dist/sources/empty.css +3 -0
  452. package/dist/sources/feature-list.css +4 -0
  453. package/dist/sources/field.css +4 -0
  454. package/dist/sources/file-drop.css +15 -0
  455. package/dist/sources/filter-bar.css +30 -0
  456. package/dist/sources/form.css +4 -0
  457. package/dist/sources/graph.css +19 -0
  458. package/dist/sources/illustration.css +28 -0
  459. package/dist/sources/input-group.css +7 -0
  460. package/dist/sources/input.css +3 -0
  461. package/dist/sources/item.css +4 -0
  462. package/dist/sources/kbd.css +5 -0
  463. package/dist/sources/label.css +3 -0
  464. package/dist/sources/layout.css +3 -0
  465. package/dist/sources/lightbox.css +33 -0
  466. package/dist/sources/locale.css +2 -0
  467. package/dist/sources/logo.css +4 -0
  468. package/dist/sources/markdown-editor.css +41 -0
  469. package/dist/sources/mentions.css +13 -0
  470. package/dist/sources/menu.css +11 -0
  471. package/dist/sources/menubar.css +14 -0
  472. package/dist/sources/message.css +16 -0
  473. package/dist/sources/meter.css +4 -0
  474. package/dist/sources/money-input.css +10 -0
  475. package/dist/sources/native-select.css +4 -0
  476. package/dist/sources/navigation-menu.css +8 -0
  477. package/dist/sources/number-field.css +8 -0
  478. package/dist/sources/number-roll.css +6 -0
  479. package/dist/sources/otp-field.css +5 -0
  480. package/dist/sources/pagination.css +11 -0
  481. package/dist/sources/pdf-viewer.css +30 -0
  482. package/dist/sources/phone-input.css +20 -0
  483. package/dist/sources/popover.css +7 -0
  484. package/dist/sources/preview-card.css +7 -0
  485. package/dist/sources/progress.css +4 -0
  486. package/dist/sources/prompt-input.css +15 -0
  487. package/dist/sources/pull-to-refresh.css +14 -0
  488. package/dist/sources/quote.css +3 -0
  489. package/dist/sources/radio-group.css +5 -0
  490. package/dist/sources/rating.css +6 -0
  491. package/dist/sources/reasoning.css +6 -0
  492. package/dist/sources/resizable.css +4 -0
  493. package/dist/sources/response.css +16 -0
  494. package/dist/sources/scheduler.css +44 -0
  495. package/dist/sources/scroll-area.css +3 -0
  496. package/dist/sources/select.css +12 -0
  497. package/dist/sources/separator.css +3 -0
  498. package/dist/sources/sidebar.css +19 -0
  499. package/dist/sources/site-header.css +15 -0
  500. package/dist/sources/skeleton.css +3 -0
  501. package/dist/sources/slider.css +6 -0
  502. package/dist/sources/sortable.css +12 -0
  503. package/dist/sources/sources.css +6 -0
  504. package/dist/sources/spinner.css +6 -0
  505. package/dist/sources/stat.css +9 -0
  506. package/dist/sources/stepper.css +6 -0
  507. package/dist/sources/suggestions.css +10 -0
  508. package/dist/sources/swipe-actions.css +20 -0
  509. package/dist/sources/switch.css +5 -0
  510. package/dist/sources/table.css +7 -0
  511. package/dist/sources/tabs.css +5 -0
  512. package/dist/sources/tag.css +3 -0
  513. package/dist/sources/tags-input.css +6 -0
  514. package/dist/sources/textarea.css +3 -0
  515. package/dist/sources/theme.css +13 -0
  516. package/dist/sources/time-field.css +7 -0
  517. package/dist/sources/timeline.css +7 -0
  518. package/dist/sources/tippy.css +6 -0
  519. package/dist/sources/toast.css +6 -0
  520. package/dist/sources/toggle-group.css +5 -0
  521. package/dist/sources/toggle.css +3 -0
  522. package/dist/sources/tool-call.css +16 -0
  523. package/dist/sources/toolbar.css +14 -0
  524. package/dist/sources/tooltip.css +6 -0
  525. package/dist/sources/tour.css +14 -0
  526. package/dist/sources/tree.css +6 -0
  527. package/dist/sources/typography.css +4 -0
  528. package/dist/sources/video-player.css +21 -0
  529. package/dist/styles/ai.css +3 -0
  530. package/dist/styles/brand.css +98 -0
  531. package/dist/styles/core.css +266 -0
  532. package/dist/styles/editor.css +3 -0
  533. package/dist/styles/expressive.css +35 -56
  534. package/dist/styles/fonts.css +61 -117
  535. package/dist/styles/graph.css +4 -0
  536. package/dist/styles/illustration.css +4 -0
  537. package/dist/styles/index.css +11 -201
  538. package/dist/styles/material.css +138 -12
  539. package/dist/styles/parts/ai.css +18 -13
  540. package/dist/styles/parts/brand.css +2 -2
  541. package/dist/styles/parts/controls.css +29 -20
  542. package/dist/styles/parts/data.css +13 -9
  543. package/dist/styles/parts/editor.css +372 -0
  544. package/dist/styles/parts/feedback.css +32 -2
  545. package/dist/styles/parts/foundations.css +12 -7
  546. package/dist/styles/parts/graph.css +25 -9
  547. package/dist/styles/parts/inputs.css +172 -9
  548. package/dist/styles/parts/isometric.css +6 -5
  549. package/dist/styles/parts/navigation.css +206 -27
  550. package/dist/styles/parts/overlays.css +19 -4
  551. package/dist/styles/parts/pdf.css +2 -2
  552. package/dist/styles/pdf.css +3 -0
  553. package/dist/styles/prose.css +3 -0
  554. package/dist/styles/tokens.css +89 -14
  555. package/dist/theme.d.ts +1 -0
  556. package/dist/theme.js +5 -0
  557. package/dist/vite.d.ts +48 -59
  558. package/dist/vite.js +54 -21
  559. package/package.json +69 -2
@@ -0,0 +1,1232 @@
1
+ # Recipes
2
+
3
+ Short, task-shaped answers: the goal in one line, the whole code to copy, and why it is built that
4
+ way. Each one uses only `@zonsh/ui` exports (and `lucide-react` icons). The server calls are
5
+ `fetch` to a placeholder endpoint: put your own in their place.
6
+
7
+ Every recipe that calls `toast` needs one `<Toaster />` mounted at the root of the app.
8
+
9
+ ## Form with server validation
10
+
11
+ Submit a form, show the server's refusals on the fields they are about, and keep the button busy
12
+ while it waits.
13
+
14
+ ```tsx
15
+ import {
16
+ Button,
17
+ Field,
18
+ FieldDescription,
19
+ FieldError,
20
+ FieldLabel,
21
+ Form,
22
+ FormActions,
23
+ Input,
24
+ toast,
25
+ } from "@zonsh/ui";
26
+ import * as React from "react";
27
+
28
+ type FieldErrors = Record<string, string>;
29
+
30
+ /** Your endpoint. It answers 422 with `{ errors: { slug: "…" } }` when it refuses a value. */
31
+ async function createProject(values: Record<string, unknown>): Promise<FieldErrors | null> {
32
+ const response = await fetch("/api/projects", {
33
+ method: "POST",
34
+ headers: { "Content-Type": "application/json" },
35
+ body: JSON.stringify(values),
36
+ });
37
+ if (response.status === 422) return ((await response.json()) as { errors: FieldErrors }).errors;
38
+ if (!response.ok) throw new Error(`Request failed with ${response.status}`);
39
+ return null;
40
+ }
41
+
42
+ export function NewProjectForm() {
43
+ const [errors, setErrors] = React.useState<FieldErrors>({});
44
+ const [pending, setPending] = React.useState(false);
45
+
46
+ return (
47
+ <Form
48
+ className="max-w-md"
49
+ errors={errors}
50
+ onFormSubmit={async (values) => {
51
+ setPending(true);
52
+ try {
53
+ const refused = await createProject(values);
54
+ setErrors(refused ?? {});
55
+ if (!refused) toast.success("Project created.");
56
+ } catch {
57
+ toast.error("We couldn't reach the server.", { description: "Nothing was saved. Try again." });
58
+ } finally {
59
+ setPending(false);
60
+ }
61
+ }}
62
+ >
63
+ <Field name="name">
64
+ <FieldLabel>Project name</FieldLabel>
65
+ <Input required maxLength={60} />
66
+ <FieldError />
67
+ </Field>
68
+ <Field name="slug">
69
+ <FieldLabel>Address</FieldLabel>
70
+ <Input required pattern="[a-z0-9-]+" placeholder="spring-catalogue" />
71
+ <FieldDescription>
72
+ Lower-case letters, digits and hyphens. It can't be changed later.
73
+ </FieldDescription>
74
+ <FieldError />
75
+ </Field>
76
+ <FormActions>
77
+ <Button type="submit" loading={pending} loadingLabel="Creating project">
78
+ Create project
79
+ </Button>
80
+ </FormActions>
81
+ </Form>
82
+ );
83
+ }
84
+ ```
85
+
86
+ - `Form errors` takes the server's answer keyed by field `name`; each bare `<FieldError />` shows
87
+ its own, focus moves to the first, and it clears once that field is changed.
88
+ - Native constraints (`required`, `pattern`) are checked before anything is sent, so the server
89
+ only sees well-formed values.
90
+ - `loading` on the submit keeps its width, sets `aria-busy` and ignores a second click;
91
+ `loadingLabel` says what is happening. Don't disable it to signal errors.
92
+ - A failure that belongs to no field (the network) is a toast, and says nothing was lost.
93
+
94
+ ## Filtered table with the URL as state
95
+
96
+ Faceted filters above a data table, kept in the address so a filtered view can be shared,
97
+ bookmarked and reloaded.
98
+
99
+ ```tsx
100
+ import { Tag } from "@zonsh/ui";
101
+ import { DataTable, createDataTableColumnHelper } from "@zonsh/ui/data-table";
102
+ import { FilterBar, matchesFilters, type Filter, type FilterField } from "@zonsh/ui/filter-bar";
103
+ import * as React from "react";
104
+
105
+ interface Order {
106
+ id: string;
107
+ customer: string;
108
+ status: "Paid" | "Shipped" | "Refunded";
109
+ total: number;
110
+ placed: Date;
111
+ }
112
+
113
+ const fields: FilterField<Order>[] = [
114
+ {
115
+ id: "status",
116
+ label: "Status",
117
+ kind: "select",
118
+ options: [
119
+ { value: "Paid", label: "Paid" },
120
+ { value: "Shipped", label: "Shipped" },
121
+ { value: "Refunded", label: "Refunded" },
122
+ ],
123
+ },
124
+ { id: "customer", label: "Customer", kind: "text" },
125
+ { id: "total", label: "Total", kind: "number", format: { style: "currency", currency: "EUR" } },
126
+ { id: "placed", label: "Placed", kind: "date" },
127
+ ];
128
+
129
+ // Module scope: built once, not on every render.
130
+ const column = createDataTableColumnHelper<Order>();
131
+ const columns = column.columns([
132
+ column.accessor("id", { header: "Order" }),
133
+ column.accessor("customer", { header: "Customer" }),
134
+ column.accessor("status", { header: "Status", cell: (info) => <Tag dot>{info.getValue()}</Tag> }),
135
+ column.accessor("total", {
136
+ header: "Total",
137
+ meta: { numeric: true },
138
+ cell: (info) => info.getValue().toLocaleString(undefined, { style: "currency", currency: "EUR" }),
139
+ }),
140
+ ]);
141
+
142
+ /** The filters live in `?filters=…`, so a filtered view can be bookmarked, shared and reloaded. */
143
+ function readFilters(): Filter[] {
144
+ try {
145
+ return JSON.parse(new URLSearchParams(window.location.search).get("filters") ?? "[]") as Filter[];
146
+ } catch {
147
+ return [];
148
+ }
149
+ }
150
+ function writeFilters(filters: Filter[]) {
151
+ const params = new URLSearchParams(window.location.search);
152
+ if (filters.length) params.set("filters", JSON.stringify(filters));
153
+ else params.delete("filters");
154
+ const query = params.toString();
155
+ window.history.replaceState(null, "", query ? `?${query}` : window.location.pathname);
156
+ }
157
+
158
+ export function Orders({ orders }: { orders: Order[] }) {
159
+ const [filters, setFilters] = React.useState<Filter[]>(readFilters);
160
+
161
+ // Back and forward bring the filters of that address back.
162
+ React.useEffect(() => {
163
+ const restore = () => setFilters(readFilters());
164
+ window.addEventListener("popstate", restore);
165
+ return () => window.removeEventListener("popstate", restore);
166
+ }, []);
167
+
168
+ const rows = React.useMemo(
169
+ () => orders.filter((order) => matchesFilters(order, filters, fields)),
170
+ [orders, filters],
171
+ );
172
+
173
+ return (
174
+ <div className="flex flex-col gap-3">
175
+ <FilterBar
176
+ fields={fields}
177
+ value={filters}
178
+ onValueChange={(next) => {
179
+ setFilters(next);
180
+ writeFilters(next);
181
+ }}
182
+ />
183
+ <DataTable
184
+ columns={columns}
185
+ data={rows}
186
+ getRowId={(order) => order.id}
187
+ label="Orders"
188
+ searchPlaceholder="Search orders"
189
+ emptyMessage="No orders match these filters."
190
+ />
191
+ </div>
192
+ );
193
+ }
194
+ ```
195
+
196
+ - `FilterBar` and `DataTable` have their own entries (`@zonsh/ui/filter-bar`,
197
+ `@zonsh/ui/data-table`); the table needs `@tanstack/react-table` installed.
198
+ - `matchesFilters(row, filters, fields)` filters on the client with the same field definitions
199
+ the bar uses. For a server-side table, send `filters` to your API instead.
200
+ - The filters are plain JSON (`{ field, operator, value }`), so they go into `?filters=` as they
201
+ are. `replaceState` keeps each change out of the back button; `popstate` restores a view.
202
+ - Columns are built once at module scope: a new array each render makes TanStack recompute.
203
+
204
+ ## Settings page with save state
205
+
206
+ A profile form that saves on "Save changes", and a switch that saves at once.
207
+
208
+ ```tsx
209
+ import {
210
+ Button,
211
+ Field,
212
+ FieldDescription,
213
+ FieldLabel,
214
+ Form,
215
+ FormActions,
216
+ Input,
217
+ Switch,
218
+ Textarea,
219
+ toast,
220
+ } from "@zonsh/ui";
221
+ import * as React from "react";
222
+
223
+ interface Profile {
224
+ name: string;
225
+ bio: string;
226
+ }
227
+
228
+ /** Your endpoints. */
229
+ async function saveProfile(profile: Profile) {
230
+ const response = await fetch("/api/profile", { method: "PUT", body: JSON.stringify(profile) });
231
+ if (!response.ok) throw new Error(`Saving failed with ${response.status}`);
232
+ }
233
+ async function saveDigest(on: boolean) {
234
+ const response = await fetch("/api/notifications/digest", { method: "PUT", body: JSON.stringify({ on }) });
235
+ if (!response.ok) throw new Error(`Saving failed with ${response.status}`);
236
+ }
237
+
238
+ export function ProfileSettings({ initial, digest }: { initial: Profile; digest: boolean }) {
239
+ const [saved, setSaved] = React.useState(initial);
240
+ const [draft, setDraft] = React.useState(initial);
241
+ const [saving, setSaving] = React.useState(false);
242
+ const [weekly, setWeekly] = React.useState(digest);
243
+ const dirty = draft.name !== saved.name || draft.bio !== saved.bio;
244
+
245
+ // Leaving with unsaved changes asks first.
246
+ React.useEffect(() => {
247
+ if (!dirty) return;
248
+ const warn = (event: BeforeUnloadEvent) => event.preventDefault();
249
+ window.addEventListener("beforeunload", warn);
250
+ return () => window.removeEventListener("beforeunload", warn);
251
+ }, [dirty]);
252
+
253
+ return (
254
+ <div className="flex max-w-xl flex-col gap-8">
255
+ <Form
256
+ onFormSubmit={async () => {
257
+ setSaving(true);
258
+ try {
259
+ await saveProfile(draft);
260
+ setSaved(draft);
261
+ toast.success("Your profile is saved.");
262
+ } catch {
263
+ toast.error("Your profile wasn't saved.", {
264
+ description: "Your changes are still here. Try again.",
265
+ });
266
+ } finally {
267
+ setSaving(false);
268
+ }
269
+ }}
270
+ >
271
+ <Field name="name">
272
+ <FieldLabel>Name</FieldLabel>
273
+ <Input required value={draft.name} onChange={(e) => setDraft({ ...draft, name: e.target.value })} />
274
+ </Field>
275
+ <Field name="bio">
276
+ <FieldLabel>Bio</FieldLabel>
277
+ <Textarea value={draft.bio} onChange={(e) => setDraft({ ...draft, bio: e.target.value })} />
278
+ <FieldDescription>Shown on your public profile.</FieldDescription>
279
+ </Field>
280
+ <FormActions align="between" className="pt-6 hairline">
281
+ <p role="status" className="font-mono text-xs text-muted-foreground">
282
+ {dirty && !saving ? "You have unsaved changes." : ""}
283
+ </p>
284
+ <div className="flex items-center gap-3">
285
+ <Button
286
+ type="button"
287
+ variant="ghost"
288
+ disabled={!dirty || saving}
289
+ focusableWhenDisabled
290
+ onClick={() => setDraft(saved)}
291
+ >
292
+ Discard
293
+ </Button>
294
+ <Button
295
+ type="submit"
296
+ disabled={!dirty}
297
+ focusableWhenDisabled
298
+ loading={saving}
299
+ loadingLabel="Saving changes"
300
+ >
301
+ Save changes
302
+ </Button>
303
+ </div>
304
+ </FormActions>
305
+ </Form>
306
+
307
+ {/* A switch takes effect at once: no Save button, and it flips back if the save fails. */}
308
+ <Field className="pt-6 hairline">
309
+ <FieldLabel>
310
+ <Switch
311
+ checked={weekly}
312
+ onCheckedChange={(on) => {
313
+ setWeekly(on);
314
+ saveDigest(on).catch(() => {
315
+ setWeekly(!on);
316
+ toast.error("The weekly summary setting wasn't saved. Try again.");
317
+ });
318
+ }}
319
+ />
320
+ Email me a weekly summary
321
+ </FieldLabel>
322
+ </Field>
323
+ </div>
324
+ );
325
+ }
326
+ ```
327
+
328
+ - "Save changes" waits for a change (`disabled={!dirty}` with `focusableWhenDisabled`, so it
329
+ stays in the tab order); Discard goes back to what was saved. One primary per view.
330
+ - The status line says "You have unsaved changes." in a `role="status"`, and leaving the page asks
331
+ first.
332
+ - A `Switch` takes effect when it is flipped: it is not part of the form, saves on its own and
333
+ flips back if the save fails.
334
+ - A failed save keeps the draft, so nothing typed is lost.
335
+
336
+ ## Dashboard KPI row with sparklines
337
+
338
+ A row of key figures with their change and a sparkline, in a description list.
339
+
340
+ ```tsx
341
+ import { Stat, StatGroup } from "@zonsh/ui";
342
+
343
+ interface Metrics {
344
+ revenue: number[];
345
+ orders: number[];
346
+ refundRate: number;
347
+ refundRateBefore: number;
348
+ /** Text keeps its unit: "18 of 24". */
349
+ fulfilment: string;
350
+ }
351
+
352
+ /** The share a value moved, from the first point of a series to the last. */
353
+ const changeOf = (series: number[]) => (series.at(-1)! - series[0]!) / series[0]!;
354
+ const sum = (series: number[]) => series.reduce((total, value) => total + value, 0);
355
+
356
+ export function KpiRow({ metrics, loading = false }: { metrics: Metrics; loading?: boolean }) {
357
+ return (
358
+ <StatGroup className="grid gap-x-8 gap-y-6 sm:grid-cols-2 lg:grid-cols-4">
359
+ <Stat
360
+ label="Revenue"
361
+ value={sum(metrics.revenue)}
362
+ format={{ style: "currency", currency: "EUR", maximumFractionDigits: 0 }}
363
+ change={changeOf(metrics.revenue)}
364
+ changeLabel="over 14 days"
365
+ series={metrics.revenue}
366
+ loading={loading}
367
+ />
368
+ <Stat
369
+ label="Orders"
370
+ value={sum(metrics.orders)}
371
+ change={changeOf(metrics.orders)}
372
+ changeLabel="over 14 days"
373
+ series={metrics.orders}
374
+ loading={loading}
375
+ />
376
+ <Stat
377
+ label="Refund rate"
378
+ value={metrics.refundRate}
379
+ format={{ style: "percent", maximumFractionDigits: 1 }}
380
+ change={(metrics.refundRate - metrics.refundRateBefore) / metrics.refundRateBefore}
381
+ better="down"
382
+ changeLabel="vs. last month"
383
+ loading={loading}
384
+ />
385
+ <Stat
386
+ label="Shipped in two days"
387
+ value={metrics.fulfilment}
388
+ description="Of this month's orders"
389
+ loading={loading}
390
+ />
391
+ </StatGroup>
392
+ );
393
+ }
394
+ ```
395
+
396
+ - `StatGroup` is a `<dl>`; each `Stat` sets its figure in Licht Mono on a top hairline, with no box
397
+ around it.
398
+ - A number `value` is formatted for the locale with `format`; text keeps its unit ("18 of 24").
399
+ - `change` is a signed fraction (`0.12` is 12%). Set `better` on every change: `"down"` turns a
400
+ fall green for a refund rate or a build time.
401
+ - `loading` keeps the label and puts placeholders where the value goes, so the row doesn't move
402
+ when the numbers arrive. A figure not measured is `value={null}`, never 0.
403
+
404
+ ## Confirm before delete
405
+
406
+ Ask before something that can't be undone, and keep the dialog open until the delete has
407
+ answered.
408
+
409
+ ```tsx
410
+ import {
411
+ AlertDialog,
412
+ AlertDialogClose,
413
+ AlertDialogContent,
414
+ AlertDialogDescription,
415
+ AlertDialogFooter,
416
+ AlertDialogHeader,
417
+ AlertDialogTitle,
418
+ AlertDialogTrigger,
419
+ Button,
420
+ toast,
421
+ } from "@zonsh/ui";
422
+ import { CircleAlertIcon } from "lucide-react";
423
+ import * as React from "react";
424
+
425
+ export function DeletePage({ title, onDelete }: { title: string; onDelete: () => Promise<void> }) {
426
+ const [open, setOpen] = React.useState(false);
427
+ const [pending, setPending] = React.useState(false);
428
+ const [error, setError] = React.useState<string | null>(null);
429
+
430
+ const remove = async () => {
431
+ setPending(true);
432
+ setError(null);
433
+ try {
434
+ await onDelete();
435
+ setOpen(false);
436
+ toast.success(`“${title}” is deleted.`);
437
+ } catch {
438
+ setError("The page couldn't be deleted: the connection dropped. Try again.");
439
+ } finally {
440
+ setPending(false);
441
+ }
442
+ };
443
+
444
+ return (
445
+ <AlertDialog
446
+ open={open}
447
+ onOpenChange={(next) => {
448
+ // While the delete runs, Escape doesn't close the dialog: its answer is still to come.
449
+ if (pending) return;
450
+ setOpen(next);
451
+ if (next) setError(null);
452
+ }}
453
+ >
454
+ <AlertDialogTrigger render={<Button variant="secondary" />}>Delete page</AlertDialogTrigger>
455
+ <AlertDialogContent>
456
+ <AlertDialogHeader>
457
+ <AlertDialogTitle>Delete “{title}”?</AlertDialogTitle>
458
+ <AlertDialogDescription>
459
+ The page is deleted for everyone who can see it. This can't be undone.
460
+ </AlertDialogDescription>
461
+ </AlertDialogHeader>
462
+ {error && (
463
+ <p role="alert" className="m-0 flex items-start gap-2 text-sm text-destructive">
464
+ <CircleAlertIcon aria-hidden className="mt-0.5 size-4 shrink-0" />
465
+ {error}
466
+ </p>
467
+ )}
468
+ <AlertDialogFooter>
469
+ <AlertDialogClose render={<Button variant="secondary" />} disabled={pending}>
470
+ Keep page
471
+ </AlertDialogClose>
472
+ <Button variant="destructive" loading={pending} loadingLabel="Deleting page" onClick={remove}>
473
+ Delete page
474
+ </Button>
475
+ </AlertDialogFooter>
476
+ </AlertDialogContent>
477
+ </AlertDialog>
478
+ );
479
+ }
480
+ ```
481
+
482
+ - `AlertDialog` doesn't close on an outside click; while the delete runs, `onOpenChange` ignores
483
+ Escape too.
484
+ - Both choices are named for what they do ("Keep page", "Delete page"), never "OK" and "Cancel".
485
+ - The destructive button shows `loading`; an error appears in the dialog as a `role="alert"`, so
486
+ people can try again where they are.
487
+ - The success is a toast, because the thing it would sit beside is gone.
488
+
489
+ ## Async search in a combobox
490
+
491
+ Pick a person from a directory that is searched on the server as you type.
492
+
493
+ ```tsx
494
+ import {
495
+ Combobox,
496
+ ComboboxContent,
497
+ ComboboxEmpty,
498
+ ComboboxInput,
499
+ ComboboxItem,
500
+ ComboboxList,
501
+ ComboboxStatus,
502
+ Field,
503
+ FieldLabel,
504
+ } from "@zonsh/ui";
505
+ import * as React from "react";
506
+
507
+ interface Person {
508
+ id: string;
509
+ name: string;
510
+ team: string;
511
+ }
512
+
513
+ /** Your search endpoint. */
514
+ async function searchPeople(query: string, signal: AbortSignal): Promise<Person[]> {
515
+ const response = await fetch(`/api/people?q=${encodeURIComponent(query)}`, { signal });
516
+ return (await response.json()) as Person[];
517
+ }
518
+
519
+ export function ReviewerField() {
520
+ const [query, setQuery] = React.useState("");
521
+ const [results, setResults] = React.useState<Person[]>([]);
522
+ const [loading, setLoading] = React.useState(false);
523
+ const [value, setValue] = React.useState<Person | null>(null);
524
+
525
+ // Search 250ms after the last key; a newer query cancels the request before it.
526
+ React.useEffect(() => {
527
+ const words = query.trim();
528
+ if (!words) {
529
+ setResults([]);
530
+ setLoading(false);
531
+ return;
532
+ }
533
+ const controller = new AbortController();
534
+ setLoading(true);
535
+ const timer = setTimeout(() => {
536
+ searchPeople(words, controller.signal)
537
+ .then((people) => {
538
+ setResults(people);
539
+ setLoading(false);
540
+ })
541
+ .catch(() => {
542
+ if (!controller.signal.aborted) setLoading(false);
543
+ });
544
+ }, 250);
545
+ return () => {
546
+ clearTimeout(timer);
547
+ controller.abort();
548
+ };
549
+ }, [query]);
550
+
551
+ // The chosen person stays among the items, so the field can show them.
552
+ const items = value && !results.some((person) => person.id === value.id) ? [...results, value] : results;
553
+ const searched = query.trim();
554
+
555
+ return (
556
+ <Field className="max-w-sm">
557
+ <FieldLabel>Assign a reviewer</FieldLabel>
558
+ <Combobox
559
+ items={items}
560
+ value={value}
561
+ filter={null}
562
+ itemToStringLabel={(person: Person) => person.name}
563
+ isItemEqualToValue={(item: Person, current: Person) => item.id === current.id}
564
+ onValueChange={(person: Person | null) => setValue(person)}
565
+ onInputValueChange={(next, { reason }) => {
566
+ if (reason !== "item-press") setQuery(next);
567
+ }}
568
+ >
569
+ <ComboboxInput placeholder="Search by name" showClear />
570
+ <ComboboxContent aria-busy={loading || undefined}>
571
+ <ComboboxStatus loading={loading}>
572
+ {loading ? "Searching…" : !searched ? "Type a name to search." : null}
573
+ </ComboboxStatus>
574
+ <ComboboxEmpty>{!loading && searched ? `No one called “${searched}”.` : null}</ComboboxEmpty>
575
+ <ComboboxList>
576
+ {(person: Person) => (
577
+ <ComboboxItem key={person.id} value={person}>
578
+ {person.name} <span className="text-muted-foreground">· {person.team}</span>
579
+ </ComboboxItem>
580
+ )}
581
+ </ComboboxList>
582
+ </ComboboxContent>
583
+ </Combobox>
584
+ </Field>
585
+ );
586
+ }
587
+ ```
588
+
589
+ - `filter={null}` hands filtering to the server: the list shows what came back.
590
+ - Each new query waits 250ms and aborts the request before it, so a slow early answer never
591
+ replaces a newer one.
592
+ - `ComboboxStatus` announces "Searching…" and the prompt; `ComboboxEmpty` says what was not found
593
+ in words.
594
+ - The chosen person is kept among the items, so the field can still show them after the next
595
+ search.
596
+
597
+ ## Command palette wired to routes
598
+
599
+ ⌘K opens a palette that jumps to any page and runs a few actions, with your router doing the
600
+ navigation.
601
+
602
+ ```tsx
603
+ import { Button, CommandDialog, KbdShortcut, useCommandShortcut, type CommandEntry } from "@zonsh/ui";
604
+ import { FilePlusIcon, FolderIcon, InboxIcon, SearchIcon, SettingsIcon } from "lucide-react";
605
+ import * as React from "react";
606
+
607
+ interface Route {
608
+ path: string;
609
+ label: string;
610
+ icon: React.ReactNode;
611
+ keywords?: string[];
612
+ }
613
+
614
+ /** The pages to jump to: the same list your router or sidebar is built from. */
615
+ const routes: Route[] = [
616
+ { path: "/inbox", label: "Inbox", icon: <InboxIcon /> },
617
+ { path: "/projects", label: "Projects", icon: <FolderIcon />, keywords: ["work"] },
618
+ { path: "/settings", label: "Settings", icon: <SettingsIcon />, keywords: ["preferences", "account"] },
619
+ ];
620
+
621
+ /** `navigate` is your router's: React Router's useNavigate(), Next's useRouter().push … */
622
+ export function CommandPalette({ navigate }: { navigate: (path: string) => void }) {
623
+ const [open, setOpen] = React.useState(false);
624
+ // ⌘K on a Mac, Ctrl+K elsewhere.
625
+ useCommandShortcut(() => setOpen((value) => !value));
626
+
627
+ const items = React.useMemo<CommandEntry[]>(
628
+ () => [
629
+ ...routes.map((route) => ({
630
+ value: route.path,
631
+ label: route.label,
632
+ group: "Go to",
633
+ icon: route.icon,
634
+ keywords: route.keywords,
635
+ onSelect: () => navigate(route.path),
636
+ })),
637
+ {
638
+ value: "new-project",
639
+ label: "New project",
640
+ group: "Actions",
641
+ icon: <FilePlusIcon />,
642
+ onSelect: () => navigate("/projects/new"),
643
+ },
644
+ ],
645
+ [navigate],
646
+ );
647
+
648
+ return (
649
+ <CommandDialog
650
+ open={open}
651
+ onOpenChange={setOpen}
652
+ items={items}
653
+ label="Search and commands"
654
+ placeholder="Go to a page or run a command…"
655
+ trigger={
656
+ <Button variant="secondary" className="w-64 justify-between">
657
+ <span className="inline-flex items-center gap-2 text-muted-foreground">
658
+ <SearchIcon />
659
+ Search
660
+ </span>
661
+ <KbdShortcut keys={["mod", "K"]} />
662
+ </Button>
663
+ }
664
+ />
665
+ );
666
+ }
667
+ ```
668
+
669
+ - `useCommandShortcut` binds ⌘K on a Mac and Ctrl+K elsewhere; `KbdShortcut keys={["mod", "K"]}`
670
+ writes the keys the same way.
671
+ - Entries come from the list your routes or sidebar are built from, so the palette can't drift
672
+ from the app.
673
+ - `group` sorts entries under headings; `keywords` find a page by other words ("preferences" finds
674
+ Settings). The palette closes after `onSelect`.
675
+
676
+ ## A theme from a brand colour
677
+
678
+ The whole app in the brand's colour, and one marketing section in a theme of its own.
679
+
680
+ ```tsx
681
+ import {
682
+ Button,
683
+ Display,
684
+ Lead,
685
+ ThemeProvider,
686
+ ThemeScope,
687
+ ThemeToggle,
688
+ themePresetFromColor,
689
+ } from "@zonsh/ui";
690
+ import type * as React from "react";
691
+
692
+ // Made once, at module scope: a new preset on every render would rebuild the theme each time.
693
+ const brand = themePresetFromColor("#0f766e", { neutral: "cool", corners: "subtle" });
694
+ const campaign = themePresetFromColor("#c2410c", {
695
+ neutral: "warm",
696
+ corners: "round",
697
+ density: "comfortable",
698
+ });
699
+
700
+ /** The whole app in the brand colour, light and dark. */
701
+ export function App({ children }: { children: React.ReactNode }) {
702
+ return (
703
+ <ThemeProvider preset={brand}>
704
+ <header className="flex justify-end p-4">
705
+ <ThemeToggle />
706
+ </header>
707
+ {children}
708
+ <SpringLaunch />
709
+ </ThemeProvider>
710
+ );
711
+ }
712
+
713
+ /** One marketing section in a theme of its own; the rest of the page keeps the app's. */
714
+ function SpringLaunch() {
715
+ return (
716
+ <ThemeScope preset={campaign} scheme="dark" className="px-6 py-16">
717
+ <Display>Spring collection</Display>
718
+ <Lead className="mt-4 max-w-xl">Linen and clay, new for the season.</Lead>
719
+ <Button size="lg" className="mt-8">
720
+ See the collection
721
+ </Button>
722
+ </ThemeScope>
723
+ );
724
+ }
725
+ ```
726
+
727
+ - `themePresetFromColor` makes a full theme from one colour: the primary, checked controls and the
728
+ focus edge take its hue, and every text colour is checked for contrast in light and dark.
729
+ - `ThemeScope` gives one area its own preset, density and corners; menus and dialogs opened inside
730
+ it take its theme too. `scheme="dark"` holds it dark.
731
+ - Make presets once, at module scope. For a server-rendered first paint, also render
732
+ `themeFromPreset(preset).css` in a `<style>` in `<head>`.
733
+ - Never restyle components one by one for a theme.
734
+
735
+ ## Dense app shell
736
+
737
+ A collapsible sidebar shell with 30px controls throughout, for a tool people work in all day.
738
+
739
+ ```tsx
740
+ import {
741
+ Separator,
742
+ Sidebar,
743
+ SidebarContent,
744
+ SidebarFooter,
745
+ SidebarGroup,
746
+ SidebarGroupLabel,
747
+ SidebarInset,
748
+ SidebarItem,
749
+ SidebarMenuBadge,
750
+ SidebarProvider,
751
+ SidebarRail,
752
+ SidebarTrigger,
753
+ ThemeProvider,
754
+ themePresetFromColor,
755
+ } from "@zonsh/ui";
756
+ import { FolderIcon, InboxIcon, SettingsIcon, UsersIcon } from "lucide-react";
757
+ import type * as React from "react";
758
+
759
+ // A grey keeps zon's grey primary; `density: "dense"` makes every control 30px high, app-wide.
760
+ const dense = themePresetFromColor("#71717a", { density: "dense" });
761
+
762
+ const pages = [
763
+ { href: "/inbox", label: "Inbox", icon: InboxIcon, count: 4 },
764
+ { href: "/projects", label: "Projects", icon: FolderIcon },
765
+ { href: "/team", label: "Team", icon: UsersIcon },
766
+ ];
767
+
768
+ export function AppShell({
769
+ path,
770
+ title,
771
+ children,
772
+ }: {
773
+ path: string;
774
+ title: string;
775
+ children: React.ReactNode;
776
+ }) {
777
+ return (
778
+ <ThemeProvider preset={dense}>
779
+ <SidebarProvider collapsible="icon" className="h-dvh">
780
+ <Sidebar aria-label="Workspace" size="sm">
781
+ <SidebarContent>
782
+ <SidebarGroup>
783
+ <SidebarGroupLabel>Workspace</SidebarGroupLabel>
784
+ {pages.map((page) => (
785
+ <SidebarItem key={page.href} href={page.href} current={path.startsWith(page.href)}>
786
+ <page.icon />
787
+ {page.label}
788
+ {page.count ? <SidebarMenuBadge>{page.count}</SidebarMenuBadge> : null}
789
+ </SidebarItem>
790
+ ))}
791
+ </SidebarGroup>
792
+ </SidebarContent>
793
+ <SidebarFooter>
794
+ <SidebarItem href="/settings" current={path.startsWith("/settings")}>
795
+ <SettingsIcon />
796
+ Settings
797
+ </SidebarItem>
798
+ </SidebarFooter>
799
+ <SidebarRail />
800
+ </Sidebar>
801
+ <SidebarInset className="@container overflow-y-auto">
802
+ <header className="flex items-center gap-3 border-b border-border/60 py-1.5 ps-1.5 pe-4">
803
+ <SidebarTrigger size="icon-sm" />
804
+ <Separator orientation="vertical" className="my-auto h-4 min-h-0 self-center" />
805
+ <span className="font-mono text-xs text-muted-foreground">Workspace / {title}</span>
806
+ </header>
807
+ <main className="px-6 py-6">{children}</main>
808
+ </SidebarInset>
809
+ </SidebarProvider>
810
+ </ThemeProvider>
811
+ );
812
+ }
813
+ ```
814
+
815
+ - `density: "dense"` sets every control to 30px, and padding, gaps and type with it. A grey colour
816
+ keeps zon's grey primary.
817
+ - `Sidebar size="sm"` gives it the matching 30px rows. `collapsible="icon"` folds it to an icon
818
+ rail (⌘B / Ctrl+B); below 768px it becomes a sheet.
819
+ - `current` marks the page you are on (`aria-current="page"`): derive it from the route, not from
820
+ clicks.
821
+
822
+ ## Toasts for async work
823
+
824
+ One toast that says the work has started, then how it ended.
825
+
826
+ ```tsx
827
+ import { Button, Toaster, toast } from "@zonsh/ui";
828
+
829
+ /** Your request: resolves with what the success toast names. */
830
+ async function publishRelease(version: string): Promise<string> {
831
+ const response = await fetch(`/api/releases/${version}/publish`, { method: "POST" });
832
+ if (!response.ok) throw new Error(`Publishing failed with ${response.status}`);
833
+ return version;
834
+ }
835
+
836
+ export function PublishButton({ version }: { version: string }) {
837
+ return (
838
+ <Button
839
+ variant="secondary"
840
+ onClick={() =>
841
+ toast
842
+ .promise(publishRelease(version), {
843
+ loading: { title: `Publishing ${version}…` },
844
+ success: (published) => ({
845
+ title: `${published} is published.`,
846
+ description: "It reaches every mirror within a few minutes.",
847
+ }),
848
+ error: {
849
+ title: `${version} wasn't published.`,
850
+ description: "Nothing changed. Try again in a moment.",
851
+ },
852
+ })
853
+ // toast.promise hands the promise back: the toast has already told people it failed.
854
+ .catch(() => {})
855
+ }
856
+ >
857
+ Publish {version}
858
+ </Button>
859
+ );
860
+ }
861
+
862
+ /** Mount one Toaster at the root of the app, once. */
863
+ export function App() {
864
+ return (
865
+ <>
866
+ <PublishButton version="v2.4.0" />
867
+ <Toaster />
868
+ </>
869
+ );
870
+ }
871
+ ```
872
+
873
+ - `toast.promise` shows a spinner toast while the promise runs and turns it into the success or
874
+ error toast; the success can use the resolved value.
875
+ - It hands the promise back: catch it, since the toast has already told people it failed.
876
+ - An error toast says what happened and what to do ("Nothing changed. Try again in a moment.").
877
+
878
+ ## File upload with a progress list
879
+
880
+ Drop, pick or paste files, and watch each one upload.
881
+
882
+ ```tsx
883
+ import { Button, FileDrop, FileDropItem, Progress } from "@zonsh/ui";
884
+ import * as React from "react";
885
+
886
+ interface Upload {
887
+ id: number;
888
+ file: File;
889
+ progress: number;
890
+ status: "uploading" | "done" | "failed";
891
+ request?: XMLHttpRequest;
892
+ }
893
+
894
+ /** XMLHttpRequest, not fetch: only it reports how much of the body has been sent. */
895
+ function send(
896
+ file: File,
897
+ onProgress: (share: number) => void,
898
+ ): { request: XMLHttpRequest; done: Promise<void> } {
899
+ const request = new XMLHttpRequest();
900
+ const done = new Promise<void>((resolve, reject) => {
901
+ request.upload.onprogress = (event) => event.lengthComputable && onProgress(event.loaded / event.total);
902
+ request.onload = () => (request.status < 300 ? resolve() : reject(new Error(String(request.status))));
903
+ request.onerror = () => reject(new Error("network"));
904
+ request.onabort = () => reject(new Error("aborted"));
905
+ });
906
+ const body = new FormData();
907
+ body.append("file", file);
908
+ request.open("POST", "/api/uploads");
909
+ request.send(body);
910
+ return { request, done };
911
+ }
912
+
913
+ let nextId = 0;
914
+
915
+ export function Attachments() {
916
+ const [uploads, setUploads] = React.useState<Upload[]>([]);
917
+ const update = (id: number, change: Partial<Upload>) =>
918
+ setUploads((all) => all.map((upload) => (upload.id === id ? { ...upload, ...change } : upload)));
919
+
920
+ const start = (file: File) => {
921
+ const id = nextId++;
922
+ const { request, done } = send(file, (share) => update(id, { progress: share * 100 }));
923
+ setUploads((all) => [...all, { id, file, progress: 0, status: "uploading", request }]);
924
+ done.then(
925
+ () => update(id, { status: "done", progress: 100 }),
926
+ () => update(id, { status: "failed" }),
927
+ );
928
+ };
929
+ const remove = (upload: Upload) => {
930
+ upload.request?.abort();
931
+ setUploads((all) => all.filter((other) => other.id !== upload.id));
932
+ };
933
+
934
+ return (
935
+ <div className="flex max-w-lg flex-col gap-3">
936
+ <FileDrop
937
+ aria-label="Add attachments"
938
+ accept="image/*,application/pdf"
939
+ maxSize={20 * 1024 * 1024}
940
+ onFiles={(files) => files.forEach(start)}
941
+ />
942
+ <ul aria-label="Attachments" className="m-0 flex list-none flex-col gap-3 p-0">
943
+ {uploads.map((upload) => (
944
+ <li key={upload.id}>
945
+ {upload.status === "done" ? (
946
+ <FileDropItem file={upload.file} onRemove={() => remove(upload)} />
947
+ ) : upload.status === "failed" ? (
948
+ <div className="flex items-center justify-between gap-3 text-sm">
949
+ <span role="alert" className="text-destructive">
950
+ {upload.file.name} wasn't uploaded.
951
+ </span>
952
+ <Button size="sm" variant="secondary" onClick={() => (remove(upload), start(upload.file))}>
953
+ Try again
954
+ </Button>
955
+ </div>
956
+ ) : (
957
+ <Progress label={upload.file.name} value={upload.progress} showValue />
958
+ )}
959
+ </li>
960
+ ))}
961
+ </ul>
962
+ </div>
963
+ );
964
+ }
965
+ ```
966
+
967
+ - `FileDrop` checks `accept` and `maxSize` before `onFiles`; refused files go to `onReject`.
968
+ - `XMLHttpRequest` reports upload progress, which `fetch` doesn't. Each row is a `Progress` with
969
+ the file's name as its label while it uploads, then a `FileDropItem` with a remove button.
970
+ - A failed upload says so in words, in a `role="alert"`, with a way to try again. Removing a file
971
+ while it uploads aborts it.
972
+
973
+ ## AI chat with a streaming reply
974
+
975
+ A conversation that follows the reply as it streams in, with a prompt bar that can stop it.
976
+
977
+ ```tsx
978
+ import {
979
+ Conversation,
980
+ ConversationContent,
981
+ ConversationScrollButton,
982
+ Message,
983
+ MessageAction,
984
+ MessageActions,
985
+ MessageContent,
986
+ MessageText,
987
+ PromptInput,
988
+ PromptInputSubmit,
989
+ PromptInputTextarea,
990
+ PromptInputToolbar,
991
+ Response,
992
+ type PromptInputStatus,
993
+ } from "@zonsh/ui";
994
+ import * as React from "react";
995
+
996
+ interface Turn {
997
+ id: number;
998
+ from: "user" | "assistant";
999
+ text: string;
1000
+ }
1001
+
1002
+ /** Your endpoint: streams the reply as plain text, chunk by chunk. */
1003
+ async function streamReply(turns: Turn[], signal: AbortSignal, onText: (text: string) => void) {
1004
+ const response = await fetch("/api/chat", { method: "POST", body: JSON.stringify(turns), signal });
1005
+ if (!response.ok || !response.body) throw new Error(`Chat failed with ${response.status}`);
1006
+ const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
1007
+ for (;;) {
1008
+ const { value, done } = await reader.read();
1009
+ if (done) return;
1010
+ onText(value);
1011
+ }
1012
+ }
1013
+
1014
+ export function Chat() {
1015
+ const [turns, setTurns] = React.useState<Turn[]>([]);
1016
+ const [status, setStatus] = React.useState<PromptInputStatus>("ready");
1017
+ const controller = React.useRef<AbortController | null>(null);
1018
+
1019
+ const send = async (prompt: string) => {
1020
+ const question: Turn = { id: Date.now(), from: "user", text: prompt };
1021
+ const reply: Turn = { id: question.id + 1, from: "assistant", text: "" };
1022
+ const history = [...turns, question];
1023
+ setTurns([...history, reply]);
1024
+ setStatus("submitted");
1025
+ controller.current = new AbortController();
1026
+ try {
1027
+ await streamReply(history, controller.current.signal, (chunk) => {
1028
+ setStatus("streaming");
1029
+ setTurns((all) =>
1030
+ all.map((turn) => (turn.id === reply.id ? { ...turn, text: turn.text + chunk } : turn)),
1031
+ );
1032
+ });
1033
+ } catch {
1034
+ // Stopped, or the connection dropped: what arrived stays on screen.
1035
+ } finally {
1036
+ setStatus("ready");
1037
+ }
1038
+ };
1039
+
1040
+ const last = turns.at(-1);
1041
+ return (
1042
+ <div className="flex h-[40rem] flex-col gap-4">
1043
+ <Conversation aria-label="Conversation with the assistant">
1044
+ <ConversationContent>
1045
+ {turns.map((turn) => (
1046
+ <Message key={turn.id} from={turn.from}>
1047
+ <MessageContent>
1048
+ {turn.from === "user" ? (
1049
+ <MessageText>{turn.text}</MessageText>
1050
+ ) : (
1051
+ <Response streaming={status !== "ready" && turn === last}>{turn.text}</Response>
1052
+ )}
1053
+ </MessageContent>
1054
+ {turn.from === "assistant" && turn.text && !(status !== "ready" && turn === last) && (
1055
+ <MessageActions>
1056
+ <MessageAction label="Copy" copy={turn.text} />
1057
+ </MessageActions>
1058
+ )}
1059
+ </Message>
1060
+ ))}
1061
+ </ConversationContent>
1062
+ <ConversationScrollButton />
1063
+ </Conversation>
1064
+ <PromptInput
1065
+ status={status}
1066
+ onSubmit={(prompt) => void send(prompt)}
1067
+ onStop={() => controller.current?.abort()}
1068
+ aria-label="Ask the assistant"
1069
+ >
1070
+ <PromptInputTextarea placeholder="Ask anything about your notes" />
1071
+ <PromptInputToolbar>
1072
+ <PromptInputSubmit />
1073
+ </PromptInputToolbar>
1074
+ </PromptInput>
1075
+ </div>
1076
+ );
1077
+ }
1078
+ ```
1079
+
1080
+ - `Conversation` sticks to the bottom while the reply streams and stays put when people scroll up;
1081
+ `ConversationScrollButton` brings them back.
1082
+ - `Response streaming` writes the markdown out evenly as chunks arrive, and is safe with untrusted
1083
+ model output.
1084
+ - `PromptInput status` turns the send button into a spinner (`submitted`) and a stop button
1085
+ (`streaming`); `onStop` aborts the request, and what arrived stays.
1086
+ - The copy action appears once a reply has finished.
1087
+
1088
+ ## Kanban board
1089
+
1090
+ Cards in columns, dragged between them with the pointer, a long press or the keyboard.
1091
+
1092
+ ```tsx
1093
+ import {
1094
+ Item,
1095
+ ItemContent,
1096
+ ItemDescription,
1097
+ ItemTitle,
1098
+ Sortable,
1099
+ SortableHandle,
1100
+ SortableItem,
1101
+ SortableList,
1102
+ } from "@zonsh/ui";
1103
+ import * as React from "react";
1104
+
1105
+ interface Card {
1106
+ title: string;
1107
+ owner: string;
1108
+ }
1109
+
1110
+ const stages = [
1111
+ { id: "todo", label: "To do" },
1112
+ { id: "doing", label: "In progress" },
1113
+ { id: "done", label: "Done" },
1114
+ ] as const;
1115
+
1116
+ type Board = Record<(typeof stages)[number]["id"], string[]>;
1117
+
1118
+ /** Your save: the card's new place, sent once the drop has settled. */
1119
+ async function moveCard(card: string, stage: string, index: number) {
1120
+ await fetch(`/api/cards/${card}`, { method: "PATCH", body: JSON.stringify({ stage, index }) });
1121
+ }
1122
+
1123
+ export function TaskBoard({ cards, initial }: { cards: Record<string, Card>; initial: Board }) {
1124
+ const [board, setBoard] = React.useState(initial);
1125
+
1126
+ return (
1127
+ <Sortable
1128
+ value={board}
1129
+ onValueChange={setBoard}
1130
+ onMoveEnd={({ item, to, cancelled }) => {
1131
+ if (!cancelled) void moveCard(item, to.list, to.index);
1132
+ }}
1133
+ className="grid gap-6 md:grid-cols-3"
1134
+ >
1135
+ {stages.map((stage) => (
1136
+ <section key={stage.id} aria-labelledby={`stage-${stage.id}`} className="flex flex-col gap-3">
1137
+ <h3
1138
+ id={`stage-${stage.id}`}
1139
+ className="m-0 flex items-baseline justify-between border-b border-border/60 pb-2 text-[13px] font-medium"
1140
+ >
1141
+ {stage.label}
1142
+ <span className="font-mono text-xs font-normal text-muted-foreground tabular-nums">
1143
+ {board[stage.id].length}
1144
+ </span>
1145
+ </h3>
1146
+ <SortableList
1147
+ id={stage.id}
1148
+ label={stage.label}
1149
+ aria-labelledby={`stage-${stage.id}`}
1150
+ className="m-0 flex min-h-24 list-none flex-col gap-2 p-0"
1151
+ >
1152
+ {board[stage.id].map((id) => (
1153
+ <SortableItem key={id} value={id} label={cards[id]!.title} className="group/card">
1154
+ <Item variant="raised" size="sm" className="ps-1.5 group-data-lifted/card:shadow-overlay">
1155
+ <SortableHandle />
1156
+ <ItemContent>
1157
+ <ItemTitle>{cards[id]!.title}</ItemTitle>
1158
+ <ItemDescription>{cards[id]!.owner}</ItemDescription>
1159
+ </ItemContent>
1160
+ </Item>
1161
+ </SortableItem>
1162
+ ))}
1163
+ </SortableList>
1164
+ </section>
1165
+ ))}
1166
+ </Sortable>
1167
+ );
1168
+ }
1169
+ ```
1170
+
1171
+ - `Sortable` holds every column as one value, `{ list: [ids] }`; `onValueChange` gives the new
1172
+ one after each move.
1173
+ - `onMoveEnd` fires once the drop settles, which is when to save. Every move is read out in a
1174
+ live region.
1175
+ - `SortableHandle` is the keyboard way in: Space picks a card up, the arrows move it (left and
1176
+ right between columns), Space drops it, Escape puts it back.
1177
+ - Cards are raised `Item`s: things that can be picked up are the one place for a card look.
1178
+
1179
+ ## Room booking scheduler
1180
+
1181
+ Bookings per room through the day, moved and resized with the pointer or the keyboard.
1182
+
1183
+ ```tsx
1184
+ import { Scheduler, type SchedulerItem, type SchedulerRow } from "@zonsh/ui/scheduler";
1185
+ import { DoorOpenIcon } from "lucide-react";
1186
+ import * as React from "react";
1187
+
1188
+ const rooms: SchedulerRow[] = [
1189
+ { id: "atrium", title: "Atrium", description: "12 seats · screen", icon: <DoorOpenIcon /> },
1190
+ { id: "library", title: "Library", description: "6 seats", icon: <DoorOpenIcon /> },
1191
+ { id: "booth", title: "Phone booth", description: "1 seat", icon: <DoorOpenIcon /> },
1192
+ ];
1193
+
1194
+ /** Your save: the booking as it is after a move, a resize or a change of room. */
1195
+ async function saveBooking(booking: SchedulerItem) {
1196
+ const response = await fetch(`/api/bookings/${booking.id}`, {
1197
+ method: "PUT",
1198
+ body: JSON.stringify(booking),
1199
+ });
1200
+ if (!response.ok) throw new Error(`Saving failed with ${response.status}`);
1201
+ }
1202
+
1203
+ export function RoomBookings({ initial, day }: { initial: SchedulerItem[]; day: Date }) {
1204
+ const [bookings, setBookings] = React.useState(initial);
1205
+
1206
+ return (
1207
+ <Scheduler
1208
+ aria-label="Meeting rooms"
1209
+ layout="resource"
1210
+ rows={rooms}
1211
+ items={bookings}
1212
+ onItemsChange={(next, { item, previous }) => {
1213
+ setBookings(next);
1214
+ // Saved after the change is on screen; put it back if the server refuses it.
1215
+ saveBooking(item).catch(() =>
1216
+ setBookings((all) => all.map((booking) => (booking.id === item.id ? previous : booking))),
1217
+ );
1218
+ }}
1219
+ defaultZoom="day"
1220
+ zooms={["day", "week"]}
1221
+ defaultDate={day}
1222
+ defaultListWidth={180}
1223
+ />
1224
+ );
1225
+ }
1226
+ ```
1227
+
1228
+ - `layout="resource"` gives each room a row; overlapping bookings stack, and a booking can move to
1229
+ another room.
1230
+ - `onItemsChange` passes the changed `item` and the `previous` one: show the change at once, save
1231
+ it, and put the previous one back if the server refuses.
1232
+ - `Scheduler` has its own entry, `@zonsh/ui/scheduler`. `zooms` limits the zoom levels offered.