banhaten 0.3.0 → 0.5.0

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

@@ -1,67 +1,67 @@
-# Steps
-
-Steps show progress through a sequential task. The implementation follows the Figma nodes `HorizontalSteps` (`570:2780`), `VerticalSteps` (`567:76719`), `VerticalStepItem` (`567:5342`), and `HorizontalStepItem` (`569:78346`).
-
-## API
-
-```tsx
-<Steps
-  direction="horizontal"
-  indicator="icon"
-  dir="ltr"
-  items={[
-    { label: "Label", caption: "Caption", supportText: "Support" },
-    { label: "Label", caption: "Caption", supportText: "Support" },
-  ]}
-/>
-```
-
-| Prop | Values | Default |
-| --- | --- | --- |
-| `direction` | `horizontal`, `vertical` | `horizontal` |
-| `indicator` | `icon`, `number` | `icon` |
-| `alignment` | `leading`, `trailing` | `leading` |
-| `dir` | `ltr`, `rtl` | `ltr` |
-| `items` | `StepItem[]` | six default steps |
-
-## Pixel Rules
-
-- Step markers are `28px` circles using `--bg-inverse` with white icon or semibold number text.
-- Connector lines are `1px` using `--border-default`.
-- Horizontal items are `240px` wide in standalone mode and flex equally inside `HorizontalSteps`.
-- Horizontal item content uses `15px / 24px` medium labels and `14px / 20px` captions.
-- Vertical items are `400px` wide with a `24px` gap between marker rail and content.
-- Vertical item labels use `17px / 28px`; support text and captions use `15px / 24px`.
-- Vertical slot content is `76px` tall with the purple subtle background and dashed purple border.
-- Action buttons are `36px` tall with the design-system primary and secondary treatment.
-- RTL mirrors marker placement, text alignment, support text order, and horizontal connector direction.
-
-## Install
-
-```bash
-npx banhaten add steps
-```
-
-## Examples
-
-Primary registry example: `examples/expanded/steps-demo.tsx`.
-
-Open the live component page or run `npx banhaten docs steps` to inspect source files, install command, and examples.
-
-## Token Contract
-
-Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
-Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
-Covered source files: `components/expanded/steps.css`, `components/expanded/Steps.tsx`.
-
-## RTL Rules
-
-This component has no special RTL contract beyond inherited document direction and logical spacing.
-
-## Accessibility
-
-Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
-
+# Steps
+
+Steps show progress through a sequential task. The implementation follows the Figma nodes `HorizontalSteps` (`570:2780`), `VerticalSteps` (`567:76719`), `VerticalStepItem` (`567:5342`), and `HorizontalStepItem` (`569:78346`).
+
+## API
+
+```tsx
+<Steps
+  direction="horizontal"
+  indicator="icon"
+  dir="ltr"
+  items={[
+    { label: "Label", caption: "Caption", supportText: "Support" },
+    { label: "Label", caption: "Caption", supportText: "Support" },
+  ]}
+/>
+```
+
+| Prop | Values | Default |
+| --- | --- | --- |
+| `direction` | `horizontal`, `vertical` | `horizontal` |
+| `indicator` | `icon`, `number` | `icon` |
+| `alignment` | `leading`, `trailing` | `leading` |
+| `dir` | `ltr`, `rtl` | `ltr` |
+| `items` | `StepItem[]` | six default steps |
+
+## Pixel Rules
+
+- Step markers are `28px` circles using `--bg-inverse` with white icon or semibold number text.
+- Connector lines are `1px` using `--border-default`.
+- Horizontal items are `240px` wide in standalone mode and flex equally inside `HorizontalSteps`.
+- Horizontal item content uses `15px / 24px` medium labels and `14px / 20px` captions.
+- Vertical items are `400px` wide with a `24px` gap between marker rail and content.
+- Vertical item labels use `17px / 28px`; support text and captions use `15px / 24px`.
+- Vertical slot content is `76px` tall with the purple subtle background and dashed purple border.
+- Action buttons are `36px` tall with the design-system primary and secondary treatment.
+- RTL mirrors marker placement, text alignment, support text order, and horizontal connector direction.
+
+## Install
+
+```bash
+npx banhaten add steps
+```
+
+## Examples
+
+Primary registry example: `examples/expanded/steps-demo.tsx`.
+
+Open the live component page or run `npx banhaten docs steps` to inspect source files, install command, and examples.
+
+## Token Contract
+
+Component styles must resolve through Banhaten semantic tokens, component aliases, or documented exception-ledger values.
+Do not add raw colors, pixel values, opacity utilities, z-index values, durations, or shadow literals directly to component source.
+Covered source files: `components/expanded/steps.css`, `components/expanded/Steps.tsx`.
+
+## RTL Rules
+
+This component has no special RTL contract beyond inherited document direction and logical spacing.
+
+## Accessibility
+
+Keep native semantics, accessible names, keyboard reachability, focus-visible treatment, and status/error announcements intact when composing this component.
+
 <!-- registry-contract:start -->
 ## Registry Contract
 
