@sableui/react 0.1.1 → 0.3.0

package/llms/blocks/wallet-block.md

@@ -0,0 +1,84 @@
+# WalletBlock
+
+A balance card: the balance in the metric mono tier, Send and Receive as an equal pair, and recent activity as Entity rows with signed amounts.
+
+**Intent:** Reach for this for a wallet, account balance or credits summary with its latest movements. For a full transaction history with filters, use a DataTable.
+
+**Block:** Commerce · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The balance is CardTitle at `text-mono-xl` — tabular figures, never a heading tier — under its label as CardDescription.
+- Send is primary and Receive secondary, side by side at equal width: two directions of one action, with sending the riskier and more frequent.
+- Incoming amounts are `text-success`; outgoing stay muted rather than red, because a withdrawal is not an error.
+
+## Accessibility
+
+- Each activity row's leading swatch is aria-hidden; the title and detail carry the meaning.
+- Amounts keep their sign in text (+0.80 / -1.50), so the direction does not depend on colour.
+
+## Source
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, cn, Entity, Icon } from "@sableui/react"
+
+const balance = "14.62 SOL"
+
+const activity = [
+	{ title: "Sold “Dusk, no. 4”", detail: "Edition · 2h ago", amount: "+0.80", tone: "edition" },
+	{ title: "Royalty", detail: "Collectible · Yesterday", amount: "+0.12", tone: "collectible" },
+	{ title: "Withdrawal", detail: "To Phantom · Mon", amount: "-1.50", tone: "standard" },
+]
+
+export interface WalletBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet or muted section that already frames it. */
+	framed?: boolean
+	onSend?: () => void
+	onReceive?: () => void
+}
+
+export function WalletBlock({ className, framed = true, onSend, onReceive }: WalletBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardHeader>
+				<CardDescription>Balance</CardDescription>
+				<CardTitle className="text-mono-xl">{balance}</CardTitle>
+			</CardHeader>
+			<CardContent className="flex flex-col gap-3">
+				<div className="grid grid-cols-2 gap-2">
+					<Button iconStart={<Icon name="arrow-up" />} onClick={onSend}>
+						Send
+					</Button>
+					<Button variant="secondary" iconStart={<Icon name="arrow-down" />} onClick={onReceive}>
+						Receive
+					</Button>
+				</div>
+				<div className="flex flex-col">
+					{activity.map((item) => (
+						<Entity
+							key={item.title}
+							className="px-0"
+							leading={
+								<span
+									aria-hidden
+									className="block size-8 rounded-full"
+									// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+									style={{ background: `oklch(from var(--tone-${item.tone}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h)` }}
+								/>
+							}
+							title={item.title}
+							subtitle={item.detail}
+							action={
+								<span className={cn("text-mono-md", item.amount.startsWith("+") ? "text-success" : "text-muted-foreground")}>
+									{item.amount}
+								</span>
+							}
+						/>
+					))}
+				</div>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/components/area-chart.md

@@ -0,0 +1,112 @@
+# AreaChart
+
+**Status:** beta
+
+A trend over a sequence, filled to the baseline: overlapping translucent series, stacked, or stacked to 100%, with smooth, linear or step curves and optional gradient fills. The line draws on and the fill rises as it scrolls into view.
+
+**Keywords:** chart, area, trend, time series, stacked, graph, analytics, dashboard, visitors, revenue
+
+## Usage
+
+Use AreaChart for volume over time — visitors, revenue, usage — where the filled shape helps the eye read the size of the total. Stack the series to show a total and its parts; `stacked="expand"` shows each category as 100%. For comparing how measures move relative to each other, LineChart is cleaner; for amounts per category, BarChart.
+
+### Best practices
+
+- Do: Keep to one to three series; past that the tints muddy — stack them or switch to LineChart.
+- Do: Set a height on className (h-72, aspect-video h-auto); the chart fills the box it is given.
+- Don't: Overlap more than two unstacked series — the translucent tints blend into a colour no series has.
+- Don't: Use it for data-heavy views — streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | Record<string, unknown>[] | — | The rows, in order along the category axis. |
+| index | string | — | The datum field naming each row's category (a month, a day, a channel). |
+| series | { key: string; label: string; tone?: ChartTone; color?: string; icon?: string }[] | — | The measures to plot: the datum field, its name in the legend/tooltip/table, and its colour (a tone by role, or any CSS colour). Omitted, series take the chart palette in order: --chart-1 … --chart-8, validated for colour-blind separation in light and dark; a theme may override the set. |
+| label | string | — | What the chart shows. Its accessible name and the caption of the data table assistive tech reads. |
+| className | string | "h-60" | Sizes the chart (plot + legend). Set a height: `h-72`, `aspect-video h-auto`. |
+| valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
+| indexFormatter | (value: string) => string | — | Shorten category labels on the axis ("January" → "Jan"); the tooltip keeps the full value. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+| tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
+| legend | boolean | true when there is more than one series | Show the legend under the chart. |
+| grid | boolean | true (false for horizontal bars) | Hairline gridlines along the value axis. |
+| xAxis | boolean | true for columns; false for horizontal bars | The horizontal axis. |
+| yAxis | boolean | false for columns; true for horizontal bars | The vertical axis. |
+| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. |
+| activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
+| defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
+| onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
+| curve | "smooth" \| "linear" \| "step" | "smooth" | How the line runs between points. `smooth` is monotone: it never overshoots a value the data does not contain. |
+| stacked | boolean \| "expand" | false | Stack the series, or `"expand"` to show each category as 100%. |
+| gradient | boolean | false | Fill each area with a fade from its colour to transparent instead of a flat tint. |
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+
+## Motion
+
+- **arrival** · Area + line · _custom (outside the recipe layer)_ — Once on screen, each line draws on (stroke-dashoffset) and its fill rises from the baseline, series staggered — the trend is read as it is drawn. On the motion tokens; reduced motion shows the finished chart.
+- **response** · Cursor + tooltip · _no motion_ — Hover and focus move the cursor and tooltip instantly — a lagging cursor reads as a slow chart.
+- **transition** · Area + line · _custom (outside the recipe layer)_ — Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place.
+- **activity** · AreaChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
+
+## Accessibility
+
+- The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.
+- With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.
+- Colour is never the only key: series are named in the legend, tooltip and table.
+
+## Related
+
+- Components: LineChart, BarChart, Sparkline, Card
+
+## Examples
+
+### Two series with a legend
+
+```tsx
+import { AreaChart } from "@sableui/react"
+
+const visitors = [
+	{ month: "January", desktop: 186, mobile: 80 },
+	{ month: "February", desktop: 305, mobile: 200 },
+	{ month: "March", desktop: 237, mobile: 120 },
+	{ month: "April", desktop: 73, mobile: 190 },
+	{ month: "May", desktop: 209, mobile: 130 },
+	{ month: "June", desktop: 214, mobile: 140 },
+]
+
+<AreaChart
+	label="Visitors, January to June"
+	data={visitors}
+	index="month"
+	series={[
+		{ key: "desktop", label: "Desktop" },
+		{ key: "mobile", label: "Mobile" },
+	]}
+	indexFormatter={(m) => m.slice(0, 3)}
+	gradient
+/>
+```
+
+### Stacked to 100%
+
+```tsx
+import { AreaChart } from "@sableui/react"
+
+<AreaChart
+	label="Share of visitors by device"
+	data={visitors}
+	index="month"
+	series={[
+		{ key: "desktop", label: "Desktop" },
+		{ key: "mobile", label: "Mobile" },
+	]}
+	stacked="expand"
+	yAxis
+	tooltip={{ indicator: "line", showTotal: true }}
+/>
+```

package/llms/components/bar-chart.md

@@ -0,0 +1,131 @@
+# BarChart
+
+**Status:** beta
+
+Bars comparing amounts across categories: grouped, stacked or stacked to 100%, vertical columns or horizontal bars, with value labels, per-category colours and a separate tone for negative values. Bars rise from the baseline in sequence as the chart scrolls into view.
+
+**Keywords:** chart, bar, column, histogram, compare, stacked, grouped, horizontal, analytics, dashboard
+
+## Usage
+
+Use BarChart to compare amounts across categories — the default chart for "how much of each". Go horizontal (`orientation="horizontal"`) when category names are long or there are many of them; group series side by side to compare them, stack them to show a total. For parts of one whole, a stacked bar or PieChart; for a trend, AreaChart or LineChart.
+
+### Best practices
+
+- Do: Sort categories by value unless they have a natural order (months, steps).
+- Do: Use negativeTone for diverging data (profit and loss), so a loss reads apart from a gain.
+- Don't: Group more than three series side by side — the bars get too thin to compare; stack them or split the chart.
+- Don't: Use it for data-heavy views — streaming or real-time data, thousands of points, zoom and brushing, trading charts. Those belong on a charting library (Recharts, visx, ECharts); Sable's charts are for dashboards, landing pages and decks.
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| data | Record<string, unknown>[] | — | The rows, in order along the category axis. |
+| index | string | — | The datum field naming each row's category (a month, a day, a channel). |
+| series | { key: string; label: string; tone?: ChartTone; color?: string; icon?: string }[] | — | The measures to plot: the datum field, its name in the legend/tooltip/table, and its colour (a tone by role, or any CSS colour). Omitted, series take the chart palette in order: --chart-1 … --chart-8, validated for colour-blind separation in light and dark; a theme may override the set. |
+| label | string | — | What the chart shows. Its accessible name and the caption of the data table assistive tech reads. |
+| className | string | "h-60" | Sizes the chart (plot + legend). Set a height: `h-72`, `aspect-video h-auto`. |
+| valueFormatter | (value: number) => string | — | Format values everywhere (axis, labels, tooltip, table) — units like "$12,480". Default: compact on the axis, full elsewhere. |
+| indexFormatter | (value: string) => string | — | Shorten category labels on the axis ("January" → "Jan"); the tooltip keeps the full value. |
+| locale | string | runtime locale | BCP 47 locale for default number and date formatting. |
+| tooltip | boolean \| { indicator?: "dot" \| "line" \| "dashed" \| "none"; hideLabel?: boolean; labelFormatter?: (label, datum) => ReactNode; showTotal?: boolean } | true | Show a tooltip on hover and keyboard focus, or configure it: the row marker, hiding the heading, rewriting it, adding a Total row. |
+| legend | boolean | true when there is more than one series | Show the legend under the chart. |
+| grid | boolean | true (false for horizontal bars) | Hairline gridlines along the value axis. |
+| xAxis | boolean | true for columns; false for horizontal bars | The horizontal axis. |
+| yAxis | boolean | false for columns; true for horizontal bars | The vertical axis. |
+| animate | boolean | true | Play the arrival once the chart scrolls into view. Reduced motion shows the finished chart. |
+| activeIndex | number \| null | — | The highlighted row (controlled); `null` for none. |
+| defaultActiveIndex | number \| null | — | The row highlighted at first — a tooltip already open before anyone hovers. |
+| onActiveIndexChange | (index: number \| null) => void | — | Called as the pointer or keyboard moves between rows. |
+| orientation | "vertical" \| "horizontal" | "vertical" | `vertical` columns rise from the bottom; `horizontal` bars run from the left, for long category names. |
+| stacked | boolean \| "expand" | false | Stack the series in one bar, or `"expand"` to show each category as 100%. Unstacked series sit side by side. |
+| labels | boolean \| "inside" | false | Print each bar's value at its end, or (`"inside"`, horizontal) the category name inside the bar as well. |
+| colorBy | "series" \| "index" | "series" | Colour by series, or give each category its own tone (one series). |
+| negativeTone | "edition" \| "collectible" \| "standard" \| "info" \| "warning" \| "primary" \| "neutral" \| "success" \| "destructive" | — | Colour negative values with this tone. |
+| radius | number | 4 | Corner radius of each bar's far end, in px. Stacks round only the outer segment. |
+| barWidth | number | 24 | Maximum thickness of a bar, in px: the band's leftover is air, not a fatter bar. Raise it for a bolder presentation look. |
+
+## Tokens used
+
+`tone-edition`, `tone-collectible`, `tone-standard`, `tone-info`, `tone-warning`, `primary`, `muted-foreground`, `border`, `popover`, `popover-foreground`, `foreground`, `background`
+
+## Motion
+
+- **arrival** · Bar · _custom (outside the recipe layer)_ — Once on screen, bars rise from the baseline in sequence on the emphasized easing (scale from the zero line) and their labels fade in. On the motion tokens; reduced motion shows the finished chart.
+- **response** · Cursor + tooltip · _no motion_ — The hovered category gets a band behind it and the other bars dim at once — a lagging highlight reads as a slow chart.
+- **transition** · Bar · _custom (outside the recipe layer)_ — Geometry eases from the old shape to the new one through a CSS `d` transition on the motion tokens (no recipe animates path geometry); browsers without `d` transitions update in place.
+- **activity** · BarChart · _no motion_ — A chart has no indeterminate state; show a Skeleton while the data loads.
+
+## Accessibility
+
+- The drawing is aria-hidden; the same numbers are in a visually hidden data table (captioned by `label`) that the chart is aria-describedby, so assistive tech reads values, not shapes.
+- With a tooltip, the chart is one tab stop (role=group, aria-roledescription="chart"): arrow keys, Home and End step through the data, Escape clears, and each step is announced in a polite live region.
+- Colour is never the only key: series are named in the legend, tooltip and table.
+
+## Related
+
+- Components: AreaChart, PieChart, SegmentedBar, Card
+
+## Examples
+
+### Grouped series
+
+```tsx
+import { BarChart } from "@sableui/react"
+
+<BarChart
+	label="Visitors by device"
+	data={visitors}
+	index="month"
+	series={[
+		{ key: "desktop", label: "Desktop" },
+		{ key: "mobile", label: "Mobile" },
+	]}
+	indexFormatter={(m) => m.slice(0, 3)}
+/>
+```
+
+### Horizontal, labelled inside
+
+```tsx
+import { BarChart } from "@sableui/react"
+
+const browsers = [
+	{ browser: "Chrome", visitors: 275 },
+	{ browser: "Safari", visitors: 200 },
+	{ browser: "Firefox", visitors: 187 },
+	{ browser: "Edge", visitors: 173 },
+]
+
+<BarChart
+	label="Visitors by browser"
+	data={browsers}
+	index="browser"
+	series={[{ key: "visitors", label: "Visitors" }]}
+	orientation="horizontal"
+	labels="inside"
+	yAxis={false}
+	grid={false}
+/>
+```
+
+### Profit and loss
+
+```tsx
+import { BarChart } from "@sableui/react"
+
+<BarChart
+	label="Net revenue by month"
+	data={[
+		{ month: "Jan", net: 186 },
+		{ month: "Feb", net: -95 },
+		{ month: "Mar", net: 137 },
+		{ month: "Apr", net: -60 },
+	]}
+	index="month"
+	series={[{ key: "net", label: "Net", tone: "success" }]}
+	negativeTone="destructive"
+	labels
+/>
+```

package/llms/components/bubble.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The surface a message's content sits on: four treatments, an align-aware tail corner, a readable measure cap, and an optional row of reaction pills.
+The surface a message's content sits on: four treatments, an align-aware tail, a readable measure cap, and an optional row of reaction pills.
 
 **Keywords:** chat bubble, message bubble, speech bubble, reactions, conversation, messaging, ai chat
 
@@ -14,7 +14,7 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 
 - Do: Use `muted` for the other party and `primary` for the reader's own messages. Two treatments is the whole vocabulary a conversation needs to say who is speaking.
 - Do: Reach for `variant="plain"` for long-form assistant output — rendered markdown, code blocks, tables. A tinted box around three paragraphs reads as a quote block rather than as a turn, and `plain` drops the measure cap with the surface.
-- Do: Pass the same `align` you gave the enclosing Message, so the flattened corner lands on the speaker's side.
+- Do: Pass the same `align` you gave the enclosing Message, so the tail lands on the speaker's side.
 - Do: Set `tail={false}` on the continuation bubbles in a grouped run — the tail marks where a speaker starts, and repeating it on every line makes a block of one person's messages look like four separate turns.
 - Do: Let the register size it. Inside `<Density value="compact">` a Bubble sets itself in the workspace prose tier automatically — a docked agent panel needs no per-call-site sizing, and hardcoding one defeats the mechanism.
 - Don't: Do not remove the measure cap to fill a wide window. ~42rem is a reading measure; a bubble spanning a 1600px viewport is a paragraph at 140 characters per line.
@@ -26,7 +26,7 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 
 | Part | Required | Description |
 | --- | --- | --- |
-| Bubble | yes | The surface itself. Holds the variant, the side, and the flattened tail corner. |
+| Bubble | yes | The surface itself. Holds the variant, the side, and the tail. |
 | BubbleReactions | no | The row of reaction pills, just under the bubble at the message column's small gap, so it reads as belonging to that message rather than the next row. |
 | BubbleReaction | no | One reaction pill — emoji, count (hidden at 1), and pressed state. |
 
@@ -42,8 +42,8 @@ The tinted (or untinted) surface a turn's content sits on. Kept separate from Me
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
 | variant | "muted" \| "primary" \| "outline" \| "plain" | "muted" | Surface treatment. `muted` for the other party, `primary` for the reader's own messages, `outline` for a quieter own-side, `plain` for long-form output that should not sit in a box (also drops the measure cap and padding). |
-| align | "start" \| "end" | "start" | Which side of the conversation the bubble is on — flattens the corner nearest the speaker. Match it to the enclosing Message. |
-| tail | boolean | true | Flatten the speaker-side corner. A flattened corner rather than a drawn arrow, so it holds up in every theme's radius language (flat through fully pilled) with no per-theme geometry. Turn it off for the continuation bubbles in a grouped run. |
+| align | "start" \| "end" | "start" | Which side of the conversation the bubble is on — puts the tail on the speaker's side. Match it to the enclosing Message. |
+| tail | boolean | true | Draw the tail: a small ear off the speaker-side top corner, which goes square to meet it. The same 5px in every theme's radius language, flat through fully pilled. The bubble keeps the ear's space either way, so turning it off for the continuation bubbles in a grouped run keeps the run aligned. |
 | ...div props | ComponentPropsWithRef<"div"> | — | Spread onto the surface element. |
 
 ## Variants

package/llms/components/button.md

@@ -72,7 +72,7 @@ Use Button when the user commits an action, submits a form, opens UI, or confirm
 
 ## Related
 
-- Components: Menu, DotsMenu, Icon, Banner
+- Components: Menu, OverflowMenu, Icon, Banner
 - Patterns: SettingsPage, AuthPage, DashboardPage
 
 ## Examples

package/llms/components/card.md

@@ -34,9 +34,9 @@ Use Card for a discrete thing with its own boundary, such as one product, one no
 | 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). |
