@sableui/react 0.0.0-stage → 0.1.1

package/llms/components/radio.md

@@ -0,0 +1,86 @@
+# Radio
+
+**Status:** stable
+
+Single-select control over Base UI RadioGroup + Radio (roving focus, arrow-key nav, ARIA radiogroup wiring, form integration). RadioGroup + Radio.
+
+**Keywords:** radio, radio group, single choice, form control
+
+## Usage
+
+Use Radio when a user must choose exactly one option from a visible set.
+
+### Best practices
+
+- Do: Use it when all options should be visible for comparison.
+- Do: Keep option labels mutually exclusive and easy to understand.
+- Don't: Do not use Radio for independent toggles or multiple selection; use Checkbox or Switch.
+- Don't: Do not use a radio group with only one option, and do not omit the Fieldset. Without the fieldset the options share no accessible name, so a screen reader reads the choices with no question attached.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| RadioGroup | yes | The grouped set that manages one selected value. |
+| Radio | yes | One selectable option in the group. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| RadioGroup | Base UI RadioGroup props (value, defaultValue, onValueChange, name, disabled, readOnly, required) + className | The group container that wraps Radio items and shares selection state across them. Controlled via value + onValueChange; uncontrolled via defaultValue. Lays its Radio items out in a vertical stack. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Radio | Base UI Radio.Root props (value, disabled, readOnly, required) + className | — | A single radio button. value pairs it with the group's selected value. Renders a native button with radio semantics, the ring and an inner Indicator dot. A custom non-button render must also set nativeButton={false}. |
+
+## Tokens used
+
+`input`, `card`, `primary`, `ring`
+
+## Accessibility
+
+- Base UI provides the radiogroup/radio roles, aria-checked, hidden native inputs, and roving tabindex.
+- Arrow keys move and select between items; Space selects the focused item; Tab enters/leaves the group.
+- Checked state styling reads from the data-[checked] attribute; disabled items from the disabled state.
+- Focus-visible draws a 2px ring on the focused item. Wrap each Radio in <Field label orientation="horizontal"> so the label names it, is part of the hit target, sits on the first line, and dims with it when disabled — do not hand-build a <label> row.
+
+## Related
+
+- Components: Checkbox, RadioCard, Field, Fieldset, Select
+
+## Examples
+
+### Basic
+
+```tsx
+import { Field, Fieldset, FieldsetContent, FieldsetLegend, Radio, RadioGroup } from "@sableui/react"
+
+<Fieldset>
+	<FieldsetLegend>Post type</FieldsetLegend>
+	<FieldsetContent>
+		<RadioGroup defaultValue="standard">
+			<Field label="Standard" orientation="horizontal"><Radio value="standard" /></Field>
+			<Field label="Edition" orientation="horizontal"><Radio value="edition" /></Field>
+		</RadioGroup>
+	</FieldsetContent>
+</Fieldset>
+```
+
+### With a disabled option
+
+```tsx
+import { Field, Fieldset, FieldsetContent, FieldsetLegend, Radio, RadioGroup } from "@sableui/react"
+
+<Fieldset>
+	<FieldsetLegend>Post type</FieldsetLegend>
+	<FieldsetContent>
+		<RadioGroup defaultValue="standard">
+			<Field label="Standard" orientation="horizontal"><Radio value="standard" /></Field>
+			<Field label="Edition" orientation="horizontal" disabled><Radio value="edition" /></Field>
+		</RadioGroup>
+	</FieldsetContent>
+</Fieldset>
+```

package/llms/components/relative-time.md

