banhaten 0.1.1 → 0.1.3

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

@@ -0,0 +1,52 @@
+# Checkbox
+
+Checkbox is the binary selection primitive for forms, preferences, batch actions, and card-style options. It includes the base Radix checkbox control plus `CheckboxCard` for labeled option rows.
+
+## API
+
+```tsx
+<Checkbox aria-label="Accept terms" />
+
+<CheckboxCard
+  title="Email updates"
+  description="Receive product and billing notifications."
+  controlPosition="start"
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `checked` | Radix checkbox checked state |
+| `disabled` | `boolean` |
+| `CheckboxCard.controlPosition` | `start`, `end` |
+| `CheckboxCard.state` | default, selected, disabled |
+
+## Token Contract
+
+Checkbox consumes Banhaten control size, radius, component shadow, border, background, content, interactive, disabled, and typography tokens.
+
+## RTL
+
+`CheckboxCard` uses logical start/end control placement. Labels and descriptions use tokenized body text and `dir="auto"` for mixed Arabic and English copy.
+
+## Accessibility
+
+Use native labels or `aria-label` for standalone checkboxes. Prefer `CheckboxCard` when the selection target needs title and description text.
+
+## Install
+
+```bash
+npx banhaten add checkbox
+```
+
+## Examples
+
+Primary registry example: `examples/checkbox-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs checkbox` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `controlPlacement`: The card uses start/end control placement so the checkbox mirrors correctly in RTL.
+- `textDirection`: Labels and descriptions use dir="auto" and tokenized body-md/body-sm typography.

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

@@ -0,0 +1,48 @@
+# Collapsible
+
+Collapsible wraps Radix Collapsible for disclosure sections with Banhaten trigger and content styling.
+
+## API
+
+```tsx
+<Collapsible defaultOpen>
+  <CollapsibleTrigger>Workspace details</CollapsibleTrigger>
+  <CollapsibleContent>Billing and team settings.</CollapsibleContent>
+</Collapsible>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Collapsible` | Radix root |
+| `CollapsibleTrigger` | disclosure button |
+| `CollapsibleContent` | expandable content region |
+
+## Token Contract
+
+Collapsible uses Banhaten spacing, radius, body typography, ghost hover, focus, and content tokens.
+
+## RTL
+
+The trigger and content use logical text alignment and inherit document direction.
+
+## Accessibility
+
+Radix manages expanded state, trigger attributes, and content relationships.
+
+## Install
+
+```bash
+npx banhaten add collapsible
+```
+
+## Examples
+
+Primary registry example: `examples/collapsible-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs collapsible` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Trigger and content use logical text alignment and inherit direction.
+- `spacing`: Icon and label spacing uses flex gap so it mirrors with document direction.

package/docs/design-system/components/command-bar.md

@@ -0,0 +1,57 @@
+# Command Bar
+
+Command Bar gives users a keyboard-friendly command palette with search, recent items, filtered results, and empty states.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / CommandBar` (`259:4097`). It supports `default`, `recent`, `results`, and `no-result`; `desktop` and `mobile`; LTR and RTL.
+
+## API
+
+```tsx
+<CommandBar type="results" breakpoint="desktop" dir="ltr" />
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `type` | `default`, `recent`, `results`, `no-result` | `default` |
+| `breakpoint` | `desktop`, `mobile` | `desktop` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+
+## Token Contract
+
+The component consumes Banhaten semantic tokens and component aliases. Do not hard-code Figma fallback literals in component source; promote any Figma value into `registry/styles/globals.css` as a `--bh-*` token or alias first.
+
+- Backgrounds: `--bh-bg-raised`, `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`
+- Borders: `--bh-border-default`, `--bh-border-input`, `--bh-border-subtle`
+- Content: `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`
+- Shape: `--bh-radius-md-6`, `--bh-radius-lg-8`, `--bh-radius-3xl-16`, `--bh-radius-full`
+
+## Pixel Rules
+
+- Text is Inter `15px / 24px`; item descriptions are `12px / 16px`.
+- Desktop command bars are `640px` wide with `16px` radius and `Shadow/xl`.
+- Mobile command bars are `375px x 812px`, flush-edged, with an inset search field.
+- Desktop search rows are `60px` high; mobile search fields are `48px`.
+- Expanded desktop content uses a clipped results area and a `48px` footer for recent/results.
+- Result filters use `36px` chips with `12px` horizontal padding.
+- Items use `32px` leading visuals, `12px` gaps, and a `56px` minimum row height.
+- RTL mirrors row order and uses Arabic labels from the Figma variants.
+
+## Install
+
+```bash
+npx banhaten add command-bar
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/command-bar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs command-bar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.

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

