banhaten 0.4.0 → 0.5.0

package/docs/design-system/components/hover-card.md

@@ -1,50 +1,50 @@
-# Hover Card
-
-Hover Card wraps Radix HoverCard for rich preview content on hover and focus.
-
-## API
-
-```tsx
-<HoverCard>
-  <HoverCardTrigger>Workspace profile</HoverCardTrigger>
-  <HoverCardContent>Preview content</HoverCardContent>
-</HoverCard>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `HoverCard`, `HoverCardTrigger`, `HoverCardPortal` | Radix shell |
-| `HoverCardContent` | tokenized preview surface |
-
-## Token Contract
-
-Hover Card uses Banhaten raised background, popover shadow, radius, spacing, and content tokens.
-
-## RTL
-
-Content inherits direction and uses logical text alignment.
-
-## Accessibility
-
-Radix manages hover/focus timing and content relationships.
-
-## Install
-
-```bash
-npx banhaten add hover-card
-```
-
-## Examples
-
-Primary registry example: `examples/hover-card-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs hover-card` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `textDirection`: Content inherits direction and uses logical text alignment.
-
+# Hover Card
+
+Hover Card wraps Radix HoverCard for rich preview content on hover and focus.
+
+## API
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger>Workspace profile</HoverCardTrigger>
+  <HoverCardContent>Preview content</HoverCardContent>
+</HoverCard>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `HoverCard`, `HoverCardTrigger`, `HoverCardPortal` | Radix shell |
+| `HoverCardContent` | tokenized preview surface |
+
+## Token Contract
+
+Hover Card uses Banhaten raised background, popover shadow, radius, spacing, and content tokens.
+
+## RTL
+
+Content inherits direction and uses logical text alignment.
+
+## Accessibility
+
+Radix manages hover/focus timing and content relationships.
+
+## Install
+
+```bash
+npx banhaten add hover-card
+```
+
+## Examples
+
+Primary registry example: `examples/hover-card-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs hover-card` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `textDirection`: Content inherits direction and uses logical text alignment.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -57,5 +57,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `parts` | `HoverCard`, `HoverCardTrigger`, `HoverCardContent`, `HoverCardPortal` |
 | `registryDependencies` | None |
 | `features` | `hover preview`, `focus preview`, `open delay`, `close delay` |
-| `tokens` | `--bh-bg-raised`, `--bh-content-default`, `--bh-radius-2xl-12`, `--bh-space-18xl-320`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-z-popover`, `--shadow-popover` |
+| `tokens` | `--bh-bg-raised`, `--bh-content-default`, `--bh-radius-2xl-12`, `--bh-space-18xl-320`, `--bh-space-3xl-16`, `--bh-space-md-8`, `--bh-z-popover`, `--elevation-popover` |
 <!-- registry-contract:end -->

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

