@sableui/react 0.2.0 → 0.3.0

package/llms/blocks/traffic-trend-block.md

@@ -0,0 +1,95 @@
+# TrafficTrendBlock
+
+A trend card: a stacked gradient AreaChart of two series by day, a time-range ToggleGroup in the header, and a one-line takeaway with its direction in the footer.
+
+**Intent:** Reach for this as the headline chart of a dashboard or an analytics section on a landing page. For a single number with a small trend beside it, KpiSparklineBlock is lighter.
+
+**Block:** Dashboard · card · designed for 20rem–48rem wide (fills its container up to the max)
+
+## Notes
+
+- Switching the range eases the chart from one shape to the next instead of redrawing it.
+- The footer states the takeaway in words, so the card says something even before the chart is read.
+- The tooltip heading spells out the weekday; the axis keeps short dates so they fit.
+
+## Accessibility
+
+- The chart's accessible name includes the range showing, and its data table updates with it.
+- The range control is a labelled ToggleGroup; the chart is one tab stop with arrow-key navigation.
+
+## Source
+
+```tsx
+import { useState } from "react"
+import { AreaChart, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, Icon, Toggle, ToggleGroup } from "@sableui/react"
+
+/** 90 days of visitors — replace with your own rows ({ date, desktop, mobile }). */
+const days = Array.from({ length: 90 }, (_, i) => {
+	const wave = Math.sin(i / 6) * 60 + Math.sin(i / 2.3) * 25
+	return {
+		date: new Date(2026, 6, 1 + i).toISOString().slice(0, 10),
+		desktop: Math.round(240 + wave + (i % 7) * 9),
+		mobile: Math.round(160 + wave * 0.7 + ((i * 3) % 11) * 6),
+	}
+})
+
+const series = [
+	{ key: "desktop", label: "Desktop" },
+	{ key: "mobile", label: "Mobile" },
+]
+
+const ranges = [
+	{ id: "90d", label: "3 months", days: 90 },
+	{ id: "30d", label: "30 days", days: 30 },
+	{ id: "7d", label: "7 days", days: 7 },
+]
+
+const shortDate = (iso: string) => new Date(`${iso}T00:00:00`).toLocaleDateString("en-US", { month: "short", day: "numeric" })
+
+export interface TrafficTrendBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+}
+
+export function TrafficTrendBlock({ className, framed = true }: TrafficTrendBlockProps) {
+	const [range, setRange] = useState("90d")
+	const shown = days.slice(-(ranges.find((r) => r.id === range)?.days ?? 90))
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-3xl", className)}>
+			<CardHeader>
+				<CardTitle render={<h2 />}>Visitors</CardTitle>
+				<CardDescription>Desktop and mobile, by day.</CardDescription>
+				<CardAction>
+					<ToggleGroup value={[range]} onValueChange={(v: unknown[]) => v[0] && setRange(String(v[0]))} aria-label="Time range">
+						{ranges.map((r) => (
+							<Toggle key={r.id} value={r.id}>
+								{r.label}
+							</Toggle>
+						))}
+					</ToggleGroup>
+				</CardAction>
+			</CardHeader>
+			<CardContent>
+				<AreaChart
+					label={`Visitors per day, last ${ranges.find((r) => r.id === range)?.label}`}
+					data={shown}
+					index="date"
+					series={series}
+					indexFormatter={shortDate}
+					tooltip={{ labelFormatter: (d) => new Date(`${d}T00:00:00`).toLocaleDateString("en-US", { weekday: "short", month: "short", day: "numeric" }) }}
+					stacked
+					gradient
+					className="h-64"
+				/>
+			</CardContent>
+			<CardFooter className="gap-1.5 text-body-sm">
+				<Icon name="arrow-up" className="text-success" />
+				<span>
+					Up 5.2% on the previous period <span className="text-muted-foreground">· desktop leads every week</span>
+				</span>
+			</CardFooter>
+		</Card>
+	)
+}
+```

package/llms/blocks/upload-list-block.md