@@ -0,0 +1,60 @@
+# RelativeTime
+
+**Status:** stable
+
+A human relative timestamp (e.g. "3 minutes ago") that reveals the full absolute date/time on hover or focus. Renders a native <time> element wrapped in our Tooltip; the absolute time is formatted with date-fns format(date, 'PPpp') (e.g. "Apr 29, 2025, 4:05:12 PM").
+
+**Keywords:** relative time, timestamp, time ago, date
+
+## Usage
+
+Use RelativeTime to show recent activity or timestamps in conversational relative language.
+
+### Best practices
+
+- Do: Use it for feeds, audit summaries, comments, and activity streams.
+- Do: Expose the exact timestamp when precision matters.
+- Don't: Do not use RelativeTime as the only date format for legal, billing, or audit-critical records.
+- Don't: Do not render it during SSR without a stable absolute fallback. "2 minutes ago" computed on the server differs from the client's value, which is a hydration mismatch — and it silently drifts as the page sits open.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| date | Date \| string \| number | — | The instant to render. Accepts a Date, an ISO/parseable string, or an epoch number (ms). Coerced to a Date for date-fns. |
+| className | string | — | Merged onto the <time> trigger element (the visible relative label). |
+| ...time props | Omit<ComponentPropsWithRef<"time">, "dateTime" \| "children"> | — | Remaining native <time> attributes pass through to the trigger. dateTime is set automatically from the parsed ISO value. |
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `ring`
+
+## Accessibility
+
+- Renders a semantic <time> element with a machine-readable dateTime (ISO) attribute.
+- The <time> carries tabIndex=0 (it is not focusable natively), so the absolute time — exposed via Base UI's Tooltip, which opens on keyboard focus as well as hover and wires aria-describedby — is reachable from the keyboard.
+- It inherits the type size of the surrounding text rather than setting its own, so it sits inside a meta row or message header without changing tier.
+- Wrap the page or a group in <TooltipProvider> to share open/close delays.
+- Relative phrasing is supplementary; the dateTime attribute remains the canonical machine value.
+
+## Related
+
+- Components: InlineStatus, Table
+
+## Examples
+
+### Basic
+
+```tsx
+import { RelativeTime, TooltipProvider } from "@sableui/react"
+
+<TooltipProvider><RelativeTime date={new Date()} /></TooltipProvider>
+```
+
+### From an ISO string
+
+```tsx
+import { RelativeTime, TooltipProvider } from "@sableui/react"
+
+<TooltipProvider><RelativeTime date="2025-04-29T16:05:12Z" /></TooltipProvider>
+```

package/llms/components/scroller.md

