banhaten 0.1.2 → 0.1.3

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

@@ -0,0 +1,69 @@
+# Field
+
+Field composes labels, controls, descriptions, and validation errors into accessible form rows. It gives Banhaten a shared form anatomy without forcing a validation library.
+
+## API
+
+```tsx
+<Field invalid>
+  <FieldLabel>Email</FieldLabel>
+  <FieldControl>
+    <Input state="error" />
+  </FieldControl>
+  <FieldError>Enter a valid email address.</FieldError>
+</Field>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Field` | row context, ids, invalid and disabled state |
+| `FieldLabel` | label connected to the control id |
+| `FieldControl` | `asChild` slot that wires id and ARIA state |
+| `FieldDescription` | helper text |
+| `FieldError` | validation message with alert role |
+| `FieldSet`, `FieldLegend`, `FieldGroup`, `FieldContent` | grouped form layout |
+
+## Validation Pattern
+
+Use native state for plain forms, or map your validation library state into `invalid`, `FieldError`, and the child control state.
+
+```tsx
+<Field invalid={Boolean(errors.email)}>
+  <FieldLabel>Email</FieldLabel>
+  <FieldControl>
+    <Input state={errors.email ? "error" : "default"} />
+  </FieldControl>
+  {errors.email ? <FieldError>{errors.email.message}</FieldError> : null}
+</Field>
+```
+
+## Token Contract
+
+Field uses Banhaten spacing, content, danger, field, typography, and disabled tokens. Child controls keep ownership of their own surface tokens.
+
+## RTL
+
+Field uses logical grid and text-start alignment. Horizontal and responsive orientations mirror naturally under inherited `dir`.
+
+## Install
+
+```bash
+npx banhaten add field
+```
+
+## Examples
+
+Primary registry example: `examples/field-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs field` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Vertical, horizontal, and responsive layouts use CSS grid and logical text alignment so field rows mirror naturally.
+- `textDirection`: Labels, descriptions, and errors use dir="auto" through Label and field text parts.
+- `semantics`: FieldControl wires the generated control id, invalid state, disabled announcement, and description/error ids into the child control.
+
+## Accessibility
+
+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.

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

@@ -0,0 +1,185 @@
+# 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.

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

@@ -0,0 +1,46 @@
+# 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.

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

@@ -0,0 +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.

package/docs/design-system/components/input-group.md

@@ -0,0 +1,56 @@
+# Input Group
+
+Input Group provides a tokenized shell for text inputs with protocol add-ons, prefixes, suffixes, and inline actions.
+
+## API
+
+```tsx
+<InputGroup>
+  <InputGroupAddon>https://</InputGroupAddon>
+  <InputGroupInput aria-label="Workspace URL" />
+  <InputGroupButton>Save</InputGroupButton>
+</InputGroup>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `InputGroup` | shared input shell |
+| `InputGroupAddon` | prefix or suffix content |
+| `InputGroupInput` | native input |
+| `InputGroupButton` | inline action |
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `lg` |
+| `variant` | `default`, `soft` |
+| `state` | `default`, `error` |
+
+## Token Contract
+
+Input Group reuses Banhaten input width, height, radius, border, shadow, typography, and focus tokens.
+
+## RTL
+
+Use logical add-on order. Border placement uses logical inline sides.
+
+## Accessibility
+
+Give `InputGroupInput` an accessible label through `aria-label`, `aria-labelledby`, or a surrounding Field.
+
+## Install
+
+```bash
+npx banhaten add input-group
+```
+
+## Examples
+
+Primary registry example: `examples/input-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input-group` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Add-ons and input segments use logical borders and inherited direction.
+- `textDirection`: Input text uses text-start so mixed Arabic and English values align naturally.

package/docs/design-system/components/input-otp.md

@@ -0,0 +1,55 @@
+# Input OTP
+
+Input OTP captures one-time passcodes and short verification codes. It reuses the Banhaten Input surface and typography while adding grouped slots, paste distribution, hidden form value, masking, custom length, and RTL-aware keyboard navigation.
+
+## API
+
+```tsx
+<InputOTP
+  label="Verification code"
+  length={6}
+  name="code"
+  onValueChange={setCode}
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `value`, `defaultValue` | controlled or uncontrolled string |
+| `length` | slot count |
+| `groupPattern` | array of slot group sizes |
+| `masked` | `boolean` |
+| `variant` | `default`, `soft` |
+| `size` | `md`, `lg` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+
+## Token Contract
+
+Input OTP uses Input field tokens for surfaces, typography, focus, border, error, helper text, labels, slot gaps, and disabled states.
+
+## RTL
+
+Slot groups inherit direction. Arrow navigation mirrors in RTL so visual previous and next follow the rendered direction.
+
+## Accessibility
+
+Provide a clear label and helper text describing how many digits are expected. The hidden form value lets the component participate in standard form submission.
+
+## Install
+
+```bash
+npx banhaten add input-otp
+```
+
+## Examples
+
+Primary registry example: `examples/input-otp-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input-otp` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `keyboard`: Arrow navigation mirrors for RTL: visual previous and next follow the inherited direction.
+- `spacing`: Slot groups, separators, labels, and helper text use inherited direction plus Input spacing tokens.
+- `composition`: Each slot reuses the Banhaten Input surface and control typography instead of a separate field style.

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

