@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/slider.md

@@ -0,0 +1,114 @@
+# Slider
+
+**Status:** stable
+
+Slider over Base UI Slider — pointer + keyboard control, ARIA slider wiring, and range support via multiple thumbs. The default export composes Root + Control + Track + Indicator + Thumb; pass an array value for a range.
+
+**Keywords:** slider, range, value, input
+
+## Usage
+
+Use Slider for bounded numeric choices where approximate adjustment is faster than typing.
+
+### Best practices
+
+- Do: Use visible labels, min/max context, and value output when precision matters.
+- Do: Choose steps that match the real granularity of the setting.
+- Don't: Do not use Slider when users must enter an exact arbitrary number; use NumberField.
+- Don't: Do not use it without showing the value. A slider with no numeric readout makes any precise choice guesswork — pair it with a ScrubField or a NumberField.
+- Don't: Do not resize the thumb's box on hover, focus, or drag. The thumb is a fixed-size hit target wrapping a decorative dot; only the dot scales. A target that grows under the cursor is a target nobody can learn, and WCAG 2.5.8 measures target size at rest. Restyle the dot, not the box.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| SliderRoot | yes | The controlled slider wrapper. |
+| SliderControl | yes | The interactive slider control region. |
+| SliderTrack | yes | The visible value range. |
+| SliderIndicator | no | The filled portion of the track. |
+| SliderThumb | yes | The draggable handle. |
+| SliderValue | no | A readable value display. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SliderRoot | Base UI Slider.Root props | The unstyled Base UI Root for custom composition — owns the value state and forwards value / defaultValue / onValueChange / min / max / step. Drag state surfaces via data-[dragging]. The default Slider export wires all the parts for you. |
+| SliderControl | Base UI Control props + className | The interactive track lane — the positioning context the indicator and thumbs sit in; dims when disabled. |
+| SliderTrack | Base UI Track props + className | The full-range rail beneath the indicator. |
+| SliderIndicator | Base UI Indicator props + className | The filled portion from min (or the lower thumb) to the current value. |
+| SliderThumb | Base UI Thumb props + className | A draggable handle: a fixed-size hit target wrapping a decorative dot. The dot rests small and scales to full size on hover, keyboard focus, and drag; the box never changes, so row metrics and the tap target hold. Range sliders render one per value; pass index for SSR. Interaction state surfaces via data-[dragging]. |
+| SliderValue | Base UI Value props | Formatted value readout for custom compositions (e.g. a live number beside the control). |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number \| number[] | — | Controlled value. An array renders a range slider with one thumb per entry. |
+| defaultValue | number \| number[] | — | Uncontrolled initial value. An array renders a range slider. |
+| onValueChange | (value, eventDetails) => void | — | Fires on every value change. value is a number (or number[] for a range). |
+| min | number | 0 | Minimum allowed value. |
+| max | number | 100 | Maximum allowed value. |
+| step | number | 1 | Granularity the slider steps through. Snaps to multiples. |
+| disabled | boolean | false | Ignore user interaction and dim the control. |
+| orientation | 'horizontal' \| 'vertical' | horizontal | Axis the slider tracks along. A vertical slider has no intrinsic length — give it a height (h-40, or flex-1 in a column). |
+
+## Tokens used
+
+`secondary`, `primary`, `background`, `ring`
+
+## Accessibility
+
+- Base UI provides role=slider, aria-valuemin/max/now, and arrow-key / Page Up-Down / Home-End control.
+- Each thumb is a focusable input[type=range] nested in the thumb element; keyboard focus raises a 2px ring on the thumb via has-[:focus-visible] (a bare focus-visible: on the thumb never fires, since the div itself is not focusable).
+- The thumb's hit area is a fixed 16px box at every state. Only the decorative inner dot resizes — rest 12px, full 16px on hover, keyboard focus, and drag — so the target a pointer or finger must land on never moves or changes size. Keyboard users, who never hover, get the enlarged dot from focus-visible.
+- The rest-to-full transition uses the motion duration/easing tokens, so it collapses to an instant state change under prefers-reduced-motion or MotionProvider off. The size change itself still happens: it reports interaction state, it is not decoration.
+- Range sliders get one thumb per value with minStepsBetweenValues honored.
+- Pass an aria-label (or getAriaLabel on a thumb) so each handle has an accessible name.
+
+## Related
+
+- Components: NumberField, Progress
+
+## Examples
+
+### Single value
+
+```tsx
+import { Slider } from "@sableui/react"
+
+<Slider defaultValue={50} aria-label="Volume" />
+```
+
+### Range
+
+```tsx
+import { Slider } from "@sableui/react"
+
+const [range, setRange] = useState([20, 60])
+<Slider value={range} onValueChange={setRange} aria-label="Price range" />
+```
+
+### Stepped
+
+```tsx
+import { Slider } from "@sableui/react"
+
+<Slider defaultValue={40} min={0} max={100} step={10} />
+```
+
+### Vertical
+
+```tsx
+import { Slider } from "@sableui/react"
+
+<div className="h-40"><Slider orientation="vertical" defaultValue={40} aria-label="Level" /></div>
+```
+
+### Composed with a value readout
+
+```tsx
+import { Field, SliderControl, SliderIndicator, SliderRoot, SliderThumb, SliderTrack, SliderValue } from "@sableui/react"
+
+<Field label="Volume"><SliderRoot defaultValue={40} className="flex items-center gap-3"><SliderControl><SliderTrack><SliderIndicator /><SliderThumb /></SliderTrack></SliderControl><SliderValue className="text-mono-sm" /></SliderRoot></Field>
+```