@@ -0,0 +1,88 @@
+# Scroller
+
+**Status:** stable
+
+Scroll container that fades its leading/trailing edges when content overflows. Tracks scroll position to toggle the fades.
+
+**Keywords:** scroller, overflow, horizontal scroll, carousel
+
+## Usage
+
+Use Scroller to create a contained overflow region for content that naturally extends beyond the viewport.
+
+### Best practices
+
+- Do: Use it for chip rows, media strips, or comparison sets where horizontal browsing is expected.
+- Do: Keep scroll affordances visible enough that overflow is discoverable.
+- Do: Put everything on `className` — sizing (`max-h-80`, `h-64`, `flex-1 min-h-0`) and chrome (`rounded-lg border`, `bg-card`) alike. It styles the Scroller's outer box, and the scrolling element inside it is `flex-1 min-h-0`, so a cap on the Scroller is still a cap on what scrolls.
+- Do: Pass `label` on any Scroller with real content. It is a focusable region, and an unnamed one announces as a bare group — "Tags" or "Recent covers" costs a word and is the difference between navigable and not.
+- Don't: Do not use Scroller to hide primary page layout or required controls.
+- Don't: Do not add your own wheel handler to make a horizontal strip mouse-scrollable — it already is. A second handler double-scrolls and usually loses the end-release, which traps the page.
+- Don't: Do not reach past it with a child selector (`[&>div]:snap-x`). The scrolling element is addressable by name: `viewportClassName`.
+- Don't: Do not use it to hide overflow you should have laid out. It exists to make an intentionally scrolling strip legible, not to contain content that overflowed by accident.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| orientation | "vertical" \| "horizontal" | "vertical" | "vertical" scrolls and fades top/bottom; "horizontal" scrolls and fades left/right. |
+| wheelScroll | boolean | true | On a horizontal Scroller, let a vertical mouse wheel scroll it sideways. Ignored when vertical. Turn it off only if the region is inside something that owns the wheel itself (a map, a canvas). |
+| label | string | — | Accessible name for the scroll region. The region takes focus, so it should say what it contains; without one a screen reader announces an unnamed group. |
+| viewportClassName | string | — | Classes for the inner element that actually scrolls. Narrow on purpose — `className` is what you want almost always. This is for the few utilities that only mean something on the scrolling box: `snap-x`, `scroll-smooth`, `scroll-p-*`. |
+| ...div props | ComponentPropsWithRef<'div'> | — | Everything except `className`/`style` spreads onto the SCROLLING element — `role`, `id`, `aria-*`, `data-*` and event handlers all describe the thing that scrolls, and CommandMenu relies on it to make this component its listbox. `ref` and `onScroll` likewise address the scroller, and compose with the component's own. |
+
+## Variants
+
+- **orientation**: vertical, horizontal
+- **wheelScroll**: true, false
+
+## Tokens used
+
+`ring`
+
+## Accessibility
+
+- The edge fades are a CSS mask-image on the scrolling element, not overlay elements — there is nothing in the DOM to intercept a pointer or be read by assistive tech, and the content under a fade stays fully interactive.
+- Two boxes: a chrome box carrying `className` (border, background, radius, sizing) and, inside it, the element that actually scrolls and carries the fade mask. They are split because a `mask-image` applies to its element's own border — so with both on one box, a bordered Scroller watched its frame dissolve at the scrolling edge. The axis is published as `data-orientation`, not `aria-orientation`, which is invalid on `role="group"`.
+- The scroll region uses native overflow and contains overscroll, so a gesture that runs out of content does not scroll the page behind it.
+- It is focusable (`tabIndex=0`, `role="group"`) and handles arrows, Home/End and PageUp/PageDown along its own axis. Chrome 128+ and Firefox make scrollable regions focusable on their own; Safari does not, so a strip with a hidden scrollbar and no focusable children is unreachable there. Declaring it makes the behaviour a property of the component, not of the reader's browser. Pass `label` to name it — an unnamed focusable region announces as a bare group.
+- On a horizontal Scroller, a vertical mouse wheel scrolls it sideways, because most mice have no horizontal wheel and the content past the fold is otherwise unreachable on them. The strip releases the wheel at both ends so it never traps the page, and leaves trackpad `deltaX` gestures and `shift+wheel` to the browser.
+- Cross-axis arrow keys are deliberately not captured, and a consumer can take the arrows entirely by calling `preventDefault()` in their own `onKeyDown` — a strip of interactive chips usually wants them for roving focus.
+
+## Related
+
+- Components: Carousel, Marquee
+
+## Examples
+
+### Vertical with overflow
+
+```tsx
+import { Scroller } from "@sableui/react"
+
+<Scroller label="Editions" className="h-64"><ul className="space-y-2 p-4">{items.map((item) => (<li key={item.id} className="text-body-sm">{item.title}</li>))}</ul></Scroller>
+```
+
+### Capped, scrolls past the cap
+
+```tsx
+import { Scroller } from "@sableui/react"
+
+<Scroller label="Versions" className="max-h-80 rounded-md border border-border"><ul className="divide-y divide-border">{versions.map((v) => (<li key={v.id} className="px-3 py-2 text-body-sm">{v.label}</li>))}</ul></Scroller>
+```
+
+### Horizontal
+
+```tsx
+import { Scroller } from "@sableui/react"
+
+<Scroller orientation="horizontal" label="Recent covers" className="w-full"><div className="flex gap-3 p-4">{covers.map((src) => (<img key={src} src={src} alt="" className="h-32 w-32 rounded-lg object-cover" />))}</div></Scroller>
+```
+
+### Snap points on the scrolling box
+
+```tsx
+import { Scroller } from "@sableui/react"
+
+<Scroller orientation="horizontal" label="Covers" className="w-full rounded-lg border border-border" viewportClassName="snap-x snap-mandatory scroll-smooth"><div className="flex gap-3 p-4">{covers.map((src) => (<img key={src} src={src} alt="" className="h-32 w-32 snap-start rounded-lg object-cover" />))}</div></Scroller>
+```

