@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/panel-group.md

@@ -0,0 +1,120 @@
+# PanelGroup
+
+**Status:** stable
+
+A row of docked chrome panels around a flexible centre, with draggable and keyboard-resizable edges and optional persisted widths.
+
+**Keywords:** panel, panels, resize, resizable, splitter, docked, workspace, tool, chrome, inspector, layout
+
+## Usage
+
+Use PanelGroup for the body of a tool workspace: fixed-width Panels docked left and/or right, a flexible Panel in the middle for the canvas, and a PanelResizer between them. Panels scroll internally and the group never scrolls. This is the workspace-register counterpart to SplitPane, which only switches between side-by-side and stacked at a breakpoint and cannot be resized.
+
+### Best practices
+
+- Do: Give every docked Panel a fixed width and leave the centre Panel width-less so it absorbs the remaining space.
+- Do: Drive the width with usePanelWidth and pass a storageKey, so a user's layout survives a reload. Spread its bounds onto the PanelResizer rather than repeating min and max by hand.
+- Do: Label every Panel — they are landmarks, and 'Layers' or 'Properties' is what a screen-reader user navigates by.
+- Don't: Let the group scroll. Only panels and the canvas scroll; a scrolling group means the shell lost its height constraint.
+- Don't: Use it for page content columns — that's Grid or Columns. PanelGroup is chrome, and it sits outside the content grid.
+- Don't: Omit PanelResizer to save effort and then let users live with a fixed panel. If a panel holds a tree or a property grid, its width is a preference.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| PanelGroup | yes | The flex row. Sets min-h-0/min-w-0 so children can actually shrink and scroll. |
+| Panel | yes | One column. Fixed-width when `width` is set, flexible otherwise. Scrolls internally. |
+| PanelResizer | no | The draggable edge between two panels: a 1px hairline with a wider hit area, operable by pointer and keyboard. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| Panel | { label: string; width?: number; scroll?: boolean } | A docked or flexible column. `label` names the landmark; omit `width` for the flexible centre. `scroll` defaults to true — set it false for a header + scrolling body + pinned footer, so the footer doesn't scroll away with the list. When you own the layout, give the header and footer shrink-0 and the middle min-h-0 flex-1 overflow-y-auto. overflow-y-auto only activates if every flex ancestor can shrink: a single missing min-h-0 anywhere up the chain makes the panel grow instead of scroll, and nothing reports it. |
+| PanelResizer | { side: 'left' \| 'right'; width: number; onWidthChange: (n: number) => void; label: string; min?: number; max?: number; step?: number } | The draggable edge. `side` says which side the resized panel is on, so the drag delta's sign is right. |
+| usePanelWidth | (defaultWidth: number, options?: { storageKey?: string; min?: number; max?: number }) => readonly [number, (n: number) => void, { min: number; max: number }] | Controlled width for a Panel, clamped and optionally persisted to localStorage (only when `storageKey` is passed). Read through useSyncExternalStore, so there is no server/client hydration mismatch and no setState in an effect; do not hand-roll a localStorage read during render or a write from an effect. Without `storageKey` the width is kept in memory per hook instance. The third element is the `{ min, max }` it clamps to: spread it onto the paired PanelResizer so the separator's aria-valuemin/max and Home/End match the real clamp. |
+
+## Tokens used
+
+`primary`, `panel`, `hairline`, `hairline-strong`
+
+## Accessibility
+
+- PanelResizer is a role=separator with aria-orientation, aria-valuenow/min/max, and is focusable — a pointer-only resizer is a keyboard trap.
+- Arrow keys resize by `step`; Home and End jump to the minimum and maximum.
+- Each Panel renders an <aside> with an accessible name from `label`, so panels are navigable landmarks.
+
+## Related
+
+- Components: PanelSection, ScrubField, SplitPane, Sidebar, AppShell
+
+## Examples
+
+### Tool body with a resizable left panel
+
+```tsx
+import { Panel, PanelGroup, PanelResizer, PanelSection, PropertyRow, Switch, usePanelWidth } from "@sableui/react"
+
+function Body() {
+  const [leftWidth, setLeftWidth, leftBounds] = usePanelWidth(240, { storageKey: "app:panel:left", min: 180, max: 360 })
+  return (
+    <PanelGroup>
+      <Panel label="Layers" width={leftWidth}>
+        <PanelSection title="Layers">
+          <PropertyRow label="Background">
+            <Switch checked />
+          </PropertyRow>
+        </PanelSection>
+      </Panel>
+      <PanelResizer side="left" width={leftWidth} onWidthChange={setLeftWidth} label="Resize layers panel" {...leftBounds} />
+      <Panel label="Canvas">
+        <div className="grid h-full place-items-center bg-canvas text-ui-body text-muted-foreground">Canvas</div>
+      </Panel>
+    </PanelGroup>
+  )
+}
+```
+
+### Both edges resizable
+
+```tsx
+import { Panel, PanelGroup, PanelResizer, PanelSection, PropertyPair, ScrubField, usePanelWidth } from "@sableui/react"
+
+function Body() {
+  const [left, setLeft, leftBounds] = usePanelWidth(240, { storageKey: "app:left" })
+  const [right, setRight, rightBounds] = usePanelWidth(256, { storageKey: "app:right" })
+  return (
+    <PanelGroup>
+      <Panel label="Layers" width={left} />
+      <PanelResizer side="left" width={left} onWidthChange={setLeft} label="Resize layers panel" {...leftBounds} />
+      <Panel label="Canvas" />
+      <PanelResizer side="right" width={right} onWidthChange={setRight} label="Resize properties panel" {...rightBounds} />
+      <Panel label="Properties" width={right}>
+        <PanelSection title="Blending">
+          <PropertyPair>
+            <ScrubField label="Opacity" icon="grid" suffix="%" value={100} min={0} max={100} />
+            <ScrubField label="Blur" value={0} min={0} max={64} suffix="px" />
+          </PropertyPair>
+        </PanelSection>
+      </Panel>
+    </PanelGroup>
+  )
+}
+```
+
+### Fixed panel, no resizer
+
+```tsx
+import { Button, Icon, Panel, PanelGroup } from "@sableui/react"
+
+<PanelGroup>
+  <Panel label="Tools" width={56}>
+    <div className="flex flex-col gap-1 p-1">
+      <Button size="icon-xs" variant="ghost" aria-label="Toggle grid"><Icon name="grid" /></Button>
+      <Button size="icon-xs" variant="ghost" aria-label="Hide"><Icon name="eye" /></Button>
+    </div>
+  </Panel>
+  <Panel label="Canvas" />
+</PanelGroup>
+```

