banhaten 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,73 +1,139 @@
-# Changelog
-
-All notable Banhaten changes are recorded here. Releases follow the policy in `docs/design-system/release-policy.md`.
-
-## 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.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,44 +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 `--shadow-*` tokens. Add
-  new values to the appropriate owned fragment under `tokens/source/` 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.
-
-## 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.