package/llms/components/scrub-field.md

@@ -0,0 +1,97 @@
+# ScrubField
+
+**Status:** stable
+
+The compact numeric field a property grid is built from: a leading glyph inside the field that doubles as a drag-to-scrub handle, the value, and an optional unit.
+
+**Keywords:** scrub, numeric, number, field, property, inspector, drag, workspace, tool, unit
+
+## Usage
+
+Use ScrubField for numeric properties in tool chrome — an inspector, a property grid, a panel. The leading icon or letter says what the number is and is also the thing you drag, which is why a value like opacity needs no slider. Reach for NumberField instead in page-register forms: it has steppers and locale formatting, and it renders at page-register height. Those two steppers put a ~112px floor on a control that needs to be about 44px in a property grid, which is why ScrubField exists rather than a NumberField size variant. The input is sized in ch, so each field is as wide as its longest value and a grid of them lines up without per-field tuning.
+
+### Best practices
+
+- Do: Give the field an icon or prefix when it stands alone, so the row has a drag affordance and the value has an identity.
+- Do: Pass the unit as `suffix` rather than baking it into the label — it renders against the number the way reference tools show 100%.
+- Do: Bracket undo with onGestureStart/onGestureEnd. A scrub fires per frame, so without it one undo rewinds a single pixel of the drag.
+- Do: Set `step` to the real precision (0.01 for a normalised threshold). Display precision follows it, so a seed shows 1234 and never 1,234.
+- Don't: Add a separate drag gripper beside the glyph. The icon or prefix already is the scrub handle; a second one is the same affordance twice and costs width a 240px panel does not have.
+- Don't: Pair it with a Slider AND give it a glyph. The slider is already the drag affordance; two on one row is the same gesture twice. Omit icon/prefix when there's a slider.
+- Don't: Use it in a page form. It is chrome-sized and has no label, description, or error slots — that's Field plus Input or NumberField.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | number | — | The current value (controlled). |
+| onValueChange | (next: number) => void | — | Fires on commit, arrow-key step, and every frame of a scrub. |
+| min | number | — | Lower clamp, applied to typing and scrubbing. |
+| max | number | — | Upper clamp, applied to typing and scrubbing. |
+| step | number | 1 | Arrow-key and scrub increment, and the source of display precision. Shift multiplies arrows by 10 and divides scrubbing by 10. |
+| label | string | — | Accessible name for the input. Required — the visible glyph is decorative. |
+| icon | string | — | Semantic icon name rendered inside the field; doubles as the scrub handle. Any name the app's IconProvider resolves works — image tools typically supply their own checkerboard glyph for opacity, which is a domain icon rather than one Sable's contract carries. |
+| prefix | ReactNode | — | Short text used instead of an icon (e.g. "X" / "Y"), with the same scrub role. |
+| suffix | ReactNode | — | Unit rendered after the value inside the field (e.g. "%", "px"). |
+| onGestureStart | () => void | — | Fires once when a scrub drag begins — open an undo transaction here, and drop expensive downstream work (e.g. a GPU renderer) to a cheap preview quality; without it a pipeline re-renders at full quality on every pointer move and the drag stutters. |
+| onGestureEnd | () => void | — | Fires when a scrub drag ends — close the undo transaction here and restore full render quality. |
+| disabled | boolean | — | Disables typing and scrubbing. |
+| id | string | — | Input id, for a PropertyRow's htmlFor. |
+
+## Tokens used
+
+`foreground`, `muted-foreground`, `ring`, `canvas`, `panel-raised`
+
+## Accessibility
+
+- The input carries the accessible name via `label`; the glyph is aria-hidden because it is decorative.
+- Every scrub gesture is reachable from the keyboard: ArrowUp/ArrowDown step by `step`, Shift+Arrow by ten steps.
+- Enter commits, Escape reverts to the last committed value, and blur commits — so a partial edit is never silently kept.
+
+## Related
+
+- Components: NumberField, Slider, PanelSection, Workspace, Input
+
+## Examples
+
+### Opacity with a glyph handle
+
+```tsx
+import { ScrubField } from "@sableui/react"
+
+<ScrubField label="Opacity" icon="grid" suffix="%" value={60} min={0} max={100} onValueChange={(v) => setOpacity(v)} />
+```
+
+### X/Y offset pair (PropertyPair puts two fields on one scan line)
+
+```tsx
+import { PropertyPair, ScrubField } from "@sableui/react"
+
+<PropertyPair labels={["Offset X", "Offset Y"]}>
+  <ScrubField label="Offset X" prefix="X" value={x} min={-128} max={128} onValueChange={setX} />
+  <ScrubField label="Offset Y" prefix="Y" value={y} min={-128} max={128} onValueChange={setY} />
+</PropertyPair>
+```
+
+### No glyph — the property name is the handle
+
+```tsx
+import { PropertyRow, ScrubField } from "@sableui/react"
+
+<PropertyRow label="Block size" scrub={{ value: size, onValueChange: setSize, min: 2, max: 256 }}>
+  <ScrubField label="Block size" value={size} min={2} max={256} suffix="px" onValueChange={setSize} />
+</PropertyRow>
+```
+
+### Paired with a slider (no glyph — one drag affordance per row)
+
+```tsx
+import { PropertyRow, ScrubField, Slider } from "@sableui/react"
+
+<PropertyRow label="Block size" stacked>
+  <div className="flex items-center gap-2">
+    <Slider value={32} min={4} max={256} className="min-w-0 flex-1" />
+    <ScrubField label="Block size" value={32} min={4} max={256} step={1} suffix="px" className="w-16 shrink-0" onValueChange={(v) => setBlockSize(v)} />
+  </div>
+</PropertyRow>
+```

