banhaten 0.3.0 → 0.5.0

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

@@ -1,63 +1,72 @@
-# Menu
-
-Menu is a Radix DropdownMenu-backed action surface for contextual commands, navigation, progress rows, labels, captions, call-to-action rows, submenus, and rich item media.
-
-## API
-
-```tsx
-<MenuRoot>
-  <MenuTrigger>Open menu</MenuTrigger>
-  <MenuContent width="menu">
-    <MenuItem>Profile</MenuItem>
-    <MenuSeparator />
-    <MenuItem kind="button">Upgrade plan</MenuItem>
-  </MenuContent>
-</MenuRoot>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuPortal` | Radix-backed menu shell |
-| `MenuItem`, `MenuItemContent`, media slots | interactive rows |
-| `MenuSub`, `MenuSubTrigger`, `MenuSubContent` | nested menus |
-| `MenuLabel`, `MenuCaption`, `MenuSeparator` | non-interactive structure |
-
-| Prop | Values |
-| --- | --- |
-| `width` | `menu`, `default`, `multiline`, `action`, `auto` |
-| `kind` | `default`, `multiline`, `action`, `progress`, `button` |
-
-## Token Contract
-
-Menu uses Banhaten raised surface, menu shadow, item typography, border, radius, spacing, progress, badge, switch, and focus tokens.
-
-## RTL
-
-Menu uses logical padding and flex direction so leading icons, trailing actions, badges, switches, meta text, and submenus mirror naturally. Directional icons should use `data-rtl-flip="true"`.
-
-## Accessibility
-
-Radix provides menu roles, focus management, typeahead, keyboard navigation, Escape handling, and outside dismissal. Keep non-command copy in labels or captions, not disabled menu items.
-
-## Install
-
-```bash
-npx banhaten add menu
-```
-
-## Examples
-
-Primary registry example: `examples/menu-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs menu` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Uses logical padding and flex direction so leading, trailing, badge, switch, right text, and action slots mirror naturally.
-- `directionalIconFlip`: Use data-rtl-flip="true" on chevrons and arrows that should mirror.
-- `textDirection`: Text slots use dir="auto" by default for Arabic and English labels.
-
+# Menu
+
+Menu is a Radix DropdownMenu-backed action surface for contextual commands, navigation, progress rows, labels, captions, call-to-action rows, submenus, and rich item media.
+
+## API
+
+```tsx
+<MenuRoot>
+  <MenuTrigger>Open menu</MenuTrigger>
+  <MenuContent width="menu">
+    <MenuItem>Profile</MenuItem>
+    <MenuSeparator />
+    <MenuItem kind="button">Upgrade plan</MenuItem>
+  </MenuContent>
+</MenuRoot>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuPortal` | Radix-backed menu shell |
+| `MenuItem`, `MenuItemContent`, media slots | interactive rows |
+| `MenuSub`, `MenuSubTrigger`, `MenuSubContent` | nested menus |
+| `MenuLabel`, `MenuCaption`, `MenuSeparator` | non-interactive structure |
+
+| Prop | Values |
+| --- | --- |
+| `width` | `menu`, `default`, `multiline`, `action`, `auto` |
+| `kind` | `default`, `multiline`, `action`, `progress`, `button` |
+| `MenuItem.onSelect` | `(event: Event) => void` |
+
+`MenuItem.onSelect` uses Radix's native selection `Event`, not React's DOM text-selection event. Selection closes the menu by default; prevent it when a toggle or multi-select flow should remain open:
+
+```tsx
+<MenuItem onSelect={(event: Event) => event.preventDefault()}>
+  Keep this menu open
+</MenuItem>
+```
+
+## Token Contract
+
+Menu uses Banhaten raised surface, menu shadow, item typography, border, radius, spacing, progress, badge, switch, and focus tokens. Leading glyphs are 18px inside 20px slots; trailing 16px affordances remain unchanged.
+
+## RTL
+
+Menu uses logical padding and flex direction so leading icons, trailing actions, badges, switches, meta text, and submenus mirror naturally. Directional icons should use `data-rtl-flip="true"`.
+
+## Accessibility
+
+Radix provides menu roles, focus management, typeahead, keyboard navigation, Escape handling, and outside dismissal. Keep non-command copy in labels or captions, not disabled menu items.
+
+## Install
+
+```bash
+npx banhaten add menu
+```
+
+## Examples
+
+Primary registry example: `examples/menu-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs menu` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical padding and flex direction so leading, trailing, badge, switch, right text, and action slots mirror naturally.
+- `directionalIconFlip`: Use data-rtl-flip="true" on chevrons and arrows that should mirror.
+- `textDirection`: Text slots use dir="auto" by default for Arabic and English labels.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -69,8 +78,9 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `supportedExports` | `components/menu.tsx: Menu, MenuCaption, MenuContent, MenuItem, MenuItemAction, MenuItemAvatar, MenuItemBadge, MenuItemContent, MenuItemDescription, MenuItemIcon, MenuItemMeta, MenuItemSwitch, MenuItemText, MenuItemTitle, MenuLabel, MenuPortal, MenuPreview, MenuProgress, MenuRoot, MenuSeparator, MenuSub, MenuSubContent, MenuSubTrigger, MenuSurface, MenuTrigger, menuItemContentVariants, menuItemIconVariants, menuItemVariants, menuVariants` |
 | `parts` | `Menu`, `MenuPreview`, `MenuSurface`, `MenuRoot`, `MenuTrigger`, `MenuContent`, `MenuPortal`, `MenuSub`, `MenuSubTrigger`, `MenuSubContent`, `MenuItem`, `MenuItemContent`, `MenuItemIcon`, `MenuItemAvatar`, `MenuItemText`, `MenuItemTitle`, `MenuItemDescription`, `MenuItemMeta`, `MenuItemBadge`, `MenuItemSwitch`, `MenuItemAction`, `MenuProgress`, `MenuSeparator`, `MenuLabel`, `MenuCaption` |
 | `registryDependencies` | None |