package/llms/components/spinner.md

@@ -0,0 +1,87 @@
+# Spinner
+
+**Status:** stable
+
+Pure SVG activity indicator. No Base UI, no icon dependency — a role=status ring (faint track + rounded-cap arc) that inherits the current text color. Size with the size prop (sm / md / lg), color with text-*.
+
+**Keywords:** spinner, loading, pending, indeterminate
+
+## Usage
+
+Use Spinner for short indeterminate waits where the user cannot know exact progress.
+
+### Best practices
+
+- Do: Use it in compact panels or places where layout is already stable. In a button, use Button's loading prop rather than placing a Spinner by hand — it disables the button, sets aria-busy and sizes the spinner to the button's icon.
+- Do: Pair it with accessible loading text when the surrounding label is not enough.
+- Don't: Do not use Spinner as the only content for long waits or full page loading.
+- Don't: Do not use it without an accessible name or a nearby status message. A spinning icon is invisible to a screen reader, so the wait is announced as nothing at all.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| label | string | "Loading" | Accessible label announced by screen readers while visible (sets aria-label on the role=status element). |
+| appearance | "ring" \| "dots" | "ring" | ring is the default indicator; dots are three bouncing dots, softer, for chat and inline text. |
+| size | "sm" \| "md" \| "lg" | "md" | One scale for both appearances: ring 14 / 16 / 24px, dots 4 / 6 / 8px. |
+| className | string | — | Color (text-*); the ring's strokes use currentColor, so it follows the text color. Size with the size prop — a size-* class still overrides the ring for an off-scale context (Button sizes its own spinner this way), but is not the way to pick a size. |
+
+## Variants
+
+- **appearance**: ring, dots
+- **size**: sm, md, lg
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `primary-foreground`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — A spinner already signals a wait. Fading it in delays the signal for exactly as long as the user most needs it.
+- **response** · Root · _no motion_ — It is a status indicator, not a control.
+- **transition** · Root · _no motion_ — One state. Whatever replaces it on completion owns that change.
+- **activity** · Root · `motion-spin` — The rotation is the whole component — it is the only thing distinguishing 'working' from 'frozen'. motion-spin rather than Tailwind's animate-spin because the built-in ignores --motion-scale, so the reduced-motion policy cannot freeze it.
+
+## Accessibility
+
+- Wrapped in role=status, a polite live region, with an aria-label (default 'Loading').
+- Color comes from currentColor; pair with a text-* token for adequate contrast.
+- Spins with the motion-spin utility, which follows --motion-scale, so it slows and stops with the motion setting and reduced-motion.
+
+## Related
+
+- Components: Skeleton, Progress
+
+## Examples
+
+### Dots
+
+```tsx
+import { Spinner } from "@sableui/react"
+
+<Spinner appearance="dots" label="Assistant is typing" className="text-muted-foreground" />
+```
+
+### Default
+
+```tsx
+import { Spinner } from "@sableui/react"
+
+<Spinner />
+```
+
+### Sized + tinted
+
+```tsx
+import { Spinner } from "@sableui/react"
+
+<Spinner size="lg" className="text-muted-foreground" />
+```
+
+### Inside a button (Button owns it — use loading)
+
+```tsx
+import { Button } from "@sableui/react"
+
+<Button loading>Collecting</Button>
+```