@@ -0,0 +1,66 @@
+# UploadListBlock
+
+An upload queue: full-width Attachment rows — one uploading with progress and a cancel button, one finished with a success check.
+
+**Intent:** Reach for this under a FileDropzone, or anywhere files are in flight — a composer, an import step, a document form. For files attached to a message, Attachment chips in the composer fit better.
+
+**Block:** Media & files · card · designed for 16rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- Rows, not chips: each Attachment drops its chip cap (`max-w-none`) to fill the block's width.
+- The success check sits in a control-sized box so it lines up with the cancel button on the row above.
+- No card: Attachment rows are their own surfaces. Wrap the block in a Card if it needs a header.
+
+## Accessibility
+
+- Attachment announces upload progress; the cancel Button carries aria-label.
+- The finished row's check carries aria-label="Uploaded", so the state is spoken, not only coloured.
+
+## Source
+
+```tsx
+import { Attachment, Button, cn, Icon } from "@sableui/react"
+
+const uploading = { name: "brand-guidelines.pdf", meta: "4.2 MB of 6.8 MB", progress: 62 }
+const uploaded = { name: "cover-final.png", meta: "Uploaded · 2.1 MB" }
+
+export interface UploadListBlockProps {
+	className?: string
+	/** Called when the in-progress upload is cancelled. */
+	onCancel?: () => void
+}
+
+export function UploadListBlock({ className, onCancel }: UploadListBlockProps) {
+	return (
+		// An upload list, not chips: rows fill the block's width.
+		<div className={cn("flex w-full max-w-xs flex-col gap-2", className)}>
+			<Attachment
+				className="max-w-none"
+				name={uploading.name}
+				meta={uploading.meta}
+				status="uploading"
+				progress={uploading.progress}
+				actions={
+					<Button variant="ghost" size="icon-sm" aria-label="Cancel upload" onClick={onCancel}>
+						<Icon name="xmark" />
+					</Button>
+				}
+			/>
+			<Attachment
+				className="max-w-none"
+				name={uploaded.name}
+				icon="image-stack"
+				meta={uploaded.meta}
+				// The same box as the icon-sm button above, so the check centres on
+				// the cancel button's line instead of hugging the edge.
+				actions={
+					<span className="grid size-(--control-sm) place-items-center">
+						<Icon name="circle-check" className="text-success" aria-label="Uploaded" />
+					</span>
+				}
+			/>
+		</div>
+	)
+}
+```

package/llms/blocks/verify-code-block.md

@@ -0,0 +1,59 @@
+# VerifyCodeBlock
+
+A one-time-code card: where the code went, a six-slot OtpField grouped 3 + 3 under a visible label, and a quiet Resend.
+
+**Intent:** Reach for this for email or SMS verification, two-factor sign-in, or confirming a sensitive change. For a code someone copies out (a recovery key), show it with Code and a copy button instead.
+
+**Block:** Auth · card · designed for 18rem–24rem wide (fills its container up to the max)
+
+## Notes
+
+- No submit button: the code verifies the moment the last slot fills, which is what people expect from a code field.
+- The destination is named in the description, so a mistyped address is caught before the wait.
+- Resend is a ghost Button — present for the stuck case, never competing with the field.
+
+## Accessibility
+
+- OtpField names each slot ("Character 1 of 6") and accepts a pasted code into all six at once.
+- Field labels the group and reads the expiry as its description.
+
+## Source
+
+```tsx
+import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, Field, OtpField } from "@sableui/react"
+
+const sentTo = "ada@studio.com"
+
+export interface VerifyCodeBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet, Dialog or muted section that already frames it. */
+	framed?: boolean
+	/** Called with the code as soon as the last digit is entered. */
+	onVerify?: (code: string) => void
+	onResend?: () => void
+}
+
+export function VerifyCodeBlock({ className, framed = true, onVerify, onResend }: VerifyCodeBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-sm", className)}>
+			<CardHeader>
+				<CardTitle>Check your email</CardTitle>
+				<CardDescription>
+					We sent a 6-digit code to <span className="text-foreground">{sentTo}</span>.
+				</CardDescription>
+			</CardHeader>
+			<CardContent>
+				<Field label="Verification code" description="The code expires in 10 minutes.">
+					<OtpField length={6} groupSize={3} onValueComplete={(code: string) => onVerify?.(code)} />
+				</Field>
+			</CardContent>
+			<CardFooter className="justify-between gap-3">
+				<span className="text-caption text-muted-foreground">Didn’t get it?</span>
+				<Button variant="ghost" size="sm" onClick={onResend}>
+					Resend code
+				</Button>
+			</CardFooter>
+		</Card>
+	)
+}
+```

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/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/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>
+```