@@ -0,0 +1,60 @@
+# Command
+
+Command is a cmdk-backed command menu with search input, grouped results, keyboard navigation, shortcuts, separators, and empty state.
+
+## API
+
+```tsx
+<Command>
+  <CommandInput />
+  <CommandList>
+    <CommandEmpty>No results found.</CommandEmpty>
+    <CommandGroup heading="Pages">
+      <CommandItem value="profile">
+        Profile
+        <CommandShortcut>⌘P</CommandShortcut>
+      </CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Command` | cmdk root |
+| `CommandInput` | search input |
+| `CommandList` | result list |
+| `CommandEmpty` | empty state |
+| `CommandGroup` | grouped results |
+| `CommandItem` | selectable command |
+| `CommandSeparator`, `CommandShortcut` | supporting row UI |
+
+## Token Contract
+
+Command uses Banhaten raised surface, menu shadow, border, ghost hover, body typography, muted content, and radius tokens.
+
+## RTL
+
+Command inherits direction. Labels and shortcuts use logical spacing.
+
+## Accessibility
+
+cmdk handles keyboard navigation and selection. Provide stable `value` props for dynamic items.
+
+## Install
+
+```bash
+npx banhaten add command
+```
+
+## Examples
+
+Primary registry example: `examples/command-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs command` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Command rows and shortcuts use logical spacing so shortcut placement mirrors naturally.
+- `textDirection`: Command copy inherits document direction; individual row labels can use dir="auto" when needed.

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

@@ -0,0 +1,44 @@
+# Context Menu
+
+Context Menu wraps Radix ContextMenu for right-click actions with labels, separators, submenus, checkboxes, radios, and shortcuts.
+
+## API
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger>Right click</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem>Open</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## Token Contract
+
+Context Menu reuses Banhaten menu width, item height, raised surface, hover, shadow, spacing, and typography tokens.
+
+## RTL
+
+Items and shortcuts use logical spacing. Directional submenu icons flip in RTL.
+
+## Accessibility
+
+Radix manages keyboard navigation, focus movement, item state, and submenu behavior.
+
+## Install
+
+```bash
+npx banhaten add context-menu
+```
+
+## Examples
+
+Primary registry example: `examples/context-menu-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs context-menu` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `directionalIconFlip`: Submenu chevrons flip in RTL.
+- `spacing`: Items and shortcuts use logical spacing.

package/docs/design-system/components/date-picker.md

