@zonsh/ui 0.4.1 → 0.6.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 (562) hide show
  1. package/CHANGELOG.md +639 -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 +7 -7
  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/ascii-field.js +2 -1
  35. package/dist/components/audio-player.d.ts +134 -0
  36. package/dist/components/audio-player.js +618 -0
  37. package/dist/components/avatar.d.ts +6 -6
  38. package/dist/components/avatar.js +13 -11
  39. package/dist/components/badge.d.ts +12 -12
  40. package/dist/components/badge.js +7 -5
  41. package/dist/components/bottom-nav.d.ts +53 -11
  42. package/dist/components/bottom-nav.js +389 -24
  43. package/dist/components/breadcrumb.d.ts +11 -2
  44. package/dist/components/breadcrumb.js +60 -6
  45. package/dist/components/button-group.js +5 -1
  46. package/dist/components/button.d.ts +23 -6
  47. package/dist/components/button.js +64 -8
  48. package/dist/components/calendar.js +8 -6
  49. package/dist/components/card.d.ts +10 -8
  50. package/dist/components/card.js +15 -14
  51. package/dist/components/carousel.d.ts +2 -2
  52. package/dist/components/carousel.js +21 -8
  53. package/dist/components/chart.d.ts +38 -1
  54. package/dist/components/chart.js +27 -5
  55. package/dist/components/checkbox.js +2 -2
  56. package/dist/components/code-block.d.ts +9 -2
  57. package/dist/components/code-block.js +26 -7
  58. package/dist/components/collapsible.js +4 -4
  59. package/dist/components/color-picker.d.ts +2 -2
  60. package/dist/components/color-picker.js +5 -5
  61. package/dist/components/combobox.d.ts +26 -7
  62. package/dist/components/combobox.js +32 -13
  63. package/dist/components/command.d.ts +29 -5
  64. package/dist/components/command.js +37 -12
  65. package/dist/components/context-menu.d.ts +5 -2
  66. package/dist/components/context-menu.js +24 -3
  67. package/dist/components/conversation.d.ts +1 -1
  68. package/dist/components/conversation.js +77 -16
  69. package/dist/components/copy-button.d.ts +1 -1
  70. package/dist/components/copy-button.js +8 -6
  71. package/dist/components/data-table.d.ts +6 -6
  72. package/dist/components/data-table.js +41 -15
  73. package/dist/components/date-picker.d.ts +31 -9
  74. package/dist/components/date-picker.js +100 -18
  75. package/dist/components/dialog.d.ts +17 -10
  76. package/dist/components/dialog.js +20 -13
  77. package/dist/components/drawer.d.ts +26 -8
  78. package/dist/components/drawer.js +75 -16
  79. package/dist/components/drawing.d.ts +25 -0
  80. package/dist/components/drawing.js +32 -0
  81. package/dist/components/empty.js +2 -2
  82. package/dist/components/feature-list.d.ts +65 -13
  83. package/dist/components/feature-list.js +116 -15
  84. package/dist/components/field.js +2 -2
  85. package/dist/components/file-drop.d.ts +9 -7
  86. package/dist/components/file-drop.js +8 -43
  87. package/dist/components/filter-bar.d.ts +10 -9
  88. package/dist/components/filter-bar.js +42 -25
  89. package/dist/components/graph.d.ts +19 -3
  90. package/dist/components/graph.js +190 -28
  91. package/dist/components/illustration.js +53 -31
  92. package/dist/components/input-group.d.ts +6 -11
  93. package/dist/components/input-group.js +21 -19
  94. package/dist/components/input.d.ts +2 -2
  95. package/dist/components/input.js +3 -3
  96. package/dist/components/item.d.ts +9 -6
  97. package/dist/components/item.js +13 -8
  98. package/dist/components/kbd.d.ts +1 -1
  99. package/dist/components/kbd.js +1 -1
  100. package/dist/components/layout.d.ts +2 -1
  101. package/dist/components/layout.js +55 -11
  102. package/dist/components/lightbox.d.ts +76 -9
  103. package/dist/components/lightbox.js +354 -48
  104. package/dist/components/locale.d.ts +6 -6
  105. package/dist/components/logo.d.ts +21 -1
  106. package/dist/components/logo.js +32 -2
  107. package/dist/components/markdown-editor.d.ts +275 -0
  108. package/dist/components/markdown-editor.js +831 -0
  109. package/dist/components/mentions.d.ts +153 -0
  110. package/dist/components/mentions.js +507 -0
  111. package/dist/components/menu.d.ts +2 -1
  112. package/dist/components/menu.js +5 -4
  113. package/dist/components/menubar.d.ts +23 -5
  114. package/dist/components/menubar.js +153 -31
  115. package/dist/components/message.d.ts +62 -11
  116. package/dist/components/message.js +51 -14
  117. package/dist/components/meter.js +1 -1
  118. package/dist/components/money-input.d.ts +1 -1
  119. package/dist/components/money-input.js +1 -1
  120. package/dist/components/native-select.d.ts +2 -2
  121. package/dist/components/native-select.js +4 -4
  122. package/dist/components/navigation-menu.d.ts +3 -1
  123. package/dist/components/navigation-menu.js +23 -10
  124. package/dist/components/number-field.d.ts +2 -9
  125. package/dist/components/number-field.js +90 -26
  126. package/dist/components/number-roll.d.ts +26 -0
  127. package/dist/components/number-roll.js +81 -0
  128. package/dist/components/otp-field.d.ts +1 -1
  129. package/dist/components/otp-field.js +24 -3
  130. package/dist/components/pagination.d.ts +11 -3
  131. package/dist/components/pagination.js +59 -13
  132. package/dist/components/pdf-viewer.d.ts +1 -1
  133. package/dist/components/pdf-viewer.js +8 -8
  134. package/dist/components/phone-input.d.ts +1 -1
  135. package/dist/components/phone-input.js +2 -2
  136. package/dist/components/popover.js +5 -3
  137. package/dist/components/preview-card.d.ts +37 -2
  138. package/dist/components/preview-card.js +226 -2
  139. package/dist/components/progress.js +1 -1
  140. package/dist/components/prompt-input.d.ts +1 -1
  141. package/dist/components/prompt-input.js +35 -17
  142. package/dist/components/pull-to-refresh.d.ts +50 -0
  143. package/dist/components/pull-to-refresh.js +189 -0
  144. package/dist/components/quote.d.ts +6 -1
  145. package/dist/components/quote.js +3 -2
  146. package/dist/components/radio-group.js +8 -3
  147. package/dist/components/rating.d.ts +4 -1
  148. package/dist/components/rating.js +131 -10
  149. package/dist/components/reasoning.d.ts +1 -1
  150. package/dist/components/reasoning.js +7 -3
  151. package/dist/components/resizable.d.ts +1 -1
  152. package/dist/components/resizable.js +2 -2
  153. package/dist/components/response.d.ts +4 -3
  154. package/dist/components/response.js +39 -15
  155. package/dist/components/scheduler.d.ts +352 -0
  156. package/dist/components/scheduler.js +1717 -0
  157. package/dist/components/scroll-area.js +1 -1
  158. package/dist/components/select.d.ts +17 -4
  159. package/dist/components/select.js +140 -9
  160. package/dist/components/separator.d.ts +1 -1
  161. package/dist/components/separator.js +3 -3
  162. package/dist/components/sidebar.d.ts +44 -3
  163. package/dist/components/sidebar.js +90 -31
  164. package/dist/components/site-header.d.ts +18 -13
  165. package/dist/components/site-header.js +26 -9
  166. package/dist/components/skeleton.d.ts +18 -8
  167. package/dist/components/skeleton.js +23 -8
  168. package/dist/components/slider.js +2 -2
  169. package/dist/components/sortable.d.ts +55 -4
  170. package/dist/components/sortable.js +187 -94
  171. package/dist/components/sources.d.ts +1 -1
  172. package/dist/components/sources.js +2 -2
  173. package/dist/components/spinner.d.ts +4 -4
  174. package/dist/components/spinner.js +4 -4
  175. package/dist/components/stat.d.ts +21 -4
  176. package/dist/components/stat.js +17 -8
  177. package/dist/components/stepper.d.ts +1 -1
  178. package/dist/components/stepper.js +8 -7
  179. package/dist/components/suggestions.d.ts +11 -3
  180. package/dist/components/suggestions.js +10 -4
  181. package/dist/components/swipe-actions.d.ts +66 -0
  182. package/dist/components/swipe-actions.js +292 -0
  183. package/dist/components/switch.js +1 -1
  184. package/dist/components/table.d.ts +13 -7
  185. package/dist/components/table.js +124 -23
  186. package/dist/components/tabs.js +15 -8
  187. package/dist/components/tag.d.ts +19 -20
  188. package/dist/components/tag.js +9 -5
  189. package/dist/components/tags-input.d.ts +2 -7
  190. package/dist/components/tags-input.js +11 -8
  191. package/dist/components/textarea.d.ts +3 -2
  192. package/dist/components/textarea.js +4 -3
  193. package/dist/components/theme.d.ts +50 -7
  194. package/dist/components/theme.js +168 -12
  195. package/dist/components/time-field.d.ts +6 -10
  196. package/dist/components/time-field.js +19 -9
  197. package/dist/components/timeline.d.ts +19 -3
  198. package/dist/components/timeline.js +21 -9
  199. package/dist/components/tippy.d.ts +17 -1
  200. package/dist/components/tippy.js +95 -15
  201. package/dist/components/toast.d.ts +2 -7
  202. package/dist/components/toast.js +12 -8
  203. package/dist/components/toggle-group.d.ts +7 -1
  204. package/dist/components/toggle-group.js +17 -5
  205. package/dist/components/toggle.d.ts +2 -2
  206. package/dist/components/toggle.js +3 -2
  207. package/dist/components/tool-call.d.ts +1 -1
  208. package/dist/components/tool-call.js +8 -3
  209. package/dist/components/toolbar.d.ts +57 -4
  210. package/dist/components/toolbar.js +219 -16
  211. package/dist/components/tooltip.d.ts +5 -3
  212. package/dist/components/tooltip.js +14 -6
  213. package/dist/components/tour.d.ts +1 -1
  214. package/dist/components/tour.js +70 -24
  215. package/dist/components/tree.js +33 -10
  216. package/dist/components/typography.d.ts +31 -8
  217. package/dist/components/typography.js +21 -10
  218. package/dist/components/video-player.d.ts +7 -2
  219. package/dist/components/video-player.js +182 -225
  220. package/dist/index.d.ts +99 -92
  221. package/dist/index.js +99 -92
  222. package/dist/lib/calendar.d.ts +153 -0
  223. package/dist/lib/calendar.js +312 -0
  224. package/dist/lib/cn.d.ts +3 -1
  225. package/dist/lib/cn.js +5 -0
  226. package/dist/lib/code-highlight.d.ts +14 -0
  227. package/dist/lib/code-highlight.js +81 -18
  228. package/dist/lib/drag.d.ts +39 -0
  229. package/dist/lib/drag.js +96 -0
  230. package/dist/lib/editorial-assets.js +16 -8
  231. package/dist/lib/figure/figures/automation.js +25 -6
  232. package/dist/lib/figure/figures/bar-chart.js +6 -1
  233. package/dist/lib/figure/figures/brackets-classic.js +4 -1
  234. package/dist/lib/figure/figures/city.js +12 -2
  235. package/dist/lib/figure/figures/conveyor.js +17 -4
  236. package/dist/lib/figure/figures/database.js +5 -2
  237. package/dist/lib/figure/figures/documents.js +11 -3
  238. package/dist/lib/figure/figures/inbox.js +5 -2
  239. package/dist/lib/figure/figures/laptop.js +3 -1
  240. package/dist/lib/figure/figures/pipeline.js +45 -10
  241. package/dist/lib/figure/figures/platform.js +62 -7
  242. package/dist/lib/figure/figures/server.js +21 -5
  243. package/dist/lib/figure/figures/spreadsheet.js +29 -5
  244. package/dist/lib/figure/kernel.d.ts +4 -2
  245. package/dist/lib/figure/kernel.js +10 -5
  246. package/dist/lib/figure/parts.js +6 -2
  247. package/dist/lib/files.d.ts +31 -0
  248. package/dist/lib/files.js +60 -0
  249. package/dist/lib/gesture.d.ts +70 -0
  250. package/dist/lib/gesture.js +141 -0
  251. package/dist/lib/glide.d.ts +10 -4
  252. package/dist/lib/glide.js +14 -5
  253. package/dist/lib/icons.d.ts +1 -0
  254. package/dist/lib/icons.js +6 -0
  255. package/dist/lib/illustration-library.js +1 -6
  256. package/dist/lib/markdown-edit.d.ts +112 -0
  257. package/dist/lib/markdown-edit.js +557 -0
  258. package/dist/lib/markdown-rich-editor.d.ts +188 -0
  259. package/dist/lib/markdown-rich-editor.js +1153 -0
  260. package/dist/lib/markdown-rich.d.ts +63 -0
  261. package/dist/lib/markdown-rich.js +534 -0
  262. package/dist/lib/mentions.d.ts +100 -0
  263. package/dist/lib/mentions.js +246 -0
  264. package/dist/lib/motion.d.ts +18 -0
  265. package/dist/lib/motion.js +43 -5
  266. package/dist/lib/number-roll.d.ts +89 -0
  267. package/dist/lib/number-roll.js +391 -0
  268. package/dist/lib/platform.d.ts +6 -0
  269. package/dist/lib/platform.js +14 -0
  270. package/dist/lib/portal-container.d.ts +9 -0
  271. package/dist/lib/portal-container.js +10 -0
  272. package/dist/lib/press.d.ts +5 -0
  273. package/dist/lib/press.js +186 -0
  274. package/dist/lib/scheduler.d.ts +128 -0
  275. package/dist/lib/scheduler.js +272 -0
  276. package/dist/lib/scroll-edges.d.ts +9 -0
  277. package/dist/lib/scroll-edges.js +50 -0
  278. package/dist/lib/table-fit.d.ts +4 -3
  279. package/dist/lib/table-fit.js +92 -25
  280. package/dist/lib/theme-preset.d.ts +267 -0
  281. package/dist/lib/theme-preset.js +1046 -0
  282. package/dist/lib/theme-script.d.ts +23 -3
  283. package/dist/lib/theme-script.js +17 -5
  284. package/dist/lib/tippy/sprite.d.ts +36 -4
  285. package/dist/lib/tippy/sprite.js +188 -15
  286. package/dist/lib/tone.d.ts +4 -0
  287. package/dist/lib/tone.js +1 -0
  288. package/dist/messages/de.d.ts +3 -3
  289. package/dist/messages/de.js +274 -3
  290. package/dist/skills/zon-ui/SKILL.md +279 -0
  291. package/dist/skills/zon-ui/references/authoring.md +265 -0
  292. package/dist/skills/zon-ui/references/brand.md +416 -0
  293. package/dist/skills/zon-ui/references/components/accordion.md +199 -0
  294. package/dist/skills/zon-ui/references/components/action-sheet.md +268 -0
  295. package/dist/skills/zon-ui/references/components/alert-dialog.md +276 -0
  296. package/dist/skills/zon-ui/references/components/alert.md +167 -0
  297. package/dist/skills/zon-ui/references/components/app-bar.md +307 -0
  298. package/dist/skills/zon-ui/references/components/ascii-field.md +121 -0
  299. package/dist/skills/zon-ui/references/components/aspect-ratio.md +112 -0
  300. package/dist/skills/zon-ui/references/components/audio-player.md +231 -0
  301. package/dist/skills/zon-ui/references/components/avatar.md +98 -0
  302. package/dist/skills/zon-ui/references/components/badge.md +227 -0
  303. package/dist/skills/zon-ui/references/components/bottom-nav.md +709 -0
  304. package/dist/skills/zon-ui/references/components/breadcrumb.md +143 -0
  305. package/dist/skills/zon-ui/references/components/button-group.md +216 -0
  306. package/dist/skills/zon-ui/references/components/button.md +309 -0
  307. package/dist/skills/zon-ui/references/components/calendar.md +296 -0
  308. package/dist/skills/zon-ui/references/components/card.md +158 -0
  309. package/dist/skills/zon-ui/references/components/carousel.md +297 -0
  310. package/dist/skills/zon-ui/references/components/chart.md +739 -0
  311. package/dist/skills/zon-ui/references/components/chat.md +417 -0
  312. package/dist/skills/zon-ui/references/components/checkbox.md +219 -0
  313. package/dist/skills/zon-ui/references/components/code-block.md +143 -0
  314. package/dist/skills/zon-ui/references/components/code-highlight.md +118 -0
  315. package/dist/skills/zon-ui/references/components/collapsible.md +146 -0
  316. package/dist/skills/zon-ui/references/components/color-picker.md +200 -0
  317. package/dist/skills/zon-ui/references/components/combobox.md +455 -0
  318. package/dist/skills/zon-ui/references/components/command.md +326 -0
  319. package/dist/skills/zon-ui/references/components/contact-form.md +562 -0
  320. package/dist/skills/zon-ui/references/components/context-menu.md +159 -0
  321. package/dist/skills/zon-ui/references/components/conversation.md +146 -0
  322. package/dist/skills/zon-ui/references/components/copy-button.md +162 -0
  323. package/dist/skills/zon-ui/references/components/crm.md +1022 -0
  324. package/dist/skills/zon-ui/references/components/dashboard.md +612 -0
  325. package/dist/skills/zon-ui/references/components/data-table.md +776 -0
  326. package/dist/skills/zon-ui/references/components/date-picker.md +444 -0
  327. package/dist/skills/zon-ui/references/components/dialog.md +335 -0
  328. package/dist/skills/zon-ui/references/components/direction.md +165 -0
  329. package/dist/skills/zon-ui/references/components/drawer.md +276 -0
  330. package/dist/skills/zon-ui/references/components/drawing.md +94 -0
  331. package/dist/skills/zon-ui/references/components/empty.md +225 -0
  332. package/dist/skills/zon-ui/references/components/feature-list.md +412 -0
  333. package/dist/skills/zon-ui/references/components/field.md +209 -0
  334. package/dist/skills/zon-ui/references/components/file-drop.md +234 -0
  335. package/dist/skills/zon-ui/references/components/filter-bar.md +485 -0
  336. package/dist/skills/zon-ui/references/components/form.md +970 -0
  337. package/dist/skills/zon-ui/references/components/graph.md +339 -0
  338. package/dist/skills/zon-ui/references/components/illustration.md +497 -0
  339. package/dist/skills/zon-ui/references/components/inbox.md +263 -0
  340. package/dist/skills/zon-ui/references/components/input-group.md +339 -0
  341. package/dist/skills/zon-ui/references/components/input.md +189 -0
  342. package/dist/skills/zon-ui/references/components/item.md +277 -0
  343. package/dist/skills/zon-ui/references/components/kanban.md +626 -0
  344. package/dist/skills/zon-ui/references/components/kbd.md +116 -0
  345. package/dist/skills/zon-ui/references/components/label.md +104 -0
  346. package/dist/skills/zon-ui/references/components/layout.md +291 -0
  347. package/dist/skills/zon-ui/references/components/lightbox.md +235 -0
  348. package/dist/skills/zon-ui/references/components/locale.md +279 -0
  349. package/dist/skills/zon-ui/references/components/logo.md +257 -0
  350. package/dist/skills/zon-ui/references/components/markdown-editor.md +558 -0
  351. package/dist/skills/zon-ui/references/components/mentions.md +512 -0
  352. package/dist/skills/zon-ui/references/components/menu.md +218 -0
  353. package/dist/skills/zon-ui/references/components/menubar.md +292 -0
  354. package/dist/skills/zon-ui/references/components/message.md +243 -0
  355. package/dist/skills/zon-ui/references/components/meter.md +105 -0
  356. package/dist/skills/zon-ui/references/components/money-input.md +333 -0
  357. package/dist/skills/zon-ui/references/components/native-select.md +197 -0
  358. package/dist/skills/zon-ui/references/components/navigation-menu.md +253 -0
  359. package/dist/skills/zon-ui/references/components/number-field.md +210 -0
  360. package/dist/skills/zon-ui/references/components/number-roll.md +175 -0
  361. package/dist/skills/zon-ui/references/components/onboarding.md +896 -0
  362. package/dist/skills/zon-ui/references/components/otp-field.md +166 -0
  363. package/dist/skills/zon-ui/references/components/pagination.md +109 -0
  364. package/dist/skills/zon-ui/references/components/pdf-viewer.md +177 -0
  365. package/dist/skills/zon-ui/references/components/phone-input.md +252 -0
  366. package/dist/skills/zon-ui/references/components/popover.md +176 -0
  367. package/dist/skills/zon-ui/references/components/preview-card.md +193 -0
  368. package/dist/skills/zon-ui/references/components/pricing.md +724 -0
  369. package/dist/skills/zon-ui/references/components/progress.md +92 -0
  370. package/dist/skills/zon-ui/references/components/prompt-input.md +307 -0
  371. package/dist/skills/zon-ui/references/components/pull-to-refresh.md +188 -0
  372. package/dist/skills/zon-ui/references/components/quote.md +115 -0
  373. package/dist/skills/zon-ui/references/components/radio-group.md +215 -0
  374. package/dist/skills/zon-ui/references/components/rating.md +260 -0
  375. package/dist/skills/zon-ui/references/components/reasoning.md +102 -0
  376. package/dist/skills/zon-ui/references/components/resizable.md +213 -0
  377. package/dist/skills/zon-ui/references/components/response.md +170 -0
  378. package/dist/skills/zon-ui/references/components/scheduler.md +732 -0
  379. package/dist/skills/zon-ui/references/components/scroll-area.md +122 -0
  380. package/dist/skills/zon-ui/references/components/select.md +351 -0
  381. package/dist/skills/zon-ui/references/components/separator.md +103 -0
  382. package/dist/skills/zon-ui/references/components/settings.md +793 -0
  383. package/dist/skills/zon-ui/references/components/shop.md +1715 -0
  384. package/dist/skills/zon-ui/references/components/sidebar.md +813 -0
  385. package/dist/skills/zon-ui/references/components/sign-in.md +1639 -0
  386. package/dist/skills/zon-ui/references/components/site-header.md +303 -0
  387. package/dist/skills/zon-ui/references/components/skeleton.md +256 -0
  388. package/dist/skills/zon-ui/references/components/slider.md +172 -0
  389. package/dist/skills/zon-ui/references/components/sortable.md +405 -0
  390. package/dist/skills/zon-ui/references/components/sources.md +106 -0
  391. package/dist/skills/zon-ui/references/components/spinner.md +222 -0
  392. package/dist/skills/zon-ui/references/components/stat.md +267 -0
  393. package/dist/skills/zon-ui/references/components/stepper.md +285 -0
  394. package/dist/skills/zon-ui/references/components/suggestions.md +146 -0
  395. package/dist/skills/zon-ui/references/components/swipe-actions.md +344 -0
  396. package/dist/skills/zon-ui/references/components/switch.md +160 -0
  397. package/dist/skills/zon-ui/references/components/table.md +999 -0
  398. package/dist/skills/zon-ui/references/components/tabs.md +258 -0
  399. package/dist/skills/zon-ui/references/components/tag.md +115 -0
  400. package/dist/skills/zon-ui/references/components/tags-input.md +216 -0
  401. package/dist/skills/zon-ui/references/components/textarea.md +95 -0
  402. package/dist/skills/zon-ui/references/components/theme-editor.md +3940 -0
  403. package/dist/skills/zon-ui/references/components/theme.md +362 -0
  404. package/dist/skills/zon-ui/references/components/time-field.md +222 -0
  405. package/dist/skills/zon-ui/references/components/timeline.md +285 -0
  406. package/dist/skills/zon-ui/references/components/tippy.md +243 -0
  407. package/dist/skills/zon-ui/references/components/toast.md +220 -0
  408. package/dist/skills/zon-ui/references/components/toggle-group.md +261 -0
  409. package/dist/skills/zon-ui/references/components/toggle.md +167 -0
  410. package/dist/skills/zon-ui/references/components/tool-call.md +146 -0
  411. package/dist/skills/zon-ui/references/components/toolbar.md +260 -0
  412. package/dist/skills/zon-ui/references/components/tooltip.md +172 -0
  413. package/dist/skills/zon-ui/references/components/tour.md +423 -0
  414. package/dist/skills/zon-ui/references/components/tree.md +481 -0
  415. package/dist/skills/zon-ui/references/components/typography.md +347 -0
  416. package/dist/skills/zon-ui/references/components/video-player.md +386 -0
  417. package/dist/skills/zon-ui/references/marketing.md +467 -0
  418. package/dist/skills/zon-ui/references/motion.md +455 -0
  419. package/dist/skills/zon-ui/references/recipes.md +1232 -0
  420. package/dist/skills/zon-ui/references/tokens.md +866 -0
  421. package/dist/sources/accordion.css +4 -0
  422. package/dist/sources/action-sheet.css +11 -0
  423. package/dist/sources/alert-dialog.css +6 -0
  424. package/dist/sources/alert.css +3 -0
  425. package/dist/sources/app-bar.css +14 -0
  426. package/dist/sources/ascii-field.css +3 -0
  427. package/dist/sources/aspect-ratio.css +3 -0
  428. package/dist/sources/audio-player.css +20 -0
  429. package/dist/sources/avatar.css +3 -0
  430. package/dist/sources/badge.css +3 -0
  431. package/dist/sources/bottom-nav.css +9 -0
  432. package/dist/sources/breadcrumb.css +14 -0
  433. package/dist/sources/button-group.css +3 -0
  434. package/dist/sources/button.css +9 -0
  435. package/dist/sources/calendar.css +13 -0
  436. package/dist/sources/card.css +3 -0
  437. package/dist/sources/carousel.css +11 -0
  438. package/dist/sources/chart.css +5 -0
  439. package/dist/sources/checkbox.css +6 -0
  440. package/dist/sources/code-block.css +13 -0
  441. package/dist/sources/collapsible.css +4 -0
  442. package/dist/sources/color-picker.css +13 -0
  443. package/dist/sources/combobox.css +13 -0
  444. package/dist/sources/command.css +13 -0
  445. package/dist/sources/context-menu.css +12 -0
  446. package/dist/sources/conversation.css +10 -0
  447. package/dist/sources/copy-button.css +10 -0
  448. package/dist/sources/data-table.css +27 -0
  449. package/dist/sources/date-picker.css +20 -0
  450. package/dist/sources/dialog.css +9 -0
  451. package/dist/sources/direction.css +2 -0
  452. package/dist/sources/drawer.css +9 -0
  453. package/dist/sources/drawing.css +5 -0
  454. package/dist/sources/empty.css +3 -0
  455. package/dist/sources/feature-list.css +4 -0
  456. package/dist/sources/field.css +4 -0
  457. package/dist/sources/file-drop.css +15 -0
  458. package/dist/sources/filter-bar.css +30 -0
  459. package/dist/sources/form.css +4 -0
  460. package/dist/sources/graph.css +19 -0
  461. package/dist/sources/illustration.css +28 -0
  462. package/dist/sources/input-group.css +7 -0
  463. package/dist/sources/input.css +3 -0
  464. package/dist/sources/item.css +4 -0
  465. package/dist/sources/kbd.css +5 -0
  466. package/dist/sources/label.css +3 -0
  467. package/dist/sources/layout.css +3 -0
  468. package/dist/sources/lightbox.css +33 -0
  469. package/dist/sources/locale.css +2 -0
  470. package/dist/sources/logo.css +4 -0
  471. package/dist/sources/markdown-editor.css +41 -0
  472. package/dist/sources/mentions.css +13 -0
  473. package/dist/sources/menu.css +11 -0
  474. package/dist/sources/menubar.css +14 -0
  475. package/dist/sources/message.css +16 -0
  476. package/dist/sources/meter.css +4 -0
  477. package/dist/sources/money-input.css +10 -0
  478. package/dist/sources/native-select.css +4 -0
  479. package/dist/sources/navigation-menu.css +8 -0
  480. package/dist/sources/number-field.css +8 -0
  481. package/dist/sources/number-roll.css +6 -0
  482. package/dist/sources/otp-field.css +5 -0
  483. package/dist/sources/pagination.css +11 -0
  484. package/dist/sources/pdf-viewer.css +30 -0
  485. package/dist/sources/phone-input.css +20 -0
  486. package/dist/sources/popover.css +7 -0
  487. package/dist/sources/preview-card.css +7 -0
  488. package/dist/sources/progress.css +4 -0
  489. package/dist/sources/prompt-input.css +15 -0
  490. package/dist/sources/pull-to-refresh.css +14 -0
  491. package/dist/sources/quote.css +3 -0
  492. package/dist/sources/radio-group.css +5 -0
  493. package/dist/sources/rating.css +6 -0
  494. package/dist/sources/reasoning.css +6 -0
  495. package/dist/sources/resizable.css +4 -0
  496. package/dist/sources/response.css +16 -0
  497. package/dist/sources/scheduler.css +44 -0
  498. package/dist/sources/scroll-area.css +3 -0
  499. package/dist/sources/select.css +12 -0
  500. package/dist/sources/separator.css +3 -0
  501. package/dist/sources/sidebar.css +19 -0
  502. package/dist/sources/site-header.css +15 -0
  503. package/dist/sources/skeleton.css +3 -0
  504. package/dist/sources/slider.css +6 -0
  505. package/dist/sources/sortable.css +12 -0
  506. package/dist/sources/sources.css +6 -0
  507. package/dist/sources/spinner.css +6 -0
  508. package/dist/sources/stat.css +9 -0
  509. package/dist/sources/stepper.css +6 -0
  510. package/dist/sources/suggestions.css +10 -0
  511. package/dist/sources/swipe-actions.css +20 -0
  512. package/dist/sources/switch.css +5 -0
  513. package/dist/sources/table.css +7 -0
  514. package/dist/sources/tabs.css +5 -0
  515. package/dist/sources/tag.css +3 -0
  516. package/dist/sources/tags-input.css +6 -0
  517. package/dist/sources/textarea.css +3 -0
  518. package/dist/sources/theme.css +13 -0
  519. package/dist/sources/time-field.css +7 -0
  520. package/dist/sources/timeline.css +7 -0
  521. package/dist/sources/tippy.css +6 -0
  522. package/dist/sources/toast.css +6 -0
  523. package/dist/sources/toggle-group.css +5 -0
  524. package/dist/sources/toggle.css +3 -0
  525. package/dist/sources/tool-call.css +16 -0
  526. package/dist/sources/toolbar.css +14 -0
  527. package/dist/sources/tooltip.css +6 -0
  528. package/dist/sources/tour.css +14 -0
  529. package/dist/sources/tree.css +6 -0
  530. package/dist/sources/typography.css +4 -0
  531. package/dist/sources/video-player.css +21 -0
  532. package/dist/styles/ai.css +3 -0
  533. package/dist/styles/brand.css +98 -0
  534. package/dist/styles/core.css +266 -0
  535. package/dist/styles/editor.css +3 -0
  536. package/dist/styles/expressive.css +75 -77
  537. package/dist/styles/fonts.css +61 -117
  538. package/dist/styles/graph.css +4 -0
  539. package/dist/styles/illustration.css +4 -0
  540. package/dist/styles/index.css +11 -193
  541. package/dist/styles/material.css +177 -31
  542. package/dist/styles/parts/ai.css +20 -14
  543. package/dist/styles/parts/brand.css +2 -2
  544. package/dist/styles/parts/controls.css +51 -38
  545. package/dist/styles/parts/data.css +43 -11
  546. package/dist/styles/parts/editor.css +372 -0
  547. package/dist/styles/parts/feedback.css +75 -15
  548. package/dist/styles/parts/foundations.css +12 -7
  549. package/dist/styles/parts/graph.css +25 -9
  550. package/dist/styles/parts/inputs.css +172 -9
  551. package/dist/styles/parts/isometric.css +6 -5
  552. package/dist/styles/parts/navigation.css +237 -25
  553. package/dist/styles/parts/overlays.css +110 -8
  554. package/dist/styles/parts/pdf.css +15 -9
  555. package/dist/styles/pdf.css +3 -0
  556. package/dist/styles/prose.css +3 -0
  557. package/dist/styles/tokens.css +105 -15
  558. package/dist/theme.d.ts +1 -0
  559. package/dist/theme.js +5 -0
  560. package/dist/vite.d.ts +48 -59
  561. package/dist/vite.js +54 -21
  562. package/package.json +69 -2
