@sableui/react 0.0.0-stage → 0.1.0

package/llms/components/settings-menu.md

@@ -0,0 +1,139 @@
+# SettingsMenu
+
+**Status:** stable
+
+A compact trigger that states the current settings, over a menu of rows that change them. Each row shows its own value and opens a submenu.
+
+**Keywords:** settings, model picker, model switcher, options menu, preferences, submenu, quality settings, ai chat
+
+## Usage
+
+For a cluster of related settings that a reader checks often and changes occasionally — the model and effort on an AI composer, quality and format on an export control, density and sort on a table. It encodes one shape: summarise the state on the trigger, then open to a list of name → current value → submenu. It knows nothing about any particular domain; the AI-model case is one instance of it.
+
+### Best practices
+
+- Do: Put the current values in `summary`, not a noun. "5.6 Sol High" tells the reader where they are; a trigger reading "Settings" makes them open it to find out, which is the wrong trade for a control glanced at twenty times a session.
+- Do: Give every SettingsRow a `value`. One glance at the open menu should answer every setting at once — a menu of bare names is a menu you have to explore.
+- Do: Use `MenuRadioGroup` + `MenuRadioItem` inside a row for single-choice settings, so the current option is checked rather than merely remembered.
+- Do: Reach for `variant="subtle"` when the trigger sits on a surface where a ghost control would float unanchored — inside a ChatComposer, for instance.
+- Don't: Do not use it for a single setting. One choice is a `Select`; the nesting only earns its cost when there are several related settings to summarise.
+- Don't: Do not put actions in it. Rows change state; a menu that mixes "Effort ›" with "Delete conversation" makes destructive commands look like preferences. That is `Menu` or `DotsMenu`.
+- Don't: Do not nest more than one level deep. Past that the reader loses the path back, and the thing you have is a settings dialog wearing a menu.
+- Don't: Do not override the upward, end-aligned default without reason. Its home is the bottom of a composer or toolbar, where a downward menu opens off-screen.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Trigger | yes | The summary control. States the current settings and carries a chevron; quiet at rest, so it does not compete with the primary action beside it. |
+| SettingsRow | yes | One setting: its name, its current value, and a submenu of options. Without children it renders flat, for a row that is a statement rather than a choice. |
+| Submenu contents | no | Usually a MenuRadioGroup of MenuRadioItems, so the active option is checked. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SettingsRow | { label: ReactNode; value?: ReactNode; disabled?: boolean; children?: ReactNode } | One setting. With children it opens a submenu; without them it renders as a flat statement row. |
+| MenuRadioGroup | { value?: string; defaultValue?: string; onValueChange?: (value: string) => void } | Single-choice group for a row's submenu. Exported from Menu; re-used here rather than duplicated. |
+| MenuRadioItem | { value: string; disabled?: boolean } | One option, with a check in a reserved leading column so labels do not shift as the highlight moves. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| summary | ReactNode | — | What the trigger reads when closed. Give it the current values, not a noun — the control should answer before it is opened. |
+| label | string | "Change settings" | Accessible name for the trigger, since the visible summary is data rather than a label. |
+| variant | "ghost" \| "subtle" | "ghost" | Resting treatment. `ghost` disappears into the surface at rest and shows its affordance on hover — right for a toolbar. `subtle` adds a fill for surfaces where a ghost trigger would float unanchored. |
+| size | "xs" \| "sm" | "sm" | Trigger height, read off the density ladder so a compact scope retunes it with every other control. |
+| side | "top" \| "bottom" \| "inline-start" \| "inline-end" | "top" | Which side the menu opens on. Upward by default — its home is the bottom of a composer. |
+| align | "start" \| "center" \| "end" | "end" | Alignment along that side. |
+| disabled | boolean | — | Disable the trigger. |
+| ...Menu props | Omit<ComponentProps<typeof Menu>, 'children'> | — | `open` / `defaultOpen` / `onOpenChange` and the rest of Base UI's menu root props. |
+
+## Variants
+
+- **variant**: ghost, subtle
+- **size**: xs, sm
+
+## Tokens used
+
+`foreground`, `muted`, `muted-foreground`, `accent`, `accent-foreground`, `popover`, `popover-foreground`, `border`, `ring`
+
+## Accessibility
+
+- Base UI's Menu underneath, so roving focus, typeahead, Esc and outside-dismissal, and the full menu/menuitemradio ARIA wiring come for free — including submenu traversal with the arrow keys.
+- The trigger carries an explicit `label`, because its visible text is the current state rather than a name: without it, a screen reader announces "5.6 Sol High" with no indication that it is a control or what it changes.
+- Radio rows are `menuitemradio` with a real checked state, so the current choice is conveyed to assistive tech rather than only by a visible tick.
+- The check occupies a reserved column instead of appearing on selection, so labels never shift sideways as the highlight moves — a change that reads as motion to anyone tracking position.
+- Submenus open on the inline-end side, which flips correctly in RTL rather than always opening right.
+
+## Related
+
+- Components: Menu, DotsMenu, Select, ChatComposer, Popover
+- Patterns: ChatPanel
+
+## Examples
+
+### A model switcher in a composer
+
+```tsx
+import { ChatComposer, MenuRadioGroup, MenuRadioItem, SettingsMenu, SettingsRow } from "@sableui/react"
+
+<ChatComposer
+	onSend={send}
+	actions={
+		<SettingsMenu variant="subtle" size="xs" summary={<><span className="text-foreground">{model.name}</span>{" "}<span className="text-muted-foreground">{effort}</span></>}>
+			<SettingsRow label="Model" value={model.name}>
+				<MenuRadioGroup value={model.id} onValueChange={setModelId}>
+					<MenuRadioItem value="sol">5.6 Sol</MenuRadioItem>
+					<MenuRadioItem value="lite">5.6 Lite</MenuRadioItem>
+				</MenuRadioGroup>
+			</SettingsRow>
+			<SettingsRow label="Effort" value={effort}>
+				<MenuRadioGroup value={effort} onValueChange={setEffort}>
+					<MenuRadioItem value="Low">Low</MenuRadioItem>
+					<MenuRadioItem value="High">High</MenuRadioItem>
+				</MenuRadioGroup>
+			</SettingsRow>
+		</SettingsMenu>
+	}
+/>
+```
+
+### Export options — the same shape, no chat involved
+
+```tsx
+import { MenuRadioGroup, MenuRadioItem, SettingsMenu, SettingsRow } from "@sableui/react"
+
+<SettingsMenu summary={`${format} · ${quality}`} side="bottom" align="start">
+	<SettingsRow label="Format" value={format}>
+		<MenuRadioGroup value={format} onValueChange={setFormat}>
+			<MenuRadioItem value="PNG">PNG</MenuRadioItem>
+			<MenuRadioItem value="SVG">SVG</MenuRadioItem>
+		</MenuRadioGroup>
+	</SettingsRow>
+	<SettingsRow label="Quality" value={quality}>
+		<MenuRadioGroup value={quality} onValueChange={setQuality}>
+			<MenuRadioItem value="Draft">Draft</MenuRadioItem>
+			<MenuRadioItem value="Final">Final</MenuRadioItem>
+		</MenuRadioGroup>
+	</SettingsRow>
+</SettingsMenu>
+```
+
+### A flat row for a setting with nothing to choose
+
+```tsx
+import { MenuRadioGroup, MenuRadioItem, MenuSeparator, SettingsMenu, SettingsRow } from "@sableui/react"
+
+<SettingsMenu summary="Standard">
+	<SettingsRow label="Speed" value="Standard">
+		<MenuRadioGroup value="standard">
+			<MenuRadioItem value="standard">Standard</MenuRadioItem>
+			<MenuRadioItem value="priority">Priority</MenuRadioItem>
+		</MenuRadioGroup>
+	</SettingsRow>
+	<MenuSeparator />
+	<SettingsRow label="Plan" value="Team" />
+</SettingsMenu>
+```