@@ -1,48 +1,48 @@
-# Icons
-
-Icons is an expanded-tier explorer for reviewing open-source icon packs, semantic mappings, shortlist comparisons, and Iconify catalog options.
-
-## API
-
-```tsx
-<IconExplorer />
-```
-
-| Feature | Notes |
-| --- | --- |
-| Icon pack review | compares candidate open-source packs |
-| Semantic mapping | maps product concepts to icon candidates |
-| Shortlist comparison | supports side-by-side review |
-| Iconify inspection | loads Iconify catalog data at runtime |
-
-## Runtime
-
-The explorer may load `https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js` and query `https://api.iconify.design`.
-
-## Token Contract
-
-The explorer uses expanded-tier CSS plus Banhaten surface, typography, border, spacing, focus, and content tokens. Product components should still use their local icon contracts instead of depending on this explorer.
-
-## RTL
-
-Explorer layout should inherit page direction for navigation, labels, and comparison rows. Icon glyphs themselves should only mirror when they are directional.
-
-## Accessibility
-
-Icon candidates must be reviewed for accessible usage. Decorative icons should be hidden with `aria-hidden`; actionable icon-only controls need clear accessible names.
-
-## Install
-
-```bash
-npx banhaten add icons
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/icons-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs icons` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
+# Icons
+
+Icons is an expanded-tier explorer for reviewing open-source icon packs, semantic mappings, shortlist comparisons, and Iconify catalog options.
+
+## API
+
+```tsx
+<IconExplorer />
+```
+
+| Feature | Notes |
+| --- | --- |
+| Icon pack review | compares candidate open-source packs |
+| Semantic mapping | maps product concepts to icon candidates |
+| Shortlist comparison | supports side-by-side review |
+| Iconify inspection | loads Iconify catalog data at runtime |
+
+## Runtime
+
+The explorer may load `https://code.iconify.design/iconify-icon/3.0.0/iconify-icon.min.js` and query `https://api.iconify.design`.
+
+## Token Contract
+
+The explorer uses expanded-tier CSS plus Banhaten surface, typography, border, spacing, focus, and content tokens. Product components should still use their local icon contracts instead of depending on this explorer.
+
+## RTL
+
+Explorer layout should inherit page direction for navigation, labels, and comparison rows. Icon glyphs themselves should only mirror when they are directional.
+
+## Accessibility
+
+Icon candidates must be reviewed for accessible usage. Decorative icons should be hidden with `aria-hidden`; actionable icon-only controls need clear accessible names.
+
+## Install
+
+```bash
+npx banhaten add icons
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/icons-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs icons` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.

package/docs/design-system/components/inline-citations.md