@@ -78,5 +78,5 @@ This table is generated from `registry/index.json`; edit the component-owned sou
 | `states` | `complete`, `active`, `todo` |
 | `tokens` | `--bh-bg-accent-purple-subtle`, `--bh-bg-inverse`, `--bh-border-accent-purple-strong`, `--bh-border-default`, `--bh-content-default`, `--bh-content-inverse`, `--bh-content-on-brand`, `--bh-content-subtle`, `--bh-control-default`, `--bh-font-family`, `--bh-font-weight-medium`, `--bh-font-weight-regular`, `--bh-font-weight-semibold`, `--bh-icon-stroke-300`, `--bh-interactive-brand-default`, `--bh-interactive-secondary-default`, `--bh-radius-full`, `--bh-radius-sm-4`, `--bh-space-3xl-16`, `--bh-space-5xl-24`, `--bh-space-9xl-64`, `--bh-space-md-8`, `--bh-space-xl-12`, `--bh-space-xs-4`, `--bh-space-xxxs-1`, `--bh-steps-horizontal-width`, `--bh-steps-indicator-panel-width`, `--bh-steps-vertical-width`, `--bh-text-base-letter-spacing`, `--bh-text-body-lg-medium-font-size`, `--bh-text-body-lg-medium-line-height`, `--bh-text-body-md-font-size`, `--bh-text-body-md-line-height`, `--bh-text-body-sm-regular-font-size`, `--bh-text-body-sm-regular-line-height`, `--bh-text-body-xs-regular-font-size` |
 | `variants` | `icon`, `number` |
-<!-- registry-contract:end -->
+<!-- registry-contract:end -->
 `ProgressSteps` covers compact bar progress and status-aware marker sequences used in setup and enrollment flows.

package/docs/design-system/components/streaming-text.md

@@ -0,0 +1,82 @@
+# Streaming Text
+
+`StreamingText` shows a response arriving token by token. A slim caret trails the text: solid while `streaming`, then a slow blink once the response is complete.
+
+The component renders only what it is given. When your transport streams tokens, pass the text so far and keep `streaming` on until the response ends. To reveal a finished response locally, run it through `useTypewriter`, which returns the revealed part and whether it is still typing.
+
+## API
+
+```tsx
+import { StreamingText, useTypewriter } from "@/components/ui/streaming-text"
+
+<StreamingText streaming={isStreaming} text={partial} />
+
+const typed = useTypewriter(response)
+<StreamingText streaming={typed.typing} text={typed.text} />
+```
+
+### StreamingText
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `text` | `string` | – | The text that has arrived so far. |
+| `streaming` | `boolean` | `false` | More text is on its way: the caret stays solid and the root sets `aria-busy`. |
+| `caret` | `boolean` | `true` | Shows the caret after the text. |
+| `as` | `"p" \| "div" \| "span"` | `"p"` | Rendered element. The ref is typed as `HTMLElement` for all three. |
+
+### useTypewriter
+
+`useTypewriter(text, options)` returns `{ text, typing }`: the revealed part of `text` and whether more is still to come.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `speed` | `number` | `220` | Characters revealed per second. |
+| `onComplete` | `() => void` | – | Called once each time the reveal reaches the end of a text, including an empty one. |
+
+Text that grows continues from what is already revealed, and different text starts over; the returned text is always a prefix of the current one. To replay a reveal, remount the component that calls the hook, for example with a `key`.
+
+## Install
+
+```bash
+npx banhaten add streaming-text
+```
+
+## Examples
+
+Primary registry example: `examples/streaming-text-demo.tsx`.
+
+## Token Contract
+
+Prose uses the `body-sm-regular` scale in `--bh-content-default`. The caret is `--bh-streaming-text-caret-width` wide (aliasing `--bh-space-xxs-2`), one em tall, rounded with `--bh-radius-full`, offset by `--bh-space-xxs-2`, and blinks on `--bh-streaming-text-caret-duration`.
+
+Covered source files: `components/streaming-text.tsx` and `components/streaming-text.css`.
+
+## RTL Rules
+
+- Text inherits document direction.
+- The caret follows the text through a logical start margin, so it trails Arabic text at its end edge.
+
+## Accessibility
+
+The root exposes `aria-busy` while streaming and `data-state` for styling. The caret is decorative and hidden from assistive technology. Under `prefers-reduced-motion`, `useTypewriter` reveals the whole text at once and the caret does not blink.
+
+<!-- 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/streaming-text.tsx: StreamingText, useTypewriter` |
+| `parts` | `StreamingText` |
+| `registryDependencies` | None |
+| `props.text` | `string; default null; The text that has arrived so far.` |
+| `props.streaming` | `boolean; default "false"; True while more text is on its way; keeps the caret solid and sets aria-busy.` |
+| `props.caret` | `boolean; default "true"; Shows the caret after the visible text.` |
+| `props.as` | `"p" \| "div" \| "span"; default "p"; Rendered element; the ref is an HTMLElement for all three.` |
+| `props.speed` | `number; default "220"; useTypewriter option: characters revealed per second.` |
+| `features` | `caller-driven streaming`, `local typewriter reveal`, `reduced motion`, `RTL` |
+| `states` | `streaming`, `complete` |
+| `tokens` | `--bh-content-default`, `--bh-font-family`, `--bh-opacity-0`, `--bh-opacity-100`, `--bh-radius-full`, `--bh-space-xxs-2`, `--bh-streaming-text-caret-duration`, `--bh-streaming-text-caret-width`, `--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` |
+<!-- registry-contract:end -->