@sableui/react 0.2.0 → 0.3.1

package/llms/blocks/hero-block.md

@@ -0,0 +1,65 @@
+# HeroBlock
+
+A centred hero: an outline Badge eyebrow, the page's h1 at display size, a lede, a primary and an outline call to action, and an install command in a CodeBlock.
+
+**Intent:** Reach for this to open a product or developer-tool landing page. A brand page that leads with a product scene beside the headline is the BrandLandingPage page shell's hero.
+
+**Block:** Marketing · section
+
+## Notes
+
+- Copied from the LandingPage page shell's hero.
+- The headline is the page's only h1 — place one HeroBlock per page.
+- Two actions, one primary. The install command is the third, quieter way in for developers who already decided.
+- The lede is capped at the prose measure and the headline at max-w-4xl, so both stay readable on wide screens.
+
+## Accessibility
+
+- Calls to action are links styled as Buttons (render={<a />}), because they navigate.
+- The CodeBlock's copy button is labelled and announces when it has copied.
+
+## Source
+
+```tsx
+import { Badge, Button, cn, CodeBlock, Icon, Region, Row, Stack } from "@sableui/react"
+
+const hero = {
+	eyebrow: "Open source · MIT licensed",
+	title: "Product UI your agents can't get wrong",
+	lede: "Sable is a themeable React component library with enforced tokens, typography, and motion, documented for coding agents as carefully as for people.",
+	primary: { label: "Get started", href: "/docs/getting-started" },
+	secondary: { label: "Browse components", href: "/components" },
+	install: "pnpm add @sableui/react",
+}
+
+export interface HeroBlockProps {
+	className?: string
+}
+
+export function HeroBlock({ className }: HeroBlockProps) {
+	return (
+		<Region as="section" max="wide" className={cn("w-full py-16 sm:py-24", className)}>
+			<Stack gap={8} align="center">
+				<Stack gap={4} align="center" className="text-center">
+					<Badge appearance="outline" size="sm" icon={<Icon name="sparkles" />}>
+						{hero.eyebrow}
+					</Badge>
+					<h1 className="max-w-4xl text-balance text-display-lg sm:text-display-2xl">{hero.title}</h1>
+					<p className="max-w-(--measure-prose) text-pretty text-body-lg text-muted-foreground">{hero.lede}</p>
+					<Row gap={2} justify="center" wrap className="pt-2">
+						<Button size="cta" render={<a href={hero.primary.href} />}>
+							{hero.primary.label}
+						</Button>
+						<Button size="cta" variant="outline" render={<a href={hero.secondary.href} />}>
+							{hero.secondary.label}
+						</Button>
+					</Row>
+				</Stack>
+				<div className="w-full max-w-sm">
+					<CodeBlock prompt="$" code={hero.install} />
+				</div>
+			</Stack>
+		</Region>
+	)
+}
+```

package/llms/blocks/invite-team-block.md