+| CardTitle | ComponentPropsWithRef<"div"> & { render?: useRender.RenderProp } | The card's name (text-title-lg). A div by default; pass `render={<h2 />}` (or h3…) to make it a heading in the page outline, at the level the card's position calls for. |
 | 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. |
+| CardAction | ComponentPropsWithRef<"div"> | Header-aligned top-right action slot (e.g. an overflow 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. |

package/llms/components/checkbox-card.md

@@ -39,7 +39,7 @@ Use CheckboxCard when an option needs more visual weight, supporting text, or ic
 | 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. |
+| icon | ReactNode | — | Optional glyph (a solid <Icon>) in the tone colour. Its presence switches to the two-dimensional card RadioCard uses — icon top-left, checkbox top-right, copy below — so the two cards match in one form. |
 | 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. |

package/llms/components/context-card.md

@@ -67,7 +67,7 @@ import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Entity } f
 ### With stat row
 
 ```tsx
-import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Description, DescriptionItem, Entity } from "@sableui/react"
+import { Avatar, ContextCard, ContextCardContent, ContextCardTrigger, Entity } from "@sableui/react"
 
-<ContextCard><ContextCardTrigger render={<a href='/u/nyx' className='text-title-sm underline-offset-2 hover:underline'>@nyx</a>} /><ContextCardContent><Entity className='[--entity-px:0] [--entity-py:0]' leading={<Avatar fallback='NY' size='lg' />} title='Nyx' subtitle='@nyx' /><Description cols='2' className='mt-4 border-t border-border pt-3'><DescriptionItem term='Posts' detail='128' /><DescriptionItem term='Followers' detail='4.2k' /></Description></ContextCardContent></ContextCard>
+<ContextCard><ContextCardTrigger render={<a href='/u/nyx' className='text-title-sm underline-offset-2 hover:underline'>@nyx</a>} /><ContextCardContent><Entity className='[--entity-px:0] [--entity-py:0]' leading={<Avatar fallback='NY' size='lg' />} title='Nyx' subtitle='@nyx' /><div className='@container mt-4 border-t border-border pt-3'><dl className='sable-list-dl sable-list-dl-2'><dt>Posts</dt><dd>128</dd><dt>Followers</dt><dd>4.2k</dd></dl></div></ContextCardContent></ContextCard>
 ```

