banhaten 0.3.0 → 0.5.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 +139 -73
- package/CONTRIBUTING.md +46 -44
- package/README.md +192 -190
- package/SECURITY.md +15 -15
- package/banhaten.config.example.json +11 -11
- package/docs/design-spacing.md +13 -0
- package/docs/design-system/README.md +22 -20
- package/docs/design-system/adoption-quality-remediation.md +87 -87
- package/docs/design-system/agent-usage.md +13 -13
- package/docs/design-system/appearance-presets.md +189 -189
- package/docs/design-system/appearances/default.md +94 -94
- package/docs/design-system/appearances/rounded.md +95 -95
- package/docs/design-system/appearances/sharp.md +95 -95
- package/docs/design-system/component-docs-pattern.md +81 -81
- package/docs/design-system/component-implementation-ownership-audit.md +245 -244
- package/docs/design-system/component-quality-audit-2026-08-20.md +225 -223
- package/docs/design-system/component-showcase-consistency-report.md +219 -219
- package/docs/design-system/component-token-consistency-audit.md +173 -173
- package/docs/design-system/components/README.md +90 -76
- package/docs/design-system/components/accordion.md +53 -53
- package/docs/design-system/components/activity-feed.md +94 -94
- package/docs/design-system/components/activity-heatmap.md +57 -57
- package/docs/design-system/components/agent-input.md +85 -0
- package/docs/design-system/components/alert-dialog.md +72 -72
- package/docs/design-system/components/alert.md +98 -98
- package/docs/design-system/components/approval-card.md +134 -0
- package/docs/design-system/components/aspect-ratio.md +45 -45
- package/docs/design-system/components/attribute.md +89 -89
- package/docs/design-system/components/autocomplete.md +75 -75
- package/docs/design-system/components/avatar.md +54 -54
- package/docs/design-system/components/badge.md +54 -54
- package/docs/design-system/components/banner.md +87 -87
- package/docs/design-system/components/breadcrumbs.md +177 -176
- package/docs/design-system/components/button-group.md +98 -98
- package/docs/design-system/components/button.md +83 -80
- package/docs/design-system/components/card.md +88 -88
- package/docs/design-system/components/carousel.md +46 -46
- package/docs/design-system/components/catalog-components.md +47 -47
- package/docs/design-system/components/chart.md +95 -24
- package/docs/design-system/components/checkbox.md +54 -54
- package/docs/design-system/components/collapsible.md +67 -53
- package/docs/design-system/components/command.md +62 -62
- package/docs/design-system/components/context-menu.md +46 -46
- package/docs/design-system/components/date-picker.md +81 -79
- package/docs/design-system/components/divider.md +102 -102
- package/docs/design-system/components/empty-state.md +56 -56
- package/docs/design-system/components/field.md +70 -70
- package/docs/design-system/components/file-upload.md +187 -187
- package/docs/design-system/components/hover-card.md +48 -48
- package/docs/design-system/components/icons.md +48 -48
- package/docs/design-system/components/inline-citations.md +93 -0
- package/docs/design-system/components/input-group.md +58 -58
- package/docs/design-system/components/input-otp.md +56 -56
- package/docs/design-system/components/input.md +117 -61
- package/docs/design-system/components/item.md +59 -57
- package/docs/design-system/components/kbd.md +54 -49
- package/docs/design-system/components/label.md +49 -49
- package/docs/design-system/components/menu.md +71 -61
- package/docs/design-system/components/menubar.md +47 -47
- package/docs/design-system/components/modal.md +105 -105
- package/docs/design-system/components/native-select.md +54 -54
- package/docs/design-system/components/navigation-menu.md +50 -50
- package/docs/design-system/components/onboarding-step-list-item.md +82 -82
- package/docs/design-system/components/page-header.md +93 -86
- package/docs/design-system/components/pagination.md +57 -57
- package/docs/design-system/components/popover.md +60 -60
- package/docs/design-system/components/progress-slider.md +50 -50
- package/docs/design-system/components/progress.md +76 -76
- package/docs/design-system/components/radio-card.md +51 -51
- package/docs/design-system/components/radio-group.md +57 -57
- package/docs/design-system/components/resizable.md +44 -44
- package/docs/design-system/components/rolling-count.md +61 -0
- package/docs/design-system/components/scroll-area.md +51 -51
- package/docs/design-system/components/segmented-control.md +54 -54
- package/docs/design-system/components/select.md +68 -62
- package/docs/design-system/components/sheet.md +67 -67
- package/docs/design-system/components/shimmer-text.md +67 -0
- package/docs/design-system/components/sidebar.md +127 -76
- package/docs/design-system/components/skeleton.md +75 -75
- package/docs/design-system/components/slideout.md +65 -65
- package/docs/design-system/components/slider.md +63 -63
- package/docs/design-system/components/social-button.md +50 -50
- package/docs/design-system/components/spinner.md +62 -62
- package/docs/design-system/components/steps.md +65 -65
- package/docs/design-system/components/streaming-text.md +82 -0
- package/docs/design-system/components/table.md +419 -414
- package/docs/design-system/components/tabs.md +59 -55
- package/docs/design-system/components/tag.md +80 -80
- package/docs/design-system/components/task-list.md +95 -0
- package/docs/design-system/components/textarea.md +50 -50
- package/docs/design-system/components/thinking-reasoning.md +72 -0
- package/docs/design-system/components/thinking-state.md +67 -0
- package/docs/design-system/components/timeline.md +83 -83
- package/docs/design-system/components/toast.md +58 -58
- package/docs/design-system/components/toggle.md +81 -81
- package/docs/design-system/components/toolbar.md +92 -87
- package/docs/design-system/components/tooltip.md +94 -92
- package/docs/design-system/components/typography.md +18 -18
- package/docs/design-system/density-and-elevation.md +65 -61
- package/docs/design-system/design-system-test-missing-items.md +368 -368
- package/docs/design-system/direction-and-localization.md +23 -23
- package/docs/design-system/form-recipes.md +73 -73
- package/docs/design-system/gap-promotion-policy.md +21 -21
- package/docs/design-system/icons.md +74 -69
- package/docs/design-system/installation.md +70 -68
- package/docs/design-system/launch-comparison-shadcn.md +98 -98
- package/docs/design-system/registry-and-cli.md +64 -64
- package/docs/design-system/release-policy.md +30 -30
- package/docs/design-system/roadmap.md +14 -14
- package/docs/design-system/support-matrix.md +23 -23
- package/docs/design-system/tabs.md +54 -53
- package/docs/design-system/template-gap-audit.md +32 -0
- package/docs/design-system/templates.md +59 -0
- package/docs/design-system/token-governance.md +72 -60
- package/package.json +98 -98
- package/registry/component-contract.json +40 -40
- package/registry/components/accordion.tsx +155 -155
- package/registry/components/agent-input-parts.tsx +552 -0
- package/registry/components/agent-input-state.ts +156 -0
- package/registry/components/agent-input.css +307 -0
- package/registry/components/agent-input.tsx +382 -0
- package/registry/components/alert-dialog.tsx +297 -297
- package/registry/components/alert.tsx +293 -293
- package/registry/components/approval-card.css +409 -0
- package/registry/components/approval-card.tsx +401 -0
- package/registry/components/approval-frame.tsx +108 -0
- package/registry/components/approval-questions.tsx +559 -0
- package/registry/components/aspect-ratio.tsx +30 -30
- package/registry/components/attribute.tsx +454 -448
- package/registry/components/autocomplete.tsx +598 -651
- package/registry/components/avatar.tsx +385 -381
- package/registry/components/badge.tsx +629 -629
- package/registry/components/button-group.tsx +565 -565
- package/registry/components/button.tsx +127 -123
- package/registry/components/card.tsx +638 -638
- package/registry/components/carousel.tsx +296 -296
- package/registry/components/chart-block-data.ts +177 -0
- package/registry/components/chart-block.css +171 -0
- package/registry/components/chart-block.tsx +260 -0
- package/registry/components/chart-interactions.ts +123 -0
- package/registry/components/chart-options.cartesian.ts +162 -0
- package/registry/components/chart-options.paint.ts +99 -0
- package/registry/components/chart-options.parts.ts +72 -0
- package/registry/components/chart-options.radial.ts +109 -0
- package/registry/components/chart-options.ts +44 -0
- package/registry/components/chart-options.types.ts +67 -0
- package/registry/components/chart.tsx +203 -203
- package/registry/components/checkbox.tsx +247 -247
- package/registry/components/collapsible.tsx +109 -69
- package/registry/components/command.tsx +208 -208
- package/registry/components/context-menu.tsx +236 -236
- package/registry/components/data-chart.tsx +40 -0
- package/registry/components/date-picker.tsx +1289 -1277
- package/registry/components/echart-theme.ts +246 -0
- package/registry/components/echart.css +49 -0
- package/registry/components/echart.tsx +178 -0
- package/registry/components/expanded/ActivityFeed.tsx +227 -227
- package/registry/components/expanded/ActivityHeatmap.tsx +64 -64
- package/registry/components/expanded/Banner.tsx +179 -179
- package/registry/components/expanded/Breadcrumbs.tsx +131 -131
- package/registry/components/expanded/CatalogComponentsShowcase.tsx +205 -205
- package/registry/components/expanded/CatalogDivider.tsx +49 -49
- package/registry/components/expanded/EmptyState.tsx +155 -155
- package/registry/components/expanded/FileUpload.tsx +543 -543
- package/registry/components/expanded/OnboardingStepListItem.tsx +60 -59
- package/registry/components/expanded/PageHeader.tsx +179 -166
- package/registry/components/expanded/Slideout.tsx +108 -108
- package/registry/components/expanded/Steps.tsx +402 -402
- package/registry/components/expanded/Table.tsx +1092 -1071
- package/registry/components/expanded/Timeline.tsx +203 -203
- package/registry/components/expanded/activityFeed.css +248 -248
- package/registry/components/expanded/activityHeatmap.css +66 -66
- package/registry/components/expanded/banner.css +260 -255
- package/registry/components/expanded/breadcrumbs.css +140 -140
- package/registry/components/expanded/catalogComponentsShowcase.css +87 -87
- package/registry/components/expanded/divider.css +75 -75
- package/registry/components/expanded/emptyState.css +111 -111
- package/registry/components/expanded/fileUpload.css +457 -457
- package/registry/components/expanded/onboardingStepListItem.css +135 -126
- package/registry/components/expanded/pageHeader.css +248 -290
- package/registry/components/expanded/slideout.css +276 -276
- package/registry/components/expanded/steps.css +356 -356
- package/registry/components/expanded/table.css +606 -603
- package/registry/components/expanded/timeline.css +286 -286
- package/registry/components/field.tsx +283 -283
- package/registry/components/hover-card.tsx +48 -48
- package/registry/components/inline-citations.css +126 -0
- package/registry/components/inline-citations.tsx +292 -0
- package/registry/components/input-content.ts +107 -107
- package/registry/components/input-group.tsx +130 -130
- package/registry/components/input-otp.tsx +584 -584
- package/registry/components/input.tsx +990 -972
- package/registry/components/item.tsx +189 -189
- package/registry/components/kbd.tsx +246 -151
- package/registry/components/label.tsx +78 -78
- package/registry/components/menu.tsx +978 -986
- package/registry/components/menubar.tsx +226 -226
- package/registry/components/modal.tsx +872 -872
- package/registry/components/native-select.tsx +205 -205
- package/registry/components/navigation-menu.tsx +171 -171
- package/registry/components/pagination.css +36 -36
- package/registry/components/pagination.tsx +560 -555
- package/registry/components/popover.tsx +338 -338
- package/registry/components/progress-slider.tsx +216 -216
- package/registry/components/radio-card.tsx +676 -677
- package/registry/components/radio-group.tsx +570 -570
- package/registry/components/resizable.tsx +108 -108
- package/registry/components/rolling-count.css +37 -0
- package/registry/components/rolling-count.tsx +110 -0
- package/registry/components/scroll-area.tsx +91 -91
- package/registry/components/segmented-control.tsx +87 -87
- package/registry/components/select-content.tsx +218 -218
- package/registry/components/select.tsx +937 -932
- package/registry/components/sheet.tsx +305 -305
- package/registry/components/shimmer-text.css +69 -0
- package/registry/components/shimmer-text.tsx +43 -0
- package/registry/components/sidebar.tsx +1433 -358
- package/registry/components/skeleton.css +54 -54
- package/registry/components/skeleton.tsx +482 -482
- package/registry/components/slider.tsx +380 -380
- package/registry/components/social-button.tsx +387 -387
- package/registry/components/spinner.tsx +78 -78
- package/registry/components/streaming-text.css +45 -0
- package/registry/components/streaming-text.tsx +165 -0
- package/registry/components/table-elements.tsx +128 -128
- package/registry/components/tabs.css +222 -218
- package/registry/components/tabs.tsx +241 -241
- package/registry/components/tag.tsx +423 -423
- package/registry/components/task-list.css +328 -0
- package/registry/components/task-list.tsx +429 -0
- package/registry/components/textarea.tsx +610 -610
- package/registry/components/thinking-reasoning.css +178 -0
- package/registry/components/thinking-reasoning.tsx +253 -0
- package/registry/components/thinking-state.css +8 -0
- package/registry/components/thinking-state.tsx +46 -0
- package/registry/components/toast.tsx +136 -136
- package/registry/components/toggle.tsx +256 -256
- package/registry/components/toolbar.tsx +539 -539
- package/registry/components/tooltip.tsx +433 -431
- package/registry/examples/agent-input-demo.tsx +90 -0
- package/registry/examples/alert-demo.tsx +34 -34
- package/registry/examples/alert-dialog-demo.tsx +42 -42
- package/registry/examples/approval-card-demo.tsx +83 -0
- package/registry/examples/aspect-ratio-demo.tsx +11 -11
- package/registry/examples/attribute-demo.tsx +65 -65
- package/registry/examples/autocomplete-demo.tsx +109 -109
- package/registry/examples/avatar-demo.tsx +132 -132
- package/registry/examples/badge-demo.tsx +69 -69
- package/registry/examples/button-demo.tsx +86 -83
- package/registry/examples/button-group-demo.tsx +63 -63
- package/registry/examples/card-demo.tsx +86 -86
- package/registry/examples/carousel-demo.tsx +43 -43
- package/registry/examples/chart-block-demo.tsx +5 -0
- package/registry/examples/chart-demo.tsx +18 -33
- package/registry/examples/checkbox-demo.tsx +62 -62
- package/registry/examples/collapsible-demo.tsx +16 -16
- package/registry/examples/collection-filter-bar-demo.tsx +135 -135
- package/registry/examples/command-demo.tsx +42 -42
- package/registry/examples/command-palette-demo.tsx +235 -236
- package/registry/examples/context-menu-demo.tsx +29 -29
- package/registry/examples/control-density-contract-demo.tsx +65 -61
- package/registry/examples/date-picker-demo.tsx +127 -127
- package/registry/examples/divider-demo.tsx +17 -17
- package/registry/examples/expanded/activity-heatmap-demo.tsx +29 -29
- package/registry/examples/expanded/banner-demo.tsx +48 -48
- package/registry/examples/expanded/breadcrumbs-demo.tsx +59 -59
- package/registry/examples/expanded/empty-state-demo.tsx +39 -39
- package/registry/examples/expanded/file-upload-demo.tsx +60 -60
- package/registry/examples/expanded/onboarding-step-demo.tsx +11 -11
- package/registry/examples/expanded/slideout-demo.tsx +15 -15
- package/registry/examples/expanded/steps-demo.tsx +29 -29
- package/registry/examples/expanded/tabs-demo.tsx +13 -13
- package/registry/examples/expanded/timeline-demo.tsx +18 -18
- package/registry/examples/field-demo.tsx +51 -51
- package/registry/examples/hover-card-demo.tsx +23 -23
- package/registry/examples/inline-citations-demo.tsx +31 -0
- package/registry/examples/input-actions-demo.tsx +36 -0
- package/registry/examples/input-demo.tsx +87 -87
- package/registry/examples/input-group-demo.tsx +16 -16
- package/registry/examples/input-otp-demo.tsx +72 -72
- package/registry/examples/item-demo.tsx +46 -46
- package/registry/examples/kbd-demo.tsx +12 -11
- package/registry/examples/label-demo.tsx +20 -20
- package/registry/examples/menu-demo.tsx +122 -122
- package/registry/examples/menubar-demo.tsx +34 -34
- package/registry/examples/modal-demo.tsx +74 -74
- package/registry/examples/native-select-demo.tsx +16 -16
- package/registry/examples/navigation-menu-demo.tsx +29 -29
- package/registry/examples/pagination-demo.tsx +20 -20
- package/registry/examples/popover-demo.tsx +547 -546
- package/registry/examples/progress-demo.tsx +37 -37
- package/registry/examples/progress-slider-demo.tsx +29 -29
- package/registry/examples/radio-card-demo.tsx +51 -51
- package/registry/examples/radio-group-demo.tsx +62 -62
- package/registry/examples/resizable-demo.tsx +22 -22
- package/registry/examples/results-toolbar-demo.tsx +44 -44
- package/registry/examples/rolling-count-demo.tsx +39 -0
- package/registry/examples/scroll-area-demo.tsx +15 -15
- package/registry/examples/segmented-control-demo.tsx +39 -39
- package/registry/examples/select-demo.tsx +87 -87
- package/registry/examples/sheet-demo.tsx +47 -47
- package/registry/examples/shimmer-text-demo.tsx +20 -0
- package/registry/examples/sidebar-demo.tsx +101 -57
- package/registry/examples/slider-demo.tsx +31 -31
- package/registry/examples/social-button-demo.tsx +61 -61
- package/registry/examples/spinner-demo.tsx +59 -59
- package/registry/examples/streaming-text-demo.tsx +28 -0
- package/registry/examples/tabs-demo.tsx +13 -13
- package/registry/examples/tag-demo.tsx +29 -29
- package/registry/examples/task-list-demo.tsx +74 -0
- package/registry/examples/textarea-demo.tsx +79 -79
- package/registry/examples/thinking-reasoning-demo.tsx +74 -0
- package/registry/examples/thinking-state-demo.tsx +13 -0
- package/registry/examples/toast-demo.tsx +35 -35
- package/registry/examples/toggle-demo.tsx +59 -59
- package/registry/examples/tooltip-demo.tsx +115 -115
- package/registry/guidance/USAGE.md +27 -27
- package/registry/guidance/charts.LICENSE.txt +24 -0
- package/registry/hooks/use-controllable-state.ts +33 -0
- package/registry/hooks/use-direction.ts +207 -207
- package/registry/hooks/use-listbox-navigation.ts +73 -0
- package/registry/hooks/use-motion-end.ts +55 -0
- package/registry/hooks/use-reduced-motion.ts +28 -0
- package/registry/index.json +1634 -184
- package/registry/styles/globals.css +1462 -1570
- package/registry.json +364 -10
- package/schema/config.schema.json +51 -51
- package/schema/registry.schema.json +194 -190
- package/schema/tokens.schema.json +167 -163
- package/src/cli/command-line.js +194 -194
- package/src/cli/config-editors.js +9 -9
- package/src/cli/doctor.js +399 -399
- package/src/cli/file-transaction.js +302 -295
- package/src/cli/global-css.js +153 -153
- package/src/cli/index.js +1002 -1009
- package/src/cli/install-plan.js +592 -592
- package/src/cli/install-receipt.js +171 -171
- package/src/cli/jsonc.js +203 -203
- package/src/cli/package-install-state.js +254 -254
- package/src/cli/package-manager.js +238 -238
- package/src/cli/package-plan.js +185 -185
- package/src/cli/package-version.js +97 -97
- package/src/cli/registry-query.js +207 -207
- package/src/cli/reporting.js +55 -55
- package/src/cli/schema-validation.js +19 -19
- package/src/cli/source-scanner.js +686 -686
- package/src/cli/vite-config.js +478 -478
- package/tokens/banhaten.tokens.json +458 -224
|
@@ -1,59 +1,59 @@
|
|
|
1
|
-
# Empty State
|
|
2
|
-
|
|
3
|
-
Empty State is a reusable result-state composition for no-results, first-run, or cleared workflow moments. It uses a neutral tokenized icon halo, 17px semibold title text, 15px regular supporting copy, and optional Banhaten Button actions.
|
|
4
|
-
|
|
5
|
-
## API
|
|
6
|
-
|
|
7
|
-
```tsx
|
|
8
|
-
<EmptyState
|
|
9
|
-
title="No results found"
|
|
10
|
-
description="Try adjusting your search or filters"
|
|
11
|
-
actions={[
|
|
12
|
-
{ label: "Reset filters", variant: "secondary" },
|
|
13
|
-
{ label: "Create item" },
|
|
14
|
-
]}
|
|
15
|
-
/>
|
|
16
|
-
```
|
|
17
|
-
|
|
18
|
-
| Prop | Values | Default |
|
|
19
|
-
| --- | --- | --- |
|
|
20
|
-
| `title` | `ReactNode` | required |
|
|
21
|
-
| `description` | `ReactNode` | none |
|
|
22
|
-
| `icon` | `ReactNode` | `SearchIcon` |
|
|
23
|
-
| `iconLabel` | `string` | decorative icon |
|
|
24
|
-
| `actions` | `EmptyStateAction[]` | `[]` |
|
|
25
|
-
| `align` | `center`, `start` | `center` |
|
|
26
|
-
| `size` | `default`, `compact` | `default` |
|
|
27
|
-
| `dir` | `ltr`, `rtl`, `auto` | `ltr` |
|
|
28
|
-
|
|
29
|
-
## Token Contract
|
|
30
|
-
|
|
31
|
-
- Icon halo: `--bh-bg-neutral-subtle`, `--bh-bg-neutral-soft`, `--bh-radius-full`
|
|
32
|
-
- Title: `--bh-text-heading-xs-semibold-*`, `--bh-content-default`
|
|
33
|
-
- Description: `--bh-text-body-md-regular-*`, `--bh-content-subtle`
|
|
34
|
-
- Spacing and sizing: `--bh-space-*`
|
|
35
|
-
- Actions: existing `Button` component variants and token contract
|
|
36
|
-
|
|
37
|
-
## RTL Rules
|
|
38
|
-
|
|
39
|
-
`EmptyState` inherits logical alignment through `dir`. Text uses `dir="auto"` so Arabic and English copy resolve naturally, while the action row preserves logical order in RTL containers.
|
|
40
|
-
|
|
41
|
-
## Install
|
|
42
|
-
|
|
43
|
-
```bash
|
|
44
|
-
npx banhaten add empty-state
|
|
45
|
-
```
|
|
46
|
-
|
|
47
|
-
## Examples
|
|
48
|
-
|
|
49
|
-
Primary registry example: `examples/expanded/empty-state-demo.tsx`.
|
|
50
|
-
|
|
51
|
-
Open the live component page or run `npx banhaten docs empty-state` to inspect source files, install command, and examples.
|
|
52
|
-
|
|
53
|
-
## Accessibility
|
|
54
|
-
|
|
55
|
-
Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
|
|
56
|
-
|
|
1
|
+
# Empty State
|
|
2
|
+
|
|
3
|
+
Empty State is a reusable result-state composition for no-results, first-run, or cleared workflow moments. It uses a neutral tokenized icon halo, 17px semibold title text, 15px regular supporting copy, and optional Banhaten Button actions.
|
|
4
|
+
|
|
5
|
+
## API
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
<EmptyState
|
|
9
|
+
title="No results found"
|
|
10
|
+
description="Try adjusting your search or filters"
|
|
11
|
+
actions={[
|
|
12
|
+
{ label: "Reset filters", variant: "secondary" },
|
|
13
|
+
{ label: "Create item" },
|
|
14
|
+
]}
|
|
15
|
+
/>
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
| Prop | Values | Default |
|
|
19
|
+
| --- | --- | --- |
|
|
20
|
+
| `title` | `ReactNode` | required |
|
|
21
|
+
| `description` | `ReactNode` | none |
|
|
22
|
+
| `icon` | `ReactNode` | `SearchIcon` |
|
|
23
|
+
| `iconLabel` | `string` | decorative icon |
|
|
24
|
+
| `actions` | `EmptyStateAction[]` | `[]` |
|
|
25
|
+
| `align` | `center`, `start` | `center` |
|
|
26
|
+
| `size` | `default`, `compact` | `default` |
|
|
27
|
+
| `dir` | `ltr`, `rtl`, `auto` | `ltr` |
|
|
28
|
+
|
|
29
|
+
## Token Contract
|
|
30
|
+
|
|
31
|
+
- Icon halo: `--bh-bg-neutral-subtle`, `--bh-bg-neutral-soft`, `--bh-radius-full`
|
|
32
|
+
- Title: `--bh-text-heading-xs-semibold-*`, `--bh-content-default`
|
|
33
|
+
- Description: `--bh-text-body-md-regular-*`, `--bh-content-subtle`
|
|
34
|
+
- Spacing and sizing: `--bh-space-*`
|
|
35
|
+
- Actions: existing `Button` component variants and token contract
|
|
36
|
+
|
|
37
|
+
## RTL Rules
|
|
38
|
+
|
|
39
|
+
`EmptyState` inherits logical alignment through `dir`. Text uses `dir="auto"` so Arabic and English copy resolve naturally, while the action row preserves logical order in RTL containers.
|
|
40
|
+
|
|
41
|
+
## Install
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
npx banhaten add empty-state
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
## Examples
|
|
48
|
+
|
|
49
|
+
Primary registry example: `examples/expanded/empty-state-demo.tsx`.
|
|
50
|
+
|
|
51
|
+
Open the live component page or run `npx banhaten docs empty-state` to inspect source files, install command, and examples.
|
|
52
|
+
|
|
53
|
+
## Accessibility
|
|
54
|
+
|
|
55
|
+
Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
|
|
56
|
+
|
|
57
57
|
<!-- registry-contract:start -->
|
|
58
58
|
## Registry Contract
|
|
59
59
|
|
|
@@ -1,73 +1,73 @@
|
|
|
1
|
-
# Field
|
|
2
|
-
|
|
3
|
-
Field composes labels, controls, descriptions, and validation errors into accessible form rows. It gives Banhaten a shared form anatomy without forcing a validation library.
|
|
4
|
-
|
|
5
|
-
## API
|
|
6
|
-
|
|
7
|
-
```tsx
|
|
8
|
-
<Field invalid>
|
|
9
|
-
<FieldLabel>Email</FieldLabel>
|
|
10
|
-
<FieldControl>
|
|
11
|
-
<Input state="error" />
|
|
12
|
-
</FieldControl>
|
|
13
|
-
<FieldError>Enter a valid email address.</FieldError>
|
|
14
|
-
</Field>
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
| Part | Purpose |
|
|
18
|
-
| --- | --- |
|
|
19
|
-
| `Field` | row context, ids, invalid and disabled state |
|
|
20
|
-
| `FieldLabel` | label connected to the control id |
|
|
21
|
-
| `FieldControl` | `asChild` slot that wires id and ARIA state |
|
|
22
|
-
| `FieldDescription` | helper text |
|
|
23
|
-
| `FieldError` | validation message with alert role |
|
|
24
|
-
| `FieldSet`, `FieldLegend`, `FieldGroup`, `FieldContent` | grouped form layout |
|
|
25
|
-
|
|
26
|
-
## Validation Pattern
|
|
27
|
-
|
|
28
|
-
Use native state for plain forms, or map your validation library state into `invalid`, `FieldError`, and the child control state.
|
|
29
|
-
|
|
30
|
-
```tsx
|
|
31
|
-
<Field invalid={Boolean(errors.email)}>
|
|
32
|
-
<FieldLabel>Email</FieldLabel>
|
|
33
|
-
<FieldControl>
|
|
34
|
-
<Input state={errors.email ? "error" : "default"} />
|
|
35
|
-
</FieldControl>
|
|
36
|
-
{errors.email ? <FieldError>{errors.email.message}</FieldError> : null}
|
|
37
|
-
</Field>
|
|
38
|
-
```
|
|
39
|
-
|
|
40
|
-
## Token Contract
|
|
41
|
-
|
|
42
|
-
Field uses Banhaten spacing, content, danger, field, typography, and disabled tokens. Child controls keep ownership of their own surface tokens.
|
|
43
|
-
|
|
44
|
-
## RTL
|
|
45
|
-
|
|
46
|
-
Field uses logical grid and text-start alignment. Horizontal and responsive orientations mirror naturally under inherited `dir`.
|
|
47
|
-
|
|
48
|
-
## Install
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
npx banhaten add field
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
## Examples
|
|
55
|
-
|
|
56
|
-
Primary registry example: `examples/field-demo.tsx`.
|
|
57
|
-
|
|
58
|
-
Open the live component page or run `npx banhaten docs field` to inspect source files, install command, and examples.
|
|
59
|
-
|
|
60
|
-
## RTL Rules
|
|
61
|
-
|
|
62
|
-
- `inheritsDirection`: true
|
|
63
|
-
- `layout`: Vertical, horizontal, and responsive layouts use CSS grid and logical text alignment so field rows mirror naturally.
|
|
64
|
-
- `textDirection`: Labels, descriptions, and errors use dir="auto" through Label and field text parts.
|
|
65
|
-
- `semantics`: FieldControl wires the generated control id, invalid state, disabled announcement, and description/error ids into the child control.
|
|
66
|
-
|
|
67
|
-
## Accessibility
|
|
68
|
-
|
|
69
|
-
This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
|
|
70
|
-
|
|
1
|
+
# Field
|
|
2
|
+
|
|
3
|
+
Field composes labels, controls, descriptions, and validation errors into accessible form rows. It gives Banhaten a shared form anatomy without forcing a validation library.
|
|
4
|
+
|
|
5
|
+
## API
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
<Field invalid>
|
|
9
|
+
<FieldLabel>Email</FieldLabel>
|
|
10
|
+
<FieldControl>
|
|
11
|
+
<Input state="error" />
|
|
12
|
+
</FieldControl>
|
|
13
|
+
<FieldError>Enter a valid email address.</FieldError>
|
|
14
|
+
</Field>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
| Part | Purpose |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| `Field` | row context, ids, invalid and disabled state |
|
|
20
|
+
| `FieldLabel` | label connected to the control id |
|
|
21
|
+
| `FieldControl` | `asChild` slot that wires id and ARIA state |
|
|
22
|
+
| `FieldDescription` | helper text |
|
|
23
|
+
| `FieldError` | validation message with alert role |
|
|
24
|
+
| `FieldSet`, `FieldLegend`, `FieldGroup`, `FieldContent` | grouped form layout |
|
|
25
|
+
|
|
26
|
+
## Validation Pattern
|
|
27
|
+
|
|
28
|
+
Use native state for plain forms, or map your validation library state into `invalid`, `FieldError`, and the child control state.
|
|
29
|
+
|
|
30
|
+
```tsx
|
|
31
|
+
<Field invalid={Boolean(errors.email)}>
|
|
32
|
+
<FieldLabel>Email</FieldLabel>
|
|
33
|
+
<FieldControl>
|
|
34
|
+
<Input state={errors.email ? "error" : "default"} />
|
|
35
|
+
</FieldControl>
|
|
36
|
+
{errors.email ? <FieldError>{errors.email.message}</FieldError> : null}
|
|
37
|
+
</Field>
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
## Token Contract
|
|
41
|
+
|
|
42
|
+
Field uses Banhaten spacing, content, danger, field, typography, and disabled tokens. Child controls keep ownership of their own surface tokens.
|
|
43
|
+
|
|
44
|
+
## RTL
|
|
45
|
+
|
|
46
|
+
Field uses logical grid and text-start alignment. Horizontal and responsive orientations mirror naturally under inherited `dir`.
|
|
47
|
+
|
|
48
|
+
## Install
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
npx banhaten add field
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
## Examples
|
|
55
|
+
|
|
56
|
+
Primary registry example: `examples/field-demo.tsx`.
|
|
57
|
+
|
|
58
|
+
Open the live component page or run `npx banhaten docs field` to inspect source files, install command, and examples.
|
|
59
|
+
|
|
60
|
+
## RTL Rules
|
|
61
|
+
|
|
62
|
+
- `inheritsDirection`: true
|
|
63
|
+
- `layout`: Vertical, horizontal, and responsive layouts use CSS grid and logical text alignment so field rows mirror naturally.
|
|
64
|
+
- `textDirection`: Labels, descriptions, and errors use dir="auto" through Label and field text parts.
|
|
65
|
+
- `semantics`: FieldControl wires the generated control id, invalid state, disabled announcement, and description/error ids into the child control.
|
|
66
|
+
|
|
67
|
+
## Accessibility
|
|
68
|
+
|
|
69
|
+
This component relies on `@radix-ui/react-slot` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.
|
|
70
|
+
|
|
71
71
|
<!-- registry-contract:start -->
|
|
72
72
|
## Registry Contract
|
|
73
73
|
|
|
@@ -1,189 +1,189 @@
|
|
|
1
|
-
# File Upload
|
|
2
|
-
|
|
3
|
-
`FileUpload` lets people drag files into a drop zone, browse for files, and review queued upload items. Use it when the workflow supports one or more files and the user needs clear per-file status feedback.
|
|
4
|
-
|
|
5
|
-
Figma reference: `File upload`, node `254:3195`.
|
|
6
|
-
|
|
7
|
-
## Variants
|
|
8
|
-
|
|
9
|
-
The Figma component defines these top-level variants:
|
|
10
|
-
|
|
11
|
-
| Size | Direction |
|
|
12
|
-
| --- | --- |
|
|
13
|
-
| `lg` | LTR |
|
|
14
|
-
| `sm` | LTR |
|
|
15
|
-
| `lg` | RTL |
|
|
16
|
-
| `sm` | RTL |
|
|
17
|
-
|
|
18
|
-
Queued file rows define these states:
|
|
19
|
-
|
|
20
|
-
| State | Meaning |
|
|
21
|
-
| --- | --- |
|
|
22
|
-
| `uploaded` | The file finished uploading successfully. |
|
|
23
|
-
| `uploading` | The file is uploading and progress is unknown. |
|
|
24
|
-
| `uploading-progress` | The file is uploading and exposes a progress bar. |
|
|
25
|
-
| `error` | The file failed and needs a retry or removal action. |
|
|
26
|
-
|
|
27
|
-
## API
|
|
28
|
-
|
|
29
|
-
Use semantic names in code and let the implementation map them to the current appearance preset.
|
|
30
|
-
|
|
31
|
-
```ts
|
|
32
|
-
type FileUploadSize = "lg" | "sm";
|
|
33
|
-
type FileUploadVariant = "default" | "button";
|
|
34
|
-
type FileUploadDropzoneState = "default" | "hover";
|
|
35
|
-
type FileUploadItemStatus = "uploaded" | "uploading" | "uploading-progress" | "error";
|
|
36
|
-
|
|
37
|
-
type FileUploadFile = {
|
|
38
|
-
id: string;
|
|
39
|
-
name: string;
|
|
40
|
-
sizeLabel: string;
|
|
41
|
-
versionLabel?: string;
|
|
42
|
-
progress?: number;
|
|
43
|
-
progressLabel?: string;
|
|
44
|
-
extensionLabel?: string;
|
|
45
|
-
status: FileUploadItemStatus;
|
|
46
|
-
errorLabel?: string;
|
|
47
|
-
uploadedLabel?: string;
|
|
48
|
-
uploadLabel?: string;
|
|
49
|
-
};
|
|
50
|
-
|
|
51
|
-
type FileUploadProps = {
|
|
52
|
-
size?: FileUploadSize;
|
|
53
|
-
variant?: FileUploadVariant;
|
|
54
|
-
dropzoneState?: FileUploadDropzoneState;
|
|
55
|
-
dir?: "ltr" | "rtl" | "auto";
|
|
56
|
-
files?: FileUploadFile[];
|
|
57
|
-
title?: string;
|
|
58
|
-
prompt?: string;
|
|
59
|
-
browseLabel?: string;
|
|
60
|
-
helperText?: string;
|
|
61
|
-
disabled?: boolean;
|
|
62
|
-
accept?: string;
|
|
63
|
-
multiple?: boolean;
|
|
64
|
-
onBrowse?: () => void;
|
|
65
|
-
onDrop?: (files: FileList) => void;
|
|
66
|
-
onMore?: (fileId: string) => void;
|
|
67
|
-
onCancel?: (fileId: string) => void;
|
|
68
|
-
onRemove?: (fileId: string) => void;
|
|
69
|
-
onRetry?: (fileId: string) => void;
|
|
70
|
-
};
|
|
71
|
-
```
|
|
72
|
-
|
|
73
|
-
`files` controls whether the queued file list renders. Do not expose a separate `hasFilesQueued` prop in production code; the rendered state should follow from the file array.
|
|
74
|
-
|
|
75
|
-
## Layout
|
|
76
|
-
|
|
77
|
-
- The root stacks the drop zone and queued file list vertically.
|
|
78
|
-
- Large width is 500px in the Figma source; small width is 343px. Implementations may use `width: 100%` with those values as max-widths.
|
|
79
|
-
- The default drop zone is 500px by 180px; the title-plus-button variant is 500px by 256px.
|
|
80
|
-
- The drop zone is centered, uses a 2px dashed border, and hover strengthens the border without changing the surface.
|
|
81
|
-
- The upload icon container is 48px square with a subtle border and the current control radius.
|
|
82
|
-
- Large file rows use 16px padding, a 40px file icon, and 12px gaps.
|
|
83
|
-
- Small file rows use 12px padding, a 32px file icon, and 8px gaps.
|
|
84
|
-
- Row actions are icon-only: more, close/cancel, and trash.
|
|
85
|
-
- The queued list uses a 12px vertical gap.
|
|
86
|
-
- RTL mode mirrors visual order and aligns file metadata to the end while preserving logical reading order.
|
|
87
|
-
|
|
88
|
-
## Tokens
|
|
89
|
-
|
|
90
|
-
The Figma source uses design tokens such as `bg/raised`, `interactive/secondary/default`, `border/subtle`, `border/danger/strong`, `space/*`, and `radius/*`. Implementations should map those to the design system's semantic token contract.
|
|
91
|
-
|
|
92
|
-
```ts
|
|
93
|
-
export const fileUploadTokens = {
|
|
94
|
-
dropzoneBackground: "background.subtle",
|
|
95
|
-
dropzoneBorder: "border.default",
|
|
96
|
-
dropzoneIconBackground: "background.default",
|
|
97
|
-
dropzoneIconBorder: "border.subtle",
|
|
98
|
-
rowBackground: "background.card",
|
|
99
|
-
rowBorder: "border.subtle",
|
|
100
|
-
rowErrorBorder: "border.danger",
|
|
101
|
-
rowElevation: "elevation.card",
|
|
102
|
-
textColor: "content.default",
|
|
103
|
-
helperTextColor: "content.subtle",
|
|
104
|
-
linkColor: "content.link",
|
|
105
|
-
successColor: "content.success",
|
|
106
|
-
dangerColor: "content.danger",
|
|
107
|
-
rowRadiusLarge: "shape.card",
|
|
108
|
-
rowRadiusSmall: "shape.control",
|
|
109
|
-
};
|
|
110
|
-
```
|
|
111
|
-
|
|
112
|
-
Do not hard-code the Figma fallback values in component code. For example, the error state should resolve through `border.danger` and `content.danger`, not through the Figma fallback hex values.
|
|
113
|
-
|
|
114
|
-
## Behavior
|
|
115
|
-
|
|
116
|
-
- Clicking the browse text or drop zone should open the platform file picker.
|
|
117
|
-
- Dragging files over the drop zone should show the same target without changing the component API.
|
|
118
|
-
- `uploading` rows should expose a close/cancel action.
|
|
119
|
-
- `uploading-progress` rows should expose a real progress bar and percent label.
|
|
120
|
-
- `uploaded` rows should expose remove and overflow actions when the product has secondary file actions.
|
|
121
|
-
- `error` rows should expose remove and retry actions.
|
|
122
|
-
- The component should support both single-file and multi-file use through the `multiple` prop or equivalent platform API.
|
|
123
|
-
|
|
124
|
-
## Accessibility
|
|
125
|
-
|
|
126
|
-
- Use a real file input or a button connected to a file input.
|
|
127
|
-
- Preserve keyboard access for browse, cancel, remove, retry, and overflow actions.
|
|
128
|
-
- Announce upload status changes through an accessible live region when status changes after initial render.
|
|
129
|
-
- Keep file names as real text and avoid icon-only status communication.
|
|
130
|
-
- Icon-only actions need accessible labels such as `Cancel upload`, `Remove file`, `Retry upload`, and `More file actions`.
|
|
131
|
-
- The drop zone should not be the only way to select files.
|
|
132
|
-
|
|
133
|
-
## Usage
|
|
134
|
-
|
|
135
|
-
```tsx
|
|
136
|
-
<FileUpload
|
|
137
|
-
files={[
|
|
138
|
-
{ id: "1", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploaded" },
|
|
139
|
-
{ id: "2", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploading" },
|
|
140
|
-
{ id: "3", name: "file-name.pdf", sizeLabel: "32 KB", progress: 40, status: "uploading-progress" },
|
|
141
|
-
{ id: "4", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "error" },
|
|
142
|
-
]}
|
|
143
|
-
multiple
|
|
144
|
-
/>
|
|
145
|
-
|
|
146
|
-
<FileUpload size="sm" files={[{ id: "1", name: "file-name.pdf", sizeLabel: "32 KB", status: "uploaded" }]} />
|
|
147
|
-
|
|
148
|
-
<FileUpload dir="rtl" size="lg" />
|
|
149
|
-
```
|
|
150
|
-
|
|
151
|
-
## Preset Impact
|
|
152
|
-
|
|
153
|
-
- `default`: white rows on a subtle drop-zone background, modest radius, quiet shadow, and balanced spacing.
|
|
154
|
-
- `rounded`: softer drop-zone and row corners, slightly more padding, and gentler borders.
|
|
155
|
-
- `sharp`: square or near-square row treatment, denser spacing, stronger borders, and minimal row elevation.
|
|
156
|
-
|
|
157
|
-
## Implementation Notes
|
|
158
|
-
|
|
159
|
-
- Keep the drop zone and file row primitives separate so rows can be reused in compact upload summaries.
|
|
160
|
-
- Prefer existing icon components for upload, file type, success, loading, close, more, trash, and warning actions.
|
|
161
|
-
- Use a real progress indicator when the product can report upload progress; use the `uploading` label when progress is unknown.
|
|
162
|
-
- Truncate long file names in the middle or end, but keep the full file name available to assistive technology and tooltips.
|
|
163
|
-
- Avoid coupling RTL behavior to translated strings. Direction should come from `dir` or document context.
|
|
164
|
-
|
|
165
|
-
## Install
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
npx banhaten add file-upload
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
## Examples
|
|
172
|
-
|
|
173
|
-
Primary registry example: `examples/expanded/file-upload-demo.tsx`.
|
|
174
|
-
|
|
175
|
-
Open the live component page or run `npx banhaten docs file-upload` to inspect source files, install command, and examples.
|
|
176
|
-
|
|
177
|
-
## Token Contract
|
|
178
|
-
|
|
179
|
-
Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
|
|
180
|
-
Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
|
|
181
|
-
Covered source files: `components/expanded/fileUpload.css`, `components/expanded/FileUpload.tsx`.
|
|
182
|
-
|
|
183
|
-
## RTL Rules
|
|
184
|
-
|
|
185
|
-
This component has no special RTL contract beyond inherited document direction and logical spacing.
|
|
186
|
-
|
|
1
|
+
# File Upload
|
|
2
|
+
|
|
3
|
+
`FileUpload` lets people drag files into a drop zone, browse for files, and review queued upload items. Use it when the workflow supports one or more files and the user needs clear per-file status feedback.
|
|
4
|
+
|
|
5
|
+
Figma reference: `File upload`, node `254:3195`.
|
|
6
|
+
|
|
7
|
+
## Variants
|
|
8
|
+
|
|
9
|
+
The Figma component defines these top-level variants:
|
|
10
|
+
|
|
11
|
+
| Size | Direction |
|
|
12
|
+
| --- | --- |
|
|
13
|
+
| `lg` | LTR |
|
|
14
|
+
| `sm` | LTR |
|
|
15
|
+
| `lg` | RTL |
|
|
16
|
+
| `sm` | RTL |
|
|
17
|
+
|
|
18
|
+
Queued file rows define these states:
|
|
19
|
+
|
|
20
|
+
| State | Meaning |
|
|
21
|
+
| --- | --- |
|
|
22
|
+
| `uploaded` | The file finished uploading successfully. |
|
|
23
|
+
| `uploading` | The file is uploading and progress is unknown. |
|
|
24
|
+
| `uploading-progress` | The file is uploading and exposes a progress bar. |
|
|
25
|
+
| `error` | The file failed and needs a retry or removal action. |
|
|
26
|
+
|
|
27
|
+
## API
|
|
28
|
+
|
|
29
|
+
Use semantic names in code and let the implementation map them to the current appearance preset.
|
|
30
|
+
|
|
31
|
+
```ts
|
|
32
|
+
type FileUploadSize = "lg" | "sm";
|
|
33
|
+
type FileUploadVariant = "default" | "button";
|
|
34
|
+
type FileUploadDropzoneState = "default" | "hover";
|
|
35
|
+
type FileUploadItemStatus = "uploaded" | "uploading" | "uploading-progress" | "error";
|
|
36
|
+
|
|
37
|
+
type FileUploadFile = {
|
|
38
|
+
id: string;
|
|
39
|
+
name: string;
|
|
40
|
+
sizeLabel: string;
|
|
41
|
+
versionLabel?: string;
|
|
42
|
+
progress?: number;
|
|
43
|
+
progressLabel?: string;
|
|
44
|
+
extensionLabel?: string;
|
|
45
|
+
status: FileUploadItemStatus;
|
|
46
|
+
errorLabel?: string;
|
|
47
|
+
uploadedLabel?: string;
|
|
48
|
+
uploadLabel?: string;
|
|
49
|
+
};
|
|
50
|
+
|
|
51
|
+
type FileUploadProps = {
|
|
52
|
+
size?: FileUploadSize;
|
|
53
|
+
variant?: FileUploadVariant;
|
|
54
|
+
dropzoneState?: FileUploadDropzoneState;
|
|
55
|
+
dir?: "ltr" | "rtl" | "auto";
|
|
56
|
+
files?: FileUploadFile[];
|
|
57
|
+
title?: string;
|
|
58
|
+
prompt?: string;
|
|
59
|
+
browseLabel?: string;
|
|
60
|
+
helperText?: string;
|
|
61
|
+
disabled?: boolean;
|
|
62
|
+
accept?: string;
|
|
63
|
+
multiple?: boolean;
|
|
64
|
+
onBrowse?: () => void;
|
|
65
|
+
onDrop?: (files: FileList) => void;
|
|
66
|
+
onMore?: (fileId: string) => void;
|
|
67
|
+
onCancel?: (fileId: string) => void;
|
|
68
|
+
onRemove?: (fileId: string) => void;
|
|
69
|
+
onRetry?: (fileId: string) => void;
|
|
70
|
+
};
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`files` controls whether the queued file list renders. Do not expose a separate `hasFilesQueued` prop in production code; the rendered state should follow from the file array.
|
|
74
|
+
|
|
75
|
+
## Layout
|
|
76
|
+
|
|
77
|
+
- The root stacks the drop zone and queued file list vertically.
|
|
78
|
+
- Large width is 500px in the Figma source; small width is 343px. Implementations may use `width: 100%` with those values as max-widths.
|
|
79
|
+
- The default drop zone is 500px by 180px; the title-plus-button variant is 500px by 256px.
|
|
80
|
+
- The drop zone is centered, uses a 2px dashed border, and hover strengthens the border without changing the surface.
|
|
81
|
+
- The upload icon container is 48px square with a subtle border and the current control radius.
|
|
82
|
+
- Large file rows use 16px padding, a 40px file icon, and 12px gaps.
|
|
83
|
+
- Small file rows use 12px padding, a 32px file icon, and 8px gaps.
|
|
84
|
+
- Row actions are icon-only: more, close/cancel, and trash.
|
|
85
|
+
- The queued list uses a 12px vertical gap.
|
|
86
|
+
- RTL mode mirrors visual order and aligns file metadata to the end while preserving logical reading order.
|
|
87
|
+
|
|
88
|
+
## Tokens
|
|
89
|
+
|
|
90
|
+
The Figma source uses design tokens such as `bg/raised`, `interactive/secondary/default`, `border/subtle`, `border/danger/strong`, `space/*`, and `radius/*`. Implementations should map those to the design system's semantic token contract.
|
|
91
|
+
|
|
92
|
+
```ts
|
|
93
|
+
export const fileUploadTokens = {
|
|
94
|
+
dropzoneBackground: "background.subtle",
|
|
95
|
+
dropzoneBorder: "border.default",
|
|
96
|
+
dropzoneIconBackground: "background.default",
|
|
97
|
+
dropzoneIconBorder: "border.subtle",
|
|
98
|
+
rowBackground: "background.card",
|
|
99
|
+
rowBorder: "border.subtle",
|
|
100
|
+
rowErrorBorder: "border.danger",
|
|
101
|
+
rowElevation: "elevation.card",
|
|
102
|
+
textColor: "content.default",
|
|
103
|
+
helperTextColor: "content.subtle",
|
|
104
|
+
linkColor: "content.link",
|
|
105
|
+
successColor: "content.success",
|
|
106
|
+
dangerColor: "content.danger",
|
|
107
|
+
rowRadiusLarge: "shape.card",
|
|
108
|
+
rowRadiusSmall: "shape.control",
|
|
109
|
+
};
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Do not hard-code the Figma fallback values in component code. For example, the error state should resolve through `border.danger` and `content.danger`, not through the Figma fallback hex values.
|
|
113
|
+
|
|
114
|
+
## Behavior
|
|
115
|
+
|
|
116
|
+
- Clicking the browse text or drop zone should open the platform file picker.
|
|
117
|
+
- Dragging files over the drop zone should show the same target without changing the component API.
|
|
118
|
+
- `uploading` rows should expose a close/cancel action.
|
|
119
|
+
- `uploading-progress` rows should expose a real progress bar and percent label.
|
|
120
|
+
- `uploaded` rows should expose remove and overflow actions when the product has secondary file actions.
|
|
121
|
+
- `error` rows should expose remove and retry actions.
|
|
122
|
+
- The component should support both single-file and multi-file use through the `multiple` prop or equivalent platform API.
|
|
123
|
+
|
|
124
|
+
## Accessibility
|
|
125
|
+
|
|
126
|
+
- Use a real file input or a button connected to a file input.
|
|
127
|
+
- Preserve keyboard access for browse, cancel, remove, retry, and overflow actions.
|
|
128
|
+
- Announce upload status changes through an accessible live region when status changes after initial render.
|
|
129
|
+
- Keep file names as real text and avoid icon-only status communication.
|
|
130
|
+
- Icon-only actions need accessible labels such as `Cancel upload`, `Remove file`, `Retry upload`, and `More file actions`.
|
|
131
|
+
- The drop zone should not be the only way to select files.
|
|
132
|
+
|
|
133
|
+
## Usage
|
|
134
|
+
|
|
135
|
+
```tsx
|
|
136
|
+
<FileUpload
|
|
137
|
+
files={[
|
|
138
|
+
{ id: "1", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploaded" },
|
|
139
|
+
{ id: "2", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploading" },
|
|
140
|
+
{ id: "3", name: "file-name.pdf", sizeLabel: "32 KB", progress: 40, status: "uploading-progress" },
|
|
141
|
+
{ id: "4", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "error" },
|
|
142
|
+
]}
|
|
143
|
+
multiple
|
|
144
|
+
/>
|
|
145
|
+
|
|
146
|
+
<FileUpload size="sm" files={[{ id: "1", name: "file-name.pdf", sizeLabel: "32 KB", status: "uploaded" }]} />
|
|
147
|
+
|
|
148
|
+
<FileUpload dir="rtl" size="lg" />
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
## Preset Impact
|
|
152
|
+
|
|
153
|
+
- `default`: white rows on a subtle drop-zone background, modest radius, quiet shadow, and balanced spacing.
|
|
154
|
+
- `rounded`: softer drop-zone and row corners, slightly more padding, and gentler borders.
|
|
155
|
+
- `sharp`: square or near-square row treatment, denser spacing, stronger borders, and minimal row elevation.
|
|
156
|
+
|
|
157
|
+
## Implementation Notes
|
|
158
|
+
|
|
159
|
+
- Keep the drop zone and file row primitives separate so rows can be reused in compact upload summaries.
|
|
160
|
+
- Prefer existing icon components for upload, file type, success, loading, close, more, trash, and warning actions.
|
|
161
|
+
- Use a real progress indicator when the product can report upload progress; use the `uploading` label when progress is unknown.
|
|
162
|
+
- Truncate long file names in the middle or end, but keep the full file name available to assistive technology and tooltips.
|
|
163
|
+
- Avoid coupling RTL behavior to translated strings. Direction should come from `dir` or document context.
|
|
164
|
+
|
|
165
|
+
## Install
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
npx banhaten add file-upload
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Examples
|
|
172
|
+
|
|
173
|
+
Primary registry example: `examples/expanded/file-upload-demo.tsx`.
|
|
174
|
+
|
|
175
|
+
Open the live component page or run `npx banhaten docs file-upload` to inspect source files, install command, and examples.
|
|
176
|
+
|
|
177
|
+
## Token Contract
|
|
178
|
+
|
|
179
|
+
Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
|
|
180
|
+
Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
|
|
181
|
+
Covered source files: `components/expanded/fileUpload.css`, `components/expanded/FileUpload.tsx`.
|
|
182
|
+
|
|
183
|
+
## RTL Rules
|
|
184
|
+
|
|
185
|
+
This component has no special RTL contract beyond inherited document direction and logical spacing.
|
|
186
|
+
|
|
187
187
|
<!-- registry-contract:start -->
|
|
188
188
|
## Registry Contract
|
|
189
189
|
|
|
@@ -198,6 +198,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
|
|
|
198
198
|
| `modes` | `single`, `multiple` |
|
|
199
199
|
| `sizes` | `lg`, `sm` |
|
|
200
200
|
| `states` | `default`, `hover`, `disabled`, `uploaded`, `uploading`, `uploading-progress`, `error` |
|
|
201
|
-
| `tokens` | `--bh-bg-accent-amber-default`, `--bh-bg-accent-aqua-default`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-green-default`, `--bh-bg-accent-lime-default`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-default`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-link`, `--bh-content-link-hover`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-file-upload-content-max-width`, `--bh-file-upload-root-max-width`, `--bh-file-upload-spin-duration`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--bh-underline-offset-default`, `--
|
|
201
|
+
| `tokens` | `--bh-bg-accent-amber-default`, `--bh-bg-accent-aqua-default`, `--bh-bg-accent-blue-default`, `--bh-bg-accent-fuchsia-default`, `--bh-bg-accent-golden-default`, `--bh-bg-accent-green-default`, `--bh-bg-accent-lime-default`, `--bh-bg-accent-purple-default`, `--bh-bg-accent-red-default`, `--bh-bg-accent-rose-default`, `--bh-bg-accent-sky-base`, `--bh-bg-default`, `--bh-bg-dim`, `--bh-bg-neutral-default`, `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-bg-success-default`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-strong`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-border-width-strong`, `--bh-content-brand-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-link`, `--bh-content-link-hover`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-file-upload-content-max-width`, `--bh-file-upload-root-max-width`, `--bh-file-upload-spin-duration`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-bold`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-size-default`, `--bh-icon-stroke-200`, `--bh-icon-stroke-220`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-13xl-160`, `--bh-space-16xl-256`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-semibold-font-size`, `--bh-text-body-lg-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-line-height`, `--bh-underline-offset-default`, `--elevation-02`, `--elevation-component-default` |
|
|
202
202
|
| `variants` | `default`, `button` |
|
|
203
203
|
<!-- registry-contract:end -->
|