@@ -0,0 +1,252 @@
1
+ # Phone Input
2
+
3
+ ```tsx
4
+ import { Field, FieldDescription, FieldLabel, PhoneInput } from "@zonsh/ui";
5
+
6
+ export function Basic() {
7
+ return (
8
+ <Field className="max-w-80">
9
+ <FieldLabel>Mobile number</FieldLabel>
10
+ <PhoneInput defaultCountry="GB" locale="en-GB" name="phone" placeholder="7700 900123" />
11
+ <FieldDescription>We text a sign-in code to this number.</FieldDescription>
12
+ </Field>
13
+ );
14
+ }
15
+ ```
16
+
17
+ One recessed field, like `InputGroup`: a flat country button showing `GB +44` in Licht Mono, then the number in mono tabular figures, grouped as typed (`20 7946 0018`). The button opens a list of every country, named and sorted in the locale, searchable by name, ISO code or calling code (`+64`).
18
+
19
+ ## Usage
20
+
21
+ ```tsx
22
+ import { Field, FieldLabel, PhoneInput } from "@zonsh/ui";
23
+
24
+ <Field name="phone">
25
+ <FieldLabel>Mobile number</FieldLabel>
26
+ <PhoneInput defaultCountry="DE" required />
27
+ </Field>;
28
+ ```
29
+
30
+ The props you'll set: `defaultCountry`, `value` / `onValueChange` and `countries`.
31
+
32
+ Typing or pasting an international number (`+44 20 7946 0018`, `0044 …`, `+44 (0)20 …`) switches the country, announced to screen readers. A trunk prefix (`020 …` in the UK) is read without it and dropped from the display on blur.
33
+
34
+ ## When to use
35
+
36
+ - A phone number someone gives you: an account's mobile number, a delivery contact, two-step sign-in.
37
+ - Numbers from one country too, with `countries={["DE"]}`: the value stays E.164.
38
+ - Not for numbers that aren't phone numbers — a customer number, a PIN, a one-time code (`OtpField`).
39
+
40
+ ## The value
41
+
42
+ The value is **E.164** — `"+442079460018"` — or `null` with no digits: what SMS, voice and identity providers take. Store it as is; format it where you show it. `onValueChange` also gives the country, the national number and whether its length fits.
43
+
44
+ The country is separate state (`country` / `onCountryChange` or `defaultCountry`); otherwise it is the value's, then the locale region's (`en-GB` → GB), then US.
45
+
46
+ ## Examples
47
+
48
+ ### The value
49
+
50
+ Controlled, showing what `onValueChange` reports.
51
+
52
+ ```tsx
53
+ import { Field, FieldDescription, FieldLabel, PhoneInput } from "@zonsh/ui";
54
+ import * as React from "react";
55
+
56
+ export function Value() {
57
+ const [value, setValue] = React.useState<string | null>("+442079460018");
58
+ const [details, setDetails] = React.useState({ country: "GB", valid: true });
59
+ return (
60
+ <div className="flex max-w-80 flex-col gap-4">
61
+ <Field>
62
+ <FieldLabel>Pharmacy phone</FieldLabel>
63
+ <PhoneInput
64
+ locale="en-GB"
65
+ value={value}
66
+ onValueChange={(next, d) => {
67
+ setValue(next);
68
+ setDetails({ country: d.country, valid: d.valid });
69
+ }}
70
+ />
71
+ <FieldDescription>Paste +1 415 555 0132 to switch to the United States.</FieldDescription>
72
+ </Field>
73
+ <dl className="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 font-mono text-[13px] tabular-nums">
74
+ <dt className="text-muted-foreground">value</dt>
75
+ <dd data-testid="phone-value">{value === null ? "null" : `"${value}"`}</dd>
76
+ <dt className="text-muted-foreground">country</dt>
77
+ <dd data-testid="phone-country">{details.country}</dd>
78
+ <dt className="text-muted-foreground">valid</dt>
79
+ <dd data-testid="phone-valid">{String(details.valid)}</dd>
80
+ </dl>
81
+ </div>
82
+ );
83
+ }
84
+ ```
85
+
86
+ ### Countries and language
87
+
88
+ `countries` limits the list; names follow `locale`, or the `LocaleProvider`'s.
89
+
90
+ ```tsx
91
+ import { Field, FieldDescription, FieldLabel, PhoneInput } from "@zonsh/ui";
92
+
93
+ export function Countries() {
94
+ return (
95
+ <Field className="max-w-80">
96
+ <FieldLabel>Telefon für die Zustellung</FieldLabel>
97
+ <PhoneInput locale="de-DE" defaultCountry="AT" countries={["AT", "CH", "DE", "LI"]} />
98
+ <FieldDescription>
99
+ Wir liefern nach Österreich, Deutschland, Liechtenstein und in die Schweiz.
100
+ </FieldDescription>
101
+ </Field>
102
+ );
103
+ }
104
+ ```
105
+
106
+ ### Sizes
107
+
108
+ ```tsx
109
+ import { Field, FieldLabel, PhoneInput } from "@zonsh/ui";
110
+
111
+ export function Sizes() {
112
+ return (
113
+ <div className="flex max-w-80 flex-col gap-4">
114
+ <Field>
115
+ <FieldLabel>Dense</FieldLabel>
116
+ <PhoneInput size="sm" locale="en-US" defaultValue="+14155550132" />
117
+ </Field>
118
+ <Field>
119
+ <FieldLabel>Default</FieldLabel>
120
+ <PhoneInput locale="en-US" defaultValue="+14155550132" />
121
+ </Field>
122
+ <Field>
123
+ <FieldLabel>Prominent</FieldLabel>
124
+ <PhoneInput size="lg" locale="en-US" defaultValue="+14155550132" />
125
+ </Field>
126
+ </div>
127
+ );
128
+ }
129
+ ```
130
+
131
+ ### States
132
+
133
+ ```tsx
134
+ import { Field, FieldError, FieldLabel, PhoneInput } from "@zonsh/ui";
135
+
136
+ export function States() {
137
+ return (
138
+ <div className="flex max-w-80 flex-col gap-4">
139
+ <Field invalid>
140
+ <FieldLabel>Emergency contact</FieldLabel>
141
+ <PhoneInput locale="en-GB" defaultValue="+4420794600" />
142
+ <FieldError match>This number is too short for +44 (United Kingdom).</FieldError>
143
+ </Field>
144
+ <Field disabled>
145
+ <FieldLabel>Office line</FieldLabel>
146
+ <PhoneInput locale="en-US" defaultValue="+14155550101" />
147
+ </Field>
148
+ <Field>
149
+ <FieldLabel>Number on file</FieldLabel>
150
+ <PhoneInput locale="en-GB" defaultValue="+442079460018" readOnly />
151
+ </Field>
152
+ </div>
153
+ );
154
+ }
155
+ ```
156
+
157
+ ### In a form
158
+
159
+ `required`, or a wrong length for the country, stops a `Form`'s submit and shows the `FieldError`.
160
+
161
+ ```tsx
162
+ import { Button, Field, FieldError, FieldLabel, Form, FormActions, PhoneInput } from "@zonsh/ui";
163
+ import * as React from "react";
164
+
165
+ export function InAForm() {
166
+ const [sent, setSent] = React.useState<string | null>(null);
167
+ return (
168
+ <Form className="max-w-80" onFormSubmit={(values: { phone: string }) => setSent(values.phone)}>
169
+ <Field name="phone">
170
+ <FieldLabel>Number for delivery updates</FieldLabel>
171
+ <PhoneInput locale="en-US" defaultCountry="US" required />
172
+ <FieldError match="valueMissing">Enter a number we can text.</FieldError>
173
+ <FieldError match="customError" />
174
+ </Field>
175
+ <FormActions>
176
+ <Button type="submit">Save number</Button>
177
+ </FormActions>
178
+ {sent && (
179
+ <p data-testid="phone-sent" className="font-mono text-[13px] text-muted-foreground tabular-nums">
180
+ Submitted {sent}
181
+ </p>
182
+ )}
183
+ </Form>
184
+ );
185
+ }
186
+ ```
187
+
188
+ ## What the length check knows
189
+
190
+ Country data is [libphonenumber](https://github.com/google/libphonenumber)'s metadata (`PhoneNumberMetadata.xml`, from ITU and national numbering plans) at `v9.0.43` (Apache-2.0), compiled by `pnpm phone:data` into `src/lib/phone-countries.ts` (~10 KB gzipped): calling codes, possible lengths, trunk and international prefixes, 0-ranges, leading digits for shared codes and national format groups. Per-kind patterns are left out:
191
+
192
+ - **Length only.** A number passes when its length is possible in its country — libphonenumber's "is possible", not "is valid". Some ranges are wide (Germany 4–13 digits); local-only lengths don't count. Confirm a number by sending it a code.
193
+ - **Shared calling codes** split by leading digits as libphonenumber does: +1 by area code (Canada, each Caribbean country), +7 by the first digit (Kazakhstan's 7), +44 for Jersey, Guernsey and the Isle of Man, +590 for Saint Barthélemy and Saint Martin, and so on. An ambiguous number (North America's toll-free 800) goes to the main country, unless another is already chosen and the digits still fit it.
194
+ - **Grouping follows libphonenumber's national formats** (`6 12 34 56 78`, `90 1234 5678`), a trunk prefix joined to the first group (`020 …`) or apart where the country writes it so (`8 912 345 67 89`). Germany follows DIN 5008 (`30 12345678`, `01511 2345678`). Formats that drop or reorder digits (Argentina's mobile "15") are left out; unmatched numbers group in threes and fours. The value never contains spaces.
195
+ - **Numbering plans change.** Bump the pinned tag in `scripts/gen-phone-countries.mjs` and run `pnpm phone:data`: it downloads the XML into `node_modules/.cache`, prints its SHA-256 once for the script to pin, then writes the table. Unit tests check the table and every example number against libphonenumber when the XML is present; CI fetches it (`pnpm phone:data --fetch`).
196
+ - **International prefixes.** `+` and `00` everywhere, plus each country's own (`011` North America, `0011` Australia, `010` Japan, `810` Tajikistan …). A prefix that would make 0 a calling code (`000 …`), or that the country's own numbers start with (Russia's `8 10`), isn't read as one.
197
+ - **Numbers that start with 0** where 0 is also the trunk prefix are read whole (Rwanda's `06` fixed lines, freephone `000800 …` in India, `00798 …` in Korea, and the like); the value keeps the 0 (`+25006123456`), checked against that range's lengths.
198
+
199
+ ## Props
200
+
201
+ | Prop | Type | Default |
202
+ | ---------------------------- | ----------------------------------------------------------------------------------- | ------------------------- |
203
+ | `value` / `defaultValue` | `string \| null`: E.164, `"+442079460018"` | — |
204
+ | `onValueChange` | `(value, { country, nationalNumber, valid }) => void` | — |
205
+ | `country` / `defaultCountry` | `string`: ISO 3166 code, `"DE"` | the value's, locale's, US |
206
+ | `onCountryChange` | `(country: string) => void` | — |
207
+ | `countries` | `string[]`: ISO codes to offer | every country |
208
+ | `locale` | `string` (BCP 47), for the country names and the default country | the provider's, browser |
209
+ | `size` | `"sm" \| "default" \| "lg"` | `"default"` |
210
+ | `name` | `string`: submits the E.164 value | — |
211
+ | `required` | `boolean` | `false` |
212
+ | `disabled` / `readOnly` | `boolean` | `false` |
213
+ | `labels` | `{ country?, search?, empty?, countryChanged?, tooShort?, tooLong?, unknownCode? }` | English |
214
+
215
+ Other props go to the `<input>`, which is `type="tel"` with `autocomplete="tel"`, so a saved number fills it and picks its country. A form reset returns an uncontrolled field to `defaultValue`.
216
+
217
+ Messages come from `labels`, or a `LocaleProvider`'s `phoneInput`; `tooShort` and `tooLong` get the country's localised name and calling code. A `FieldError` with `match="customError"` shows them, `match="valueMissing"` an empty required field.
218
+
219
+ Data attributes: `data-slot="phone-input"` and `data-size` on the root, `data-phone-input-country` on the country button (which keeps `data-slot="input-group-button"`, with `data-popup-open` while the list is open), and the `Field`'s state attributes on the field.
220
+
221
+ ## Brand rules
222
+
223
+ - **Do** keep the E.164 value from the field to the server, and say in a `FieldDescription` what the number is for.
224
+ - **Do** confirm a number that matters by sending it a code; the length check only catches typos.
225
+ - **Don't** add flags. Countries are told apart by name and code, in mono; a flag is not a language or a country's name, and emoji flags don't render everywhere.
226
+ - **Don't** split the country and the number into two separate fields.
227
+
228
+ ## Accessibility
229
+
230
+ - The number is a `tel` input named by its `FieldLabel`. The country button is named for what it shows, "Country: United Kingdom, +44", and opens a listbox with a search field.
231
+ - A country switched by typing or pasting is announced in a polite live region.
232
+ - Errors use the destructive edge and a message, never colour alone.
233
+
234
+ ### Keyboard
235
+
236
+ | Key | What it does |
237
+ | --------------------- | ------------------------------------------------------------------------------------- |
238
+ | Tab | Moves from the country button to the number |
239
+ | Enter / Space / ↓ / ↑ | Opens the country list, on the country button, with focus in its search |
240
+ | ↑ / ↓ | Moves through the countries |
241
+ | Enter | Picks the highlighted country and returns focus to the number |
242
+ | Escape | Closes the list |
243
+ | Backspace / Delete | Next to a space in the number, removes the digit beyond it |
244
+ | ⌘V / Ctrl+V | Pastes a whole international number ("+44 …") over the field and switches the country |
245
+
246
+ Typing in the search filters the countries by name, ISO code or calling code ("+44").
247
+
248
+ ---
249
+
250
+ - Import: `import { PhoneInput } from "@zonsh/ui"`
251
+ - Source: `packages/ui/src/components/phone-input.tsx`
252
+ - Primitive: `@base-ui/react/combobox` (Base UI docs: `node_modules/@base-ui/react/docs/react/components/combobox.md`)
@@ -0,0 +1,176 @@
1
+ # Popover
2
+
3
+ ```tsx
4
+ import { Button, Popover, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from "@zonsh/ui";
5
+
6
+ export function Basic() {
7
+ return (
8
+ <Popover>
9
+ <PopoverTrigger render={<Button variant="secondary" />}>When will it arrive?</PopoverTrigger>
10
+ <PopoverContent>
11
+ <PopoverTitle>After you order</PopoverTitle>
12
+ <PopoverDescription>
13
+ Orders placed before 14:00 leave the same day and usually arrive in two to three working days.
14
+ </PopoverDescription>
15
+ </PopoverContent>
16
+ </Popover>
17
+ );
18
+ }
19
+ ```
20
+
21
+ A small panel attached to the control that opened it, in `material-menu` at 12px, scaling in from its trigger. Across, it stays within its trigger's room — in a narrow panel it shifts and narrows to fit; up and down it may use the window.
22
+
23
+ ## Usage
24
+
25
+ ```tsx
26
+ import {
27
+ Button,
28
+ Popover,
29
+ PopoverContent,
30
+ PopoverDescription,
31
+ PopoverTitle,
32
+ PopoverTrigger,
33
+ } from "@zonsh/ui";
34
+
35
+ <Popover>
36
+ <PopoverTrigger render={<Button variant="secondary" />}>When will it arrive?</PopoverTrigger>
37
+ <PopoverContent>
38
+ <PopoverTitle>After you order</PopoverTitle>
39
+ <PopoverDescription>Orders placed before 14:00 leave the same day.</PopoverDescription>
40
+ </PopoverContent>
41
+ </Popover>;
42
+ ```
43
+
44
+ The props you'll reach for: `render` on the trigger (to make it a `Button`), `side` / `align` on the content, and `arrow`.
45
+
46
+ ## When to use
47
+
48
+ - A hint that needs more than a tooltip: a sentence and a link.
49
+ - A short inline form — invite someone, rename a tag.
50
+ - Not for a list of actions (`Menu`), nor a task with a heading, scroll and footer (`Dialog`).
51
+ - Not for a glance at where a link goes (`PreviewCard`, which never opens on touch). A popover is a panel you act in, opened by a button and announced as a dialog.
52
+
53
+ ## Examples
54
+
55
+ ### With arrow
56
+
57
+ Base UI flips the side when there is no room.
58
+
59
+ ```tsx
60
+ import { Button, Popover, PopoverContent, PopoverDescription, PopoverTrigger } from "@zonsh/ui";
61
+ import { InfoIcon } from "lucide-react";
62
+
63
+ export function WithArrow() {
64
+ return (
65
+ <div className="flex flex-wrap gap-3">
66
+ {(["left", "top", "bottom", "right"] as const).map((side) => (
67
+ <Popover key={side}>
68
+ <PopoverTrigger
69
+ render={<Button variant="secondary" size="icon" aria-label={`Details (${side})`} />}
70
+ >
71
+ <InfoIcon />
72
+ </PopoverTrigger>
73
+ <PopoverContent side={side} arrow className="w-60">
74
+ <PopoverDescription>Opens on the {side}. The notch points at the trigger.</PopoverDescription>
75
+ </PopoverContent>
76
+ </Popover>
77
+ ))}
78
+ </div>
79
+ );
80
+ }
81
+ ```
82
+
83
+ ### With form
84
+
85
+ ```tsx
86
+ import { Button, Field, FieldLabel, Input, Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from "@zonsh/ui";
87
+
88
+ export function WithForm() {
89
+ return (
90
+ <Popover>
91
+ <PopoverTrigger render={<Button variant="secondary" />}>Invite a colleague</PopoverTrigger>
92
+ <PopoverContent align="start" className="w-80 gap-4">
93
+ <div className="flex flex-col gap-1.5">
94
+ <PopoverTitle>Invite a colleague</PopoverTitle>
95
+ <PopoverDescription>They get read access to this project.</PopoverDescription>
96
+ </div>
97
+ <Field>
98
+ <FieldLabel>Work email</FieldLabel>
99
+ <Input type="email" placeholder="name@company.com" />
100
+ </Field>
101
+ <div className="flex justify-end gap-2">
102
+ <PopoverClose render={<Button variant="ghost" size="sm" />}>Cancel</PopoverClose>
103
+ <PopoverClose render={<Button size="sm" />}>Send invite</PopoverClose>
104
+ </div>
105
+ </PopoverContent>
106
+ </Popover>
107
+ );
108
+ }
109
+ ```
110
+
111
+ ### Open on hover
112
+
113
+ `openOnHover` on the trigger: hover intent as well as click.
114
+
115
+ ```tsx
116
+ import { Button, Popover, PopoverContent, PopoverDescription, PopoverTrigger } from "@zonsh/ui";
117
+
118
+ export function OpenOnHover() {
119
+ return (
120
+ <Popover>
121
+ <PopoverTrigger openOnHover delay={200} render={<Button variant="ghost" />}>
122
+ Returns
123
+ </PopoverTrigger>
124
+ <PopoverContent side="top">
125
+ <PopoverDescription>Send anything back within 30 days, in its original packaging.</PopoverDescription>
126
+ </PopoverContent>
127
+ </Popover>
128
+ );
129
+ }
130
+ ```
131
+
132
+ ## On phones
133
+
134
+ A popover is fine on a phone for what a glance takes in: a sentence, a link, a short list. It opens beside its trigger and keeps inside the screen, flipping when there is no room. A popover that holds a form, a long list or anything a thumb must work through is cramped there: open a [`Drawer`](drawer.md) (`side="bottom"`) on phones instead — `FilterBar` does that with its editors (`sheet`), and a `Select` opens the platform's own picker with `native="touch"`. Don't open a popover on hover alone on a touch screen; give it a trigger that a tap opens.
135
+
136
+ ## Props
137
+
138
+ | Prop | Type | Default |
139
+ | ---------------------------- | -------------------------------------------------------------------------- | ---------- |
140
+ | `PopoverContent.side` | `"top" \| "right" \| "bottom" \| "left" \| "inline-start" \| "inline-end"` | `"bottom"` |
141
+ | `PopoverContent.align` | `"start" \| "center" \| "end"` | `"center"` |
142
+ | `PopoverContent.sideOffset` | `number \| OffsetFunction` | `8` |
143
+ | `PopoverContent.alignOffset` | `number \| OffsetFunction` | `0` |
144
+ | `PopoverContent.arrow` | `boolean` | `false` |
145
+ | `PopoverContent.positioner` | other `Popover.Positioner` props (`collisionPadding`, `anchor`, `sticky`) | — |
146
+ | `PopoverContent.portal` | `Popover.Portal` props | — |
147
+ | `PopoverTrigger.openOnHover` | `boolean`, with `delay` / `closeDelay` | `false` |
148
+
149
+ `Popover` is Base UI `Popover.Root` (`open`, `onOpenChange`, `modal`, `handle` …). `PopoverContent` renders Portal → Positioner → Popup and forwards Popup props. It is 288px wide (never wider than the room); override with `className="w-80"`.
150
+
151
+ ## Brand rules
152
+
153
+ - **Do** keep it to a title, a sentence or two and at most two small actions.
154
+ - **Do** use `PopoverClose` with `Button size="sm"` for actions.
155
+ - **Don't** change the radius or swap `material-menu` for a flat fill.
156
+ - **Don't** open a popover from a popover.
157
+
158
+ ## Accessibility
159
+
160
+ - The trigger gets `aria-expanded` and `aria-controls`; `PopoverTitle` and `PopoverDescription` label and describe the popup.
161
+ - Focus moves into the popup if it has focusable content and returns to the trigger on close. Outside clicks close it.
162
+ - Hover-opened popovers still open on click and keyboard; never make hover the only way in.
163
+
164
+ ### Keyboard
165
+
166
+ | Key | What it does |
167
+ | --------------- | ------------------------------------------------------------------------------------ |
168
+ | Enter / Space | Opens or closes the popover from its trigger |
169
+ | Tab / Shift+Tab | Moves through the popup's controls; tabbing past the last one closes it and moves on |
170
+ | Escape | Closes the popover and returns focus to the trigger |
171
+
172
+ ---
173
+
174
+ - Import: `import { Popover, PopoverTrigger, PopoverContent, PopoverTitle, PopoverDescription, PopoverClose } from "@zonsh/ui"`
175
+ - Source: `packages/ui/src/components/popover.tsx`
176
+ - Primitive: `@base-ui/react/popover` (Base UI docs: `node_modules/@base-ui/react/docs/react/components/popover.md`)
@@ -0,0 +1,193 @@
1
+ # Preview Card
2
+
3
+ ```tsx
4
+ import { PreviewCard, PreviewCardContent, PreviewCardTrigger } from "@zonsh/ui";
5
+
6
+ /** Where this docs site is served: /ui/ on zon.sh. */
7
+ const SITE = import.meta.env.BASE_URL;
8
+
9
+ /*
10
+ * A live thumbnail of another page of this docs site: the route is loaded in an iframe at a
11
+ * 1280 × 800 desktop viewport and scaled to a quarter, so the card shows the real page, not a
12
+ * drawing of it. The iframe is inert (no pointer, no focus, hidden from assistive tech) — the
13
+ * link itself is the way in. Only mounted while the card is open, and lazy on top of that.
14
+ */
15
+ function PagePreview({
16
+ href,
17
+ title,
18
+ path,
19
+ children,
20
+ }: {
21
+ href: string;
22
+ title: string;
23
+ path: string;
24
+ children: React.ReactNode;
25
+ }) {
26
+ return (
27
+ <PreviewCard>
28
+ <PreviewCardTrigger href={href} className="link">
29
+ {children}
30
+ </PreviewCardTrigger>
31
+ <PreviewCardContent className="gap-0 overflow-hidden p-0">
32
+ <div
33
+ inert
34
+ className="relative h-[200px] w-full overflow-hidden border-b border-field-edge bg-background"
35
+ >
36
+ {/* Sits behind the iframe until the page paints its own background over it. */}
37
+ <span className="absolute inset-0 flex items-center justify-center eyebrow">Loading preview…</span>
38
+ <iframe
39
+ src={href}
40
+ title={`Preview of the ${title} page`}
41
+ loading="lazy"
42
+ tabIndex={-1}
43
+ className="pointer-events-none absolute top-0 left-0 h-[800px] w-[1280px] origin-top-left scale-25 border-0"
44
+ />
45
+ </div>
46
+ <div className="flex flex-col gap-1 p-4">
47
+ <span className="eyebrow">{path}</span>
48
+ <p className="m-0 font-heading text-xl leading-tight font-light text-foreground">{title}</p>
49
+ </div>
50
+ </PreviewCardContent>
51
+ </PreviewCard>
52
+ );
53
+ }
54
+
55
+ export function Basic() {
56
+ return (
57
+ <p className="m-0 max-w-md text-[17px] leading-relaxed text-foreground-soft">
58
+ Every colour in the library comes from the{" "}
59
+ <PagePreview href={`${SITE}tokens`} title="Tokens" path="Foundations · Tokens">
60
+ design tokens
61
+ </PagePreview>
62
+ , and every action starts from the{" "}
63
+ <PagePreview href={`${SITE}components/button`} title="Button" path="Components · Button">
64
+ Button
65
+ </PagePreview>
66
+ .
67
+ </p>
68
+ );
69
+ }
70
+ ```
71
+
72
+ Shows what is behind a link — a guide, a person, a docs page — when the reader hovers or focuses it; above, a thumbnail of the real page over its path and title. It is the popover surface at 320px wide, opening after 600ms and lingering 300ms so the pointer can travel into it.
73
+
74
+ ## Usage
75
+
76
+ ```tsx
77
+ import { PreviewCard, PreviewCardContent, PreviewCardTrigger } from "@zonsh/ui";
78
+
79
+ <PreviewCard>
80
+ <PreviewCardTrigger href="/guides/review" className="link">
81
+ editorial review
82
+ </PreviewCardTrigger>
83
+ <PreviewCardContent>…</PreviewCardContent>
84
+ </PreviewCard>;
85
+ ```
86
+
87
+ The props you'll reach for: `href` on the trigger (a real link; give it the `link` utility), `delay`, and `side` on the content.
88
+
89
+ ## When to use
90
+
91
+ - Inline links in prose where a glance saves a click: a term, a related page, a person.
92
+ - Not for actions, forms or anything the reader must see — on touch it never opens.
93
+ - A panel the reader acts in is a `Popover` (`openOnHover` to also open on hover): a button that opens on click and takes focus.
94
+
95
+ ## Examples
96
+
97
+ ### Summary
98
+
99
+ The text version: an eyebrow, a Licht title and one sentence.
100
+
101
+ ```tsx
102
+ import { PreviewCard, PreviewCardContent, PreviewCardTrigger } from "@zonsh/ui";
103
+
104
+ export function Summary() {
105
+ return (
106
+ <p className="m-0 max-w-md text-[17px] leading-relaxed text-foreground-soft">
107
+ Every article goes through an{" "}
108
+ <PreviewCard>
109
+ <PreviewCardTrigger href="#review" className="link">
110
+ editorial review
111
+ </PreviewCardTrigger>
112
+ <PreviewCardContent>
113
+ <span className="eyebrow">Guide · 03</span>
114
+ <p className="m-0 font-heading text-xl leading-tight font-light text-foreground">
115
+ Editorial review
116
+ </p>
117
+ <p className="m-0 text-[13px] leading-normal text-muted-foreground">
118
+ A second reader checks facts, names and links, and flags anything that reads unclearly.
119
+ </p>
120
+ </PreviewCardContent>
121
+ </PreviewCard>{" "}
122
+ before it is published.
123
+ </p>
124
+ );
125
+ }
126
+ ```
127
+
128
+ ### With arrow
129
+
130
+ ```tsx
131
+ import { PreviewCard, PreviewCardContent, PreviewCardTrigger } from "@zonsh/ui";
132
+
133
+ export function WithArrow() {
134
+ return (
135
+ <PreviewCard>
136
+ <PreviewCardTrigger href="#shortcuts" className="text-[15px] link">
137
+ Keyboard shortcuts
138
+ </PreviewCardTrigger>
139
+ <PreviewCardContent side="top" arrow className="w-72">
140
+ <p className="m-0 text-[13px] leading-normal text-muted-foreground">
141
+ Press ? anywhere in the editor to see every shortcut, grouped by what it does.
142
+ </p>
143
+ </PreviewCardContent>
144
+ </PreviewCard>
145
+ );
146
+ }
147
+ ```
148
+
149
+ ## Page thumbnails
150
+
151
+ The base demo builds the thumbnail: an `iframe` of the page in `PreviewCardContent` (`className="gap-0 overflow-hidden p-0"`), rendered at `w-[1280px] h-[800px]` and scaled `origin-top-left scale-25` into a 200px frame. Make the frame `inert`; give the iframe `pointer-events-none`, `tabIndex={-1}`, `loading="lazy"` and a `title`. It loads on first hover; a mono "Loading preview…" label behind it covers the wait. Frame same-origin pages only; for other sites use a screenshot `<img>`.
152
+
153
+ ## Props
154
+
155
+ | Prop | Type | Default |
156
+ | ------------------------------------------ | ------------------------------------------ | ---------- |
157
+ | `PreviewCardTrigger.href` | `string` — it is a real link | — |
158
+ | `PreviewCardTrigger.delay` | `number` (ms) | `600` |
159
+ | `PreviewCardTrigger.closeDelay` | `number` (ms) | `300` |
160
+ | `PreviewCardContent.side` | `"top" \| "right" \| "bottom" \| "left" …` | `"bottom"` |
161
+ | `PreviewCardContent.align` | `"start" \| "center" \| "end"` | `"center"` |
162
+ | `PreviewCardContent.sideOffset` | `number` | `8` |
163
+ | `PreviewCardContent.arrow` | `boolean` | `false` |
164
+ | `PreviewCardContent.positioner` / `portal` | Base UI positioner / portal props | — |
165
+
166
+ `PreviewCard` is Base UI `PreviewCard.Root` (`open`, `onOpenChange`, `handle`). The trigger is unstyled.
167
+
168
+ ## Brand rules
169
+
170
+ - **Do** keep it a preview: an eyebrow, a title, a sentence, maybe a page thumbnail.
171
+ - **Do** make the link meaningful on its own.
172
+ - **Don't** put buttons or forms inside it.
173
+ - **Don't** use it on navigation links, where it would fire constantly.
174
+
175
+ ## Accessibility
176
+
177
+ - Opens on hover and on keyboard focus of the link.
178
+ - A thumbnail is decorative: its `inert` frame is never focused or read out; the title under it names the page.
179
+ - The content is not announced with the link — never put essential information only here.
180
+
181
+ ### Keyboard
182
+
183
+ | Key | What it does |
184
+ | ------ | ----------------------------------------------------------------------------- |
185
+ | Tab | Focusing the link opens the card after its delay; moving focus away closes it |
186
+ | Enter | Follows the link |
187
+ | Escape | Closes the card, or cancels one still waiting to open |
188
+
189
+ ---
190
+
191
+ - Import: `import { PreviewCard, PreviewCardTrigger, PreviewCardContent } from "@zonsh/ui"`
192
+ - Source: `packages/ui/src/components/preview-card.tsx`
193
+ - Primitive: `@base-ui/react/preview-card` (Base UI docs: `node_modules/@base-ui/react/docs/react/components/preview-card.md`)