@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/table.md

@@ -0,0 +1,112 @@
+# Table
+
+**Status:** stable
+
+Styled native table subcomponents (Table, TableHeader, TableBody, TableFooter, TableRow, TableHead, TableCell, TableCaption). Horizontally scrollable frame, hairline row borders, hover-lift, and selectable rows via data-selected.
+
+**Keywords:** table, data table, rows, columns, grid, caption, header, cell, tabular
+
+## Usage
+
+Use Table for structured data with consistent columns and rows. Use DataTable when the table should be data-driven with sorting or empty state behavior, and use lists or cards when each item has a different shape.
+
+### Best practices
+
+- Do: Use TableCaption and TableHead so the table has a clear purpose and column semantics.
+- Do: Keep cells concise and scannable; compose Badge, StatusDot, Avatar, or Button only when they clarify the row.
+- Do: Use the built-in horizontal frame for overflow instead of squeezing columns until content becomes unreadable.
+- Do: Put a table in a card with `<CardContent flush>`. The first and last columns then take the card's own padding (`--table-edge-px`), so they line up with the CardHeader at any density. Never hand-set `pl-6`/`pr-6` on edge cells.
+- Don't: Use Table for heterogeneous items with no stable columns. Use Card, Entity, or a list composition instead.
+- Don't: Put every possible action in every row. Use one primary row action, a DotsMenu, or row detail navigation.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Caption | no | Accessible summary of what the table contains. |
+| Header | yes | Column labels rendered with TableHead cells. |
+| Body | yes | Rows and cells containing the tabular data. |
+| Footer | no | Optional totals or summary row group. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| TableHeader | ComponentPropsWithRef<"thead"> | The header row group (thead). |
+| TableBody | ComponentPropsWithRef<"tbody"> | The data row group (tbody). |
+| TableFooter | ComponentPropsWithRef<"tfoot"> | Summary row group (tfoot) with a muted fill. |
+| TableRow | ComponentPropsWithRef<"tr"> | A row (tr) — hairline bottom border, hover lift, and a selected state via the data-selected attribute. |
+| TableHead | ComponentPropsWithRef<"th"> | A column header cell (th) in muted label styling. |
+| TableCell | ComponentPropsWithRef<"td"> | A data cell (td). |
+| TableCaption | ComponentPropsWithRef<"caption"> | Accessible description of the table (caption), muted. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| className | string | — | The root renders a horizontally scrollable frame around a native <table>; forwards all native table attributes plus className. Each subcomponent likewise forwards its element's native attributes + className. |
+
+## Tokens used
+
+`border`, `muted`, `muted-foreground`
+
+## Accessibility
+
+- Renders semantic native table elements (thead/tbody/tfoot/th/td/caption) preserving built-in table semantics.
+- Use TableHead (th) for column headers and TableCaption for an accessible description.
+- Mark the active row with the data-selected attribute for a visible selected state.
+
+## Related
+
+- Components: DataTable, Pagination, Badge, StatusDot, Avatar
+- Patterns: DashboardPage, ListDetailPage
+
+## Examples
+
+### Collectors
+
+```tsx
+import { Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+
+<Table>
+	<TableCaption>Recent collectors</TableCaption>
+	<TableHeader>
+		<TableRow>
+			<TableHead>Collector</TableHead>
+			<TableHead>Edition</TableHead>
+			<TableHead>Paid</TableHead>
+		</TableRow>
+	</TableHeader>
+	<TableBody>
+		<TableRow>
+			<TableCell>@nova</TableCell>
+			<TableCell>#012</TableCell>
+			<TableCell>0.5 SOL</TableCell>
+		</TableRow>
+	</TableBody>
+</Table>
+```
+
+### Rich status cells
+
+```tsx
+import { Avatar, Badge, Button, Row, Table, TableBody, TableCaption, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+
+<Table><TableCaption>Deployments</TableCaption><TableHeader><TableRow><TableHead>Name</TableHead><TableHead>Status</TableHead><TableHead>Owner</TableHead><TableHead className="text-end">Actions</TableHead></TableRow></TableHeader><TableBody><TableRow data-selected><TableCell>Catalog API</TableCell><TableCell><Badge appearance="plain" tone="warning" dot pulse>Building</Badge></TableCell><TableCell><Row gap={1}><Avatar fallback="NR" alt="Nova Reed" size="sm" /><span>Nova</span></Row></TableCell><TableCell className="text-end"><Button size="sm" variant="ghost">View</Button></TableCell></TableRow></TableBody></Table>
+```
+
+### Flush in a card
+
+```tsx
+import { Card, CardContent, CardHeader, CardTitle, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+
+<Card><CardHeader><CardTitle>Collectors</CardTitle></CardHeader><CardContent flush><Table><TableHeader><TableRow><TableHead>Collector</TableHead><TableHead>Paid</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>@nova</TableCell><TableCell>0.5 SOL</TableCell></TableRow></TableBody></Table></CardContent></Card>
+```
+
+### Summary footer
+
+```tsx
+import { Table, TableBody, TableCell, TableFooter, TableHead, TableHeader, TableRow } from "@sableui/react"
+
+<Table><TableHeader><TableRow><TableHead>Item</TableHead><TableHead className="text-end">Amount</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>Primary sale</TableCell><TableCell className="text-end">42 SOL</TableCell></TableRow></TableBody><TableFooter><TableRow><TableCell>Total</TableCell><TableCell className="text-end">42 SOL</TableCell></TableRow></TableFooter></Table>
+```

