banhaten 0.3.0 → 0.5.0

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

@@ -1,56 +1,60 @@
-# Tabs
-
-Tabs is a Radix-backed local navigation primitive with underline, segmented, and rounded treatments across size, full-width behavior, controlled state, LTR, and RTL.
-
-## API
-
-```tsx
-<Tabs
-  ariaLabel="Project sections"
-  items={["Overview", "Activity", "Settings"]}
-  variant="underline"
-/>
-```
-
-| Prop | Values |
-| --- | --- |
-| `variant` | `underline`, `segment`, `rounded` |
-| `size` | `md`, `sm`, `xs` |
-| `fullWidth` | `boolean` |
-| `activeIndex`, `defaultActiveIndex` | controlled or uncontrolled index |
-| `onActiveIndexChange` | selected-index callback |
-
-## Token Contract
-
-Tabs uses Banhaten tab CSS variables for sizes, spacing, border, radius, active indicators, surfaces, and content states.
-
-## RTL
-
-Tabs accepts `dir="rtl"` and mirrors layout through inherited direction. Labels should remain short enough for each treatment and viewport.
-
-## Accessibility
-
-Tabs uses Radix Tabs so keyboard behavior, roving focus, activation mode, trigger state, and panel relationships come from the primitive.
-
-## Install
-
-```bash
-npx banhaten add tabs
-```
-
-## Examples
-
-Primary registry example: `examples/tabs-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs tabs` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `keyboard`: Radix receives dir so arrow-key navigation follows the document direction.
-- `textDirection`: Trigger labels use dir="auto" by default for Arabic and English tab labels.
-- `spacing`: Uses inherited direction and logical inline spacing so underline, segmented, and rounded treatments mirror naturally.
-
+# Tabs
+
+Tabs is a Radix-backed local navigation primitive with underline, segmented, and rounded treatments across size, full-width behavior, controlled state, LTR, and RTL.
+
+## API
+
+```tsx
+<Tabs
+  ariaLabel="Project sections"
+  items={["Overview", "Activity", "Settings"]}
+  variant="underline"
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `variant` | `underline`, `segment`, `rounded` |
+| `size` | `md`, `sm`, `xs` |
+| `fullWidth` | `boolean`; default `false`. Equal shares while labels fit; content-safe scrolling under pressure. |
+| `activeIndex`, `defaultActiveIndex` | controlled or uncontrolled index |
+| `onActiveIndexChange` | selected-index callback |
+
+## Token Contract
+
+Tabs uses Banhaten tab CSS variables for sizes, spacing, border, radius, active indicators, surfaces, and content states.
+
+## RTL
+
+Tabs accepts `dir="rtl"` and mirrors layout through inherited direction. Trigger labels stay complete in both directions: content-hug tabs keep their intrinsic width, while full-width tabs keep equal shares until a label's intrinsic width requires horizontal overflow.
+
+## Overflow
+
+Tab labels stay on one line and are never painted outside their trigger. When all triggers cannot fit, the tab list owns horizontal scrolling. `fullWidth` changes how spare inline space is distributed; it does not enable truncation or unsafe shrinking.
+
+## Accessibility
+
+Tabs uses Radix Tabs so keyboard behavior, roving focus, activation mode, trigger state, and panel relationships come from the primitive.
+
+## Install
+
+```bash
+npx banhaten add tabs
+```
+
+## Examples
+
+Primary registry example: `examples/tabs-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs tabs` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `keyboard`: Radix receives dir so arrow-key navigation follows the document direction.
+- `textDirection`: Trigger labels use dir="auto" by default for Arabic and English tab labels.
+- `spacing`: Uses inherited direction and logical inline spacing so underline, segmented, and rounded treatments mirror naturally.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -62,8 +66,8 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/tabs.tsx: Tabs, TabsContent, TabsList, TabsRoot, TabsTrigger` |
 | `parts` | `Tabs`, `TabsRoot`, `TabsList`, `TabsTrigger`, `TabsContent` |
 | `registryDependencies` | None |