package/llms/components/context-menu.md

@@ -58,7 +58,7 @@ Use ContextMenu for actions that are specific to the object or area the user inv
 
 ## Related
 
-- Components: Menu, DotsMenu
+- Components: Menu, OverflowMenu
 
 ## Examples
 

package/llms/components/date-tile.md

@@ -0,0 +1,79 @@
+# DateTile
+
+**Status:** stable
+
+A calendar-page date: the short month on a primary band over the day number, in a <time> element. The leading visual of an event, booking or deadline row.
+
+**Keywords:** date, calendar, event, day, month, schedule, booking, tile
+
+## Usage
+
+Use DateTile as the leading visual when the date is what a reader scans a list or card by — events, bookings, deadlines, releases. It sits beside a title and a time line, usually in an Entity's `leading` slot or a flex row in a CardContent. For a date inside a sentence or a row's metadata, use text or RelativeTime instead.
+
+### Best practices
+
+- Do: Pair the tile with a title and the full time or range in text beside it; the tile only names the day.
+- Do: Keep every row of a list on DateTile so the dates line up as one column.
+- Don't: Use it for timestamps ("2 hours ago", "Oct 14, 10:02") — that is RelativeTime or plain metadata text.
+- Don't: Stretch it to its neighbour's height or restyle the band per row; the tile is a fixed shape so a column of them reads as one calendar.
+
+### Anatomy
+
+| Part | Required | Description |
+| --- | --- | --- |
+| Band | yes | The short month name on the primary colour. |
+| Day | yes | The day of the month, on the muted surface. |
+
+## Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| date | Date | — | The day to show, read in local time. Rendered as `<time dateTime="YYYY-MM-DD">`. |
+| locale | string | runtime locale | BCP 47 locale for the month name. |
+
+## Tokens used
+
+`muted`, `primary`, `primary-foreground`, `foreground`
+
+## Motion
+
+- **arrival** · Tile · _no motion_ — A static label; it appears with whatever row or card holds it.
+- **response** · Tile · _no motion_ — Not interactive.
+- **transition** · Tile · _no motion_ — It has no states to move between.
+- **activity** · Tile · _no motion_ — Nothing runs in the background.
+
+## Accessibility
+
+- Renders a <time> with a machine-readable `dateTime`, so the day is announced as text ("Oct 14") and parsable as a date.
+- The tile names only the day — state the weekday, time or range in the text beside it, where it is read in order.
+
+## Related
+
+- Components: Entity, Card, RelativeTime, Calendar
+
+## Examples
+
+### Event row
+
+```tsx
+import { DateTile, Row, Stack } from "@sableui/react"
+
+<Row gap={4} align="start">
+	<DateTile date={new Date(2026, 9, 14)} />
+	<Stack gap={1}>
+		<span className="text-title-lg">Design review</span>
+		<span className="text-body-sm text-muted-foreground">Tuesday, 2:00 – 2:45 PM</span>
+	</Stack>
+</Row>
+```
+
+### In an Entity list
+
+```tsx
+import { CardList, DateTile, Entity } from "@sableui/react"
+
+<CardList>
+	<Entity leading={<DateTile date={new Date(2026, 9, 14)} />} title="Design review" subtitle="Tuesday, 2:00 PM" />
+	<Entity leading={<DateTile date={new Date(2026, 9, 21)} />} title="Launch" subtitle="Tuesday, all day" />
+</CardList>
+```