package/llms/components/tabs.md

@@ -0,0 +1,84 @@
+# Tabs
+
+**Status:** stable
+
+Tabs over Base UI Tabs (roving focus, arrow-key nav, ARIA tablist wiring) in two styles: underline (page sections) or pill (compact switchers). Tabs (Root) + TabsList + TabsTrigger + TabsPanel.
+
+**Keywords:** tabs, tablist, panels, segmented content
+
+## Usage
+
+Use Tabs to switch between related panels within the same page context.
+
+### Best practices
+
+- Do: Use tabs when each panel is peer content and users may compare or switch often.
+- Do: Keep tab labels short and make the active tab unmistakable.
+- Do: Use variant="pill" for a short switcher inside a card or toolbar (Preview / Code, List / Grid); keep the default underline for sections of a page.
+- Don't: Do not use Tabs for unrelated pages or primary navigation that needs distinct URLs.
+- Don't: Do not use tabs for sequential steps. Tabs are peer views the user returns to in any order; a process with an order needs a stepper, or the user will skip ahead.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| TabsList | yes | The list of tab triggers. |
+| TabsTrigger | yes | One selectable tab. |
+| TabsPanel | yes | The content associated with a trigger. |
+| TabsContent | no | Compatibility alias for panel content. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| TabsList | Base UI Tabs.List props (activateOnFocus, loopFocus) + variant?: "underline" \| "pill" + className | The tablist row. variant="underline" (default) draws a divider rule beneath the triggers; variant="pill" drops the rule and fills the active trigger. Triggers inherit the variant. |
+| TabsTrigger | Base UI Tabs.Tab props (value, disabled) + className | A single tab button. value pairs it with the panel of the same value. |
+| TabsPanel | Base UI Tabs.Panel props (value, keepMounted) + className | The content shown when the matching trigger is active. |
+| TabsContent | Alias of TabsPanel | Re-export of TabsPanel for consumers that prefer this name. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Tabs (Root) | Base UI Tabs.Root props (value, defaultValue, onValueChange, orientation) | defaultValue: 0 | Controls the active tab. Uncontrolled via defaultValue; controlled via value + onValueChange. |
+
+## Tokens used
+
+`border`, `muted`, `muted-foreground`, `foreground`, `ring`
+
+## Accessibility
+
+- Base UI provides the tablist/tab/tabpanel roles, aria-selected, and roving tabindex.
+- Arrow keys move between tabs; Home/End jump to first/last; panels are linked via aria-controls.
+- Active tab styling reads from the data-active attribute; disabled tabs from data-disabled. Disabled tabs are skipped by arrow-key navigation.
+- Keyboard focus shows a ring on the focused trigger in both variants; the panel remains focusable.
+
+## Related
+
+- Components: Accordion, BottomNav, SideNav
+
+## Examples
+
+### Basic
+
+```tsx
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "@sableui/react"
+
+<Tabs defaultValue="overview"><TabsList><TabsTrigger value="overview">Overview</TabsTrigger><TabsTrigger value="activity">Activity</TabsTrigger></TabsList><TabsPanel value="overview">Overview content</TabsPanel><TabsPanel value="activity">Activity content</TabsPanel></Tabs>
+```
+
+### Pill switcher
+
+```tsx
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "@sableui/react"
+
+<Tabs defaultValue="preview"><TabsList variant="pill"><TabsTrigger value="preview">Preview</TabsTrigger><TabsTrigger value="code">Code</TabsTrigger></TabsList><TabsPanel value="preview">Rendered example</TabsPanel><TabsPanel value="code">Source</TabsPanel></Tabs>
+```
+
+### With a disabled tab
+
+```tsx
+import { Tabs, TabsList, TabsPanel, TabsTrigger } from "@sableui/react"
+
+<Tabs defaultValue="overview"><TabsList><TabsTrigger value="overview">Overview</TabsTrigger><TabsTrigger value="holders" disabled>Holders</TabsTrigger></TabsList><TabsPanel value="overview">Overview content</TabsPanel></Tabs>
+```