package/llms/components/panel-section.md

@@ -0,0 +1,122 @@
+# PanelSection
+
+**Status:** stable
+
+A flush group of property rows inside a docked panel — eyebrow header, hairline separator, rows beneath. The workspace register's answer to Card, which does not belong in a panel.
+
+**Keywords:** panel, section, inspector, properties, property grid, workspace, tool, chrome, sidebar
+
+## Usage
+
+Use PanelSection to group properties inside an inspector or docked panel, with PropertyRow for one label-plus-control line and PropertyPair for two controls side by side. This is the workspace register's grouping primitive: it separates with a hairline and nothing else, because a Card inside a 240px panel spends its border and inset on nothing and pushes every row inward.
+
+### Best practices
+
+- Do: Group related properties under a short functional title — Blending, Layout, Fill — the way a tool inspector names its sections.
+- Do: Reach for PropertyPair before giving each property its own full-width row; pairing halves the vertical cost in a narrow panel.
+- Do: Put a section-scoped control (a visibility toggle, an add action) in the action slot rather than inventing a second header row.
+- Don't: Wrap panel content in Card. Cards are page-register furniture; in a panel they read as a page pasted into chrome.
+- Don't: Repeat the panel's own title as the section title. If the header above already names the selection, title the section by what it controls (Parameters, Blending).
+- Don't: Hand-roll a property line (`<div className="flex justify-between"><span>Opacity</span><Slider /></div>`). Use PropertyRow for every label-plus-control line: when each property type invents its own arrangement, a panel of fifteen properties ends up with fifteen layouts.
+- Don't: Use PropertyRow for page forms — use Field, which carries label/description/error semantics. PropertyRow is a dense chrome row, not a form control.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Header | yes | The section title in the UI section tier, with an optional trailing action. |
+| PropertyRow | no | One property: label left, control right. `stacked` moves the control to its own line for full-width controls. |
+| PropertyPair | no | Two controls side by side, with optional captions above each. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| PropertyRow | { label: ReactNode; htmlFor?: string; hint?: string; stacked?: boolean; scrub?: { value, onValueChange, step?, min?, max?, onGestureStart?, onGestureEnd?, disabled? } } | One property line. `hint` becomes the label's hover explanation; `stacked` puts the control on its own line. `scrub` makes the property NAME a drag handle for its value — the Figma/Framer/Paper convention, and the answer for a numeric row with no honest glyph to put in a ScrubField (a schema-generated `levels` or `seed`, where a `#` would be noise pretending to be meaning). Opt-in and additive: a row without it is unchanged. The label stays a real `<label htmlFor>` — a 2px jitter threshold keeps a click a click, and the click synthesised after a real drag is swallowed so a scrub does not also select the field's text. |
+| PropertyPair | { labels?: [ReactNode, ReactNode] } | Two controls side by side in a 2-up grid, with optional captions above each. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| title | ReactNode | — | Section name, rendered as the header in the UI section tier. |
+| action | ReactNode | — | Optional trailing control in the header — a visibility toggle, an add action. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `hairline`
+
+## Accessibility
+
+- PropertyRow renders a real <label>; pass htmlFor with the control's id so clicking the label focuses it.
+- The section title is an h3, so panels contribute a real heading outline rather than styled divs.
+- `hint` is exposed as the label's title attribute — keep the essential meaning in the label itself, since title text is not reliably announced.
+- A `scrub` label does not replace keyboard editing and must not be the only way to set the value: the drag is a pointer affordance, so the control it names still has to accept typing and arrow keys. It also keeps its `htmlFor` behaviour, which is the reason the gesture arms on a 2px threshold rather than on pointerdown.
+
+## Related
+
+- Components: Workspace, PanelGroup, ScrubField, StatusBar, Field, Card
+
+## Examples
+
+### Blending section, 2-up
+
+```tsx
+import { PanelSection, PropertyPair, ScrubField, Select, SelectContent, SelectItem, SelectTrigger } from "@sableui/react"
+
+<PanelSection title="Blending">
+  <PropertyPair>
+    <ScrubField label="Opacity" value={100} min={0} max={100} suffix="%" />
+    <Select value="normal">
+      <SelectTrigger size="xs" />
+      <SelectContent>
+        <SelectItem value="normal">Normal</SelectItem>
+        <SelectItem value="multiply">Multiply</SelectItem>
+      </SelectContent>
+    </Select>
+  </PropertyPair>
+</PanelSection>
+```
+
+### Rows with a stacked slider
+
+```tsx
+import { PanelSection, PropertyRow, Select, SelectContent, SelectItem, SelectTrigger, Slider, Switch } from "@sableui/react"
+
+<PanelSection title="Parameters">
+  <PropertyRow label="Block size" hint="Block edge length in reference pixels." stacked>
+    <Slider value={32} min={4} max={256} />
+  </PropertyRow>
+  <PropertyRow label="Direction">
+    <Select value="both">
+      <SelectTrigger size="xs" />
+      <SelectContent>
+        <SelectItem value="both">Both</SelectItem>
+        <SelectItem value="horizontal">Horizontal</SelectItem>
+      </SelectContent>
+    </Select>
+  </PropertyRow>
+  <PropertyRow label="Reverse">
+    <Switch checked={false} />
+  </PropertyRow>
+</PanelSection>
+```
+
+### Section with a header action
+
+```tsx
+import { Button, Icon, PanelSection, PropertyRow, ScrubField } from "@sableui/react"
+
+<PanelSection
+  title="Blending"
+  action={
+    <Button size="icon-xs" variant="ghost" aria-label="Hide layer">
+      <Icon name="eye" />
+    </Button>
+  }
+>
+  <PropertyRow label="Opacity">
+    <ScrubField label="Opacity" value={60} min={0} max={100} suffix="%" />
+  </PropertyRow>
+</PanelSection>
+```