package/llms/components/dialog.md

@@ -38,7 +38,7 @@ Use Dialog for focused decisions, short modal forms, confirmations, and content
 | Name | Type | Description |
 | --- | --- | --- |
 | DialogContent | Base UI Popup props + size?: "default" \| "fullscreen" + showCloseButton?: boolean + scroll?: boolean + className | Backdrop + popup; portals to <body>. Composes DialogOverlay by default. size="fullscreen" is the media viewer: a near-opaque scrim (bg-overlay/95), an edge-to-edge popup that centres its children with no card chrome, motion-fade instead of motion-pop, and a safe-area-aware floating close button (Button variant="floating"); at that size showCloseButton defaults to true and scroll to false, and the media fits itself with max-h-full max-w-full object-contain. At the default size, showCloseButton (defaults to false) renders a built-in close (X) button in the top-end corner, and the header leaves room for it (Icon name="xmark"). The popup caps at the viewport height less a 1rem margin and wraps its children in a scrolling region, so a tall dialog scrolls instead of overflowing a viewport whose own scroll is locked; pass scroll={false} when the dialog owns its internal layout (a pinned header over a scrolling body) and supplies its own min-h-0 scroll region. |
-| DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/50 by default, near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
+| DialogOverlay | Base UI Backdrop props + size?: "default" \| "fullscreen" + className | The styleable scrim/backdrop — bg-overlay/(--scrim-alpha) by default (50% light, 72% dark, so it dims a near-black page as visibly as a white one), near-opaque bg-overlay/95 at size="fullscreen". Composed into DialogContent (at the matching size) by default; exported for manual styling. |
 | DialogTrigger | Base UI Dialog.Trigger props (render) | Element that opens the dialog. Compose via render prop. |
 | DialogClose | Base UI Dialog.Close props (render) | Element that dismisses the dialog. Compose via render prop. |
 | DialogHeader | ComponentProps<"div"> | Top section holding DialogTitle/DialogDescription. |