package/llms/components/search-input.md

@@ -0,0 +1,84 @@
+# SearchInput
+
+**Status:** stable
+
+Styled search field with a leading magnifier and a clearable X. Soft-square (rounded-sm), card surface, 2px focus ring; the clear button appears only when there is a value.
+
+**Keywords:** search, input, filter, query
+
+## Usage
+
+Use SearchInput for text queries that filter or search a known content set.
+
+### Best practices
+
+- Do: Use a clear placeholder that names the content being searched.
+- Do: Provide a visible clear affordance when query state persists.
+- Do: When a button stands in for search (a header trigger that opens CommandMenu with ⌘K), use CommandMenuTrigger. It wears this field's shell from the same source, so the two cannot drift; a hand-styled button already did once, into a borderless chip that matched neither the field nor a button.
+- Don't: Do not use SearchInput as a command palette; use CommandMenu for global commands, opened from the header by CommandMenuTrigger. A SearchInput that opens a dialog on focus is a text box you cannot type in.
+- Don't: Do not search on every keystroke against an expensive backend without debouncing. The user sees results flicker and reorder under them, and you send a request per character.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| value | string | — | Controlled value of the search field. |
+| defaultValue | string | — | Uncontrolled initial value. The field tracks its own text, so the clear button still appears and empties it. |
+| className | string | — | Sizes and places the whole field — magnifier, input and clear button together (e.g. max-w-80). A width cap here keeps the clear button inside the field. |
+| inputClassName | string | — | Classes for the <input> element alone, for the rare input-only override. |
+| onValueChange | (value: string) => void | — | Called with the next string on every keystroke. |
+| onClear | () => void | — | Called when the clear button is pressed. The component also fires onValueChange('') so a controlled value resets. |
+| placeholder | string | "Search" | Placeholder text shown when the field is empty. |
+| disabled | boolean | false | Dims the control and blocks pointer interaction. |
+| ...props | ComponentPropsWithRef<"input"> | — | All native input attributes (name, autoFocus, ref, aria-invalid, …) pass through to the <input> except value/onChange, which are owned by value/onValueChange, and className, which sizes the whole field. |
+
+## Tokens used
+
+`input`, `card`, `foreground`, `muted-foreground`, `ring`, `destructive`
+
+## Accessibility
+
+- Renders a native <input type="search"> — keyboard and form semantics come for free.
+- Associate a <label htmlFor> (or wrap) — the magnifier glyph is decorative, not a label.
+- The leading search Icon is pointer-events-none and purely decorative.
+- The clear button is a real <button> (Sable's ghost icon Button) with aria-label='Clear search' and a focus-visible ring. It is hidden while the field is disabled.
+- Focus-visible draws a 2px ring in the --ring token; aria-invalid raises the destructive border and ring.
+
+## Related
+
+- Components: Input, CommandMenu, Combobox
+
+## Examples
+
+### Controlled
+
+```tsx
+import { SearchInput } from "@sableui/react"
+
+const [q, setQ] = useState("")
+<SearchInput value={q} onValueChange={setQ} placeholder="Search posts" />
+```
+
+### With onClear
+
+```tsx
+import { SearchInput } from "@sableui/react"
+
+<SearchInput value={q} onValueChange={setQ} onClear={() => console.log("cleared")} />
+```
+
+### Uncontrolled, sized as a whole
+
+```tsx
+import { Field, SearchInput } from "@sableui/react"
+
+<Field label="Search posts"><SearchInput defaultValue="editions" className="max-w-80" /></Field>
+```
+
+### Disabled
+
+```tsx
+import { SearchInput } from "@sableui/react"
+
+<SearchInput disabled placeholder="Search" />
+```

package/llms/components/select.md

@@ -0,0 +1,106 @@
+# Select
+
+**Status:** stable
+
+Listbox over Base UI Select — typeahead, roving focus, collision-aware popup, ARIA option wiring, and form integration. Trigger shows the selected value; the popup portals to <body>.
+
+**Keywords:** select, listbox, dropdown, picker, option, choice, typeahead, form
+
+## Usage
+
+Use Select when users choose one value from a known, finite set. Use Combobox for searchable or user-entered values, Combobox `multiple` for several choices, and Radio when all options should remain visible.
+
+### Best practices
+
+- Do: Use clear item labels and pass label explicitly when children are richer than plain text.
+- Do: Group long option sets with SelectGroup and SelectGroupLabel when categories improve scanning.
+- Do: Wrap in Field when the select belongs to a form so label, helper text, and errors are wired automatically.
+- Do: Leave the trigger's type alone on mobile. Below the sm breakpoint the md trigger renders text-body-lg (17px) so it matches the Input and Textarea beside it, which carry that tier because iOS Safari zooms the page when a focused field computes under 16px. A custom field in the same row should follow: a second paired tier under a max-sm: variant, never a hand-set font-size.
+- Do: Inside a <Workspace> a Select adapts automatically — trigger and popup both pick up the compact density, including across the portal. Do NOT hand-size it per call site; that was necessary before v0.41 and is now drift.
+- Don't: Use Select for very large or fuzzy lists. Use Combobox when typing is the primary way to find an option.
+- Don't: Use Select for binary on/off settings. Use Switch or Checkbox instead.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Root | yes | Owns value, open state, form integration, and item collection. |
+| Trigger | yes | The button that shows the selected value and opens the listbox. |
+| Content | yes | The positioned popup containing options and optional groups. |
+| Item | yes | A selectable option with selected and highlighted states. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SelectTrigger | Base UI Trigger props + placeholder?: ReactNode + size?: "md" \| "xs" + className | The button. Composes Trigger + Value + a chevron Icon that flips on open (data-[popup-open]). `size="xs"` is the property-grid rung — height, padding, radius AND surface move together, which is why it is a prop and not a className: the xs trigger is an inset `bg-canvas` field with no border, matching ScrubField on the same row. A consumer overriding only the height gets an md-register 8px radius on a 24px box and a raised card sitting among inset fields; one inspector panel had eleven of those, and both tells are visible at a glance. |
+| SelectContent | Base UI Popup props + side, align, sideOffset + className | Portal + Positioner + Popup + List. side="bottom", align="start", sideOffset=6 by default; matches trigger width. |
+| SelectItem | { value: string; disabled?: boolean; label?: string } + className | An option. Composes Item + ItemText + a check ItemIndicator for the selected row. String children double as the item's `label`, so the closed trigger shows the display text — pass `label` explicitly only when children are richer than a string. |
+| SelectGroup | Base UI Group props + className | Optional grouping of related options. |
+| SelectGroupLabel | Base UI GroupLabel props + className | The heading associated with a SelectGroup for screen readers. |
+| SelectValue | Base UI Value props (children render fn) + placeholder | Renders the selected option's label with a placeholder fallback. Already composed inside SelectTrigger; exported for advanced layouts that render the value outside the default trigger. |
+| SelectSeparator | Base UI Separator props + className | A thin themed divider between groups of items. Decorative — Base UI marks it aria-hidden. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| items | Record<string, ReactNode> \| { value: string; label: ReactNode }[] | — | value → label map (a record, or an array of { value, label }). Derived automatically from literal SelectItem children; pass it explicitly when the items are generated in a loop, or a closed trigger renders the raw value instead of the label. |
+| Select (Root) | Base UI Select.Root props (value, defaultValue, onValueChange, open, defaultOpen, onOpenChange, disabled, required, name, multiple, items) | — | Controls the selected value and open state. Uncontrolled by default. When `items` isn't passed, it is derived from the SelectItem children so the closed trigger shows display text instead of the raw value; pass `items` explicitly when item children aren't plain strings. |
+
+## Tokens used
+
+`input`, `card`, `foreground`, `ring`, `border`, `popover`, `popover-foreground`, `accent`, `accent-foreground`, `muted-foreground`
+
+## Motion
+
+- **arrival** · SelectContent · `motion-pop` — The popup's transform-origin follows Base UI's anchor, so it grows out of the trigger it belongs to. On a dense form with several selects in a column, that origin is the only thing identifying which field the open list is for.
+- **response** · SelectItem · `motion-interactive` — Highlight follows both pointer and keyboard. Easing it means arrow-keying down a list is continuous motion rather than a background teleporting between rows, which is what makes a long list readable while moving.
+- **transition** · SelectContent · `motion-pop` — Closing collapses back toward the trigger, so the reader's eye is returned to the field that now holds the value they just picked.
+- **activity** · SelectContent · _no motion_ — Select takes a resident list of options. Anything that has to be fetched or filtered as you type is Combobox, which owns that state.
+
+## Accessibility
+
+- Base UI provides listbox/option roles, aria-expanded, typeahead, roving focus, and a hidden form input.
+- Esc and click-outside dismiss; arrow keys and Home/End navigate the list.
+- Selected option carries data-[selected]; the highlighted option carries data-[highlighted].
+- Animate the popup via data-[starting-style] / data-[ending-style].
+
+## Related
+
+- Components: Combobox, Radio, Field, Input
+- Patterns: SettingsPage, AuthPage
+
+## Examples
+
+### Basic (controlled)
+
+```tsx
+import { Select, SelectContent, SelectItem, SelectTrigger } from "@sableui/react"
+
+<Select value={value} onValueChange={setValue}><SelectTrigger placeholder="Choose a font" /><SelectContent><SelectItem value="sans">Sans-serif</SelectItem><SelectItem value="serif">Serif</SelectItem><SelectItem value="mono">Monospace</SelectItem></SelectContent></Select>
+```
+
+### Grouped
+
+```tsx
+import { SelectContent, SelectGroup, SelectGroupLabel, SelectItem } from "@sableui/react"
+
+<SelectContent><SelectGroup><SelectGroupLabel>Weights</SelectGroupLabel><SelectItem value="regular">Regular</SelectItem><SelectItem value="bold">Bold</SelectItem></SelectGroup></SelectContent>
+```
+
+### Inside Field
+
+```tsx
+import { Field, Select, SelectContent, SelectItem, SelectTrigger } from "@sableui/react"
+
+<Field label="Default visibility" description="Controls how new editions appear."><Select defaultValue="public"><SelectTrigger placeholder="Choose visibility" /><SelectContent><SelectItem value="public">Public</SelectItem><SelectItem value="private">Private</SelectItem><SelectItem value="unlisted">Unlisted</SelectItem></SelectContent></Select></Field>
+```
+
+### Rich item labels
+
+```tsx
+import { Badge, Select, SelectContent, SelectItem, SelectTrigger } from "@sableui/react"
+
+<Select defaultValue="edition" items={[{ value: "edition", label: "Edition" }, { value: "collectible", label: "Collectible" }]}><SelectTrigger /><SelectContent><SelectItem value="edition" label="Edition"><span className="flex items-center gap-2"><Badge tone="edition">Edition</Badge><span>Edition drop</span></span></SelectItem><SelectItem value="collectible" label="Collectible"><span className="flex items-center gap-2"><Badge tone="collectible">Collectible</Badge><span>Collectible</span></span></SelectItem></SelectContent></Select>
+```

package/llms/components/separator.md

@@ -0,0 +1,70 @@
+# Separator
+
+**Status:** stable
+
+A hairline divider. Horizontal full-width rule or vertical 1px column, tinted with the border token. Optional centered label (horizontal) for a captioned section divider.
+
+**Keywords:** separator, divider, section break, rule
+
+## Usage
+
+Use Separator to divide related groups where spacing alone does not provide enough structure.
+
+### Best practices
+
+- Do: Use it sparingly between sections, menu groups, or dense rows.
+- Do: Choose orientation based on the layout direction it separates.
+- Don't: Do not use Separator as decoration when hierarchy, spacing, or headings would explain the layout better.
+- Don't: Do not use it where space would do. A page whose every section is divided by a rule reads as a form; the rule should mark a real change of subject.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| orientation | "horizontal" \| "vertical" | "horizontal" | Axis of the rule. Vertical stretches to its flex parent's height. |
+| label | ReactNode | — | When set (horizontal only), centers a muted caption between two hairline rules. |
+| render | ReactElement \| (props, state) => ReactElement | — | Compose with another element/component through the Base UI render prop. Ignored on the labeled variant. |
+
+## Variants
+
+- **orientation**: horizontal, vertical
+
+## Tokens used
+
+`border`, `muted-foreground`
+
+## Accessibility
+
+- Base UI sets role=separator and aria-orientation for assistive tech.
+- The labeled variant renders a div with explicit role=separator + aria-orientation (the caption is the visible context).
+- Purely decorative dividers can carry aria-hidden when adjacent content already conveys the grouping.
+
+## Related
+
+- Components: Menu, ContextMenu, Card
+
+## Examples
+
+### Horizontal
+
+```tsx
+import { Separator } from "@sableui/react"
+
+<Separator />
+```
+
+### Labeled section divider
+
+```tsx
+import { Separator } from "@sableui/react"
+
+<Separator label="Other holdings" />
+```
+
+### Vertical (inside a flex row)
+
+```tsx
+import { Row, Separator } from "@sableui/react"
+
+<Row gap={3} className="h-6 items-center"><span>Edit</span><Separator orientation="vertical" /><span>Delete</span></Row>
+```