@@ -0,0 +1,93 @@
+# Inline Citations
+
+`InlineCitations` renders prose with superscript numbered chips that link to their sources and reveal the reference name in a Tooltip on hover, followed by a compact source list showing the number, label, host, and an external-link arrow.
+
+Compose the prose from `CitationProse` paragraphs and place a `CitationMark` wherever a claim needs support. Each mark finds its source by number, so nothing is parsed out of the text: a literal "[1]" stays text, and a mark whose number has no source renders nothing instead of a dead chip. Outside `InlineCitations`, give a mark its own `href` and `label`.
+
+Citation URLs usually come from model output or search results, so only web addresses become links: `http:` and `https:` URLs, relative links included. A source with any other URL, such as `javascript:` or `data:`, gets no chip in the prose and a plain, unlinked row in the source list. This holds on React 18, which still renders `javascript:` links, as well as on React 19.
+
+## API
+
+```tsx
+import {
+  CitationMark,
+  CitationProse,
+  InlineCitations,
+  type CitationSource,
+} from "@/components/ui/inline-citations"
+
+const sources: CitationSource[] = [
+  { host: "arxiv.org", label: "Attention Is All You Need", url: "https://arxiv.org/abs/1706.03762" },
+]
+
+<InlineCitations sources={sources}>
+  <CitationProse>
+    Transformers scale well with data and compute<CitationMark n={1} />.
+  </CitationProse>
+</InlineCitations>
+```
+
+Model output that attaches citations to spans of text maps straight onto marks:
+
+```tsx
+<CitationProse>
+  {segments.map((segment, index) => (
+    <React.Fragment key={index}>
+      {segment.text}
+      {segment.cite ? <CitationMark n={segment.cite} /> : null}
+    </React.Fragment>
+  ))}
+</CitationProse>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `React.ReactNode` | – | Cited prose: `CitationProse` paragraphs with `CitationMark` markers. |
+| `sources` | `readonly CitationSource[]` | – | `label`, `url`, optional `host`, and optional `n` (defaults to position). Only `http:` and `https:` URLs link. |
+| `showSources` | `boolean` | `true` | Renders the source list under the prose whenever there are sources to list. |
+| `labels` | `Partial<InlineCitationsLabels>` | English | `citation(n, label)` accessible name and the `sources` list name. |
+
+`CitationMark` takes the marker number `n`; its optional `href` and `label` override the matching source. `CitationList` and `CitationItem` render the reference list on their own.
+
+## Install
+
+```bash
+npx banhaten add inline-citations
+```
+
+## Examples
+
+Primary registry example: `examples/inline-citations-demo.tsx`.
+
+## Token Contract
+
+Chips are `--bh-citation-mark-size` squares (aliasing `--bh-space-2xl-14`) with `--bh-radius-sm-4`, `--bh-interactive-soft-default` fill, `--bh-content-subtle` text on the `body-3xs-semibold` scale, and `--bh-interactive-soft-hover` on hover. The list separates with `--bh-border-subtle`, uses the `body-2xs` scale, and reveals a `--bh-space-lg-10` arrow. Tooltips reuse the Tooltip primitive tokens.
+
+Covered source files: `components/inline-citations.tsx`, `components/inline-citations.css`, and the `tooltip` registry dependency.
+
+## RTL Rules
+
+- Prose and list rows inherit document direction and use logical margins and gaps.
+- Hosts stay LTR; the external arrow mirrors horizontally in RTL.
+
+## Accessibility
+
+Every chip is a link with an accessible name that includes the number and the reference label, opening in a new tab with `rel="noreferrer"`. The source list is a `nav` landmark named by `labels.sources`. Hover-only affordances (tooltip, arrow) also appear on keyboard focus.
+
+<!-- registry-contract:start -->
+## Registry Contract
+
+This table is generated from `registry/index.json`; edit the component-owned source under `registry/catalog/components/`, not this table or the compiled index.
+`supportedExports` is the exhaustive runtime import contract grouped by source module. `parts` is an ordered, non-exhaustive anatomy list.
+
+| Field | Values |
+| --- | --- |
+| `supportedExports` | `components/inline-citations.tsx: CitationItem, CitationList, CitationMark, CitationProse, InlineCitations` |
+| `parts` | `InlineCitations`, `CitationProse`, `CitationMark`, `CitationList`, `CitationItem` |
+| `registryDependencies` | `tooltip` |
+| `props.children` | `React.ReactNode; default null; Cited prose: CitationProse paragraphs with CitationMark markers that find their source by number.` |
+| `props.sources` | `readonly CitationSource[]; default null; Cited sources with label, url, optional host, and optional marker number. Only http and https URLs become links.` |
+| `props.showSources` | `boolean; default "true"; Renders the compact source list under the prose when there are sources.` |
+| `props.labels` | `Partial<InlineCitationsLabels>; default "English"; Localized accessible names for markers and the source list.` |
+| `tokens` | `--bh-border-subtle`, `--bh-border-width-default`, `--bh-citation-mark-size`, `--bh-content-default`, `--bh-content-subtle`, `--bh-duration-default`, `--bh-duration-fast`, `--bh-easing-standard`, `--bh-font-family`, `--bh-icon-stroke-180`, `--bh-interactive-soft-default`, `--bh-interactive-soft-hover`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-sm-4`, `--bh-space-lg-10`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xxs-2`, `--bh-space-xxxs-1`, `--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-semibold-font-size`, `--bh-text-body-3xs-semibold-font-weight`, `--bh-text-body-3xs-semibold-letter-spacing`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-font-weight`, `--bh-text-body-sm-regular-letter-spacing`, `--bh-text-body-sm-regular-line-height`, `--elevation-component-focus-ring` |
+<!-- registry-contract:end -->

package/docs/design-system/components/input-group.md