package/llms/components/status-bar.md

@@ -0,0 +1,91 @@
+# StatusBar
+
+**Status:** stable
+
+The bottom chrome strip of a Workspace: ambient document facts — dimensions, counts, sync state — in the micro type tier.
+
+**Keywords:** status bar, status, footer, chrome, workspace, tool, ambient, counts, document
+
+## Usage
+
+Use StatusBar for the persistent facts about a document that otherwise have nowhere to live: size, counts, selection state, sync or connection status. Everything in it is ambient — it reports, it does not command. Pair it with Workspace's statusBar slot.
+
+### Best practices
+
+- Do: Put document-scoped facts here — dimensions, layer or record counts, saved/sync state — so panels stop competing for that space.
+- Do: Use StatusBarGroup with align="end" for the trailing cluster, and StatusBarSeparator between related facts.
+- Do: Render numeric facts in the UI num tier so a changing value doesn't shift the strip's layout.
+- Don't: Make it the only route to an action. It's ambient chrome at the micro tier — anything essential needs a real control elsewhere too.
+- Don't: Put zoom here. Anchor zoom to the canvas it acts on, which is where every reference tool puts it.
+- Don't: Use it for transient feedback like a save confirmation — that's Toast. A status bar states what is true, not what just happened.
+- Don't: Derive a fact here separately from the surface that shows it, or from something expensive to recompute. The strip re-renders with the document, so read the same value the canvas or panel uses: a status bar that reports max(asset sizes) while the canvas reports something else is a bug types cannot catch, because both are numbers.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| StatusBarGroup | no | A cluster of items; align="end" pins it to the trailing edge. |
+| StatusBarSeparator | no | A decorative dot between related facts; aria-hidden. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| StatusBarGroup | { align?: 'start' \| 'end' } | A cluster of status items; `end` pushes it to the trailing edge. |
+| StatusBarSeparator | ComponentProps<'span'> | A decorative middle dot between facts. aria-hidden, since order conveys grouping. |
+
+## Tokens used
+
+`muted-foreground`, `panel`, `hairline`, `hairline-strong`
+
+## Accessibility
+
+- Renders a <footer>, so the strip is a discoverable region rather than an anonymous row of text.
+- Separators are aria-hidden — a screen reader announcing 'middle dot' between every fact is noise.
+- Micro-tier text is small by design; never put information here that exists nowhere else.
+
+## Related
+
+- Components: Workspace, PanelGroup, InlineStatus, Toast, Banner
+
+## Examples
+
+### Document facts with a trailing cluster
+
+```tsx
+import { StatusBar, StatusBarGroup, StatusBarSeparator } from "@sableui/react"
+
+<StatusBar>
+  <span className="text-ui-num">1024 × 768</span>
+  <StatusBarSeparator />
+  <span>3 layers</span>
+  <StatusBarGroup align="end">
+    <span>Saved</span>
+  </StatusBarGroup>
+</StatusBar>
+```
+
+### With a warning tone
+
+```tsx
+import { StatusBar, StatusBarGroup } from "@sableui/react"
+
+<StatusBar>
+  <span>Offline — edits are queued</span>
+  <StatusBarGroup align="end">
+    <span className="text-tone-warning">2 unsynced</span>
+  </StatusBarGroup>
+</StatusBar>
+```
+
+### In a Workspace
+
+```tsx
+import { PanelGroup, StatusBar, Workspace, WorkspaceCanvas } from "@sableui/react"
+
+<Workspace statusBar={<StatusBar><span>Connected</span></StatusBar>}>
+  <PanelGroup>
+    <WorkspaceCanvas />
+  </PanelGroup>
+</Workspace>
+```

package/llms/components/status-dot.md

