banhaten 0.1.1 → 0.1.3

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

@@ -0,0 +1,55 @@
+# Radio Group
+
+Radio Group is the native-input single-choice primitive. It includes `Radio`, `RadioField`, `RadioGroup`, and `RadioGroupItem` for grouped labels, descriptions, errors, disabled state, controlled or uncontrolled values, and horizontal or vertical layout.
+
+## API
+
+```tsx
+<RadioGroup
+  label="Billing interval"
+  defaultValue="monthly"
+  orientation="vertical"
+>
+  <RadioGroupItem value="monthly" label="Monthly" />
+  <RadioGroupItem value="annual" label="Annual" />
+</RadioGroup>
+```
+
+| Prop | Values |
+| --- | --- |
+| `value`, `defaultValue` | controlled or uncontrolled value |
+| `orientation` | `vertical`, `horizontal` |
+| `state` | `default`, `error`, `disabled` |
+| `label`, `description`, `errorMessage` | `ReactNode` |
+| `controlPosition` | `start`, `end` on field/item rows |
+
+## Token Contract
+
+Radio Group uses Banhaten radio control, field gap, group spacing, text, helper, error, disabled, border, and focus tokens.
+
+## RTL
+
+`RadioField` and `RadioGroupItem` use logical start/end control placement. Labels, descriptions, and error text use `dir="auto"` and tokenized typography.
+
+## Accessibility
+
+The group uses `fieldset`, shared native radio names, label wrapping, and platform keyboard behavior. Provide visible error text when the group is invalid.
+
+## Install
+
+```bash
+npx banhaten add radio-group
+```
+
+## Examples
+
+Primary registry example: `examples/radio-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs radio-group` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `controlPlacement`: RadioField and RadioGroupItem use start/end control placement so the radio mirrors correctly in RTL.
+- `textDirection`: Group labels, item labels, descriptions, and error text use dir="auto" with tokenized body typography.
+- `semantics`: Uses native radio inputs with a shared group name, fieldset grouping, and label wrapping for platform keyboard and form behavior.

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

@@ -0,0 +1,42 @@
+# Resizable
+
+Resizable wraps `react-resizable-panels` for split panes and workbench layouts.
+
+## API
+
+```tsx
+<ResizablePanelGroup direction="horizontal">
+  <ResizablePanel defaultSize={30}>Sidebar</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={70}>Content</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+## Token Contract
+
+Resizable uses Banhaten border, focus, raised surface, radius, and icon sizing tokens.
+
+## RTL
+
+Panel order follows DOM order. Use logical layout around the panel group for RTL shells.
+
+## Accessibility
+
+`react-resizable-panels` provides keyboard-adjustable resize handles.
+
+## Install
+
+```bash
+npx banhaten add resizable
+```
+
+## Examples
+
+Primary registry example: `examples/resizable-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs resizable` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `layout`: Panel order follows DOM order; use logical shell layout for RTL workspaces.

package/docs/design-system/components/scroll-area.md

@@ -0,0 +1,45 @@
+# Scroll Area
+
+Scroll Area wraps Radix ScrollArea with tokenized viewport, scrollbar, thumb, and corner styling.
+
+## API
+
+```tsx
+<ScrollArea className="h-48">
+  <div>Scrollable content</div>
+</ScrollArea>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `ScrollArea` | root and viewport |
+| `ScrollBar` | vertical or horizontal scrollbar |
+
+## Token Contract
+
+Scroll Area uses Banhaten radius, border, and neutral thumb tokens.
+
+## RTL
+
+Scroll Area inherits direction from its parent. Use logical padding inside the viewport content.
+
+## Accessibility
+
+Use Scroll Area for visual scrollbars around already accessible content, not for hiding essential controls.
+
+## Install
+
+```bash
+npx banhaten add scroll-area
+```
+
+## Examples
+
+Primary registry example: `examples/scroll-area-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs scroll-area` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Viewport content should use logical padding so scrollable regions mirror with document direction.

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