@@ -1,60 +1,60 @@
-# Input Group
-
-Input Group provides a tokenized shell for text inputs with protocol add-ons, prefixes, suffixes, and inline actions.
-
-## API
-
-```tsx
-<InputGroup>
-  <InputGroupAddon>https://</InputGroupAddon>
-  <InputGroupInput aria-label="Workspace URL" />
-  <InputGroupButton>Save</InputGroupButton>
-</InputGroup>
-```
-
-| Part | Purpose |
-| --- | --- |
-| `InputGroup` | shared input shell |
-| `InputGroupAddon` | prefix or suffix content |
-| `InputGroupInput` | native input |
-| `InputGroupButton` | inline action |
-
-| Prop | Values |
-| --- | --- |
-| `size` | `md`, `lg` |
-| `variant` | `default`, `soft` |
-| `state` | `default`, `error` |
-
-## Token Contract
-
-Input Group reuses Banhaten input width, height, radius, border, shadow, typography, and focus tokens.
-
-## RTL
-
-Use logical add-on order. Border placement uses logical inline sides.
-
-## Accessibility
-
-Give `InputGroupInput` an accessible label through `aria-label`, `aria-labelledby`, or a surrounding Field.
-
-## Install
-
-```bash
-npx banhaten add input-group
-```
-
-## Examples
-
-Primary registry example: `examples/input-group-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs input-group` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `spacing`: Add-ons and input segments use logical borders and inherited direction.
-- `textDirection`: Input text uses text-start so mixed Arabic and English values align naturally.
-
+# Input Group
+
+Input Group provides a tokenized shell for text inputs with protocol add-ons, prefixes, suffixes, and inline actions.
+
+## API
+
+```tsx
+<InputGroup>
+  <InputGroupAddon>https://</InputGroupAddon>
+  <InputGroupInput aria-label="Workspace URL" />
+  <InputGroupButton>Save</InputGroupButton>
+</InputGroup>
+```
+
+| Part | Purpose |
+| --- | --- |
+| `InputGroup` | shared input shell |
+| `InputGroupAddon` | prefix or suffix content |
+| `InputGroupInput` | native input |
+| `InputGroupButton` | inline action |
+
+| Prop | Values |
+| --- | --- |
+| `size` | `md`, `lg` |
+| `variant` | `default`, `soft` |
+| `state` | `default`, `error` |
+
+## Token Contract
+
+Input Group reuses Banhaten input width, height, radius, border, shadow, typography, and focus tokens.
+
+## RTL
+
+Use logical add-on order. Border placement uses logical inline sides.
+
+## Accessibility
+
+Give `InputGroupInput` an accessible label through `aria-label`, `aria-labelledby`, or a surrounding Field.
+
+## Install
+
+```bash
+npx banhaten add input-group
+```
+
+## Examples
+
+Primary registry example: `examples/input-group-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input-group` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `spacing`: Add-ons and input segments use logical borders and inherited direction.
+- `textDirection`: Input text uses text-start so mixed Arabic and English values align naturally.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -68,6 +68,6 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `registryDependencies` | `button` |
 | `sizes` | `md`, `lg` |
 | `states` | `default`, `error` |
-| `tokens` | `--bh-border-danger-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-input-border`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--shadow-component-default`, `--shadow-input`, `--shadow-input-focus-ring` |
+| `tokens` | `--bh-border-danger-strong`, `--bh-border-disabled`, `--bh-border-input`, `--bh-border-width-default`, `--bh-content-default`, `--bh-content-disabled`, `--bh-content-muted`, `--bh-content-subtle`, `--bh-input-border`, `--bh-input-lg-height`, `--bh-input-lg-padding-x`, `--bh-input-md-height`, `--bh-input-radius`, `--bh-input-width`, `--bh-interactive-input-default`, `--bh-interactive-input-disabled`, `--bh-interactive-input-soft`, `--bh-space-sm-6`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-text-body-md-regular-font-size`, `--bh-text-body-md-regular-font-weight`, `--bh-text-body-md-regular-letter-spacing`, `--bh-text-body-md-regular-line-height`, `--bh-text-body-sm-medium-font-size`, `--bh-text-body-sm-medium-font-weight`, `--bh-text-body-sm-medium-letter-spacing`, `--bh-text-body-sm-medium-line-height`, `--elevation-component-default`, `--elevation-input`, `--elevation-input-focus-ring` |
 | `variants` | `default`, `soft` |
 <!-- registry-contract:end -->

