banhaten 0.3.0 → 0.5.0

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

@@ -1,49 +1,49 @@
-# Carousel
-
-Carousel is an Embla-backed carousel with content, item, previous, and next controls.
-
-## API
-
-```tsx
-<Carousel messages={{ previousSlide: "Previous item", nextSlide: "Next item" }}>
-  <CarouselContent>
-    <CarouselItem>Slide</CarouselItem>
-  </CarouselContent>
-  <CarouselPrevious />
-  <CarouselNext />
-</Carousel>
-```
-
-## Token Contract
-
-Carousel controls use Banhaten Button tokens, spacing, radius, and directional icon behavior.
-
-## RTL
-
-Directional icons flip in RTL. Direction does not select a language; pass `messages` on `Carousel` or `aria-label` on an individual control. Set Embla options through `opts` when you need a custom direction strategy.
-
-## Accessibility
-
-Carousel exposes a region and English button-label defaults for previous and next controls. `messages` accepts partial localized overrides, while a control's direct `aria-label` has highest precedence.
-
-## Install
-
-```bash
-npx banhaten add carousel
-```
-
-## Examples
-
-Primary registry example: `examples/carousel-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs carousel` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `directionalIconFlip`: Previous and next arrow icons flip in RTL.
-- `messages`: Direction does not select language. Pass messages or direct aria-label overrides for localized control names.
-
+# Carousel
+
+Carousel is an Embla-backed carousel with content, item, previous, and next controls.
+
+## API
+
+```tsx
+<Carousel messages={{ previousSlide: "Previous item", nextSlide: "Next item" }}>
+  <CarouselContent>
+    <CarouselItem>Slide</CarouselItem>
+  </CarouselContent>
+  <CarouselPrevious />
+  <CarouselNext />
+</Carousel>
+```
+
+## Token Contract
+
+Carousel controls use Banhaten Button tokens, spacing, radius, and directional icon behavior.
+
+## RTL
+
+Directional icons flip in RTL. Direction does not select a language; pass `messages` on `Carousel` or `aria-label` on an individual control. Set Embla options through `opts` when you need a custom direction strategy.
+
+## Accessibility
+
+Carousel exposes a region and English button-label defaults for previous and next controls. `messages` accepts partial localized overrides, while a control's direct `aria-label` has highest precedence.
+
+## Install
+
+```bash
+npx banhaten add carousel
+```
+
+## Examples
+
+Primary registry example: `examples/carousel-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs carousel` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `directionalIconFlip`: Previous and next arrow icons flip in RTL.
+- `messages`: Direction does not select language. Pass messages or direct aria-label overrides for localized control names.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 

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