@@ -0,0 +1,50 @@
+# Select
+
+Select is a Radix Select-backed field and menu system. It supports default and soft trigger styles, md/lg sizing, error, filled and disabled states, menu surfaces, checkbox or check selection, and item media for text, icons, avatars, companies, payment methods, and status dots.
+
+## API
+
+```tsx
+<Select label="Country" placeholder="Choose country">
+  <SelectMenuItem value="eg">Egypt</SelectMenuItem>
+  <SelectMenuItem value="sa">Saudi Arabia</SelectMenuItem>
+</Select>
+```
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `default`, `soft` |
+| `size` | `lg`, `md` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+| `itemType` | `default`, `icon`, `avatar`, `company`, `payment`, `dot` |
+| `selectionType` | `default`, `checkbox` |
+
+## Token Contract
+
+Select consumes Banhaten field, trigger, menu, item, checkbox, status, avatar, payment, typography, spacing, border, radius, shadow, and focus tokens.
+
+## RTL
+
+Values, labels, helper text, and menu item text use `text-start` and `dir="auto"`. Trigger icons and selected checks use logical placement so they mirror in RTL.
+
+## Accessibility
+
+Radix provides listbox semantics, focus management, typeahead, selection state, and keyboard behavior. Use visible helper or error text for validation states.
+
+## Install
+
+```bash
+npx banhaten add select
+```
+
+## Examples
+
+Primary registry example: `examples/select-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs select` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" for values, labels, helper text, and menu item text.
+- `spacing`: Uses logical padding, start/end positioning, and inherited flex direction so trigger icons and selected checks mirror in RTL.

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

