@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/calendar.md

@@ -0,0 +1,75 @@
+# Calendar
+
+**Status:** stable
+
+Date picker grid wrapping react-day-picker v9, themed entirely with semantic tokens (no external stylesheet). Supports single, multiple, and range selection; nav chevrons render through the injected icon set.
+
+**Keywords:** calendar, date grid, month, schedule
+
+## Usage
+
+Use Calendar to browse or choose dates in a month grid, especially when relative date position matters.
+
+### Best practices
+
+- Do: Use it when users need to compare weekdays, ranges, or nearby dates.
+- Do: Provide selected, disabled, and today states when date choice is interactive.
+- Don't: Do not use Calendar when a compact DatePicker (with granularity="minute" for a time) would be faster.
+- Don't: Do not use it as the only way to enter a date. A grid is slow for a date far from today and unusable for someone who knows the value — always pair it with a text input.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| mode | "single" \| "multiple" \| "range" | — | Selection behavior. Pair with the matching selected/onSelect shape (Date, Date[], or DateRange). |
+| selected | Date \| Date[] \| DateRange \| undefined | — | The controlled selection. Shape follows mode. |
+| onSelect | (value, triggerDate, modifiers, event) => void | — | Fires when a day is chosen. The first argument's type follows mode. |
+| defaultMonth | Date | — | The month shown on first render (uncontrolled navigation). |
+| month | Date | — | Controlled displayed month; pair with onMonthChange. |
+| numberOfMonths | number | 1 | How many month grids to render side by side. |
+| disabled | Matcher \| Matcher[] | — | Days matching this are dimmed and non-selectable (e.g. { before: new Date() }). |
+| showOutsideDays | boolean | true | Render leading/trailing days from adjacent months, dimmed. |
+| bare | boolean | false | Drop the card frame (border, fill, padding) so the grid sits flush inside a surface that already has one, such as a Popover. DatePicker renders its Calendar this way. |
+| className | string | — | Merged onto the bordered card container that wraps the grid. |
+| classNames | Partial<ClassNames> | — | Per-part class overrides merged over the themed defaults. Themed slots: months, month, nav, button_previous, button_next, month_caption, caption_label, month_grid, weekdays, weekday, week, day, day_button, range_start, range_middle, range_end, selected, today, outside, disabled, hidden. Selection/state slots (selected/today/range_*/outside/disabled) style the day CELL; the inner day button is targeted via the [&>button] descendant. |
+| components | Partial<CustomComponents> | — | Render overrides for RDP parts. Chevron is supplied by default and merged with yours. |
+
+## Variants
+
+- **mode**: single, multiple, range
+
+## Tokens used
+
+`card`, `card-foreground`, `border`, `primary`, `primary-foreground`, `accent`, `accent-foreground`, `muted-foreground`, `ring`
+
+## Accessibility
+
+- react-day-picker manages the roving-tabindex grid, arrow-key navigation, and ARIA roles/labels for the calendar.
+- Selected days use bg-primary/text-primary-foreground for AA contrast; today is marked with a dot under the number (not a ring, which is reserved for keyboard focus) rather than color alone.
+- Disabled and outside days are dimmed and removed from the tab order.
+- Nav chevrons resolve through the injected IconProvider; ensure chevron-left and chevron-right are registered in the icon set.
+
+## Related
+
+- Components: DatePicker
+
+## Examples
+
+### Single date
+
+```tsx
+import { Calendar } from "@sableui/react"
+
+const [date, setDate] = useState<Date>()
+<Calendar mode="single" selected={date} onSelect={setDate} />
+```
+
+### Range
+
+```tsx
+import { Calendar } from "@sableui/react"
+import type { DateRange } from "react-day-picker"
+
+const [range, setRange] = useState<DateRange>()
+<Calendar mode="range" selected={range} onSelect={setRange} numberOfMonths={2} />
+```

package/llms/components/card.md

