@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.
- package/CHANGELOG.md +639 -0
- package/README.md +49 -21
- package/dist/brand.d.ts +3 -0
- package/dist/brand.js +7 -0
- package/dist/components/_breadcrumb-more.d.ts +6 -0
- package/dist/components/_breadcrumb-more.js +5 -0
- package/dist/components/_drawing-svg.d.ts +11 -0
- package/dist/components/_drawing-svg.js +30 -0
- package/dist/components/_media.d.ts +159 -0
- package/dist/components/_media.js +266 -0
- package/dist/components/_overlay.d.ts +8 -5
- package/dist/components/_overlay.js +11 -6
- package/dist/components/_scheduler-calendar.d.ts +71 -0
- package/dist/components/_scheduler-calendar.js +940 -0
- package/dist/components/_scheduler-editor.d.ts +29 -0
- package/dist/components/_scheduler-editor.js +111 -0
- package/dist/components/_scheduler-menu.d.ts +16 -0
- package/dist/components/_scheduler-menu.js +18 -0
- package/dist/components/_scheduler-parts.d.ts +164 -0
- package/dist/components/_scheduler-parts.js +327 -0
- package/dist/components/_suggest-list.d.ts +142 -0
- package/dist/components/_suggest-list.js +159 -0
- package/dist/components/_toolbar-more.d.ts +24 -0
- package/dist/components/_toolbar-more.js +25 -0
- package/dist/components/accordion.d.ts +1 -1
- package/dist/components/accordion.js +7 -7
- package/dist/components/action-sheet.d.ts +88 -0
- package/dist/components/action-sheet.js +124 -0
- package/dist/components/alert-dialog.js +3 -1
- package/dist/components/alert.d.ts +11 -18
- package/dist/components/alert.js +9 -6
- package/dist/components/app-bar.d.ts +93 -0
- package/dist/components/app-bar.js +175 -0
- package/dist/components/ascii-field.js +2 -1
- package/dist/components/audio-player.d.ts +134 -0
- package/dist/components/audio-player.js +618 -0
- package/dist/components/avatar.d.ts +6 -6
- package/dist/components/avatar.js +13 -11
- package/dist/components/badge.d.ts +12 -12
- package/dist/components/badge.js +7 -5
- package/dist/components/bottom-nav.d.ts +53 -11
- package/dist/components/bottom-nav.js +389 -24
- package/dist/components/breadcrumb.d.ts +11 -2
- package/dist/components/breadcrumb.js +60 -6
- package/dist/components/button-group.js +5 -1
- package/dist/components/button.d.ts +23 -6
- package/dist/components/button.js +64 -8
- package/dist/components/calendar.js +8 -6
- package/dist/components/card.d.ts +10 -8
- package/dist/components/card.js +15 -14
- package/dist/components/carousel.d.ts +2 -2
- package/dist/components/carousel.js +21 -8
- package/dist/components/chart.d.ts +38 -1
- package/dist/components/chart.js +27 -5
- package/dist/components/checkbox.js +2 -2
- package/dist/components/code-block.d.ts +9 -2
- package/dist/components/code-block.js +26 -7
- package/dist/components/collapsible.js +4 -4
- package/dist/components/color-picker.d.ts +2 -2
- package/dist/components/color-picker.js +5 -5
- package/dist/components/combobox.d.ts +26 -7
- package/dist/components/combobox.js +32 -13
- package/dist/components/command.d.ts +29 -5
- package/dist/components/command.js +37 -12
- package/dist/components/context-menu.d.ts +5 -2
- package/dist/components/context-menu.js +24 -3
- package/dist/components/conversation.d.ts +1 -1
- package/dist/components/conversation.js +77 -16
- package/dist/components/copy-button.d.ts +1 -1
- package/dist/components/copy-button.js +8 -6
- package/dist/components/data-table.d.ts +6 -6
- package/dist/components/data-table.js +41 -15
- package/dist/components/date-picker.d.ts +31 -9
- package/dist/components/date-picker.js +100 -18
- package/dist/components/dialog.d.ts +17 -10
- package/dist/components/dialog.js +20 -13
- package/dist/components/drawer.d.ts +26 -8
- package/dist/components/drawer.js +75 -16
- package/dist/components/drawing.d.ts +25 -0
- package/dist/components/drawing.js +32 -0
- package/dist/components/empty.js +2 -2
- package/dist/components/feature-list.d.ts +65 -13
- package/dist/components/feature-list.js +116 -15
- package/dist/components/field.js +2 -2
- package/dist/components/file-drop.d.ts +9 -7
- package/dist/components/file-drop.js +8 -43
- package/dist/components/filter-bar.d.ts +10 -9
- package/dist/components/filter-bar.js +42 -25
- package/dist/components/graph.d.ts +19 -3
- package/dist/components/graph.js +190 -28
- package/dist/components/illustration.js +53 -31
- package/dist/components/input-group.d.ts +6 -11
- package/dist/components/input-group.js +21 -19
- package/dist/components/input.d.ts +2 -2
- package/dist/components/input.js +3 -3
- package/dist/components/item.d.ts +9 -6
- package/dist/components/item.js +13 -8
- package/dist/components/kbd.d.ts +1 -1
- package/dist/components/kbd.js +1 -1
- package/dist/components/layout.d.ts +2 -1
- package/dist/components/layout.js +55 -11
- package/dist/components/lightbox.d.ts +76 -9
- package/dist/components/lightbox.js +354 -48
- package/dist/components/locale.d.ts +6 -6
- package/dist/components/logo.d.ts +21 -1
- package/dist/components/logo.js +32 -2
- package/dist/components/markdown-editor.d.ts +275 -0
- package/dist/components/markdown-editor.js +831 -0
- package/dist/components/mentions.d.ts +153 -0
- package/dist/components/mentions.js +507 -0
- package/dist/components/menu.d.ts +2 -1
- package/dist/components/menu.js +5 -4
- package/dist/components/menubar.d.ts +23 -5
- package/dist/components/menubar.js +153 -31
- package/dist/components/message.d.ts +62 -11
- package/dist/components/message.js +51 -14
- package/dist/components/meter.js +1 -1
- package/dist/components/money-input.d.ts +1 -1
- package/dist/components/money-input.js +1 -1
- package/dist/components/native-select.d.ts +2 -2
- package/dist/components/native-select.js +4 -4
- package/dist/components/navigation-menu.d.ts +3 -1
- package/dist/components/navigation-menu.js +23 -10
- package/dist/components/number-field.d.ts +2 -9
- package/dist/components/number-field.js +90 -26
- package/dist/components/number-roll.d.ts +26 -0
- package/dist/components/number-roll.js +81 -0
- package/dist/components/otp-field.d.ts +1 -1
- package/dist/components/otp-field.js +24 -3
- package/dist/components/pagination.d.ts +11 -3
- package/dist/components/pagination.js +59 -13
- package/dist/components/pdf-viewer.d.ts +1 -1
- package/dist/components/pdf-viewer.js +8 -8
- package/dist/components/phone-input.d.ts +1 -1
- package/dist/components/phone-input.js +2 -2
- package/dist/components/popover.js +5 -3
- package/dist/components/preview-card.d.ts +37 -2
- package/dist/components/preview-card.js +226 -2
- package/dist/components/progress.js +1 -1
- package/dist/components/prompt-input.d.ts +1 -1
- package/dist/components/prompt-input.js +35 -17
- package/dist/components/pull-to-refresh.d.ts +50 -0
- package/dist/components/pull-to-refresh.js +189 -0
- package/dist/components/quote.d.ts +6 -1
- package/dist/components/quote.js +3 -2
- package/dist/components/radio-group.js +8 -3
- package/dist/components/rating.d.ts +4 -1
- package/dist/components/rating.js +131 -10
- package/dist/components/reasoning.d.ts +1 -1
- package/dist/components/reasoning.js +7 -3
- package/dist/components/resizable.d.ts +1 -1
- package/dist/components/resizable.js +2 -2
- package/dist/components/response.d.ts +4 -3
- package/dist/components/response.js +39 -15
- package/dist/components/scheduler.d.ts +352 -0
- package/dist/components/scheduler.js +1717 -0
- package/dist/components/scroll-area.js +1 -1
- package/dist/components/select.d.ts +17 -4
- package/dist/components/select.js +140 -9
- package/dist/components/separator.d.ts +1 -1
- package/dist/components/separator.js +3 -3
- package/dist/components/sidebar.d.ts +44 -3
- package/dist/components/sidebar.js +90 -31
- package/dist/components/site-header.d.ts +18 -13
- package/dist/components/site-header.js +26 -9
- package/dist/components/skeleton.d.ts +18 -8
- package/dist/components/skeleton.js +23 -8
- package/dist/components/slider.js +2 -2
- package/dist/components/sortable.d.ts +55 -4
- package/dist/components/sortable.js +187 -94
- package/dist/components/sources.d.ts +1 -1
- package/dist/components/sources.js +2 -2
- package/dist/components/spinner.d.ts +4 -4
- package/dist/components/spinner.js +4 -4
- package/dist/components/stat.d.ts +21 -4
- package/dist/components/stat.js +17 -8
- package/dist/components/stepper.d.ts +1 -1
- package/dist/components/stepper.js +8 -7
- package/dist/components/suggestions.d.ts +11 -3
- package/dist/components/suggestions.js +10 -4
- package/dist/components/swipe-actions.d.ts +66 -0
- package/dist/components/swipe-actions.js +292 -0
- package/dist/components/switch.js +1 -1
- package/dist/components/table.d.ts +13 -7
- package/dist/components/table.js +124 -23
- package/dist/components/tabs.js +15 -8
- package/dist/components/tag.d.ts +19 -20
- package/dist/components/tag.js +9 -5
- package/dist/components/tags-input.d.ts +2 -7
- package/dist/components/tags-input.js +11 -8
- package/dist/components/textarea.d.ts +3 -2
- package/dist/components/textarea.js +4 -3
- package/dist/components/theme.d.ts +50 -7
- package/dist/components/theme.js +168 -12
- package/dist/components/time-field.d.ts +6 -10
- package/dist/components/time-field.js +19 -9
- package/dist/components/timeline.d.ts +19 -3
- package/dist/components/timeline.js +21 -9
- package/dist/components/tippy.d.ts +17 -1
- package/dist/components/tippy.js +95 -15
- package/dist/components/toast.d.ts +2 -7
- package/dist/components/toast.js +12 -8
- package/dist/components/toggle-group.d.ts +7 -1
- package/dist/components/toggle-group.js +17 -5
- package/dist/components/toggle.d.ts +2 -2
- package/dist/components/toggle.js +3 -2
- package/dist/components/tool-call.d.ts +1 -1
- package/dist/components/tool-call.js +8 -3
- package/dist/components/toolbar.d.ts +57 -4
- package/dist/components/toolbar.js +219 -16
- package/dist/components/tooltip.d.ts +5 -3
- package/dist/components/tooltip.js +14 -6
- package/dist/components/tour.d.ts +1 -1
- package/dist/components/tour.js +70 -24
- package/dist/components/tree.js +33 -10
- package/dist/components/typography.d.ts +31 -8
- package/dist/components/typography.js +21 -10
- package/dist/components/video-player.d.ts +7 -2
- package/dist/components/video-player.js +182 -225
- package/dist/index.d.ts +99 -92
- package/dist/index.js +99 -92
- package/dist/lib/calendar.d.ts +153 -0
- package/dist/lib/calendar.js +312 -0
- package/dist/lib/cn.d.ts +3 -1
- package/dist/lib/cn.js +5 -0
- package/dist/lib/code-highlight.d.ts +14 -0
- package/dist/lib/code-highlight.js +81 -18
- package/dist/lib/drag.d.ts +39 -0
- package/dist/lib/drag.js +96 -0
- package/dist/lib/editorial-assets.js +16 -8
- package/dist/lib/figure/figures/automation.js +25 -6
- package/dist/lib/figure/figures/bar-chart.js +6 -1
- package/dist/lib/figure/figures/brackets-classic.js +4 -1
- package/dist/lib/figure/figures/city.js +12 -2
- package/dist/lib/figure/figures/conveyor.js +17 -4
- package/dist/lib/figure/figures/database.js +5 -2
- package/dist/lib/figure/figures/documents.js +11 -3
- package/dist/lib/figure/figures/inbox.js +5 -2
- package/dist/lib/figure/figures/laptop.js +3 -1
- package/dist/lib/figure/figures/pipeline.js +45 -10
- package/dist/lib/figure/figures/platform.js +62 -7
- package/dist/lib/figure/figures/server.js +21 -5
- package/dist/lib/figure/figures/spreadsheet.js +29 -5
- package/dist/lib/figure/kernel.d.ts +4 -2
- package/dist/lib/figure/kernel.js +10 -5
- package/dist/lib/figure/parts.js +6 -2
- package/dist/lib/files.d.ts +31 -0
- package/dist/lib/files.js +60 -0
- package/dist/lib/gesture.d.ts +70 -0
- package/dist/lib/gesture.js +141 -0
- package/dist/lib/glide.d.ts +10 -4
- package/dist/lib/glide.js +14 -5
- package/dist/lib/icons.d.ts +1 -0
- package/dist/lib/icons.js +6 -0
- package/dist/lib/illustration-library.js +1 -6
- package/dist/lib/markdown-edit.d.ts +112 -0
- package/dist/lib/markdown-edit.js +557 -0
- package/dist/lib/markdown-rich-editor.d.ts +188 -0
- package/dist/lib/markdown-rich-editor.js +1153 -0
- package/dist/lib/markdown-rich.d.ts +63 -0
- package/dist/lib/markdown-rich.js +534 -0
- package/dist/lib/mentions.d.ts +100 -0
- package/dist/lib/mentions.js +246 -0
- package/dist/lib/motion.d.ts +18 -0
- package/dist/lib/motion.js +43 -5
- package/dist/lib/number-roll.d.ts +89 -0
- package/dist/lib/number-roll.js +391 -0
- package/dist/lib/platform.d.ts +6 -0
- package/dist/lib/platform.js +14 -0
- package/dist/lib/portal-container.d.ts +9 -0
- package/dist/lib/portal-container.js +10 -0
- package/dist/lib/press.d.ts +5 -0
- package/dist/lib/press.js +186 -0
- package/dist/lib/scheduler.d.ts +128 -0
- package/dist/lib/scheduler.js +272 -0
- package/dist/lib/scroll-edges.d.ts +9 -0
- package/dist/lib/scroll-edges.js +50 -0
- package/dist/lib/table-fit.d.ts +4 -3
- package/dist/lib/table-fit.js +92 -25
- package/dist/lib/theme-preset.d.ts +267 -0
- package/dist/lib/theme-preset.js +1046 -0
- package/dist/lib/theme-script.d.ts +23 -3
- package/dist/lib/theme-script.js +17 -5
- package/dist/lib/tippy/sprite.d.ts +36 -4
- package/dist/lib/tippy/sprite.js +188 -15
- package/dist/lib/tone.d.ts +4 -0
- package/dist/lib/tone.js +1 -0
- package/dist/messages/de.d.ts +3 -3
- package/dist/messages/de.js +274 -3
- package/dist/skills/zon-ui/SKILL.md +279 -0
- package/dist/skills/zon-ui/references/authoring.md +265 -0
- package/dist/skills/zon-ui/references/brand.md +416 -0
- package/dist/skills/zon-ui/references/components/accordion.md +199 -0
- package/dist/skills/zon-ui/references/components/action-sheet.md +268 -0
- package/dist/skills/zon-ui/references/components/alert-dialog.md +276 -0
- package/dist/skills/zon-ui/references/components/alert.md +167 -0
- package/dist/skills/zon-ui/references/components/app-bar.md +307 -0
- package/dist/skills/zon-ui/references/components/ascii-field.md +121 -0
- package/dist/skills/zon-ui/references/components/aspect-ratio.md +112 -0
- package/dist/skills/zon-ui/references/components/audio-player.md +231 -0
- package/dist/skills/zon-ui/references/components/avatar.md +98 -0
- package/dist/skills/zon-ui/references/components/badge.md +227 -0
- package/dist/skills/zon-ui/references/components/bottom-nav.md +709 -0
- package/dist/skills/zon-ui/references/components/breadcrumb.md +143 -0
- package/dist/skills/zon-ui/references/components/button-group.md +216 -0
- package/dist/skills/zon-ui/references/components/button.md +309 -0
- package/dist/skills/zon-ui/references/components/calendar.md +296 -0
- package/dist/skills/zon-ui/references/components/card.md +158 -0
- package/dist/skills/zon-ui/references/components/carousel.md +297 -0
- package/dist/skills/zon-ui/references/components/chart.md +739 -0
- package/dist/skills/zon-ui/references/components/chat.md +417 -0
- package/dist/skills/zon-ui/references/components/checkbox.md +219 -0
- package/dist/skills/zon-ui/references/components/code-block.md +143 -0
- package/dist/skills/zon-ui/references/components/code-highlight.md +118 -0
- package/dist/skills/zon-ui/references/components/collapsible.md +146 -0
- package/dist/skills/zon-ui/references/components/color-picker.md +200 -0
- package/dist/skills/zon-ui/references/components/combobox.md +455 -0
- package/dist/skills/zon-ui/references/components/command.md +326 -0
- package/dist/skills/zon-ui/references/components/contact-form.md +562 -0
- package/dist/skills/zon-ui/references/components/context-menu.md +159 -0
- package/dist/skills/zon-ui/references/components/conversation.md +146 -0
- package/dist/skills/zon-ui/references/components/copy-button.md +162 -0
- package/dist/skills/zon-ui/references/components/crm.md +1022 -0
- package/dist/skills/zon-ui/references/components/dashboard.md +612 -0
- package/dist/skills/zon-ui/references/components/data-table.md +776 -0
- package/dist/skills/zon-ui/references/components/date-picker.md +444 -0
- package/dist/skills/zon-ui/references/components/dialog.md +335 -0
- package/dist/skills/zon-ui/references/components/direction.md +165 -0
- package/dist/skills/zon-ui/references/components/drawer.md +276 -0
- package/dist/skills/zon-ui/references/components/drawing.md +94 -0
- package/dist/skills/zon-ui/references/components/empty.md +225 -0
- package/dist/skills/zon-ui/references/components/feature-list.md +412 -0
- package/dist/skills/zon-ui/references/components/field.md +209 -0
- package/dist/skills/zon-ui/references/components/file-drop.md +234 -0
- package/dist/skills/zon-ui/references/components/filter-bar.md +485 -0
- package/dist/skills/zon-ui/references/components/form.md +970 -0
- package/dist/skills/zon-ui/references/components/graph.md +339 -0
- package/dist/skills/zon-ui/references/components/illustration.md +497 -0
- package/dist/skills/zon-ui/references/components/inbox.md +263 -0
- package/dist/skills/zon-ui/references/components/input-group.md +339 -0
- package/dist/skills/zon-ui/references/components/input.md +189 -0
- package/dist/skills/zon-ui/references/components/item.md +277 -0
- package/dist/skills/zon-ui/references/components/kanban.md +626 -0
- package/dist/skills/zon-ui/references/components/kbd.md +116 -0
- package/dist/skills/zon-ui/references/components/label.md +104 -0
- package/dist/skills/zon-ui/references/components/layout.md +291 -0
- package/dist/skills/zon-ui/references/components/lightbox.md +235 -0
- package/dist/skills/zon-ui/references/components/locale.md +279 -0
- package/dist/skills/zon-ui/references/components/logo.md +257 -0
- package/dist/skills/zon-ui/references/components/markdown-editor.md +558 -0
- package/dist/skills/zon-ui/references/components/mentions.md +512 -0
- package/dist/skills/zon-ui/references/components/menu.md +218 -0
- package/dist/skills/zon-ui/references/components/menubar.md +292 -0
- package/dist/skills/zon-ui/references/components/message.md +243 -0
- package/dist/skills/zon-ui/references/components/meter.md +105 -0
- package/dist/skills/zon-ui/references/components/money-input.md +333 -0
- package/dist/skills/zon-ui/references/components/native-select.md +197 -0
- package/dist/skills/zon-ui/references/components/navigation-menu.md +253 -0
- package/dist/skills/zon-ui/references/components/number-field.md +210 -0
- package/dist/skills/zon-ui/references/components/number-roll.md +175 -0
- package/dist/skills/zon-ui/references/components/onboarding.md +896 -0
- package/dist/skills/zon-ui/references/components/otp-field.md +166 -0
- package/dist/skills/zon-ui/references/components/pagination.md +109 -0
- package/dist/skills/zon-ui/references/components/pdf-viewer.md +177 -0
- package/dist/skills/zon-ui/references/components/phone-input.md +252 -0
- package/dist/skills/zon-ui/references/components/popover.md +176 -0
- package/dist/skills/zon-ui/references/components/preview-card.md +193 -0
- package/dist/skills/zon-ui/references/components/pricing.md +724 -0
- package/dist/skills/zon-ui/references/components/progress.md +92 -0
- package/dist/skills/zon-ui/references/components/prompt-input.md +307 -0
- package/dist/skills/zon-ui/references/components/pull-to-refresh.md +188 -0
- package/dist/skills/zon-ui/references/components/quote.md +115 -0
- package/dist/skills/zon-ui/references/components/radio-group.md +215 -0
- package/dist/skills/zon-ui/references/components/rating.md +260 -0
- package/dist/skills/zon-ui/references/components/reasoning.md +102 -0
- package/dist/skills/zon-ui/references/components/resizable.md +213 -0
- package/dist/skills/zon-ui/references/components/response.md +170 -0
- package/dist/skills/zon-ui/references/components/scheduler.md +732 -0
- package/dist/skills/zon-ui/references/components/scroll-area.md +122 -0
- package/dist/skills/zon-ui/references/components/select.md +351 -0
- package/dist/skills/zon-ui/references/components/separator.md +103 -0
- package/dist/skills/zon-ui/references/components/settings.md +793 -0
- package/dist/skills/zon-ui/references/components/shop.md +1715 -0
- package/dist/skills/zon-ui/references/components/sidebar.md +813 -0
- package/dist/skills/zon-ui/references/components/sign-in.md +1639 -0
- package/dist/skills/zon-ui/references/components/site-header.md +303 -0
- package/dist/skills/zon-ui/references/components/skeleton.md +256 -0
- package/dist/skills/zon-ui/references/components/slider.md +172 -0
- package/dist/skills/zon-ui/references/components/sortable.md +405 -0
- package/dist/skills/zon-ui/references/components/sources.md +106 -0
- package/dist/skills/zon-ui/references/components/spinner.md +222 -0
- package/dist/skills/zon-ui/references/components/stat.md +267 -0
- package/dist/skills/zon-ui/references/components/stepper.md +285 -0
- package/dist/skills/zon-ui/references/components/suggestions.md +146 -0
- package/dist/skills/zon-ui/references/components/swipe-actions.md +344 -0
- package/dist/skills/zon-ui/references/components/switch.md +160 -0
- package/dist/skills/zon-ui/references/components/table.md +999 -0
- package/dist/skills/zon-ui/references/components/tabs.md +258 -0
- package/dist/skills/zon-ui/references/components/tag.md +115 -0
- package/dist/skills/zon-ui/references/components/tags-input.md +216 -0
- package/dist/skills/zon-ui/references/components/textarea.md +95 -0
- package/dist/skills/zon-ui/references/components/theme-editor.md +3940 -0
- package/dist/skills/zon-ui/references/components/theme.md +362 -0
- package/dist/skills/zon-ui/references/components/time-field.md +222 -0
- package/dist/skills/zon-ui/references/components/timeline.md +285 -0
- package/dist/skills/zon-ui/references/components/tippy.md +243 -0
- package/dist/skills/zon-ui/references/components/toast.md +220 -0
- package/dist/skills/zon-ui/references/components/toggle-group.md +261 -0
- package/dist/skills/zon-ui/references/components/toggle.md +167 -0
- package/dist/skills/zon-ui/references/components/tool-call.md +146 -0
- package/dist/skills/zon-ui/references/components/toolbar.md +260 -0
- package/dist/skills/zon-ui/references/components/tooltip.md +172 -0
- package/dist/skills/zon-ui/references/components/tour.md +423 -0
- package/dist/skills/zon-ui/references/components/tree.md +481 -0
- package/dist/skills/zon-ui/references/components/typography.md +347 -0
- package/dist/skills/zon-ui/references/components/video-player.md +386 -0
- package/dist/skills/zon-ui/references/marketing.md +467 -0
- package/dist/skills/zon-ui/references/motion.md +455 -0
- package/dist/skills/zon-ui/references/recipes.md +1232 -0
- package/dist/skills/zon-ui/references/tokens.md +866 -0
- package/dist/sources/accordion.css +4 -0
- package/dist/sources/action-sheet.css +11 -0
- package/dist/sources/alert-dialog.css +6 -0
- package/dist/sources/alert.css +3 -0
- package/dist/sources/app-bar.css +14 -0
- package/dist/sources/ascii-field.css +3 -0
- package/dist/sources/aspect-ratio.css +3 -0
- package/dist/sources/audio-player.css +20 -0
- package/dist/sources/avatar.css +3 -0
- package/dist/sources/badge.css +3 -0
- package/dist/sources/bottom-nav.css +9 -0
- package/dist/sources/breadcrumb.css +14 -0
- package/dist/sources/button-group.css +3 -0
- package/dist/sources/button.css +9 -0
- package/dist/sources/calendar.css +13 -0
- package/dist/sources/card.css +3 -0
- package/dist/sources/carousel.css +11 -0
- package/dist/sources/chart.css +5 -0
- package/dist/sources/checkbox.css +6 -0
- package/dist/sources/code-block.css +13 -0
- package/dist/sources/collapsible.css +4 -0
- package/dist/sources/color-picker.css +13 -0
- package/dist/sources/combobox.css +13 -0
- package/dist/sources/command.css +13 -0
- package/dist/sources/context-menu.css +12 -0
- package/dist/sources/conversation.css +10 -0
- package/dist/sources/copy-button.css +10 -0
- package/dist/sources/data-table.css +27 -0
- package/dist/sources/date-picker.css +20 -0
- package/dist/sources/dialog.css +9 -0
- package/dist/sources/direction.css +2 -0
- package/dist/sources/drawer.css +9 -0
- package/dist/sources/drawing.css +5 -0
- package/dist/sources/empty.css +3 -0
- package/dist/sources/feature-list.css +4 -0
- package/dist/sources/field.css +4 -0
- package/dist/sources/file-drop.css +15 -0
- package/dist/sources/filter-bar.css +30 -0
- package/dist/sources/form.css +4 -0
- package/dist/sources/graph.css +19 -0
- package/dist/sources/illustration.css +28 -0
- package/dist/sources/input-group.css +7 -0
- package/dist/sources/input.css +3 -0
- package/dist/sources/item.css +4 -0
- package/dist/sources/kbd.css +5 -0
- package/dist/sources/label.css +3 -0
- package/dist/sources/layout.css +3 -0
- package/dist/sources/lightbox.css +33 -0
- package/dist/sources/locale.css +2 -0
- package/dist/sources/logo.css +4 -0
- package/dist/sources/markdown-editor.css +41 -0
- package/dist/sources/mentions.css +13 -0
- package/dist/sources/menu.css +11 -0
- package/dist/sources/menubar.css +14 -0
- package/dist/sources/message.css +16 -0
- package/dist/sources/meter.css +4 -0
- package/dist/sources/money-input.css +10 -0
- package/dist/sources/native-select.css +4 -0
- package/dist/sources/navigation-menu.css +8 -0
- package/dist/sources/number-field.css +8 -0
- package/dist/sources/number-roll.css +6 -0
- package/dist/sources/otp-field.css +5 -0
- package/dist/sources/pagination.css +11 -0
- package/dist/sources/pdf-viewer.css +30 -0
- package/dist/sources/phone-input.css +20 -0
- package/dist/sources/popover.css +7 -0
- package/dist/sources/preview-card.css +7 -0
- package/dist/sources/progress.css +4 -0
- package/dist/sources/prompt-input.css +15 -0
- package/dist/sources/pull-to-refresh.css +14 -0
- package/dist/sources/quote.css +3 -0
- package/dist/sources/radio-group.css +5 -0
- package/dist/sources/rating.css +6 -0
- package/dist/sources/reasoning.css +6 -0
- package/dist/sources/resizable.css +4 -0
- package/dist/sources/response.css +16 -0
- package/dist/sources/scheduler.css +44 -0
- package/dist/sources/scroll-area.css +3 -0
- package/dist/sources/select.css +12 -0
- package/dist/sources/separator.css +3 -0
- package/dist/sources/sidebar.css +19 -0
- package/dist/sources/site-header.css +15 -0
- package/dist/sources/skeleton.css +3 -0
- package/dist/sources/slider.css +6 -0
- package/dist/sources/sortable.css +12 -0
- package/dist/sources/sources.css +6 -0
- package/dist/sources/spinner.css +6 -0
- package/dist/sources/stat.css +9 -0
- package/dist/sources/stepper.css +6 -0
- package/dist/sources/suggestions.css +10 -0
- package/dist/sources/swipe-actions.css +20 -0
- package/dist/sources/switch.css +5 -0
- package/dist/sources/table.css +7 -0
- package/dist/sources/tabs.css +5 -0
- package/dist/sources/tag.css +3 -0
- package/dist/sources/tags-input.css +6 -0
- package/dist/sources/textarea.css +3 -0
- package/dist/sources/theme.css +13 -0
- package/dist/sources/time-field.css +7 -0
- package/dist/sources/timeline.css +7 -0
- package/dist/sources/tippy.css +6 -0
- package/dist/sources/toast.css +6 -0
- package/dist/sources/toggle-group.css +5 -0
- package/dist/sources/toggle.css +3 -0
- package/dist/sources/tool-call.css +16 -0
- package/dist/sources/toolbar.css +14 -0
- package/dist/sources/tooltip.css +6 -0
- package/dist/sources/tour.css +14 -0
- package/dist/sources/tree.css +6 -0
- package/dist/sources/typography.css +4 -0
- package/dist/sources/video-player.css +21 -0
- package/dist/styles/ai.css +3 -0
- package/dist/styles/brand.css +98 -0
- package/dist/styles/core.css +266 -0
- package/dist/styles/editor.css +3 -0
- package/dist/styles/expressive.css +75 -77
- package/dist/styles/fonts.css +61 -117
- package/dist/styles/graph.css +4 -0
- package/dist/styles/illustration.css +4 -0
- package/dist/styles/index.css +11 -193
- package/dist/styles/material.css +177 -31
- package/dist/styles/parts/ai.css +20 -14
- package/dist/styles/parts/brand.css +2 -2
- package/dist/styles/parts/controls.css +51 -38
- package/dist/styles/parts/data.css +43 -11
- package/dist/styles/parts/editor.css +372 -0
- package/dist/styles/parts/feedback.css +75 -15
- package/dist/styles/parts/foundations.css +12 -7
- package/dist/styles/parts/graph.css +25 -9
- package/dist/styles/parts/inputs.css +172 -9
- package/dist/styles/parts/isometric.css +6 -5
- package/dist/styles/parts/navigation.css +237 -25
- package/dist/styles/parts/overlays.css +110 -8
- package/dist/styles/parts/pdf.css +15 -9
- package/dist/styles/pdf.css +3 -0
- package/dist/styles/prose.css +3 -0
- package/dist/styles/tokens.css +105 -15
- package/dist/theme.d.ts +1 -0
- package/dist/theme.js +5 -0
- package/dist/vite.d.ts +48 -59
- package/dist/vite.js +54 -21
- package/package.json +69 -2
|
@@ -0,0 +1,279 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: zon-ui
|
|
3
|
+
description: Build interfaces with the zon design system (@zonsh/ui) — Base UI components in the zon material, monochrome tokens with status and category colours, Licht/Licht Sans/Licht Mono type, and brand rules. Use whenever a task creates or changes zon/ui, pages, landing pages, marketing sites, waitlists, shops, product pages, marketing sections, forms, dashboards, or anything that should look like zon.sh, or mentions @zonsh/ui, zon brand, Licht, or the brand room.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# zon/ui
|
|
7
|
+
|
|
8
|
+
The zon component library: React 19 + Base UI 1.x + Tailwind v4, styled in the
|
|
9
|
+
zon material (layered primary, raised secondary, recessed fields, hairline structure).
|
|
10
|
+
Version 0.6.0. 124 components.
|
|
11
|
+
|
|
12
|
+
> **Building a landing page, marketing site, waitlist, shop front or product page?** Read
|
|
13
|
+
> `references/marketing.md` first. It has the hero variants, a library of section patterns
|
|
14
|
+
> chosen by content, four footer patterns and the code for each — and it explains why a page
|
|
15
|
+
> should not copy zon.sh's outline (numbered sections, three icon columns, an FAQ accordion,
|
|
16
|
+
> the night footer) unless the content calls for it.
|
|
17
|
+
|
|
18
|
+
## Workflow
|
|
19
|
+
|
|
20
|
+
0. **Before the first screen:** ask about the look once for a new product: zon's default, a brand
|
|
21
|
+
colour, or a preset code (see "The look" under Setup). For a marketing page (landing page,
|
|
22
|
+
waitlist, shop, product or campaign page), start with `references/marketing.md`: write the
|
|
23
|
+
outline from the reader's questions, then pick a pattern per section.
|
|
24
|
+
1. **Find the component** in the index below. Prefer composing existing components.
|
|
25
|
+
2. **Read its reference** (`references/components/<name>.md`) before using it — it has the API,
|
|
26
|
+
working examples and the brand rules people break.
|
|
27
|
+
3. **Compose** with the material utilities and tokens (`references/tokens.md`). Never invent
|
|
28
|
+
colours, radii or heights.
|
|
29
|
+
4. For new brand compositions, read `references/brand.md` (the full brand guide); for anything
|
|
30
|
+
that moves, `references/motion.md`; for a marketing page, `references/marketing.md`. For a
|
|
31
|
+
common task (a form with server errors, a filtered table, a confirm dialog, a chat), start
|
|
32
|
+
from its recipe in `references/recipes.md`.
|
|
33
|
+
5. To add or change a library component, follow `references/authoring.md`.
|
|
34
|
+
6. Check: both themes, mobile + desktop, keyboard focus, reduced motion, honest copy.
|
|
35
|
+
|
|
36
|
+
## Core rules
|
|
37
|
+
|
|
38
|
+
1. **Monochrome surfaces, colour for meaning.** Use semantic tokens (`bg-background`, `text-foreground`, `text-muted-foreground`, `border-field-edge` …); surfaces, controls and type stay neutral, and the primary takes the theme's colour (grey in zon's own; see "The look"). Colour carries meaning in small marks — text, a dot, an icon, a segment, a 1px edge, a 10–20% tint: status (`--success`, `--warning`, `--info`, `--destructive`) or a category people must tell apart (`--tone-blue`, `-aqua`, `-violet`, `-magenta`, `-orange`, `-lime`). Never decoration, never a button, card or page coloured by hand; always with text or an icon; one meaning per colour.
|
|
39
|
+
2. **Three faces, three jobs.** Licht (`font-heading` / `display`, one weight, Light; never bold it) for headlines; Licht Sans (`font-body`) for reading, controls and navigation; Licht Mono (`font-mono` / `eyebrow`) for labels, numbers and indices. Mixed-case headlines; all caps only for short mono labels.
|
|
40
|
+
3. **Fixed geometry.** Heights 30 (dense) / 38 (default) / 46 (prominent) via the `size` prop. Radii: buttons 12, inputs 10, items 7, checkboxes 5, cards 20, regions 0. Never add a radius, a height, or `h-12` on a control.
|
|
41
|
+
4. **The material, never flat fills.** Interactive surfaces use `material-primary`, `material-raised`, `material-row`, `material-field`, `material-menu`. Enclosing surfaces use `surface-container` (square region) or `surface-card` (20px object).
|
|
42
|
+
5. **Hairlines before boxes; few cards.** Group with a hairline rule, whitespace and type hierarchy: `Section`, `Separator`, `hairline`, `FeatureList`, a divided list of `Item`s, a two-column label / content row; a part of the page that needs a ground is a square `surface-container` region. A card is for a thing that can be picked up, moved or opened on its own — a quote, a product, a draggable deal, a dialog. Page sections, forms, pricing, settings and sign-in on a page are not cards (a form takes a card only when it is the whole screen on its own: sign-in or setup centred under the logo); never nest cards.
|
|
43
|
+
6. **One primary per view.** At most one primary in sight at a time: per screen, dialog or step, and per screenful of a long page. Every other action is `secondary`/`ghost`. On a marketing page the main action is primary where the reader acts on it; the same action asked again elsewhere is `secondary`, and a section that is its own task (the plans, a contact form) keeps its one primary a screenful away from the others. Primary labels name the outcome: "Save changes", "Create project", "Get started".
|
|
44
|
+
7. **Focus and motion.** 2px `--control-focus` outline, offset 0, never hidden; a focused text field (or an open select) takes a softer edge instead, halfway to `--control-focus`, with no ring. Motion follows `docs/motion.md`: the motion tokens (`--ease`, `--ease-glide`, `--ease-move`, `--duration` 150ms), nothing the keyboard does animates (bar the digit roll and the OTP ring), leaving is quicker than arriving, within 300ms. Reduced motion keeps fades and drops movement; keep mobile backdrops static.
|
|
45
|
+
8. **Honest copy.** Precise, warm, practical, written for the product at hand. Never invent metrics, savings, customers, testimonials, ratings, logos, awards or certifications. The rule is about inventing: content the person gives you, or that the project already has (its quotes, logos, figures, team), is kept as it is. Facts you can't know — how data is handled, privacy and security, prices, dates and delivery times, platforms and integrations, any number, and features beyond the brief (what follows plainly from the brief may be written as it is) — are written as marked placeholders to confirm, `<Mono className="text-warning">[To confirm: monthly price]</Mono>` in the sentence where the fact goes, and listed in your summary; never stated as fact.
|
|
46
|
+
9. **Use the library.** Import from `@zonsh/ui`, or from the subpath a component's doc names (`@zonsh/ui/chart`, `@zonsh/ui/data-table` …). Compose existing components before writing new markup; never recreate a control that exists.
|
|
47
|
+
10. **Custom popups on the desktop, the platform's picker on phones.** `Select`, `DatePicker` and `DateTimePicker` do this by default (`native="touch"`): on a phone a `NativeSelect` or a native date field, the custom popup elsewhere; never build your own switch. `native={false}` keeps the popup on phones, only for multiple choice, options with icons or descriptions. `NativeSelect` outright in plain forms.
|
|
48
|
+
11. **A placeholder is the size of its content.** A text `Skeleton` is one line tall: size it by the text's type (`text-sm`, `leading-snug`), never `h-*`. Media take the content's `aspect-*` and an explicit `shape` (`item`, `card`). Build loading states from the same wrappers (`Item`, `ItemTitle`, `CardTitle` …) and row count as the content, so nothing moves when it arrives.
|
|
49
|
+
12. **Size a dialog by its content.** `DialogContent size`: `sm` for one field or a short message, `default` for most tasks, `lg` for a table or a longer form, `xl` for side by side, `full` for a workspace; they grow on large screens. More than about four fields go in two columns once there is room (`DialogBody className="@container"`, fields in `grid gap-5 @md:grid-cols-2`). Confirmations are an `AlertDialog`, which stays small.
|
|
50
|
+
|
|
51
|
+
## Setup
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
pnpm add @zonsh/ui lucide-react
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
```css
|
|
58
|
+
/* app.css — Tailwind first, then the library */
|
|
59
|
+
@import "tailwindcss";
|
|
60
|
+
@import "@zonsh/ui/styles.css";
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
That is the whole setup. It is the design system, on a plain `--background` page. To give the page zon.sh's own look as well (still grain and a faint light from above on the page ground), add one line after it:
|
|
64
|
+
|
|
65
|
+
```css
|
|
66
|
+
@import "@zonsh/ui/brand.css";
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
The Licht fonts come with the stylesheet (from `licht`, a dependency): the bundler copies them into the build and serves them from your own origin. The build lists every cut (52 WOFF2 files; `LichtSerif-*` is Licht, the headline face), but a browser downloads only the cuts a page sets. No plugin, proxy or rewrite; an app set up before 0.6.0 removes `zonFonts()` (from `@zonsh/ui/vite`, now gone) and any `/licht/fonts` rewrite.
|
|
70
|
+
|
|
71
|
+
Next.js (App Router): the two imports above are all of `app/globals.css` (drop the template's styles and Geist fonts), and server components render the components directly: each is a client module already.
|
|
72
|
+
|
|
73
|
+
To load less CSS, import the core, the parts your components need, and in place of scanning the whole package the sources of the components you import. A component's sources name the files it is built from:
|
|
74
|
+
|
|
75
|
+
```css
|
|
76
|
+
@import "tailwindcss";
|
|
77
|
+
@import "@zonsh/ui/styles/core.css";
|
|
78
|
+
@import "@zonsh/ui/styles/prose.css"; /* only if you use them: prose, ai, graph, pdf, editor, illustration */
|
|
79
|
+
@import "@zonsh/ui/sources/button.css"; /* one per component you import, named after its file */
|
|
80
|
+
@import "@zonsh/ui/sources/table.css";
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The core holds the tokens, fonts, materials and every component's styles but those parts: `prose.css` (Prose, Code Block), `ai.css` (Prompt Input, Reasoning, Response, with `prose.css`), `graph.css` (Graph), `pdf.css` (PDF Viewer), `editor.css` (Markdown Editor) and `illustration.css` (Illustrations). `@zonsh/ui/brand.css` (zon.sh's page ground) goes after them, if you want it.
|
|
84
|
+
|
|
85
|
+
Dark mode: wrap the app in `ThemeProvider` and run the theme script first in `<head>`, so the first paint has the right scheme. Next.js: `<script dangerouslySetInnerHTML={{ __html: themeScript }} />` in the root layout's `<head>`, with `suppressHydrationWarning` on `<html>`. Vite: `zonThemeScript()` from `@zonsh/ui/vite` in the plugins injects it into `index.html` (the Theme page also prints the script to paste). Force a scheme locally with `.theme-dark`, `.theme-light` or `.theme-night`.
|
|
86
|
+
|
|
87
|
+
Older apps move up first, on a branch: Tailwind CSS 3 with `npx @tailwindcss/upgrade` (then `@tailwindcss/vite` or `@tailwindcss/postcss`, and drop `tailwindcss-animate`); React 18 and Next.js 14 together with `npx @next/codemod@canary upgrade latest` (on Vite, `react@19 react-dom@19 @types/react@19 @types/react-dom@19` in one install); packages that pin React 18 upgraded in the same install or removed. `lucide-react` 1.x has no brand icons (`Github` …): use the brand's own SVG. Replacing shadcn/ui, delete its `components/ui` files and `@radix-ui/*`, `cmdk`, `vaul`, `sonner`, `next-themes` once unused, and remove its colour variables (`--background`, `--primary`, `--radius` …) from the stylesheet: zon/ui's tokens share the names. Details: https://zon.sh/ui/get-started.
|
|
88
|
+
|
|
89
|
+
### The look
|
|
90
|
+
|
|
91
|
+
Every app on zon's default theme looks alike. Before building the first screen of a new product (unless the project already sets `preset` on its `ThemeProvider`), ask the person once, in plain words:
|
|
92
|
+
|
|
93
|
+
> How should it look? 1. zon's default: grey and quiet. 2. Your brand colour (a hex code or a colour name) and, if you like, warm or cool greys and round or square corners. 3. A preset code from https://zon.sh/ui/theme (it starts with Z1).
|
|
94
|
+
|
|
95
|
+
Then set it once, at the root:
|
|
96
|
+
|
|
97
|
+
- **Default:** `<ThemeProvider>` as it is.
|
|
98
|
+
- **A colour:** `<ThemeProvider preset={themePresetFromColor("#c2410c", { neutral: "warm", corners: "round" })}>`, from `@zonsh/ui`. `neutral` is `pure` (default), `warm`, `cool` or `tinted`; `corners` is `square`, `subtle`, `default` or `round`; `density` is `compact`, `default` or `comfortable`. The primary takes the colour, and text is kept readable in light and dark. For a code instead, run `npx create-zon@latest theme --color "#c2410c" --corners round`.
|
|
99
|
+
- **A code:** `<ThemeProvider preset="Z1…">`.
|
|
100
|
+
|
|
101
|
+
So the first paint is already in the theme, not zon's grey until the app runs: in Vite, define the preset once in a module of its own (`export const preset = themePresetFromColor(…)`, imported from `@zonsh/ui/theme`, which the Vite config can load) and give it to both `<ThemeProvider preset={preset}>` and `zonThemeScript({ preset })`, which writes its stylesheet into `index.html`. Server-rendered, render `themeFromPreset(preset).css` (from `@zonsh/ui`; it takes a code or a preset) in a `<style>` in `<head>` after the library's stylesheet, or paste that CSS after `@import "@zonsh/ui/styles.css";`.
|
|
102
|
+
|
|
103
|
+
If no one can answer (you run unattended), don't fall back to the default silently: choose a colour, greys and corners that suit the product from the brief, and say in your summary what you chose and how to change it. Pick a primary away from the hues that already mean something — the status colours (green, amber, blue, red) and the category tones the app will use — so a selected control never reads as a status or a kind. Never restyle components one by one for a theme.
|
|
104
|
+
|
|
105
|
+
## Component index
|
|
106
|
+
|
|
107
|
+
### Foundations
|
|
108
|
+
|
|
109
|
+
| Component | Exports | Use it for |
|
|
110
|
+
| --- | --- | --- |
|
|
111
|
+
| [Aspect Ratio](references/components/aspect-ratio.md) | `AspectRatio` | A box that keeps its width-to-height ratio, for images, video and embeds. Also known as: ratio, media frame, embed. |
|
|
112
|
+
| [Code Highlight](references/components/code-highlight.md) | `zonCodeTheme`, `registerCodeLanguage`, `codeLanguages` | The zon syntax theme that colours code blocks, loaded only when one appears. Also known as: syntax highlighting, shiki, code colours, highlighted code, code theme. |
|
|
113
|
+
| [Direction](references/components/direction.md) | `DirectionProvider`, `useDirection` | Right-to-left support for every component inside it. Also known as: rtl, right to left, dir, bidi. |
|
|
114
|
+
| [Layout](references/components/layout.md) | `Container`, `Section`, `Grid`, `GridItem`, `Rails`, `PlusMark`, … | The page column, hairline sections, the 12-column grid and the drawing-board backdrops. Also known as: container, section, grid, stack. |
|
|
115
|
+
| [Locale](references/components/locale.md) | `LocaleProvider`, `useLocale`, `useMessages` | Sets the language and number and date formats for every component inside it. Also known as: i18n, internationalization, localization, translation, translations, language, messages, l10n, german, deutsch, message pack. |
|
|
116
|
+
| [Logo](references/components/logo.md) | `Logo`, `LogoMark`, `LogoLeft`, `LogoRight`, `Wordmark` | The zon crescent mark and the wordmark lockup — and Wordmark, your own product's mark and name for the same slots. Also known as: brand mark, wordmark, zon mark, crescent, moon, your logo, own brand, product logo, app logo. |
|
|
117
|
+
| [Theme](references/components/theme.md) | `ThemeProvider`, `useTheme`, `ThemeToggle`, `ThemeScope`, `usePortalContainer`, `themeScript`, … | Light, dark and system themes, with a toggle and no flash on load, and your own theme from a brand colour or a preset code. Also known as: dark mode, color scheme, theme toggle, brand colour, brand color, custom theme, primary colour, scoped theme, theme scope, nested theme, theme one section, theme.json. |
|
|
118
|
+
| [Typography](references/components/typography.md) | `Display`, `Heading`, `TwoTone`, `PageHeader`, `Eyebrow`, `Lead`, … | Licht headlines, Licht Sans reading copy and Licht Mono labels, as ready text components. Also known as: text, heading, prose. |
|
|
119
|
+
|
|
120
|
+
### Components
|
|
121
|
+
|
|
122
|
+
| Component | Exports | Use it for |
|
|
123
|
+
| --- | --- | --- |
|
|
124
|
+
| [Accordion](references/components/accordion.md) | `Accordion`, `AccordionItem`, `AccordionTrigger`, `AccordionPanel` | Stacked sections that open and close, separated by hairlines, for FAQs and long details. Also known as: faq, disclosure, expandable list. |
|
|
125
|
+
| [Alert](references/components/alert.md) | `Alert`, `AlertTitle`, `AlertDescription`, `AlertAction` | An inline message about the page or a task, with an icon, title and optional action. Also known as: callout, banner, notice, inline message. |
|
|
126
|
+
| [Alert Dialog](references/components/alert-dialog.md) | `AlertDialog`, `AlertDialogTrigger`, `AlertDialogContent`, `AlertDialogHeader`, `AlertDialogTitle`, `AlertDialogDescription`, … | A confirmation that interrupts on purpose, with two clearly named choices. Also known as: confirm dialog, confirmation. |
|
|
127
|
+
| [Audio Player](references/components/audio-player.md) | `AudioPlayer`, `audioPeaks` | Plays a recording or a track, with the waveform as the scrubber. Also known as: audio, audio player, sound player, music player, podcast player, voice note, voice message, recording, track, waveform, scrubber, voice message player, history, peaks, html5 audio, media player. |
|
|
128
|
+
| [Avatar](references/components/avatar.md) | `Avatar`, `AvatarGroup` | A round picture of a person, with initials when there is no image. Also known as: profile picture, user image. |
|
|
129
|
+
| [Badge](references/components/badge.md) | `Badge`, `BadgeAnchor` | A small count or status mark pinned to the corner of an icon button or avatar. Also known as: notification count, counter, status dot, presence indicator, new marker. |
|
|
130
|
+
| [Breadcrumb](references/components/breadcrumb.md) | `Breadcrumb` | A trail of links showing where the page sits in the site. Also known as: breadcrumbs, path. |
|
|
131
|
+
| [Button](references/components/button.md) | `Button` | The layered primary and raised secondary actions, in three sizes and as round icon buttons. |
|
|
132
|
+
| [Button Group](references/components/button-group.md) | `ButtonGroup`, `ButtonGroupSeparator` | Joins related buttons, selects and inputs edge to edge, in a row or a column. Also known as: segmented buttons, split button. |
|
|
133
|
+
| [Calendar](references/components/calendar.md) | `Calendar` | A month grid for picking a date, several dates or a range. Also known as: date grid, month view, day picker. |
|
|
134
|
+
| [Cards](references/components/card.md) | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter` | Groups content as a card, a square region of the page, or a plain hairline section. Also known as: panel, tile, box, surface, region, feature card. |
|
|
135
|
+
| [Carousel](references/components/carousel.md) | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext`, `CarouselDots`, … | Slides shown one at a time, with previous and next buttons and an index. Also known as: slider gallery, slideshow. |
|
|
136
|
+
| [Chart](references/components/chart.md) | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartGradient`, … | Line, bar, area and pie charts on Recharts, with tooltips and legends. Also known as: graph, plot, recharts, dashboard chart. |
|
|
137
|
+
| [Checkbox](references/components/checkbox.md) | `Checkbox`, `CheckboxGroup` | A box to tick for yes/no choices, with an indeterminate state and groups. Also known as: tick box, check. |
|
|
138
|
+
| [Code block](references/components/code-block.md) | `CodeBlock` | Shows source code with syntax colours, a filename, line numbers and a copy button. Also known as: code snippet, pre, syntax, syntax highlighting, shiki, highlighted code. |
|
|
139
|
+
| [Collapsible](references/components/collapsible.md) | `Collapsible`, `CollapsibleTrigger`, `CollapsiblePanel` | One region shown and hidden by a trigger, like a "show more". Also known as: disclosure, expander, show more. |
|
|
140
|
+
| [Color Picker](references/components/color-picker.md) | `ColorPicker`, `ColorPickerPanel`, `ColorSwatch` | Pick a colour from a swatch field, hue slider and presets, as hex, rgb, hsl or oklch. Also known as: colour picker, color input, colour input, swatch, hex picker, hsv picker, oklch picker, palette picker. |
|
|
141
|
+
| [Combobox](references/components/combobox.md) | `Combobox`, `ComboboxInput`, `ComboboxContent`, `ComboboxList`, `ComboboxItem`, `ComboboxEmpty`, … | A select you can type into to filter its options, with single or multiple choice. Also known as: autocomplete, typeahead, searchable select, multi select. |
|
|
142
|
+
| [Command](references/components/command.md) | `CommandDialog`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandGroupLabel`, `CommandItem`, … | The ⌘K command palette for searching and running actions from the keyboard. Also known as: command palette, cmdk, spotlight, quick search. |
|
|
143
|
+
| [Context Menu](references/components/context-menu.md) | `ContextMenu`, `ContextMenuTrigger`, `ContextMenuContent`, `ContextMenuItem`, `ContextMenuLinkItem`, `ContextMenuCheckboxItem`, … | A menu of actions for a thing, opened by right click or long press. Also known as: right click menu. |
|
|
144
|
+
| [Copy Button](references/components/copy-button.md) | `CopyButton` | Copies a value to the clipboard and confirms it with a check or "Copied". Also known as: copy to clipboard, clipboard, copy link, copy code, copy id. |
|
|
145
|
+
| [Data Table](references/components/data-table.md) | `DataTable`, `createDataTableColumnHelper`, `dataTableFeatures` | A full data grid with sorting, search, selection, grouping, paging and virtual rows. Also known as: datagrid, data grid, tanstack table, sortable table, grouped table, responsive data table, virtualized table, large data table. |
|
|
146
|
+
| [Date Picker](references/components/date-picker.md) | `DatePicker`, `DateRangePicker`, `DateTimePicker` | A field that opens a calendar to pick a date, a range, or a date and time. Also known as: datepicker, date range picker, date time picker, datetime picker, datetime-local, date and time. |
|
|
147
|
+
| [Dialog](references/components/dialog.md) | `Dialog`, `DialogTrigger`, `DialogContent`, `DialogHeader`, `DialogTitle`, `DialogDescription`, … | A modal window for a focused task on top of the page. Also known as: modal, lightbox. |
|
|
148
|
+
| [Drawer](references/components/drawer.md) | `Drawer`, `DrawerTrigger`, `DrawerContent`, `DrawerHeader`, `DrawerTitle`, `DrawerDescription`, … | A swipeable panel from the edge of the screen, as a bottom sheet or a side panel. Also known as: sheet, bottom sheet, side panel, off-canvas. |
|
|
149
|
+
| [Empty](references/components/empty.md) | `Empty`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyActions` | What to show when a list, search or dashboard has nothing in it yet. Also known as: empty state, zero state, blank slate, no results. |
|
|
150
|
+
| [Field](references/components/field.md) | `Field`, `FieldLabel`, `FieldDescription`, `FieldError`, `Fieldset`, `FieldsetLegend`, … | Labels, descriptions and validation messages for any form control. Also known as: form field, label, form control. |
|
|
151
|
+
| [File Drop](references/components/file-drop.md) | `FileDrop`, `FileDropItem`, `formatFileSize` | A place to add files by dropping, choosing or pasting them, with checks on type and size. Also known as: dropzone, file upload, file input, upload, drag and drop, paste files, attachments, file picker. |
|
|
152
|
+
| [Filter Bar](references/components/filter-bar.md) | `FilterBar`, `matchesFilters` | Filter chips above a list or table, such as "Status is Active", to narrow the rows. Also known as: filters, faceted search, facets, filter chips, query builder, table filters. |
|
|
153
|
+
| [Form](references/components/form.md) | `Form`, `FormActions` | A native form that lays out fields, collects validation and shows server errors. |
|
|
154
|
+
| [Graph](references/components/graph.md) | `Graph` | Diagrams of things and how they connect, like flowcharts, org charts and networks, on React Flow. Also known as: diagram, flowchart, bpmn, process map, node graph, network graph, relations, org chart, tree, mind map, react flow, xyflow, diagram editor. |
|
|
155
|
+
| [Input](references/components/input.md) | `Input` | A single-line text field for names, emails, search and the like. Also known as: text field, text input. |
|
|
156
|
+
| [Input Group](references/components/input-group.md) | `InputGroup`, `InputGroupInput`, `InputGroupTextarea`, `InputGroupAddon`, `InputGroupText`, `InputGroupButton`, … | A text field with icons, prefixes, buttons or a toolbar inside it. Also known as: input addon, input adornment. |
|
|
157
|
+
| [Item](references/components/item.md) | `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`, … | A flexible row with media, a title, a description and actions. Also known as: list item, row, list row, media object. |
|
|
158
|
+
| [Kbd](references/components/kbd.md) | `Kbd`, `KbdGroup`, `KbdShortcut`, `useShortcutKeys`, `useKeyNames` | Shows a keyboard key or shortcut, written for the reader's device. Also known as: keyboard shortcut, hotkey, key. |
|
|
159
|
+
| [Label](references/components/label.md) | `Label` | A standalone label for a control that is not inside a Field. Also known as: form label, caption. |
|
|
160
|
+
| [Lightbox](references/components/lightbox.md) | `Lightbox`, `LightboxGrid`, `LightboxTrigger` | Opens images full screen, with previous and next, zoom and captions. Also known as: lightbox, image viewer, gallery, photo gallery, image gallery, zoom image, fullscreen image, image preview, photo viewer. |
|
|
161
|
+
| [Markdown Editor](references/components/markdown-editor.md) | `MarkdownEditor`, `useMarkdownEditor` | A rich text field that stores markdown and writes like Notion or Slack. Also known as: markdown, markdown editor, md editor, rich text, rich text editor, wysiwyg, text editor, tiptap, prosemirror, comment box, comment composer, message composer, chat composer, slack composer, notion editor, formatting toolbar, write preview, editor, description field, mentions, slash commands, slash menu, bubble menu, floating toolbar, block menu, turn into, document editor, table editor, markdown table, notes editor, alt text. |
|
|
162
|
+
| [Mentions](references/components/mentions.md) | `Mentions`, `MentionToken` | Suggests people, issues or commands at the caret of a text field as you type. Also known as: mention, mention chip, mention highlight, highlight within textarea, at mention, autocomplete, inline autocomplete, typeahead, caret menu, slash command, slash menu, hashtag, issue reference, textarea suggestions, tribute. |
|
|
163
|
+
| [Menu](references/components/menu.md) | `Menu`, `MenuTrigger`, `MenuContent`, `MenuItem`, `MenuLinkItem`, `MenuCheckboxItem`, … | A list of actions opened from a button, with checkbox, radio and submenu items. Also known as: dropdown menu, dropdown, action menu. |
|
|
164
|
+
| [Menubar](references/components/menubar.md) | `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarLinkItem`, … | The application menu bar of File, Edit, View and the like. Also known as: app menu, menu bar. |
|
|
165
|
+
| [Meter](references/components/meter.md) | `Meter` | Shows a static amount within a range, like storage used. Also known as: gauge, level. |
|
|
166
|
+
| [Money Input](references/components/money-input.md) | `MoneyInput`, `toMinorUnits`, `fromMinorUnits` | A field for an amount of money in one currency, formatted for the locale. Also known as: money field, amount input, currency input, price input, monetary amount, payment amount, transfer amount, minor units, cents. |
|
|
167
|
+
| [Native Select](references/components/native-select.md) | `NativeSelect`, `NativeSelectOption`, `NativeSelectOptGroup` | The browser's own select, styled to match, that works without JavaScript. Also known as: html select. |
|
|
168
|
+
| [Navigation menu](references/components/navigation-menu.md) | `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink` | Site header links with optional dropdown panels. Also known as: nav, mega menu, site navigation. |
|
|
169
|
+
| [Number Field](references/components/number-field.md) | `NumberField` | A field for exact numbers, with − and + steppers. Also known as: number input, stepper, spin button. |
|
|
170
|
+
| [Number Roll](references/components/number-roll.md) | `NumberRoll` | A number whose changed digits roll to their new value like an odometer — up as it grows, down as it falls — formatted for the locale with Intl.NumberFormat, for a total, a price or a count that changes as someone works. Also known as: odometer, rolling number, animated number, number ticker, counter, number flow, slot number, animated price, animated total. |
|
|
171
|
+
| [OTP Field](references/components/otp-field.md) | `OtpField`, `OtpFieldSlot`, `OtpFieldSeparator` | Enter a one-time code, one box per character. Also known as: input otp, pin input, verification code. |
|
|
172
|
+
| [Pagination](references/components/pagination.md) | `Pagination` | Page number buttons for moving through a long list. Also known as: pager, page numbers. |
|
|
173
|
+
| [PDF Viewer](references/components/pdf-viewer.md) | `PdfViewer`, `PdfPreview` | Reads a PDF in the page, with search, zoom and thumbnails, or opens it from a preview card. Also known as: pdf, pdf reader, document viewer, pdf preview, file preview, attachment preview, pdfjs. |
|
|
174
|
+
| [Phone Input](references/components/phone-input.md) | `PhoneInput` | An international phone number field with a country picker and formatting as you type. Also known as: phone number, telephone, tel input, mobile number, international phone, country code, dialling code, dial code, e164, e.164. |
|
|
175
|
+
| [Popover](references/components/popover.md) | `Popover`, `PopoverTrigger`, `PopoverContent`, `PopoverTitle`, `PopoverDescription`, `PopoverClose` | A small panel anchored to a control. Also known as: flyout, dropdown panel. |
|
|
176
|
+
| [Preview Card](references/components/preview-card.md) | `PreviewCard`, `PreviewCardTrigger`, `PreviewCardContent` | A card that previews what a link points to, on hover or focus. Also known as: hover card, link preview. |
|
|
177
|
+
| [Progress](references/components/progress.md) | `Progress` | A bar showing how far along a task is, or that it is still working. Also known as: progress bar, loading bar. |
|
|
178
|
+
| [Radio Group](references/components/radio-group.md) | `RadioGroup`, `Radio` | Pick exactly one option from a short, visible list. Also known as: radio buttons, option group. |
|
|
179
|
+
| [Rating](references/components/rating.md) | `Rating` | A row of stars to give or show a score out of five. Also known as: stars, star rating, review score, score, rate. |
|
|
180
|
+
| [Resizable](references/components/resizable.md) | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle` | Split panes the user can resize by dragging the divider. Also known as: split pane, splitter, panels. |
|
|
181
|
+
| [Scheduler](references/components/scheduler.md) | `Scheduler` | Tasks, bookings and events in time — a Gantt chart with dependencies and milestones, a resource timeline of people and rooms whose bookings stack in lanes, or a calendar with days across and hours down (Day, Work week, Week) or a Month of weeks, where overlapping events sit side by side — with drag to move, resize and draw, snapping, and full keyboard control. Also known as: gantt, gantt chart, gantt editor, dependencies, event editor, booking editor, resource timeline, timeline view, schedule, booking calendar, room booking, project plan, roadmap, planner, capacity planning, shift plan, calendar, week view, day view, month view, work week, time grid, agenda, event calendar, team calendar, google calendar, outlook calendar. |
|
|
182
|
+
| [Scroll area](references/components/scroll-area.md) | `ScrollArea` | A scrolling region with a slim scrollbar and edges that fade. Also known as: scroll container, scrollbar. |
|
|
183
|
+
| [Select](references/components/select.md) | `Select`, `SelectTrigger`, `SelectValue`, `SelectContent`, `SelectItem`, `SelectGroup`, … | Pick one or several options from a dropdown list. Also known as: dropdown select, picker, multi select, multiple select. |
|
|
184
|
+
| [Separator](references/components/separator.md) | `Separator` | The hairline rule, the default way to group content. Also known as: divider, hr, rule. |
|
|
185
|
+
| [Sidebar](references/components/sidebar.md) | `Sidebar`, `SidebarGroup`, `SidebarGroupLabel`, `SidebarItem`, `SidebarSubmenu`, `SidebarProvider`, … | Side navigation, or a full app shell that collapses to icons and becomes a sheet on mobile. Also known as: app shell, side nav. |
|
|
186
|
+
| [Skeleton](references/components/skeleton.md) | `Skeleton` | Loading placeholders shaped like the content they stand in for. Also known as: placeholder, shimmer, loading placeholder. |
|
|
187
|
+
| [Slider](references/components/slider.md) | `Slider` | Drag to pick a value or a range along a track. Also known as: range, range slider. |
|
|
188
|
+
| [Sortable](references/components/sortable.md) | `Sortable`, `SortableList`, `SortableItem`, `SortableHandle`, `useSortable`, `useSortableItem`, … | Lists, rows and grids people reorder by dragging or with the keyboard. Also known as: sortable list, reorder, reorderable list, drag and drop, dnd, drag to reorder, sortable, drag handle, move between lists, sortable grid, reorder grid. |
|
|
189
|
+
| [Spinner](references/components/spinner.md) | `Spinner` | An accessible loading indicator, in eleven styles. Also known as: loader, loading, activity indicator, busy. |
|
|
190
|
+
| [Stat](references/components/stat.md) | `Stat`, `StatGroup`, `Sparkline` | One key figure with its label, change and an optional sparkline. Also known as: kpi, metric, figure, statistic, number, kpi row, sparkline, trend, delta, scorecard. |
|
|
191
|
+
| [Stepper](references/components/stepper.md) | `Stepper` | Shows where someone is in a flow of a few steps. Also known as: steps, step indicator, wizard steps, progress steps, multi-step, checkout steps, stepper form. |
|
|
192
|
+
| [Switch](references/components/switch.md) | `Switch` | An on/off setting that takes effect at once. Also known as: toggle switch, on off. |
|
|
193
|
+
| [Table](references/components/table.md) | `Table`, `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`, … | Rows and columns of data, with dense, grouped, responsive and virtual modes. Also known as: grid, data list, row groups, responsive table, issue list, task list, container query table, virtual table, virtualized rows, large table. |
|
|
194
|
+
| [Tabs](references/components/tabs.md) | `Tabs`, `TabsList`, `TabsTab`, `TabsPanel` | Switch between related panels in the same place. Also known as: tab bar, segmented tabs. |
|
|
195
|
+
| [Tag](references/components/tag.md) | `Tag` | A small label for a status or a category. Also known as: chip, pill, label, status tag, category tag. |
|
|
196
|
+
| [Tags Input](references/components/tags-input.md) | `TagsInput` | A field where typed values become chips, like keywords or email addresses. Also known as: tag input, chips input, token field, keywords, labels input, email list, multi value input. |
|
|
197
|
+
| [Textarea](references/components/textarea.md) | `Textarea` | A multi-line text field for messages, notes and longer answers. Also known as: multiline input, text area, message field. |
|
|
198
|
+
| [Time Field](references/components/time-field.md) | `TimeField` | A field for a time of day, typed as hours and minutes. Also known as: time input, time picker, clock input, hour minute field, time of day. |
|
|
199
|
+
| [Timeline](references/components/timeline.md) | `Timeline`, `TimelineItem`, `TimelineTitle`, `TimelineTime`, `TimelineContent`, `TimelineComment`, … | Events in order, as an activity feed, a history or a changelog. Also known as: activity feed, activity log, history, audit log, changelog, release notes, milestones, events. |
|
|
200
|
+
| [Toast](references/components/toast.md) | `Toaster`, `toast`, `useToast` | Short status messages that pop up in the corner and go away. Also known as: sonner, notification, snackbar. |
|
|
201
|
+
| [Toggle](references/components/toggle.md) | `Toggle` | A button that stays pressed when on, like bold in a text editor. Also known as: toggle button, pressed button. |
|
|
202
|
+
| [Toggle Group](references/components/toggle-group.md) | `ToggleGroup`, `ToggleGroupItem` | A segmented control for picking one of a few options. Also known as: segmented control, button toggle group. |
|
|
203
|
+
| [Toolbar](references/components/toolbar.md) | `Toolbar`, `ToolbarButton`, `ToolbarGroup`, `ToolbarSeparator` | A dense row of command buttons, grouped by hairlines. Also known as: action bar, button bar. |
|
|
204
|
+
| [Tooltip](references/components/tooltip.md) | `TooltipProvider`, `Tooltip`, `TooltipTrigger`, `TooltipContent` | A short label shown on hover and focus. Also known as: hint, title. |
|
|
205
|
+
| [Tour](references/components/tour.md) | `Tour` | A guided product tour of steps pointing at parts of the page. Also known as: tour, product tour, onboarding tour, walkthrough, guided tour, coach marks, feature tour, spotlight, intro, hints, mascot, tippy, guide, speech bubble. |
|
|
206
|
+
| [Tree](references/components/tree.md) | `Tree` | A nested list that expands and collapses, like files and folders. Also known as: tree view, treeview, file tree, file explorer, nested list, outline, folder tree. |
|
|
207
|
+
| [Video Player](references/components/video-player.md) | `VideoPlayer` | Plays a video or a movie, with subtitles, audio tracks, quality and episodes. Also known as: video, video player, media player, player, html5 video, movie, movie player, clip, captions, subtitles, dub, audio track, audio language, quality, resolution, episodes, episode list, seasons. |
|
|
208
|
+
|
|
209
|
+
### Phone
|
|
210
|
+
|
|
211
|
+
| Component | Exports | Use it for |
|
|
212
|
+
| --- | --- | --- |
|
|
213
|
+
| [Action Sheet](references/components/action-sheet.md) | `ActionSheet`, `ActionSheetTrigger`, `ActionSheetContent`, `ActionSheetAction` | A few choices about one thing sliding up from the bottom of a phone screen — a title and message, the actions with at most one destructive, and a separate Cancel; swiped down to dismiss, and a small dialog on a desktop. Also known as: action sheet, bottom sheet menu, options sheet, share sheet, context actions, ios action sheet, more actions. |
|
|
214
|
+
| [App Bar](references/components/app-bar.md) | `AppBar`, `AppBarBack`, `AppBarAction`, `AppBarSearch` | The top bar of a phone screen — a back button, the title and trailing actions, sticky over what scrolls, with a large title that folds into the bar as the content scrolls and an optional search field under it. Also known as: top app bar, navigation bar, nav bar, large title, header bar, toolbar, mobile header, ios navigation bar. |
|
|
215
|
+
| [Bottom Nav](references/components/bottom-nav.md) | `BottomNav`, `BottomNavItem`, `BottomNavAction` | The tab bar of three to five destinations at the bottom of a phone screen. Also known as: bottom navigation, tab bar, bottom tabs, mobile nav, navigation bar, app bar. |
|
|
216
|
+
| [Pull to Refresh](references/components/pull-to-refresh.md) | `PullToRefresh` | A scrolling list that refreshes when pulled down past its top — the list follows the finger with growing resistance, an arc fills to the threshold, and the zon Spinner turns until onRefresh settles; with a Refresh button for the keyboard and screen readers. Also known as: pull to refresh, pull down to refresh, refresh control, swipe to refresh, reload list, ptr. |
|
|
217
|
+
| [Swipe Actions](references/components/swipe-actions.md) | `SwipeActions` | A list row that slides aside under the finger to show its actions — Archive and Delete at the end, Unread at the start — opened by a swipe, a side's single action run by a full one, springing back otherwise; every action also in a menu button for the keyboard, screen readers and a mouse. Also known as: swipe to delete, swipe actions, row swipe, swipeable row, swipe to archive, leading actions, trailing actions, slide actions, list item actions. |
|
|
218
|
+
|
|
219
|
+
### Patterns
|
|
220
|
+
|
|
221
|
+
| Component | Exports | Use it for |
|
|
222
|
+
| --- | --- | --- |
|
|
223
|
+
| [Feature List](references/components/feature-list.md) | `FeatureList`, `FeatureItem`, `FeatureFigure`, `FeatureCalloutList`, `FeatureCallout` | Features, steps and specifications drawn like a sheet on the drawing board, in five layouts — a ruled grid, a framed bento with dotted stages, rows with large figures on the blueprint grid, a numbered list and a label · description list. Also known as: features, feature grid, bento, bento grid, steps, how it works, alternating rows, zigzag, specifications, what's included. |
|
|
224
|
+
| [Quote](references/components/quote.md) | `Quote` | A quote card with an attribution and an optional logo, for real quotes only. Also known as: testimonial, blockquote. |
|
|
225
|
+
| [Site header](references/components/site-header.md) | `SiteHeader` | The sticky top bar of a site — your logo, links, dropdowns and actions, with actions that stay in the bar on phones. Also known as: navbar, top bar, header. |
|
|
226
|
+
|
|
227
|
+
### AI
|
|
228
|
+
|
|
229
|
+
| Component | Exports | Use it for |
|
|
230
|
+
| --- | --- | --- |
|
|
231
|
+
| [Conversation](references/components/conversation.md) | `Conversation`, `ConversationContent`, `ConversationScrollButton` | The scrolling log of an AI chat that follows the reply as it streams in. Also known as: chat log, message list, chat thread, stick to bottom. |
|
|
232
|
+
| [Message](references/components/message.md) | `Message`, `MessageAvatar`, `MessageContent`, `MessageText`, `MessageActions`, `MessageAction`, … | One turn in an AI conversation, with actions to copy, retry or rate it. Also known as: chat message, chat bubble, turn. |
|
|
233
|
+
| [Prompt Input](references/components/prompt-input.md) | `PromptInput`, `PromptInputHeader`, `PromptInputAttachment`, `PromptInputAttachButton`, `PromptInputTextarea`, `PromptInputToolbar`, … | The prompt bar of an AI chat, with attachments, tools and a send button. Also known as: prompt bar, chat input, composer, ai input, message box, file upload, paste screenshot. |
|
|
234
|
+
| [Reasoning](references/components/reasoning.md) | `Reasoning`, `ReasoningTrigger`, `ReasoningContent` | The model's thinking, shown while it runs and folded away when it is done. Also known as: thinking, chain of thought, reasoning trace, thought. |
|
|
235
|
+
| [Response](references/components/response.md) | `Response` | An AI reply rendered from markdown, written out smoothly as it streams. Also known as: markdown, streaming text, ai response, assistant message, rich text. |
|
|
236
|
+
| [Sources](references/components/sources.md) | `Sources`, `SourcesTrigger`, `SourcesContent`, `Source` | The pages an AI answer drew on, as a folded list of links. Also known as: citations, references, links, grounding. |
|
|
237
|
+
| [Suggestions](references/components/suggestions.md) | `Suggestions`, `Suggestion` | Prompts to start from or follow up with in an AI chat. Also known as: prompt suggestions, quick replies, starters, follow-ups. |
|
|
238
|
+
| [Tool Call](references/components/tool-call.md) | `ToolCall`, `ToolCallInput`, `ToolCallOutput` | A tool the AI model used, with its status, parameters and result. Also known as: function call, tool use, tool invocation, agent step, action. |
|
|
239
|
+
|
|
240
|
+
### Illustrations
|
|
241
|
+
|
|
242
|
+
| Component | Exports | Use it for |
|
|
243
|
+
| --- | --- | --- |
|
|
244
|
+
| [AsciiField](references/components/ascii-field.md) | `AsciiField` | A hero backdrop of flickering mono characters that brighten near the pointer. |
|
|
245
|
+
| [Drawing](references/components/drawing.md) | `DrawingHorizon`, `DrawingEclipse`, `DrawingCrescent`, `DrawingNibStudy`, `DrawingElevationGuides`, `DrawingBracketConstruction` | The light-table drawings one component each, from @zonsh/ui/drawing — the horizon under a footer without the whole illustration library in the build. Also known as: horizon, footer horizon, eclipse, crescent, single illustration, light illustration, tree-shaking. |
|
|
246
|
+
| [Illustrations](references/components/illustration.md) | `Illustration`, `illustrations`, `illustrationKinds`, `SpecSheet`, `SpecSheetGrid` | The library of isometric figures, drawings and editorial images, by name. Also known as: illustration library, isometric, iso objects, spot illustration, drawings, spec sheet, light table, editorial illustration, line art, eclipse, horizon, moon, svg assets. |
|
|
247
|
+
| [Tippy](references/components/tippy.md) | `Tippy`, `TippyGuide`, `tippyMoves` | Tippy, zon.sh's pixel mascot, with moves and a speech bubble to guide a tour. Also known as: mascot, character, sprite, pixel art, tippy, guide, companion, onboarding mascot, speech bubble. |
|
|
248
|
+
|
|
249
|
+
### Blocks
|
|
250
|
+
|
|
251
|
+
| Component | Exports | Use it for |
|
|
252
|
+
| --- | --- | --- |
|
|
253
|
+
| [Chat](references/components/chat.md) | | A complete AI chat screen with history, streaming replies, tool calls and a prompt bar. Also known as: ai chat, assistant, chatbot, copilot, chat interface, chat history, conversation list. |
|
|
254
|
+
| [Contact form](references/components/contact-form.md) | | A "Send us a message" section with a validated form and a confirmation. Also known as: contact, contact us, get in touch, support form, feedback form. |
|
|
255
|
+
| [CRM](references/components/crm.md) | | A small CRM workspace with deals by stage and the selected deal's details. Also known as: customer relationship, crm, pipeline, deals, contacts, sales, leads. |
|
|
256
|
+
| [Dashboard](references/components/dashboard.md) | | An overview dashboard with key figures, a chart, top products and recent orders. Also known as: admin dashboard, analytics, overview page, operations dashboard, kpi row, sparkline, top products, account menu, app overview. |
|
|
257
|
+
| [Inbox](references/components/inbox.md) | | A mail inbox on a phone built from the Phone parts — a large title and search that fold into the AppBar, rows that swipe to archive, delete or mark as read, a pull that fetches new mail, an action sheet from each row's "…" and the bottom nav. Also known as: inbox, mail, email, mobile app, phone screen, message list, swipe to delete, pull to refresh, action sheet, ios app. |
|
|
258
|
+
| [Kanban](references/components/kanban.md) | | Deals as a board of stage columns, with cards you drag between them. Also known as: kanban, board, kanban board, pipeline board, drag and drop, sortable, columns, trello, task board. |
|
|
259
|
+
| [Onboarding](references/components/onboarding.md) | | A four-step workspace setup flow with validation, a review and a confirmation. Also known as: onboarding, setup, workspace setup, wizard, multi-step form, stepper form, get started, first run, invite team. |
|
|
260
|
+
| [Pricing](references/components/pricing.md) | | A pricing section — a monthly or yearly toggle with the saving computed from the prices, three plans as cards or hairline columns whose parts line up across them, large mono prices that roll when the period changes, the recommended plan set apart by its ground and the one primary, and a comparison table. Also known as: pricing, pricing page, pricing table, plans, plan comparison, billing period, monthly yearly, subscription, tiers. |
|
|
261
|
+
| [Settings](references/components/settings.md) | | An account and workspace settings page with profile, members, notifications and security. Also known as: account settings, preferences, profile page, user settings, workspace settings, settings page, members, roles, security settings, sessions, two-factor. |
|
|
262
|
+
| [Shop](references/components/shop.md) | | A small editorial shop — a product grid of photos in 20px frames with names in Licht and prices in mono, a product page with a gallery that opens in the Lightbox, glaze swatches, sizes, quantity and a details accordion, a cart drawer with photo lines, a free-delivery track and a pinned total, and a one-page checkout with the order beside the form, delivery or pickup, a sticky total on a phone, a pending submit and a confirmation, all on sample products and prices computed in minor units. Also known as: shop, store, online shop, e-commerce, ecommerce, product card, product grid, product page, product detail, product gallery, product photos, variant picker, colour swatches, cart, shopping cart, basket, cart drawer, line items, free delivery, checkout, order summary, order form, delivery or pickup, order confirmation. |
|
|
263
|
+
| [Sign in and sign up](references/components/sign-in.md) | | Sign in and sign up forms with Google, GitHub and Apple, or an email that continues to a one-time code. Also known as: login, log in, sign in form, authentication, auth, otp login, two-step sign in, verification code, magic code, signup, sign up, sign up form, register, registration, create account, new account, join, email verification, verify email, cardless form, social sign in, sign in with google, oauth, mascot sign in. |
|
|
264
|
+
|
|
265
|
+
### Tools
|
|
266
|
+
|
|
267
|
+
| Component | Exports | Use it for |
|
|
268
|
+
| --- | --- | --- |
|
|
269
|
+
| [Theme editor](references/components/theme-editor.md) | `themeFromPreset`, `themePresetFromColor`, `decodeThemePreset`, `encodeThemePreset`, `normalizeThemePreset`, `themePalette`, … | Build a zon theme from three colours, preview it on an app and share it as a short preset code. Also known as: theme generator, theme builder, colour editor, color picker, palette generator, custom colours, custom theme, control height, border radius, corners, density, theming, design tokens, brand colours, export theme, theme json, theme.json, theme file, preset code, theme code, theme preset, seed colour, shuffle. |
|
|
270
|
+
|
|
271
|
+
## References
|
|
272
|
+
|
|
273
|
+
- `references/brand.md` — the full zon brand guide (identity, colour, type, components, voice).
|
|
274
|
+
- `references/tokens.md` — every token and material utility, with values for both themes.
|
|
275
|
+
- `references/authoring.md` — how library components are built and documented.
|
|
276
|
+
- `references/motion.md` — when something should move, and how: the curves, durations and reduced motion.
|
|
277
|
+
- `references/marketing.md` — landing pages, marketing sites, waitlists, shops and product pages: hero variants, section patterns, footer patterns, with code.
|
|
278
|
+
- `references/recipes.md` — task-shaped recipes with complete code: a form with server validation, a filtered table with the URL as state, settings with save state, a KPI row, confirm before delete, async combobox search, a command palette, a brand theme, a dense app shell, toasts for async work, file uploads with progress, a streaming AI chat, a Kanban board, a room booking scheduler.
|
|
279
|
+
- `references/components/*.md` — one file per component.
|
|
@@ -0,0 +1,265 @@
|
|
|
1
|
+
# Authoring components
|
|
2
|
+
|
|
3
|
+
How a component is built, documented and shipped in `@zonsh/ui`. Read `docs/brand.md`
|
|
4
|
+
first — it is the design brief. This file is the implementation contract.
|
|
5
|
+
|
|
6
|
+
## Files per component
|
|
7
|
+
|
|
8
|
+
| File | Purpose |
|
|
9
|
+
| --------------------------------------- | -------------------------------------------------------------- |
|
|
10
|
+
| `packages/ui/src/components/<name>.tsx` | The component. kebab-case filename. Named exports only. |
|
|
11
|
+
| `packages/ui/docs/<name>.md` | The single source of docs: frontmatter + Markdown (see below). |
|
|
12
|
+
| `packages/ui/docs/<name>.demo.tsx` | Live examples. Each `export function Name()` is one demo. |
|
|
13
|
+
|
|
14
|
+
Do **not** edit `packages/ui/src/index.ts` or any generated agent file — they
|
|
15
|
+
are generated by `pnpm agents` from the files above. Export names must be unique across the
|
|
16
|
+
whole library (prefix compound parts: `DialogTitle`, `MenuItem`, …).
|
|
17
|
+
|
|
18
|
+
Every name a component module exports is public: the index lists each one. A helper exported only
|
|
19
|
+
for another file of the library gets `@internal` in its JSDoc (`/** @internal … */`), which keeps
|
|
20
|
+
it out of the index and the API report; a module whose name starts with `_` (`_media.tsx`) is
|
|
21
|
+
private as a whole, and what another module re-exports from it stays out too.
|
|
22
|
+
|
|
23
|
+
## Stack
|
|
24
|
+
|
|
25
|
+
- React 19, TypeScript (strict), Tailwind CSS v4, `@base-ui/react` 1.x for every interactive
|
|
26
|
+
primitive, `lucide-react` icons, `motion` only when CSS cannot express the motion.
|
|
27
|
+
- Components import their icons from `src/lib/icons.ts`, never from `lucide-react` directly: add
|
|
28
|
+
an icon there first. Moving to another icon set then changes that one file. (Demos import from
|
|
29
|
+
`lucide-react`, as apps do.)
|
|
30
|
+
- Base UI's own docs ship in `packages/ui/node_modules/@base-ui/react/docs/react/components/*.md`.
|
|
31
|
+
They are authoritative for parts, props, data attributes and CSS variables.
|
|
32
|
+
|
|
33
|
+
## Component rules
|
|
34
|
+
|
|
35
|
+
1. **Wrap Base UI, flatten the parts.** Export shadcn-style flat names (`Select`, `SelectTrigger`,
|
|
36
|
+
`SelectContent`, `SelectItem`). Hide `Portal` + `Positioner` inside the `…Content`/`…Popup`
|
|
37
|
+
export and expose positioner props through a `positioner` prop or explicit `side`/`align`/`sideOffset`.
|
|
38
|
+
2. **`data-slot` on every rendered part** (`data-slot="select-trigger"`). Variants/sizes are also
|
|
39
|
+
reflected as `data-variant` / `data-size`.
|
|
40
|
+
3. **className composition** — Base UI accepts `className` as string or `(state) => string`.
|
|
41
|
+
Always compose with `sx(base, className)` from `../lib/cn`. For plain elements use `cn()`.
|
|
42
|
+
4. **Use the material utilities, never flat fills** (defined in `src/styles/material.css`):
|
|
43
|
+
`material-primary`, `material-raised`, `material-row`, `material-field`, `material-menu`,
|
|
44
|
+
`surface-container`, `surface-card`, `popup-motion`, `focus-ring`, `display`, `eyebrow`,
|
|
45
|
+
`link`, `container-page`, `hairline`, `touch-target`. Expressive: `grain`, `blueprint`, `dots`, `rails`.
|
|
46
|
+
5. **Tokens via CSS variables.** Colour utilities exist for every token (`bg-control-hover`,
|
|
47
|
+
`text-muted-foreground`, `border-field-edge`, …). Geometry uses the token vars:
|
|
48
|
+
`rounded-button` (12), `rounded-control` (10), `rounded-item` (7), `rounded-checkbox` (5),
|
|
49
|
+
`rounded-card` (20); heights `min-h-(--control-h-sm|--control-h|--control-h-lg)`, `size-(--icon-button)`.
|
|
50
|
+
**Never add a new radius or height.** Controls nested _inside_ a field (steppers, clear
|
|
51
|
+
buttons, chip removers, addon buttons) use the inset geometry instead: `--control-inset`
|
|
52
|
+
(30px, inside a 38px field) and `--control-inset-sm` (24px, inside a 30px field).
|
|
53
|
+
**Density.** A theme's `--density` (1 at zon's, 0.79 to 1.21) scales every Tailwind step a
|
|
54
|
+
part draws with (`p-3`, `gap-2`, `size-4`, `w-72` …, through `--spacing` on `[data-slot]`) and
|
|
55
|
+
its type by half as much (`--type`). Above 1 the steps grow only as fast as the type
|
|
56
|
+
(`--space`, `min(--density, --type)`): the control heights carry a roomy theme's extra room.
|
|
57
|
+
A part nested in a field's 3px inset is `--control-inset` tall, never `--control-h-sm`, which
|
|
58
|
+
only matches it at zon's 38px. So space with Tailwind's steps, not `px-[12px]`, and set type with the
|
|
59
|
+
density sizes `text-11` … `text-36` (or `text-xs`, `text-sm`), never `text-[13px]`; arbitrary
|
|
60
|
+
px stay fixed, for what the brand fixes in px (an 18px checkbox, a 16px badge). `text-base`
|
|
61
|
+
stays 16px for a field on a touch screen, which would zoom into anything smaller.
|
|
62
|
+
**Shadows are named utilities, never `shadow-[…]`:** `shadow-raised`, `shadow-raised-pressed`,
|
|
63
|
+
`shadow-raised-current`, `shadow-key`, `shadow-checked`, `shadow-thumb`, `shadow-field`,
|
|
64
|
+
`shadow-highlight`, `shadow-invalid`, `shadow-overlay`, `shadow-card`. Thumbs use
|
|
65
|
+
`bg-(--control-thumb)` / `--control-thumb-on`. Key caps use `Kbd`, or `kbdClassName` on a
|
|
66
|
+
non-`<kbd>` element.
|
|
67
|
+
6. **States come from Base UI data attributes** — `data-highlighted`, `data-selected`,
|
|
68
|
+
`data-checked`, `data-pressed`, `data-active`, `data-popup-open`, `data-disabled`,
|
|
69
|
+
`data-invalid`, `data-starting-style` / `data-ending-style` for enter/exit transitions.
|
|
70
|
+
Tailwind v4 variants: `data-highlighted:bg-control-hover`, `data-[side=top]:…`.
|
|
71
|
+
7. **Motion** follows [docs/motion.md](motion.md). In short:
|
|
72
|
+
- Use the tokens, never a hand-typed curve or millisecond value. `--ease` is for entering,
|
|
73
|
+
leaving and colour. `--ease-glide` and `--duration-glide` are for gliding indicators and
|
|
74
|
+
opening heights. `--ease-move` is for moves the interface makes on its own, and for loops.
|
|
75
|
+
`--ease-pop` overshoots, for a small mark only; `--ease-in` for something that leaves unwatched.
|
|
76
|
+
- Colour and opacity use `--duration-fade`, which reduced motion keeps. Movement uses
|
|
77
|
+
`--duration`, which is 0 there. A transition of both lists a duration per property
|
|
78
|
+
(`transition-[opacity,translate] [transition-duration:var(--duration-fade),var(--duration)]`).
|
|
79
|
+
Script reads the tokens with `cssDuration()`, `cssTime()` and `cssEase()` (`lib/motion.ts`). Popups use `popup-motion`: from `--transform-origin`, 97% and
|
|
80
|
+
transparent, leaving in 0.7 of the time.
|
|
81
|
+
- Nothing the keyboard does animates (give it `data-instant`). The exceptions are the digit roll
|
|
82
|
+
and the OTP ring, which show what a key changed and give way to a held key.
|
|
83
|
+
- Motion that answers what someone did ends within 300ms in total, delays included, and eases
|
|
84
|
+
out. Ease-in only for something that leaves unwatched.
|
|
85
|
+
- Use transitions for anything that can be interrupted, and keyframes only for loops (and a
|
|
86
|
+
one-off sequence on a small mark, or a page's one entrance).
|
|
87
|
+
- Animate transform and opacity. Longer motion is only for loops and decorative reveals that
|
|
88
|
+
answer nothing.
|
|
89
|
+
8. **Focus**: 2px `--control-focus` outline, `outline-offset: 0`. Use `focus-ring` or rely on the
|
|
90
|
+
base `:focus-visible` rule. Never remove it, never offset it — except on a text field
|
|
91
|
+
(`material-field` on an input or textarea, an InputGroup): there `material-field` gives a
|
|
92
|
+
softer 1px edge, halfway to `--control-focus`, and the caret marks focus.
|
|
93
|
+
9. **Accessibility**: icon-only controls need `aria-label`; every field needs a visible label;
|
|
94
|
+
errors use colour **and** text; decorative art is `aria-hidden`.
|
|
95
|
+
- **Touch targets.** A control under 44px — a 30px or round icon button, a checkbox, a radio, a
|
|
96
|
+
switch, a slider thumb, a close or remove button, a toolbar button — takes `touch-target`
|
|
97
|
+
(`material.css`): on a coarse pointer an invisible `::before` widens its tap to 44 × 44px
|
|
98
|
+
(`--touch-target`), centred, and nothing is drawn. It makes the control `position: relative`
|
|
99
|
+
there (an `absolute` of yours still wins) and uses its `::before`, so don't put both on one
|
|
100
|
+
element. Leave it off what tiles its own area (calendar days, segments in a track); on a
|
|
101
|
+
remover inside a chip, clip the chip (`pointer-coarse:overflow-clip`) so the area never reaches
|
|
102
|
+
the next chip. `Button` sizes `sm`, `icon` and `icon-sm` have it already.
|
|
103
|
+
- **Forced colours** (a Windows contrast theme) replace fills with the page colour and drop
|
|
104
|
+
gradients and shadows. Anything the material draws only with those — a ring in `box-shadow`, a
|
|
105
|
+
chosen state that is a fill, a focus that is a border shade — gets a rule in
|
|
106
|
+
`@media (forced-colors: active)` (Tailwind: `forced-colors:`) in system colours: `Highlight`
|
|
107
|
+
for focus and selection, `CanvasText` for marks, `GrayText` for what is unavailable. Keyboard
|
|
108
|
+
focus is always an outline, which forced colours keep. Icons ink with `currentColor`.
|
|
109
|
+
- **Text at 200%.** Set type in the density sizes (`text-13`, `text-sm` …) and let what holds
|
|
110
|
+
text grow with it: `min-h-*` rather than `h-*` on anything with a label, a line height in `em`
|
|
111
|
+
or unitless rather than px, and `truncate` (an ellipsis) where a box must keep its width.
|
|
112
|
+
- **Narrow rows.** A row of controls that can outgrow a phone either scrolls inside itself with
|
|
113
|
+
faded ends (`TabsList`, `ToggleGroup`: `lib/scroll-edges.ts`) or folds (`Menubar`'s one menu,
|
|
114
|
+
`Breadcrumb`'s "…", `Pagination`'s compact form, `Toolbar`'s overflow), never widens the page.
|
|
115
|
+
10. **Type**: Licht (`font-heading`, one weight, Light; never bold it) for display/headings; Licht Sans (`font-body`) for
|
|
116
|
+
reading and controls (14px controls, 17px body); Licht Mono (`font-mono`) for small labels,
|
|
117
|
+
numbers, indices and navigation. Eyebrows: 12px mono, uppercase, 0.18em tracking.
|
|
118
|
+
11. **Colour**: surfaces, controls and type are monochrome. Colour carries meaning in small marks (text, a dot, an icon, a segment, a 1px edge, a 10–20% tint): the status colours `--success`, `--warning`, `--info`, `--destructive`, and the category tones `--tone-blue`, `-aqua`, `-violet`, `-magenta`, `-orange`, `-lime` for kinds people must tell apart. Never as decoration or a fill for a button, card or page; always paired with text or an icon, never colour alone. Spell each coloured class out in full (`text-tone-violet`, not `` `text-${tone}` ``) so Tailwind sees it.
|
|
119
|
+
12. **Surfaces**: regions are square (`surface-container`), objects are cards at 20px
|
|
120
|
+
(`surface-card`). The default grouping is a hairline rule and whitespace, not a box.
|
|
121
|
+
Card padding (24/32/40) is set through `--card-padding`; use `[--card-padding:0]` for
|
|
122
|
+
edge-to-edge content (tables, code), never `p-0!`.
|
|
123
|
+
13. Write JSDoc on every exported component: what it is, when to use it, the one rule people break.
|
|
124
|
+
|
|
125
|
+
## Doc file format (`docs/<name>.md`)
|
|
126
|
+
|
|
127
|
+
````md
|
|
128
|
+
---
|
|
129
|
+
name: select # = filename, kebab-case
|
|
130
|
+
title: Select
|
|
131
|
+
category: components # foundations | components | phone | patterns | ai | illustrations | blocks | tools
|
|
132
|
+
description: One sentence, used in search, llms.txt and the skill.
|
|
133
|
+
primitive: "@base-ui/react/select" # omit for non-Base-UI components
|
|
134
|
+
exports: [Select, SelectTrigger, SelectValue, SelectContent, SelectItem]
|
|
135
|
+
status: ready # draft | ready
|
|
136
|
+
added: 2026-11-05 # the day it is added
|
|
137
|
+
release: next # stamped with the version on release; the newest version's docs get a sidebar dot
|
|
138
|
+
change: new # new | updated — see docs/versioning.md, "Release dots"
|
|
139
|
+
---
|
|
140
|
+
|
|
141
|
+
# Select
|
|
142
|
+
|
|
143
|
+
```demo
|
|
144
|
+
Basic (the base example — the component at its most typical, shown first)
|
|
145
|
+
```
|
|
146
|
+
````
|
|
147
|
+
|
|
148
|
+
Lead paragraph: what it is in the zon material.
|
|
149
|
+
|
|
150
|
+
## When to use (bullets: which variant for which job, and when to reach for something else)
|
|
151
|
+
|
|
152
|
+
## Usage (a minimal tsx code block importing from "@zonsh/ui")
|
|
153
|
+
|
|
154
|
+
## Examples (one ### heading per further demo, a sentence of prose, then its ```demo block)
|
|
155
|
+
|
|
156
|
+
## Props (table of the props WE add or that matter; mention forwarded Base UI props)
|
|
157
|
+
|
|
158
|
+
## Brand rules (Do / Don't bullets)
|
|
159
|
+
|
|
160
|
+
## Accessibility
|
|
161
|
+
|
|
162
|
+
````
|
|
163
|
+
|
|
164
|
+
Every page opens on a live base example, so the first thing a reader sees is the component
|
|
165
|
+
itself. A page whose base example needs the full width (a browser, a studio) names it in the
|
|
166
|
+
frontmatter instead — `hero: Studio` — and the docs page shows it under the header. Further demos go under Examples with a short `###` title ("### Sizes", "### As link").
|
|
167
|
+
Component-specific sections ("Motion", "How the horizon is drawn") sit after Examples.
|
|
168
|
+
|
|
169
|
+
A fenced block with language `demo` whose body is a demo export name is replaced by the live
|
|
170
|
+
demo in the playground and by that demo's source code in agent-facing docs.
|
|
171
|
+
|
|
172
|
+
## Demo file format (`docs/<name>.demo.tsx`)
|
|
173
|
+
|
|
174
|
+
- Import from `"@zonsh/ui"` (aliased to the source) and `lucide-react`.
|
|
175
|
+
- Each demo is `export function PascalName() { … }` — self-contained, no props (except the
|
|
176
|
+
controls below).
|
|
177
|
+
- Write realistic, specific copy (see brand.md §07) from varied domains — a shop, a notebook, a course, a code project — not one trade throughout. No invented metrics or customers.
|
|
178
|
+
- Demos render on the playground canvas; do not add page-level padding or backgrounds.
|
|
179
|
+
|
|
180
|
+
### Demo controls
|
|
181
|
+
|
|
182
|
+
A demo whose state is worth switching from outside — a block's flow or layout, say — declares its
|
|
183
|
+
controls instead of drawing its own switches. The docs site renders a `ToggleGroup` for each in
|
|
184
|
+
the frame's toolbar row (in the studio, on the Blocks page and in full screen), named by its
|
|
185
|
+
`label`, and passes the chosen values to the demo as props; the first option is the default.
|
|
186
|
+
|
|
187
|
+
```tsx
|
|
188
|
+
export function SignIn({ flow = "in" }: { flow?: "in" | "up" }) {
|
|
189
|
+
return flow === "in" ? <SignInForm /> : <SignUpForm />;
|
|
190
|
+
}
|
|
191
|
+
SignIn.controls = [
|
|
192
|
+
{
|
|
193
|
+
name: "flow", // the prop
|
|
194
|
+
label: "Flow", // the toggle group's accessible name
|
|
195
|
+
options: [
|
|
196
|
+
{ value: "in", label: "Sign in" }, // the default
|
|
197
|
+
{ value: "up", label: "Sign up" },
|
|
198
|
+
],
|
|
199
|
+
},
|
|
200
|
+
] satisfies DemoControls;
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
- `DemoControls` is a global type in the demos (`packages/ui/docs/demo-controls.d.ts`); no import.
|
|
204
|
+
The docs app's own is in `apps/docs/src/lib/demo-controls.ts`.
|
|
205
|
+
- Two to five short options per control, one or two controls per demo; values are strings.
|
|
206
|
+
- The demo must work with no props at all (its defaults are the first options), as it does in
|
|
207
|
+
the isolated `/__demo/<name>/<Demo>` route and the visual tests.
|
|
208
|
+
- A new value is a new prop: remount (`key`) inside the demo if its state should start over.
|
|
209
|
+
- The `Demo.controls = …` statement is left out of the code people copy and of the agent docs.
|
|
210
|
+
|
|
211
|
+
## Verify
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
pnpm ready # before every commit: format → regenerate (agents) → typecheck → unit tests
|
|
215
|
+
pnpm typecheck
|
|
216
|
+
pnpm agents # regenerate index, skill, AGENTS.md, llms.txt, API report
|
|
217
|
+
pnpm test:unit # integrity: docs ↔ demos ↔ exports, Props tables ↔ types, API report, material rules, and component logic
|
|
218
|
+
pnpm test:e2e # keyboard/pointer flows (also right to left) + axe (WCAG 2.2 AA) on every demo, light and dark
|
|
219
|
+
pnpm test:visual # screenshots of every demo: light, dark, and the base demo on a phone
|
|
220
|
+
````
|
|
221
|
+
|
|
222
|
+
`tests/e2e/zoom.spec.ts` renders every base demo with its text at 200% (`--type: 2`) at 1280px:
|
|
223
|
+
no sideways page scroll, no text cut off or spilling out of its control, every control still
|
|
224
|
+
there to press. `tests/e2e/forced-colors.spec.ts` renders them in forced colours: keyboard focus
|
|
225
|
+
shows as an outline, ticked and unticked controls look different, icons are drawn and disabled
|
|
226
|
+
controls are told apart. Run both with `pnpm test:a11y` (projects `zoom`, `forced-colors`); a
|
|
227
|
+
deliberate exception goes in the spec's `KNOWN` with its reason. `tests/e2e/narrow.spec.ts` and
|
|
228
|
+
`touch.spec.ts` hold the narrow and the touch flows (the latter on a touch screen, `@touch`).
|
|
229
|
+
|
|
230
|
+
`pnpm test:unit` runs two Vitest projects: `tests/unit` in Node, and `tests/components`, which
|
|
231
|
+
renders components in happy-dom with Testing Library and drives them through their props, roles
|
|
232
|
+
and keys. Put logic a component owns there (page lists, typing rules, parsing) rather than in a
|
|
233
|
+
browser test.
|
|
234
|
+
|
|
235
|
+
Every demo renders right to left at `/__demo/<component>/<Demo>?dir=rtl`, inside a
|
|
236
|
+
`DirectionProvider` on an element with `dir="rtl"`; `tests/e2e/rtl.spec.ts` checks the arrow keys,
|
|
237
|
+
the ends things sit at and the mirrored icons. Use logical utilities (`ms-*`, `pe-*`, `border-s`,
|
|
238
|
+
`text-end`) so a component needs nothing more.
|
|
239
|
+
|
|
240
|
+
The interaction flows also run in Firefox, WebKit and, for the `@touch`-tagged ones, an iPhone
|
|
241
|
+
(`interactions-firefox`, `interactions-webkit`, `interactions-iphone`). Run those in Playwright's
|
|
242
|
+
image, which has the browsers and their libraries, against a preview you start yourself:
|
|
243
|
+
|
|
244
|
+
```bash
|
|
245
|
+
pnpm --filter @zonsh/docs build && pnpm --filter @zonsh/docs exec vite preview --port 5206 --strictPort &
|
|
246
|
+
docker run --rm --ipc=host --network=host --user "$(id -u):$(id -g)" -e HOME=/tmp \
|
|
247
|
+
-e PW_REUSE=1 -e PW_PORT=5206 -v "$PWD:$PWD" -w "$PWD" mcr.microsoft.com/playwright:v1.63.0-noble \
|
|
248
|
+
node node_modules/@playwright/test/cli.js test --project=interactions-firefox --project=interactions-webkit
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
New components are picked up automatically: every `demo` in `docs/<name>.md` gets an axe
|
|
252
|
+
check and screenshots, and the integrity tests check its frontmatter and exports. Demos must be
|
|
253
|
+
deterministic — no `Math.random()` or `Date.now()` in what they render (tests freeze the clock
|
|
254
|
+
at 2026-10-01 and reduce motion; canvases are masked).
|
|
255
|
+
|
|
256
|
+
A change to a component's props or exports changes `packages/ui/api/report.md` (`pnpm api`, part
|
|
257
|
+
of `pnpm agents`); commit it with a changeset that describes the change. Every prop a doc's
|
|
258
|
+
`## Props` table names must exist on the component: name a part's props `Part.prop` or in a
|
|
259
|
+
`Component` column, or put them under a `### Part` heading. `node scripts/api-report.mjs
|
|
260
|
+
--undocumented` lists the props a doc leaves out. What counts as breaking, and how to write it
|
|
261
|
+
down: `docs/versioning.md`.
|
|
262
|
+
|
|
263
|
+
After an **intentional** visual change, update the baselines and review the image diffs in the
|
|
264
|
+
commit: `pnpm test:visual:update` (Windows/macOS baselines) and the **Update screenshots**
|
|
265
|
+
GitHub workflow (Linux baselines, used by CI). `pnpm test:report` opens the last report.
|