banhaten 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,139 +1,177 @@
-# Changelog
-
-All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
-
-## Unreleased
-
-## 0.5.0 - 2026-10-16
-
-### Added
-
-- ECharts-backed `DataChart`, `EChart`, and `ChartBlock` APIs with eight chart families, 18 example blocks, token-driven themes, and interactive legends, tooltips, and brush controls. Existing Recharts wrappers remain supported.
-- AI conversation components built only from Banhaten primitives and tokens: `ThinkingState`, `ThinkingReasoning`, `StreamingText` with a `useTypewriter` hook for local reveals, `InlineCitations` composed from `CitationProse` and `CitationMark`, `TaskList` with `TaskListRoot`, `TaskListHeader`, `TaskListItems`, and `TaskListPreview` parts for static and folded lists, `AgentInput`, and the approval cards (`ApprovalQuestions`, `ApprovalCommand`, `ApprovalPlan`) with the `ApprovalFrame` shell they share for custom decisions, each with registry metadata, documentation, examples, playground pages, and tests.
-- `ShimmerText` for labels of work in progress and `RollingCount` for counts that roll each changed digit into place, general-purpose components the AI conversation components build on, each with registry metadata, documentation, examples, playground pages, and tests.
-- Foundation motion tokens `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-duration-slower`, and `--bh-easing-emphasized`; component tokens for the reasoning block, streaming caret, citation marks, agent input, shimmer text, and task list; and a `--bh-font-family-mono` family for command blocks.
-- Shared hooks installed with the base files: `use-motion-end` runs script work after the CSS motion it waits for instead of after copied timings, `use-controllable-state` backs controlled and uncontrolled props, `use-reduced-motion` follows the user's motion setting, and `use-listbox-navigation` gives Autocomplete and the Agent Input skill palette one keyboard model.
-- `CollapsiblePanel`, an unstyled Collapsible part that animates its height open and closed, and `asChild` support on `CollapsibleTrigger` for components with their own disclosure design.
-- Registry file entries accept `"internal": true`. An internal module installs and compiles with its component, but its exports stay out of the supported import contract, so a large component can be split into modules without publishing them.
-
-### Changed
-
-- Autocomplete moves the active option to the first enabled match when filtering removes the one that was active, instead of leaving no option active.
-- Input quantity steppers now update values using native number-input constraints and change events; button and dropdown compositions expose native action props.
-- Public depth tokens use the `--elevation-*` namespace, with seven numbered steps and semantic component aliases. Token graphs rebind at nested theme boundaries.
-- Sidebar collapse uses staged transitions and dedicated motion tokens.
-
-### Fixed
-
-- CLI writes detect concurrent edits before replacing consumer files.
-- Checked indicators retain contrast in dark themes; label-less Selects receive accessible names; Input exposes required semantics; Toolbar defaults to group semantics.
-- Breadcrumbs, keyboard shortcuts, Page Header, Tabs, and Table improve content direction, overflow handling, and pagination sizing.
-- Packed-artifact validation invokes npm directly through Node on Windows, avoiding the `spawn EINVAL` failure from launching `npm.cmd`.
-- Refreshed dependency resolutions for runtime and playground security fixes; Windows token-security fixtures use directory junctions, and browser tests include the Windows autofill workaround.
-
-### Migration
-
-- Replace `--shadow-xs`, `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`, and `--shadow-3xl` with `--elevation-01` through `--elevation-07`, respectively. Rename semantic `--shadow-*` references and overrides to their corresponding `--elevation-*` names; the old token names are no longer published.
-- Run `npx banhaten@0.5.0 diff` before `npx banhaten@0.5.0 update`. Review customized component files and token overrides before using `--force`.
-- Updating `chart` adds an `echarts` dependency alongside `recharts`; run the package-manager install command printed by the CLI. Existing Recharts compositions continue to work.
-- Quantity Input now renders a number input with working steppers. Review custom click handlers to avoid applying a second increment, and call `preventDefault()` in a stepper handler when overriding the built-in step.
-
-## 0.4.0 - 2026-08-22
-
-### Added
-
-- A Figma-aligned Sidebar composition with brand and workspace headers, header and group actions, menu badges, nested and tree navigation, user footers, rail tooltips, controlled state, and documented expanded, collapsed, LTR, and RTL variants.
-- `Shortcut`, a compact combined keyboard-chord primitive for inputs and constrained action rows, alongside the existing separated-keycap `KbdShortcut` API.
-- A Test Lab V2 playground with scenario navigation, a focused inspector, state-comparison boards, responsive previews, and browser coverage for the new QA workflow.
-- Noto Sans Arabic as the default Arabic playground font, with the previous Arabic font options retained.
-
-### Changed
-
-- The default brand theme is now monochrome `gray`; `blue` remains available as an explicit alternate theme.
-- Elevation now publishes the complete seven-level Figma scale as `--elevation-01` through `--elevation-07`, with dedicated reviewed light and dark values and updated token documentation.
-- Shared icon and icon-slot geometry is tokenized across controls, navigation, feedback, and data-display components for more consistent alignment.
-- Sidebar defaults now use a 280px expanded shell and a 48px collapsed rail, with logical placement and spacing throughout.
-- Button now publishes `success`, `warning`, and `link` as canonical variants across its catalog, documentation, examples, and playground.
-
-### Fixed
-
-- `MenuItem.onSelect` now exposes Radix's `(event: Event) => void` contract without intersecting React's unrelated DOM selection handler, so explicit annotations and prevent-default multi-select flows compile correctly.
-- Sidebar focus, tooltip, collapse, nesting, active-state, narrow-layout, and RTL behavior across both controlled and uncontrolled compositions.
-- Component icon sizing, spacing, and state styling across Alert, Avatar, Button Group, Date Picker, Input, Item, Menu, Pagination, Select, Tag, Toolbar, and expanded compositions.
-- Playground token enforcement now uses explicit Banhaten shadow variables in every Test Lab surface.
-
-### Migration
-
-- To retain the previous blue default, set `data-theme="blue"` on the themed root; roots without `data-theme` now resolve to gray.
-- Review custom Sidebar shells before updating because the canonical expanded and collapsed widths and the recommended header, menu, and footer composition have changed. Run `npx banhaten diff sidebar` before `npx banhaten update sidebar`, and use `--force` only after reviewing local generated-file changes.
-- Button's `destructive` and `soft-destructive` values remain accepted as deprecated compatibility aliases; migrate to `danger` and `soft-danger`, respectively.
-
-## 0.3.0 - 2026-08-21
-
-### Added
-
-- `ActivityHeatmap`, a token-only expanded component with five intensity levels, accessible summary semantics, responsive overflow, inherited RTL behavior, registry metadata, documentation, and an installable example.
-- Public `CardSurface`, semantic table-element exports, and `ProgressSteps` APIs for owned product composition without bypassing Banhaten primitives.
-- An AST-backed component-ownership gate plus route-wide accessibility, inherited-RTL containment, and deterministic visual-regression coverage for every component page.
-
-### Changed
-
-- Expanded components and all 38 audited playground backgrounds now compose Banhaten-owned controls; Alert, Page Header, and Slideout declare their new Button and Breadcrumbs registry dependencies.
-- Direction inheritance, narrow-layout containment, focus behavior, and machine-readable RTL contracts were completed across the 68-component catalog.
-- Elevation and color-mode sources were consolidated around shared semantic effects, and the canonical contrast audit was expanded to 910 passing scenarios.
-- Page Header accepts `headingLevel`; Timeline labels and captions accept React nodes; horizontal timelines are keyboard-scrollable and standalone `TimelineItem` semantics are now caller-controlled.
-
-### Fixed
-
-- ARIA ownership, naming, focus, landmark, and relationship defects across Date Picker, Select, Command, Tabs, Field, Table, Menu, Carousel, Sidebar, Slideout, Timeline, and composed documentation examples.
-- Contrast failures across component states and themes, including focus indicators, selected states, badges, tags, alerts, banners, toggles, social buttons, and tables.
-- Inherited-RTL and 324px containment defects in activity, navigation, form, data-display, and expanded layout components.
-
-### Migration
-
-- `SidebarInset` now renders a neutral `div` instead of an implicit `main`. When the inset is the page landmark, render your own `<main>` through `<SidebarInset asChild><main>...</main></SidebarInset>`.
-- `Slideout` is an explicitly named presentational region. Use `Sheet` or `Modal` when the experience requires a portal, overlay, focus trap, Escape dismissal, and focus return.
-- A standalone `TimelineItem` no longer assumes `role="listitem"`; use it inside `Timeline` or pass an explicit role when composing your own list.
-- Run `npx banhaten diff` before `npx banhaten update`, then review locally customized generated files before using `--force`.
-
-## 0.2.0 - 2026-08-08
-
-### Added
-
-- Canonical JSON-driven token generation and strict component token enforcement.
-- Color Contrast documentation covering every audited theme, mode, foreground, and background scenario.
-- Item and Toggle Group primitives, inherited direction context, Arabic font installation, and named categorical chart tokens.
-- Receipt-backed CLI drift protection, unified diffs, and isolated compilation for every registry component.
-- Documentation search, token search/copy, stable component and pattern separation, and dedicated lab navigation.
-- `SegmentedControl` and `KbdShortcut` primitives with accessibility, RTL, registry metadata, examples, and tests.
-- Semantic `compact`, `default`, and `comfortable` density across Button, Input, Select, DatePicker, ButtonGroup, SegmentedControl, and Toolbar controls.
-- Canonical collection-filter, results-toolbar, and control-density recipes with accessibility and visual-regression coverage.
-- Install-time coding-agent guidance, a read-only `banhaten doctor` adoption audit, and recurring-gap promotion reporting.
-
-### Changed
-
-- Production components no longer invent demo content, fake actions, or fixed sample dates.
-- Input and Select no longer invent optional leading, information, or trailing icons when those props are omitted; explicit flags retain the previous built-in adornments.
-- Registry component metadata now publishes machine-readable prop types, rendered defaults, and descriptions for optional visual slots.
-- Registry component token metadata is generated from source references.
-- Pagination, OTP, Carousel, Alert, and Toast direction behavior now resolves from explicit props, provider context, or the nearest document boundary.
-- The default appearance keeps blue brand roles but now composes all neutral surfaces, borders, content, and interaction roles from the reviewed gray ramp in light and dark modes.
-- Registry metadata now declares capability defaults, recommended uses, avoid guidance, recipes, and deprecated props instead of inferring defaults from array order.
-- Toolbar controls default to the shared 36px density; use `density="comfortable"` for the previous 40px toolbar height.
-
-### Fixed
-
-- Undefined token references, raw component values, inaccessible progress semantics, no-op controls, and the Arabic Pagination “Previous” label.
-- Documentation section anchors, narrow Input preview overflow, Popover arrow sizing, Slideout icon geometry, and playground bundle chunking.
-- High-severity playground advisories in Nano ID, PostCSS, and Undici through patched lockfile versions.
-
-### Migration
-
-- Prefer `density` over legacy component-specific sizes when controls share a row. Legacy size props continue to work.
-- Replace Input `hasLeadingIcon` and `hasInformationIcon` with explicit `leadingIcon`/`trailingIcon`, or use `showAtSign`/`showInfo` for those exact affordances. The legacy flags remain supported for this deprecation window.
-- Replace single-glyph Input shortcuts with `shortcutKeys={["Mod", "K"]}` or `KbdShortcut` for platform-aware keycaps.
-- Run `npx banhaten init` to install `.banhaten/USAGE.md`, then run `npx banhaten doctor` and `npx banhaten diff` before updating consumer components.
-
-## 0.1.3
-
-- Pre-launch registry and documentation baseline.
+# Changelog
+
+All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
+
+## Unreleased
+
+## 0.6.0 - 2026-10-28
+
+### Added
+
+- Sidebar `size="comfortable"` on `SidebarProvider` for application shells with 40px navigation rows. While expanded it uses 40px rows 8px apart, body-md labels, 16px shell padding, a 24px section gap, a heading-md brand, and 20px group labels. The collapsed rail and the default size are unchanged.
+- `SidebarHeaderBrand` accepts `subtitle` for a stacked module line and `logo={false}` for a text-only brand.
+- `SidebarFooterUser variant="card"` renders the signed-in user as an inset tinted block. Every footer variant accepts `avatar={false}` and `trailingIcon={false}`, and `SidebarFooter divider={false}` drops the top rule.
+- Sidebar tokens `--bh-sidebar-group-label-content`, `--bh-sidebar-user-card-bg`, `--bh-sidebar-user-card-bg-hover`, and seven `--bh-sidebar-comfortable-*` dimensions.
+- `AppHeader`, the workspace bar above page content in a sidebar shell, with `AppHeaderStart`, `AppHeaderEnd`, `AppHeaderSearch`, and `AppHeaderAction`. The bar is 72px with 24px padding and gaps. Actions are flush with their 24px icon or label at rest and keep a 40px pointer target; `size="sm"` text actions reserve 32px for a language code.
+- Breadcrumbs `size="sm"` for a 14/20 trail with a 12px separator, and the `--bh-breadcrumbs-current-content` token for the current item color. App Header sets it to its subtle location color.
+- Table `size="comfortable"` follows Table item 1.2: 44px headers in body-sm medium on the table-header fill, 64px rows with 8px cells and body-md text, no row dividers, and a 12px radius. `sm` and `lg` are unchanged.
+- The owned table elements take the same spec through `TableRoot size="comfortable"`, and the new `TableContainer` frames them with a 12px radius and a border drawn inside the edge. Without a size they stay unstyled.
+- Line + subline table cells from Table item 1.2 (`hasCaption`): `text`, `brandLogoText`, `payment`, and `image` items accept `caption`, as `avatarText` already did. The caption is body-2xs in `content/subtle` directly under the label, so the pair fills 40px of a 56px `lg` row. DataTable search also matches captions.
+- `TableCellText` gives owned `TableCell`s the same line + subline content, with `caption`, a `leading` icon or avatar 6px before the text, and `tone` and `weight` for the label. Long labels and captions end in an ellipsis inside the cell. Table tokens `--bh-table-caption-content` and `--bh-table-cell-text-gap`.
+- `TableCellLink`, a flush text action for a cell label that opens a record. It keeps the cell text style, underlines on hover and focus, and draws its focus ring outside the clipped text. It renders a button, or its child with `asChild`. Table now lists `@radix-ui/react-slot` as a direct dependency.
+
+- PageHeader `size="comfortable"` for the page heading inside an app shell whose header carries the breadcrumbs.
+  - No block padding; 8px between title and description, 24px between copy and actions, 12px between actions.
+  - 40px action Buttons with a 160px minimum width (176px for primary Buttons), and no icon or tabs unless passed.
+  - New tokens `--bh-page-header-comfortable-action-min-width` and `--bh-page-header-comfortable-primary-action-min-width`.
+  - `actions` also accepts your own nodes, `description` accepts inline content, and `children` add supporting content, such as a status badge, under the description.
+- Button renders `data-variant` with its variant (`default` for primary), so containers can style actions by variant.
+- Tabs `size="comfortable"` for view navigation in an app page: underline tabs 48px tall and 8px apart, the active indicator drawn inside the tab, and no divider under the row. Segment and rounded tabs render it like `md`.
+- Card and CardSurface `size="comfortable"` for panels in an app shell: the same surface and 1px inset edge with a 12px radius (`--bh-card-comfortable-radius`) instead of the library card's 16px. Both render `data-size`.
+- Alert `icon` replaces the status icon, and `descriptionColor="default"` sets the description in `content/default`, as the ATS360 frames do.
+- Menu `MenuRadioGroup` and `MenuRadioItem` for menus that set one value, such as a display time zone: items are `menuitemradio` with `aria-checked`, the chosen one shows a trailing check, and choosing one calls the group's `onValueChange`. They also render in `MenuPreview`.
+
+### Changed
+
+- Attribute `density="comfortable"` is now the app-shell detail row: no row padding, rows 16px apart, a body-sm label in a 176px column (`--bh-attribute-comfortable-label-width`) and 16px before the value, aligned to the top. It rendered like `default` before.
+- Alert descriptions use the status colour from the library (`content/{status}/default`) instead of the strong title colour, and an expandable Alert with a description now uses the expanded layout without actions, as the library allows with Actions Links off. Before, it fell back to the compact layout and hid the description.
+- Input `md` and `lg` text starts 12px from the field edge, as in the library Input frame: 8px content padding plus a 4px value inset, with trailing icons 8px from the edge. It was 10px in `lg` and 8px in `md`. New tokens `--bh-input-content-padding-x` and `--bh-input-value-inset`; `comfortable` is unchanged.
+- Input and Select docs explain the 320px default width, the library frame width, and how to make a field fill its form column.
+- Table `lg` rows use body-md (15/24) text, as the Figma `lg` cells do; `sm` keeps body-sm.
+- Table `avatarText` names, and the labels of `brandLogoText`, `payment`, `image`, and `file` items, use medium weight, as in Figma; `avatarText` names were semibold. The `avatarText` caption moves from `content/default` with a 1px gap to `content/subtle` with no gap.
+- Badge draws its border inside the side padding, as the library's inside stroke does, so a badge is its label plus 8px (12px at `lg`) on each side. Each side padding subtracts the border width (1px, or `--bh-badge-outline-border-width` for `outline`); badges were 2px wider than the library, and outline badges 3px. Heights are unchanged.
+- Sidebar `size="comfortable"` draws the expanded rail's 1px stroke inside on all four sides, an outline inset by its width in `--bh-sidebar-border`, instead of an end border, as the ATS360 shell frames do. It takes no width and stays visible above the header and footer fills; the collapsed rail keeps the end border.
+
+## 0.5.0 - 2026-10-16
+
+### Added
+
+- ECharts-backed `DataChart`, `EChart`, and `ChartBlock` APIs with eight chart families, 18 example blocks, token-driven themes, and interactive legends, tooltips, and brush controls. Existing Recharts wrappers remain supported.
+- AI conversation components built only from Banhaten primitives and tokens: `ThinkingState`, `ThinkingReasoning`, `StreamingText` with a `useTypewriter` hook for local reveals, `InlineCitations` composed from `CitationProse` and `CitationMark`, `TaskList` with `TaskListRoot`, `TaskListHeader`, `TaskListItems`, and `TaskListPreview` parts for static and folded lists, `AgentInput`, and the approval cards (`ApprovalQuestions`, `ApprovalCommand`, `ApprovalPlan`) with the `ApprovalFrame` shell they share for custom decisions, each with registry metadata, documentation, examples, playground pages, and tests.
+- `ShimmerText` for labels of work in progress and `RollingCount` for counts that roll each changed digit into place, general-purpose components the AI conversation components build on, each with registry metadata, documentation, examples, playground pages, and tests.
+- Foundation motion tokens `--bh-duration-moderate`, `--bh-duration-slow`, `--bh-duration-slower`, and `--bh-easing-emphasized`; component tokens for the reasoning block, streaming caret, citation marks, agent input, shimmer text, and task list; and a `--bh-font-family-mono` family for command blocks.
+- Shared hooks installed with the base files: `use-motion-end` runs script work after the CSS motion it waits for instead of after copied timings, `use-controllable-state` backs controlled and uncontrolled props, `use-reduced-motion` follows the user's motion setting, and `use-listbox-navigation` gives Autocomplete and the Agent Input skill palette one keyboard model.
+- `CollapsiblePanel`, an unstyled Collapsible part that animates its height open and closed, and `asChild` support on `CollapsibleTrigger` for components with their own disclosure design.
+- Registry file entries accept `"internal": true`. An internal module installs and compiles with its component, but its exports stay out of the supported import contract, so a large component can be split into modules without publishing them.
+
+### Changed
+
+- Autocomplete moves the active option to the first enabled match when filtering removes the one that was active, instead of leaving no option active.
+- Input quantity steppers now update values using native number-input constraints and change events; button and dropdown compositions expose native action props.
+- Public depth tokens use the `--elevation-*` namespace, with seven numbered steps and semantic component aliases. Token graphs rebind at nested theme boundaries.
+- Sidebar collapse uses staged transitions and dedicated motion tokens.
+
+### Fixed
+
+- CLI writes detect concurrent edits before replacing consumer files.
+- Checked indicators retain contrast in dark themes; label-less Selects receive accessible names; Input exposes required semantics; Toolbar defaults to group semantics.
+- Breadcrumbs, keyboard shortcuts, Page Header, Tabs, and Table improve content direction, overflow handling, and pagination sizing.
+- Packed-artifact validation invokes npm directly through Node on Windows, avoiding the `spawn EINVAL` failure from launching `npm.cmd`.
+- Refreshed dependency resolutions for runtime and playground security fixes; Windows token-security fixtures use directory junctions, and browser tests include the Windows autofill workaround.
+
+### Migration
+
+- Replace `--shadow-xs`, `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl`, and `--shadow-3xl` with `--elevation-01` through `--elevation-07`, respectively. Rename semantic `--shadow-*` references and overrides to their corresponding `--elevation-*` names; the old token names are no longer published.
+- Run `npx banhaten@0.5.0 diff` before `npx banhaten@0.5.0 update`. Review customized component files and token overrides before using `--force`.
+- Updating `chart` adds an `echarts` dependency alongside `recharts`; run the package-manager install command printed by the CLI. Existing Recharts compositions continue to work.
+- Quantity Input now renders a number input with working steppers. Review custom click handlers to avoid applying a second increment, and call `preventDefault()` in a stepper handler when overriding the built-in step.
+
+## 0.4.0 - 2026-08-22
+
+### Added
+
+- A Figma-aligned Sidebar composition with brand and workspace headers, header and group actions, menu badges, nested and tree navigation, user footers, rail tooltips, controlled state, and documented expanded, collapsed, LTR, and RTL variants.
+- `Shortcut`, a compact combined keyboard-chord primitive for inputs and constrained action rows, alongside the existing separated-keycap `KbdShortcut` API.
+- A Test Lab V2 playground with scenario navigation, a focused inspector, state-comparison boards, responsive previews, and browser coverage for the new QA workflow.
+- Noto Sans Arabic as the default Arabic playground font, with the previous Arabic font options retained.
+
+### Changed
+
+- The default brand theme is now monochrome `gray`; `blue` remains available as an explicit alternate theme.
+- Elevation now publishes the complete seven-level Figma scale as `--elevation-01` through `--elevation-07`, with dedicated reviewed light and dark values and updated token documentation.
+- Shared icon and icon-slot geometry is tokenized across controls, navigation, feedback, and data-display components for more consistent alignment.
+- Sidebar defaults now use a 280px expanded shell and a 48px collapsed rail, with logical placement and spacing throughout.
+- Button now publishes `success`, `warning`, and `link` as canonical variants across its catalog, documentation, examples, and playground.
+
+### Fixed
+
+- `MenuItem.onSelect` now exposes Radix's `(event: Event) => void` contract without intersecting React's unrelated DOM selection handler, so explicit annotations and prevent-default multi-select flows compile correctly.
+- Sidebar focus, tooltip, collapse, nesting, active-state, narrow-layout, and RTL behavior across both controlled and uncontrolled compositions.
+- Component icon sizing, spacing, and state styling across Alert, Avatar, Button Group, Date Picker, Input, Item, Menu, Pagination, Select, Tag, Toolbar, and expanded compositions.
+- Playground token enforcement now uses explicit Banhaten shadow variables in every Test Lab surface.
+
+### Migration
+
+- To retain the previous blue default, set `data-theme="blue"` on the themed root; roots without `data-theme` now resolve to gray.
+- Review custom Sidebar shells before updating because the canonical expanded and collapsed widths and the recommended header, menu, and footer composition have changed. Run `npx banhaten diff sidebar` before `npx banhaten update sidebar`, and use `--force` only after reviewing local generated-file changes.
+- Button's `destructive` and `soft-destructive` values remain accepted as deprecated compatibility aliases; migrate to `danger` and `soft-danger`, respectively.
+
+## 0.3.0 - 2026-08-21
+
+### Added
+
+- `ActivityHeatmap`, a token-only expanded component with five intensity levels, accessible summary semantics, responsive overflow, inherited RTL behavior, registry metadata, documentation, and an installable example.
+- Public `CardSurface`, semantic table-element exports, and `ProgressSteps` APIs for owned product composition without bypassing Banhaten primitives.
+- An AST-backed component-ownership gate plus route-wide accessibility, inherited-RTL containment, and deterministic visual-regression coverage for every component page.
+
+### Changed
+
+- Expanded components and all 38 audited playground backgrounds now compose Banhaten-owned controls; Alert, Page Header, and Slideout declare their new Button and Breadcrumbs registry dependencies.
+- Direction inheritance, narrow-layout containment, focus behavior, and machine-readable RTL contracts were completed across the 68-component catalog.
+- Elevation and color-mode sources were consolidated around shared semantic effects, and the canonical contrast audit was expanded to 910 passing scenarios.
+- Page Header accepts `headingLevel`; Timeline labels and captions accept React nodes; horizontal timelines are keyboard-scrollable and standalone `TimelineItem` semantics are now caller-controlled.
+
+### Fixed
+
+- ARIA ownership, naming, focus, landmark, and relationship defects across Date Picker, Select, Command, Tabs, Field, Table, Menu, Carousel, Sidebar, Slideout, Timeline, and composed documentation examples.
+- Contrast failures across component states and themes, including focus indicators, selected states, badges, tags, alerts, banners, toggles, social buttons, and tables.
+- Inherited-RTL and 324px containment defects in activity, navigation, form, data-display, and expanded layout components.
+
+### Migration
+
+- `SidebarInset` now renders a neutral `div` instead of an implicit `main`. When the inset is the page landmark, render your own `<main>` through `<SidebarInset asChild><main>...</main></SidebarInset>`.
+- `Slideout` is an explicitly named presentational region. Use `Sheet` or `Modal` when the experience requires a portal, overlay, focus trap, Escape dismissal, and focus return.
+- A standalone `TimelineItem` no longer assumes `role="listitem"`; use it inside `Timeline` or pass an explicit role when composing your own list.
+- Run `npx banhaten diff` before `npx banhaten update`, then review locally customized generated files before using `--force`.
+
+## 0.2.0 - 2026-08-08
+
+### Added
+
+- Canonical JSON-driven token generation and strict component token enforcement.
+- Color Contrast documentation covering every audited theme, mode, foreground, and background scenario.
+- Item and Toggle Group primitives, inherited direction context, Arabic font installation, and named categorical chart tokens.
+- Receipt-backed CLI drift protection, unified diffs, and isolated compilation for every registry component.
+- Documentation search, token search/copy, stable component and pattern separation, and dedicated lab navigation.
+- `SegmentedControl` and `KbdShortcut` primitives with accessibility, RTL, registry metadata, examples, and tests.
+- Semantic `compact`, `default`, and `comfortable` density across Button, Input, Select, DatePicker, ButtonGroup, SegmentedControl, and Toolbar controls.
+- Canonical collection-filter, results-toolbar, and control-density recipes with accessibility and visual-regression coverage.
+- Install-time coding-agent guidance, a read-only `banhaten doctor` adoption audit, and recurring-gap promotion reporting.
+
+### Changed
+
+- Production components no longer invent demo content, fake actions, or fixed sample dates.
+- Input and Select no longer invent optional leading, information, or trailing icons when those props are omitted; explicit flags retain the previous built-in adornments.
+- Registry component metadata now publishes machine-readable prop types, rendered defaults, and descriptions for optional visual slots.
+- Registry component token metadata is generated from source references.
+- Pagination, OTP, Carousel, Alert, and Toast direction behavior now resolves from explicit props, provider context, or the nearest document boundary.
+- The default appearance keeps blue brand roles but now composes all neutral surfaces, borders, content, and interaction roles from the reviewed gray ramp in light and dark modes.
+- Registry metadata now declares capability defaults, recommended uses, avoid guidance, recipes, and deprecated props instead of inferring defaults from array order.
+- Toolbar controls default to the shared 36px density; use `density="comfortable"` for the previous 40px toolbar height.
+
+### Fixed
+
+- Undefined token references, raw component values, inaccessible progress semantics, no-op controls, and the Arabic Pagination “Previous” label.
+- Documentation section anchors, narrow Input preview overflow, Popover arrow sizing, Slideout icon geometry, and playground bundle chunking.
+- High-severity playground advisories in Nano ID, PostCSS, and Undici through patched lockfile versions.
+
+### Migration
+
+- Prefer `density` over legacy component-specific sizes when controls share a row. Legacy size props continue to work.
+- Replace Input `hasLeadingIcon` and `hasInformationIcon` with explicit `leadingIcon`/`trailingIcon`, or use `showAtSign`/`showInfo` for those exact affordances. The legacy flags remain supported for this deprecation window.
+- Replace single-glyph Input shortcuts with `shortcutKeys={["Mod", "K"]}` or `KbdShortcut` for platform-aware keycaps.
+- Run `npx banhaten init` to install `.banhaten/USAGE.md`, then run `npx banhaten doctor` and `npx banhaten diff` before updating consumer components.
+
+## 0.1.3
+
+- Pre-launch registry and documentation baseline.