package/llms/components/phone.md

@@ -0,0 +1,70 @@
+# Phone
+
+**Status:** stable
+
+A current smartphone frame at iPhone proportions: a dark body with a titanium band, thin bezels, an island, an optional status bar and a scrollable screen.
+
+**Keywords:** phone, device mockup, mobile preview, frame
+
+## Usage
+
+Use Phone to frame a mobile product preview when the device context is useful.
+
+### Best practices
+
+- Do: Use it for mobile UI demos, screenshots, and responsive previews.
+- Do: Keep the framed content legible and avoid stuffing full desktop layouts into the phone frame.
+- Don't: Do not use Phone as a generic panel, card, or production app shell.
+- Don't: Do not use it to test responsive behaviour. The frame is a fixed aspect box, not a viewport, so media queries inside key off the real window.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| children | ReactNode | — | Content rendered inside the scrollable screen region. |
+| statusBar | boolean | true | Draw a status bar (time, signal, battery) across the top of the screen. Turn it off to frame a screenshot that already has one. |
+| systemChrome | boolean | true | Draw the camera pill and home indicator. Turn it off when the content draws its own system chrome, such as an iOS prototype framed by PhoneFrame from @sableui/react/ios/preview. |
+| className | string | — | Additional classes merged onto the outer wrapper (set the width here; the screen keeps its proportions). |
+
+## Tokens used
+
+`background`, `foreground`
+
+## Accessibility
+
+- Purely presentational frame; the screen region scrolls when content overflows. Add headings/landmarks in the content as needed.
+- The frame's chrome (status bar, camera, buttons) is aria-hidden, so the content inside carries the entire accessible meaning. A screenshot with no alt text makes the whole mockup announce as nothing at all.
+
+## Related
+
+- Components: Browser
+
+## Examples
+
+### Framing a mobile layout
+
+```tsx
+import { Phone } from "@sableui/react"
+
+<Phone><div className="p-4"><h2 className="text-title-lg">Activity</h2><p className="text-body-sm text-muted-foreground">3 new collects today.</p></div></Phone>
+```
+
+### Mockup, not a responsive preview
+
+```tsx
+import { Phone } from "@sableui/react"
+
+// Phone is DECORATIVE framing for a mobile screenshot on a marketing surface.
+
+<Phone>
+  <img src="/screenshots/mobile.png" alt="The mobile app" />
+</Phone>
+
+// ✗ Using it to test responsive layout. The frame is a fixed aspect box, not a
+//   viewport — media queries inside it key off the real window, so what you see
+//   is not what a phone renders. Resize the browser, or use device emulation.
+// ✗ Wrapping live, interactive app UI (forms, buttons that act). Same as Browser: the frame says "picture of
+//   software", so real controls inside it read as a screenshot that moves. Static composed content is fine.
+//   The exception is a clickable iOS prototype: PhoneFrame (@sableui/react/ios/preview)
+//   frames a whole phone-sized document in an iframe, where the frame is the device.
+```

