banhaten 0.5.0 → 0.6.0

package/docs/design-system/components/file-upload.md

@@ -1,189 +1,189 @@
-# File Upload
-
-`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.
-
-Figma reference: `File upload`, node `254:3195`.
-
-## Variants
-
-The Figma component defines these top-level variants:
-
-| Size | Direction |
-| --- | --- |
-| `lg` | LTR |
-| `sm` | LTR |
-| `lg` | RTL |
-| `sm` | RTL |
-
-Queued file rows define these states:
-
-| State | Meaning |
-| --- | --- |
-| `uploaded` | The file finished uploading successfully. |
-| `uploading` | The file is uploading and progress is unknown. |
-| `uploading-progress` | The file is uploading and exposes a progress bar. |
-| `error` | The file failed and needs a retry or removal action. |
-
-## API
-
-Use semantic names in code and let the implementation map them to the current appearance preset.
-
-```ts
-type FileUploadSize = "lg" | "sm";
-type FileUploadVariant = "default" | "button";
-type FileUploadDropzoneState = "default" | "hover";
-type FileUploadItemStatus = "uploaded" | "uploading" | "uploading-progress" | "error";
-
-type FileUploadFile = {
-  id: string;
-  name: string;
-  sizeLabel: string;
-  versionLabel?: string;
-  progress?: number;
-  progressLabel?: string;
-  extensionLabel?: string;
-  status: FileUploadItemStatus;
-  errorLabel?: string;
-  uploadedLabel?: string;
-  uploadLabel?: string;
-};
-
-type FileUploadProps = {
-  size?: FileUploadSize;
-  variant?: FileUploadVariant;
-  dropzoneState?: FileUploadDropzoneState;
-  dir?: "ltr" | "rtl" | "auto";
-  files?: FileUploadFile[];
-  title?: string;
-  prompt?: string;
-  browseLabel?: string;
-  helperText?: string;
-  disabled?: boolean;
-  accept?: string;
-  multiple?: boolean;
-  onBrowse?: () => void;
-  onDrop?: (files: FileList) => void;
-  onMore?: (fileId: string) => void;
-  onCancel?: (fileId: string) => void;
-  onRemove?: (fileId: string) => void;
-  onRetry?: (fileId: string) => void;
-};
-```
-
-`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.
-
-## Layout
-
-- The root stacks the drop zone and queued file list vertically.
-- Large width is 500px in the Figma source; small width is 343px. Implementations may use `width: 100%` with those values as max-widths.
-- The default drop zone is 500px by 180px; the title-plus-button variant is 500px by 256px.
-- The drop zone is centered, uses a 2px dashed border, and hover strengthens the border without changing the surface.
-- The upload icon container is 48px square with a subtle border and the current control radius.
-- Large file rows use 16px padding, a 40px file icon, and 12px gaps.
-- Small file rows use 12px padding, a 32px file icon, and 8px gaps.
-- Row actions are icon-only: more, close/cancel, and trash.
-- The queued list uses a 12px vertical gap.
-- RTL mode mirrors visual order and aligns file metadata to the end while preserving logical reading order.
-
-## Tokens
-
-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.
-
-```ts
-export const fileUploadTokens = {
-  dropzoneBackground: "background.subtle",
-  dropzoneBorder: "border.default",
-  dropzoneIconBackground: "background.default",
-  dropzoneIconBorder: "border.subtle",
-  rowBackground: "background.card",
-  rowBorder: "border.subtle",
-  rowErrorBorder: "border.danger",
-  rowElevation: "elevation.card",
-  textColor: "content.default",
-  helperTextColor: "content.subtle",
-  linkColor: "content.link",
-  successColor: "content.success",
-  dangerColor: "content.danger",
-  rowRadiusLarge: "shape.card",
-  rowRadiusSmall: "shape.control",
-};
-```
-
-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.
-
-## Behavior
-
-- Clicking the browse text or drop zone should open the platform file picker.
-- Dragging files over the drop zone should show the same target without changing the component API.
-- `uploading` rows should expose a close/cancel action.
-- `uploading-progress` rows should expose a real progress bar and percent label.
-- `uploaded` rows should expose remove and overflow actions when the product has secondary file actions.
-- `error` rows should expose remove and retry actions.
-- The component should support both single-file and multi-file use through the `multiple` prop or equivalent platform API.
-
-## Accessibility
-
-- Use a real file input or a button connected to a file input.
-- Preserve keyboard access for browse, cancel, remove, retry, and overflow actions.
-- Announce upload status changes through an accessible live region when status changes after initial render.
-- Keep file names as real text and avoid icon-only status communication.
-- Icon-only actions need accessible labels such as `Cancel upload`, `Remove file`, `Retry upload`, and `More file actions`.
-- The drop zone should not be the only way to select files.
-
-## Usage
-
-```tsx
-<FileUpload
-  files={[
-    { id: "1", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploaded" },
-    { id: "2", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploading" },
-    { id: "3", name: "file-name.pdf", sizeLabel: "32 KB", progress: 40, status: "uploading-progress" },
-    { id: "4", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "error" },
-  ]}
-  multiple
-/>
-
-<FileUpload size="sm" files={[{ id: "1", name: "file-name.pdf", sizeLabel: "32 KB", status: "uploaded" }]} />
-
-<FileUpload dir="rtl" size="lg" />
-```
-
-## Preset Impact
-
-- `default`: white rows on a subtle drop-zone background, modest radius, quiet shadow, and balanced spacing.
-- `rounded`: softer drop-zone and row corners, slightly more padding, and gentler borders.
-- `sharp`: square or near-square row treatment, denser spacing, stronger borders, and minimal row elevation.
-
-## Implementation Notes
-
-- Keep the drop zone and file row primitives separate so rows can be reused in compact upload summaries.
-- Prefer existing icon components for upload, file type, success, loading, close, more, trash, and warning actions.
-- Use a real progress indicator when the product can report upload progress; use the `uploading` label when progress is unknown.
-- Truncate long file names in the middle or end, but keep the full file name available to assistive technology and tooltips.
-- Avoid coupling RTL behavior to translated strings. Direction should come from `dir` or document context.
-
-## Install
-
-```bash
-npx banhaten add file-upload
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/file-upload-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs file-upload` to inspect source files, install command, and examples.
-
-## Token Contract
-
-Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
-Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
-Covered source files: `components/expanded/fileUpload.css`, `components/expanded/FileUpload.tsx`.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
-
+# File Upload
+
+`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.
+
+Figma reference: `File upload`, node `254:3195`.
+
+## Variants
+
+The Figma component defines these top-level variants:
+
+| Size | Direction |
+| --- | --- |
+| `lg` | LTR |
+| `sm` | LTR |
+| `lg` | RTL |
+| `sm` | RTL |
+
+Queued file rows define these states:
+
+| State | Meaning |
+| --- | --- |
+| `uploaded` | The file finished uploading successfully. |
+| `uploading` | The file is uploading and progress is unknown. |
+| `uploading-progress` | The file is uploading and exposes a progress bar. |
+| `error` | The file failed and needs a retry or removal action. |
+
+## API
+
+Use semantic names in code and let the implementation map them to the current appearance preset.
+
+```ts
+type FileUploadSize = "lg" | "sm";
+type FileUploadVariant = "default" | "button";
+type FileUploadDropzoneState = "default" | "hover";
+type FileUploadItemStatus = "uploaded" | "uploading" | "uploading-progress" | "error";
+
+type FileUploadFile = {
+  id: string;
+  name: string;
+  sizeLabel: string;
+  versionLabel?: string;
+  progress?: number;
+  progressLabel?: string;
+  extensionLabel?: string;
+  status: FileUploadItemStatus;
+  errorLabel?: string;
+  uploadedLabel?: string;
+  uploadLabel?: string;
+};
+
+type FileUploadProps = {
+  size?: FileUploadSize;
+  variant?: FileUploadVariant;
+  dropzoneState?: FileUploadDropzoneState;
+  dir?: "ltr" | "rtl" | "auto";
+  files?: FileUploadFile[];
+  title?: string;
+  prompt?: string;
+  browseLabel?: string;
+  helperText?: string;
+  disabled?: boolean;
+  accept?: string;
+  multiple?: boolean;
+  onBrowse?: () => void;
+  onDrop?: (files: FileList) => void;
+  onMore?: (fileId: string) => void;
+  onCancel?: (fileId: string) => void;
+  onRemove?: (fileId: string) => void;
+  onRetry?: (fileId: string) => void;
+};
+```
+
+`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.
+
+## Layout
+
+- The root stacks the drop zone and queued file list vertically.
+- Large width is 500px in the Figma source; small width is 343px. Implementations may use `width: 100%` with those values as max-widths.
+- The default drop zone is 500px by 180px; the title-plus-button variant is 500px by 256px.
+- The drop zone is centered, uses a 2px dashed border, and hover strengthens the border without changing the surface.
+- The upload icon container is 48px square with a subtle border and the current control radius.
+- Large file rows use 16px padding, a 40px file icon, and 12px gaps.
+- Small file rows use 12px padding, a 32px file icon, and 8px gaps.
+- Row actions are icon-only: more, close/cancel, and trash.
+- The queued list uses a 12px vertical gap.
+- RTL mode mirrors visual order and aligns file metadata to the end while preserving logical reading order.
+
+## Tokens
+
+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.
+
+```ts
+export const fileUploadTokens = {
+  dropzoneBackground: "background.subtle",
+  dropzoneBorder: "border.default",
+  dropzoneIconBackground: "background.default",
+  dropzoneIconBorder: "border.subtle",
+  rowBackground: "background.card",
+  rowBorder: "border.subtle",
+  rowErrorBorder: "border.danger",
+  rowElevation: "elevation.card",
+  textColor: "content.default",
+  helperTextColor: "content.subtle",
+  linkColor: "content.link",
+  successColor: "content.success",
+  dangerColor: "content.danger",
+  rowRadiusLarge: "shape.card",
+  rowRadiusSmall: "shape.control",
+};
+```
+
+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.
+
+## Behavior
+
+- Clicking the browse text or drop zone should open the platform file picker.
+- Dragging files over the drop zone should show the same target without changing the component API.
+- `uploading` rows should expose a close/cancel action.
+- `uploading-progress` rows should expose a real progress bar and percent label.
+- `uploaded` rows should expose remove and overflow actions when the product has secondary file actions.
+- `error` rows should expose remove and retry actions.
+- The component should support both single-file and multi-file use through the `multiple` prop or equivalent platform API.
+
+## Accessibility
+
+- Use a real file input or a button connected to a file input.
+- Preserve keyboard access for browse, cancel, remove, retry, and overflow actions.
+- Announce upload status changes through an accessible live region when status changes after initial render.
+- Keep file names as real text and avoid icon-only status communication.
+- Icon-only actions need accessible labels such as `Cancel upload`, `Remove file`, `Retry upload`, and `More file actions`.
+- The drop zone should not be the only way to select files.
+
+## Usage
+
+```tsx
+<FileUpload
+  files={[
+    { id: "1", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploaded" },
+    { id: "2", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "uploading" },
+    { id: "3", name: "file-name.pdf", sizeLabel: "32 KB", progress: 40, status: "uploading-progress" },
+    { id: "4", name: "file-name.pdf", sizeLabel: "32mb", versionLabel: "v1.2.2", status: "error" },
+  ]}
+  multiple
+/>
+
+<FileUpload size="sm" files={[{ id: "1", name: "file-name.pdf", sizeLabel: "32 KB", status: "uploaded" }]} />
+
+<FileUpload dir="rtl" size="lg" />
+```
+
+## Preset Impact
+
+- `default`: white rows on a subtle drop-zone background, modest radius, quiet shadow, and balanced spacing.
+- `rounded`: softer drop-zone and row corners, slightly more padding, and gentler borders.
+- `sharp`: square or near-square row treatment, denser spacing, stronger borders, and minimal row elevation.
+
+## Implementation Notes
+
+- Keep the drop zone and file row primitives separate so rows can be reused in compact upload summaries.
+- Prefer existing icon components for upload, file type, success, loading, close, more, trash, and warning actions.
+- Use a real progress indicator when the product can report upload progress; use the `uploading` label when progress is unknown.
+- Truncate long file names in the middle or end, but keep the full file name available to assistive technology and tooltips.
+- Avoid coupling RTL behavior to translated strings. Direction should come from `dir` or document context.
+
+## Install
+
+```bash
+npx banhaten add file-upload
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/file-upload-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs file-upload` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/fileUpload.css`, `components/expanded/FileUpload.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