+| `props.onSelect` | `(event: Event) => void; default null; MenuItem selection handler. Uses Radix's native selection Event, not React's DOM text-selection event; call event.preventDefault() to keep toggle or multi-select menus open.` |
 | `itemKinds` | `default`, `multiline`, `action`, `progress`, `button` |
 | `states` | `default`, `disabled` |
-| `tokens` | `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-icon-stroke-300`, `--bh-interactive-indicator-default`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-hover`, `--bh-interactive-switch-active`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-menu-action-gap`, `--bh-menu-action-height`, `--bh-menu-action-padding-x`, `--bh-menu-badge-height`, `--bh-menu-badge-padding-x`, `--bh-menu-bg`, `--bh-menu-divider-padding-y`, `--bh-menu-gap`, `--bh-menu-icon-padding`, `--bh-menu-item-action-height`, `--bh-menu-item-action-width`, `--bh-menu-item-bg`, `--bh-menu-item-button-height`, `--bh-menu-item-caption-height`, `--bh-menu-item-content-compact-padding-y`, `--bh-menu-item-content-padding`, `--bh-menu-item-default-height`, `--bh-menu-item-default-width`, `--bh-menu-item-divider-height`, `--bh-menu-item-gap`, `--bh-menu-item-hover-bg`, `--bh-menu-item-label-height`, `--bh-menu-item-multiline-height`, `--bh-menu-item-multiline-width`, `--bh-menu-item-padding-x`, `--bh-menu-item-progress-height`, `--bh-menu-item-radius`, `--bh-menu-item-slot-gap`, `--bh-menu-label-padding-x`, `--bh-menu-leading-icon-size`, `--bh-menu-padding-y`, `--bh-menu-progress-gap`, `--bh-menu-progress-height`, `--bh-menu-radius`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-menu-trailing-icon-size`, `--bh-menu-width`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-medium-font-size`, `--bh-text-body-3xs-medium-font-weight`, `--bh-text-body-3xs-medium-letter-spacing`, `--bh-text-body-3xs-medium-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-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-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`, `--shadow-menu` |
+| `tokens` | `--bh-bg-neutral-soft`, `--bh-bg-neutral-subtle`, `--bh-border-brand-strong`, `--bh-border-default`, `--bh-border-subtle`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-control-default`, `--bh-icon-stroke-300`, `--bh-interactive-indicator-default`, `--bh-interactive-outlined-default`, `--bh-interactive-outlined-hover`, `--bh-interactive-switch-active`, `--bh-interactive-switch-default`, `--bh-interactive-switch-disabled`, `--bh-interactive-switch-handle`, `--bh-interactive-switch-handle-disabled`, `--bh-menu-action-gap`, `--bh-menu-action-height`, `--bh-menu-action-padding-x`, `--bh-menu-badge-height`, `--bh-menu-badge-padding-x`, `--bh-menu-bg`, `--bh-menu-divider-padding-y`, `--bh-menu-gap`, `--bh-menu-icon-padding`, `--bh-menu-item-action-height`, `--bh-menu-item-action-width`, `--bh-menu-item-bg`, `--bh-menu-item-button-height`, `--bh-menu-item-caption-height`, `--bh-menu-item-content-compact-padding-y`, `--bh-menu-item-content-padding`, `--bh-menu-item-default-height`, `--bh-menu-item-default-width`, `--bh-menu-item-divider-height`, `--bh-menu-item-gap`, `--bh-menu-item-hover-bg`, `--bh-menu-item-label-height`, `--bh-menu-item-multiline-height`, `--bh-menu-item-multiline-width`, `--bh-menu-item-padding-x`, `--bh-menu-item-progress-height`, `--bh-menu-item-radius`, `--bh-menu-item-slot-gap`, `--bh-menu-label-padding-x`, `--bh-menu-leading-icon-size`, `--bh-menu-leading-icon-slot-size`, `--bh-menu-padding-y`, `--bh-menu-progress-gap`, `--bh-menu-progress-height`, `--bh-menu-radius`, `--bh-menu-switch-handle-size`, `--bh-menu-switch-height`, `--bh-menu-switch-padding`, `--bh-menu-switch-width`, `--bh-menu-trailing-icon-size`, `--bh-menu-width`, `--bh-opacity-60`, `--bh-radius-full`, `--bh-space-5xl-24`, `--bh-space-7xl-40`, `--bh-space-md-8`, `--bh-space-xs-4`, `--bh-space-xxs-2`, `--bh-text-body-2xs-regular-font-size`, `--bh-text-body-2xs-regular-font-weight`, `--bh-text-body-2xs-regular-letter-spacing`, `--bh-text-body-2xs-regular-line-height`, `--bh-text-body-3xs-medium-font-size`, `--bh-text-body-3xs-medium-font-weight`, `--bh-text-body-3xs-medium-letter-spacing`, `--bh-text-body-3xs-medium-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-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-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`, `--elevation-menu` |
 | `widths` | `menu`, `default`, `multiline`, `action`, `auto` |
 <!-- registry-contract:end -->

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

@@ -1,49 +1,49 @@
-# Menubar
-
-Menubar wraps Radix Menubar for application-style top menus.
-
-## API
-
-```tsx
-<Menubar>
-  <MenubarMenu>
-    <MenubarTrigger>File</MenubarTrigger>
-    <MenubarContent>
-      <MenubarItem>New</MenubarItem>
-    </MenubarContent>
-  </MenubarMenu>
-</Menubar>
-```
-
-## Token Contract
-
-Menubar uses Banhaten menu, surface, border, shadow, hover, spacing, and body typography tokens.
-
-## RTL
-
-Triggers, menu items, and shortcuts use logical spacing and inherited direction.
-
-## Accessibility
-
-Radix provides menubar roles, keyboard navigation, open state, and submenu behavior.
-
-## Install
-
-```bash
-npx banhaten add menubar
-```
-
-## Examples
-
-Primary registry example: `examples/menubar-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs menubar` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Triggers, items, and shortcuts use logical spacing.
-
+# Menubar
+
+Menubar wraps Radix Menubar for application-style top menus.
+
+## API
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New</MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+## Token Contract
+
+Menubar uses Banhaten menu, surface, border, shadow, hover, spacing, and body typography tokens.
+
+## RTL
+
+Triggers, menu items, and shortcuts use logical spacing and inherited direction.
+
+## Accessibility
+
+Radix provides menubar roles, keyboard navigation, open state, and submenu behavior.
+
+## Install
+
+```bash
+npx banhaten add menubar
+```
+
+## Examples
+
+Primary registry example: `examples/menubar-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs menubar` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Triggers, items, and shortcuts use logical spacing.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -56,5 +56,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarCheckboxItem`, `MenubarRadioItem`, `MenubarLabel`, `MenubarSeparator`, `MenubarShortcut` |
 | `registryDependencies` | None |
 | `features` | `top menu`, `keyboard navigation`, `checkbox items`, `radio items`, `shortcuts` |
-| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-menu-item-default-height`, `--bh-menu-item-hover-bg`, `--bh-menu-width`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--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-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`, `--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-popover`, `--shadow-component-default`, `--shadow-menu` |
+| `tokens` | `--bh-bg-raised`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-interactive-ghost-hover`, `--bh-interactive-soft-default`, `--bh-menu-item-default-height`, `--bh-menu-item-hover-bg`, `--bh-menu-width`, `--bh-radius-lg-8`, `--bh-radius-md-6`, `--bh-radius-xl-10`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-7xl-40`, `--bh-space-8xl-48`, `--bh-space-md-8`, `--bh-space-sm-6`, `--bh-space-xs-4`, `--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-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`, `--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-popover`, `--elevation-component-default`, `--elevation-menu` |
 <!-- registry-contract:end -->

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

@@ -1,107 +1,107 @@
-# Modal
-
-`Modal` presents a focused dialog surface for decisions and blocking workflows. `ConfirmModal` adds the constrained alert-dialog/confirm pattern for consequential actions.
-
-Figma reference: `Design system 3.0 Copy / Modal`, node `227:5480`.
-
-## Variants
-
-The implementation covers the six-node Modal matrix from Figma:
-
-| Prop | Values |
-| --- | --- |
-| `size` | `sm`, `default`, `lg` |
-| `dir` | `ltr`, `rtl` |
-
-## API
-
-```tsx
-<Modal size="default" />
-<Modal dir="rtl" messages={arabicModalMessages} size="lg" />
-<ConfirmModal intent="danger" confirmLabel="Delete project" />
-```
-
-| Prop | Default |
-| --- | --- |
-| `size` | `sm` |
-| `dir` | inherited |
-| `title` | English default; overrides `messages.title` |
-| `description` | English default; overrides `messages.description` |
-| `messages` | partial localized Modal message catalog |
-| `closeLabel` | overrides `messages.closeLabel` |
-| `showIcon` | `true` |
-| `showCloseButton` | `true` |
-| `showDivider` | `true` |
-| `showFooter` | `true` |
-| `showCheckbox` | `true` |
-| `footer` | none |
-
-`ConfirmModal` also accepts:
-
-| Prop | Default |
-| --- | --- |
-| `intent` | `danger` |
-| `messages` | partial localized ConfirmModal message catalog |
-| `confirmLabel` / `cancelLabel` | English; direct props override `messages` |
-| `confirmLoading` | `false` |
-| `confirmDisabled` | `false` |
-| `preventOutsideDismiss` | `true` |
-| `closeOnConfirm` / `closeOnCancel` | `true` |
-| `onConfirm` / `onCancel` | none |
-
-## Pixel Rules
-
-- Small, Default, and Large modal widths are `440px`, `560px`, and `700px`.
-- The shell uses `--bh-radius-2xl-12`.
-- Header padding is `20px 20px 8px`, with logical end padding reserved for the close button.
-- Body padding is `10px 20px 20px`.
-- Footer padding is `16px 20px`, with a `10px` gap.
-- Actions reuse `Button` with `size="sm"`, `variant="soft"` for the secondary action, and the default variant for the primary action.
-- Confirm actions reuse `Button` with `variant="danger"`, `variant="warning"`, or `variant="default"` from the selected intent.
-- The opt-out control reuses `Checkbox`.
-- Loading confirm actions reuse the Banhaten `Spinner` component.
-
-## Token Contract
-
-The component consumes existing Banhaten variables:
-
-- Surface: `--bh-bg-raised`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-warning-subtle`
-- Border: `--bh-border-subtle`
-- Content: `--bh-content-default`, `--bh-content-subtle`, `--bh-content-danger-default`, `--bh-content-warning-default`
-- Shape: `--bh-radius-2xl-12`, `--bh-radius-full`
-- Space: `--bh-space-xs-4`, `--bh-space-sm-6`, `--bh-space-md-8`, `--bh-space-lg-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`
-- Type: `--bh-text-heading-sm-semibold-*`, `--bh-text-body-md-regular-*`
-- Elevation: `--shadow-component-default`, `--shadow-button-focus`, `--shadow-button-danger-focus`
-
-## Accessibility
-
-- `ModalContent` is backed by Radix Dialog for focus trap, Escape, outside-click dismissal, and ARIA dialog semantics.
-- `ModalTitle` and `ModalDescription` map to Radix dialog title and description primitives.
-- The close affordance is a real button through `ModalCloseButton`.
-- `ConfirmModal` sets `role="alertdialog"`, focuses the cancel action first when present, disables outside-pointer dismissal by default, and can optionally prevent Escape dismissal.
-- `ModalSurface` is presentational and intended for static documentation or visual comparison, not live modal behavior.
-- Direction never selects modal copy. Choose `messages` from the product locale; direct title, description, action, and close-label props have highest precedence.
-
-## Install
-
-```bash
-npx banhaten add modal
-```
-
-## Examples
-
-Primary registry example: `examples/modal-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs modal` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `closePlacement`: Close uses logical inline-end placement so it moves to the left side in RTL.
-- `footerOrder`: The checkbox and action cluster use inherited direction and logical gaps so their order mirrors naturally.
-- `messages`: Direction does not select language. Modal and ConfirmModal accept explicit message catalogs plus direct label overrides.
-- `textDirection`: Title, description, checkbox label, confirm labels, and actions use dir="auto" for Arabic and English copy.
-
+# Modal
+
+`Modal` presents a focused dialog surface for decisions and blocking workflows. `ConfirmModal` adds the constrained alert-dialog/confirm pattern for consequential actions.
+
+Figma reference: `Design system 3.0 Copy / Modal`, node `227:5480`.
+
+## Variants
+
+The implementation covers the six-node Modal matrix from Figma:
+
+| Prop | Values |
+| --- | --- |
+| `size` | `sm`, `default`, `lg` |
+| `dir` | `ltr`, `rtl` |
+
+## API
+
+```tsx
+<Modal size="default" />
+<Modal dir="rtl" messages={arabicModalMessages} size="lg" />
+<ConfirmModal intent="danger" confirmLabel="Delete project" />
+```
+
+| Prop | Default |
+| --- | --- |
+| `size` | `sm` |
+| `dir` | inherited |
+| `title` | English default; overrides `messages.title` |
+| `description` | English default; overrides `messages.description` |
+| `messages` | partial localized Modal message catalog |
+| `closeLabel` | overrides `messages.closeLabel` |
+| `showIcon` | `true` |
+| `showCloseButton` | `true` |
+| `showDivider` | `true` |
+| `showFooter` | `true` |
+| `showCheckbox` | `true` |
+| `footer` | none |
+
+`ConfirmModal` also accepts:
+
+| Prop | Default |
+| --- | --- |
+| `intent` | `danger` |
+| `messages` | partial localized ConfirmModal message catalog |
+| `confirmLabel` / `cancelLabel` | English; direct props override `messages` |
+| `confirmLoading` | `false` |
+| `confirmDisabled` | `false` |
+| `preventOutsideDismiss` | `true` |
+| `closeOnConfirm` / `closeOnCancel` | `true` |
+| `onConfirm` / `onCancel` | none |
+
+## Pixel Rules
+
+- Small, Default, and Large modal widths are `440px`, `560px`, and `700px`.
+- The shell uses `--bh-radius-2xl-12`.
+- Header padding is `20px 20px 8px`, with logical end padding reserved for the close button.
+- Body padding is `10px 20px 20px`.
+- Footer padding is `16px 20px`, with a `10px` gap.
+- Actions reuse `Button` with `size="sm"`, `variant="soft"` for the secondary action, and the default variant for the primary action.
+- Confirm actions reuse `Button` with `variant="danger"`, `variant="warning"`, or `variant="default"` from the selected intent.
+- The opt-out control reuses `Checkbox`.
+- Loading confirm actions reuse the Banhaten `Spinner` component.
+
+## Token Contract
+
+The component consumes existing Banhaten variables:
+
+- Surface: `--bh-bg-raised`, `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-warning-subtle`
+- Border: `--bh-border-subtle`
+- Content: `--bh-content-default`, `--bh-content-subtle`, `--bh-content-danger-default`, `--bh-content-warning-default`
+- Shape: `--bh-radius-2xl-12`, `--bh-radius-full`
+- Space: `--bh-space-xs-4`, `--bh-space-sm-6`, `--bh-space-md-8`, `--bh-space-lg-10`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`
+- Type: `--bh-text-heading-sm-semibold-*`, `--bh-text-body-md-regular-*`
+- Elevation: `--elevation-component-default`, `--elevation-button-focus`, `--elevation-button-danger-focus`
+
+## Accessibility
+
+- `ModalContent` is backed by Radix Dialog for focus trap, Escape, outside-click dismissal, and ARIA dialog semantics.
+- `ModalTitle` and `ModalDescription` map to Radix dialog title and description primitives.
+- The close affordance is a real button through `ModalCloseButton`.
+- `ConfirmModal` sets `role="alertdialog"`, focuses the cancel action first when present, disables outside-pointer dismissal by default, and can optionally prevent Escape dismissal.
+- `ModalSurface` is presentational and intended for static documentation or visual comparison, not live modal behavior.
+- Direction never selects modal copy. Choose `messages` from the product locale; direct title, description, action, and close-label props have highest precedence.
+
+## Install
+
+```bash
+npx banhaten add modal
+```
+
+## Examples
+
+Primary registry example: `examples/modal-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs modal` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `closePlacement`: Close uses logical inline-end placement so it moves to the left side in RTL.
+- `footerOrder`: The checkbox and action cluster use inherited direction and logical gaps so their order mirrors naturally.
+- `messages`: Direction does not select language. Modal and ConfirmModal accept explicit message catalogs plus direct label overrides.
+- `textDirection`: Title, description, checkbox label, confirm labels, and actions use dir="auto" for Arabic and English copy.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -115,5 +115,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | `alert-dialog`, `button`, `checkbox`, `spinner` |
 | `intents` | `default`, `warning`, `danger` |
 | `sizes` | `sm`, `default`, `lg` |