package/llms/components/textarea.md

@@ -0,0 +1,88 @@
+# Textarea
+
+**Status:** stable
+
+Styled native multi-line text control. Soft-square, card surface, --ring focus, and an aria-invalid destructive error state.
+
+**Keywords:** textarea, multi line input, form, text
+
+## Usage
+
+Use Textarea for multi-line freeform text entry such as notes, descriptions, or messages.
+
+### Best practices
+
+- Do: Use labels, helper text, and character limits when expectations are specific.
+- Do: Size it to the expected amount of input without making the page feel blocked.
+- Do: Keep a focusable field at 16px or larger on mobile. iOS Safari zooms the whole page when a focused textarea computes under 16px and never zooms back out. Textarea handles this itself — below the sm breakpoint it renders text-body-lg (17px) and returns to text-body-md at sm and up. Build a custom field the same way: a second paired tier under a max-sm: variant, never a hand-set font-size.
+- Don't: Do not override the type with a page tier below 16px (text-body-md, text-body-sm) without a >=16px mobile arm — that reintroduces the iOS focus zoom.
+- Don't: Do not use Textarea for short single-line values; use Input.
+- Don't: Do not leave it at the default height for long-form input. A two-row textarea for a paragraph forces the user to write through a letterbox.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| aria-invalid | boolean | — | When true, swaps the input border to the destructive token to signal a validation error. |
+| disabled | boolean | false | Dims the control to 50% and blocks pointer interaction. |
+| rows | number | — | Native textarea row count. The floor is min-h-20 on the spacing scale, so it moves with density. |
+| autoResize | boolean | false | Grows to fit content via CSS field-sizing: content (no JS). The min-height stays the floor; browsers without field-sizing fall back to the fixed min-height. |
+| ...props | ComponentPropsWithRef<"textarea"> | — | All native textarea attributes (value, placeholder, onChange, name, ref, …). |
+
+## Tokens used
+
+`input`, `card`, `foreground`, `muted-foreground`, `ring`, `destructive`
+
+## Accessibility
+
+- Renders a native <textarea> — label association, keyboard, and screen-reader semantics come for free.
+- Renders through Base UI's Field.Control: inside a Field it picks up the label, description, error and validity wiring from context.
+- Pair with a <label htmlFor> (or aria-label) for an accessible name.
+- Set aria-invalid and reference an error message via aria-describedby to announce validation failures.
+- Focus-visible draws a 2px ring in the --ring token.
+
+## Related
+
+- Components: Input, Form, Label
+
+## Examples
+
+### Default
+
+```tsx
+import { Textarea } from "@sableui/react"
+
+<Textarea placeholder="Write a caption…" />
+```
+
+### With rows
+
+```tsx
+import { Textarea } from "@sableui/react"
+
+<Textarea rows={6} placeholder="Tell the story behind this edition…" />
+```
+
+### Auto-resize
+
+```tsx
+import { Textarea } from "@sableui/react"
+
+<Textarea autoResize placeholder="Grows as you type…" />
+```
+
+### Invalid
+
+```tsx
+import { Textarea } from "@sableui/react"
+
+<Textarea aria-invalid defaultValue="Too long" />
+```
+
+### Disabled
+
+```tsx
+import { Textarea } from "@sableui/react"
+
+<Textarea disabled defaultValue="Captions lock once the edition is minted." />
+```