package/docs/design-system/components/input-otp.md

@@ -1,59 +1,59 @@
-# Input OTP
-
-Input OTP captures one-time passcodes and short verification codes. It reuses the Banhaten Input surface and typography while adding grouped slots, paste distribution, hidden form value, masking, custom length, and RTL-aware keyboard navigation.
-
-## API
-
-```tsx
-<InputOTP
-  label="Verification code"
-  length={6}
-  name="code"
-  onValueChange={setCode}
-/>
-```
-
-| Prop | Values |
-| --- | --- |
-| `value`, `defaultValue` | controlled or uncontrolled string |
-| `length` | slot count |
-| `groupPattern` | array of slot group sizes |
-| `masked` | `boolean` |
-| `variant` | `default`, `soft` |
-| `size` | `md`, `lg` |
-| `state` | `default`, `filled`, `error`, `disabled` |
-
-## Token Contract
-
-Input OTP uses Input field tokens for surfaces, typography, focus, border, error, helper text, labels, slot gaps, and disabled states.
-
-## RTL
-
-Slot groups inherit direction. Arrow navigation mirrors in RTL so visual previous and next follow the rendered direction.
-
-## Accessibility
-
-Provide a clear label and helper text describing how many digits are expected. The hidden form value lets the component participate in standard form submission.
-
-## Install
-
-```bash
-npx banhaten add input-otp
-```
-
-## Examples
-
-Primary registry example: `examples/input-otp-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs input-otp` to inspect source files, install command, and examples.
-
-## RTL Rules
-
-- `inheritsDirection`: true
-- `keyboard`: Arrow navigation mirrors for RTL: visual previous and next follow the inherited direction.
-- `spacing`: Slot groups, separators, labels, and helper text use inherited direction plus Input spacing tokens.
-- `composition`: Each slot reuses the Banhaten Input surface and control typography instead of a separate field style.
-
+# Input OTP
+
+Input OTP captures one-time passcodes and short verification codes. It reuses the Banhaten Input surface and typography while adding grouped slots, paste distribution, hidden form value, masking, custom length, and RTL-aware keyboard navigation.
+
+## API
+
+```tsx
+<InputOTP
+  label="Verification code"
+  length={6}
+  name="code"
+  onValueChange={setCode}
+/>
+```
+
+| Prop | Values |
+| --- | --- |
+| `value`, `defaultValue` | controlled or uncontrolled string |
+| `length` | slot count |
+| `groupPattern` | array of slot group sizes |
+| `masked` | `boolean` |
+| `variant` | `default`, `soft` |
+| `size` | `md`, `lg` |
+| `state` | `default`, `filled`, `error`, `disabled` |
+
+## Token Contract
+
+Input OTP uses Input field tokens for surfaces, typography, focus, border, error, helper text, labels, slot gaps, and disabled states.
+
+## RTL
+
+Slot groups inherit direction. Arrow navigation mirrors in RTL so visual previous and next follow the rendered direction.
+
+## Accessibility
+
+Provide a clear label and helper text describing how many digits are expected. The hidden form value lets the component participate in standard form submission.
+
+## Install
+
+```bash
+npx banhaten add input-otp
+```
+
+## Examples
+
+Primary registry example: `examples/input-otp-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs input-otp` to inspect source files, install command, and examples.
+
+## RTL Rules
+
+- `inheritsDirection`: true
+- `keyboard`: Arrow navigation mirrors for RTL: visual previous and next follow the inherited direction.
+- `spacing`: Slot groups, separators, labels, and helper text use inherited direction plus Input spacing tokens.
+- `composition`: Each slot reuses the Banhaten Input surface and control typography instead of a separate field style.
+
 <!-- registry-contract:start -->
 ## Registry Contract