package/llms/components/empty-state.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-The centered empty / error block: optional icon disc or error code, title, description and an action. tone="destructive" makes it an announced error, size="lg" a page-level state, surface="card" a self-contained card.
+The centered empty / error block: optional icon or error code, title, description and an action. tone="destructive" makes it an announced error, size="lg" a page-level state, surface="card" a self-contained card.
 
 **Keywords:** empty, zero state, blank slate, no results, placeholder, onboarding, no data
 
@@ -33,12 +33,12 @@ Use EmptyState when a content area has no items, no search results, or no first-
 
 | Name | Type | Default | Description |
 | --- | --- | --- | --- |
-| icon | ReactNode | — | Optional leading glyph — pass an `<Icon />`. Rendered in a soft muted disc. |
+| icon | ReactNode | — | Optional glyph above the title — an `<Icon />` takes the muted ink at 3xl; an image or illustration renders as given. |
 | title | ReactNode | — | The headline. Short and direct. |
 | description | ReactNode | — | Optional supporting line beneath the title. |
 | action | ReactNode | — | Optional action below the copy — typically a `<Button />`. |
 | code | ReactNode | — | A large figure above the title, such as an error code (404). |
-| tone | "neutral" \| "destructive" | "neutral" | destructive is an error state: a destructive icon disc (a warning by default) and role="alert" so it is announced. |
+| tone | "neutral" \| "destructive" | "neutral" | destructive is an error state: a destructive icon (a warning by default) and role="alert" so it is announced. |
 | size | "md" \| "lg" | "md" | lg is page-level: the title is an h2 and the block takes more room. md sits in a panel, list or card. |
 | surface | "none" \| "card" | "none" | card draws it as a Card, for an error or empty block standing on its own in a page. |
 