package/llms/components/pill.md

@@ -0,0 +1,73 @@
+# Pill
+
+**Status:** stable
+
+A chip someone clicks: a filter, a tag choice, an option in a row. Always a button with aria-pressed. appearance="solid" (filters; selected lifts onto the primary surface) or "outline" (quiet chips that annotate content, like reactions); size md or sm. A static label is a Badge.
+
+**Keywords:** pill, chip, filter, tag, toggle chip, category
+
+## Usage
+
+Use Pill for a row of filters or choices a person clicks to narrow or toggle what they see. For a label that only describes something, use Badge.
+
+### Best practices
+
+- Do: Use short text that names the filter or choice.
+- Do: Reflect the current choice with selected, so the active filter reads at a glance.
+- Don't: Do not use Pill as a static label. A pressable-looking chip that does nothing is the most common cause of dead clicks in a filter row — that is a Badge.
+- Don't: Do not use Pill for primary actions or important system status.
+- Don't: Do not restyle a Pill with border or background classes to get a quieter chip. That is appearance="outline" (and size="sm" for a small one); an override is a look that exists nowhere else in the system.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| selected | boolean | false | Marks the pill as chosen. Solid lifts onto the primary surface; outline takes a primary tint and soft primary edge. Sets aria-pressed. |
+| appearance | "solid" \| "outline" | "solid" | solid for a filter row; outline for quiet chips that annotate other content (a reaction under a message, a tag on a card), where a filled chip would compete with what it annotates. |
+| size | "md" \| "sm" | "md" | sm sits on the density ladder's xs control height, for chips under or inside other content. |
+| icon | ReactNode | — | Optional leading glyph (e.g. <Icon name="lock" />), rendered before the children with the base gap. |
+
+## Variants
+
+- **appearance**: solid, outline
+- **size**: md, sm
+- **selected**: true, false
+
+## Tokens used
+
+`secondary`, `secondary-foreground`, `accent`, `accent-foreground`, `primary`, `primary-foreground`, `card`, `border`, `muted-foreground`, `foreground`
+
+## Accessibility
+
+- Renders a native <button type="button"> for focus and keyboard activation.
+- Selected state is exposed via aria-pressed.
+
+## Related
+
+- Components: Badge, ToggleGroup
+
+## Examples
+
+### Filter row
+
+```tsx
+import { Pill, Row } from "@sableui/react"
+
+<Row gap={1}><Pill selected onClick={() => {}}>All</Pill><Pill onClick={() => {}}>Editions</Pill><Pill onClick={() => {}}>Collectibles</Pill></Row>
+```
+
+### Outline, small (reactions)
+
+```tsx
+import { Pill, Row } from "@sableui/react"
+
+<Row gap={1}><Pill appearance="outline" size="sm" selected onClick={() => {}}>🎉 3</Pill><Pill appearance="outline" size="sm" onClick={() => {}}>👀</Pill></Row>
+```
+
+### With icon
+
+```tsx
+import { Icon, Pill } from "@sableui/react"
+
+<Pill icon={<Icon name="lock" />} onClick={() => {}}>Locked</Pill>
+```