package/llms/components/sheet.md

@@ -0,0 +1,97 @@
+# Sheet
+
+**Status:** stable
+
+Edge-anchored drawer over Base UI Drawer — focus trap, scroll lock, Esc/outside dismissal, portal backdrop, plus swipe-to-dismiss on touch. Slides in from a viewport edge via side and swipes back out toward the same edge.
+
+**Keywords:** sheet, drawer, side panel, overlay, swipe to dismiss
+
+## Usage
+
+Use Sheet for secondary workflows that slide in while preserving context from the underlying page.
+
+### Best practices
+
+- Do: Use it for inspect, edit, filter, or create flows that relate to the current page.
+- Do: Include clear title, close path, and footer actions for task-oriented sheets.
+- Don't: Do not use Sheet for simple confirmations or deeply nested workflows.
+- Don't: Do not use it on desktop where a Dialog fits. A sheet's affordance is edge-anchored travel for thumb reach; on a wide viewport it becomes a dialog that arrives from the wrong place.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| SheetTrigger | no | The element that opens the sheet. |
+| SheetContent | yes | The sliding panel content. |
+| SheetClose | no | An explicit close control. |
+| SheetHeader | no | The title and description region. |
+| SheetTitle | no | The sheet heading. |
+| SheetDescription | no | Supporting context for the sheet. |
+| SheetFooter | no | Footer actions for the workflow. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SheetContent | Base UI Drawer.Popup props (initialFocus, finalFocus, …) + side: "right" \| "left" \| "top" \| "bottom" + className | Backdrop + edge-anchored popup; portals to <body>. side picks which viewport edge the sheet anchors to and slides in from (defaults to "right"). Left/right are full-height side panels; top/bottom span the width up to 80vh. On touch it swipes closed toward that same edge (right swipes right, left swipes left, top swipes up, bottom swipes down). |
+| SheetTrigger | Base UI Drawer.Trigger props (render) | Element that opens the sheet. Compose via render prop. |
+| SheetClose | Base UI Drawer.Close props (render) | Element that dismisses the sheet. Compose via render prop. |
+| SheetHeader | ComponentProps<"div"> | Top section holding SheetTitle/SheetDescription. |
+| SheetTitle | Base UI Drawer.Title props + className | The sheet's accessible name — wires aria-labelledby on the popup. |
+| SheetDescription | Base UI Drawer.Description props + className | Muted supporting line; wires aria-describedby. |
+| SheetFooter | ComponentProps<"div"> | Bottom row for actions, pinned after the scrollable body. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| Sheet (Root) | Base UI Drawer.Root props (open, defaultOpen, onOpenChange, onOpenChangeComplete, modal, disablePointerDismissal, actionsRef, handle) — minus swipeDirection and snap points | — | Controls open state. Uncontrolled by default. The dismiss swipe direction is not a prop: it follows SheetContent's side. onOpenChange reports reason "swipe" when a swipe closed it. |
+
+## Variants
+
+- **side**: right, left, top, bottom
+
+## Tokens used
+
+`popover`, `popover-foreground`, `border`, `muted-foreground`
+
+## Accessibility
+
+- Base UI provides focus trapping, scroll lock, aria-modal, and labelled-by wiring (SheetTitle).
+- The panel scrolls its own content (thin scrollbar, contained overscroll) when it outgrows its bound — the full height on left/right, 80vh on top/bottom.
+- Esc and click-outside dismiss by default; on touch, a swipe toward the sheet's own edge dismisses too. A short or slow drag springs back.
+- Swipe is an extra path, never the only one: Esc, click-outside and SheetClose all still work.
+- Focus matches Dialog: the first tabbable on mouse/keyboard open, the panel itself on touch (so the virtual keyboard stays down); focus returns to the trigger on close.
+- Render a SheetClose inside SheetContent so screen-reader users can escape the popup.
+- Slide animation runs via data-[starting-style]/data-[ending-style] attributes on the motion-duration token; while swiping the panel tracks the finger directly, and a released swipe finishes on the same token (scaled by flick speed), so reduced motion makes it instant.
+- A mouse drag that starts on sheet content selects text rather than dragging the panel; mouse dragging only starts from the padding edge.
+
+## Related
+
+- Components: Dialog, Popover, Sidebar
+
+## Examples
+
+### Basic (right)
+
+```tsx
+import { Button, Sheet, SheetClose, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from "@sableui/react"
+
+<Sheet><SheetTrigger render={<Button>Open</Button>} /><SheetContent><SheetHeader><SheetTitle>Filters</SheetTitle><SheetDescription>Narrow the feed.</SheetDescription></SheetHeader><SheetFooter><SheetClose render={<Button variant="secondary">Cancel</Button>} /><SheetClose render={<Button>Apply</Button>} /></SheetFooter></SheetContent></Sheet>
+```
+
+### Left side
+
+```tsx
+import { Button, Sheet, SheetClose, SheetContent, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from "@sableui/react"
+
+<Sheet><SheetTrigger render={<Button variant="secondary">Menu</Button>} /><SheetContent side="left"><SheetHeader><SheetTitle>Navigation</SheetTitle></SheetHeader><SheetFooter><SheetClose render={<Button variant="secondary">Close</Button>} /></SheetFooter></SheetContent></Sheet>
+```
+
+### Bottom side
+
+```tsx
+import { Button, Sheet, SheetClose, SheetContent, SheetFooter, SheetHeader, SheetTitle, SheetTrigger } from "@sableui/react"
+
+<Sheet><SheetTrigger render={<Button variant="secondary">Details</Button>} /><SheetContent side="bottom"><SheetHeader><SheetTitle>Edition details</SheetTitle></SheetHeader><SheetFooter><SheetClose render={<Button variant="secondary">Close</Button>} /></SheetFooter></SheetContent></Sheet>
+```