@@ -1,49 +1,49 @@
-# Catalog Components
-
-Catalog Components is an expanded-tier showcase bundle for catalog-style product pages. It brings together breadcrumbs, catalog-only dividers, catalog tag previews, file upload states, and table previews.
-
-## API
-
-```tsx
-<CatalogComponentsShowcase dir="ltr" />
-```
-
-| Included part | Source |
-| --- | --- |
-| `Breadcrumbs` | expanded breadcrumbs component |
-| `CatalogContentDivider`, `CatalogDivider` | catalog divider visuals |
-| `Tag` | core tag component, previewed in the showcase |
-| `FileUpload` | expanded upload states |
-| `Table` | expanded table preview |
-
-## Token Contract
-
-The bundle uses expanded-tier CSS files plus Banhaten button, surface, border, spacing, typography, tag, upload, and table tokens. Treat this as a composition bundle, not a new primitive token namespace.
-
-## RTL
-
-Catalog examples include LTR and RTL states through the child components. Breadcrumbs, upload rows, table content, and tags should inherit direction from the wrapper.
-
-## Accessibility
-
-Use the individual child component docs for production semantics. This page is a bundled visual reference for catalog composition and component fit.
-
-## Install
-
-```bash
-npx banhaten add catalog-components
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/catalog-components-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs catalog-components` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
-
+# Catalog Components
+
+Catalog Components is an expanded-tier showcase bundle for catalog-style product pages. It brings together breadcrumbs, catalog-only dividers, catalog tag previews, file upload states, and table previews.
+
+## API
+
+```tsx
+<CatalogComponentsShowcase dir="ltr" />
+```
+
+| Included part | Source |
+| --- | --- |
+| `Breadcrumbs` | expanded breadcrumbs component |
+| `CatalogContentDivider`, `CatalogDivider` | catalog divider visuals |
+| `Tag` | core tag component, previewed in the showcase |
+| `FileUpload` | expanded upload states |
+| `Table` | expanded table preview |
+
+## Token Contract
+
+The bundle uses expanded-tier CSS files plus Banhaten button, surface, border, spacing, typography, tag, upload, and table tokens. Treat this as a composition bundle, not a new primitive token namespace.
+
+## RTL
+
+Catalog examples include LTR and RTL states through the child components. Breadcrumbs, upload rows, table content, and tags should inherit direction from the wrapper.
+
+## Accessibility
+
+Use the individual child component docs for production semantics. This page is a bundled visual reference for catalog composition and component fit.
+
+## Install
+
+```bash
+npx banhaten add catalog-components
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/catalog-components-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs catalog-components` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -57,6 +57,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | `breadcrumbs`, `button`, `file-upload`, `table`, `tag` |
 | `modes` | `showcase`, `divider`, `content-divider` |
 | `states` | `label`, `action`, `disabled-action` |
-| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-catalog-file-grid-max`, `--bh-catalog-file-grid-min`, `--bh-catalog-file-preview-max`, `--bh-catalog-file-preview-min`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-opacity-65`, `--bh-radius-lg-8`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--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-base-letter-spacing`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-heading-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-line-height`, `--shadow-component-default` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-catalog-file-grid-max`, `--bh-catalog-file-grid-min`, `--bh-catalog-file-preview-max`, `--bh-catalog-file-preview-min`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-opacity-65`, `--bh-radius-lg-8`, `--bh-space-2xl-14`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--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-base-letter-spacing`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size`, `--bh-text-heading-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-line-height`, `--elevation-component-default` |
 | `variants` | `solid-divider`, `dotted-divider` |
 <!-- registry-contract:end -->

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

@@ -1,46 +1,110 @@
 # Chart
 