@@ -0,0 +1,65 @@
+# Sheet
+
+Sheet is a Radix Dialog-based side or edge panel for contextual workflows that need more room than a popover but less interruption than a full modal. It supports logical `start` and `end` sides for RTL, plus top and bottom placements.
+
+## API
+
+```tsx
+<Sheet>
+  <SheetTrigger asChild>
+    <Button>Open settings</Button>
+  </SheetTrigger>
+  <SheetContent side="end">
+    <SheetHeader>
+      <SheetTitle>Workspace settings</SheetTitle>
+      <SheetDescription>Update billing and access controls.</SheetDescription>
+    </SheetHeader>
+    <SheetBody>...</SheetBody>
+    <SheetFooter>...</SheetFooter>
+  </SheetContent>
+</Sheet>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `Sheet`, `SheetTrigger`, `SheetClose`, `SheetPortal` | Radix Dialog shell |
+| `SheetOverlay`, `SheetContent` | overlay and trapped panel |
+| `SheetHeader`, `SheetTitle`, `SheetDescription` | accessible heading area |
+| `SheetBody`, `SheetFooter` | scrollable content and actions |
+
+| Prop | Values |
+| --- | --- |
+| `side` | `start`, `end`, `top`, `bottom` |
+| `size` | `sm`, `default`, `lg` |
+| `showCloseButton` | `boolean` |
+
+## Token Contract
+
+Sheet uses Banhaten overlay, raised surface, border, radius, shadow, spacing, typography, focus, and content tokens.
+
+## RTL
+
+Use `side="start"` and `side="end"` instead of physical left/right placement. CSS logical edges place the panel on the right edge in LTR for `end`, and on the left edge in RTL.
+
+## Accessibility
+
+Radix Dialog provides focus trap, Escape dismissal, outside dismissal, title/description wiring, and modal dialog semantics. Use Alert Dialog for destructive confirmations.
+
+## Install
+
+```bash
+npx banhaten add sheet
+```
+
+## Examples
+
+Primary registry example: `examples/sheet-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs sheet` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: Use side="start" and side="end" for logical placement; CSS start/end edges mirror under RTL.
+- `textDirection`: Title and description use dir="auto" for Arabic and English copy.
+- `semantics`: Radix Dialog handles modal semantics, focus trapping, and dismissal.

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

@@ -0,0 +1,68 @@
+# Sidebar
+
+Sidebar is a composable app navigation surface with collapse state, grouped menu items, logical start/end placement, and generated `--bh-sidebar-*` tokens.
+
+## API
+
+```tsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>
+      Workspace
+      <SidebarToggle />
+    </SidebarHeader>
+    <SidebarBody>
+      <SidebarGroup>
+        <SidebarGroupLabel>Main</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton active>Overview</SidebarMenuButton>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarBody>
+  </Sidebar>
+</SidebarProvider>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `SidebarProvider` | controlled or uncontrolled collapsed state |
+| `Sidebar` | navigation surface |
+| `SidebarHeader`, `SidebarBody`, `SidebarFooter` | layout regions |
+| `SidebarGroup`, `SidebarGroupLabel` | grouped navigation |
+| `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton` | menu structure |
+| `SidebarToggle`, `SidebarRail` | collapse controls |
+| `SidebarTrigger` | shadcn-compatible alias for `SidebarToggle` |
+| `SidebarInset` | main content wrapper for app-shell layouts |
+
+## Token Contract
+
+Sidebar uses generated `--bh-sidebar-width`, `--bh-sidebar-width-collapsed`, `--bh-sidebar-item-height`, `--bh-sidebar-padding`, `--bh-sidebar-bg`, `--bh-sidebar-border`, and `--shadow-sidebar` tokens.
+
+## RTL
+
+Use `dir="rtl"` on `SidebarProvider` and `side="start"` or `side="end"` for logical placement.
+
+## Accessibility
+
+Use clear labels for collapsed icon-only menu buttons. `SidebarToggle` announces the pressed collapse state.
+Sidebar composition parts must be rendered inside `SidebarProvider`.
+
+## Install
+
+```bash
+npx banhaten add sidebar
+```
+
+## Examples
+
+Primary registry example: `examples/sidebar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs sidebar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: Use side="start" or side="end" with dir on SidebarProvider for logical placement.
+- `spacing`: Menu item icon and label spacing uses flex gaps and logical text alignment.

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

@@ -0,0 +1,73 @@
+# Skeleton
+
+Skeleton is the token-built loading placeholder system for pending content. It includes a small primitive plus composed text, avatar, button, input, card, list, table, and form placeholders.
+
+## API
+
+```tsx
+import {
+  Skeleton,
+  SkeletonCard,
+  SkeletonTable,
+  SkeletonText,
+} from "@/components/ui/skeleton"
+
+export function LoadingPanel() {
+  return (
+    <section aria-busy="true" aria-label="Loading project details">
+      <SkeletonCard />
+      <SkeletonTable rows={4} columns={4} />
+    </section>
+  )
+}
+```
+
+| Export | Purpose |
+| --- | --- |
+| `Skeleton` | Base block, text, or circle placeholder. |
+| `SkeletonText` | Multi-line text placeholder with optional line widths. |
+| `SkeletonAvatar` | Token-sized circular avatar placeholder. |
+| `SkeletonButton` | Button-height placeholder for actions and icon buttons. |
+| `SkeletonInput` | Label, control, and helper-text loading field. |
+| `SkeletonCard` | Media, avatar/text, and action skeleton composition. |
+| `SkeletonList` | Repeated row loading state for feeds, menus, and lists. |
+| `SkeletonTable` | Header and row loading state for table surfaces. |
+| `SkeletonForm` | Repeated input loading state with footer actions. |
+
+## Token Contract
+
+Skeleton consumes Banhaten background, border, radius, spacing, button, card, opacity, and shadow tokens. Custom layout sizing should be passed through CSS variables or token classes rather than raw dimensions.
+
+- Fill: `--bh-bg-muted`, `--bh-bg-subtle`, `--bh-bg-raised-subtle`, `--bh-bg-brand-subtle`
+- Highlight: `--bh-bg-raised-subtle`, `--bh-bg-default`, `--bh-bg-brand-soft`
+- Shape: `--bh-radius-md-6`, `--bh-radius-full`, `--bh-control-default`
+- Layout: `--bh-space-*`, `--bh-button-*-height`, `--bh-card-desktop-content-padding`
+
+## RTL And Accessibility
+
+- Skeleton compositions inherit `dir` from the nearest parent.
+- The shimmer direction mirrors in RTL containers.
+- Skeletons are decorative by default. Put `aria-busy="true"` and an accessible label or status message on the loading region when the loading state needs to be announced.
+
+## Install
+
+```bash
+npx banhaten add skeleton
+```
+
+## Examples
+
+Primary registry example: `examples/skeleton-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs skeleton` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `motion`: The shimmer direction mirrors inside RTL containers while preserving logical layout.
+- `composition`: Composed card, list, table, and form placeholders use logical gaps, inherited direction, and token-sized rows.
+- `accessibility`: Skeletons are decorative by default; set aria-busy on the loading region and pair with a status label when loading progress needs to be announced.
+
+## 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/slideout.md

@@ -0,0 +1,63 @@
+# Slideout
+
+`Slideout` renders a right- or left-aligned panel for focused secondary workflows. It supports desktop and mobile breakpoints, three desktop widths, optional header action, optional footer actions, and LTR/RTL direction.
+
+Figma reference: `Slideout`, node `256:19065`.
+
+## Examples
+
+The local implementation includes these Figma slot-content examples:
+
+| Example | Figma node |
+| --- | --- |
+| Filters | `256:18779` |
+| User profile activity | `256:18872` |
+| Payment detail | `256:18901` |
+| Payment detail 02 | `256:18964` |
+
+## API
+
+```tsx
+<Slideout size="small" breakpoint="desktop" dir="ltr">
+  <SlideoutFiltersExample />
+</Slideout>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `size` | `small`, `medium`, `large` | `small` |
+| `breakpoint` | `desktop`, `mobile` | `desktop` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `title` | `string` | none |
+| `headerAction` | `boolean` | `true` |
+| `footer` | `boolean` | `true` |
+| `secondaryAction` | `boolean` | `true` |
+
+## Layout
+
+- Desktop outer sizes match the Figma matrix: small `356px`, medium `416px`, and large `516px`, each at `900px` height.
+- Mobile uses `375px x 812px` and removes the desktop panel corner radius.
+- Header and footer are fixed-height regions; the body owns vertical scrolling.
+- Slot content is passed as children so product workflows can compose filters, activity, payment details, forms, or custom content without changing the panel API.
+
+## Accessibility
+
+- The panel uses `role="dialog"` with the current title as its accessible label.
+- Close and action controls are real buttons.
+- Slot examples keep text content as real text and mirror layout through `dir="rtl"` rather than separate component APIs.
+
+## Install
+
+```bash
+npx banhaten add slideout
+```
+
+## 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/slideout.css`, `components/expanded/Slideout.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.

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