-| `features` | `Radix keyboard behavior`, `controlled active index`, `controlled value`, `optional panels`, `full-width tabs` |
+| `features` | `Radix keyboard behavior`, `controlled active index`, `controlled value`, `optional panels`, `content-hug tabs`, `content-safe full-width tabs`, `horizontal overflow without label overlap` |
 | `sizes` | `md`, `sm`, `xs` |
-| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-subtle`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-space-3xl-16`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--shadow-button-soft` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-neutral-subtle`, `--bh-border-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-space-3xl-16`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--elevation-button-soft` |
 | `variants` | `underline`, `segment`, `rounded` |
 <!-- registry-contract:end -->

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

@@ -1,82 +1,82 @@
-# Tag
-
-Tags identify compact metadata, filters, or removable selections.
-
-The implementation follows the Figma component at `Design system 3.0 Copy / Tag` (`188:64712`). It supports every variant in the matrix: `simple`, `dot`, `flag`, `avatar`, and `icon`; `default`, `active`, and `disabled` states with native hover and focus-visible styling; `xs`, `md`, and `lg` sizes; optional close button; LTR and RTL.
-
-## API
-
-```tsx
-<Tag
-  type="simple"
-  size="md"
-  state="default"
-  showCloseButton={false}
-  dir="ltr"
->
-  Label
-</Tag>
-```
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `type` | `simple`, `dot`, `flag`, `avatar`, `icon` | `simple` |
-| `size` | `xs`, `md`, `lg` | `md` |
-| `state` | `default`, `active`, `disabled` | `default` |
-| `showCloseButton` | `boolean` | `false` |
-| `disabled` | `boolean` | `false` |
-| `dir` | `ltr`, `rtl`, `auto` | `auto` |
-| `avatar` | `ReactNode` | initials placeholder |
-| `flag` | `ReactNode` | token-colored placeholder |
-| `icon` | `ReactNode` | plus icon |
-| `onClose` | close-button click handler | none |
-
-## Token Contract
-
-The component consumes semantic design-system tokens only:
-
-- Text and icons: `content.default`, `content.disabled`, `content.primary`, `content.onColor`, `content.muted`
-- Backgrounds: `background.default`, `background.hover`, `background.pressed`, `background.disabled`, `background.selected`, `background.danger`
-- Borders: `border.default`, `border.disabled`, `border.brand`, `border.focus`, `border.subtle`
-- Shape: `shape.control`, `shape.badge`, `shape.avatar`
-- Density: `density.controlHeight`, `density.controlPaddingX`
-
-## Pixel Rules
-
-- `xs` tags are `24px` tall and use body-xs medium text.
-- `md` tags are `28px` tall and use body-sm medium text.
-- `lg` tags are `36px` tall and use body-md medium text.
-- Simple tags use centered text and no leading slot.
-- Dot, flag, avatar, and icon tags use a `20px` leading slot.
-- Close buttons are `16px` with a `12px` icon.
-- Focused tags use a brand border plus an outside focus ring at reduced opacity.
-- Active tags use selected/brand treatment and a stronger brand border.
-- Disabled tags use disabled background, border, and content tokens.
-- RTL uses logical inline padding and inherited direction so leading media, label, and close button mirror naturally.
-
-## Install
-
-```bash
-npx banhaten add tag
-```
-
-## Examples
-
-Primary registry example: `examples/tag-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs tag` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Uses logical inline padding and inherited flex direction so the leading media, label, and close button mirror naturally.
-- `textDirection`: Text labels use dir="auto" for short Arabic and English tag labels.
-- `closeButton`: The close affordance is a 16px token-sized icon button using currentColor and the tag disabled state.
-
-## 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.
-
+# Tag
+
+Tags identify compact metadata, filters, or removable selections.
+
+The implementation follows the Figma component at `Design system 3.0 Copy / Tag` (`188:64712`). It supports every variant in the matrix: `simple`, `dot`, `flag`, `avatar`, and `icon`; `default`, `active`, and `disabled` states with native hover and focus-visible styling; `xs`, `md`, and `lg` sizes; optional close button; LTR and RTL.
+
+## API
+
+```tsx
+<Tag
+  type="simple"
+  size="md"
+  state="default"
+  showCloseButton={false}
+  dir="ltr"
+>
+  Label
+</Tag>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `type` | `simple`, `dot`, `flag`, `avatar`, `icon` | `simple` |
+| `size` | `xs`, `md`, `lg` | `md` |
+| `state` | `default`, `active`, `disabled` | `default` |
+| `showCloseButton` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `dir` | `ltr`, `rtl`, `auto` | `auto` |
+| `avatar` | `ReactNode` | initials placeholder |
+| `flag` | `ReactNode` | token-colored placeholder |
+| `icon` | `ReactNode` | plus icon |
+| `onClose` | close-button click handler | none |
+
+## Token Contract
+
+The component consumes semantic design-system tokens only:
+
+- Text and icons: `content.default`, `content.disabled`, `content.primary`, `content.onColor`, `content.muted`
+- Backgrounds: `background.default`, `background.hover`, `background.pressed`, `background.disabled`, `background.selected`, `background.danger`
+- Borders: `border.default`, `border.disabled`, `border.brand`, `border.focus`, `border.subtle`
+- Shape: `shape.control`, `shape.badge`, `shape.avatar`
+- Density: `density.controlHeight`, `density.controlPaddingX`
+
+## Pixel Rules
+
+- `xs` tags are `24px` tall and use body-xs medium text.
+- `md` tags are `28px` tall and use body-sm medium text.
+- `lg` tags are `36px` tall and use body-md medium text.
+- Simple tags use centered text and no leading slot.
+- Dot, flag, avatar, and icon tags use a `20px` leading slot; the default icon glyph is `18px`.
+- Close buttons are `16px` with a `12px` icon.
+- Focused tags use a brand border plus a solid outside focus ring.
+- Active tags use selected/brand treatment and a stronger brand border.
+- Disabled tags use disabled background, border, and content tokens.
+- RTL uses logical inline padding and inherited direction so leading media, label, and close button mirror naturally.
+
+## Install
+
+```bash
+npx banhaten add tag
+```
+
+## Examples
+
+Primary registry example: `examples/tag-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs tag` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical inline padding and inherited flex direction so the leading media, label, and close button mirror naturally.
+- `textDirection`: Text labels use dir="auto" for short Arabic and English tag labels.
+- `closeButton`: The close affordance is a 16px token-sized icon button using currentColor and the tag disabled state.
+
+## 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.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -90,6 +90,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `sizes` | `xs`, `md`, `lg` |
 | `states` | `default`, `active`, `disabled` |
