banhaten 0.1.2 → 0.1.3

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

@@ -0,0 +1,81 @@
+# Timeline
+
+Timelines show ordered progress or dated events. Use `Timeline` for a complete sequence and `TimelineItem` when a consumer needs to compose a custom layout.
+
+Figma references:
+
+- `TimelineVetical`, node `572:6768`
+- `TimeLineHorizontal`, node `584:4501`
+- `TimelineVerticalItem`, node `572:6444`
+- `TimelineHorizontalItem`, node `582:4214`
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `orientation` | `vertical`, `horizontal` |
+| `variant` | `default`, `icon` |
+| `state` | `finished`, `active`, `inactive` |
+| `dir` | `ltr`, `rtl` |
+
+The Figma source includes vertical timelines with seven steps and horizontal timelines with six steps. Code accepts any `steps` array.
+
+## API
+
+```tsx
+<Timeline
+  orientation="vertical"
+  variant="default"
+  dir="ltr"
+  steps={[
+    { label: "Label", caption: "Caption", date: "Mar 15. 2050", state: "finished" },
+    { label: "Label", caption: "Caption", date: "Mar 15. 2050", state: "active" },
+    { label: "Label", caption: "Caption", date: "Mar 15. 2050", state: "inactive" },
+  ]}
+/>
+```
+
+`TimelineStep` supports `label`, `caption`, `date`, `topDate`, `bottomDate`, `state`, `icon`, and visibility flags for leading/top/bottom dates, caption, connector line, and bottom padding.
+
+## Token Contract
+
+- `--bg-brand-default`: filled icon marker
+- `--bg-default`: default marker center
+- `--bg-muted`: inactive icon marker
+- `--border-brand-strong`: finished connector line
+- `--border-default`: active and inactive connector line
+- `--content-default`: labels and inactive check
+- `--content-subtle`: dates and captions
+- `--radius-full`: marker and line radius
+
+## Pixel Rules
+
+- Dates are `12px / 16px`, regular.
+- Labels are `15px / 24px`, semibold.
+- Captions are `14px / 20px`, regular.
+- Default markers reserve a `20px` box with a small circular ring.
+- Icon markers are `28px` circles with an 18px check glyph.
+- Vertical item gaps use `12px`; horizontal item body spacing uses `10px`.
+- Finished connector lines use the brand border color.
+- Active and inactive connector lines use the default border color.
+- RTL mirrors the date/content placement while preserving source step order.
+
+## Install
+
+```bash
+npx banhaten add timeline
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/timeline-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs timeline` 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/toast.md

@@ -0,0 +1,56 @@
+# Toast
+
+Toast provides transient feedback for saves, errors, warnings, background work, and undoable actions. It uses a Sonner-style API with Banhaten token styling, semantic intents, action support, and logical LTR/RTL placement.
+
+## API
+
+```tsx
+<Toaster />
+
+toast.success("Project saved")
+toast.danger("Unable to publish", {
+  action: { label: "Retry", onClick: retry },
+})
+```
+
+| Export | Purpose |
+| --- | --- |
+| `Toaster` | app-level toast viewport |
+| `toast` | imperative toast API |
+| `toast.success`, `toast.info`, `toast.warning`, `toast.danger` | semantic shortcuts |
+
+| Prop | Values |
+| --- | --- |
+| `dir` | `ltr`, `rtl` |
+| `side` | `start`, `end` |
+| `position` | Sonner position override |
+
+## Token Contract
+
+Toast uses Banhaten raised surface, border, shadow, radius, body typography, action, danger, warning, success, info, and content tokens.
+
+## RTL
+
+`side="end"` resolves to top-right in LTR and top-left in RTL. Use `side="start"` for the opposite logical edge.
+
+## Accessibility
+
+Keep toast copy short and pair destructive failures with a visible retry or recovery path when possible. Do not use toasts as the only place for critical validation errors.
+
+## Install
+
+```bash
+npx banhaten add toast
+```
+
+## Examples
+
+Primary registry example: `examples/toast-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs toast` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `placement`: side="end" resolves to top-right in LTR and top-left in RTL; side="start" resolves to the opposite edge.
+- `textDirection`: Toast content inherits the Toaster direction and uses tokenized typography classes.

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