-Chart provides Recharts wrappers with Banhaten chart tokens, responsive sizing, tooltip content, and legend content.
+Eight ECharts families and 18 ready-made blocks adapted from [EvilCharts](https://evilcharts.com/docs/echarts/area-chart/blocks), using Banhaten tokens throughout. Existing Recharts wrappers remain compatible.
+
+## Install
+
+```bash
+npx banhaten add chart
+```
+
+This installs the source modules and declares `echarts` and `recharts`. The playground loads the chart page separately; chart instances initialize when visible.
 
 ## API
 
+Use `DataChart` for application data. Every series uses a Banhaten categorical palette index; raw colors are not part of the specification.
+
 ```tsx
-<ChartContainer config={{ revenue: { color: "var(--bh-chart-1)" } }}>
-  <LineChart data={data}>
-    <ChartTooltip content={<ChartTooltipContent />} />
-    <Line dataKey="revenue" stroke="var(--color-revenue)" />
-  </LineChart>
-</ChartContainer>
+import { DataChart } from "@/components/ui/data-chart"
+import type { ChartSpec } from "@/components/ui/chart-options"
+
+const spec: ChartSpec = {
+  family: "area",
+  variant: "gradient",
+  categoryKey: "month",
+  data: [
+    { month: "Jan", revenue: 120, costs: 80 },
+    { month: "Feb", revenue: 180, costs: 95 },
+    { month: "Mar", revenue: 150, costs: 90 },
+  ],
+  series: [
+    { key: "revenue", label: "Revenue", colorIndex: 0 },
+    { key: "costs", label: "Costs", colorIndex: 1 },
+  ],
+  legend: true,
+  brush: true,
+}
+
+<DataChart label="Revenue and costs" description="Revenue exceeds costs in each month." spec={spec} />
 ```
 
+`DataChart` accepts `spec`, required `label`, optional `description`, `loading`, `loadingLabel`, `emptyLabel`, and container attributes. `ChartSpec` selects `area`, `line`, `bar`, `composed`, `radar`, `pie`, `radial`, or `sankey`. Use `stack="stacked"` or `stack="percent"`, `horizontal`, `labels`, `grid`, `max`, `nodes`, and `links` where applicable. Curves are native ECharts approximations, matching the reference implementation; named spline variants are not mathematical spline implementations.
+
+Shared parts support seven `legendIndicator` shapes; series `dotStyle` and `activeDotStyle`; `tooltipRadius`, `tooltipSurface`, `tooltipPosition`, and `tooltipCursor`. Translucent tooltips use the Banhaten opacity token. Brush controls are enabled with `brush: true`. Forecast `buffer` tails apply to independent series; stacked series retain their complete data to preserve totals.
+
+Use `EChart` for advanced native options. Its `option(theme)` factory receives resolved inherited Banhaten colors, font metrics, spacing, radii, opacity, direction, and reduced-motion preference. An optional `onReady(chart, theme)` callback can attach interactions and return their cleanup. Native options supplied by callers must also use these tokens.
+
+```tsx
+import { ChartBlock } from "@/components/ui/chart-block"
+
+<ChartBlock block="latency" />
+```
+
+`ChartBlock` provides example compositions with illustrative datasets. Time-range controls update both chart data and summaries. The visible data table uses the same filtered rows. Use `DataChart` for your own production data or adapt the installed block source.
+
+| Family | Block IDs |
+| --- | --- |
+| Area | `latency`, `portfolio`, `benchmark`, `audience` |
+| Line | `payouts`, `shipments` |
+| Bar | `peak`, `grid`, `monospace` |
+| Pie | `market-share`, `progress-rings`, `revenue-mix`, `reliability-score` |
+| Radial | `budget`, `ride`, `cache-tiers` |
+| Sankey | `allocation`, `pipeline` |
+
+Legacy `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, and `ChartLegendContent` still compose with Recharts. Their `config` maps series names to `--color-*` CSS variables.
+
 ## Token Contract
 
-Chart adds `--bh-chart-1` through `--bh-chart-5` via the token build. `ChartContainer` maps config entries to `--color-*` variables.
+- Marks use the eight `--bh-chart-categorical-*` colors. Neutral tracks, surfaces, borders, and text use existing semantic tokens.
+- Fonts, weights, sizes, line heights, spacing, radii, opacity, and animation duration resolve from the chart's inherited Banhaten tokens. No duplicate theme palette is maintained.
+- Theme, font, radius, and direction changes update mounted charts. Existing legend selections and brush range survive theme updates.
+- Gradient fills and patterns remain available. Colored blur shadows and glow variants are omitted. Tooltips have no shadow.
+- Numeric data, chart percentages, angles, and geometry ratios describe the visualization rather than design tokens.
+- All source modules, including TypeScript helpers, are included in token governance checks.
 
-## RTL
+### Chart corner radii
 
-Chart layout depends on the Recharts configuration. Surrounding labels and legends use logical layout.
+Keep chart marks subtly rounded so their endpoints and stacked joins remain easy to compare. Use `--bh-radius-sm-4` for exposed bar ends and separated donut slices: 4px in the default theme, 6px in rounded mode, and 0px in sharp mode. The native `option(theme)` API exposes this as `theme.markRadius` separately from surface and tooltip radii.
 
-## Accessibility
+| Mark | Corner treatment |
+| --- | --- |
+| Bars, including composed charts | Small radius at the exposed value end; square at the baseline. |
+| Stacked bars | Square between segments; Small radius only at the outer end of the stack. |
+| Standard pie and donut slices | Square slice corners (0px). |
+| Separated and petal donut slices | Small radius; avoid pill-shaped corners. |
 
-Pair charts with text summaries or tables for critical data. Tooltips are supplemental.
+## RTL
 
-## Install
+`DataChart` inherits direction or accepts `dir="rtl"`. Cartesian category axes and value-axis placement mirror. Block controls, summaries, and tables follow logical layout. Data order is preserved. Text uses the active Banhaten Arabic and English font tokens.
 
-```bash
-npx banhaten add chart
-```
+## Accessibility
+
+Supply a meaningful `label` and a concise `description` of the finding. Charts are labelled figures; hover tooltips supplement that description. Blocks provide keyboard-operable time ranges and expandable data tables. For application data, provide a corresponding table or text summary when precise values matter. Do not rely on color alone: use labels, patterns, dashed strokes, or point markers. Reduced motion disables animations and moving dashes.
 
 ## Examples
 
-Primary registry example: `examples/chart-demo.tsx`.
+Primary registry example: `examples/chart-demo.tsx`. Ready-made block example: `examples/chart-block-demo.tsx`.
 
-Open the live component page or run `npx banhaten docs chart` to inspect source files, install command, and examples.
+The live Chart page contains all eight families, all 18 blocks, and an Arabic RTL example. Examples include gradients, texture fills, grouped/stacked/percentage series, dots, brush controls, circular and polygon radar grids, pie labels, radial progress, and Sankey links.
 
 ## RTL Rules
 
 - `inheritsDirection`: true
-- `layout`: Chart labels and legends should use logical layout; chart geometry is controlled by Recharts.
+- `layout`: Cartesian axes mirror; block layouts use logical properties. Legacy Recharts geometry remains caller-controlled.
+
+## Source attribution
+
+Chart designs and illustrative block data are adapted from the MIT-licensed [EvilCharts repository](https://github.com/legions-developer/evilcharts). Its notice is included in the installed chart files. The shared renderer uses Apache ECharts under Apache-2.0. Banhaten's token layer, family builders, and lifecycle replace duplicated source chart implementations.
 
 <!-- registry-contract:start -->
 ## Registry Contract
@@ -50,9 +114,16 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/chart.tsx: ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent` |
-| `parts` | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent` |
-| `registryDependencies` | None |
-| `features` | `responsive container`, `tooltip content`, `legend content`, `config colors` |
-| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-subtle`, `--bh-chart-categorical-aqua`, `--bh-chart-categorical-brand`, `--bh-chart-categorical-danger`, `--bh-chart-categorical-fuchsia`, `--bh-chart-categorical-information`, `--bh-chart-categorical-purple`, `--bh-chart-categorical-success`, `--bh-chart-categorical-warning`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--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-regular-font-size`, `--bh-text-body-xs-regular-font-weight`, `--bh-text-body-xs-regular-letter-spacing`, `--bh-text-body-xs-regular-line-height`, `--shadow-popover` |
+| `supportedExports` | `components/chart.tsx: ChartContainer, ChartLegend, ChartLegendContent, ChartTooltip, ChartTooltipContent`, `components/echart.tsx: EChart`, `components/chart-options.ts: createChartOption`, `components/data-chart.tsx: DataChart`, `components/chart-block.tsx: ChartBlock, chartBlocks` |
+| `parts` | `DataChart`, `ChartBlock`, `EChart`, `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent` |
+| `registryDependencies` | `button`, `progress` |
+| `props.spec` | `ChartSpec; default null; DataChart: family, data, series, variant, stacking, labels, brush, and interaction options. Series colors are Banhaten palette indices.` |
+| `props.label` | `string; default null; DataChart / EChart: required accessible chart name.` |
+| `props.description` | `string; default null; DataChart / EChart: optional accessible text summary.` |
+| `props.block` | `ChartBlockId; default null; ChartBlock: one of 18 documented blocks, with illustrative data and period controls where applicable.` |
+| `props.option` | `(theme: EChartTheme) => EChartsOption; default null; EChart: advanced option factory receives resolved inherited Banhaten tokens.` |
+| `props.onReady` | `(chart, theme) => void \| (() => void); default null; EChart: attach custom interactions and return their cleanup.` |
+| `props.config` | `ChartConfig; default null; Legacy ChartContainer: maps series names to CSS color variables.` |
+| `features` | `eight chart families`, `18 ready-made blocks`, `live theme and font tokens`, `responsive SVG`, `tooltips and legends`, `range brush`, `pattern fills`, `reduced motion`, `RTL`, `Recharts compatibility` |
+| `tokens` | `--bh-bg-neutral-subtle`, `--bh-bg-raised`, `--bh-border-default`, `--bh-border-focus`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-chart-categorical-aqua`, `--bh-chart-categorical-brand`, `--bh-chart-categorical-danger`, `--bh-chart-categorical-fuchsia`, `--bh-chart-categorical-information`, `--bh-chart-categorical-purple`, `--bh-chart-categorical-success`, `--bh-chart-categorical-warning`, `--bh-chart-neutral-default`, `--bh-content-brand-default`, `--bh-content-default`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-duration-default`, `--bh-focus-ring-width`, `--bh-font-family`, `--bh-font-family-mono`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-opacity-15`, `--bh-opacity-30`, `--bh-opacity-90`, `--bh-opacity-muted`, `--bh-radius-3xl-16`, `--bh-radius-full`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-sm-4`, `--bh-radius-xl-10`, `--bh-radius-xs-2`, `--bh-space-11xl-96`, `--bh-space-12xl-128`, `--bh-space-15xl-224`, `--bh-space-17xl-288`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-9xl-64`, `--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-2xs-regular-font-size`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-regular-font-size`, `--bh-text-body-3xs-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-medium-font-size`, `--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`, `--bh-text-heading-lg-semibold-font-size`, `--bh-text-heading-lg-semibold-font-weight`, `--bh-text-heading-lg-semibold-letter-spacing`, `--bh-text-heading-lg-semibold-line-height`, `--bh-text-heading-md-semibold-font-size`, `--bh-text-heading-md-semibold-font-weight`, `--bh-text-heading-md-semibold-letter-spacing`, `--bh-text-heading-md-semibold-line-height`, `--bh-text-heading-xs-semibold-font-size`, `--bh-text-heading-xs-semibold-font-weight`, `--bh-text-heading-xs-semibold-letter-spacing`, `--bh-text-heading-xs-semibold-line-height`, `--elevation-popover` |
 <!-- registry-contract:end -->

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

@@ -1,56 +1,56 @@
-# 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.
-
+# 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.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -64,5 +64,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | None |
 | `cardPositions` | `start`, `end` |
 | `states` | `unchecked`, `checked`, `indeterminate`, `selected`, `disabled` |
-| `tokens` | `--bh-bg-default`, `--bh-bg-disabled`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-brand-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-checkbox-card-border`, `--bh-checkbox-card-border-width`, `--bh-checkbox-card-border-width-active`, `--bh-checkbox-card-border-width-current`, `--bh-checkbox-card-content-gap`, `--bh-checkbox-card-gap`, `--bh-checkbox-card-label-gap`, `--bh-checkbox-card-media-icon-size`, `--bh-checkbox-card-padding`, `--bh-checkbox-card-radius`, `--bh-checkbox-card-text-gap`, `--bh-checkbox-card-width`, `--bh-checkbox-control-border`, `--bh-checkbox-control-radius`, `--bh-checkbox-control-size`, `--bh-checkbox-icon-size`, `--bh-checkbox-root-size`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-on-color`, `--bh-content-subtle`, `--bh-icon-stroke-300`, `--bh-interactive-checkbox-default`, `--bh-interactive-checkbox-hover`, `--bh-opacity-60`, `--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-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--shadow-checkbox-card`, `--shadow-checkbox-card-focus`, `--shadow-checkbox-control`, `--shadow-checkbox-focus`, `--shadow-component-default` |
+| `tokens` | `--bh-bg-default`, `--bh-bg-disabled`, `--bh-bg-raised`, `--bh-bg-raised-hover`, `--bh-border-brand-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-checkbox-card-border`, `--bh-checkbox-card-border-width`, `--bh-checkbox-card-border-width-active`, `--bh-checkbox-card-border-width-current`, `--bh-checkbox-card-content-gap`, `--bh-checkbox-card-gap`, `--bh-checkbox-card-label-gap`, `--bh-checkbox-card-media-icon-size`, `--bh-checkbox-card-padding`, `--bh-checkbox-card-radius`, `--bh-checkbox-card-text-gap`, `--bh-checkbox-card-width`, `--bh-checkbox-control-border`, `--bh-checkbox-control-radius`, `--bh-checkbox-control-size`, `--bh-checkbox-icon-size`, `--bh-checkbox-root-size`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-icon-stroke-300`, `--bh-interactive-checkbox-content`, `--bh-interactive-checkbox-default`, `--bh-interactive-checkbox-hover`, `--bh-opacity-60`, `--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-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--elevation-checkbox-card`, `--elevation-checkbox-card-focus`, `--elevation-checkbox-control`, `--elevation-checkbox-focus`, `--elevation-component-default` |
 <!-- registry-contract:end -->

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

@@ -1,52 +1,66 @@
-# 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.
-
+# 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; with `asChild` your own element becomes the unstyled trigger |
+| `CollapsibleContent` | expandable content region |
+| `CollapsiblePanel` | unstyled content that animates its height open and closed |
+
+Components with their own disclosure design compose the unstyled pieces:
+
+```tsx
+<Collapsible open={open} onOpenChange={setOpen}>
+  <CollapsibleTrigger asChild>
+    <button type="button">Show details</button>
+  </CollapsibleTrigger>
+  <CollapsiblePanel>…</CollapsiblePanel>
+</Collapsible>
+```
+
+`CollapsiblePanel` animates on `--collapsible-panel-duration` (default `--bh-duration-moderate`) and `--collapsible-panel-easing` (default `--bh-easing-emphasized`); set them on the panel to tune the motion.
+
+## 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. Closed content unmounts after its closing animation, so nothing inside a closed section can be focused or read.
+
+## 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.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -55,9 +69,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 
 | Field | Values |
 | --- | --- |
-| `supportedExports` | `components/collapsible.tsx: Collapsible, CollapsibleContent, CollapsibleTrigger` |
-| `parts` | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent` |
+| `supportedExports` | `components/collapsible.tsx: Collapsible, CollapsibleContent, CollapsiblePanel, CollapsibleTrigger` |
+| `parts` | `Collapsible`, `CollapsibleTrigger`, `CollapsibleContent`, `CollapsiblePanel` |
 | `registryDependencies` | None |
-| `features` | `controlled state`, `uncontrolled state`, `keyboard trigger`, `RTL` |
-| `tokens` | `--bh-content-default`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-space-3xl-16`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--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-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--shadow-button-focus` |
+| `features` | `controlled state`, `uncontrolled state`, `keyboard trigger`, `RTL`, `animated panel`, `custom trigger with asChild` |
+| `tokens` | `--bh-content-default`, `--bh-content-subtle`, `--bh-duration-moderate`, `--bh-easing-emphasized`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-radius-lg-8`, `--bh-space-3xl-16`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-xl-12`, `--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-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--elevation-button-focus` |
 <!-- registry-contract:end -->