-| `tokens` | `--bh-bg-accent-green-default`, `--bh-bg-always-dark`, `--bh-bg-always-white`, `--bh-bg-brand-subtle`, `--bh-bg-danger-default`, `--bh-bg-neutral-bold`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-neutral`, `--bh-control-default`, `--bh-control-md`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-opacity-30`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-tag-active-border-width`, `--bh-tag-focus-ring-inset`, `--bh-tag-focus-ring-width`, `--bh-text-body-3xs-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--bh-text-body-3xs-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-z-raised`, `--shadow-button-focus` |
+| `tokens` | `--bh-bg-accent-green-default`, `--bh-bg-always-dark`, `--bh-bg-always-white`, `--bh-bg-brand-subtle`, `--bh-bg-danger-default`, `--bh-bg-neutral-bold`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-on-neutral`, `--bh-control-default`, `--bh-control-md`, `--bh-icon-size-default`, `--bh-icon-slot-size-default`, `--bh-icon-stroke-200`, `--bh-icon-stroke-225`, `--bh-interactive-ghost-hover`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-interactive-secondary-hover`, `--bh-opacity-30`, `--bh-radius-full`, `--bh-radius-xs-2`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-none`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-tag-active-border-width`, `--bh-tag-focus-ring-inset`, `--bh-tag-focus-ring-width`, `--bh-text-body-3xs-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--bh-text-body-3xs-semibold-line-height`, `--bh-text-body-md-medium-font-size`, `--bh-text-body-md-medium-font-weight`, `--bh-text-body-md-medium-letter-spacing`, `--bh-text-body-md-medium-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-z-raised`, `--elevation-button-focus` |
 | `types` | `simple`, `dot`, `flag`, `avatar`, `icon` |
 <!-- registry-contract:end -->

package/docs/design-system/components/task-list.md

@@ -0,0 +1,95 @@
+# Task List
+
+`TaskList` is an agent progress tracker. Rows move from a dashed pending circle to an arrow while active (with a shimmering label) to a check when done. The header icon crossfades from a list to a determinate pie to a filled check, and the counter rolls its digits as work completes through [Rolling Count](./rolling-count.md).
+
+For any other list, compose the parts instead of configuring the tracker: `TaskListRoot` draws the surface, `TaskListHeader` is a static header, `TaskListItems` renders rows, and `TaskListPreview` shows the first rows and folds the rest. [Approval Card](./approval-card.md) builds its plan this way.
+
+## API
+
+```tsx
+import {
+  TaskList,
+  TaskListHeader,
+  TaskListPreview,
+  TaskListRoot,
+  type TaskListItem,
+} from "@/components/ui/task-list"
+
+const items: TaskListItem[] = [
+  { id: "1", label: "Scaffold the project structure", status: "done" },
+  { id: "2", label: "Build the component registry", status: "active" },
+  { id: "3", label: "Wire up checkout", status: "pending" },
+]
+
+<TaskList items={items} />
+
+<TaskListRoot surface="well">
+  <TaskListHeader count={items.length}>To-dos</TaskListHeader>
+  <TaskListPreview items={items} visibleCount={2} />
+</TaskListRoot>
+```
+
+### TaskList
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `readonly TaskListItem[]` | – | Rows with `id`, `label`, and `pending`, `active`, or `done` status. |
+| `title` | `React.ReactNode` | `"To-dos"` | Header label. |
+| `surface` | `"card" \| "well" \| "plain"` | `"card"` | Raised card, subtle well for embedding, or no surface. |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` | `true` | Fold state. |
+| `labels` | `Partial<TaskListLabels>` | English | `count(done, total)` copy, which the toggle reads after its title. |
+
+### Parts
+
+| Part | Props | Description |
+| --- | --- | --- |
+| `TaskListRoot` | `surface` | Surface of a composed list. A header inside it names the rows. |
+| `TaskListHeader` | `children`, `count`, `items` | Static header. `items` drives the icon from list to progress pie to check; `count` renders at the end. |
+| `TaskListItems` | `items` | Rows. They start flush when no header sits above them. |
+| `TaskListPreview` | `items`, `visibleCount` (`3`), `labels` | The first rows, then a Collapsible fold for the rest with `more(count)` and `less` copy. |
+
+## Install
+
+```bash
+npx banhaten add task-list
+```
+
+## Examples
+
+Primary registry example: `examples/task-list-demo.tsx`.
+
+## Token Contract
+
+Surfaces use `--bh-bg-raised` with `--elevation-02` and `--bh-radius-2xl-12` (card) or `--bh-bg-subtle` with `--bh-radius-lg-8` (well). Rows use the `body-xs` scale, `--bh-task-list-icon-size` icons, `--bh-content-subtle` for muted rows, `--bh-content-default` for the active row, and `--bh-content-success-default` for the finished check. Motion uses the `--bh-duration-*` foundation tokens, rows enter `--bh-task-list-stagger` apart, and the active row uses the shared shimmer.
+
+Covered source files: `components/task-list.tsx`, `components/task-list.css`, and the `collapsible`, `rolling-count`, and `shimmer-text` registry dependencies.
+
+## RTL Rules
+
+- Rows, counters, and the collapse chevron use logical placement.
+- The active arrow icon mirrors horizontally in RTL; the check and dashed circle are symmetric.
+
+## Accessibility
+
+The collapsible header and the "more" control are Collapsible triggers with `aria-expanded` and `aria-controls`, named by what they show: the header by its title and progress, for example "To-dos 2 of 5 done". Folded rows unmount after their closing animation, so nothing hidden can be focused. Rows are labelled by the header title of their list, including a `TaskListHeader` composed inside `TaskListRoot`. Status changes are expressed through icons plus strikethrough, never color alone, and the counter carries an accessible "done of total" summary. Rolling digits, crossfades, and shimmer collapse to instant changes under `prefers-reduced-motion`.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/task-list.tsx: TaskList, TaskListHeader, TaskListItems, TaskListPreview, TaskListRoot` |
+| `parts` | `TaskList`, `TaskListRoot`, `TaskListHeader`, `TaskListItems`, `TaskListPreview` |
+| `registryDependencies` | `collapsible`, `rolling-count`, `shimmer-text` |
+| `props.items` | `readonly TaskListItem[]; default null; Rows with id, label, and pending, active, or done status.` |
+| `props.surface` | `"card" \| "well" \| "plain"; default "card"; Raised card, subtle well for embedding, or no surface.` |
+| `props.labels` | `Partial<TaskListLabels>; default "English"; Localized counter copy, read after the title in the toggle's name.` |
+| `props.visibleCount` | `number; default "3"; TaskListPreview: rows shown before the rest fold behind a more control.` |
+| `features` | `controlled state`, `uncontrolled state`, `composable parts`, `preview fold`, `reduced motion`, `RTL` |
+| `states` | `pending`, `active`, `done` |
+| `tokens` | `--bh-bg-raised`, `--bh-bg-subtle`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-success-default`, `--bh-duration-default`, `--bh-duration-fast`, `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-easing-standard`, `--bh-font-family`, `--bh-icon-stroke-180`, `--bh-icon-stroke-200`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-sm-4`, `--bh-space-4xl-20`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--bh-task-list-icon-size`, `--bh-task-list-stagger`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--elevation-02`, `--elevation-component-focus-ring` |
+| `variants` | `card`, `well`, `plain` |
+<!-- registry-contract:end -->

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