package/llms/components/theme-selector.md

@@ -0,0 +1,95 @@
+# ThemeSelector
+
+**Status:** stable
+
+A presentational radiogroup for choosing a Sable design theme from theme manifests — swatch-strip cards for a settings page, or compact rows for tool chrome. Pair it with useSableTheme().themeId and setThemeId when the app uses SableThemeProvider.
+
+**Keywords:** theme selector, theme, appearance, skin, design theme, preset
+
+## Usage
+
+Use ThemeSelector wherever a person picks a theme. The default `cards` layout is page-register furniture: a swatch strip, a name, and a caption only where one distinguishes the card (the default theme, or a single-mode theme), at ~144px tall. Use `layout="list"` in tool chrome, a popover, or any docked panel — five cards is the wrong object for a 256px surface, however it is sized. For colour mode (light/dark/system) use ThemeSwitcher, which is a segmented control and belongs in chrome as-is.
+
+### Best practices
+
+- Do: Use layout="list" in a popover, a menu, or a docked panel. Rows sit on the --control-sm ladder and still show each theme's swatch strip, so the choice stays visible rather than described. Rows take `sable-frame-inner`, so host the list in a sable-frame (a Popover, or `sable-frame sable-surface sable-surface-popover sable-frame-popover`) and their corners nest concentrically.
+- Do: Pass mode={useSableTheme().mode} so every preview renders in the colour mode actually in use, rather than in each theme's manifest default.
+- Do: Load each theme's fonts in the host app. Every card carries a type specimen in that theme's own face so people can compare typography as well as color. A theme whose fonts are not loaded falls back to system-ui, and its specimen stops telling the truth.
+- Don't: Add a viewport breakpoint to force a column count — `className="sm:grid-cols-1"` or similar. `sm:` keys off the VIEWPORT, not this component's container, so on a wide screen it does nothing for a narrow parent. The cards grid already reflows on its own width via auto-fit.
+- Don't: Put the cards layout in workspace chrome. It was built for a settings page; in a 256px popover the cards clip their labels to a single character and grow to roughly twice their intended height.
+- Don't: Use ThemeSelector for light / dark / system colour mode. That is ThemeSwitcher — a segmented control. This picks the design theme, which is a different axis entirely, and the two are frequently confused.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | ThemeId | — | The currently selected Sable design theme id. |
+| onValueChange | (themeId: ThemeId) => void | — | Called with the next design theme id when an option is chosen. |
+| themes | readonly ThemeManifest[] | themeManifests | Theme manifests to render. Defaults to Sable's built-in themes. |
+| mode | "light" \| "dark" | — | Preview mode for each card's swatch strip. Pass useSableTheme().mode to match the current color mode; omitted cards use their manifest defaultMode. |
+| label | string | "Design theme" | Accessible label for the radiogroup. |
+| layout | "cards" \| "list" | "cards" | Presentation. "cards" is the page-register picker (~144px per card); "list" is one compact --control-sm row per theme, for chrome and popovers. A presentation variant, not a size — "list" is not "cards, smaller" — which is why it is a prop rather than a density scope. |
+| className | string | — | Merged onto the outer radiogroup grid. |
+
+## Tokens used
+
+`input`, `card`, `border`, `background`, `primary`, `primary-foreground`, `accent`, `muted`, `muted-foreground`, `ring`
+
+## Accessibility
+
+- The container is role="radiogroup" with an aria-label; each card is a role="radio" button with aria-checked reflecting the selected theme.
+- Focus-visible draws a 2px ring on the focused card.
+- The selected card wears the shared selection-card checked ring (the same as RadioCard and CheckboxCard), a muted fill and a check icon, so selection does not rely on colour alone.
+- Presentational only: it does not change the document theme; pass useSableTheme().setThemeId or apply the change in onValueChange.
+
+## Related
+
+- Components: ThemeSwitcher, Popover, RadioCard
+
+## Examples
+
+### With SableThemeProvider
+
+```tsx
+import { ThemeSelector, useSableTheme } from "@sableui/react"
+
+const { themeId, setThemeId, themes, mode } = useSableTheme()
+<ThemeSelector value={themeId} onValueChange={setThemeId} themes={themes} mode={mode} />
+```
+
+### Controlled
+
+```tsx
+import { ThemeSelector, type ThemeId } from "@sableui/react"
+
+const [themeId, setThemeId] = useState<ThemeId>("base")
+<ThemeSelector value={themeId} onValueChange={setThemeId} />
+```
+
+### In chrome — a popover or a docked panel
+
+```tsx
+import { PopoverContent, ThemeSelector, ThemeSwitcher } from "@sableui/react"
+
+// Five 144px cards is the wrong object for a 256px surface. Rows are.
+<PopoverContent align="end" className="w-64 p-3">
+  <ThemeSwitcher value={preference} onValueChange={setPreference} />
+  <ThemeSelector layout="list" value={themeId} onValueChange={setThemeId} mode={mode} />
+</PopoverContent>
+```
+
+### Do not reach for a viewport breakpoint
+
+```tsx
+import { ThemeSelector } from "@sableui/react"
+
+// ✗ `sm:` keys off the VIEWPORT, not this component's container. On a wide
+//   screen it does nothing at all for a narrow parent — and this exact
+//   workaround, once documented here, is how the cards layout ended up in a
+//   256px popover clipping "Default" to "D".
+<ThemeSelector className="sm:grid-cols-1" value={themeId} onValueChange={setThemeId} />
+
+// ✓ The cards grid already reflows on its own width (auto-fit, 9rem tracks).
+//   For a genuinely narrow surface, change the presentation instead.
+<ThemeSelector layout="list" value={themeId} onValueChange={setThemeId} />
+```