package/CONTRIBUTING.md

@@ -1,46 +1,46 @@
-# Contributing to Banhaten
-
-## Local checks
-
-Use Node 18.18 or newer, install the root and playground dependencies, then run:
-
-```bash
-npm run check
-```
-
-The full check validates schemas, CLI behavior, token generation, token-only component styling, registry mirrors, isolated installs, documentation coverage, browser tests, and the production bundle.
-
-## Component rules
-
-- Build component styling from canonical `--bh-*` and `--elevation-*` tokens. Add
-  new values to the component's own fragment under
-  `tokens/source/components/<id>/`, or to a foundation fragment when several
-  components share them, before using them in component source.
-- Keep product copy, sample dates, and product actions in examples rather than production defaults.
-- Preserve inherited direction and use logical CSS properties. Test both LTR and RTL keyboard behavior.
-- Use native semantics or proven accessible primitives, and document the public API, examples, tokens, RTL behavior, and accessibility contract.
-- Keep stable primitives in Components, larger compositions in Patterns, and experiments in Lab. A family built for one product surface, such as AI conversation, may have its own group; the general-purpose primitives it relies on still go in Components.
-- Split a component that nears 1,000 lines into modules by concern. Mark the modules that only serve its public module `"internal": true` in its catalog entry so the split does not publish them.
-
-## Generated artifacts
-
-Edit the owned fragments under `tokens/source/` for structured tokens and
-aliases, and edit `registry/catalog/components/<id>.json` for component registry
-metadata. `tokens/banhaten.tokens.json` and `registry/index.json` are compiled
-publication artifacts. Edit `tokens/banhaten.utilities.css` for authored
-Tailwind mappings, keyframes, global rules, accessibility rules, and typography
-utilities. The generated `registry/styles/globals.css` is rebuilt from the
-compiled token catalog and that authored CSS source.
-
-After token or registry metadata changes, run:
-
-```bash
-npm run tokens:build
-npm run components:tokens:metadata -- --write
-npm run registry:export
-npm run docs:normalize
-```
-
-Do not hand-edit `tokens/banhaten.tokens.json`, `registry/index.json`,
-`registry/styles/globals.css`, `registry.json`, or generated registry contract
-tables.
+# Contributing to Banhaten
+
+## Local checks
+
+Use Node 18.18 or newer, install the root and playground dependencies, then run:
+
+```bash
+npm run check
+```
+
+The full check validates schemas, CLI behavior, token generation, token-only component styling, registry mirrors, isolated installs, documentation coverage, browser tests, and the production bundle.
+
+## Component rules
+
+- Build component styling from canonical `--bh-*` and `--elevation-*` tokens. Add
+  new values to the component's own fragment under
+  `tokens/source/components/<id>/`, or to a foundation fragment when several
+  components share them, before using them in component source.
+- Keep product copy, sample dates, and product actions in examples rather than production defaults.
+- Preserve inherited direction and use logical CSS properties. Test both LTR and RTL keyboard behavior.
+- Use native semantics or proven accessible primitives, and document the public API, examples, tokens, RTL behavior, and accessibility contract.
+- Keep stable primitives in Components, larger compositions in Patterns, and experiments in Lab. A family built for one product surface, such as AI conversation, may have its own group; the general-purpose primitives it relies on still go in Components.
+- Split a component that nears 1,000 lines into modules by concern. Mark the modules that only serve its public module `"internal": true` in its catalog entry so the split does not publish them.
+
+## Generated artifacts
+
+Edit the owned fragments under `tokens/source/` for structured tokens and
+aliases, and edit `registry/catalog/components/<id>.json` for component registry
+metadata. `tokens/banhaten.tokens.json` and `registry/index.json` are compiled
+publication artifacts. Edit `tokens/banhaten.utilities.css` for authored
+Tailwind mappings, keyframes, global rules, accessibility rules, and typography
+utilities. The generated `registry/styles/globals.css` is rebuilt from the
+compiled token catalog and that authored CSS source.
+
+After token or registry metadata changes, run:
+
+```bash
+npm run tokens:build
+npm run components:tokens:metadata -- --write
+npm run registry:export
+npm run docs:normalize
+```
+
+Do not hand-edit `tokens/banhaten.tokens.json`, `registry/index.json`,
+`registry/styles/globals.css`, `registry.json`, or generated registry contract
+tables.