@@ -0,0 +1,70 @@
+# StatusDot
+
+**Status:** stable
+
+A small colored status dot. Tone variants encode state via semantic tone tokens; sizes scale the diameter. Decorative (aria-hidden) — pair with text. Optional pulse adds a live ping ring.
+
+**Keywords:** status, dot, presence, health, state, online, live, indicator
+
+## Usage
+
+Use StatusDot as a compact visual state cue next to text, avatars, rows, or labels. It is decorative by design, so pair it with visible text or use `<Badge appearance="plain" dot>` when the label and dot should travel together — that is the labelled status line, not a hand-built row.
+
+### Best practices
+
+- Do: Place StatusDot beside a readable state label, person name, or row title.
+- Do: Use pulse only for live or in-progress states that are actively changing.
+- Don't: Use the dot as the only status indicator; it is aria-hidden and color alone is not enough.
+- Don't: Mix many dot sizes in the same list. Keep row indicators visually consistent.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Dot | yes | The small tone-colored circle. It is decorative and hidden from assistive tech. |
+| Pulse ring | no | Optional motion ring for in-progress or live states. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| tone | "neutral" \| "standard" \| "success" \| "warning" \| "info" \| "edition" \| "collectible" \| "destructive" | "neutral" | Semantic color of the dot. |
+| size | "sm" \| "md" \| "lg" | "md" | Dot diameter. |
+| pulse | boolean | false | Wrap the dot in an animated ping ring to signal a live state. |
+
+## Variants
+
+- **tone**: neutral, standard, success, warning, info, edition, collectible, destructive
+- **size**: sm, md, lg
+
+## Tokens used
+
+`muted-foreground`, `tone-standard`, `success`, `tone-warning`, `tone-info`, `tone-edition`, `tone-collectible`, `destructive`
+
+## Accessibility
+
+- Rendered aria-hidden — purely decorative. Convey status in adjacent text, not color alone.
+- A dot conveys state through colour alone, which fails for colour-blind users and announces as nothing. It must always sit beside text that states the same thing, or carry its own accessible name.
+
+## Related
+
+- Components: Badge, Avatar, InlineStatus
+- Patterns: DashboardPage, ListDetailPage
+
+## Examples
+
+### Tones
+
+```tsx
+import { Row, StatusDot } from "@sableui/react"
+
+<Row gap={2}><StatusDot tone="standard" /><StatusDot tone="info" /><StatusDot tone="warning" /><StatusDot tone="destructive" /></Row>
+```
+
+### With label — use Badge
+
+```tsx
+import { Badge } from "@sableui/react"
+
+<Badge appearance="plain" tone="success" dot pulse>Live</Badge>
+```

package/llms/components/stepper.md

