@sableui/react 0.1.1 → 0.3.0

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>
+	)
+}
+```

package/llms/blocks/pricing-card-block.md

@@ -0,0 +1,82 @@
+# PricingCardBlock
+
+A single-plan pricing card: a Monthly/Yearly ToggleGroup, the price and billing note, a checked feature list, and one full-width call to action.
+
+**Intent:** Reach for this when one plan is on offer — an upgrade prompt, a paywall, a plan summary in billing settings. Comparing several tiers side by side is a pricing table, not three of these.
+
+**Block:** Commerce · card · designed for 18rem–20rem wide (fills its container up to the max)
+
+## Notes
+
+- The period switch is a ToggleGroup (a segmented control), not Tabs: it changes a value in place rather than showing another panel.
+- The price is a heading tier because it is the card's headline; its unit and billing note sit beside and below it in muted body text.
+- `onStart` receives the period showing, so checkout opens on the plan the person was looking at.
+
+## Accessibility
+
+- The ToggleGroup carries aria-label="Billing period"; each Toggle's text is its name.
+- The check icons are decorative beside each feature's text.
+
+## Source
+
+```tsx
+import { useState } from "react"
+import { Button, Card, CardContent, cn, Icon, Toggle, ToggleGroup } from "@sableui/react"
+
+const plan = {
+	monthly: { price: "$20", note: "Billed monthly. Cancel anytime." },
+	yearly: { price: "$16", note: "Billed $192 yearly. You save 20%." },
+	features: ["Unlimited projects", "Version history", "Priority support"],
+}
+
+type Period = "monthly" | "yearly"
+
+export interface PricingCardBlockProps {
+	className?: string
+	/** false drops the card's surface and border — for a muted section that already frames it. */
+	framed?: boolean
+	/** Called with the billing period showing when the trial starts. */
+	onStart?: (period: Period) => void
+}
+
+export function PricingCardBlock({ className, framed = true, onStart }: PricingCardBlockProps) {
+	const [period, setPeriod] = useState<Period>("yearly")
+	return (
+		<Card variant={framed ? "default" : "flat"} className={cn("w-full max-w-xs", className)}>
+			<CardContent className="flex flex-col gap-5">
+				<ToggleGroup
+					value={[period]}
+					onValueChange={(v: unknown[]) => v[0] && setPeriod(v[0] as Period)}
+					aria-label="Billing period"
+					className="w-full"
+				>
+					<Toggle value="monthly" className="flex-1">
+						Monthly
+					</Toggle>
+					<Toggle value="yearly" className="flex-1">
+						Yearly
+					</Toggle>
+				</ToggleGroup>
+				<div className="flex flex-col gap-1">
+					<div className="flex items-baseline gap-1.5">
+						<span className="text-heading-2">{plan[period].price}</span>
+						<span className="text-body-sm text-muted-foreground">per seat / month</span>
+					</div>
+					<span className="text-body-sm text-muted-foreground">{plan[period].note}</span>
+				</div>
+				<ul className="flex flex-col gap-2 text-body-sm">
+					{plan.features.map((feature) => (
+						<li key={feature} className="flex items-center gap-2">
+							<Icon name="check" className="text-success" />
+							{feature}
+						</li>
+					))}
+				</ul>
+				<Button className="w-full" onClick={() => onStart?.(period)}>
+					Start free trial
+				</Button>
+			</CardContent>
+		</Card>
+	)
+}
+```

package/llms/blocks/pricing-table-block.md

@@ -0,0 +1,129 @@
+# PricingTableBlock
+
+A three-tier pricing section: heading, a Monthly/Yearly ToggleGroup, and three equal-height plan cards with the recommended one outlined in primary and badged "Most popular".
+
+**Intent:** Reach for this on a pricing page or the pricing band of a landing page, to compare plans side by side. A single plan on offer (an upgrade prompt, a paywall) is PricingCardBlock.
+
+**Block:** Commerce · section
+
+## Notes
+
+- One featured tier at most: it takes the primary button and a primary outline; the others take outline buttons so the recommendation is unmistakable.
+- Cards stretch to the tallest one and push their buttons to the bottom, so the calls to action line up across the row.
+- The yearly saving is stated in the toggle itself, where the choice is made. `onChoose` receives the tier id and the period showing.
+
+## Accessibility
+
+- Each plan is an <article> with an h3 under the section's h2, so the tiers are navigable by heading.
+- The ToggleGroup is labelled "Billing period"; prices update in place and stay in the reading order of each card.
+
+## Source
+
+```tsx
+import { useState, useId } from "react"
+import { Badge, Button, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, cn, Grid, Icon, Region, Stack, Toggle, ToggleGroup } from "@sableui/react"
+
+const tiers = [
+	{
+		id: "starter",
+		name: "Starter",
+		blurb: "For one person shipping their first editions.",
+		monthly: 0,
+		yearly: 0,
+		cta: "Start for free",
+		featured: false,
+		features: ["3 live editions", "Collector profiles", "Community support"],
+	},
+	{
+		id: "studio",
+		name: "Studio",
+		blurb: "For working artists with a steady release schedule.",
+		monthly: 20,
+		yearly: 16,
+		cta: "Start free trial",
+		featured: true,
+		features: ["Unlimited editions", "Scheduled drops", "Sales analytics", "Priority support"],
+	},
+	{
+		id: "collective",
+		name: "Collective",
+		blurb: "For galleries and teams releasing together.",
+		monthly: 48,
+		yearly: 40,
+		cta: "Talk to sales",
+		featured: false,
+		features: ["Everything in Studio", "Up to 10 seats", "Shared payouts", "Roles and approvals"],
+	},
+]
+
+type Period = "monthly" | "yearly"
+
+export interface PricingTableBlockProps {
+	className?: string
+	/** Called with the chosen tier and the billing period showing. */
+	onChoose?: (tier: string, period: Period) => void
+}
+
+export function PricingTableBlock({ className, onChoose }: PricingTableBlockProps) {
+	const [period, setPeriod] = useState<Period>("yearly")
+	const titleId = useId()
+	return (
+		<Region as="section" aria-labelledby={titleId} max="wide" className={cn("w-full py-16", className)}>
+			<Stack gap={10}>
+				<Stack gap={4} align="center" className="text-center">
+					<h2 id={titleId} className="text-balance text-heading-1">
+						Pricing that grows with your practice
+					</h2>
+					<p className="max-w-(--measure-prose) text-body-lg text-muted-foreground">
+						Every plan includes unlimited collectors and no fees on your first $1,000 in sales.
+					</p>
+					<ToggleGroup value={[period]} onValueChange={(v: unknown[]) => v[0] && setPeriod(v[0] as Period)} aria-label="Billing period">
+						<Toggle value="monthly">Monthly</Toggle>
+						<Toggle value="yearly">Yearly · save 20%</Toggle>
+					</ToggleGroup>
+				</Stack>
+				<Grid cols={{ base: 1, md: 3 }} gap={4} className="items-stretch">
+					{tiers.map((tier) => (
+						<Card
+							key={tier.id}
+							render={<article />}
+							className={cn("flex flex-col", tier.featured && "border-primary ring-1 ring-primary")}
+						>
+							<CardHeader>
+								<CardTitle render={<h3 />}>{tier.name}</CardTitle>
+								<CardDescription>{tier.blurb}</CardDescription>
+								{tier.featured ? (
+									<CardAction>
+										<Badge tone="edition" size="sm">
+											Most popular
+										</Badge>
+									</CardAction>
+								) : null}
+							</CardHeader>
+							<CardContent className="flex flex-1 flex-col gap-5">
+								<div className="flex items-baseline gap-1.5">
+									<span className="text-heading-2">${tier[period]}</span>
+									<span className="text-body-sm text-muted-foreground">per seat / month</span>
+								</div>
+								<ul className="flex flex-col gap-2 text-body-sm">
+									{tier.features.map((feature) => (
+										<li key={feature} className="flex items-center gap-2">
+											<Icon name="check" className="text-success" />
+											{feature}
+										</li>
+									))}
+								</ul>
+							</CardContent>
+							<CardFooter>
+								<Button className="w-full" variant={tier.featured ? "primary" : "outline"} onClick={() => onChoose?.(tier.id, period)}>
+									{tier.cta}
+								</Button>
+							</CardFooter>
+						</Card>
+					))}
+				</Grid>
+			</Stack>
+		</Region>
+	)
+}
+```