package/llms/components/popover.md

@@ -0,0 +1,79 @@
+# Popover
+
+**Status:** stable
+
+Click-triggered overlay over Base UI Popover (focus management, collision-aware positioning, Esc/outside dismissal). Holds interactive content; 18rem-wide surface.
+
+**Keywords:** popover, floating panel, anchored, disclosure
+
+## Usage
+
+Use Popover for anchored secondary content that needs more room than a tooltip but less commitment than a dialog.
+
+### Best practices
+
+- Do: Use it for small pickers, summaries, or contextual controls tied to a trigger.
+- Do: Keep focus behavior and dismissal predictable.
+- Don't: Do not use Popover for blocking confirmations, long forms, or critical information.
+- Don't: Do not put a form that can fail validation inside one. A popover dismisses on outside click, which discards what the user typed with no warning — that is a Dialog.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| PopoverTrigger | yes | The element that anchors and opens the popover. |
+| PopoverContent | yes | The floating content surface. |
+| PopoverTitle | no | An optional heading for the content. |
+| PopoverDescription | no | Optional supporting copy. |
+| PopoverClose | no | An explicit close control when helpful. |
+| PopoverArrow | no | An optional arrow pointing to the trigger. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| PopoverTrigger | Base UI Trigger props + render | The anchor element. Use render={<Button/>} to compose with another component. |
+| PopoverContent | Base UI Popup props + side: "top" \| "bottom" \| "left" \| "right" \| "inline-*" + align: "start" \| "center" \| "end" + sideOffset: number + anchor: Element \| Ref \| (() => Element) \| VirtualElement + className | Portals + positions + paints the popup. side picks which side of the trigger to render against (auto-flips on collision; defaults to "bottom"); align sets alignment along that side (defaults to "center"); sideOffset is the gap in px (defaults to 8). anchor positions against a different element/ref/getter than the trigger — Base UI 1.5 has no separate Anchor part, so pass it here to decouple the open-location from the trigger. |
+| PopoverTitle | Base UI Title props + className | Accessible heading; Base UI wires aria-labelledby to the popup. |
+| PopoverDescription | Base UI Description props + className | Supplementary copy; Base UI wires aria-describedby to the popup. |
+| PopoverClose | Base UI Close props + render | A button that closes the popover. Use render={<Button/>} to compose. |
+| PopoverArrow | Base UI Arrow props + className | Optional pointer connecting the popup to its trigger. Place inside PopoverContent. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Popover (Root) | Base UI Popover.Root props (open, defaultOpen, onOpenChange, modal) | — | Groups the trigger and content. Uncontrolled by default. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border-floating`, `muted-foreground`
+
+## Accessibility
+
+- Base UI manages focus into and out of the popup, traps focus when modal, and restores focus to the trigger on close.
+- Opens on trigger press (click/Enter/Space); dismisses on Esc and outside press.
+- PopoverTitle/PopoverDescription wire aria-labelledby/aria-describedby on the popup.
+- Enters and exits on the motion-pop recipe (Base UI starting/ending-style attributes), so it follows the motion policy.
+
+## Related
+
+- Components: Tooltip, ContextCard, Dialog
+
+## Examples
+
+### Basic
+
+```tsx
+import { Button, Popover, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from "@sableui/react"
+
+<Popover><PopoverTrigger render={<Button variant="secondary">Details</Button>} /><PopoverContent><PopoverTitle>Edition details</PopoverTitle><PopoverDescription>A limited run of 100, stored permanently on Arweave.</PopoverDescription></PopoverContent></Popover>
+```
+
+### With close
+
+```tsx
+import { Button, Popover, PopoverClose, PopoverContent, PopoverDescription, PopoverTitle, PopoverTrigger } from "@sableui/react"
+
+<Popover><PopoverTrigger render={<Button variant="secondary">Open</Button>} /><PopoverContent><PopoverTitle>Heads up</PopoverTitle><PopoverDescription>Collecting mints a compressed NFT to your wallet.</PopoverDescription><PopoverClose render={<Button size="sm">Got it</Button>} /></PopoverContent></Popover>
+```

package/llms/components/progress.md

@@ -0,0 +1,98 @@
+# Progress
+
+**Status:** stable
+
+Linear progress bar over Base UI Progress — value 0–100 drives the fill; omit value (or pass null) for an indeterminate, pulsing bar.
+
+**Keywords:** progress, task progress, meter, loading
+
+## Usage
+
+Use Progress to communicate determinate or indeterminate completion for a task or process.
+
+### Best practices
+
+- Do: Use determinate values when progress can be measured.
+- Do: Pair the visual indicator with text when users need context or exact values.
+- Don't: Do not use Progress as a decorative divider or status color bar.
+- Don't: Do not use a determinate Progress for an unknown duration. A bar that sits at 90% is worse than a Spinner, because it makes a promise about time that you cannot keep.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| ProgressTrack | yes | The background track that defines the range. |
+| ProgressIndicator | yes | The filled or animated progress indicator. |
+| ProgressLabel | no | A text label for the progress task. |
+| ProgressValue | no | A readable value such as 45 percent. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| ProgressTrack | Base UI Track props + className | The rail. Rendered automatically when Progress has no children; renders a ProgressIndicator child by default. Takes `size` (inherited from Progress) for its thickness — use that rather than a className height. |
+| ProgressIndicator | Base UI Indicator props + className | The fill. Width is set by Base UI from the value; spans full width and pulses while indeterminate. |
+| ProgressLabel | Base UI Label props + className | Accessible label; wires aria-labelledby on the Root. |
+| ProgressValue | Base UI Value props + className | Formatted value readout. Accepts a render-function child for custom formatting. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number \| null | null | Current value between min and max. null (or omitted) renders the indeterminate state. |
+| min | number | 0 | The minimum value of the range. |
+| max | number | 100 | The maximum value of the range. |
+| format | Intl.NumberFormatOptions | — | Formatting options for ProgressValue (e.g. style: 'percent', or a currency). |
+| getAriaValueText | (formatted, value) => string | — | Returns a human-readable text alternative for aria-valuenow. |
+| size | "sm" \| "md" \| "lg" | "md" | Bar thickness, on the same three rails as Meter so the two match on one page. ProgressTrack inherits it. |
+
+## Variants
+
+- **size**: sm, md, lg
+
+## Tokens used
+
+`secondary`, `primary`, `foreground`, `muted-foreground`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — A progress bar appears because work started. Staging its entrance delays the one piece of information the reader is waiting for.
+- **response** · Root · _no motion_ — It reports; it does not accept input. A bar that reacted to the pointer would read as a Slider, which is a control the reader can drag.
+- **transition** · ProgressIndicator · _custom (outside the recipe layer)_ — Fill width eases between values on the motion tokens (no recipe animates width), so the bar reads as filling rather than as a series of unrelated widths. It matters most where progress arrives in coarse jumps — four chunked upload callbacks look like a glitching bar without it.
+- **activity** · ProgressIndicator · `motion-pulse` — Indeterminate (value null) has no width to animate, so the pulse carries the whole signal that work is still happening. Without it the indeterminate state is a static bar — indistinguishable from a stalled determinate one.
+
+## Accessibility
+
+- Base UI sets role=progressbar with aria-valuenow / aria-valuemin / aria-valuemax and reports status to screen readers.
+- Indeterminate state (value null) omits aria-valuenow per the ARIA spec.
+- Pair ProgressLabel with the bar for a visible, associated name; ProgressValue exposes the formatted value.
+
+## Related
+
+- Components: Spinner, Skeleton
+
+## Examples
+
+### Determinate
+
+```tsx
+import { Progress } from "@sableui/react"
+
+<Progress value={64} aria-label="Upload" />
+```
+
+### Indeterminate
+
+```tsx
+import { Progress } from "@sableui/react"
+
+<Progress aria-label="Preparing export" />
+```
+
+### With label and value
+
+```tsx
+import { Progress, ProgressLabel, ProgressTrack, ProgressValue } from "@sableui/react"
+
+<Progress value={40}><div className="mb-2 flex flex-wrap items-center justify-between gap-x-3 gap-y-1"><ProgressLabel>Uploading</ProgressLabel><ProgressValue /></div><ProgressTrack /></Progress>
+```

package/llms/components/radio-card.md

@@ -0,0 +1,90 @@
+# RadioCard
+
+**Status:** stable
+
+A selectable card option (radio-card) over Base UI RadioGroup + Radio. RadioGroup shares selection state; each RadioCard is a card with a radio indicator, title, and description. Add an icon to switch to the richer two-dimensional card, and a tone to give the selected state a semantic colour identity.
+
+**Keywords:** radio-card, choice card, selection, option card
+
+## Usage
+
+Use RadioCard for visual choice cards when users compare a small set of named options.
+
+### Best practices
+
+- Do: Use it when labels, descriptions, or icons make options easier to understand.
+- Do: Make the selected state explicit and preserve keyboard access through the group.
+- Don't: Do not use RadioCard for dense menus, long lists, or simple yes/no settings.
+- Don't: Do not use a single RadioCard on its own. It is a radio, so one option cannot be deselected — a lone one is a switch, and should be a Switch.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| RadioCard | yes | One selectable option card. |
+| RadioGroup | no | A grouped set of related choice cards. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| RadioGroup | Base UI RadioGroup props (value, defaultValue, onValueChange, name, disabled, readOnly, required) + className | The group container that wraps the RadioCard cards and shares their selection state. Controlled via value + onValueChange; uncontrolled via defaultValue. Lays its cards out in a single column by default; override with className (e.g. 'grid sm:grid-cols-3') for a grid — the group is a flex column, so a grid-cols-* class alone does nothing. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | — | The unique value that pairs this card with the group's selected value. |
+| title | ReactNode | — | The card's primary label (rendered as text-title-sm). |
+| description | ReactNode | — | Optional supporting copy beneath the title (text-body-sm, muted). |
+| icon | ReactNode | — | Leading icon (e.g. a solid <Icon>). Its presence switches to the two-dimensional card — icon top-left, indicator top-right, copy below — and the glyph is rendered as a solid-fill icon in the tone colour. |
+| tone | "neutral" \| "standard" \| "collectible" \| "edition" \| "info" \| "warning" | "neutral" | Semantic colour the selected state carries across the border, radio, and icon glyph. Neutral uses the primary ring with a muted wash. |
+| disabled | boolean | false | Dims the card and blocks selection. The group skips it during keyboard navigation. |
+| titleClassName | string | — | Merged onto the title span (default text-title-sm) — e.g. to tighten copy in a two-column layout. |
+| descriptionClassName | string | — | Merged onto the description span (default text-body-sm text-muted-foreground). |
+
+## Variants
+
+- **tone**: neutral, standard, collectible, edition, info, warning
+
+## Tokens used
+
+`input`, `card`, `foreground`, `primary`, `muted`, `ring`, `muted-foreground`, `tone-standard`, `tone-collectible`, `tone-edition`, `tone-info`, `tone-warning`
+
+## Accessibility
+
+- Base UI provides the radiogroup/radio roles, aria-checked, hidden native inputs, and roving tabindex.
+- Arrow keys move and select between cards; Space selects the focused card; Tab enters/leaves the group.
+- Checked state styling reads from the data-[checked] attribute; disabled cards from data-disabled.
+- focus-within draws a 2px ring on the focused card; the whole card is the hit target.
+- The icon is decorative — the title labels the card — so selection meaning never relies on colour alone (the border ring and the filled radio both shift; the neutral tone adds a muted fill).
+
+## Related
+
+- Components: Radio, CheckboxCard, Select
+
+## Examples
+
+### Post type (tone + icon)
+
+```tsx
+import { Icon, RadioCard, RadioGroup } from "@sableui/react"
+
+<RadioGroup defaultValue="post" className="grid sm:grid-cols-3"><RadioCard value="post" tone="standard" icon={<Icon name="plus" />} title="Standard" description="Share without minting" /><RadioCard value="collectible" tone="collectible" icon={<Icon name="gem" />} title="Collectible" description="Free to collect as NFT" /><RadioCard value="edition" tone="edition" icon={<Icon name="image-stack" />} title="Edition" description="Sell as NFT editions" /></RadioGroup>
+```
+
+### Plan picker (plain)
+
+```tsx
+import { RadioCard, RadioGroup } from "@sableui/react"
+
+<RadioGroup defaultValue="pro"><RadioCard value="free" title="Free" description="For trying things out." /><RadioCard value="pro" title="Pro" description="For growing teams." /><RadioCard value="enterprise" title="Enterprise" description="Custom limits and support." /></RadioGroup>
+```
+
+### With a disabled option
+
+```tsx
+import { RadioCard, RadioGroup } from "@sableui/react"
+
+<RadioGroup defaultValue="free"><RadioCard value="free" title="Free" description="For trying things out." /><RadioCard value="enterprise" title="Enterprise" description="Contact sales to enable." disabled /></RadioGroup>
+```