package/llms/components/show-more.md

@@ -0,0 +1,59 @@
+# ShowMore
+
+**Status:** stable
+
+Collapsible content region that clips children to a collapsed height, fades the cut edge, and reveals the rest with a toggle.
+
+**Keywords:** show more, disclosure, truncate, expand
+
+## Usage
+
+Use ShowMore to reveal additional content after an intentionally shortened preview.
+
+### Best practices
+
+- Do: Use it when the preview is useful on its own and the rest is optional.
+- Do: Make the expanded state reversible when collapsing helps users regain context.
+- Don't: Do not place it on a card or tinted surface without checking the fade. The cut-edge gradient fades to the page background color, so on any other surface it reads as a visible band.
+- Don't: Do not hide required steps, important warnings, or primary actions behind ShowMore.
+- Don't: Do not use it to hide content search engines or screen readers need. Collapsed content is still in the DOM here, but if the user must read it to act, it should not be behind a toggle.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| collapsedHeight | number | 96 | Collapsed height of the content region in px. The inner wrapper clips to this height until expanded. The toggle and fade only appear when the measured content is taller than this; content that already fits shows in full with no control. Expanding animates to the measured height. |
+| collapsedLines | number | — | Collapsed height as a count of the content's own lines (measured from its line height). Wins over collapsedHeight, and is the one to prefer: the preview keeps the same number of lines when the type scale or density changes, where a px height shows fewer as type grows. |
+| children | ReactNode | — | The content to collapse and reveal. |
+
+## Tokens used
+
+`background`, `foreground`, `ring`
+
+## Accessibility
+
+- The toggle is a real <button> with aria-expanded reflecting the open state.
+- The fade overlay is pointer-events-none and decorative; it never traps clicks.
+- Collapsed content stays in the DOM, so screen readers can still reach it.
+
+## Related
+
+- Components: Collapsible
+
+## Examples
+
+### Long paragraph
+
+```tsx
+import { ShowMore } from "@sableui/react"
+
+<ShowMore><p className="text-body-md text-foreground">A long paragraph that exceeds the collapsed height…</p></ShowMore>
+```
+
+### Collapsed to a line count
+
+```tsx
+import { ShowMore } from "@sableui/react"
+
+<ShowMore collapsedLines={6}><p className="text-body-md text-foreground">{post.description}</p></ShowMore>
+```