package/llms/components/theme-switcher.md

@@ -0,0 +1,71 @@
+# ThemeSwitcher
+
+**Status:** stable
+
+A segmented light / dark / system switch. Presentational: it renders the selected color preference and reports changes via onValueChange; pair it with useSableTheme() when the app uses SableThemeProvider. A radiogroup of three icon buttons (sun / moon / desktop).
+
+**Keywords:** theme switcher, color mode, dark mode, appearance
+
+## Usage
+
+Use ThemeSwitcher for light, dark, and system color mode preference.
+
+### Best practices
+
+- Do: Use it where users expect appearance controls, such as app chrome or settings.
+- Do: Respect persisted system or user preference when initializing the control.
+- Don't: Do not use ThemeSwitcher to choose brand themes or component style presets.
+- Don't: Do not hand-build another segmented capsule for a different choice. ThemeSwitcher wears the shared segmented look (lib/segmented); for any other single-select switch use ToggleGroup appearance="segmented".
+- Don't: Do not omit the `system` option or default to a hardcoded mode. Overriding the OS preference is the single most common accessibility complaint about theme controls.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | "light" \| "dark" \| "system" | — | The currently selected color preference. |
+| onValueChange | (value: ThemeMode) => void | — | Called with the next color preference when an option is chosen. |
+| label | string | "Theme" | Accessible label for the radiogroup. |
+| className | string | — | Merged onto the outer radiogroup container. |
+
+## Tokens used
+
+`border`, `card`, `muted-foreground`, `foreground`, `accent`, `accent-foreground`, `ring`
+
+## Accessibility
+
+- The container is role="radiogroup" with an aria-label; each option is role="radio" with aria-checked reflecting the selected value.
+- Each icon button carries an aria-label (Light / Dark / System) plus a title tooltip, since the visual is icon-only.
+- Focus-visible draws a 2px ring on the focused option; selection styling reads from aria-checked.
+- Presentational only: it does not change the document theme; pass useSableTheme().setPreference or apply the change in onValueChange.
+
+## Related
+
+- Components: ThemeSelector, Switch, Toggle
+
+## Examples
+
+### Controlled
+
+```tsx
+import { ThemeSwitcher, type ThemeMode } from "@sableui/react"
+
+const [theme, setTheme] = useState<ThemeMode>("system")
+<ThemeSwitcher value={theme} onValueChange={setTheme} />
+```
+
+### With SableThemeProvider
+
+```tsx
+import { ThemeSwitcher, useSableTheme } from "@sableui/react"
+
+const { preference, setPreference } = useSableTheme()
+<ThemeSwitcher value={preference} onValueChange={setPreference} />
+```
+
+### Light selected
+
+```tsx
+import { ThemeSwitcher } from "@sableui/react"
+
+<ThemeSwitcher value="light" onValueChange={setTheme} />
+```