@@ -0,0 +1,135 @@
+# Card
+
+**Status:** stable
+
+Raised surface container (rounded-lg) with optional Header/Title/Description/Action/Content/Footer parts. A density knob trades the part padding (comfortable vs compact) for denser section panels. `render` makes the whole card one link or button, with a hover, a full-card focus ring and motion.
+
+**Keywords:** card, surface, panel, container, tile, section, header, footer, settings, link card, clickable card, nav card
+
+## Usage
+
+Use Card for a discrete thing with its own boundary, such as one product, one notification, one metric, or one setting cluster. Do not use Card as the default way to group every page section; whitespace, headings, Stack, Section, and dividers often create cleaner hierarchy.
+
+### Best practices
+
+- Do: Use Card when the item could be reordered, removed, selected, or compared independently.
+- Do: Keep sibling cards on the same density and padding rhythm so lists and grids scan cleanly.
+- Do: Use CardHeader, CardContent, and CardFooter when the card has a stable title/body/action structure.
+- Do: Make the whole card one link (`render={<a href="…" />}`) when the card IS a single destination — a nav tile, a gallery item, a news teaser — and nothing inside it is interactive. All of the card text becomes the accessible name of the link, so keep it short: a title and a line.
+- Don't: Make a card a link when it holds its own buttons, menus, switches or links. Interactive content nested in a link is invalid HTML and announces twice; keep the card a plain surface and put the link on its title or in CardFooter instead.
+- Don't: Wrap every settings section or form group in a card; use headings, Stack, or the SettingsPage pattern instead.
+- Don't: Nest cards inside cards. Flatten the hierarchy or use dividers and spacing inside one card.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Container | yes | The raised or flat surface that creates the item boundary. |
+| Header | no | Optional title, description, and aligned action area for the card's identity. |
+| Content | yes | The body region. It should contain the information or controls that belong to this one item. |
+| Footer | no | Optional action or metadata row, usually lower-emphasis than the header. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| CardHeader | ComponentPropsWithRef<"div"> | Top section holding CardTitle/CardDescription (and optionally CardAction). Padding follows the density knob. |
+| CardTitle | ComponentPropsWithRef<"div"> | The card's name (text-title-lg). |
+| CardDescription | ComponentPropsWithRef<"div"> | Muted supporting line under the title. |
+| CardAction | ComponentPropsWithRef<"div"> | Header-aligned top-right action slot (e.g. a dots menu, switch, or close button). Place inside CardHeader, which becomes a 2-column grid when present and collapses to a single column otherwise. |
+| CardContent | ComponentPropsWithRef<"div"> & { flush?: boolean } | The body region. Padding follows the density knob on all sides — does not assume a preceding CardHeader, so it is safe to use standalone (e.g. no CardHeader in the card). When paired with CardHeader, the seam stays tight because CardHeader zeroes its own bottom padding. `flush` runs it edge to edge for a table: the Table insets its first and last columns by exactly the card padding, so it lines up with the header — never hand-set pl-6/pr-6 on columns. |
+| CardList | ComponentPropsWithRef<"div"> | Rows that run edge to edge in the card (Entity rows, most often), divided by hairlines. Insets each row to the card's own padding, so a list card lines up with every other card at any density — no hand-tuned px-* on the rows. Under a CardHeader it opens with a hairline and a gap; alone it fills the card. |
+| CardFooter | ComponentPropsWithRef<"div"> | Bottom row for actions/meta. Padding follows the density knob. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| variant | "default" \| "flat" | "default" | "default" raises with bg-card + border + soft shadow; "flat" is transparent. |
+| density | "comfortable" \| "compact" | "comfortable" | Padding of the Header/Content/Footer parts: comfortable = p-6 (default), compact = p-4 for denser section panels (pair compact with the flat variant for a settings / form section panel). Threaded to the parts via the inherited --card-p custom property. Card sets --card-p via inline style, which beats a plain (non-!important) stylesheet override of the same property on the same element — use this prop rather than a className override; if an external override is unavoidable, it needs !important. |
+| render | useRender.RenderProp | — | Replace the rendered element through the Base UI render prop — most often `render={<a href="/x" />}` (or a router Link) to make the whole card one link. When the rendered element is a link (a[href]) or a button, the card gains a hover state (stronger border and shadow; a muted fill when flat), a full-card focus-visible ring and motion-interactive easing. Any other element (article, li) stays a static surface. Children can answer the hover with `group-hover/card:`. |
+
+## Variants
+
+- **variant**: default, flat
+- **density**: comfortable, compact
+
+## Tokens used
+
+`card`, `card-foreground`, `border`, `border-strong`, `muted`, `muted-foreground`, `ring`
+
+## Motion
+
+- **arrival** · Container · _no motion_ — A card is part of the layout it ships in; whatever stages that region owns the entrance. A card that fades in on its own delays reading the thing it holds.
+- **response** · Container · `motion-interactive` — Only when the card is rendered as a link or button. The border, shadow and ring ease in so the pointer reads as landing on one target, not as the grid flickering. No motion-press: a 0.97 settle on a surface this large reads as the layout lurching. A static card has no response, so it gets no transition.
+- **transition** · Container · _no motion_ — A card has no states of its own to move between. Selection is CheckboxCard or RadioCard; disclosure is Collapsible or Accordion.
+- **activity** · Container · _no motion_ — A card does not work on anything. Loading content inside it is a Skeleton's job.
+
+## Accessibility
+
+- Purely presentational by default; add headings/landmarks in content as needed.
+- Rendered as a link or button, the whole card is one target: its full text is the accessible name, and the focus ring wraps the whole card. Nothing interactive may sit inside it — nested links or buttons inside a link are invalid and unreachable for keyboard users in some browsers.
+- A Card is a container, not a landmark and not a heading. If its title is the only heading in the region, render it as a real heading element with a title tier — a visually-styled div gives screen-reader heading navigation nothing to find.
+
+## Related
+
+- Components: Region, Stack, Separator, Button, Badge
+- Patterns: DashboardPage, SettingsPage, ListDetailPage
+
+## Examples
+
+### With parts
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@sableui/react"
+
+<Card><CardHeader><CardTitle>Edition</CardTitle><CardDescription>Limited run of 100.</CardDescription></CardHeader><CardContent><p className="text-body-md">Each collector receives a signed print and the on-chain edition.</p></CardContent></Card>
+```
+
+### With a header action
+
+```tsx
+import { Button, Card, CardAction, CardContent, CardHeader, CardTitle, Icon } from "@sableui/react"
+
+<Card><CardHeader><CardTitle>Edition</CardTitle><CardAction><Button variant="ghost" size="icon-sm" aria-label="More"><Icon name="ellipsis" /></Button></CardAction></CardHeader><CardContent><p className="text-body-md text-muted-foreground">24 of 100 collected.</p></CardContent></Card>
+```
+
+### Compact section panel
+
+```tsx
+import { Card, CardContent, CardHeader, CardTitle } from "@sableui/react"
+
+<Card variant="flat" density="compact"><CardHeader><CardTitle>Notifications</CardTitle></CardHeader><CardContent><p className="text-body-sm text-muted-foreground">Push and email are enabled.</p></CardContent></Card>
+```
+
+### Product card with actions
+
+```tsx
+import { Badge, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@sableui/react"
+
+<Card><CardHeader><CardTitle>Midnight Archive</CardTitle><CardDescription>Edition #24 of 100</CardDescription><CardAction><Badge tone="edition">Edition</Badge></CardAction></CardHeader><CardContent><p className="text-body-sm text-muted-foreground">A signed print and token-gated download for collectors.</p></CardContent><CardFooter><Button size="sm">Collect</Button><Button size="sm" variant="ghost">Preview</Button></CardFooter></Card>
+```
+
+### Whole card as a link
+
+```tsx
+import { Card, CardContent, CardDescription, CardTitle, Icon } from "@sableui/react"
+
+<Card render={<a href="/components" />}><CardContent className="flex items-center justify-between gap-4"><div className="min-w-0"><CardTitle>Components</CardTitle><CardDescription>Every building block, with live examples.</CardDescription></div><Icon name="chevron-right" className="text-sm text-muted-foreground motion-interactive group-hover/card:translate-x-0.5 group-hover/card:text-foreground" /></CardContent></Card>
+```
+
+### Metric card
+
+```tsx
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@sableui/react"
+
+<Card density="compact"><CardHeader><CardTitle>Revenue</CardTitle><CardDescription>Last 30 days</CardDescription></CardHeader><CardContent><p className="text-heading-3">128.4 SOL</p><p className="text-body-sm text-success">+12.8% from previous period</p></CardContent></Card>
+```
+
+### List card
+
+```tsx
+import { Avatar, Card, CardDescription, CardHeader, CardList, CardTitle, Entity } from "@sableui/react"
+
+<Card><CardHeader><CardTitle>Members</CardTitle><CardDescription>3 people can edit this space.</CardDescription></CardHeader><CardList>{people.map((p) => <Entity key={p.id} interactive onSelect={() => open(p)} leading={<Avatar fallback={p.initials} alt={p.name} />} title={p.name} subtitle={p.role} />)}</CardList></Card>
+```

package/llms/components/carousel.md

@@ -0,0 +1,87 @@
+# Carousel
+
+**Status:** stable
+
+Generic, accessible, zero-dependency slide carousel. Transform track with measured slide pitch — multiple slides per view, infinite loop (cloned ends), pointer drag-to-swipe with snap, autoplay (with a pause control + hover/focus/reduced-motion pausing), arrows, dots, counter, and keyboard. Motion is token-driven.
+
+**Keywords:** carousel, gallery, slides, horizontal
+
+## Usage
+
+Use Carousel for a curated, finite sequence of media or cards that benefits from horizontal browsing.
+
+### Best practices
+
+- Do: Use obvious previous and next controls and make the current position understandable.
+- Do: Keep slide content independent so users do not need every slide to complete a task.
+- Don't: Do not hide critical information or primary conversion actions only inside later slides.
+- Don't: Do not autoplay without a visible pause control. Motion that cannot be stopped fails WCAG 2.2.2 and makes the surrounding text hard to read.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| children | ReactNode | — | Each top-level child becomes one slide. |
+| slidesToShow | number \| { base?: number; sm?: number; md?: number; lg?: number; xl?: number } | 1 | Slides visible per view. A number, or a mobile-first breakpoint set keyed to Tailwind's default min-widths (sm 640, md 768, lg 1024, xl 1280px); a missing key inherits from the next smaller defined one, and base (default 1) is also the server-render value. Resolved with matchMedia, so no hand-rolled resize hook is needed. |
+| gap | string | "0px" | Gap between slides (any CSS length). Use the spacing scale — e.g. "calc(var(--spacing) * 4)" — so density moves it. |
+| loop | boolean | false | Infinite loop via cloned ends (needs count > slidesToShow). |
+| autoplay | number | 0 | Auto-advance interval in ms (0 = off). Pauses on hover/focus/reduced-motion and exposes a play/pause control. |
+| arrows | boolean | true | Prev/next arrow buttons. |
+| dots | boolean | true | Pagination dots. |
+| counter | boolean | false | An N / M slide counter. |
+| draggable | boolean | true | Pointer drag-to-swipe. |
+| index | number | — | Controlled active index. |
+| defaultIndex | number | 0 | Initial index (uncontrolled). |
+| onIndexChange | (index: number) => void | — | Notified when the active index changes. |
+| label | string | — | Accessible label for the carousel region. |
+| slideClassName | string | — | Class for each slide wrapper (e.g. an aspect ratio). |
+| arrowClassName | string | — | Class for both prev/next arrow buttons. Merged through cn(), so a radius or shadow utility replaces the default rounded-full shadow-md rather than stacking with it. |
+
+## Tokens used
+
+`border`, `ring`, `popover`, `popover-foreground`, `foreground`, `muted-foreground`
+
+## Accessibility
+
+- Region carries aria-roledescription='carousel'; each slide is a group with aria-roledescription='slide' and an 'N of M' label; clones are aria-hidden.
+- Arrows and dots are real buttons (dots set aria-current); Left/Right arrow keys navigate when the viewport is focused.
+- A polite live region announces the active slide; it goes silent while auto-rotating (APG).
+- Autoplay exposes a pause/play control and pauses on hover, focus, and under prefers-reduced-motion (which also makes transitions instant).
+
+## Related
+
+- Components: Scroller, Dialog
+
+## Examples
+
+### Looping media
+
+```tsx
+import { Carousel } from "@sableui/react"
+
+<Carousel loop dots slideClassName="aspect-video">{images.map((s) => <img key={s.id} src={s.url} alt={s.alt} className="size-full object-cover" />)}</Carousel>
+```
+
+### Multiple per view
+
+```tsx
+import { Carousel } from "@sableui/react"
+
+<Carousel slidesToShow={3} gap="calc(var(--spacing) * 4)">{cards}</Carousel>
+```
+
+### Responsive per view
+
+```tsx
+import { Carousel } from "@sableui/react"
+
+<Carousel slidesToShow={{ base: 1, sm: 2, lg: 3 }} gap="calc(var(--spacing) * 6)" label="Templates">{cards}</Carousel>
+```
+
+### Autoplay
+
+```tsx
+import { Carousel } from "@sableui/react"
+
+<Carousel loop autoplay={4000} counter>{slides}</Carousel>
+```

package/llms/components/chat-composer.md

@@ -0,0 +1,126 @@
+# ChatComposer
+
+**Status:** stable
+
+The input half of a conversation: one surface holding attachments, an auto-growing field, and its controls. Enter sends, Shift+Enter breaks the line, and send becomes stop while a reply streams.
+
+**Keywords:** chat input, composer, message input, prompt input, send message, ai chat, support chat, textarea
+
+## Usage
+
+Pairs with MessageScroller to make a working chat. A single surface rather than an input with buttons parked beside it: attachments above, text in the middle, affordances along the bottom. Works controlled or uncontrolled — uncontrolled is the default because it is what the common case wants, and what lets a hook-free page shell ship a composer that actually types.
+
+### Best practices
+
+- Do: Pass `busy` while a reply streams, and `onStop` alongside it. Interrupting a long generation is the most common thing a reader wants during one, and the control belongs where their cursor already is.
+- Do: Leave it uncontrolled unless you need the text elsewhere — a slash-command menu, a draft you persist. Uncontrolled clears itself on send; controlled does not.
+- Do: Render pending uploads as `<Attachment>` chips in `attachments`, so the file and the message it belongs to stay in one box.
+- Do: Put model pickers and tool toggles in `leading`, beside the attach button — they are composer state, not message content, and belong on the chrome row rather than in the field.
+- Do: Building a docked agent panel inside a tool? Wrap the whole conversation — scroller, messages and composer — in `<Density value="compact">`. The entire set follows the workspace register from there: prose drops a tier, the rhythm tightens, and the controls come off the compact ladder. Do not hand-size it at the call site.
+- Don't: Do not clear a controlled composer for the user on send. Only the caller knows whether the send succeeded, and clearing on their behalf loses the message when it did not.
+- Don't: Do not add your own Enter-to-send handler on top. The built-in one already guards against firing mid-IME-composition, which is the line hand-rolled chat inputs miss.
+- Don't: Do not use it as a general multi-line input. That is `Textarea` — this one submits on Enter, which is wrong for any field inside a larger form.
+- Don't: Do not override the field's type utility to make it match your transcript. The field and `Bubble` both read the same tier already, which is what stops a message changing size the moment it is sent — overriding one breaks that pairing.
+- Don't: Do not remove the height cap to let the field grow without limit. A pasted essay would push the conversation off the screen; past the cap it scrolls.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Attachments | no | Pending files as chips, above the field, inside the same surface. |
+| Field | yes | An auto-growing Textarea, stripped of its own border and ring — the surface carries both — capped before it eats the transcript. |
+| Controls | yes | Attach and any `leading` controls on the left; `actions` and the send/stop button on the right. |
+| Footer | no | Helper text or a character counter below the controls. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | — | Controlled value. Omit for an uncontrolled composer that owns its own text. |
+| defaultValue | string | "" | Initial value when uncontrolled. |
+| onValueChange | (value: string) => void | — | Notified on every keystroke. Required when `value` is supplied. |
+| onSend | (value: string) => void | — | Called with the trimmed message. An uncontrolled composer clears itself afterwards; a controlled one is the caller's to clear. |
+| placeholder | string | "Send a message…" | Placeholder for the field. |
+| busy | boolean | false | A reply is streaming. Disables send, and swaps it for a stop control when `onStop` is supplied. |
+| onStop | () => void | — | Interrupt the in-flight reply. Supplying it turns send into stop while busy. |
+| disabled | boolean | false | Block sending entirely — over a limit, disconnected, read-only thread. Distinct from `busy`, which is temporary and offers a way out (stop). |
+| invalid | boolean | false | Mark the current text invalid. Colours the surface border and sets `aria-invalid` on the field. |
+| attachments | ReactNode | — | Attachment chips, shown above the field. |
+| leading | ReactNode | — | Controls on the left of the footer row — model picker, tool toggles. |
+| actions | ReactNode | — | Extra controls left of the send button. |
+| onAttach | () => void | — | Attach handler. Supplying it renders the built-in attach button. |
+| label | string | "Message" | Accessible label for the field. |
+| sendLabel | string | "Send message" | Accessible label for the send button. |
+| stopLabel | string | "Stop generating" | Accessible label for the stop button. |
+| footer | ReactNode | — | Helper text or counter below the controls. |
+| fieldRef | Ref<HTMLTextAreaElement> | — | Ref to the underlying textarea — for focusing after a send, or on mount. |
+| ...form props | Omit<ComponentPropsWithRef<"form">, "onSubmit" \| "defaultValue"> | — | Spread onto the form element. Use `onSend` rather than `onSubmit`. |
+
+## Variants
+
+- **invalid**: true, false
+
+## Tokens used
+
+`card`, `input`, `ring`, `destructive`, `foreground`, `muted-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `accent`, `accent-foreground`
+
+## Accessibility
+
+- A real `<form>`, so the send button is a submit button and the whole thing behaves as one control to assistive tech and to password managers alike.
+- Enter never submits while an IME composition is open (`isComposing`), so a CJK reader confirming a candidate word does not mail a fragment of their first sentence.
+- The focus ring is drawn on the surface via `focus-within`, not on the textarea, so the visible focus indicator matches the box a sighted user perceives as the input.
+- Send is disabled — not merely styled down — until there is non-whitespace to send, so the affordance and the behaviour agree for keyboard users.
+- Icon-only attach, send and stop buttons all carry accessible labels, each overridable for localisation.
+
+## Related
+
+- Components: MessageScroller, Message, Bubble, Attachment, Textarea
+- Patterns: ChatPanel
+
+## Examples
+
+### Uncontrolled — the common case
+
+```tsx
+import { ChatComposer } from "@sableui/react"
+
+<ChatComposer onSend={(text) => send(text)} onAttach={pickFile} />
+```
+
+### Streaming, with a stop control
+
+```tsx
+import { ChatComposer } from "@sableui/react"
+
+<ChatComposer onSend={send} busy={isStreaming} onStop={stop} placeholder="Ask a follow-up…" />
+```
+
+### Controlled, with pending attachments
+
+```tsx
+import { Attachment, Button, ChatComposer, Icon } from "@sableui/react"
+
+<ChatComposer
+	value={draft}
+	onValueChange={setDraft}
+	onSend={(text) => { post(text, files); setDraft("") }}
+	onAttach={pickFile}
+	attachments={files.map((f) => (<Attachment key={f.id} variant="media" name={f.name} thumbnail={f.url} actions={<Button variant="floating" size="icon-xs" aria-label="Remove" onClick={() => drop(f.id)}><Icon name="xmark" /></Button>} />))}
+	footer={`${draft.length} / 4000`}
+	invalid={draft.length > 4000}
+/>
+```
+
+### A working chat, end to end
+
+```tsx
+import { Bubble, ChatComposer, Marker, Message, MessageScroller } from "@sableui/react"
+
+<div className="flex h-128 flex-col gap-3">
+	<MessageScroller className="flex-1 min-h-0">
+		{messages.map((m) => (<Message key={m.id} messageId={m.id} align={m.mine ? "end" : "start"}><Bubble variant={m.mine ? "primary" : "muted"} align={m.mine ? "end" : "start"}>{m.body}</Bubble></Message>))}
+		{streaming ? <Marker icon="spinner" spin shimmer>Thinking…</Marker> : null}
+	</MessageScroller>
+	<ChatComposer onSend={send} busy={streaming} onStop={stop} />
+</div>
+```

package/llms/components/checkbox-card.md

@@ -0,0 +1,98 @@
+# CheckboxCard
+
+**Status:** stable
+
+A multi-select selection card — a card-sized Base UI Checkbox with a checkbox box, title, and optional description. The checkbox twin of RadioCard (same tone table). CheckboxGroup lays a column out and can own the selection: give each card a `value` and the group holds the checked values as an array, with an optional parent "select all" Checkbox.
+
+**Keywords:** checkbox card, select card, multi select, option card
+
+## Usage
+
+Use CheckboxCard when an option needs more visual weight, supporting text, or iconography than a plain checkbox row.
+
+### Best practices
+
+- Do: Use it for a small number of options where details help users compare choices.
+- Do: Keep the checked state visible across the full card, not only inside the indicator.
+- Do: Let CheckboxGroup own the selection when the cards answer one question: give each card a `value` and read one array from `onValueChange` instead of wiring a toggle per card.
+- Do: Use a plain Checkbox with `parent` for "select all", and list every child value in the group's `allValues`. The group works out its checked and mixed states.
+- Don't: Do not use CheckboxCard for long lists; use Checkbox rows or a Combobox with `multiple` instead.
+- Don't: Do not put a link or a button inside the card. The whole card is the checkbox's label, so a nested interactive element is either unreachable or steals the click that should toggle it.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| CheckboxCard | yes | One card-shaped checkbox option. |
+| CheckboxGroup | no | A grouped set of related checkbox cards. Optionally owns the selected values and a parent "select all" checkbox. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| CheckboxGroup | { className?: string; children: ReactNode; value?: string[]; defaultValue?: string[]; onValueChange?: (value: string[]) => void; allValues?: string[]; disabled?: boolean } | Column wrapper (role=group) over Base UI's CheckboxGroup. With no group props it is layout only and each card stays independent. Pass value/defaultValue/onValueChange (string[]) and give each child a `value` to let the group own the selection — works for CheckboxCard and plain Checkbox children alike. Add allValues plus a `<Checkbox parent />` for a select-all box that turns mixed when only some are checked. `disabled` disables every child. onValueChange gets (value, eventDetails). Override the grid via className for multi-column layouts. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| onCheckedChange | (checked: boolean, eventDetails) => void | — | Fires with the next checked state (Base UI passes eventDetails second). Pair with `checked` for a controlled card; omit both to let it manage its own state. |
+| title | ReactNode | — | The card's primary label (text-title-sm). |
+| description | ReactNode | — | Optional supporting copy beneath the title (text-body-sm, muted). |
+| icon | ReactNode | — | Optional leading glyph (a solid <Icon>); takes the tone colour. |
+| tone | "neutral" \| "standard" \| "collectible" \| "edition" \| "info" \| "warning" | "neutral" | Semantic colour the checked state carries across the border, checkbox box, and icon. |
+| value | string | — | Names the card inside a group-owned CheckboxGroup: the card is checked when the group's value array includes it. Also the value submitted with a form. Inside a CheckboxGroup, `name` stands in for `value` when `value` is omitted. |
+| checked / onCheckedChange / defaultChecked / disabled | Base UI Checkbox.Root props | — | Standard checkbox state. Without a group-owned value, each card is independent — drive checked/onCheckedChange per item for multi-select. |
+
+## Variants
+
+- **tone**: neutral, standard, collectible, edition, info, warning
+
+## Tokens used
+
+`input`, `card`, `ring`, `primary`, `primary-foreground`, `accent`, `foreground`, `muted-foreground`, `tone-standard`, `tone-standard-foreground`, `tone-collectible`, `tone-collectible-foreground`, `tone-edition`, `tone-edition-foreground`, `tone-info`, `tone-info-foreground`, `tone-warning`, `tone-warning-foreground`
+
+## Accessibility
+
+- Base UI provides the checkbox role, aria-checked, hidden native input, keyboard toggle, and data-[checked]/data-disabled state.
+- The whole card is the hit target; focus draws a 2px outline outside the card (not a ring, so the checked tone ring survives focus); Space toggles the focused card.
+- Selection never relies on colour alone — the filled checkbox box + check mark and the card border all shift.
+- A parent select-all Checkbox gets aria-checked=mixed and aria-controls pointing at its children from Base UI; give it a visible label.
+
+## Related
+
+- Components: Checkbox, RadioCard
+
+## Examples
+
+### Group-owned selection
+
+```tsx
+import { CheckboxCard, CheckboxGroup } from "@sableui/react"
+
+<CheckboxGroup value={selected} onValueChange={setSelected}>{REASONS.map((r) => (<CheckboxCard key={r} value={r} title={r} />))}</CheckboxGroup>
+```
+
+### Select all
+
+```tsx
+import { Checkbox, CheckboxCard, CheckboxGroup, Field } from "@sableui/react"
+
+<CheckboxGroup allValues={REASONS} value={selected} onValueChange={setSelected}><Field label="All reasons" orientation="horizontal"><Checkbox parent /></Field>{REASONS.map((r) => (<CheckboxCard key={r} value={r} title={r} />))}</CheckboxGroup>
+```
+
+### A single independent card
+
+```tsx
+import { CheckboxCard } from "@sableui/react"
+
+<CheckboxCard title="Email me a receipt" description="Sent when the mint settles" checked={receipt} onCheckedChange={setReceipt} />
+```
+
+### Toned with description
+
+```tsx
+import { CheckboxCard } from "@sableui/react"
+
+<CheckboxCard tone="edition" title="Editions" description="Sell as numbered NFT editions" defaultChecked />
+```

package/llms/components/checkbox.md

@@ -0,0 +1,90 @@
+# Checkbox
+
+**Status:** stable
+
+Square toggle (18px at rest, on the spacing scale) over Base UI's Checkbox. Checked/indeterminate/disabled states; controlled or uncontrolled; form-ready via the hidden native input.
+
+**Keywords:** checkbox, boolean, multi select, form control
+
+## Usage
+
+Use Checkbox for independent boolean choices or for selecting multiple options in a set.
+
+### Best practices
+
+- Do: Use Checkbox when each option can be toggled independently.
+- Do: Attach a visible label that explains the consequence of checking the control.
+- Don't: Do not use Checkbox for mutually exclusive choices; use Radio or Select instead.
+- Don't: Do not use it without a label or an aria-label. An 18px square with no accessible name is announced as just "checkbox", which tells a screen-reader user nothing about what they are agreeing to.
+- Don't: Do not phrase the label as a negative, such as "Don't send read receipts". Paired with an unchecked box it becomes a double negative the reader has to solve before they can answer. Label the state being turned on.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| checked | boolean | — | Controlled checked state. Pair with onCheckedChange. Omit for uncontrolled. |
+| defaultChecked | boolean | false | Initial checked state for an uncontrolled checkbox. |
+| onCheckedChange | (checked: boolean, eventDetails) => void | — | Fires when the checkbox is ticked or unticked. Note: Base UI passes a second eventDetails arg — not the common (checked) => void, so a single-arg handler must widen its signature. |
+| indeterminate | boolean | false | Mixed state (neither checked nor unchecked). Renders a dash instead of the check. For a "select all" box inside a CheckboxGroup, use `parent` instead and the group sets this for you. |
+| parent | boolean | false | Makes this the "select all" box of a CheckboxGroup that has `allValues`. It checks or clears every child, and shows the dash when only some are checked. Only works inside a CheckboxGroup. |
+| disabled | boolean | false | Ignores user interaction and dims the control. |
+| name | string | — | Field name for the hidden input on form submit. |
+| value | string | — | Value submitted with the form when checked. Inside a group-owned CheckboxGroup, it is the name the group's value array uses for this checkbox. |
+| render | ReactElement \| (props, state) => ReactElement | — | Compose the root with another element through the Base UI render prop. |
+
+## Tokens used
+
+`card`, `input`, `primary`, `primary-foreground`, `ring`
+
+## Accessibility
+
+- Base UI renders a hidden native <input type=checkbox> for keyboard, focus, and form semantics.
+- Space toggles; focus-visible draws a 2px ring in the --ring token.
+- indeterminate sets aria-checked=mixed automatically; a `parent` checkbox in a CheckboxGroup gets aria-checked=mixed and aria-controls for its children from the group.
+- Label it with Field orientation="horizontal": it wires the label's htmlFor to the checkbox, so the label text joins the click target, and adds the description and error plumbing.
+
+## Related
+
+- Components: CheckboxCard, Switch, Radio
+
+## Examples
+
+### Default
+
+```tsx
+import { Checkbox } from "@sableui/react"
+
+<Checkbox defaultChecked />
+```
+
+### Controlled
+
+```tsx
+import { Checkbox } from "@sableui/react"
+
+<Checkbox checked={value} onCheckedChange={setValue} />
+```
+
+### Indeterminate
+
+```tsx
+import { Checkbox } from "@sableui/react"
+
+<Checkbox indeterminate />
+```
+
+### Select all in a group
+
+```tsx
+import { Checkbox, CheckboxGroup, Field } from "@sableui/react"
+
+<CheckboxGroup allValues={["email", "sms"]} defaultValue={["email"]} className="gap-3"><Field label="All channels" orientation="horizontal"><Checkbox parent /></Field><Field label="Email" orientation="horizontal" className="ps-7"><Checkbox value="email" /></Field><Field label="SMS" orientation="horizontal" className="ps-7"><Checkbox value="sms" /></Field></CheckboxGroup>
+```
+
+### With label
+
+```tsx
+import { Checkbox, Field } from "@sableui/react"
+
+<Field label="Remember me" orientation="horizontal"><Checkbox /></Field>
+```