@@ -0,0 +1,77 @@
+# Date Picker
+
+Date Picker is the calendar and range-selection suite for Banhaten forms. It covers single calendars, month/year views, double calendars, preset lists, date-picker triggers, date-range pickers, open/closed states, time rows, and RTL use cases.
+
+## Install
+
+```bash
+npx banhaten add date-picker
+```
+
+## Anatomy
+
+- `Calendar`: single calendar surface with day and month/year views.
+- `RangeCalendar`: single or double range calendar with optional preset list.
+- `DatePicker`: trigger plus single-date calendar surface.
+- `DateRangePicker`: trigger plus range calendar surface.
+- `DatePickerTrigger`: standalone tokenized trigger.
+
+## Example
+
+```tsx
+import { DatePicker, DateRangePicker } from "@/components/ui/date-picker"
+
+export function Example() {
+  return (
+    <div className="grid gap-4">
+      <DatePicker defaultOpen />
+      <DateRangePicker type="double" />
+    </div>
+  )
+}
+```
+
+## Variants
+
+| API | Values |
+| --- | --- |
+| `Calendar view` | `days`, `month-year` |
+| `RangeCalendar type` | `single`, `double`, `double-with-presets` |
+| `DatePicker state` | `open`, `closed` |
+| `dir` | inherited, `ltr`, `rtl` |
+
+## RTL
+
+The trigger, calendar header, preset list, day cells, range fill, and time rows use logical spacing and borders. Range endpoints keep their visual start/end rounding in both LTR and RTL.
+
+## API
+
+Public exports: `Calendar`, `RangeCalendar`, `DatePicker`, `DateRangePicker`, `DatePickerTrigger`.
+
+| Contract | Values |
+| --- | --- |
+| `modes` | `single-calendar`, `single-month-year`, `double-calendar`, `double-calendar-with-presets`, `single-range-calendar`, `date-picker`, `date-range-picker` |
+| `states` | `open`, `closed` |
+
+## Examples
+
+Primary registry example: `examples/date-picker-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs date-picker` 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/date-picker.tsx`, `components/date-picker-state.ts`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `triggerLayout`: The trigger uses inherited direction so the calendar icon and value mirror naturally.
+- `calendarLayout`: Calendar headers, range presets, date cells, and time rows use logical borders, spacing, and text alignment for LTR and RTL surfaces.
+- `rangeSelection`: Range fill uses logical start/end rounding for week edges and keeps selected endpoints tokenized with brand colors.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.

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

@@ -0,0 +1,101 @@
+# Divider
+
+Dividers, also called separators, separate related content without creating a new surface. `Divider` is the canonical separator primitive for plain horizontal and vertical rules.
+
+Figma reference: `Divider`, node `165:3111`.
+
+## Variants
+
+The component defines these variants:
+
+| Direction | Type |
+| --- | --- |
+| `horizontal` | `solid`, `dotted` |
+| `vertical` | `solid`, `dotted` |
+
+## API
+
+Use semantic names in code even if the Figma variant labels are title-cased.
+
+```ts
+type DividerDirection = "horizontal" | "vertical";
+type DividerType = "solid" | "dotted";
+
+type DividerProps = {
+  direction?: DividerDirection;
+  type?: DividerType;
+  decorative?: boolean;
+};
+```
+
+## Layout
+
+- Horizontal dividers render as a `1px` high rule with the Figma component length.
+- Vertical dividers render as a `1px` wide rule with the same tokenized length.
+- Dotted dividers use a 2px dash/gap rhythm from the number scale.
+- Direction does not require a separate RTL prop; plain separators are direction-neutral.
+
+## Tokens
+
+Dividers should consume existing semantic tokens:
+
+```ts
+export const dividerTokens = {
+  ruleColor: "border.subtle",
+  strokeWidth: "space.xxxs-1",
+  dash: "space.xxs-2",
+  length: "space.15xl-224",
+};
+```
+
+Do not hard-code the Figma fallback values in component code. The current Figma fallback for the rule is `rgba(55, 83, 122, 0.13)`, but the implementation should resolve through `border.subtle`.
+
+## Accessibility
+
+- Decorative divider lines should be hidden from assistive technology.
+- A standalone semantic separator may render as `<hr />` or `role="separator"` when it conveys structure.
+- Do not use the divider as the only indicator of a required grouping if the grouping needs a visible heading.
+
+## Usage
+
+```tsx
+<Divider />
+<Divider type="dotted" />
+<Divider direction="vertical" />
+<Divider decorative />
+```
+
+## Preset Impact
+
+- `default`: quiet 1px rule using `border.subtle`.
+- `rounded`: same rule weight; surrounding compositions may use softer radius tokens.
+- `sharp`: same rule weight; surrounding compositions may use square or near-square containers.
+
+## Implementation Notes
+
+- Prefer `border-top` or a 1px block rule instead of a filled rectangle.
+- Use `border-style: dashed` for the Figma dotted variant unless the platform has a distinct dotted token or renderer.
+- Compose labeled section breaks outside `Divider`; the core primitive should stay a small separator.
+
+## Install
+
+```bash
+npx banhaten add divider
+```
+
+## Examples
+
+Primary registry example: `examples/divider-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs divider` 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/divider.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: false
+- `geometry`: Direction maps to component orientation, not document text direction.

package/docs/design-system/components/empty-state.md

@@ -0,0 +1,55 @@
+# Empty State
+
+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.
+
+## API
+
+```tsx
+<EmptyState
+  title="No results found"
+  description="Try adjusting your search or filters"
+  actions={[
+    { label: "Reset filters", variant: "secondary" },
+    { label: "Create item" },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `title` | `ReactNode` | required |
+| `description` | `ReactNode` | none |
+| `icon` | `ReactNode` | `SearchIcon` |
+| `iconLabel` | `string` | decorative icon |
+| `actions` | `EmptyStateAction[]` | `[]` |
+| `align` | `center`, `start` | `center` |
+| `size` | `default`, `compact` | `default` |
+| `dir` | `ltr`, `rtl`, `auto` | `ltr` |
+
+## Token Contract
+
+- Icon halo: `--bh-bg-neutral-subtle`, `--bh-bg-neutral-soft`, `--bh-radius-full`
+- Title: `--bh-text-heading-xs-semibold-*`, `--bh-content-default`
+- Description: `--bh-text-body-md-regular-*`, `--bh-content-subtle`
+- Spacing and sizing: `--bh-space-*`
+- Actions: existing `Button` component variants and token contract
+
+## RTL Rules
+
+`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.
+
+## Install
+
+```bash
+npx banhaten add empty-state
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/empty-state-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs empty-state` to inspect source files, install command, and examples.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.

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.