package/llms/components/thinking-orb.md

@@ -0,0 +1,91 @@
+# ThinkingOrb
+
+**Status:** stable
+
+Canvas dot-cloud 'agent is thinking' indicator. Three generated modes (orbit / globe / mesh) drawn from pure math — no icon dependency, no animation library. Ink follows currentColor; size steps are separately tuned.
+
+**Keywords:** thinking, orb, agent, ai, chat, loading, streaming, indeterminate, canvas
+
+## Usage
+
+Use ThinkingOrb while an AI agent is working and there is nothing specific to report yet — before the first token streams, or between tool calls. It is a richer, more characterful sibling of Spinner for the one place in a product where the wait is the experience.
+
+### Best practices
+
+- Do: Reserve it for the single active agent state — the composer, the streaming message header, a standalone thinking screen. One orb on screen reads as intent; several read as decoration.
+- Do: Switch mode to say what kind of work is happening: orbit for generic thinking, globe while searching or retrieving, mesh while relating sources or running tools. Pair it with a text status so the phase is legible without decoding the animation.
+- Do: Use size="sm" inline in a message row or composer and size="lg" only when the orb is the main thing on screen. The size steps are separately tuned, not scaled, so the small one stays legible.
+- Don't: Do not put one on every row of a list or in a repeated skeleton. Each orb runs its own animation frame loop painting hundreds of arcs; use Skeleton for content-shaped waits and Spinner inside buttons.
+- Don't: Do not use it for a determinate wait. It carries no sense of how far along anything is — reach for Progress when a percentage exists.
+- Don't: Do not rely on the animation alone to announce the wait. Give the label a short constant phrase (it is the role=status announcement) or place a status message next to it.
+- Don't: Do not pass a label that changes while the orb is up. It is the accessible name of a live region, so every change re-announces the whole thing — feed it a per-token phase and a screen reader interrupts on each delta: "Chromatic drift" → "Chromatic drift · rgb-shift" → "Chromatic drift · rgb-shift → grain", which is unusable. The label names the wait ("Thinking"); the phase belongs in adjacent text, as in the "Inline with a status line" example. If the phase must be announced, announce it once when the turn settles from a separate live region — not per update.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| mode | "orbit" \| "globe" \| "mesh" | "orbit" | Which cloud to draw. orbit = generic working, globe = searching/retrieving (a scan band sweeps pole to pole), mesh = relating things (nodes wire to near neighbours and signals run the edges). |
+| size | "sm" \| "md" \| "lg" | "md" | Rendered box on the spacing scale: sm 5 units (20px at the default spacing; inline in a composer or message row), md 8 (32px; beside a status line), lg 16 (64px; standalone). The box moves with density like the text beside it, and the canvas re-measures it. Each step has its own dot density, dot size and speed. |
+| speed | number | 1 | Multiplier on top of the per-size tuned speed. Below ~0.5 the orb reads as stalled. |
+| paused | boolean | false | Freeze on a representative still frame without unmounting. |
+| label | string | "Thinking" | Accessible label announced by screen readers while visible (sets aria-label on the role=status element). Must stay constant for as long as the orb is mounted — it names the wait, it does not report progress. |
+| className | string | — | Set the ink with a semantic text-* token (the dots are drawn from the element's computed color). The box is sized by the size prop, not by className. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `primary`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — The orb appears when work starts, and the point cloud is already in motion on its first painted frame. There is nothing to stage.
+- **response** · Root · _no motion_ — It reports state; it is not a control. A hover reaction would suggest the wait is something you can click your way out of.
+- **transition** · Root · _no motion_ — Changing `mode` swaps the renderer on the next frame: the cloud is redrawn as the new shape, not morphed into it. The phase change is carried by the status text beside the orb, which is what a reader actually reads; a per-particle morph would be decoration on top of it.
+- **activity** · Root · _custom (outside the recipe layer)_ — The cloud is drawn per frame on a canvas by a single requestAnimationFrame loop — no CSS animation exists to name here. The loop reads the motion policy itself, which is the part worth checking when auditing: `custom` means the kill-switch is honoured in JS rather than by --motion-scale.
+
+## Accessibility
+
+- Wrapped in role=status, a polite live region, with an aria-label (default 'Thinking'); the canvas itself is aria-hidden.
+- Because that label is the live region's accessible name, it must not change while the orb is mounted — a name that churns re-announces on every change, so a phase recomputed per streamed delta becomes an interruption per delta. Keep the label constant and let the phase live in adjacent text; announce an outcome once when the work settles, from a separate region.
+- Ink is the element's computed color, so contrast is the consumer's token choice — pair with foreground or muted-foreground rather than a decorative tint.
+- Honours the motion policy: under prefers-reduced-motion or <MotionProvider> off, it paints one still frame and never starts an animation loop.
+- The loop also stops when the orb scrolls out of view or the tab is backgrounded, so a forgotten orb cannot burn a CPU core.
+
+## Related
+
+- Components: Spinner, Skeleton, Progress, InlineStatus, ChatComposer, Message
+
+## Examples
+
+### Default
+
+```tsx
+import { ThinkingOrb } from "@sableui/react"
+
+<ThinkingOrb />
+```
+
+### Modes
+
+```tsx
+import { ThinkingOrb } from "@sableui/react"
+
+<ThinkingOrb mode="orbit" size="lg" />
+<ThinkingOrb mode="globe" size="lg" />
+<ThinkingOrb mode="mesh" size="lg" />
+```
+
+### Inline with a status line (the label stays constant, the phase moves)
+
+```tsx
+import { InlineStatus, ThinkingOrb } from "@sableui/react"
+
+<InlineStatus icon={<ThinkingOrb mode="globe" size="sm" label="Searching" />}>Searching your workspace…</InlineStatus>
+```
+
+### Tinted and paused
+
+```tsx
+import { ThinkingOrb } from "@sableui/react"
+
+<ThinkingOrb size="lg" className="text-primary" paused />
+```