@@ -0,0 +1,61 @@
+# Slider
+
+Slider is an accessible value and range control built on Radix Slider. It matches the Figma single-node and double-node slider sets, including text and tooltip indicators above or below the thumb, RTL, tick marks, disabled state, vertical orientation, and the large pill treatment used by the investment savings background.
+
+## API
+
+```tsx
+<Slider aria-label="Investment amount" defaultValue={[45]} />
+
+<Slider
+  aria-label="Savings range"
+  ariaLabels={["Minimum savings", "Maximum savings"]}
+  defaultValue={[25, 72]}
+  indicator="lower-text"
+  minStepsBetweenThumbs={4}
+/>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `default`, `pill` |
+| `size` | `sm`, `default`, `lg` |
+| `tone` | `brand`, `neutral`, `success`, `warning`, `danger` |
+| `indicator` | `none`, `lower-text`, `upper-text`, `lower-tooltip`, `upper-tooltip` |
+| `orientation` | `horizontal`, `vertical` |
+
+Use `showTicks` and `tickCount` for dotted track markers. Use `indicator` for Figma text/tooltip markers, `thumbLabel` or `thumbLabels` to customize marker text, `showThumbGrip` for pill controls, and `ariaValueText` for assistive value formatting.
+
+## Tokens
+
+Slider consumes component aliases for track size, thumb size, pill height, tick geometry, thumb shadows, and semantic color roles. Tones map to semantic brand/status/accent tokens so color theme changes are inherited automatically.
+
+## Install
+
+```bash
+npx banhaten add slider
+```
+
+## Examples
+
+Primary registry example: `examples/slider-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs slider` 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/slider.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `valueDirection`: Radix Slider handles direction and keyboard behavior through the inherited dir attribute.
+- `spacing`: Uses logical thumb content spacing and tokenized track/thumb geometry.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-slider` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.