@@ -0,0 +1,48 @@
+# Input
+
+Input is the text-entry field primitive for forms, filters, search, numeric entry, tags, shortcuts, add-ons, and action-adorned fields. It supports default and soft variants, md/lg sizing, helper and error text, and RTL-safe slot placement.
+
+## API
+
+```tsx
+<Input label="Email" placeholder="name@example.com" />
+<Input state="error" label="Amount" message="Enter a valid amount" />
+```
+
+| Prop | Values |
+| --- | --- |
+| `kind` | `default`, `shortcut`, `add-on`, `inline-add-on`, `tags`, `inline-tags`, `trailing-dropdown`, `leading-dropdown`, `quantity`, `quantity-2`, `trailing-button`, `leading-button` |
+| `variant` | `default`, `soft` |
+| `size` | `md`, `lg` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+| `label`, `message` | `ReactNode` |
+
+## Token Contract
+
+Input consumes Banhaten field, control, typography, spacing, border, radius, content, disabled, error, and focus tokens. Add-on and button segments should use logical borders and shared field tokens.
+
+## RTL
+
+Input uses logical start/end slots and `text-start`. Labels, values, add-ons, tags, and helper text use `dir="auto"` where string copy is rendered.
+
+## Accessibility
+
+Connect labels and helper/error text through the component props when possible. Use `state="error"` with visible error copy instead of relying only on red borders.
+
+## Install
+
+```bash
+npx banhaten add input
+```
+
+## Examples
+
+Primary registry example: `examples/input-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English labels, values, add-ons, tags, and helper text align naturally.
+- `spacing`: Uses logical start/end borders and inherited direction so leading and trailing segments mirror in RTL.

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

@@ -0,0 +1,44 @@
+# Kbd
+
+Kbd renders compact keyboard hints for shortcuts, command rows, and form help text.
+
+## API
+
+```tsx
+<Kbd>⌘</Kbd>
+<Kbd>K</Kbd>
+<Kbd size="md">Shift</Kbd>
+```
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `md` |
+
+## Token Contract
+
+Kbd uses Banhaten border, soft interactive background, radius, body-xs typography, and button shadow tokens.
+
+## RTL
+
+Kbd is direction-neutral. Use surrounding text direction for shortcut descriptions.
+
+## Accessibility
+
+Use Kbd as supporting text, not as the only label for an action.
+
+## Install
+
+```bash
+npx banhaten add kbd
+```
+
+## Examples
+
+Primary registry example: `examples/kbd-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs kbd` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `semantics`: Kbd is direction-neutral and should be paired with surrounding text labels.

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

@@ -0,0 +1,48 @@
+# Label
+
+Label renders accessible control labels with Banhaten typography, required markers, optional text, tone variants, and RTL-safe copy. It is backed by Radix Label.
+
+## API
+
+```tsx
+<Label htmlFor="email" required>
+  Email address
+</Label>
+```
+
+| Prop | Values |
+| --- | --- |
+| `htmlFor` | target control id |
+| `tone` | `default`, `subtle`, `danger` |
+| `required` | `boolean` |
+| `optionalText` | `ReactNode` |
+
+## Token Contract
+
+Label consumes Banhaten body-sm, body-xs, content, danger, spacing, and disabled-state tokens.
+
+## RTL
+
+Label uses logical inline spacing and `dir="auto"` for label and optional text.
+
+## Accessibility
+
+Use `htmlFor` for native controls. For complete form rows with description and error text, use `Field`.
+
+## Install
+
+```bash
+npx banhaten add label
+```
+
+## Examples
+
+Primary registry example: `examples/label-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs label` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Label and optional text use dir="auto" so Arabic and English labels resolve naturally.
+- `spacing`: Uses logical inline spacing between label text, required marker, and optional text.

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

@@ -0,0 +1,59 @@
+# Menu
+
+Menu is a Radix DropdownMenu-backed action surface for contextual commands, navigation, progress rows, labels, captions, call-to-action rows, submenus, and rich item media.
+
+## API
+
+```tsx
+<MenuRoot>
+  <MenuTrigger>Open menu</MenuTrigger>
+  <MenuContent width="menu">
+    <MenuItem>Profile</MenuItem>
+    <MenuSeparator />
+    <MenuItem kind="button">Upgrade plan</MenuItem>
+  </MenuContent>
+</MenuRoot>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuPortal` | Radix-backed menu shell |
+| `MenuItem`, `MenuItemContent`, media slots | interactive rows |
+| `MenuSub`, `MenuSubTrigger`, `MenuSubContent` | nested menus |
+| `MenuLabel`, `MenuCaption`, `MenuSeparator` | non-interactive structure |
+
+| Prop | Values |
+| --- | --- |
+| `width` | `menu`, `default`, `multiline`, `action`, `auto` |
+| `kind` | `default`, `multiline`, `action`, `progress`, `button` |
+
+## Token Contract
+
+Menu uses Banhaten raised surface, menu shadow, item typography, border, radius, spacing, progress, badge, switch, and focus tokens.
+
+## RTL
+
+Menu uses logical padding and flex direction so leading icons, trailing actions, badges, switches, meta text, and submenus mirror naturally. Directional icons should use `data-rtl-flip="true"`.
+
+## Accessibility
+
+Radix provides menu roles, focus management, typeahead, keyboard navigation, Escape handling, and outside dismissal. Keep non-command copy in labels or captions, not disabled menu items.
+
+## Install
+
+```bash
+npx banhaten add menu
+```
+
+## Examples
+
+Primary registry example: `examples/menu-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs menu` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical padding and flex direction so leading, trailing, badge, switch, right text, and action slots mirror naturally.
+- `directionalIconFlip`: Use data-rtl-flip="true" on chevrons and arrows that should mirror.
+- `textDirection`: Text slots use dir="auto" by default for Arabic and English labels.