@@ -0,0 +1,79 @@
+# Toggle
+
+Toggle is a Radix Switch-backed boolean control. It supports sm and md switch geometry, active and disabled states, optional handle icons, labeled leading or trailing compositions, supporting text, and inherited RTL direction.
+
+The implementation follows the Figma components at `Design system 3.0 Copy / Toogle` (`175:23379`) and `Toggle label` (`175:23443`).
+
+## API
+
+Use `Toggle` for standalone controls with an accessible label.
+
+```tsx
+<Toggle aria-label="Enable notifications" defaultChecked />
+```
+
+Use `ToggleField` when the visible label and supporting text should name the switch.
+
+```tsx
+<ToggleField
+  defaultChecked
+  controlPosition="end"
+  label="Email notifications"
+  description="Send product updates and billing activity."
+/>
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `md` |
+| `showIcon` | `boolean` |
+| `ToggleField controlPosition` | `start`, `end` |
+| `disabled` | `boolean` |
+
+## Tokens
+
+Toggle uses the existing Banhaten switch aliases:
+
+| Purpose | Token |
+| --- | --- |
+| Default track | `--bh-interactive-switch-default` |
+| Hover track | `--bh-interactive-switch-hover` |
+| Active track | `--bh-interactive-switch-active` |
+| Active hover track | `--bh-interactive-switch-active-hover` |
+| Disabled track | `--bh-interactive-switch-disabled` |
+| Handle | `--bh-interactive-switch-handle` |
+| Disabled handle | `--bh-interactive-switch-handle-disabled` |
+| Focus ring | `--shadow-social-button-focus-ring` |
+
+Text uses body-md for labels and body-xs for supporting text. ToggleField uses logical start/end placement so label order and thumb motion mirror in RTL.
+
+## Install
+
+```bash
+npx banhaten add toggle
+```
+
+## Examples
+
+Primary registry example: `examples/toggle-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs toggle` 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/toggle.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `controlPlacement`: ToggleField uses start/end control placement so the switch and text order mirror in RTL.
+- `handleMotion`: The thumb translates with logical direction, so checked state moves to the visual end edge in LTR and RTL.
+- `textDirection`: Labels and descriptions use dir="auto" with tokenized body-md/body-xs typography.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-switch` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.

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