package/llms/components/side-nav.md

@@ -0,0 +1,106 @@
+# SideNav
+
+**Status:** stable
+
+A lightweight in-content vertical navigation list - the settings / docs sub-nav, distinct from the app-chrome Sidebar. Router-agnostic items, optional SideNavGroup sections, and an explicit active-state vocabulary for content rails or sidebar chrome.
+
+**Keywords:** side nav, navigation, settings nav, sidebar, rail, docs nav, active item, group
+
+## Usage
+
+Use SideNav for vertical navigation inside a settings page, documentation area, dashboard rail, or sidebar chrome. It is router-agnostic: compose items with render={<Link />} and choose activeVariant based on whether the nav sits in content or app chrome.
+
+### Best practices
+
+- Do: Use aria-label on SideNav when a page contains more than one nav landmark.
+- Do: Group related items with SideNavGroup when the rail has more than one conceptual area.
+- Do: Use size='lg' and activeVariant='sidebar' when the nav is part of persistent app chrome.
+- Do: Inside a rounded, padded frame, give each item rounded-concentric-<outer>/<inset> (e.g. rounded-concentric-lg/2 in a rounded-lg p-2 box). The rows' own radius is fixed per size, and a same-radius row inset into a frame reads as a second system.
+- Don't: Use SideNav for bottom mobile navigation; use BottomNav in AppShell's bottomNav slot.
+- Don't: Mix content and sidebar active variants in the same rail unless individual items intentionally override the group.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Nav | yes | The landmark container for the vertical navigation list. |
+| Group | no | Optional labelled cluster of related navigation items. |
+| Item | yes | Interactive row with label, optional icon, optional badge, and active state. |
+| Badge | no | Trailing count or state indicator aligned to the row end. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SideNavItem | { label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; size?: "md" \| "lg"; activeVariant?: "content" \| "sidebar"; render?: useRender.RenderProp } + button props | A single row. label is the row text; icon is an optional leading icon; active marks the current sub-section (active fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end; size and activeVariant override the enclosing SideNav per item; render composes another element, e.g. render={<Link to="/x" />}. |
+| SideNavGroup | { label?: ReactNode } + div props | A labelled section within a SideNav - groups settings into areas. label renders an optional sentence-case caption heading above the group's items. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| size | "md" \| "lg" | — | Density shared by all items. "md" (default) = the lightweight in-content sub-nav; "lg" = chrome-weight (larger label + icon, roomier rows) for a rail that pairs with the app Sidebar. |
+| activeVariant | "content" \| "sidebar" | "content" | Active-state token vocabulary shared by all items. "content" uses bg-accent/text-accent-foreground for local rails inside the content area; "sidebar" uses bg-sidebar-accent/text-sidebar-accent-foreground for SideNavs rendered inside app chrome. |
+
+## Tokens used
+
+`muted`, `muted-foreground`, `foreground`, `accent`, `accent-foreground`, `ring`, `sidebar-foreground`, `sidebar-accent`, `sidebar-accent-foreground`, `sidebar-ring`
+
+## Accessibility
+
+- SideNav renders a <nav> landmark; pair multiple navs with aria-label to distinguish them.
+- The active item carries aria-current="page".
+- Items expose a focus-visible ring; the active state is reinforced by weight + fill, not colour alone.
+- Use activeVariant="content" for local in-page rails and activeVariant="sidebar" when a SideNav is placed on Sidebar chrome.
+
+## Related
+
+- Components: Sidebar, AppShell, BottomNav, Badge, Icon
+- Patterns: SettingsPage, DashboardPage
+
+## Examples
+
+### Settings sub-nav
+
+```tsx
+import { SideNav, SideNavItem } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<SideNav><SideNavItem label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem label="Account" render={<Link to="/settings/account" />} /><SideNavItem label="Notifications" render={<Link to="/settings/notifications" />} /></SideNav>
+```
+
+### Grouped
+
+```tsx
+import { SideNav, SideNavGroup, SideNavItem } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<SideNav><SideNavGroup label="Account"><SideNavItem label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem label="Security" render={<Link to="/settings/security" />} /></SideNavGroup><SideNavGroup label="Workspace"><SideNavItem label="Members" render={<Link to="/settings/members" />} /></SideNavGroup></SideNav>
+```
+
+### Chrome-weight rail (size=lg)
+
+```tsx
+import { SideNav, SideNavItem } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<SideNav size="lg"><SideNavItem label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem label="Wallets" render={<Link to="/settings/wallets" />} /><SideNavItem label="Security" render={<Link to="/settings/security" />} /></SideNav>
+```
+
+### Inside Sidebar chrome
+
+```tsx
+import { SideNav, SideNavItem } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<SideNav size="lg" activeVariant="sidebar"><SideNavItem label="Overview" active render={<Link to="/" />} /><SideNavItem label="Reports" render={<Link to="/reports" />} /><SideNavItem label="Settings" render={<Link to="/settings" />} /></SideNav>
+```
+
+### Grouped with icons and badges
+
+```tsx
+import { Badge, Icon, SideNav, SideNavGroup, SideNavItem } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<SideNav aria-label="Settings sections"><SideNavGroup label="Account"><SideNavItem icon={<Icon name="user" />} label="Profile" active render={<Link to="/settings/profile" />} /><SideNavItem icon={<Icon name="lock" />} label="Security" badge={<Badge tone="warning" size="sm">2</Badge>} render={<Link to="/settings/security" />} /></SideNavGroup><SideNavGroup label="Workspace"><SideNavItem icon={<Icon name="bell" />} label="Notifications" render={<Link to="/settings/notifications" />} /></SideNavGroup></SideNav>
+```

package/llms/components/sidebar.md

@@ -0,0 +1,87 @@
+# Sidebar
+
+**Status:** stable
+
+Desktop side-navigation rail (in-flow sticky, hidden below lg) with SidebarHeader / SidebarNav / SidebarItem / SidebarFooter parts. Items are router-agnostic via the `render` prop; an optional collapsed icon-rail mode reveals labels in tooltips.
+
+**Keywords:** sidebar, navigation, app chrome, rail
+
+## Usage
+
+Use Sidebar for persistent desktop navigation or application chrome outside the main content region.
+
+### Best practices
+
+- Do: Use it for stable app destinations that should remain visible while content changes.
+- Do: Keep item labels predictable and active state obvious.
+- Don't: Do not use Sidebar for page-local settings, filters, or temporary action groups.
+- Don't: Do not put page content in it. It is fixed-width chrome OUTSIDE the content grid, so anything in it is exempt from the page's measure and rhythm.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Sidebar | yes | The persistent navigation container. |
+| SidebarItem | yes | One navigation destination or action. |
+
+## Subcomponents
+
+| Name | Type | Description |
+| --- | --- | --- |
+| SidebarItem | { label: ReactNode; icon?: ReactNode; active?: boolean; badge?: ReactNode; render?: useRender.RenderProp } + button props | A single nav row. label is the row text (inline when expanded, in a hover tooltip when collapsed); icon is the leading icon node (the consumer swaps fill weight for the active state); active marks the current route (accent fill + aria-current="page"); badge is a trailing node (e.g. a count) pushed to the row end and hidden when collapsed; render composes another element, e.g. render={<Link to="/x" />}. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| collapsed | boolean | false | Collapse the rail to an icon-only width (--sidebar-width-collapsed). Items hide their label + badge and reveal the label in a hover tooltip; the content area reflows. Controlled — wire a toggle from app state. Read the state in custom header/footer content via useSidebar(). |
+| icons | boolean | true | Render the leading icon on each SidebarItem. Set false for a text-only rail. Ignored while collapsed (icon-only by definition). |
+| variant | "app" \| "inline" | "app" | Where the rail lives. "app" is the page's chrome column — sticky, full viewport height, hidden below lg where AppHeader + BottomNav take over. "inline" is always visible and fills its parent's height, for a rail inside a bounded frame (a nested shell, an embedded preview). Use it instead of overriding the layout with !important classes. |
+
+## Variants
+
+- **variant**: app, inline
+
+## Tokens used
+
+`sidebar`, `sidebar-foreground`, `sidebar-border`, `sidebar-accent`, `sidebar-accent-foreground`, `sidebar-ring`
+
+## Accessibility
+
+- SidebarNav renders a <nav> landmark.
+- Active item carries aria-current="page".
+- Items expose a focus-visible ring (sidebar-ring).
+- Collapsed: items take their accessible name from a string label (or aria-label) and reveal the visible label via the tooltip, so the rail stays usable by keyboard and screen readers.
+
+## Related
+
+- Components: SideNav, BottomNav, AppShell
+
+## Examples
+
+### Rail with nav
+
+```tsx
+import { Icon, NotificationBadge, Sidebar, SidebarFooter, SidebarHeader, SidebarItem, SidebarNav } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+<Sidebar><SidebarHeader>{brand}</SidebarHeader><SidebarNav><SidebarItem icon={<Icon name="bell" />} label="Notifications" badge={<NotificationBadge count={3} />} render={<Link to="/notifications" />} /></SidebarNav><SidebarFooter>{wallet}</SidebarFooter></Sidebar>
+```
+
+### Collapsible (icon rail)
+
+```tsx
+import { Button, Icon, Sidebar, SidebarFooter, SidebarItem, SidebarNav } from "@sableui/react"
+// <Link> = your router's link (react-router, next/link, @tanstack/router, …)
+
+const [collapsed, setCollapsed] = useState(false)
+<Sidebar collapsed={collapsed}><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active render={<Link to="/" />} /></SidebarNav><SidebarFooter><Button variant="ghost" size="icon" onClick={() => setCollapsed((c) => !c)} aria-label="Toggle sidebar"><Icon name="chevron-left" /></Button></SidebarFooter></Sidebar>
+```
+
+### Inline (inside a bounded frame)
+
+```tsx
+import { Icon, Sidebar, SidebarItem, SidebarNav } from "@sableui/react"
+
+<div className="flex h-80 overflow-hidden rounded-lg border border-border"><Sidebar variant="inline"><SidebarNav><SidebarItem icon={<Icon name="home" />} label="Home" active /></SidebarNav></Sidebar><div className="flex-1 p-6">Content</div></div>
+```

package/llms/components/skeleton.md

@@ -0,0 +1,62 @@
+# Skeleton
+
+**Status:** stable
+
+Loading placeholder — a muted, shimmering block (rounded-md bg-muted motion-shimmer). Shape it with utility classes; rounded-full for circles.
+
+**Keywords:** skeleton, loading, placeholder, pending
+
+## Usage
+
+Use Skeleton to reserve space and hint at the shape of content while data is loading.
+
+### Best practices
+
+- Do: Match the approximate size and rhythm of the eventual content.
+- Do: Use it for content regions where layout stability matters during loading.
+- Don't: Do not leave Skeleton visible after an error or empty state; switch to EmptyState (tone='destructive' for an error).
+- Don't: Do not use a skeleton whose shape differs from the content that replaces it. A mismatched placeholder causes a visible jump, which is worse than a brief spinner.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| ...props | ComponentPropsWithRef<"div"> | — | All native div props plus className. Size and shape the placeholder with utilities (h-*, w-*, size-*, rounded-full). |
+
+## Tokens used
+
+`muted`
+
+## Motion
+
+- **arrival** · Root · _no motion_ — A skeleton stands in for content that has not arrived; fading the placeholder in adds a wait before the wait.
+- **response** · Root · _no motion_ — Nothing here is interactive. A skeleton that reacted to the pointer would invite a click on a thing that cannot be clicked.
+- **transition** · Root · _no motion_ — The skeleton has one state. Swapping it for real content is the parent's job, and the parent decides whether that swap is animated.
+- **activity** · Root · `motion-shimmer` — The sweep is the entire point of the component: it is what separates 'still loading' from 'loaded, and empty'. A static grey block is indistinguishable from a broken layout, which is why users reload the page.
+
+## Accessibility
+
+- Purely presentational; the shimmer sweep is decorative, and it stops under reduced motion because motion-shimmer follows --motion-scale.
+- Mark the loading region with aria-busy="true" on a parent, and swap in real content (with the same layout) once loaded to avoid shift.
+
+## Related
+
+- Components: Spinner, PageLoader
+
+## Examples
+
+### Shapes
+
+```tsx
+import { Skeleton } from "@sableui/react"
+
+<Skeleton className="h-4 w-40" /><Skeleton className="size-10 rounded-full" /><Skeleton className="h-40 w-full" />
+```
+
+### Post-card composition
+
+```tsx
+import { Skeleton } from "@sableui/react"
+
+<div className="flex items-center gap-3"><Skeleton className="size-10 rounded-full" /><div className="space-y-2"><Skeleton className="h-3 w-32" /><Skeleton className="h-3 w-20" /></div></div>
+```