package/docs/design-system/components/social-button.md

@@ -0,0 +1,47 @@
+# Social Button
+
+Social Button is the sign-in action primitive for supported identity providers. It includes Figma-matched platform styling, solid and outlined variants, icon-only mode, native focus-visible styling, and RTL labels.
+
+## API
+
+```tsx
+<SocialButton platform="google">Continue with Google</SocialButton>
+<SocialButton platform="apple" variant="outline" size="icon" aria-label="Continue with Apple" />
+```
+
+| Prop | Values |
+| --- | --- |
+| `platform` | `apple`, `facebook`, `google`, `linkedin`, `twitter`, `whatsapp` |
+| `variant` | `solid`, `outline` |
+| `size` | `default`, `icon` |
+| `label` | localized label override |
+
+## Token Contract
+
+Social Button uses Banhaten control, typography, radius, focus, spacing, and shadow tokens. Provider colors are the limited brand-color exception and should stay scoped to this component.
+
+## RTL
+
+When direction is RTL, platform labels default to Arabic where provided. Icon and label spacing uses logical flex rhythm.
+
+## Accessibility
+
+Icon-only social buttons must provide `aria-label`. Button text should name the provider and the action, such as `Continue with Google`.
+
+## Install
+
+```bash
+npx banhaten add social-button
+```
+
+## Examples
+
+Primary registry example: `examples/social-button-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs social-button` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `labels`: Defaults to the Arabic platform label when the document direction is RTL, and accepts an explicit label for nested RTL surfaces.
+- `spacing`: Uses logical label padding and flex gap so the icon/label order follows inherited direction.

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

@@ -0,0 +1,61 @@
+# Spinner
+
+Spinner is a compact loading indicator for buttons, inline feedback, status rows, and pending regions. `Spinner` is the simple steady loader, while `DynamicSpinner` uses the smoother variable-arc motion for moments that benefit from a more organic loading state.
+
+## Usage
+
+```tsx
+import { DynamicSpinner, Spinner } from "@/components/ui/spinner"
+
+export function LoadingLabel() {
+  return (
+    <span className="inline-flex items-center gap-2" role="status">
+      <Spinner />
+      Loading
+
+      <DynamicSpinner />
+      Syncing
+    </span>
+  )
+}
+```
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `className` | `string` | - | Sets color, layout, or other SVG classes. |
+| `style` | `React.CSSProperties` | - | Override `--bh-spinner-size` when a local size is needed. |
+
+## Guidance
+
+- Pair the decorative spinner with visible status text or a loading button label.
+- Use `Spinner` for ordinary button and inline loading.
+- Use `DynamicSpinner` when the loading state is prominent enough to benefit from variable arc motion.
+- Keep sizing token-based by setting `--bh-spinner-size` rather than hardcoding SVG geometry.
+
+## Install
+
+```bash
+npx banhaten add spinner
+```
+
+## Examples
+
+Primary registry example: `examples/spinner-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs spinner` 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/spinner.tsx`.
+
+## 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.