-| `tokens` | `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-modal-action-label-padding-x`, `--bh-modal-border`, `--bh-modal-width`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--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-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--shadow-button-focus`, `--shadow-lg`, `--shadow-modal` |
+| `tokens` | `--bh-bg-backdrop`, `--bh-bg-danger-subtle`, `--bh-bg-raised`, `--bh-bg-warning-subtle`, `--bh-border-subtle`, `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-subtle`, `--bh-content-warning-default`, `--bh-icon-stroke-200`, `--bh-interactive-ghost-hover`, `--bh-modal-action-label-padding-x`, `--bh-modal-border`, `--bh-modal-width`, `--bh-radius-2xl-12`, `--bh-radius-full`, `--bh-space-12xl-128`, `--bh-space-16xl-256`, `--bh-space-19xl-384`, `--bh-space-3xl-16`, `--bh-space-4xl-20`, `--bh-space-5xl-24`, `--bh-space-6xl-32`, `--bh-space-8xl-48`, `--bh-space-9xl-64`, `--bh-space-lg-10`, `--bh-space-md-8`, `--bh-space-sm-6`, `--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-heading-sm-semibold-font-size`, `--bh-text-heading-sm-semibold-font-weight`, `--bh-text-heading-sm-semibold-letter-spacing`, `--bh-text-heading-sm-semibold-line-height`, `--bh-z-overlay`, `--elevation-06`, `--elevation-button-focus`, `--elevation-modal` |
 <!-- registry-contract:end -->

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

@@ -1,56 +1,56 @@
-# Native Select
-
-Native Select is a tokenized native `<select>` field for platform forms, mobile fallback, and lightweight option sets.
-
-## API
-
-```tsx
-<NativeSelect
-  label="Workspace"
-  options={[
-    { label: "Design", value: "design" },
-    { label: "Engineering", value: "engineering" },
-  ]}
-/>
-```
-
-| Prop | Values |
-| --- | --- |
-| `size` | `md`, `lg` |
-| `variant` | `default`, `soft` |
-| `state` | `default`, `filled`, `error`, `disabled` |
-| `options` | array of `{ label, value, disabled }` |
-
-## Token Contract
-
-Native Select reuses Banhaten select width, label, helper, trigger, border, focus, icon, and validation tokens.
-
-## RTL
-
-Native Select accepts `dir` and uses logical padding plus an inline-end chevron.
-
-## Accessibility
-
-Prefer `label` or an external `<Label htmlFor>` and use helper or error copy for validation context.
-
-## Install
-
-```bash
-npx banhaten add native-select
-```
-
-## Examples
-
-Primary registry example: `examples/native-select-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs native-select` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Uses logical padding and inline-end chevron placement.
-- `textDirection`: Label and helper copy use dir="auto" through Label and helper text.
-
+# Native Select
+
+Native Select is a tokenized native `<select>` field for platform forms, mobile fallback, and lightweight option sets.
+
+## API
+
+```tsx
+<NativeSelect
+  label="Workspace"
+  options={[
+    { label: "Design", value: "design" },
+    { label: "Engineering", value: "engineering" },
+  ]}
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `lg` |
+| `variant` | `default`, `soft` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+| `options` | array of `{ label, value, disabled }` |
+
+## Token Contract
+
+Native Select reuses Banhaten select width, label, helper, trigger, border, focus, icon, and validation tokens.
+
+## RTL
+
+Native Select accepts `dir` and uses logical padding plus an inline-end chevron.
+
+## Accessibility
+
+Prefer `label` or an external `<Label htmlFor>` and use helper or error copy for validation context.
+
+## Install
+
+```bash
+npx banhaten add native-select
+```
+
+## Examples
+
+Primary registry example: `examples/native-select-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs native-select` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Uses logical padding and inline-end chevron placement.
+- `textDirection`: Label and helper copy use dir="auto" through Label and helper text.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -65,6 +65,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `features` | `options array`, `native children`, `label`, `helper text`, `error text` |
 | `sizes` | `md`, `lg` |
 | `states` | `default`, `filled`, `error`, `disabled` |