package/docs/design-system/components/hover-card.md

@@ -1,50 +1,50 @@
-# Hover Card
-
-Hover Card wraps Radix HoverCard for rich preview content on hover and focus.
-
-## API
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger>Workspace profile</HoverCardTrigger>
-  <HoverCardContent>Preview content</HoverCardContent>
-</HoverCard>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `HoverCard`, `HoverCardTrigger`, `HoverCardPortal` | Radix shell |
-| `HoverCardContent` | tokenized preview surface |
-
-## Token Contract
-
-Hover Card uses Banhaten raised background, popover shadow, radius, spacing, and content tokens.
-
-## RTL
-
-Content inherits direction and uses logical text alignment.
-
-## Accessibility
-
-Radix manages hover/focus timing and content relationships.
-
-## Install
-
-```bash
-npx banhaten add hover-card
-```
-
-## Examples
-
-Primary registry example: `examples/hover-card-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs hover-card` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textDirection`: Content inherits direction and uses logical text alignment.
-
+# Hover Card
+
+Hover Card wraps Radix HoverCard for rich preview content on hover and focus.
+
+## API
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>Workspace profile</HoverCardTrigger>
+  <HoverCardContent>Preview content</HoverCardContent>
+</HoverCard>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `HoverCard`, `HoverCardTrigger`, `HoverCardPortal` | Radix shell |
+| `HoverCardContent` | tokenized preview surface |
+
+## Token Contract
+
+Hover Card uses Banhaten raised background, popover shadow, radius, spacing, and content tokens.
+
+## RTL
+
+Content inherits direction and uses logical text alignment.
+
+## Accessibility
+
+Radix manages hover/focus timing and content relationships.
+
+## Install
+
+```bash
+npx banhaten add hover-card
+```
+
+## Examples
+
+Primary registry example: `examples/hover-card-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs hover-card` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Content inherits direction and uses logical text alignment.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

package/docs/design-system/components/icons.md

@@ -1,48 +1,48 @@
-# Icons
-
-Icons is an expanded-tier explorer for reviewing open-source icon packs, semantic mappings, shortlist comparisons, and Iconify catalog options.
-
-## API
-
-```tsx
-<IconExplorer />
-```
-
-| Feature | Notes |
-| --- | --- |
-| Icon pack review | compares candidate open-source packs |
-| Semantic mapping | maps product concepts to icon candidates |
-| Shortlist comparison | supports side-by-side review |
-| Iconify inspection | loads Iconify catalog data at runtime |
-
-## Runtime
-
-The explorer may load `https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js` and query `https://api.iconify.design`.
-
-## Token Contract
-
-The explorer uses expanded-tier CSS plus Banhaten surface, typography, border, spacing, focus, and content tokens. Product components should still use their local icon contracts instead of depending on this explorer.
-
-## RTL
-
-Explorer layout should inherit page direction for navigation, labels, and comparison rows. Icon glyphs themselves should only mirror when they are directional.
-
-## Accessibility
-
-Icon candidates must be reviewed for accessible usage. Decorative icons should be hidden with `aria-hidden`; actionable icon-only controls need clear accessible names.
-
-## Install
-
-```bash
-npx banhaten add icons
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/icons-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs icons` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
+# Icons
+
+Icons is an expanded-tier explorer for reviewing open-source icon packs, semantic mappings, shortlist comparisons, and Iconify catalog options.
+
+## API
+
+```tsx
+<IconExplorer />
+```
+
+| Feature | Notes |
+| --- | --- |
+| Icon pack review | compares candidate open-source packs |
+| Semantic mapping | maps product concepts to icon candidates |
+| Shortlist comparison | supports side-by-side review |
+| Iconify inspection | loads Iconify catalog data at runtime |
+
+## Runtime
+
+The explorer may load `https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js` and query `https://api.iconify.design`.
+
+## Token Contract
+
+The explorer uses expanded-tier CSS plus Banhaten surface, typography, border, spacing, focus, and content tokens. Product components should still use their local icon contracts instead of depending on this explorer.
+
+## RTL
+
+Explorer layout should inherit page direction for navigation, labels, and comparison rows. Icon glyphs themselves should only mirror when they are directional.
+
+## Accessibility
+
+Icon candidates must be reviewed for accessible usage. Decorative icons should be hidden with `aria-hidden`; actionable icon-only controls need clear accessible names.
+
+## Install
+
+```bash
+npx banhaten add icons
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/icons-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs icons` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.