@@ -54,7 +54,7 @@ Use EmptyState when a content area has no items, no search results, or no first-
 
 ## Accessibility
 
-- Decorative icon discs should not carry meaning the title doesn't already convey.
+- Decorative icons should not carry meaning the title doesn't already convey.
 - Pair with an actionable next step so the zero-state is a path forward, not a dead end.
 
 ## Related

package/llms/components/entity.md

@@ -2,7 +2,7 @@
 
 **Status:** stable
 
-A list-row record: leading visual + title/subtitle column + trailing action, with truncating text. Presentational by default (no hover); `interactive` rows gain the hover highlight, focus ring, and keyboard activation. Compact/comfortable density.
+A list-row record: leading visual + title/subtitle column + trailing action, with truncating text. Presentational by default (no hover); `interactive` rows gain the hover highlight, focus ring, and keyboard activation, and `selected` marks the current one. Compact/comfortable density.
 
 **Keywords:** entity, identity, object, avatar row
 
@@ -28,6 +28,7 @@ Use Entity to show a compact identity block for a person, organization, file, pr
 | action | ReactNode | — | Trailing slot — typically a ghost icon Button or a StatusDot. |
 | interactive | boolean | false | Make the whole row a target: the leading visual and text become a native <button> whose hit area stretches over the row (focus ring, Enter/Space). The action stays outside it. Requires onSelect. |
 | onSelect | () => void | — | Activation handler for an interactive row (fired on click and Enter/Space). Required when interactive. |