-| `tokens` | `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-input-lg-height`, `--bh-input-md-height`, `--bh-select-field-gap`, `--bh-select-trigger-bg`, `--bh-select-trigger-bg-disabled`, `--bh-select-trigger-bg-soft`, `--bh-select-trigger-border`, `--bh-select-trigger-border-current`, `--bh-select-trigger-border-disabled`, `--bh-select-trigger-border-error`, `--bh-select-trigger-border-focus`, `--bh-select-trigger-icon-color`, `--bh-select-trigger-padding-x`, `--bh-select-trigger-radius`, `--bh-select-width`, `--bh-space-3xl-16`, `--bh-space-8xl-48`, `--bh-space-sm-6`, `--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-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-component-default`, `--shadow-select-danger-focus-ring`, `--shadow-select-focus-ring`, `--shadow-select-trigger` |
+| `tokens` | `--bh-border-width-default`, `--bh-content-danger-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-subtle`, `--bh-icon-stroke-200`, `--bh-input-lg-height`, `--bh-input-md-height`, `--bh-select-field-gap`, `--bh-select-trigger-bg`, `--bh-select-trigger-bg-disabled`, `--bh-select-trigger-bg-soft`, `--bh-select-trigger-border`, `--bh-select-trigger-border-current`, `--bh-select-trigger-border-disabled`, `--bh-select-trigger-border-error`, `--bh-select-trigger-border-focus`, `--bh-select-trigger-icon-color`, `--bh-select-trigger-padding-x`, `--bh-select-trigger-radius`, `--bh-select-width`, `--bh-space-3xl-16`, `--bh-space-8xl-48`, `--bh-space-sm-6`, `--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-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-component-default`, `--elevation-select-danger-focus-ring`, `--elevation-select-focus-ring`, `--elevation-select-trigger` |
 | `variants` | `default`, `soft` |
 <!-- registry-contract:end -->