@@ -1,52 +1,52 @@
-# Textarea
-
-Textarea is the multiline field primitive for comments, notes, descriptions, and tag-style text entry. It supports label, helper and error text, default and tags modes, placeholder, filled, disabled, and RTL states.
-
-## API
-
-```tsx
-<Textarea label="Comments" placeholder="Add context..." />
-<Textarea mode="tags" label="Tags" defaultValue="Design, System" />
-```
-
-| Prop | Values |
-| --- | --- |
-| `mode` | `default`, `tags` |
-| `state` | `placeholder`, `filled`, `disabled` |
-| `hasError` | `boolean` |
-| `label`, `helperText` | `ReactNode` |
-| `dir` | `ltr`, `rtl` |
-
-## Token Contract
-
-Textarea uses Banhaten field surface, text, label, helper, error, tag, spacing, border, radius, disabled, and focus tokens.
-
-## RTL
-
-Textarea uses `text-start`, inherited direction, and logical field layout. Labels, helper text, and tag chips mirror without physical left/right styling.
-
-## Accessibility
-
-Connect labels and helper/error text through component props. Use visible error text with `hasError` rather than color alone.
-
-## Install
-
-```bash
-npx banhaten add textarea
-```
-
-## Examples
-
-Primary registry example: `examples/textarea-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs textarea` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textAlignment`: Uses text-start and dir="auto" so Arabic and English content align naturally.
-- `spacing`: Uses inherited direction and flex order so labels, helper icons, and tag chips mirror without physical left/right rules.
-
+# Textarea
+
+Textarea is the multiline field primitive for comments, notes, descriptions, and tag-style text entry. It supports label, helper and error text, default and tags modes, placeholder, filled, disabled, and RTL states.
+
+## API
+
+```tsx
+<Textarea label="Comments" placeholder="Add context..." />
+<Textarea mode="tags" label="Tags" defaultValue="Design, System" />
+```
+
+| Prop | Values |
+| --- | --- |
+| `mode` | `default`, `tags` |
+| `state` | `placeholder`, `filled`, `disabled` |
+| `hasError` | `boolean` |
+| `label`, `helperText` | `ReactNode` |
+| `dir` | `ltr`, `rtl` |
+
+## Token Contract
+
+Textarea uses Banhaten field surface, text, label, helper, error, tag, spacing, border, radius, disabled, and focus tokens.
+
+## RTL
+
+Textarea uses `text-start`, inherited direction, and logical field layout. Labels, helper text, and tag chips mirror without physical left/right styling.
+
+## Accessibility
+
+Connect labels and helper/error text through component props. Use visible error text with `hasError` rather than color alone.
+
+## Install
+
+```bash
+npx banhaten add textarea
+```
+
+## Examples
+
+Primary registry example: `examples/textarea-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs textarea` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textAlignment`: Uses text-start and dir="auto" so Arabic and English content align naturally.
+- `spacing`: Uses inherited direction and flex order so labels, helper icons, and tag chips mirror without physical left/right rules.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -60,5 +60,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `modes` | `default`, `tags` |
 | `states` | `placeholder`, `filled`, `disabled` |