+| selected | boolean | false | Interactive rows only: the current row of a selectable list (the record open in a list–detail view). Sets aria-current="true" on the row's button and paints the selected fill, a step off the surface the row sits on, which holds on hover. |
 | density | "compact" \| "comfortable" | "compact" | Row padding: compact (12px × 10px, the default) or comfortable (16px × 12px), on the spacing scale. The insets read --entity-px / --entity-py first, which CardList sets from the card's own padding so rows in a card line up with its header. |
 
 ## Variants
@@ -36,17 +37,18 @@ Use Entity to show a compact identity block for a person, organization, file, pr
 
 ## Tokens used
 
-`muted`, `foreground`, `muted-foreground`, `ring`
+`accent`, `accent-foreground`, `foreground`, `muted-foreground`, `ring`
 
 ## Accessibility
 
 - Default rows are presentational layout; semantics come from the content you place in title/subtitle/action.
 - interactive rows render a real <button> around the leading visual and text, with its ::after stretched over the whole row — native focus, a focus-visible ring, and Enter/Space. The action slot sits outside that button and above the overlay, so a Button there stays valid HTML and keeps its own clicks.
 - Give any interactive action an accessible label (e.g. aria-label on a ghost icon Button).
+- A selected row announces aria-current="true" on its button, so the current record is spoken, not only shown by its fill.
 
 ## Related
 
-- Components: Avatar, Badge, Description
+- Components: Avatar, Badge
 
 ## Examples
 

package/llms/components/fieldset.md

@@ -56,7 +56,7 @@ Use Fieldset to group related controls under a shared label or explanation.
 
 ## Related
 
-- Components: Form, Label, Description
+- Components: Form, Label
 
 ## Examples