@@ -0,0 +1,85 @@
+# Toolbar
+
+Toolbar is the token-built implementation of the Figma `Filter Toolbar` component set. It supports eight filter/action layouts, desktop and mobile wrapping, and inherited LTR/RTL direction.
+
+## Install
+
+```bash
+npx banhaten add toolbar
+```
+
+## Anatomy
+
+- `Toolbar`: root layout surface with `inline`, `split`, `stack`, and `wrap` modes.
+- `ToolbarSection`: grouped start, end, wrapped, or stacked control regions.
+- `ToolbarSearch`: tokenized search input using Banhaten input height, radius, typography, and focus ring.
+- `ToolbarSelect`: button-backed filter trigger using select/input tokens.
+- `ToolbarButton`: toolbar action button built with the same Slot and text-label construction as Button.
+- `ToolbarIconButton`, `ToolbarFilterButton`, `ToolbarMoreButton`: icon action helpers.
+- `ToolbarBadge`: selected-count or applied-filter metadata.
+- `ToolbarText` and `ToolbarSpacer`: supporting label and layout slots.
+
+## Example
+
+```tsx
+import {
+  Toolbar,
+  ToolbarButton,
+  ToolbarFilterButton,
+  ToolbarMoreButton,
+  ToolbarSearch,
+  ToolbarSection,
+  ToolbarSelect,
+} from "@/components/ui/toolbar"
+
+export function Example() {
+  return (
+    <Toolbar layout="split" wrap>
+      <ToolbarSection grow wrap>
+        <ToolbarSearch aria-label="Search objects" />
+        <ToolbarSelect value="Status" />
+        <ToolbarSelect value="Owner" />
+        <ToolbarFilterButton />
+      </ToolbarSection>
+      <ToolbarSection align="end" wrap>
+        <ToolbarMoreButton />
+        <ToolbarButton variant="soft">Export</ToolbarButton>
+        <ToolbarButton>Create Object</ToolbarButton>
+      </ToolbarSection>
+    </Toolbar>
+  )
+}
+```
+
+## Token Contract
+
+Toolbar styling is derived from the existing control tokens: `--bh-input-lg-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-select-width`, `--bh-space-xl-12`, `--bh-space-3xl-16`, `--bh-control-default`, input/select/button shadows, and semantic content/interactive tokens.
+
+## RTL
+
+Set `dir="rtl"` on `Toolbar` or inherit it from the document. Sections, fields, button labels, badges, and search text use logical spacing and `dir="auto"` for mixed-language labels.
+
+## API
+
+Public exports: `Toolbar`, `ToolbarSection`, `ToolbarSearch`, `ToolbarSelect`, `ToolbarButton`, `ToolbarIconButton`, `ToolbarFilterButton`, `ToolbarMoreButton`, `ToolbarBadge`, `ToolbarText`, `ToolbarSpacer`.
+
+| Contract | Values |
+| --- | --- |
+| `styles` | `filter-fields`, `filter-actions`, `selection-actions`, `grouped-fields`, `field-grid`, `inline-search`, `filter-chips`, `saved-segment` |
+| `layouts` | `inline`, `split`, `stack`, `wrap` |
+
+## Examples
+
+Primary registry example: `examples/toolbar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs toolbar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses logical section layout and dir="auto" labels so mixed English and Arabic filter text aligns naturally.
+- `spacing`: Uses tokenized flex gaps and logical icon attributes so search, fields, chips, summaries, and actions mirror without alternate APIs.
+
+## 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/tooltip.md

@@ -0,0 +1,90 @@
+# Tooltip
+
+Tooltip is a Radix Tooltip-backed help surface matched to the Figma tooltip matrix. It supports dark and default surfaces, small and large sizes, shortcut and close slots, logical pointer positions, tokenized shadows, and RTL-safe layout.
+
+## Install
+
+```bash
+npx banhaten add tooltip
+```
+
+## Anatomy
+
+- `TooltipProvider`: shared Radix provider for delay timing.
+- `Tooltip`: root tooltip wrapper.
+- `TooltipTrigger`: trigger element.
+- `TooltipContent`: positioned surface with pointer, title, support text, shortcut, and close affordance.
+- `TooltipShortcut`: shortcut slot.
+- `TooltipCloseButton`: optional close affordance.
+
+## Example
+
+```tsx
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+import { Button } from "@/components/ui/button"
+
+export function Example() {
+  return (
+    <TooltipProvider>
+      <Tooltip>
+        <TooltipTrigger asChild>
+          <Button variant="secondary">Details</Button>
+        </TooltipTrigger>
+        <TooltipContent pointerPosition="top-center" size="lg">
+          More information
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  )
+}
+```
+
+## Variants
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `dark`, `default` |
+| `size` | `sm`, `lg` |
+| `pointerPosition` | `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`, `center-left`, `center-right`, `none` |
+| `showPointer` | `boolean` |
+
+## RTL
+
+Tooltip content uses inherited direction and `dir="auto"` text. Top and bottom left/right positions map to logical start/end in RTL, while center-left and center-right remain physical sides to match the Figma matrix.
+
+## API
+
+Public exports: `Tooltip`, `TooltipRoot`, `TooltipTrigger`, `TooltipContent`, `TooltipProvider`, `TooltipPortal`, `TooltipShortcut`, `TooltipCloseButton`.
+
+| Contract | Values |
+| --- | --- |
+| `variants` | `dark`, `default` |
+| `sizes` | `sm`, `lg` |
+
+## Examples
+
+Primary registry example: `examples/tooltip-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs tooltip` 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/tooltip.tsx`.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses inherited direction with flex layout so label/shortcut and text/close order mirror naturally.
+- `pointerPlacement`: Top and bottom left/right positions map to logical start/end in RTL. Center-left and center-right remain physical sides to match the Figma matrix.
+- `textDirection`: Labels and support text use dir="auto" for Arabic and English copy.
+
+## Accessibility
+
+This component relies on `@radix-ui/react-tooltip` for its base accessibility behavior. Keep required labels, titles, descriptions, and focusable trigger/content relationships intact when composing it.

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

@@ -0,0 +1,18 @@
+# Typography
+
+Banhaten exposes text utility classes generated from the design token contract. Use `.bh-text-*` classes when you need token-exact typography without pulling in a React component.
+
+## Usage
+
+```html
+<h1 class="bh-text-heading-lg-semibold">Workspace overview</h1>
+<p class="bh-text-body-md-regular">Review project status and owners.</p>
+```
+
+## Families
+
+The classes mirror token names across Display, Heading, and Body styles. Each class applies font size, line height, font weight, and letter spacing from `registry/styles/globals.css`.
+
+## RTL
+
+Typography classes do not set direction. Use `dir`, `lang`, and logical text alignment on the surrounding element.