-| `tokens` | `--bh-bg-accent-blue-soft`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-accent-blue-strong`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-font-weight-semibold`, `--bh-icon-stroke-225`, `--bh-icon-stroke-250`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-opacity-0`, `--bh-opacity-30`, `--bh-opacity-50`, `--bh-radius-full`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-textarea-border`, `--bh-textarea-close-button-size`, `--bh-textarea-close-icon-size`, `--bh-textarea-focus-ring-inset`, `--bh-textarea-focus-ring-width`, `--bh-textarea-gap`, `--bh-textarea-helper-icon-size`, `--bh-textarea-icon-size`, `--bh-textarea-inline-gap`, `--bh-textarea-min-height`, `--bh-textarea-padding`, `--bh-textarea-radius`, `--bh-textarea-tag-avatar-font-size`, `--bh-textarea-tag-avatar-size`, `--bh-textarea-tag-height`, `--bh-textarea-width`, `--shadow-component-default`, `--shadow-textarea` |
+| `tokens` | `--bh-bg-accent-blue-soft`, `--bh-border-danger-strong`, `--bh-border-default`, `--bh-border-disabled`, `--bh-border-focus`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-accent-blue-strong`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-md`, `--bh-font-weight-semibold`, `--bh-icon-stroke-225`, `--bh-icon-stroke-250`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-secondary-default`, `--bh-interactive-secondary-disabled`, `--bh-opacity-0`, `--bh-opacity-30`, `--bh-opacity-50`, `--bh-radius-full`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-textarea-border`, `--bh-textarea-close-button-size`, `--bh-textarea-close-icon-size`, `--bh-textarea-focus-ring-inset`, `--bh-textarea-focus-ring-width`, `--bh-textarea-gap`, `--bh-textarea-helper-icon-size`, `--bh-textarea-icon-size`, `--bh-textarea-inline-gap`, `--bh-textarea-min-height`, `--bh-textarea-padding`, `--bh-textarea-radius`, `--bh-textarea-tag-avatar-font-size`, `--bh-textarea-tag-avatar-size`, `--bh-textarea-tag-height`, `--bh-textarea-width`, `--elevation-component-default`, `--elevation-textarea` |
 <!-- registry-contract:end -->