@@ -0,0 +1,61 @@
+# InviteTeamBlock
+
+An invite card: who is already on the team as an AvatarGroup, and an email field with Send.
+
+**Intent:** Reach for this for team or project invites in onboarding, an empty workspace, or a settings section. For managing an existing member list with roles, use a CardList of Entity rows instead.
+
+**Block:** Settings & team · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The field and Send are a <form>, so Enter sends; `onSend` receives the typed address.
+- The AvatarGroup ring matches the card surface when framed and inherits the host surface when not.
+
+## Accessibility
+
+- The AvatarGroup carries an aria-label with the count, so the stack reads as one item, not four initials.
+- The email Input carries aria-label; there is no visible label in this compact layout.
+
+## Source
+
+```tsx
+import { Avatar, AvatarGroup, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, cn, Input } from "@sableui/react"
+
+const collaborators = ["MO", "SR", "JL", "AK"]
+
+export interface InviteTeamBlockProps {
+	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 address typed, on Send or Enter. */
+	onSend?: (email: string) => void
+}
+
+export function InviteTeamBlock({ className, framed = true, onSend }: InviteTeamBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardHeader>
+				<CardTitle>Invite your team</CardTitle>
+				<CardDescription>Collaborators can edit every project.</CardDescription>
+			</CardHeader>
+			<CardContent className="flex flex-col gap-4">
+				<AvatarGroup aria-label={`${collaborators.length} collaborators`} size="sm" surface={framed ? "card" : undefined}>
+					{collaborators.map((initials) => (
+						<Avatar key={initials} fallback={initials} alt={initials} />
+					))}
+				</AvatarGroup>
+				<form
+					className="flex gap-2"
+					onSubmit={(event) => {
+						event.preventDefault()
+						onSend?.(String(new FormData(event.currentTarget).get("email") ?? ""))
+					}}
+				>
+					<Input name="email" type="email" placeholder="name@company.com" aria-label="Email address" />
+					<Button type="submit">Send</Button>
+				</form>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/invoice-history-block.md

@@ -0,0 +1,84 @@
+# InvoiceHistoryBlock
+
+A billing history card: a flush Table of date, plan, amount and status per invoice, with a download button on each row.
+
+**Intent:** Reach for this in billing settings, under the current plan. For a long, filterable history (hundreds of rows, date ranges, export), use DataTable on its own page.
+
+**Block:** Commerce · card · designed for 20rem–42rem wide (fills its container up to the max)
+
+## Notes
+
+- The table runs edge to edge (CardContent flush); its first and last columns still line up with the card header's padding.
+- Amounts are a numeric column — right-aligned with tabular figures — so they compare by eye.
+- On a narrow screen the table scrolls sideways inside the card (with a quiet scrollbar) rather than squeezing its columns.
+
+## Accessibility
+
+- The download column has a screen-reader-only header, and each button names its invoice ("Download INV-0042").
+- Status is text in a Badge; the dot's colour only reinforces it.
+
+## Source
+
+```tsx
+import { Badge, Button, Card, CardContent, CardDescription, CardHeader, CardTitle, cn, Icon, Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "@sableui/react"
+
+const invoices = [
+	{ id: "INV-0042", date: "Oct 1, 2026", plan: "Studio · yearly", amount: "$192.00", status: "Paid" },
+	{ id: "INV-0031", date: "Sep 1, 2026", plan: "Studio · monthly", amount: "$20.00", status: "Paid" },
+	{ id: "INV-0027", date: "Aug 1, 2026", plan: "Studio · monthly", amount: "$20.00", status: "Refunded" },
+	{ id: "INV-0019", date: "Jul 1, 2026", plan: "Starter", amount: "$0.00", status: "Paid" },
+]
+
+export interface InvoiceHistoryBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+	/** Called with the invoice id to download. */
+	onDownload?: (id: string) => void
+}
+
+export function InvoiceHistoryBlock({ className, framed = true, onDownload }: InvoiceHistoryBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-2xl", className)}>
+			<CardHeader>
+				<CardTitle render={<h2 />}>Invoices</CardTitle>
+				<CardDescription>Sent to billing@studio.com on the 1st of each month.</CardDescription>
+			</CardHeader>
+			<CardContent flush className="overflow-x-auto scrollbar-quiet">
+				<Table>
+					<TableHeader>
+						<TableRow>
+							<TableHead>Date</TableHead>
+							<TableHead>Plan</TableHead>
+							<TableHead numeric>Amount</TableHead>
+							<TableHead>Status</TableHead>
+							<TableHead className="w-0">
+								<span className="sr-only">Download</span>
+							</TableHead>
+						</TableRow>
+					</TableHeader>
+					<TableBody>
+						{invoices.map((invoice) => (
+							<TableRow key={invoice.id}>
+								<TableCell className="whitespace-nowrap">{invoice.date}</TableCell>
+								<TableCell className="text-muted-foreground">{invoice.plan}</TableCell>
+								<TableCell numeric>{invoice.amount}</TableCell>
+								<TableCell>
+									<Badge appearance="plain" tone={invoice.status === "Paid" ? "success" : "neutral"} dot>
+										{invoice.status}
+									</Badge>
+								</TableCell>
+								<TableCell>
+									<Button variant="ghost" size="icon-sm" aria-label={`Download ${invoice.id}`} onClick={() => onDownload?.(invoice.id)}>
+										<Icon name="download" />
+									</Button>
+								</TableCell>
+							</TableRow>
+						))}
+					</TableBody>
+				</Table>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/kpi-sparkline-block.md

@@ -0,0 +1,57 @@
+# KpiSparklineBlock
+
+A KPI row with trends: three stat cards, each the value in the metric mono tier, a Sparkline of its last twelve weeks, and the change as a Badge.
+
+**Intent:** Reach for this at the top of a dashboard or a landing page's proof section, where each number needs its recent shape. Without the trend, StatRowBlock is calmer; for one headline trend, TrafficTrendBlock.
+
+**Block:** Dashboard · section
+
+## Notes
+
+- Each sparkline is coloured by what its measure is, and the change Badge by whether it is good: churn falling is good news in a warning-toned trend.
+- The sparklines draw on as the row scrolls into view.
+- One column on a phone, three from sm.
+
+## Accessibility
+
+- Each Sparkline is an image named by the measure and the period, with its range spoken.
+- The change is stated in text (+8.2% vs last quarter) with an arrow icon; colour only reinforces it.
+
+## Source
+
+```tsx
+import { Badge, Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle, cn, Grid, Icon, Sparkline } from "@sableui/react"
+
+const kpis = [
+	{ label: "Revenue", value: "$18,240", delta: "+8.2%", up: true, trend: [12, 14, 13, 17, 16, 19, 18, 21, 20, 24, 23, 26], tone: "success" },
+	{ label: "Active users", value: "3,912", delta: "+3.1%", up: true, trend: [30, 31, 29, 33, 34, 33, 36, 35, 37, 38, 37, 39], tone: "info" },
+	{ label: "Churn", value: "4.1%", delta: "−0.6%", up: false, trend: [9, 8, 9, 7, 8, 6, 7, 5, 6, 4, 5, 4], tone: "warning" },
+] as const
+
+export interface KpiSparklineBlockProps {
+	className?: string
+}
+
+export function KpiSparklineBlock({ className }: KpiSparklineBlockProps) {
+	return (
+		<Grid cols={{ base: 1, sm: 3 }} gap={3} className={cn("w-full", className)}>
+			{kpis.map((kpi) => (
+				<Card key={kpi.label}>
+					<CardHeader>
+						<CardDescription>{kpi.label}</CardDescription>
+						<CardTitle className="text-mono-xl">{kpi.value}</CardTitle>
+						<CardAction>
+							<Sparkline label={`${kpi.label}, last 12 weeks`} data={[...kpi.trend]} variant="area" tone={kpi.tone} />
+						</CardAction>
+					</CardHeader>
+					<CardContent>
+						<Badge tone={kpi.up ? "success" : "neutral"} size="sm" icon={<Icon name={kpi.up ? "arrow-up" : "arrow-down"} />}>
+							{kpi.delta} vs last quarter
+						</Badge>
+					</CardContent>
+				</Card>
+			))}
+		</Grid>
+	)
+}
+```

package/llms/blocks/media-player-block.md

@@ -0,0 +1,100 @@
+# MediaPlayerBlock
+
+A now-playing card: cover, title and artist as an Entity with a Like action, a position Slider with elapsed and remaining time, and previous / play-pause / next.
+
+**Intent:** Reach for this for audio or video playback controls outside the media itself — a mini player, a podcast card, a preview in a feed. Playback over the video frame is the Video component's own chrome.
+
+**Block:** Media & files · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- Play/pause is the one filled control, centred between two ghost skips.
+- Times are `text-mono-caption`, so the digits do not shift as they count.
+- The cover is painted from the palette as a placeholder; swap it for the real artwork.
+
+## Accessibility
+
+- Every icon-only Button carries aria-label, and play/pause's label follows its state.
+- The Slider carries aria-label="Position". Give it aria-valuetext in your player ("1:24 of 3:40") so the position is read as time, not a percentage.
+
+## Source
+
+```tsx
+import { useState } from "react"
+import { Button, Card, CardContent, cn, Entity, Icon, Slider } from "@sableui/react"
+
+const track = { title: "Low tide, high noon", artist: "Juno Avery", position: 38, elapsed: "1:24", remaining: "-2:16" }
+
+/**
+ * Placeholder cover painted from the palette — the theme's decorative tones
+ * over the brand, so it follows every look. Replace with the cover image.
+ */
+const ART_TONES = ["info", "collectible", "edition"]
+const ART_SPOTS = [[20, 20, 70], [85, 30, 60], [60, 90, 65]]
+const cover = [
+	...ART_SPOTS.map(
+		([x, y, reach], i) =>
+			// design-lint-disable-next-line inline-color -- relative colour derived from the theme's own --tone token, so it follows every look
+			`radial-gradient(in oklab at ${x}% ${y}%, oklch(from var(--tone-${ART_TONES[i % ART_TONES.length]}) clamp(0.5, calc(l + 0.16), 0.9) max(calc(c * 1.25), 0.1) h), transparent ${reach}%)`,
+	),
+	"var(--primary)",
+].join(", ")
+
+export interface MediaPlayerBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet or muted section that already frames it. */
+	framed?: boolean
+	/** Called with the new playing state. */
+	onPlayingChange?: (playing: boolean) => void
+	onPrevious?: () => void
+	onNext?: () => void
+}
+
+export function MediaPlayerBlock({ className, framed = true, onPlayingChange, onPrevious, onNext }: MediaPlayerBlockProps) {
+	const [playing, setPlaying] = useState(true)
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardContent className="flex flex-col gap-4">
+				{/* Entity's own row padding is for lists; inside a card's content the
+				    card already pads it. */}
+				<Entity
+					className="p-0"
+					leading={<div aria-hidden className="size-14 rounded-md" style={{ background: cover }} />}
+					title={track.title}
+					subtitle={track.artist}
+					action={
+						<Button variant="ghost" size="icon-sm" aria-label="Like">
+							<Icon name="heart" />
+						</Button>
+					}
+				/>
+				<div className="flex flex-col gap-1.5">
+					<Slider defaultValue={track.position} aria-label="Position" />
+					<div className="flex justify-between text-mono-caption text-muted-foreground">
+						<span>{track.elapsed}</span>
+						<span>{track.remaining}</span>
+					</div>
+				</div>
+				<div className="flex items-center justify-center gap-3">
+					<Button variant="ghost" size="icon" aria-label="Previous" onClick={onPrevious}>
+						<Icon name="previous" variant="solid" />
+					</Button>
+					<Button
+						size="icon"
+						aria-label={playing ? "Pause" : "Play"}
+						onClick={() => {
+							setPlaying(!playing)
+							onPlayingChange?.(!playing)
+						}}
+					>
+						<Icon name={playing ? "pause" : "play"} variant="solid" />
+					</Button>
+					<Button variant="ghost" size="icon" aria-label="Next" onClick={onNext}>
+						<Icon name="next" variant="solid" />
+					</Button>
+				</div>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/newsletter-block.md

@@ -0,0 +1,64 @@
+# NewsletterBlock
+
+A newsletter sign-up card: the list's name, what it sends and how often, and an email field with Subscribe.
+
+**Intent:** Reach for this in a footer, at the end of an article, or beside a changelog. Creating an account is SignUpBlock; inviting a teammate is InviteTeamBlock.
+
+**Block:** Marketing · card · designed for 18rem–24rem wide (fills its container up to the max)
+
+## Notes
+
+- Copied from the BrandLandingPage page shell's footer.
+- The description says how often mail arrives — the one thing people want to know before they subscribe.
+- The field and button sit side by side from sm up and stack on a phone, where the button goes full width.
+
+## Accessibility
+
+- The input has a real (visually hidden) <label>, not just a placeholder.
+- The CardTitle renders an h2, so the sign-up is reachable by heading in a footer.
+
+## Source
+
+```tsx
+import { useId } from "react"
+import { Button, Card, CardContent, CardDescription, CardHeader, CardTitle, cn, Input } from "@sableui/react"
+
+const newsletter = { title: "The Cove digest", body: "One note a month on trusted workflows and product releases." }
+
+export interface NewsletterBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a footer or muted section that already frames it. */
+	framed?: boolean
+	/** Called with the address on Subscribe or Enter. */
+	onSubscribe?: (email: string) => void
+}
+
+export function NewsletterBlock({ className, framed = true, onSubscribe }: NewsletterBlockProps) {
+	const emailId = useId()
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-sm", className)}>
+			<CardHeader>
+				<CardTitle render={<h2 />}>{newsletter.title}</CardTitle>
+				<CardDescription>{newsletter.body}</CardDescription>
+			</CardHeader>
+			<CardContent>
+				<form
+					className="grid gap-2 sm:grid-cols-[1fr_auto]"
+					onSubmit={(event) => {
+						event.preventDefault()
+						onSubscribe?.(String(new FormData(event.currentTarget).get("email") ?? ""))
+					}}
+				>
+					<label htmlFor={emailId} className="sr-only">
+						Work email
+					</label>
+					<Input id={emailId} name="email" type="email" autoComplete="email" placeholder="you@company.com" required />
+					<Button type="submit" className="w-full sm:w-auto">
+						Subscribe
+					</Button>
+				</form>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/not-found-block.md

@@ -0,0 +1,56 @@
+# NotFoundBlock
+
+A not-found page body: the status code in mono, a plain-language h1, what probably happened, and two ways on — home and search.
+
+**Intent:** Reach for this as the body of a 404 route. An empty list or a search with no results inside a working page is EmptyState, not this.
+
+**Block:** System · section
+
+## Notes
+
+- The heading says what happened in words; the code is a small mono label for people who look for it.
+- Two ways on, one primary. Never a dead end with only the browser's back button.
+- Capped at the `form` region width, so the short message stays a tight, centred column.
+
+## Accessibility
+
+- It renders the page's h1 — use it as the route's main content, inside <main>.
+- Both actions are links styled as Buttons, because they navigate.
+
+## Source
+
+```tsx
+import { Button, cn, Icon, Region, Row, Stack } from "@sableui/react"
+
+const notFound = {
+	code: "404",
+	title: "This page isn't here",
+	body: "It may have moved, or the link may be mistyped. Check the address, or head back to somewhere you know.",
+	home: { label: "Go home", href: "/" },
+	help: { label: "Search the docs", href: "/docs" },
+}
+
+export interface NotFoundBlockProps {
+	className?: string
+}
+
+export function NotFoundBlock({ className }: NotFoundBlockProps) {
+	return (
+		<Region as="section" max="form" className={cn("w-full py-16 sm:py-24", className)}>
+			<Stack gap={4} align="center" className="text-center">
+				<p className="text-mono-md text-muted-foreground">{notFound.code}</p>
+				<h1 className="text-balance text-heading-1">{notFound.title}</h1>
+				<p className="text-pretty text-body-md text-muted-foreground">{notFound.body}</p>
+				<Row gap={2} justify="center" wrap className="pt-2">
+					<Button iconStart={<Icon name="home" />} render={<a href={notFound.home.href} />}>
+						{notFound.home.label}
+					</Button>
+					<Button variant="outline" iconStart={<Icon name="search" />} render={<a href={notFound.help.href} />}>
+						{notFound.help.label}
+					</Button>
+				</Row>
+			</Stack>
+		</Region>
+	)
+}
+```

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

@@ -0,0 +1,63 @@
+# NotificationListBlock
+
+An activity list: Entity rows with the actor's Avatar, who did what, and a compact time with an unread StatusDot.
+
+**Intent:** Reach for this for a notifications popover, a recent-activity card or an inbox preview. A full inbox with selection and bulk actions is a ListDetailPage.
+
+**Block:** Social & messaging · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- Rows are Card + CardList + Entity, inset from the card's padding at any density.
+- Unread is a quiet info dot after the time — the list stays calm when most items are unread.
+- framed={false} drops the surface for a Popover, which already is one.
+
+## Accessibility
+
+- The unread dot is decorative; each unread row also carries a screen-reader-only "(unread)" after the name.
+- Each Avatar's alt is the actor's name.
+
+## Source
+
+```tsx
+import { Avatar, Card, CardList, cn, Entity, StatusDot } from "@sableui/react"
+
+const notifications = [
+	{ initials: "MO", name: "Mara Okafor", what: "collected your edition", when: "2m", unread: true },
+	{ initials: "SR", name: "Sam Rivera", what: "left a comment on Dusk", when: "1h", unread: false },
+]
+
+export interface NotificationListBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Popover or Sheet that already frames it. */
+	framed?: boolean
+}
+
+export function NotificationListBlock({ className, framed = true }: NotificationListBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs overflow-hidden", className)}>
+			<CardList>
+				{notifications.map((n) => (
+					<Entity
+						key={n.name}
+						leading={<Avatar size="sm" fallback={n.initials} alt={n.name} />}
+						title={
+							<>
+								{n.name}
+								{n.unread ? <span className="sr-only"> (unread)</span> : null}
+							</>
+						}
+						subtitle={n.what}
+						action={
+							<span className="flex items-center gap-1.5 text-caption text-muted-foreground">
+								{n.when}
+								{n.unread ? <StatusDot tone="info" /> : null}
+							</span>
+						}
+					/>
+				))}
+			</CardList>
+		</Card>
+	)
+}
+```

package/llms/blocks/notification-settings-block.md

@@ -0,0 +1,54 @@
+# NotificationSettingsBlock
+
+A preferences card: Entity rows in a CardList, each with a title, a one-line detail and a Switch that applies instantly.
+
+**Intent:** Reach for this for any short list of on/off preferences — notifications, privacy, feature flags in a settings section. For a full settings route with a section rail, start from the SettingsPage page shell.
+
+**Block:** Settings & team · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- Switches apply the moment they change; never pair them with a Save button. `onChange` receives the row id and the new state.
+- Rows are Card + CardList + Entity, so they inset with the card's padding at any density.
+
+## Accessibility
+
+- Each Switch takes its row title as aria-label, since the Entity title is not a <label>.
+- Keep details to one line — Entity truncates its subtitle.
+
+## Source
+
+```tsx
+import { Card, CardList, cn, Entity, Switch } from "@sableui/react"
+
+const preferences = [
+	{ id: "email", title: "Email notifications", detail: "Replies and mentions", on: true },
+	{ id: "push", title: "Push notifications", detail: "On this device", on: false },
+	{ id: "digest", title: "Weekly digest", detail: "Every Monday", on: true },
+]
+
+export interface NotificationSettingsBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet, Dialog or muted section that already frames it. */
+	framed?: boolean
+	/** Called the moment a switch changes. Toggles apply instantly; there is no Save. */
+	onChange?: (id: string, on: boolean) => void
+}
+
+export function NotificationSettingsBlock({ className, framed = true, onChange }: NotificationSettingsBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs overflow-hidden", className)}>
+			<CardList>
+				{preferences.map((p) => (
+					<Entity
+						key={p.id}
+						title={p.title}
+						subtitle={p.detail}
+						action={<Switch defaultChecked={p.on} aria-label={p.title} onCheckedChange={(on: boolean) => onChange?.(p.id, on)} />}
+					/>
+				))}
+			</CardList>
+		</Card>
+	)
+}
+```

package/llms/blocks/order-tracking-block.md

@@ -0,0 +1,62 @@
+# OrderTrackingBlock
+
+An order status card: order number, item and a status Badge in the header over a vertical dot Stepper of delivery milestones.
+
+**Intent:** Reach for this for anything that moves through known stages — a delivery, an application, a review, a deployment. For an open-ended activity log, use a list of Entity rows with timestamps instead.
+
+**Block:** Commerce · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The Stepper's `current` is the step under way; finished steps show their timestamp and future steps show none.
+- The status Badge restates the current stage in one word so the card scans without reading the steps.
+
+## Accessibility
+
+- The Stepper is labelled "Delivery status" and marks the current step for assistive tech.
+- The Badge's tone is backed by its text; colour alone never carries the status.
+
+## Source
+
+```tsx
+import { Badge, Card, CardAction, CardContent, CardDescription, CardHeader, CardTitle, cn, Stepper, StepperItem } from "@sableui/react"
+
+// design-lint-disable-next-line inline-color -- an order number, not a colour
+const order = { number: "Order #2048", item: "Giclée print, 18 × 24 in", status: "In transit", current: 2 }
+
+const steps = [
+	{ title: "Order placed", detail: "Oct 9, 10:14 AM" },
+	{ title: "Printed and packed", detail: "Oct 10, 4:02 PM" },
+	{ title: "Out for delivery", detail: "Arriving today by 6 PM" },
+	{ title: "Delivered", detail: undefined },
+]
+
+export interface OrderTrackingBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a Sheet or muted section that already frames it. */
+	framed?: boolean
+}
+
+export function OrderTrackingBlock({ className, framed = true }: OrderTrackingBlockProps) {
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardHeader>
+				<CardTitle>{order.number}</CardTitle>
+				<CardDescription>{order.item}</CardDescription>
+				<CardAction>
+					<Badge tone="warning" size="sm">
+						{order.status}
+					</Badge>
+				</CardAction>
+			</CardHeader>
+			<CardContent>
+				<Stepper orientation="vertical" indicator="dot" current={order.current} aria-label="Delivery status">
+					{steps.map((step) => (
+						<StepperItem key={step.title} title={step.title} description={step.detail} />
+					))}
+				</Stepper>
+			</CardContent>
+		</Card>
+	)
+}
+```