@@ -0,0 +1,125 @@
+# Stepper
+
+**Status:** stable
+
+Where the user is in a multi-step flow — an ordered list of numbered steps, horizontal or vertical, each complete, current, upcoming or in error, with aria-current="step" on the current one. `indicator="dot"` turns it into a timeline of events (an order's delivery) with dots instead of numbers.
+
+**Keywords:** stepper, steps, wizard, multi-step form, checkout steps, onboarding progress, progress steps, timeline
+
+## Usage
+
+Use Stepper above or beside a flow that is split into a known, small number of named steps — checkout, onboarding, an import wizard — so the user can see how far they have come and what is left. It reports position; the flow's own Back and Continue buttons move it.
+
+### Best practices
+
+- Do: Drive it from one number (`current`) and override a single step's `status` only for what a number cannot say — a completed step that now needs attention is `status="error"`.
+- Do: Name steps with a word or two ("Shipping", "Payment"). Go vertical when steps need a description or there are more than five; horizontal titles truncate first.
+- Do: Give completed steps `onSelect` only when going back to edit them actually works, and keep the user's later answers when they do.
+- Don't: Do not use Stepper for a task with unknown length or for a percentage. That is Progress; a stepper promises a fixed set of named stops.
+- Don't: Do not use it as navigation between independent sections. Sections the user can visit in any order are Tabs; a stepper implies each step depends on the one before.
+- Don't: Do not make upcoming steps pressable to skip ahead. A step that looks reachable but is not is worse than one that is plainly locked.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Stepper | yes | The ordered list. Takes `current` and `orientation`, and an aria-label naming the flow. |
+| StepperItem | yes | One step: a numbered disc (a check when complete, a warning mark on error) — or, with `indicator="dot"`, a dot centred on the title's first line — a title, and an optional description. |
+| Connector | no | The line to the next step, filled once this step is complete. Drawn automatically between items. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| StepperItem | { title: ReactNode; description?: ReactNode; status?: StepStatus; onSelect?: () => void } + li props | One step. `status` overrides the derived state; `onSelect` makes the disc and title a button for returning to the step. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| current | number | 0 | Zero-based index of the current step. Earlier steps derive complete, later ones upcoming. |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Horizontal for a short flow across the top of a form; vertical for long flows, narrow columns or steps with descriptions. |
+| indicator | "number" \| "dot" | "number" | `number` for a flow the user moves through; `dot` for a timeline of events (delivery tracking, a document's history) where the position number adds nothing. The dot centres on the title's first line and scales with its type at every density. |
+| statusLabels | Partial<Record<StepStatus, string>> | — | Screen-reader status words appended to each title (Completed, Current step, Not started, Needs attention). Override to localize. |
+| aria-label | string | — | Names the flow ("Checkout progress"). Every Stepper needs one. |
+
+## Variants
+
+- **orientation**: horizontal, vertical
+- **indicator**: number, dot
+- **status**: complete, current, upcoming, error
+
+## Tokens used
+
+`primary`, `primary-foreground`, `background`, `foreground`, `muted-foreground`, `border-strong`, `destructive`, `destructive-foreground`, `ring`
+
+## Motion
+
+- **arrival** · Stepper · _no motion_ — The stepper frames the flow and is on screen before any step is. Animating it in would compete with the step content, which is what changed.
+- **response** · StepperItem · `motion-interactive` — Only steps with onSelect respond, and the eased underline is what tells a returning user that this completed step can be reopened while the upcoming ones cannot.
+- **transition** · Indicator · `motion-interactive` — When the user continues, the disc they leave fills and its connector darkens. Easing the colour makes that read as one step completing rather than the whole bar re-rendering.
+- **activity** · Stepper · _no motion_ — A step is a place, not a process. Saving or validating between steps belongs on the Continue button's loading state; a pulsing disc would suggest the step itself is busy.
+
+## Accessibility
+
+- Renders an ordered list, so assistive tech announces the step count and each step's position.
+- The current step carries aria-current="step"; every title also gets a visually hidden status word (Completed, Not started, Needs attention), so state never depends on colour or the disc glyph.
+- Discs and connectors are aria-hidden — the number is already the list position.
+- Steps with onSelect render as native buttons with a visible focus ring; steps without it are not focusable.
+
+## Related
+
+- Components: Progress, Tabs, Form, Button
+
+## Examples
+
+### Checkout
+
+```tsx
+import { Stepper, StepperItem } from "@sableui/react"
+
+<Stepper current={1} aria-label="Checkout progress">
+	<StepperItem title="Cart" />
+	<StepperItem title="Shipping" />
+	<StepperItem title="Payment" />
+	<StepperItem title="Review" />
+</Stepper>
+```
+
+### Vertical with descriptions
+
+```tsx
+import { Stepper, StepperItem } from "@sableui/react"
+
+<Stepper orientation="vertical" current={2} aria-label="Workspace setup">
+	<StepperItem title="Create account" description="Email verified" />
+	<StepperItem title="Invite team" description="3 people invited" />
+	<StepperItem title="Connect data" description="Choose a source to import from" />
+	<StepperItem title="Launch" />
+</Stepper>
+```
+
+### Delivery timeline (dots)
+
+```tsx
+import { Stepper, StepperItem } from "@sableui/react"
+
+<Stepper orientation="vertical" indicator="dot" current={2} aria-label="Delivery status">
+	<StepperItem title="Order placed" description="Oct 9, 10:14 AM" />
+	<StepperItem title="Printed and packed" description="Oct 10, 4:02 PM" />
+	<StepperItem title="Out for delivery" description="Arriving today by 6 PM" />
+	<StepperItem title="Delivered" />
+</Stepper>
+```
+
+### A completed step with an error
+
+```tsx
+import { Stepper, StepperItem } from "@sableui/react"
+
+<Stepper current={2} aria-label="Checkout progress">
+	<StepperItem title="Cart" onSelect={() => console.log("cart")} />
+	<StepperItem title="Shipping" status="error" description="Address needs a postcode" onSelect={() => console.log("shipping")} />
+	<StepperItem title="Payment" />
+</Stepper>
+```

package/llms/components/streaming-text.md

@@ -0,0 +1,86 @@
+# StreamingText
+
+**Status:** stable
+
+Prose arriving from a live source, a token at a time. Each token resolves out of blur, the trailing edge stays soft while more is coming, and a steady caret marks the write head.
+
+**Keywords:** streaming, stream, tokens, typewriter, generation, assistant, llm, caret, incremental
+
+## Usage
+
+Use StreamingText for text whose final length is unknown while it renders — a model's answer, a live transcript, a log line being written. It is the counterpart to ThinkingOrb and Spinner: those cover the wait BEFORE the first token, this covers the arrival of the tokens themselves.
+
+### Best practices
+
+- Do: Grow `text` and let the component do the rest. It assumes an append-only string and keys units by index, so React mounts only the new spans — re-rendering a longer string animates what was added and leaves what the reader has already read alone.
+- Do: Drop `streaming` to false the moment the source closes. That is what removes the caret and the softened tail, and their disappearance is the only signal the reader gets that the answer is complete.
+- Do: Turn `caret` off when something adjacent already reports the wait — a spinner in the message header, a status row beneath. Two indicators for one wait read as two things happening.
+- Don't: Do not use it for text that is already complete. Staging known text on scroll is TextReveal (a `motion` export, not a component folder), which computes a stagger from the full string; StreamingText cannot, because nothing here knows the length. Using it for static prose animates the whole paragraph on every mount and says 'still generating' about something that finished.
+- Don't: Do not wrap it in an aria-live region. Every token would be announced, which is unusable; the component sets `aria-busy` instead. Announce once when the turn settles, from whatever owns the turn.
+- Don't: Do not pass `split="char"` for paragraph-length text. It is one element per character — thousands of nodes for an answer, each with its own animation — and word-splitting is indistinguishable at prose reading speed. Reserve it for a headline-length string.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Container | yes | The paragraph (or `as` element). Carries `aria-busy` while output is incomplete. |
+| Unit | yes | One word or character. Animates once on mount and never again; the newest one carries the softened tail while streaming. |
+| Caret | no | The write head, shown while streaming. Steady rather than blinking — see `motion-caret`. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| text | string | — | The text received so far. Assumed append-only: the component keys units by index precisely so a grown string mounts only its new spans. |
+| streaming | boolean | false | Whether more is still coming. Drives the caret, the softened trailing edge, and `aria-busy`. |
+| as | ElementType | "p" | Render container element. |
+| split | "word" \| "char" | "word" | Split granularity. `char` is one element per character — short strings only. |
+| caret | boolean | true | Show the caret while streaming. Turn it off when something adjacent already reports the wait. |
+
+## Tokens used
+
+`foreground`
+
+## Motion
+
+- **arrival** · Unit · `motion-stream-in` — Each token resolves out of blur rather than fading. A fade makes every word a separate event; blur reads as the word coming into focus, so a paragraph arrives as one sentence being written instead of a queue of arrivals.
+- **response** · Container · _no motion_ — It is prose, not a control. Selecting and copying it is the only interaction, and both are native.
+- **transition** · Container · _no motion_ — There is no state to move between — streaming to complete is marked by the caret and tail leaving, not by the text changing. Animating the whole paragraph on completion would re-stage text the reader already read.
+- **activity** · Caret · `motion-caret` — The caret is the write head, and it is deliberately STEADY (`data-streaming="true"` suppresses the blink). A blink during arrival puts two rhythms on screen — text advancing at one rate, a caret flashing at another — and the flashing one carries no information the moving text has not already given.
+
+## Accessibility
+
+- The text is real text in the accessibility tree: units are ordinary spans, not aria-hidden fragments, so a screen reader concatenates them into the sentence.
+- `aria-busy` is set on the container while `streaming` is true, marking the output incomplete without announcing each token.
+- The caret is `aria-hidden` — it is a rendering of the write head, and a screen reader has no use for it.
+- Under reduced motion or with MotionProvider off, no unit animates and no tail is softened; text simply appears as it arrives.
+
+## Related
+
+- Components: ThinkingOrb, Message, Bubble
+
+## Examples
+
+### Streaming an answer
+
+```tsx
+import { StreamingText } from "@sableui/react"
+
+<StreamingText text={answer} streaming={pending} />
+```
+
+### Inside a message, with the wait reported elsewhere
+
+```tsx
+import { Message, StreamingText } from "@sableui/react"
+
+<Message role="assistant"><StreamingText text={answer} streaming={pending} caret={false} /></Message>
+```
+
+### A headline resolving character by character
+
+```tsx
+import { StreamingText } from "@sableui/react"
+
+<StreamingText as="h2" split="char" className="text-heading-2" text={headline} streaming={pending} />
+```

package/llms/components/switch.md

@@ -0,0 +1,87 @@
+# Switch
+
+**Status:** stable
+
+Binary on/off toggle for immediate-effect settings. Track fills with the primary tone when checked; the thumb slides on a spring-eased transform (mirrored in RTL).
+
+**Keywords:** switch, toggle setting, on off, form control
+
+## Usage
+
+Use Switch for immediate on/off settings that take effect as a persistent preference or mode.
+
+### Best practices
+
+- Do: Use it for binary settings where the label describes the enabled state.
+- Do: Make the current state obvious through both position and accessible text.
+- Don't: Do not phrase the label as a negative, such as "Don't send read receipts". Turning off a negative is a double negative, and the user has to solve it before they can act.
+- Don't: Do not use Switch for one-time agreement, multi-select choices, or submit-only booleans.
+- Don't: Do not use a Switch whose effect is not immediately visible somewhere. A toggle flipped with no observable consequence gives no confirmation it worked, so the user flips it again to check.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| checked | boolean | — | Controlled on/off state. Pair with onCheckedChange. Omit for an uncontrolled switch. |
+| defaultChecked | boolean | false | Initial state for an uncontrolled switch. |
+| onCheckedChange | (checked: boolean, eventDetails) => void | — | Fired when the switch is toggled. Note: Base UI passes a second eventDetails arg — not the common (checked) => void, so a single-arg handler must widen its signature. |
+| disabled | boolean | false | Dims the control and ignores user interaction. |
+| readOnly | boolean | false | Prevents toggling while keeping the control fully visible. |
+| required | boolean | false | Marks the switch as required when inside a form. |
+| name | string | — | Identifies the field when the enclosing form is submitted. |
+
+## Tokens used
+
+`input`, `primary`, `primary-foreground`, `ring`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — Switches arrive as part of a settings list. Animating each one in turns a form into a title sequence.
+- **response** · Root · `motion-interactive` — The track is small and its hover change is subtle; without the ease the colour shift reads as a rendering glitch rather than a reaction.
+- **transition** · Thumb · `motion-interactive` — The thumb sliding IS the affordance — it shows the control has two ends and which one you are now at. Teleporting the thumb makes on and off two unrelated pictures, and users re-read the label to work out which they are looking at. motion-interactive is the right recipe because it declares `translate`, so the thumb transform and the track colour ease on one timeline instead of two.
+- **activity** · Root · _no motion_ — A switch commits instantly. If the write is slow enough to need a pending state, the surrounding form owns that, not the control.
+
+## Accessibility
+
+- Renders Base UI's Switch with a hidden native <input> — role, ARIA, and keyboard (Space/Enter) toggling come for free.
+- Focus-visible draws a 2px ring in the --ring token.
+- Disabled state sets cursor-not-allowed and 50% opacity; readOnly keeps full contrast but blocks changes.
+- Give it an accessible name: wrap it in <Field label=… orientation="horizontal">, which wires the label for you.
+
+## Related
+
+- Components: Checkbox, Toggle, ThemeSwitcher
+
+## Examples
+
+### Default (uncontrolled)
+
+```tsx
+import { Switch } from "@sableui/react"
+
+<Switch defaultChecked />
+```
+
+### Controlled
+
+```tsx
+import { Switch } from "@sableui/react"
+
+<Switch checked={on} onCheckedChange={setOn} />
+```
+
+### Disabled
+
+```tsx
+import { Switch } from "@sableui/react"
+
+<Switch disabled defaultChecked />
+```
+
+### With a label
+
+```tsx
+import { Field, Switch } from "@sableui/react"
+
+<Field label="Reduce motion" orientation="horizontal"><Switch defaultChecked /></Field>
+```