package/docs/design-system/components/thinking-reasoning.md

@@ -0,0 +1,72 @@
+# Thinking Reasoning
+
+`ThinkingReasoning` is an animated, collapsible reasoning block. While the agent thinks, a shimmering label sits above sentences that reveal in sequence and auto-scroll behind soft fades. Once the agent is done, the block folds into a "Thought for Ns" summary that unfolds the full, scrollable reasoning on demand.
+
+The component is data-driven: append sentences to `steps` as they arrive and flip `status` to `done` when the model stops. Scripted timers belong in examples, not in the component.
+
+## API
+
+```tsx
+import { ThinkingReasoning } from "@/components/ui/thinking-reasoning"
+
+<ThinkingReasoning
+  duration={5}
+  status={done ? "done" : "thinking"}
+  steps={sentences}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `steps` | `readonly string[]` | – | Reasoning sentences in arrival order. Each row clamps to two lines. |
+| `status` | `"thinking" \| "done"` | `"thinking"` | Thinking keeps the block open and auto-scrolling; done folds it into the summary. |
+| `duration` | `number` | measured | Seconds shown in the summary. Measured from the first thinking render when omitted; a block that mounts already done shows the verb alone. |
+| `open` / `defaultOpen` / `onOpenChange` | `boolean` | `false` | Controls whether the finished reasoning is unfolded. |
+| `reserveSpace` | `boolean` | `false` | Keeps the block height stable while folding so content below does not jump. |
+| `labels` | `Partial<ThinkingReasoningLabels>` | English | `thinking`, `thought`, and `duration(seconds)` copy. The finished summary also names the toggle. |
+
+## Install
+
+```bash
+npx banhaten add thinking-reasoning
+```
+
+## Examples
+
+Primary registry example: `examples/thinking-reasoning-demo.tsx`.
+
+## Token Contract
+
+Width and the capped viewport come from `--bh-thinking-reasoning-width`, `--bh-thinking-reasoning-max-height`, and `--bh-thinking-reasoning-fade`. Sentences use the `body-xs` scale, the header uses `body-xs-medium`, and colors resolve through `--bh-content-subtle` for the verb and sentences and `--bh-content-muted` for the duration and chevron. Motion uses the `--bh-duration-*` foundation tokens with `--bh-easing-emphasized`.
+
+Covered source files: `components/thinking-reasoning.tsx`, `components/thinking-reasoning.css`, and the `collapsible` and `shimmer-text` registry dependencies.
+
+## RTL Rules
+
+- The block inherits document direction; the header, chevron, and sentence text use logical alignment.
+- Auto-scroll, fades, and the fold are vertical and therefore direction-neutral.
+
+## Accessibility
+
+The header is a Collapsible trigger with `aria-expanded` and `aria-controls`, and folded reasoning unmounts after its closing animation. It is disabled while thinking, when there is nothing to toggle, and once done becomes the summary toggle, named by the summary it shows, such as "Thought for 5s". The live label announces the thinking state politely. When unfolded, the reasoning viewport is keyboard scrollable. The reveal, fade, and fold animations collapse to instant changes under `prefers-reduced-motion`.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/thinking-reasoning.tsx: ThinkingReasoning` |
+| `parts` | `ThinkingReasoning` |
+| `registryDependencies` | `collapsible`, `shimmer-text` |
+| `props.steps` | `readonly string[]; default null; Reasoning sentences in arrival order; append to stream new ones.` |
+| `props.status` | `"thinking" \| "done"; default "thinking"; Thinking keeps the block open and auto-scrolling; done folds it into the summary.` |
+| `props.duration` | `number; default "measured"; Seconds shown in the summary; measured from mount when omitted.` |
+| `props.open` | `boolean; default "false"; Controls whether the finished reasoning is unfolded.` |
+| `props.reserveSpace` | `boolean; default "false"; Keeps the block height stable while folding so content below does not jump.` |
+| `props.labels` | `Partial<ThinkingReasoningLabels>; default "English"; Localized thinking, thought, and duration copy; the finished summary also names the toggle.` |
+| `states` | `thinking`, `done`, `open`, `closed` |
+| `tokens` | `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-fast`, `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-duration-slower`, `--bh-easing-emphasized`, `--bh-easing-standard`, `--bh-font-family`, `--bh-icon-stroke-180`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-sm-4`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-xs-medium-font-size`, `--bh-text-body-xs-medium-font-weight`, `--bh-text-body-xs-medium-letter-spacing`, `--bh-text-body-xs-medium-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--bh-thinking-reasoning-fade`, `--bh-thinking-reasoning-max-height`, `--bh-thinking-reasoning-width`, `--elevation-component-focus-ring` |
+<!-- registry-contract:end -->