themelia-ui 1.0.0

package/docs/build/recipes.md

@@ -0,0 +1,4392 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# Recipes
+
+374 adaptable live-preview snippets, taken from the pages that render them —
+so a recipe here and the example on the page cannot drift apart. Excerpts may depend on
+surrounding values supplied by the application. Each section names the exact
+import and stylesheet for the family.
+
+**What the application still owns:** data fetching, routing, persistence, translation and
+domain state. Every snippet below assumes those arrive as props, callbacks or accessors.
+
+## (no family)
+
+Preview route: Scale & density — `/scale`
+
+### The factor
+
+```tsx
+<UIProvider config={{ scale: 0.875 }}>
+  <Toolbar />
+</UIProvider>
+```
+
+### Why not size props
+
+```tsx
+{/* smaller type, control geometry untouched */}
+<UIProvider config={{ typography: { scale: 0.875 } }}>…</UIProvider>
+
+{/* denser geometry, type held at its default */}
+<UIProvider config={{ scale: 0.875, typography: { scale: 1 } }}>…</UIProvider>
+```
+
+### Two levels of control
+
+```tsx
+/* everything denser */
+<UIProvider config={{ scale: 0.875 }}>
+
+/* heights and rows only — gaps untouched */
+<Scope vars={{ "--density-scale": 0.875 }}>
+
+/* gaps and padding only — control heights untouched */
+<Scope vars={{ "--space-scale": 0.875 }}>
+
+/* one measurement, leaving everything else alone */
+<Scope vars={{ "--button-px": "1.5rem" }}>
+
+/* a plain div does NOT work: overriding a factor needs a scope
+   boundary, or the measurements above it have already resolved. */
+```
+
+### Why a factor and not a size prop
+
+```tsx
+<UIProvider config={{ scale: 1.125 }}>
+  <Page>
+    <UIProvider config={{ scale: 0.875 }}>
+      <Toolbar />
+    </UIProvider>
+  </Page>
+</UIProvider>
+```
+
+### Density presets
+
+```tsx
+<UIProvider config={{ density: "compact" }}>…</UIProvider>
+
+{/* or, with no provider at all */}
+<div data-density="compact">…</div>
+```
+
+### Semantic tier
+
+```tsx
+<UIProvider config={{ theme: { colors: { primary: "oklch(0.55 0.2 25)" } } }}>
+```
+
+## admin/patterns/commerce
+
+```tsx
+import { … } from "themelia-ui/admin/patterns/commerce"
+import "themelia-ui/admin/patterns/commerce.css"
+```
+
+Preview route: Catalogue & partners — `/blocks-catalogue`
+
+### SeoListing
+
+```tsx
+import { calculateSeoScore } from "themelia-ui/admin/patterns/commerce"
+
+const score = calculateSeoScore({ title, description, permalink, baseUrl, keyword })
+<SeoListing listing={listing} score={score} onEdit={edit} />
+```
+
+### InventorySection
+
+```tsx
+<InventorySection
+  value={value}
+  sections={["summary", "identity", "tracking"]}
+  onFieldChange={({ field, value }) => update(field, value)}
+/>
+```
+
+### VendorProfile
+
+```tsx
+<VendorProfile name="Northwind Traders" earnings="48,200.00 EUR" metrics={metrics} stats={stats} />
+```
+
+### BookingCard
+
+```tsx
+<BookingCard title="Reservation #4417" details={details} actionLabel="Open booking" onAction={open} />
+```
+
+### CartSummary
+
+```tsx
+<CartSummary items={items} subtotal="258.00 EUR" discount="50.00 EUR" total="264.40 EUR" />
+```
+
+### TaxBreakdown
+
+```tsx
+<TaxBreakdown subtotal="258.00 EUR" taxes={taxes} totalTax="52.89 EUR" total="310.89 EUR" />
+```
+
+### DiscountStack
+
+```tsx
+<DiscountStack discounts={discounts} totalSavings="50.00 EUR" />
+```
+
+### CodeEntry
+
+```tsx
+<CodeEntry onApply={apply} />
+<CodeEntry kind="gift" appliedCode="GC-4417-92AB" balance="45.00 EUR" onRemove={remove} />
+```
+
+### OrderStatusCard
+
+```tsx
+<OrderStatusCard orderNumber="#1041" status="shipped" events={events} eta="18 Aug" />
+```
+
+### ShipmentTracking
+
+```tsx
+<ShipmentTracking trackingNumber="1Z999AA1…" carrier="UPS" status="inTransit" steps={steps} />
+```
+
+### RefundStatus
+
+```tsx
+<RefundStatus stage="processing" amount="124.00 EUR" reason="Damaged on arrival" />
+```
+
+### InvoiceHeader
+
+```tsx
+<InvoiceHeader invoiceNumber="INV-2026-0114" status="overdue" from={from} to={to} amountDue="3,120.00 EUR" />
+```
+
+### InvoiceLineItems
+
+```tsx
+<InvoiceLineItems currency="EUR" taxRate={0.2} lines={lines} />
+```
+
+### InvoiceMini
+
+```tsx
+<InvoiceMini invoiceNumber="INV-0114" status="overdue" customerName="…" total="3,120.00 EUR" />
+```
+
+### AddressCard
+
+```tsx
+<AddressCard kind="shipping" name="Alice Mercer" line1="14 Kingsway" city="London" country="United Kingdom" isDefault />
+```
+
+### PaymentMethodCard
+
+```tsx
+<PaymentMethodCard brand="visa" last4="4417" expiry="09/28" isDefault onChange={change} />
+```
+
+### PaymentTimeline
+
+```tsx
+<PaymentTimeline events={events} />
+```
+
+### SubscriptionSummary
+
+```tsx
+<SubscriptionSummary planName="Scale" price="240.00 EUR" cycle="Per month" nextBillingDate="01 Sep 2026" />
+```
+
+### InventoryLevel
+
+```tsx
+<InventoryLevel productName="Merino crew neck" stock={8} reorderLevel={12} maxStock={120} />
+```
+
+### UpcomingBookings
+
+```tsx
+<UpcomingBookings bookings={bookings} boxedDate />
+```
+
+### LoyaltyPoints
+
+```tsx
+<LoyaltyPoints balance={4830} tier="Platinum" movements={movements} onRedeem={redeem} />
+```
+
+### Two statuses, not one
+
+```tsx
+<OrderHeader
+  orderNumber="1036"
+  paymentStatus="refunded"
+  fulfillmentStatus="unfulfilled"
+  placedAt="December 21, 2025 at 10:10 pm"
+  source="Simple Sample Data (via import)"
+/>
+```
+
+### Fulfillment groups
+
+```tsx
+<FulfillmentGroup
+  status="unfulfilled"
+  location="Bul Bulgaria 111"
+  notice="Shipping not required"
+  items={lines}
+  actions={[{ id: "fulfil", label: "Mark as fulfilled", onClick: fulfil }]}
+/>
+```
+
+### A line, and what a consumer attaches to it
+
+```tsx
+<OrderLineItem
+  {...line}
+  properties={[
+    { label: "Engraving", value: "A. MERCER" },
+    { label: "Gift message", value: "Happy birthday" },
+  ]}
+/>
+```
+
+### OrderSummary
+
+```tsx
+<OrderSummary
+  goods={[{ label: "Subtotal", note: "3 items", amount: "€239.95" }]}
+  total={{ label: "Total", amount: "€239.95" }}
+  payments={[{ label: "Paid", amount: "€0.00" }, { label: "Balance", amount: "€239.95" }]}
+  alert="€239.95 of the balance is currently unauthorized"
+/>
+```
+
+### OrderTransactions
+
+```tsx
+<OrderTransactions transactions={transactions} />
+```
+
+### Customer and addresses
+
+```tsx
+<OrderCustomer
+  name="Alice Mercer"
+  email="alice@example.test"
+  orderCount={4}
+  shippingAddress={address}
+  billingSameAsShipping
+/>
+```
+
+## base/accordion
+
+```tsx
+import { … } from "themelia-ui/base/accordion"
+import "themelia-ui/base/accordion.css"
+```
+
+Preview route: Accordion — `/accordion`
+
+### Accordion
+
+```tsx
+<Accordion
+  items={[
+    { value: "billing", title: "Billing", description: "…", content: <…/> },
+  ]}
+/>
+```
+
+## base/action-menu
+
+```tsx
+import { … } from "themelia-ui/base/action-menu"
+import "themelia-ui/base/action-menu.css"
+```
+
+Preview route: Action buttons — `/action-buttons`
+
+### ActionButtons
+
+```tsx
+<ActionButtons actions={actions.slice(0, 2)} />
+```
+
+### Overflow
+
+```tsx
+<ActionButtons actions={toolbar} max={2} />
+```
+
+### ActionMenu
+
+```tsx
+<ActionMenu
+  actions={[
+    { label: "Edit", icon: PencilIcon, onClick: … },
+    { label: "Archive", icon: ArchiveIcon, onClick: …, group: true },
+    { label: "Delete", icon: TrashIcon, onClick: …, tone: "destructive" },
+  ]}
+/>
+```
+
+### Destructive last
+
+```tsx
+const declared = [
+  { label: "Delete", tone: "destructive", onClick: … },
+  { label: "Edit", onClick: … },
+  { label: "Duplicate", onClick: … },
+]
+
+<ActionMenu actions={declared} />
+<ActionMenu actions={declared} preserveOrder />
+```
+
+### Width and row slots
+
+```tsx
+<ActionMenu actions={actions} maxWidth="18rem" />
+<ActionMenu actions={actions} width={280} />
+<ActionMenu actions={actions} width="trigger" label="Matches trigger" />
+
+// Rows take slots, so the label is the only part that gives way:
+{ label: "Duplicate", icon: CopyIcon, shortcut: "⌘D" }
+{ label: "Export", description: "CSV, one row per invoice" }
+```
+
+## base/alert-dialog
+
+```tsx
+import { … } from "themelia-ui/base/alert-dialog"
+import "themelia-ui/base/alert-dialog.css"
+```
+
+Preview route: Alert dialog — `/alert-dialog`
+
+### Alert dialog
+
+```tsx
+<AlertDialogContent>  {/* dismissal={{ backdrop: false, escape: false }} */}
+```
+
+## base/avatar
+
+```tsx
+import { … } from "themelia-ui/base/avatar"
+import "themelia-ui/base/avatar.css"
+```
+
+Preview route: Avatar — `/avatar`
+
+### Avatar
+
+```tsx
+<Avatar>
+  <AvatarImage src={user.photo} alt="" />
+  <AvatarFallback>JM</AvatarFallback>
+</Avatar>
+```
+
+### StackedAvatars
+
+```tsx
+<StackedAvatars users={members} max={4} />
+```
+
+## base/badge
+
+```tsx
+import { … } from "themelia-ui/base/badge"
+import "themelia-ui/base/badge.css"
+```
+
+Preview route: Badge — `/badge`
+
+### Tones
+
+```tsx
+<Badge tone="success">Paid</Badge>
+<Badge tone="warning" variant="solid">Due</Badge>
+<Badge tone="destructive" variant="outline">Overdue</Badge>
+```
+
+### Status dot
+
+```tsx
+<Badge tone="success" dot>Live</Badge>
+<Badge tone="warning" dot pending>Queued</Badge>
+<Badge tone="info" dot pulse>Syncing</Badge>
+```
+
+## base/batch-action-bar
+
+```tsx
+import { … } from "themelia-ui/base/batch-action-bar"
+import "themelia-ui/base/batch-action-bar.css"
+```
+
+Preview route: Batch action bar — `/batch-action-bar`
+
+### Floating
+
+```tsx
+<BatchActionBar selectedCount={selected} totalCount={250} onClear={() => setSelected(0)}>
+	<Button tone="neutral" buttonStyle="outline">Export</Button>
+	<Button tone="destructive" buttonStyle="outline">Delete</Button>
+</BatchActionBar>
+```
+
+### Inline
+
+```tsx
+<BatchActionBar placement="inline" selectedCount={12} onClear={clear}>
+	<Button tone="neutral" buttonStyle="outline">Assign</Button>
+</BatchActionBar>
+```
+
+## base/buttons
+
+```tsx
+import { … } from "themelia-ui/base/buttons"
+import "themelia-ui/base/buttons.css"
+```
+
+Preview route: Button — `/button`
+
+### Tone × style
+
+```tsx
+<Button tone="destructive" buttonStyle="ghost">Delete</Button>
+```
+
+### Scale, not size
+
+```tsx
+{/* not this */}
+<Button>Save</Button>
+
+{/* this — the whole region stays in proportion */}
+<UIProvider config={{ scale: 0.875 }}>
+  <Toolbar />
+</UIProvider>
+```
+
+### State
+
+```tsx
+<Button>Save changes</Button>
+<Button loading>Save changes</Button>
+<Button disabled>Disabled</Button>
+```
+
+### Icon only
+
+```tsx
+<Button iconOnly aria-label="Settings">⚙</Button>
+```
+
+### Group
+
+```tsx
+<ButtonGroup>
+  <Button buttonStyle="outline" tone="neutral">Day</Button>
+  <Button buttonStyle="outline" tone="neutral">Week</Button>
+</ButtonGroup>
+```
+
+### Three buttons that are not styles
+
+```tsx
+<TextButton onClick={undo}>Undo</TextButton>
+<LoaderButton onClick={async () => save()}>Save</LoaderButton>
+<TooltipButton tooltip="Archive" iconOnly><ArchiveIcon /></TooltipButton>
+```
+
+### Separators and text inside a group
+
+```tsx
+<ButtonGroup>
+  <Button>Day</Button>
+  <ButtonGroupSeparator />
+  <ButtonGroupText>of</ButtonGroupText>
+  <Button>Week</Button>
+</ButtonGroup>
+```
+
+## base/cards
+
+```tsx
+import { … } from "themelia-ui/base/cards"
+import "themelia-ui/base/cards.css"
+```
+
+Preview route: Card — `/card`
+
+### Surfaces
+
+```tsx
+<Card surface="framed" title="Revenue" description="Last 30 days" />
+```
+
+### Slots
+
+```tsx
+<Card
+  icon={<CreditCardIcon />}
+  title="Primary card"
+  titleSuffix={<Badge>Default</Badge>}
+  description="Visa ending 4242"
+  actions={[
+    { label: "Edit", onClick: … },
+    { label: "Remove", onClick: …, tone: "destructive" },
+  ]}
+  footerText="Updated 3 days ago"
+  footerSlot={<Button>Manage</Button>}
+/>
+```
+
+### Expandable
+
+```tsx
+<Card expandable title="Terms">…</Card>
+```
+
+### One card primitive
+
+```tsx
+<Card
+  icon={<CreditCardIcon />}
+  title="Payment method"
+  titleSuffix={<Badge tone="success">Verified</Badge>}
+  tooltip="We store only the last four digits."
+  headerAction={<Button buttonStyle="ghost" tone="neutral">Change</Button>}
+  description="Charged on the first of the month."
+/>
+```
+
+### Alert band
+
+```tsx
+<Card title="Domain" alert="Verification expires in 3 days." alertTone="warning" />
+```
+
+### Actions, and the whole card as one
+
+```tsx
+<Card>
+  <CardContent>…</CardContent>
+  <CardFooter>
+    <CardActionStrip actions={[{ id: "open", label: "Open" }, { id: "archive", label: "Archive" }]} />
+  </CardFooter>
+</Card>
+
+// Or the whole card as one link. The card becomes the anchor's containing
+// block on its own, and a control inside it still takes its own clicks.
+<Card title="Northwind Traders">
+  <CardPrimaryAction href="/invoices/4417" label="Open Northwind Traders" />
+  <CardFooter>
+    <TextLink href="/invoices/4417.pdf">View the invoice instead</TextLink>
+  </CardFooter>
+</Card>
+```
+
+### CardSkeleton
+
+```tsx
+<CardSkeleton surface="bordered" showHeader lines={3} />
+```
+
+## base/carousel
+
+```tsx
+import { … } from "themelia-ui/base/carousel"
+import "themelia-ui/base/carousel.css"
+```
+
+Preview route: Carousel — `/carousel`
+
+### Carousel
+
+```tsx
+<Carousel showDots dotStyle="pill" label="Recent invoices">
+  {invoices.map((name) => (
+    <CarouselSlide key={name} size="16rem">
+      <Card surface="bordered" title={name} />
+    </CarouselSlide>
+  ))}
+</Carousel>
+```
+
+### Control placement
+
+```tsx
+<Carousel controls="overlay" label="Gallery">…</Carousel>
+```
+
+### Slide width
+
+```tsx
+<CarouselSlide size="50%">…</CarouselSlide>
+<CarouselSlide size="18rem">…</CarouselSlide>
+```
+
+## base/chart
+
+```tsx
+import { … } from "themelia-ui/base/chart"
+import "themelia-ui/base/chart.css"
+```
+
+Preview route: Chart — `/chart`
+
+### Chart
+
+```tsx
+const config = {
+  revenue: { label: "Revenue", color: "var(--chart-1)" },
+  expenses: { label: "Expenses", color: "var(--chart-2)" },
+} satisfies ChartConfig
+
+<ChartContainer config={config}>
+  <BarChart data={data}>
+    <CartesianGrid vertical={false} />
+    <XAxis dataKey="month" tickLine={false} axisLine={false} />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <Bar dataKey="revenue" fill="var(--color-revenue)" radius={4} />
+  </BarChart>
+</ChartContainer>
+```
+
+### Sparkline
+
+```tsx
+<Sparkline data={[4, 9, 6, 12, 10, 17, 15, 22]} tone="success" label="Revenue, last eight weeks" />
+```
+
+## base/choice-inputs
+
+```tsx
+import { … } from "themelia-ui/base/choice-inputs"
+import "themelia-ui/base/choice-inputs.css"
+```
+
+Preview route: Card radio group — `/card-radio-group`
+
+### CardRadioGroup
+
+```tsx
+<CardRadioGroup
+  options={plans}
+  value={plan}
+  onValueChange={setPlan}
+  columns={3}
+/>
+```
+
+### CardCheckboxGroup
+
+```tsx
+<CardCheckboxGroup
+  options={channels}
+  value={selected}
+  onValueChange={setSelected}
+  columns={4}
+/>
+```
+
+### Checkbox
+
+```tsx
+<Checkbox label="Checked" defaultChecked />
+<Checkbox label="Indeterminate" indeterminate />
+```
+
+### ListRadioGroup
+
+```tsx
+<ListRadioGroup options={roles} value={role} onValueChange={setRole} />
+```
+
+### PillRadioGroup
+
+```tsx
+<PillRadioGroup options={views} value={view} onValueChange={setView} allowClear />
+```
+
+### Radio group
+
+```tsx
+<RadioGroup name="plan">
+  <Radio label="Free" value="free" />
+  <Radio label="Pro" value="pro" defaultChecked />
+</RadioGroup>
+```
+
+### Select
+
+```tsx
+<Select
+  options={countries}
+  value={country}
+  onValueChange={setCountry}
+  allowClear
+/>
+```
+
+### Switch
+
+```tsx
+<Switch label="Email notifications" defaultChecked />
+```
+
+### SwitchCard and ToggleField
+
+```tsx
+<SwitchCard label="Two-factor authentication" icon={ShieldIcon} description="…" />
+<ToggleField label="Email notifications" description="…" />
+```
+
+## base/combobox
+
+```tsx
+import { … } from "themelia-ui/base/combobox"
+import "themelia-ui/base/combobox.css"
+```
+
+Preview route: Combobox — `/combobox`
+
+### One field surface
+
+```tsx
+<ComboboxInputTrigger placeholder="Search…" showClear />
+```
+
+### Without free text
+
+```tsx
+<ComboboxTrigger>
+  <ComboboxValue placeholder="Choose a country" />
+</ComboboxTrigger>
+```
+
+### Multiple
+
+```tsx
+<ComboboxChips>
+  {value.map((item) => <ComboboxChip key={item}>{item}</ComboboxChip>)}
+  <ComboboxChipsInput />
+</ComboboxChips>
+```
+
+## base/command
+
+```tsx
+import { … } from "themelia-ui/base/command"
+import "themelia-ui/base/command.css"
+```
+
+Preview route: Command — `/command`
+
+### Command
+
+```tsx
+<Command>
+  <CommandInput placeholder="Type a command…" />
+  <CommandList>
+    <CommandEmpty>No results.</CommandEmpty>
+    <CommandGroup heading="Pages">
+      <CommandItem>Invoices</CommandItem>
+    </CommandGroup>
+  </CommandList>
+</Command>
+```
+
+### CommandDialog
+
+```tsx
+useEffect(() => {
+  const onKey = (e: KeyboardEvent) => {
+    if (e.key === "k" && (e.metaKey || e.ctrlKey)) { e.preventDefault(); setOpen(true) }
+  }
+  document.addEventListener("keydown", onKey)
+  return () => document.removeEventListener("keydown", onKey)
+}, [])
+```
+
+## base/context-menu
+
+```tsx
+import { … } from "themelia-ui/base/context-menu"
+import "themelia-ui/base/context-menu.css"
+```
+
+Preview route: Context menu — `/context-menu`
+
+### Context menu
+
+```tsx
+<ContextMenu>
+  <ContextMenuTrigger render={<div />}>…</ContextMenuTrigger>
+  <ContextMenuContent>
+    <ContextMenuItem icon={<PencilIcon />}>Edit</ContextMenuItem>
+    <ContextMenuSeparator />
+    <ContextMenuItem variant="destructive">Delete</ContextMenuItem>
+  </ContextMenuContent>
+</ContextMenu>
+```
+
+## base/copyable
+
+```tsx
+import { … } from "themelia-ui/base/copyable"
+import "themelia-ui/base/copyable.css"
+```
+
+Preview route: Copyable — `/copyable`
+
+### Copyable
+
+```tsx
+{/* truncate keeps the button in view however long the value is */}
+<Copyable value="sk_live_9f2c…" mono truncate />
+<Copyable value="jane@example.com" displayValue={<Email value="jane@example.com" />} />
+```
+
+### useCopyToClipboard
+
+```tsx
+const { copied, copy } = useCopyToClipboard()
+
+<Button onClick={() => void copy(url)}>
+  {copied ? "Link copied" : "Copy invite link"}
+</Button>
+```
+
+## base/date-pickers
+
+```tsx
+import { … } from "themelia-ui/base/date-pickers"
+import "themelia-ui/base/date-pickers.css"
+```
+
+Preview route: Calendar — `/calendar`
+
+### Calendar
+
+```tsx
+<Calendar mode="range" value={range} onValueChange={setRange} numberOfMonths={2} />
+```
+
+### Another language, another week
+
+```tsx
+import { de } from "date-fns/locale"
+
+<UIProvider config={{ dates: { locale: de, weekStartsOn: 0 } }}>
+  <Calendar mode="single" />
+</UIProvider>
+```
+
+### DatePicker
+
+```tsx
+<DatePicker value={day} onValueChange={setDay} clearable />
+<DatePicker mode="range" value={range} onValueChange={setRange} presets={RANGE_PRESETS} />
+```
+
+### One picker, four fixed modes
+
+```tsx
+<SingleDatePicker value={day} onValueChange={setDay} />
+<RangeDatePicker value={range} onValueChange={setRange} />
+<MonthYearPicker value={month} onValueChange={setMonth} />
+```
+
+### TimePicker and DateTimeInput
+
+```tsx
+<TimePicker value={time} onValueChange={setTime} minuteStep={15} />
+<DateTimeInput value={iso} onValueChange={setIso} />
+```
+
+## base/dialog
+
+```tsx
+import { … } from "themelia-ui/base/dialog"
+import "themelia-ui/base/dialog.css"
+```
+
+Preview route: Dialog — `/dialog`
+
+### Dialog
+
+```tsx
+<Dialog>
+  <DialogTrigger render={<Button>Open</Button>} />
+  <DialogContent>
+    <DialogHeader><DialogTitle>Title</DialogTitle></DialogHeader>
+    <DialogBody>…</DialogBody>
+    <DialogFooter>
+      <DialogDismissArea>
+        <Button>Cancel</Button><Button>Save</Button>
+      </DialogDismissArea>
+    </DialogFooter>
+  </DialogContent>
+</Dialog>
+
+{/* or per-action: */}
+<DialogClose render={<Button>Cancel</Button>} />
+```
+
+### Bare surface
+
+```tsx
+<DialogContent surface="bare" showCloseButton={false}>
+```
+
+### Where focus lands
+
+```tsx
+const nameRef = useRef<HTMLInputElement>(null)
+
+<DialogContent initialFocusRef={nameRef}>
+  <Input ref={nameRef} />
+</DialogContent>
+```
+
+## base/display
+
+```tsx
+import { … } from "themelia-ui/base/display"
+import "themelia-ui/base/display.css"
+```
+
+Preview route: Collapsible — `/collapsible`
+
+### Collapsible
+
+```tsx
+<Collapsible>
+  <CollapsibleTrigger>Advanced options</CollapsibleTrigger>
+  <CollapsibleContent>…</CollapsibleContent>
+</Collapsible>
+```
+
+### Four surfaces
+
+```tsx
+<ContentBlock surface="card" title="Contract" description="…">
+  …
+</ContentBlock>
+```
+
+### flush
+
+```tsx
+<ContentBlock surface="card" flush>
+  <ItemGroup ruled>…</ItemGroup>
+</ContentBlock>
+```
+
+### The header assembles itself
+
+```tsx
+<ContentBlock
+  icon={<TruckIcon />}
+  title="Shipment"
+  titleSuffix={<Badge tone="info">In transit</Badge>}
+  headerEnd={<Button buttonStyle="ghost">Track</Button>}
+/>
+```
+
+### IconBadge
+
+```tsx
+<IconBadge icon={CreditCardIcon} tone="success" />
+<IconBadge icon={CreditCardIcon} tone="success" shape="circle" solid />
+```
+
+### DateBlock
+
+```tsx
+<DateBlock date="2026-08-16" />
+```
+
+### PlaceholderPattern
+
+```tsx
+<PlaceholderPattern style={{ height: "8rem" }} />
+```
+
+### DirectionProvider and Slot
+
+```tsx
+<DirectionProvider direction="rtl">
+  <Stack>…</Stack>
+</DirectionProvider>
+
+// render is Slot:
+<OverlayTrigger render={<Button>Open</Button>} />
+```
+
+### between
+
+```tsx
+<InlineStat label="Subtotal" value="€ 1,240.00" mono />
+```
+
+### inline
+
+```tsx
+<InlineStat layout="inline" label="Version" value="v3.2" mono />
+```
+
+### stacked
+
+```tsx
+<InlineStat layout="stacked" label="Open invoices" value="14" mono />
+```
+
+### grid
+
+```tsx
+<MetadataList
+  columns={3}
+  items={[
+    { label: "Reference", value: { kind: "mono", value: "INV-4417" } },
+    { label: "Amount", value: { kind: "money", value: 48200, currency: "USD" } },
+    { label: "Status", value: { kind: "badge", value: "Overdue", badgeTone: "destructive" } },
+  ]}
+/>
+```
+
+### rows
+
+```tsx
+<MetadataList layout="rows" itemSeparator items={facts} />
+```
+
+### inline
+
+```tsx
+<MetadataList layout="inline" itemSeparator items={summary} />
+```
+
+### density
+
+```tsx
+<MetadataList density="compact" columns={2} items={facts} />
+```
+
+### ScrollArea
+
+```tsx
+<ScrollArea style={{ maxHeight: "8rem" }}>…</ScrollArea>
+```
+
+### BooleanIndicator
+
+```tsx
+<BooleanIndicator value strings={{ true: "Active", false: "Paused" }} />
+```
+
+### VisuallyHidden
+
+```tsx
+<Text>
+  Saved
+  <VisuallyHidden> at 09:32 by Jane McDonald</VisuallyHidden>
+</Text>
+```
+
+### Separator
+
+```tsx
+<Separator />
+<Separator label="OR" />
+<Separator orientation="vertical" />
+```
+
+### Variants and thickness
+
+```tsx
+<Separator variant="dashed" />
+<Separator variant="dotted" />
+<Separator thickness={2} />
+```
+
+## base/dropdown-menu
+
+```tsx
+import { … } from "themelia-ui/base/dropdown-menu"
+import "themelia-ui/base/dropdown-menu.css"
+```
+
+Preview route: Dropdown menu — `/dropdown-menu`
+
+### Dropdown menu
+
+```tsx
+<DropdownMenu>
+  <DropdownMenuTrigger render={<Button />}>Open</DropdownMenuTrigger>
+  <DropdownMenuContent>
+    <DropdownMenuItem>Edit</DropdownMenuItem>
+    <DropdownMenuSeparator />
+    <DropdownMenuSub>…</DropdownMenuSub>
+  </DropdownMenuContent>
+</DropdownMenu>
+```
+
+## base/feedback
+
+```tsx
+import { … } from "themelia-ui/base/feedback"
+import "themelia-ui/base/feedback.css"
+```
+
+Preview route: Alert — `/alert`
+
+### Alert
+
+```tsx
+<Alert tone="warning">
+  <AlertTitle>Approaching your limit</AlertTitle>
+  <AlertDescription>You have used 90% of your quota.</AlertDescription>
+</Alert>
+```
+
+### Alert layout
+
+```tsx
+<Alert tone="destructive" icon={<TriangleAlertIcon />}>
+  <AlertTitle>Payment failed</AlertTitle>
+  <AlertDescription>…</AlertDescription>
+  <AlertAction><Button>Retry</Button></AlertAction>
+</Alert>
+```
+
+### Empty
+
+```tsx
+<Empty
+  media={<InboxIcon />}
+  mediaVariant="icon"
+  title="No invoices yet"
+  description="Invoices appear here once a customer is billed."
+  action={<Button>Create invoice</Button>}
+/>
+```
+
+### How the media is dressed
+
+```tsx
+<Empty mediaVariant="icon" media={<SearchIcon />} … />
+<Empty mediaVariant="illustration" media={<SearchGlassIllustration />} … />
+```
+
+### The illustration set
+
+```tsx
+import { StackedCardsIllustration } from "themelia-ui/base/feedback"
+
+<Empty
+  mediaVariant="illustration"
+  media={<StackedCardsIllustration />}
+  title="No products yet"
+/>
+```
+
+### padding and border
+
+```tsx
+<Empty padding="sm" border title="No filters" description="…" />
+```
+
+### Progress
+
+```tsx
+<Progress value={64} label="Upload" />
+<Progress label="Working" />           {/* indeterminate */}
+```
+
+### ProgressCircle
+
+```tsx
+<ProgressCircle value={72} tone="warning" label="Title length">
+  <Text tag="span" size="xs" weight="semibold" numeric>72%</Text>
+</ProgressCircle>
+```
+
+## base/forms
+
+```tsx
+import { … } from "themelia-ui/base/forms"
+import "themelia-ui/base/forms.css"
+```
+
+Preview route: Form field — `/form-field`
+
+### FormField
+
+```tsx
+<FormField
+  label="Email"
+  required
+  hint="We only use this for receipts."
+  error={errors.email}
+>
+  <Input type="email" />
+</FormField>
+```
+
+### Custom control composition
+
+```tsx
+<FormField label="Weight" error={errors.weight}>
+  {(fieldProps) => (
+    <FieldShell {...fieldProps} end="kg">
+      {(controlProps) => <WrappedNumberInput controlProps={controlProps} />}
+    </FieldShell>
+  )}
+</FormField>
+```
+
+### Horizontal fields
+
+```tsx
+<FormField orientation="horizontal" label="Display name">
+  <Input />
+</FormField>
+```
+
+### Scale
+
+```tsx
+<Scope vars={{ "--density-scale": 0.875 }}>…</Scope>
+```
+
+### FieldGroup
+
+```tsx
+<FieldGroup legend="Reporting period" description="Both ends are inclusive.">
+  <FormField label="From"><Input type="date" /></FormField>
+  <FormField label="To"><Input type="date" /></FormField>
+</FieldGroup>
+```
+
+### FormSection
+
+```tsx
+<FormSection title="Billing" description="Where invoices go." actions={<Button>Edit</Button>}>
+  <FormField label="Company">…</FormField>
+</FormSection>
+```
+
+### FormActionsBar
+
+```tsx
+<FormActionsBar leading={<Text size="xs" type="secondary">Saved 2 minutes ago</Text>}>
+  <Button buttonStyle="outline">Discard</Button>
+  <Button>Save</Button>
+</FormActionsBar>
+```
+
+### ErrorSummary
+
+```tsx
+<ErrorSummary
+  errors={["Name is required.", "Email is not valid."]}
+  action={<Button buttonStyle="outline">Review the first problem</Button>}
+/>
+```
+
+### DirtyStateBanner
+
+```tsx
+<DirtyStateBanner actions={<><Button buttonStyle="outline">Discard</Button><Button>Save</Button></>} />
+```
+
+### SubmitStateButton
+
+```tsx
+<SubmitStateButton state={state} />
+```
+
+### LoadingState and ErrorState
+
+```tsx
+<LoadingState />
+<ErrorState onRetry={refetch} />
+```
+
+## base/forms-numeric
+
+```tsx
+import { … } from "themelia-ui/base/forms-numeric"
+import "themelia-ui/base/forms-numeric.css"
+```
+
+Preview route: Currency input — `/currency-input`
+
+### CurrencyInput
+
+```tsx
+<CurrencyInput
+  value={amount}
+  onChange={(e) => setAmount(e.target.value)}
+  currency={currency}
+  onCurrencyChange={setCurrency}
+/>
+```
+
+### DecimalInput
+
+```tsx
+<DecimalInput decimalPlaces={2} min={0} max={100} step={0.5} />
+```
+
+### RoundingModeSelect
+
+```tsx
+<RoundingModeSelect value={mode} onValueChange={setMode} />
+<DecimalInput decimalPlaces={2} roundingMode={mode} />
+```
+
+### PercentageInput
+
+```tsx
+<PercentageInput defaultValue="21" />
+```
+
+### Weight, dimensions, coordinates
+
+```tsx
+<WeightInput value={weight} onChange={(e) => setWeight(e.target.value)} />
+<DimensionsInput value={dimensions} onValueChange={setDimensions} />
+<CoordinatesInput value={coordinates} onValueChange={setCoordinates} />
+```
+
+## base/input-group
+
+```tsx
+import { … } from "themelia-ui/base/input-group"
+import "themelia-ui/base/input-group.css"
+```
+
+Preview route: Input group — `/input-group`
+
+### Attached along the line
+
+```tsx
+<InputGroup>
+  <InputGroupAddon><SearchIcon /></InputGroupAddon>
+  <InputGroupInput placeholder="Search orders" />
+</InputGroup>
+```
+
+### Attached above or below
+
+```tsx
+<InputGroup>
+  <InputGroupTextarea placeholder="Write a note" />
+  <InputGroupAddon align="block-end">
+    <InputGroupText>Markdown supported</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Button sizes inside the shell
+
+```tsx
+<InputGroupButton size="icon-xs" aria-label="Go"><ArrowRightIcon /></InputGroupButton>
+```
+
+## base/item
+
+```tsx
+import { … } from "themelia-ui/base/item"
+import "themelia-ui/base/item.css"
+```
+
+Preview route: Item — `/item`
+
+### Item
+
+```tsx
+<ItemGroup>
+  <Item>
+    <ItemMedia variant="image"><Avatar /></ItemMedia>
+    <ItemContent>
+      <ItemTitle>Jane McDonald</ItemTitle>
+      <ItemDescription>jane@example.com</ItemDescription>
+    </ItemContent>
+    <ItemActions><Badge>Active</Badge></ItemActions>
+  </Item>
+</ItemGroup>
+```
+
+### Density
+
+```tsx
+<Scope vars={{ "--density-scale": 0.85 }}>
+  <ItemGroup>…</ItemGroup>
+</Scope>
+```
+
+### A ruled group
+
+```tsx
+<ItemGroup ruled>
+  <Item>…</Item>
+  <Item>…</Item>
+</ItemGroup>
+```
+
+## base/label
+
+```tsx
+import { … } from "themelia-ui/base/label"
+import "themelia-ui/base/label.css"
+```
+
+Preview route: Label — `/label`
+
+### Label
+
+```tsx
+<Label htmlFor="email">Email</Label>
+<Input id="email" />
+```
+
+## base/menubar
+
+```tsx
+import { … } from "themelia-ui/base/menubar"
+import "themelia-ui/base/menubar.css"
+```
+
+Preview route: Menubar & hover card — `/menubar`
+
+### Menubar
+
+```tsx
+<Menubar>
+  <MenubarMenu>
+    <MenubarTrigger>File</MenubarTrigger>
+    <MenubarContent>
+      <MenubarItem>New <MenubarShortcut>⌘N</MenubarShortcut></MenubarItem>
+    </MenubarContent>
+  </MenubarMenu>
+</Menubar>
+```
+
+### HoverCard
+
+```tsx
+<HoverCard>
+  <HoverCardTrigger render={<TextLink />}>@jane</HoverCardTrigger>
+  <HoverCardContent>…</HoverCardContent>
+</HoverCard>
+```
+
+### Resizable
+
+```tsx
+<ResizablePanelGroup orientation="horizontal" autoSaveId="inspector">
+  <ResizablePanel defaultSize={65}>…</ResizablePanel>
+  <ResizableHandle withHandle />
+  <ResizablePanel defaultSize={35}>…</ResizablePanel>
+</ResizablePanelGroup>
+```
+
+### OtpInput
+
+```tsx
+<OtpInput length={6} groupSize={3} value={code} onValueChange={setCode} />
+```
+
+### AspectRatio
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <img src={cover} alt="" />
+</AspectRatio>
+```
+
+### Kbd
+
+```tsx
+<Kbd>⌘K</Kbd>
+```
+
+## base/navigation
+
+```tsx
+import { … } from "themelia-ui/base/navigation"
+import "themelia-ui/base/navigation.css"
+```
+
+Preview route: Breadcrumbs — `/breadcrumbs`
+
+### Breadcrumbs
+
+```tsx
+<Breadcrumbs
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Orders", href: "/orders" },
+    { label: "Order 4417" },
+  ]}
+/>
+```
+
+### Pagination
+
+```tsx
+<Pagination page={page} total={128} onPageChange={setPage} />
+```
+
+### Arrows, and what they are made of
+
+```tsx
+<Pagination labels="text" … />
+<Pagination labels="icon" … />
+<Pagination numbers={false} page={3} total={12} … />
+```
+
+### A pager is navigation
+
+```tsx
+<Pagination
+  page={page}
+  total={128}
+  onPageChange={setPage}
+  renderLink={(page, props) => <Link href={`?page=${page}\
+```
+
+### Tabs
+
+```tsx
+<Tabs value={tab} onValueChange={setTab}>
+  <TabList label="Sections">
+    <Tab value="overview">Overview</Tab>
+    <Tab value="activity">Activity</Tab>
+  </TabList>
+  <TabPanel value="overview">…</TabPanel>
+</Tabs>
+```
+
+### OverflowTabBar
+
+```tsx
+<OverflowTabBar
+  items={[
+    { id: "overview", label: "Overview" },
+    { id: "activity", label: "Activity", badge: <Badge tone="neutral">3</Badge> },
+    { id: "billing", label: "Billing", href: "/billing" },
+  ]}
+  value={tab}
+  onValueChange={setTab}
+/>
+```
+
+## base/overlay
+
+```tsx
+import { … } from "themelia-ui/base/overlay"
+import "themelia-ui/base/overlay.css"
+```
+
+Preview route: Overlay — `/overlay`
+
+### placement
+
+```tsx
+<Overlay>
+  <OverlayTrigger render={<Button>Open</Button>} />
+  <OverlayContent placement="inline-end">
+    <OverlayHeader>…</OverlayHeader>
+    <OverlayBody>…</OverlayBody>
+  </OverlayContent>
+</Overlay>
+```
+
+### modality
+
+```tsx
+<OverlayContent placement="inline-end" modality="trap-focus" />
+```
+
+### size, length and inset
+
+```tsx
+<OverlayContent placement="inline-end" size="lg" length="95%" inset />
+```
+
+### dismissal
+
+```tsx
+<OverlayContent dismissal={{ backdrop: false, escape: false }} />
+```
+
+### Controlled
+
+```tsx
+<Overlay open={open} onOpenChange={setOpen}>
+  <OverlayContent>…</OverlayContent>
+</Overlay>
+```
+
+## base/popover
+
+```tsx
+import { … } from "themelia-ui/base/popover"
+import "themelia-ui/base/popover.css"
+```
+
+Preview route: Popover — `/popover`
+
+### Anatomy
+
+```tsx
+<Popover>
+  <PopoverTrigger render={<Button>Filters</Button>} />
+  <PopoverContent>
+    <PopoverHeader>
+      <PopoverTitle>Filters</PopoverTitle>
+      <PopoverDescription>Narrow the list.</PopoverDescription>
+    </PopoverHeader>
+    …
+    <PopoverFooter>…</PopoverFooter>
+  </PopoverContent>
+</Popover>
+```
+
+### side, align and width
+
+```tsx
+<PopoverContent side="right" align="start" width="trigger" />
+```
+
+### PopoverAnchor
+
+```tsx
+<Popover>
+  <PopoverAnchor>
+    <Text>The panel points here…</Text>
+  </PopoverAnchor>
+  <PopoverTrigger render={<Button>…but this opens it</Button>} />
+  <PopoverContent>…</PopoverContent>
+</Popover>
+```
+
+## base/popover-menu
+
+```tsx
+import { … } from "themelia-ui/base/popover-menu"
+import "themelia-ui/base/popover-menu.css"
+```
+
+Preview route: Popover menu — `/popover-menu`
+
+### PopoverMenu
+
+```tsx
+<PopoverMenu
+  trigger={<Button buttonStyle="outline">Owner</Button>}
+  items={owners}
+  onSelect={(item) => setOwner(item.value)}
+/>
+```
+
+## base/qr-code
+
+```tsx
+import { … } from "themelia-ui/base/qr-code"
+import "themelia-ui/base/qr-code.css"
+```
+
+Preview route: QR code — `/qr-code`
+
+### QRCode
+
+```tsx
+<QRCode value={url} robustness="M" />
+```
+
+## base/repeaters
+
+```tsx
+import { … } from "themelia-ui/base/repeaters"
+import "themelia-ui/base/repeaters.css"
+```
+
+Preview route: Repeater — `/repeater`
+
+### Repeater
+
+```tsx
+<Repeater
+  items={contacts}
+  getKey={(contact) => contact.id}
+  onAdd={() => setContacts([...contacts, blank()])}
+  onRemove={(index) => setContacts(contacts.filter((_, i) => i !== index))}
+  onMove={move}
+  rowVariant="card"
+>
+  {(contact, { index }) => (
+    <Stack direction="horizontal" gap="md">
+      <Input value={contact.name} onChange={…} aria-label="Name" />
+      <Input value={contact.email} onChange={…} aria-label="Email" />
+    </Stack>
+  )}
+</Repeater>
+```
+
+### StringRepeater
+
+```tsx
+<StringRepeater value={domains} onValueChange={setDomains} sortable />
+```
+
+### KeyValueEditor
+
+```tsx
+<KeyValueEditor value={headers} onValueChange={setHeaders} sortable />
+```
+
+### LocalizedStringField
+
+```tsx
+<LocalizedStringField
+  locales={[{ value: "en", label: "English" }, { value: "nl", label: "Nederlands" }]}
+  value={name}
+  onValueChange={setName}
+/>
+```
+
+## base/sheet
+
+```tsx
+import { … } from "themelia-ui/base/sheet"
+import "themelia-ui/base/sheet.css"
+```
+
+Preview route: Sheet — `/sheet`
+
+### Sheet
+
+```tsx
+<SheetContent side="inline-end" />
+```
+
+### Size, length, and inset
+
+```tsx
+{/* the default: welded to the edge */}
+<SheetContent side="inline-end" size="md" />
+
+{/* a tall dialog from the corner — the offset is the whole shape */}
+<SheetContent side="inline-end" size="28rem" inset />
+
+{/* shorter still, centred in what the offset left */}
+<SheetContent side="inline-end" size="28rem" length="70%" inset />
+```
+
+### Decided once, not per call site
+
+```tsx
+<UIProvider config={{ defaults: { sheet: { size: "26rem", inset: true } } }}>
+  <App />
+</UIProvider>
+```
+
+### Modality
+
+```tsx
+<SheetContent modality="non-modal" />
+```
+
+## base/sidebar
+
+```tsx
+import { … } from "themelia-ui/base/sidebar"
+import "themelia-ui/base/sidebar.css"
+```
+
+Preview route: Sidebar — `/sidebar`
+
+### Anatomy
+
+```tsx
+<SidebarProvider>
+  <Sidebar>
+    <SidebarHeader>…</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Workspace</SidebarGroupLabel>
+        <SidebarGroupContent>
+          <SidebarMenu>
+            <SidebarMenuItem>
+              <SidebarMenuButton active>…</SidebarMenuButton>
+              <SidebarMenuBadge>12</SidebarMenuBadge>
+            </SidebarMenuItem>
+          </SidebarMenu>
+        </SidebarGroupContent>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarFooter>…</SidebarFooter>
+    <SidebarRail />
+  </Sidebar>
+  <SidebarInset>…</SidebarInset>
+</SidebarProvider>
+```
+
+### variant
+
+```tsx
+<Sidebar variant="floating" />
+```
+
+### collapsible
+
+```tsx
+<Sidebar collapsible="icon" />
+```
+
+### Controlled
+
+```tsx
+<SidebarProvider open={open} onOpenChange={setOpen}>…</SidebarProvider>
+```
+
+## base/skeleton
+
+```tsx
+import { … } from "themelia-ui/base/skeleton"
+import "themelia-ui/base/skeleton.css"
+```
+
+Preview route: Skeleton — `/skeleton`
+
+### Skeleton
+
+```tsx
+<Skeleton style={{ width: "12rem", height: "1rem" }} />
+```
+
+### Composed skeletons
+
+```tsx
+<ContentSkeleton lines={3} />
+<TableSkeleton rows={4} columns={3} />
+<PageSkeleton blocks={2} />
+<TwoColumnPageSkeleton />
+```
+
+## base/spinner
+
+```tsx
+import { … } from "themelia-ui/base/spinner"
+import "themelia-ui/base/spinner.css"
+```
+
+Preview route: Spinner — `/spinner`
+
+### Spinner
+
+```tsx
+<Spinner label="Saving…" />   {/* announced */}
+<Spinner />                   {/* decorative, aria-hidden */}
+```
+
+### Size
+
+```tsx
+<Spinner size="sm" />
+<Spinner size="md" />
+<Spinner size="lg" />
+```
+
+### Tone
+
+```tsx
+<Spinner tone="neutral" />
+<Spinner tone="success" />
+```
+
+## base/structure
+
+```tsx
+import { … } from "themelia-ui/base/structure"
+import "themelia-ui/base/structure.css"
+```
+
+Preview route: Stack & Grid — `/structure`
+
+### Stack
+
+```tsx
+<Stack gap="sm">…</Stack>
+<Stack direction="horizontal" justify="between" align="center">…</Stack>
+```
+
+### Responsive props
+
+```tsx
+<Stack direction={{ base: "vertical", md: "horizontal" }} gap={{ base: "xs", md: "xl" }}>
+```
+
+### Grid
+
+```tsx
+<Grid columns={{ base: 1, md: 3 }}>
+  <GridCell span="full">…</GridCell>
+</Grid>
+```
+
+### AdaptiveGrid
+
+```tsx
+<AdaptiveGrid minColumnWidth="sm">…</AdaptiveGrid>
+```
+
+### Split
+
+```tsx
+<Split sideWidth="14rem" gap="md">
+  <Box>main</Box>
+  <Box>side</Box>
+</Split>
+```
+
+### Bleed
+
+```tsx
+<Bleed amount="md">
+  <img … />
+</Bleed>
+```
+
+## base/table
+
+```tsx
+import { … } from "themelia-ui/base/table"
+import "themelia-ui/base/table.css"
+```
+
+Preview route: Table — `/table`
+
+### Table
+
+```tsx
+<Table>
+  <TableHeader>
+    <TableRow><TableHead>Invoice</TableHead>…</TableRow>
+  </TableHeader>
+  <TableBody>
+    <TableRow>
+      <TableCell>INV-4417</TableCell>
+      <TableCell align="end"><Money amount={1299.5} /></TableCell>
+    </TableRow>
+  </TableBody>
+</Table>
+```
+
+### Selection
+
+```tsx
+<TableRow data-state={isSelected ? "selected" : undefined}>
+  <TableCell><Checkbox … /></TableCell>
+  …
+</TableRow>
+```
+
+### Overflow
+
+```tsx
+<Scope vars={{ "--density-scale": 0.85 }}>
+  <Table>…</Table>
+</Scope>
+```
+
+### Sortable columns
+
+```tsx
+<TableHead
+  sortable
+  sortDirection={sort.key === "amount" ? sort.direction : null}
+  onSort={() => toggleSort("amount")}
+  align="end"
+>
+  Amount
+</TableHead>
+```
+
+### Empty and sticky
+
+```tsx
+<TableBody>
+  {rows.length === 0 ? <TableEmpty colSpan={4} /> : rows.map(…)}
+</TableBody>
+
+<Table stickyHeader containerClassName="…max-height…">
+```
+
+## base/text-inputs
+
+```tsx
+import { … } from "themelia-ui/base/text-inputs"
+import "themelia-ui/base/text-inputs.css"
+```
+
+Preview route: Input — `/input`
+
+### One shared surface
+
+```tsx
+/* styles/fields.css */
+[data-field-control] {
+  height: var(--field-h);
+  border: 1px solid var(--input);
+  box-shadow: var(--shadow-xs);
+}
+[data-field-control]:focus-visible { box-shadow: var(--focus-ring); }
+[data-field-control][aria-invalid="true"] { box-shadow: var(--invalid-ring); }
+```
+
+### States
+
+```tsx
+<Input aria-invalid="true" />
+<Input disabled />
+```
+
+### Inline affordances
+
+```tsx
+<FieldShell start={<SearchIcon />} end={<Button>Go</Button>}>
+  <Input />
+</FieldShell>
+
+<PasswordInput />
+<SearchInput value={q} onChange={…} onClear={…} />
+```
+
+### Password input
+
+```tsx
+<PasswordInput placeholder="Password" />
+```
+
+### Search input
+
+```tsx
+<SearchInput value={query} onChange={(e) => setQuery(e.target.value)} onClear={() => setQuery("")} />
+```
+
+### SlugField
+
+```tsx
+<SlugField value={title} prefix="acme.com/" />
+```
+
+### Textarea
+
+```tsx
+<Textarea rows={4} placeholder="Notes" />
+<Textarea showCharacterCount maxLength={280} />
+```
+
+## base/timeline
+
+```tsx
+import { … } from "themelia-ui/base/timeline"
+import "themelia-ui/base/timeline.css"
+```
+
+Preview route: Timeline — `/timeline`
+
+### An order's progress
+
+```tsx
+<Timeline
+  items={[
+    { id: "placed", title: "Order placed", timestamp: "14 Aug, 09:12", icon: CheckIcon, status: "completed" },
+    { id: "transit", title: "In transit", timestamp: "16 Aug, 06:02", icon: TruckIcon, status: "current" },
+    { id: "delivered", title: "Delivered", timestamp: "Expected 18 Aug", status: "pending" },
+  ]}
+/>
+```
+
+### Statuses
+
+```tsx
+<Timeline items={[{ id: "1", title: "Packed", status: "completed" }]} />
+```
+
+### Entries that carry more than a line
+
+```tsx
+<Timeline
+  items={[
+    {
+      id: "refund",
+      title: "Refund issued",
+      status: "warning",
+      children: <Badge tone="warning">Partial</Badge>,
+    },
+  ]}
+/>
+```
+
+## base/toaster
+
+```tsx
+import { … } from "themelia-ui/base/toaster"
+import "themelia-ui/base/toaster.css"
+```
+
+Preview route: Toast — `/toast`
+
+### Statuses
+
+```tsx
+toast.success("Invoice sent")
+toast.error("Could not reach the server")
+toast.loading("Uploading…", { id: "upload" })
+```
+
+### Actions
+
+```tsx
+toast("Invoice deleted", {
+  action: { label: "Undo", onClick: restore },
+  duration: 8000,
+})
+```
+
+### Promise
+
+```tsx
+toast.promise(saveInvoice(), {
+  loading: "Saving…",
+  success: (invoice) => `Saved ${invoice.id}`,
+  error: "Could not save",
+})
+```
+
+## base/toggle
+
+```tsx
+import { … } from "themelia-ui/base/toggle"
+import "themelia-ui/base/toggle.css"
+```
+
+Preview route: Toggle — `/toggle`
+
+### Toggle
+
+```tsx
+<Toggle pressed={bold} onPressedChange={setBold} aria-label="Bold">
+  <BoldIcon />
+</Toggle>
+```
+
+### ToggleGroup
+
+```tsx
+{/* several at once */}
+<ToggleGroup multiple value={marks} onValueChange={setMarks}>
+  <ToggleGroupItem value="bold"><BoldIcon /></ToggleGroupItem>
+</ToggleGroup>
+
+{/* one at a time */}
+<ToggleGroup value={[align]} onValueChange={([next]) => setAlign(next)}>
+```
+
+## base/toolbar
+
+```tsx
+import { … } from "themelia-ui/base/toolbar"
+import "themelia-ui/base/toolbar.css"
+```
+
+Preview route: Toolbar — `/toolbar`
+
+### Formatting controls
+
+```tsx
+<Toolbar aria-label="Formatting">
+  <ToolbarGroup>
+    <ToolbarButton iconOnly aria-label="Bold"><BoldIcon /></ToolbarButton>
+    <ToolbarButton iconOnly aria-label="Italic"><ItalicIcon /></ToolbarButton>
+  </ToolbarGroup>
+  <ToolbarSeparator />
+  <ToolbarInput aria-label="Font size" defaultValue="14" />
+</Toolbar>
+```
+
+## base/tooltip
+
+```tsx
+import { … } from "themelia-ui/base/tooltip"
+import "themelia-ui/base/tooltip.css"
+```
+
+Preview route: Tooltip — `/tooltip`
+
+### Tooltip
+
+```tsx
+<Tooltip>
+  <TooltipTrigger render={<Button buttonStyle="outline" tone="neutral" />}>
+    Hover me
+  </TooltipTrigger>
+  <TooltipContent>Explains the control.</TooltipContent>
+</Tooltip>
+```
+
+## base/typography
+
+```tsx
+import { … } from "themelia-ui/base/typography"
+import "themelia-ui/base/typography.css"
+```
+
+Preview route: Typography — `/typography`
+
+### Text roles
+
+```tsx
+<Text type="secondary">Supporting copy</Text>
+```
+
+### Size
+
+```tsx
+<Text size="xs">Metadata</Text>
+```
+
+### Heading
+
+```tsx
+<Heading level={2} size="lg" subHeading="Supporting line">Title</Heading>
+```
+
+### Numeric
+
+```tsx
+<Text numeric>1,234,567.89</Text>
+```
+
+### Alignment
+
+```tsx
+<Text align="right" numeric>1,234.50</Text>
+```
+
+### Truncation
+
+```tsx
+{/* Stack sets min-width: 0 on itself, so a nested one can still shrink */}
+<Stack gap="sm">
+  <Text truncate>{veryLongName}</Text>
+</Stack>
+```
+
+### DisplayLabel and TextLink
+
+```tsx
+<TextLink render={<RouterLink to="/x" />}>Go</TextLink>
+```
+
+## base/upload
+
+```tsx
+import { … } from "themelia-ui/base/upload"
+import "themelia-ui/base/upload.css"
+```
+
+Preview route: File upload — `/file-upload`
+
+### FileUpload
+
+```tsx
+<FileUpload
+  multiple
+  accept=".pdf,image/*"
+  maxSizeBytes={5 * 1024 * 1024}
+  maxFiles={4}
+  value={files}
+  onValueChange={setFiles}
+  onRejectedFiles={setRejected}
+/>
+```
+
+### AvatarUpload and ImageUpload
+
+```tsx
+<AvatarUpload onValueChange={setAvatar} />
+<ImageUpload previewUrl={coverUrl} onValueChange={setCover} />
+```
+
+### Upload progress
+
+```tsx
+<UploadProgressList items={items} onRetry={retry} onRemove={remove} />
+```
+
+### UploadTray
+
+```tsx
+<UploadTray
+  items={items}
+  onAddFiles={start}
+  onRetry={retry}
+  onRemove={remove}
+  onClearAll={clear}
+/>
+```
+
+### MediaGallery
+
+```tsx
+<MediaGallery
+  value={images}
+  onValueChange={setImages}
+  maxFiles={6}
+/>
+```
+
+## base/value-inputs
+
+```tsx
+import { … } from "themelia-ui/base/value-inputs"
+import "themelia-ui/base/value-inputs.css"
+```
+
+Preview route: Color input — `/color-input`
+
+### ColorInput
+
+```tsx
+<ColorInput value={color} onValueChange={setColor} />
+```
+
+### What the picker hands back
+
+```tsx
+<ColorInput format="hex" … />
+<ColorInput format="rgb" … />
+<ColorInput format="hsl" … />
+```
+
+### PhoneInput
+
+```tsx
+<PhoneInput
+  prefix={prefix}
+  onPrefixChange={setPrefix}
+  value={number}
+  onChange={(e) => setNumber(e.target.value)}
+/>
+```
+
+### SliderField
+
+```tsx
+<SliderField value={volume} onValueChange={setVolume} showValue unit="%" />
+```
+
+### Sizes
+
+```tsx
+<SliderField size="sm" />   {/* the default — a row in a form */}
+<SliderField size="md" />   {/* touch, media controls */}
+```
+
+### Vertical, and a range
+
+```tsx
+<SliderField orientation="vertical" value={level} onValueChange={setLevel} />
+<SliderField value={[20, 70]} onValueChange={setRange} />
+```
+
+### Slider
+
+```tsx
+<Slider defaultValue={40} aria-label="Zoom" />
+```
+
+### TagsInput
+
+```tsx
+<TagsInput value={tags} onValueChange={setTags} maxTags={5} showCount showClearAll />
+```
+
+## features/actions
+
+```tsx
+import { … } from "themelia-ui/features/actions"
+import "themelia-ui/features/actions.css"
+```
+
+Preview route: Actions — `/actions`
+
+### One definition, many surfaces
+
+```tsx
+const actions = [defineAction({
+  id: "invoice.delete",
+  label: "Delete invoice",
+  surfaces: ["page", "card"],
+  modality: { type: "alert", title: "Delete this invoice?", tone: "destructive" },
+  run: async ({ payload }) => api.delete(payload),
+})]
+
+useRegisterActions(actions, { scope: "invoice" })
+const pageActions = useActionSurface({ surface: "page", scope: "invoice", payload: id })
+```
+
+## features/activities
+
+```tsx
+import { … } from "themelia-ui/features/activities"
+import "themelia-ui/features/activities.css"
+```
+
+Preview route: Activities — `/activities`
+
+### ActivityFeed
+
+```tsx
+<ActivityFeed
+  activities={activities}
+  density="rich"
+  currentUserId="u1"
+  resources={registry}
+  onActorClick={(actor) => open(actor)}
+/>
+```
+
+### ActivityLog
+
+```tsx
+<ActivityLog
+  entries={entries}
+  resources={resources}
+  canModerate
+  composer={{ enabled: true, context, onSubmit }}
+/>
+```
+
+### createActivityEventAdapter
+
+```tsx
+// Pinned to the page's kind union, so the entries it produces line up with the rest.
+const toEntry = createActivityEventAdapter<AuditRow, CommentUser, unknown, Kind>({
+  id: (row) => row.uuid,
+  timestamp: (row) => row.at,
+  kind: () => "audit",
+  actor: (row) => row.who,
+  action: (row) => row.verb,
+  target: (row) => row.subject,
+})
+
+const entries = auditRows.map(toEntry)
+```
+
+## features/ai-chat
+
+```tsx
+import { … } from "themelia-ui/features/ai-chat"
+import "themelia-ui/features/ai-chat.css"
+```
+
+Preview route: AI chat — `/ai-chat`
+
+### The chat
+
+```tsx
+<AiChat
+  messages={messages}
+  inputValue={input}
+  onInputChange={setInput}
+  onSubmit={({ text, attachments }) => send(text, attachments)}
+  onStop={() => abort()}
+  streaming={isStreaming}
+  agent={{ name: "Atlas", subtitle: "claude-opus-5", status: "thinking" }}
+  suggestions={suggestions}
+  onPickSuggestion={(s) => setInput(String(s.label))}
+/>
+```
+
+### A turn
+
+```tsx
+<AiMessageBubble role="assistant" authorName="Atlas" onRegenerate={retry}>
+  The totals are summed as floats.
+</AiMessageBubble>
+
+<AiShimmer>Thinking…</AiShimmer>
+```
+
+### Reasoning and plans
+
+```tsx
+<AiReasoning streaming={isThinking} durationSeconds={4}>
+  {trace}
+</AiReasoning>
+
+<AiChainOfThought steps={steps} streaming />
+<AiTask task={plan} />
+```
+
+### Tool calls
+
+```tsx
+<AiToolCall
+  name="search_codebase"
+  status="success"
+  durationMs={820}
+  args={JSON.stringify(args, null, 2)}
+  result={summary}
+/>
+```
+
+### What it produced
+
+```tsx
+<AiArtifact title="totals.ts" subtitle="TypeScript" copyText={code} onDownload={save}>
+  <AiCodeBlock code={code} language="TypeScript" showLineNumbers highlightLines={[2, 8]} />
+</AiArtifact>
+
+<AiSources sources={sources} defaultExpanded />
+<AiSources sources={sources} variant="avatars" />
+```
+
+### Asking first
+
+```tsx
+<AiConfirmation
+  title="Run the backfill on 4,102 invoices"
+  description="Rewrites every amount into cents. Not reversible."
+  tone="destructive"
+  status={status}
+  onApprove={approve}
+  onReject={reject}
+/>
+```
+
+## features/async-preview
+
+```tsx
+import { … } from "themelia-ui/features/async-preview"
+import "themelia-ui/features/async-preview.css"
+```
+
+Preview route: Async preview — `/async-preview`
+
+### Fetching on open
+
+```tsx
+<AsyncPreview.Root
+  type="customer"
+  context={{ id }}
+  cacheKey={`customer:${id}\
+```
+
+### The four states
+
+```tsx
+// null → empty, thrown → error
+onShow={async ({ signal }) => {
+  const response = await fetch(url, { signal })
+  if (!response.ok) throw new Error(response.statusText)
+  return (await response.json()) ?? null
+}}
+```
+
+### PreviewTriggerCell
+
+```tsx
+<PreviewTriggerCell
+  value={row.customerName}
+  secondary={row.reference}
+  hasPreview={row.customerId !== null}
+  disabledReason="Imported without a customer record"
+/>
+```
+
+## features/combobox
+
+```tsx
+import { … } from "themelia-ui/features/combobox"
+import "themelia-ui/features/combobox.css"
+```
+
+Preview route: Async combobox — `/async-combobox`
+
+### AsyncCombobox
+
+```tsx
+<AsyncCombobox
+  items={items}
+  searchValue={query}
+  onSearchValueChange={setQuery}
+  selectedValue={selected}
+  onSelectedValueChange={setSelected}
+  getItemLabel={(c) => c.name}
+  getItemKey={(c) => c.code}
+  getItemGroup={(c) => c.region}
+  highlightMatch
+/>
+```
+
+### AsyncMultiCombobox
+
+```tsx
+<AsyncMultiCombobox
+  items={items}
+  selectedValues={selected}
+  onSelectedValuesChange={setSelected}
+  …
+/>
+```
+
+### applyButton
+
+```tsx
+<AsyncMultiCombobox applyButton onApply={run} … />
+```
+
+### creatable
+
+```tsx
+<AsyncCombobox creatable onCreate={(name) => create(name)} … />
+```
+
+### ResourceCombobox
+
+```tsx
+<ResourceCombobox
+  fetcher={({ query, limit, signal }) => api.search(query, { limit, signal })}
+  getKey={(c) => c.code}
+  getLabel={(c) => c.name}
+  getDescription={(c) => c.capital}
+  getMeta={(c) => c.region}
+/>
+```
+
+### SuggestionsCombobox
+
+```tsx
+const suggestions = useSuggestions({ fetchData, minQueryLength: 1 })
+
+// or, when it really is a combobox:
+<SuggestionsCombobox
+  fetchData={(q, { signal }) => api.search(q, { signal })}
+  itemKey={(c) => c.code}
+  itemText={(c) => c.name}
+/>
+```
+
+## features/comments
+
+```tsx
+import { … } from "themelia-ui/features/comments"
+import "themelia-ui/features/comments.css"
+```
+
+Preview route: Comments — `/comments`
+
+### A thread
+
+```tsx
+<Comments
+  context={{ id: "4417", type: "booking" }}
+  comments={comments}
+  canModerate
+  resources={resources}
+  onSubmit={(values, helpers) => {
+    post(values)
+    helpers.reset()
+  }}
+  onUpdate={update}
+  onDelete={remove}
+  attachments={{ onUpload, maxSize: 5_000_000, maxFiles: 3 }}
+/>
+```
+
+### Three stored formats
+
+```tsx
+{ contentType: "html", content: "<p>…<span data-ref-id='user:1'>@Maria</span></p>" }
+{ contentType: "text", content: "Two lines.\\nKept as written." }
+{ contentType: "rich", content: JSON.stringify({ blocks: [...] }) }
+```
+
+### Empty, and read-only
+
+```tsx
+<Comments bare canComment={false} comments={[]} … />
+```
+
+## features/data-view
+
+```tsx
+import { … } from "themelia-ui/features/data-view"
+import "themelia-ui/features/data-view.css"
+```
+
+Preview route: Data view — `/data-view`
+
+### An index
+
+```tsx
+<DataView
+  data={bookings}
+  columns={columns}
+  filtering={{
+    filters,
+    activeFilters: active,
+    onFilterChange: setActive,
+    tabs: savedViews,
+  }}
+  table={{ enableSorting: true, enableColumnVisibility: true }}
+  slots={{ footer: <DataViewPagination page={page} pageCount={4} onPageChange={setPage} /> }}
+/>
+```
+
+## features/event-calendar
+
+```tsx
+import { … } from "themelia-ui/features/event-calendar"
+import "themelia-ui/features/event-calendar.css"
+```
+
+Preview route: Event calendar — `/event-calendar`
+
+### The grid
+
+```tsx
+<EventCalendar
+  events={events}
+  categories={categories}
+  enableCategoryFilter
+  onEventClick={(event) => open(event.id)}
+  onDayClick={(date, events) => setDay({ date, events })}
+/>
+```
+
+### The agenda
+
+```tsx
+<EventCalendar viewMode="agenda" events={events} categories={categories} />
+```
+
+### A week, and a range
+
+```tsx
+<EventCalendar
+  viewMode="week"
+  minDate={new Date(2026, 8, 1)}
+  maxDate={new Date(2026, 8, 30)}
+  disabledDates={(date) => date.getDay() === 0}
+/>
+```
+
+## features/filters
+
+```tsx
+import { … } from "themelia-ui/features/filters"
+import "themelia-ui/features/filters.css"
+```
+
+Preview route: Filters — `/filters`
+
+### The bar
+
+```tsx
+<FilterProvider
+  filters={filters}
+  activeFilters={active}
+  onFilterChange={setActive}
+>
+  <FilterLayout tabs={savedViews} showClearFilters />
+</FilterProvider>
+
+// And when a change lands, hand the query to your own router:
+const query = serializeFiltersToQuery(filters, active)
+```
+
+## features/global-search
+
+```tsx
+import { … } from "themelia-ui/features/global-search"
+import "themelia-ui/features/global-search.css"
+```
+
+Preview route: Global search — `/global-search`
+
+### The panel
+
+```tsx
+<GlobalSearch<Group>
+  query={query}
+  onQueryChange={setQuery}
+  results={results}
+  loading={isFetching}
+  groupLabels={{ people: "People", bookings: "Bookings" }}
+  idleSections={recentAndSuggested}
+  onResultSelect={(result) => navigate(result.data.href)}
+/>
+```
+
+### The palette
+
+```tsx
+<GlobalSearchDialog
+  open={open}
+  onOpenChange={setOpen}
+  query={query}
+  onQueryChange={setQuery}
+  results={results}
+  onResultSelect={(result) => { setOpen(false); navigate(result.id) }}
+/>
+```
+
+## features/kanban
+
+```tsx
+import { … } from "themelia-ui/features/kanban"
+import "themelia-ui/features/kanban.css"
+```
+
+Preview route: Kanban & sync — `/kanban`
+
+### The board
+
+```tsx
+<Kanban
+  value={board}
+  onValueChange={setBoard}
+  getItemValue={(card) => card.id}
+  onItemMove={(event) => api.persist(event)}
+  itemActions={(card) => card.done ? [reopen] : [archive]}
+>
+  <KanbanBoard>
+    {columns.map((column) => (
+      <KanbanColumn key={column.id} value={column.id}>
+        <header>{column.title}</header>
+        <KanbanColumnContent value={column.id}>
+          {board[column.id].map((card) => (
+            <KanbanItem key={card.id} value={card.id}>…</KanbanItem>
+          ))}
+        </KanbanColumnContent>
+      </KanbanColumn>
+    ))}
+  </KanbanBoard>
+  <KanbanOverlay />
+</Kanban>
+```
+
+### Where the handle goes
+
+```tsx
+<ActionDialog
+  title="Run a sync"
+  formId="sync-form"
+  trigger={<Button>Sync</Button>}
+>
+  <SyncRangeForm
+    formId="sync-form"
+    options={windows}
+    syncOptions={families}
+    onSubmit={({ hours, options }) => api.sync(hours, options)}
+  />
+</ActionDialog>
+```
+
+## features/map
+
+```tsx
+import { … } from "themelia-ui/features/map"
+import "themelia-ui/features/map.css"
+```
+
+Preview route: Map — `/map`
+
+### A map with controls
+
+```tsx
+<Map center={[51.5687, -0.7746]} zoom={13}>
+  <MapLayers defaultTileLayer="Streets">
+    <MapTileLayer name="Streets" />
+    <MapTileLayer name="Terrain" url="https://tile.opentopomap.org/{z}/{x}/{y}.png" />
+    <MapLayerGroup name="Venues">
+      {venues.map((venue) => (
+        <MapMarker key={venue.id} position={venue.position}>
+          <MapPopup>{venue.name}</MapPopup>
+        </MapMarker>
+      ))}
+    </MapLayerGroup>
+    <MapLayersControl />
+  </MapLayers>
+  <MapZoomControl />
+  <MapFullscreenControl position="bottom-right" />
+</Map>
+```
+
+### Drawing
+
+```tsx
+<Map center={center} zoom={13}>
+  <MapTileLayer />
+  <MapDrawControl onLayersChange={(group) => save(group.toGeoJSON())}>
+    <MapDrawMarker />
+    <MapDrawPolyline />
+    <MapDrawPolygon />
+    <MapDrawRectangle />
+    <MapDrawCircle />
+    <MapDrawEdit />
+    <MapDrawDelete />
+    <MapDrawUndo />
+  </MapDrawControl>
+</Map>
+```
+
+### Place autocomplete
+
+```tsx
+<PlaceAutocomplete
+  limit={5}
+  onPlaceSelect={(feature) => {
+    const [lon, lat] = feature.geometry.coordinates
+    map.flyTo([lat, lon], 15)
+  }}
+/>
+
+// Inside a map, as a control:
+<MapSearchControl position="top-left" />
+```
+
+## features/media-library
+
+```tsx
+import { … } from "themelia-ui/features/media-library"
+import "themelia-ui/features/media-library.css"
+```
+
+Preview route: Media library — `/media-library`
+
+### The browser
+
+```tsx
+<MediaLibrary
+  items={assets}
+  collections={collections}
+  value={selected}
+  onValueChange={setSelected}
+  onItemUpdate={(item, patch) => api.updateAsset(item.id, patch)}
+  onItemDelete={(item) => api.deleteAsset(item.id)}
+  onUpload={(files, options, { setProgress }) => api.upload(files, options, setProgress)}
+  onConfirm={(items) => attach(items)}
+/>
+```
+
+### Acting on a selection
+
+```tsx
+<MediaLibrary
+  items={assets}
+  bulkActions={({ selectedItems, clearSelection }) => (
+    <>
+      <Button tone="neutral" buttonStyle="outline">Download</Button>
+      <Button tone="destructive" buttonStyle="outline"
+        onClick={() => { remove(selectedItems); clearSelection() }}>
+        Delete
+      </Button>
+    </>
+  )}
+/>
+```
+
+### As a picker
+
+```tsx
+<MediaLibraryDialog
+  open={open}
+  onOpenChange={setOpen}
+  items={assets}
+  selectionMode="single"
+  confirmOnSelect
+  onConfirm={([asset]) => setCover(asset)}
+/>
+```
+
+### Attached to a record
+
+```tsx
+<MediaResourceGallery
+  items={attached}
+  primaryId={coverId}
+  onPrimaryChange={setCoverId}
+  onReorder={(ids, items) => setAttached(items)}
+  onRemove={(id) => detach(id)}
+  onAdd={() => setPickerOpen(true)}
+  maxItems={8}
+/>
+```
+
+## features/mentions
+
+```tsx
+import { … } from "themelia-ui/features/mentions"
+import "themelia-ui/features/mentions.css"
+```
+
+Preview route: Mentions — `/mentions`
+
+### Typing a mention
+
+```tsx
+const editorRef = useRef<MentionEditorHandle>(null)
+const mentions = useMentions<"user" | "booking">({ resources, editorRef })
+
+<div style={{ position: "relative" }}>
+  <Editor ref={editorRef} onCaretChange={mentions.handleCaretChange} />
+  <MentionInlineSuggestions
+    {...mentions}
+    open={mentions.triggerActive && mentions.pickerOpen}
+    loading={mentions.isLoading}
+    onManualKindChange={() => mentions.setManualKindOverride(true)}
+    onSelect={mentions.pickSuggestion}
+  />
+</div>
+```
+
+### Rendering a stored body
+
+```tsx
+<MentionContent
+  html={comment.body}
+  mentions={comment.mentions}
+  resources={resources}
+/>
+```
+
+### Chips
+
+```tsx
+<MentionChip mention={mention} resource={resources[mention.kind]} />
+```
+
+## features/overlays
+
+```tsx
+import { … } from "themelia-ui/features/overlays"
+import "themelia-ui/features/overlays.css"
+```
+
+Preview route: Action overlays — `/action-overlays`
+
+### ActionDialog
+
+```tsx
+<ActionDialog
+  title="Rename workspace"
+  trigger={<Button>Rename</Button>}
+  onConfirm={save}
+/>
+```
+
+### ConfirmDialog
+
+```tsx
+<ConfirmDialog
+  destructive
+  title="Delete this invoice?"
+  description="This cannot be undone."
+  trigger={<Button tone="destructive">Delete</Button>}
+  onAsyncConfirm={remove}
+/>
+```
+
+### ActionSheet
+
+```tsx
+<ActionSheet
+  side="inline-end"
+  title="Filters"
+  modality="non-modal"
+  trigger={<Button>Filter</Button>}
+/>
+```
+
+### Driving them from elsewhere
+
+```tsx
+const overlays = useOverlayVisibilityGroup(["edit", "remove"], {
+  closeOthersOnOpen: true,
+})
+
+<Button onClick={overlays.edit.show}>Edit</Button>
+<ActionDialog {...overlays.edit.overlayProps} title="Edit" />
+```
+
+## features/products
+
+```tsx
+import { … } from "themelia-ui/features/products"
+import "themelia-ui/features/products.css"
+```
+
+Preview route: Options & variants — `/product-variants`
+
+### Options and variants together
+
+```tsx
+<ProductVariantsManager
+  optionGroups={options}
+  variants={variants}
+  groupByOptionId="size"
+  cellDisplay="field"
+  onCreateOption={createOption}
+  onSaveEditingOption={(option, draft) => save(option.id, draft)}
+  onAddValue={addValue}
+  onGenerateVariants={generate}
+  onVariantFieldBlur={(variant, field, value) => patch(variant.id, field, value)}
+/>
+```
+
+### The two option surfaces
+
+```tsx
+<ProductOptionsSummary options={summary} onManageOptions={openMatrix} />
+
+<ProductOptionsMatrix
+  optionGroups={groups}
+  onSaveEditingOption={(option, draft) => save(option.id, draft)}
+  onAddValue={addValue}
+  onDeleteOption={remove}
+  confirmDelete            // on by default — removing an option removes its variants
+/>
+```
+
+### Variants
+
+```tsx
+<ProductVariantsBulkTable
+  variants={variants}
+  optionGroups={groups}
+  groupByOptionId="size"
+  cellDisplay={{ sku: "field", price: "field", inventory: "text" }}
+  onVariantFieldBlur={(variant, field, value) => api.patch(variant.id, { [field]: value })}
+  onBulkDelete={(rows) => api.removeMany(rows.map((row) => row.id))}
+/>
+```
+
+### One variant, read and edited
+
+```tsx
+<ProductVariantDetails
+  variant={selected}
+  optionItems={options}
+  onBack={() => setSelected(null)}
+  onEditVariant={(variant) => setEditing(variant)}
+/>
+
+<ProductVariantEditor
+  defaultValue={{ name: "M · Trail", sku: "TRL-29-M-TR", price: "€1,850" }}
+  optionFields={[{ id: "size", label: "Frame size", choices: sizes }]}
+  statusOptions={statuses}
+  onSubmit={(values) => api.save(values)}
+  onDelete={(values) => api.remove(values)}
+/>
+```
+
+### Nothing yet
+
+```tsx
+<ProductVariantsBulkTable
+  variants={[]}
+  onGenerateVariants={() => api.generate(productId)}
+/>
+```
+
+### Overview and quote
+
+```tsx
+<ProductOverview
+  title="Trailhead 29er"
+  status="Live"
+  statusTone="success"
+  metrics={[{ id: "variants", label: "Variants", value: "18" }]}
+/>
+
+<ProductQuotePreviewCard
+  lines={[…, { id: "total", label: "Total", value: "€2,268", emphasis: true }]}
+  onRecalculate={() => api.quote(id)}
+/>
+```
+
+### Readiness, structure, operations
+
+```tsx
+<ProductReadinessCard
+  score={72}
+  items={[{ id: "price", label: "Pricing", tone: "warning", value: "1 missing" }]}
+  onSelectReadinessItem={(item) => open(item.id)}
+/>
+```
+
+### Details, contract, policies
+
+```tsx
+<ProductContractOverview
+  metrics={metrics}
+  terms={terms}          // MetadataListItem[]
+  rules={rules}
+  onCreateRule={() => …}
+/>
+```
+
+## features/resource
+
+```tsx
+import { … } from "themelia-ui/features/resource"
+import "themelia-ui/features/resource.css"
+```
+
+Preview route: Resource shells — `/resource`
+
+### ResourceIndexShell
+
+```tsx
+<ResourceIndexShell
+  title="Invoices"
+  description="Everything billed on this account."
+  actions={<Button>New invoice</Button>}
+  loading={isLoading}
+  error={error}
+  empty={rows.length === 0}
+  onRetry={refetch}
+  toolbar={<ResourceActionBar leading={<SearchInput />} />}
+>
+  <InvoiceTable rows={rows} />
+</ResourceIndexShell>
+```
+
+### ResourceShowShell
+
+```tsx
+<ResourceShowShell
+  title="INV-4417"
+  slots={{ aside: <PaymentPanel /> }}
+>
+  <ResourceDetailsSection title="Details" metadata={facts} />
+</ResourceShowShell>
+```
+
+### TabbedResourceShell
+
+```tsx
+<TabbedResourceShell
+  tabs={tabs}
+  activeTab={tab}
+  onTabChange={setTab}
+  title="INV-4417"
+>
+  {panelFor(tab)}
+</TabbedResourceShell>
+```
+
+### ResourceEmptyState
+
+```tsx
+slots={{ empty: (
+  <ResourceEmptyState
+    mediaVariant="illustration"
+    media={<StackedCardsIllustration />}
+    title="No invoices yet"
+    action={<Button>New invoice</Button>}
+    border
+  />
+) }}
+```
+
+## features/resource-assignment
+
+```tsx
+import { … } from "themelia-ui/features/resource-assignment"
+import "themelia-ui/features/resource-assignment.css"
+```
+
+Preview route: Resource assignment — `/resource-assignment`
+
+### With a resource
+
+```tsx
+<SharedResourceCard<Venue, VenueHit>
+  icon={<MapPinIcon />}
+  title="Venue"
+  resource={venue}
+  sections={[{ id: "facts", Component: ({ context }) => <VenueFacts venue={context.resource!} /> }]}
+  viewLink={{ href: `/venues/${venue.id}`, label: "Open venue" }}
+  selector={{
+    title: "Choose a venue",
+    confirmText: "Assign venue",
+    cancelText: "Cancel",
+    SelectorComponent: VenuePicker,
+    mapInitialSelected: (venue) =>
+      venue ? { id: venue.id, label: venue.name, description: "" } : null,
+    getSelectionLabel: (hit) => hit.label,
+    onConfirmSelection: async (hit) => { await api.assign(hit.id) },
+  }}
+/>
+```
+
+### With none
+
+```tsx
+<SharedResourceCard resource={null} selector={…} />
+// no selector — the empty state does not pretend there is something to do
+<SharedResourceCard resource={null} />
+```
+
+## features/rich-text-editor
+
+```tsx
+import { … } from "themelia-ui/features/rich-text-editor"
+import "themelia-ui/features/rich-text-editor.css"
+```
+
+Preview route: Rich text editor — `/rich-text-editor`
+
+### The editor
+
+```tsx
+<RichTextEditor
+  value={body}
+  onValueChange={setBody}
+  showCounts
+  maxLength={280}
+  placeholder="Write something…"
+/>
+```
+
+### compact
+
+```tsx
+<RichTextEditor
+  compact
+  value={note}
+  onValueChange={setNote}
+  hideSourceToggle
+  footerSlot={<><AttachmentChips /><Button>Post</Button></>}
+/>
+```
+
+### What comes out
+
+```tsx
+<RichText html={body} />
+```
+
+### On execCommand
+
+```tsx
+// The default. Nothing to install, and no document model.
+<RichTextEditor value={html} onValueChange={setHtml} />
+
+// TipTap, behind its own exact subpath — a real undo stack, a selection that
+// survives a re-render, and commands that are transactions. Install
+// @tiptap/core, @tiptap/pm and @tiptap/starter-kit; importing the generic
+// editor resolves none of them.
+import { createTiptapEngine } from "themelia-ui/features/rich-text-editor/tiptap"
+
+const engine = useMemo(() => createTiptapEngine({ element, content: html }), [element])
+<RichTextEditor engine={engine} value={html} onValueChange={setHtml} />
+
+// Or your own: getState, setHtml, focus, execute, subscribe, destroy.
+// getState must return the SAME object until something changes — the shell
+// reads it through useSyncExternalStore, which compares by identity.
+```
+
+## features/schema-form
+
+```tsx
+import { … } from "themelia-ui/features/schema-form"
+import "themelia-ui/features/schema-form.css"
+```
+
+Preview route: Schema form — `/schema-form`
+
+### One surface
+
+```tsx
+<SchemaForm
+  schema={{
+    sections: [{ id: "identity", title: "Identity", columns: 2 }],
+    fields: [
+      { key: "name", label: "Venue name", sectionId: "identity", required: true },
+      { key: "cutoff", type: "integer", label: "Cut-off",
+        hidden: (values) => values.selfService !== true },
+    ],
+  }}
+  onSubmit={(values) => api.save(values)}
+  onReset={() => undefined}
+/>
+```
+
+### One surface per section
+
+```tsx
+<SchemaForm schema={schema} layout="cards" onSubmit={save} />
+```
+
+## features/table
+
+```tsx
+import { … } from "themelia-ui/features/table"
+import "themelia-ui/features/table.css"
+```
+
+Preview route: Data table — `/data-table`
+
+### An index table
+
+```tsx
+<DataTable
+  columns={columns}
+  data={bookings}
+  enableSorting
+  enableRowSelection
+  enableColumnVisibility
+  stickyFirstColumn
+  getRowId={(row) => row.id}
+  rowActions={(row) => [
+    { id: "open", label: "Open", onClick: () => navigate(row.id) },
+    { id: "archive", label: "Archive", tone: "destructive", onClick: () => archive(row) },
+  ]}
+/>
+```
+
+### Cells
+
+```tsx
+cell: ({ row }) => (
+  <CellStack values={[
+    row.customer,
+    [row.customerEmail, "email"],
+    row.vip && { value: "VIP", kind: "mono" },
+  ]} />
+)
+```
+
+### Acting on a selection
+
+```tsx
+<DataTable
+  enableRowSelection
+  initialState={{ rowSelection: { b2: true, b4: true } }}
+  bulkActions={({ selectedRowCount, clearSelection }) => (
+    <Button onClick={() => archive(selectedRowCount)}>Archive selected</Button>
+  )}
+/>
+```
+
+## features/theme-tweaker
+
+```tsx
+import { … } from "themelia-ui/features/theme-tweaker"
+import "themelia-ui/features/theme-tweaker.css"
+```
+
+Preview route: Theme tweaker — `/theme-tweaker`
+
+### The editor
+
+```tsx
+<ThemeTweaker
+  value={theme}
+  onValueChange={setTheme}
+  target="self"
+  onExport={(artifact) => api.saveTheme(artifact.cssText)}
+/>
+```
+
+### ThemeScope alone
+
+```tsx
+<ThemeScope theme={createTheme({ mode: "dark", dark: { "--primary": "…" } })}>
+  <YourApp />
+</ThemeScope>
+```
+
+## forms
+
+```tsx
+import { … } from "themelia-ui/forms"
+```
+
+Preview route: Form binding — `/form-binding`
+
+### useStateFormControl
+
+```tsx
+const control = useStateFormControl({ email: "", workspace: "acme-corp" })
+
+function BoundInput({ name, label, control }) {
+  const field = useFormFieldBinding<string>({ name, control })
+  return (
+    <FormField label={label} error={field.error}>
+      <Input
+        value={field.value ?? ""}
+        onChange={(event) => field.onValueChange(event.target.value)}
+        onBlur={field.onBlur}
+      />
+    </FormField>
+  )
+}
+```
+
+### The contract
+
+```tsx
+import { rhfFormControl } from "themelia-ui/forms-rhf"
+
+const form = useForm({ defaultValues: { email: "" } })
+const control = rhfFormControl(form.control)
+
+const email = useFormFieldBinding<string>({ name: "email", control })
+```
+
+## layout/app-shell
+
+```tsx
+import { … } from "themelia-ui/layout/app-shell"
+import "themelia-ui/layout/app-shell.css"
+```
+
+Preview route: App shell — `/app-shell`
+
+### The shell
+
+```tsx
+<SidebarProvider>
+  <Sidebar collapsible="icon">
+    <SidebarHeader>…</SidebarHeader>
+    <SidebarContent>
+      <SidebarGroup>
+        <SidebarGroupLabel>Workspace</SidebarGroupLabel>
+        <SidebarMenu>
+          <SidebarMenuItem>
+            <SidebarMenuButton active>
+              <FileTextIcon />
+              <span>Invoices</span>
+            </SidebarMenuButton>
+            <SidebarMenuBadge>12</SidebarMenuBadge>
+          </SidebarMenuItem>
+        </SidebarMenu>
+      </SidebarGroup>
+    </SidebarContent>
+    <SidebarRail />
+  </Sidebar>
+  <SidebarInset>{children}</SidebarInset>
+</SidebarProvider>
+```
+
+### TopbarSidebarLayout
+
+```tsx
+<TopbarSidebarLayout
+  logo={<Brand />}
+  slots={{
+    headerCenter: <HeaderSearch onOpen={openPalette} />,
+    headerEnd: (
+      <>
+        <HeaderNotifications notifications={items} unreadCount={3} />
+        <HeaderUserMenu user={user} onLogout={signOut} />
+      </>
+    ),
+  }}
+  sidebar={<AppSidebar navigationGroups={NAVIGATION} currentUrl={url} />}
+>
+  {children}
+</TopbarSidebarLayout>
+```
+
+### StackedLayout
+
+```tsx
+<StackedLayout
+  header={<Nav />}
+  headerEnd={<Account />}
+>
+  {children}
+</StackedLayout>
+```
+
+## layout/auth
+
+```tsx
+import { … } from "themelia-ui/layout/auth"
+import "themelia-ui/layout/auth.css"
+```
+
+Preview route: Auth shells — `/auth-shell`
+
+### AuthShell
+
+```tsx
+<AuthShell
+  brand={{ logo: <Logo />, label: "Acme", description: "Operations console", href: "/" }}
+  title="Sign in"
+  description="Use your work account."
+  banner={<Alert tone="warning">That link has expired.</Alert>}
+  postCard={<Text size="sm">New here? <TextLink>Create an account</TextLink></Text>}
+  footerLinks={help}
+  policyLinks={policy}
+>
+  {fields}
+</AuthShell>
+```
+
+### AuthCard
+
+```tsx
+<AuthCard
+  eyebrow="Step 2 of 3"
+  title="Confirm your email"
+  headerEnd={<Badge>2 / 3</Badge>}
+  media={<Illustration />}
+  footer={<Button buttonStyle="ghost">Back</Button>}
+>
+  {fields}
+</AuthCard>
+```
+
+### Split
+
+```tsx
+<AuthShell
+  variant="split"
+  splitSide="start"
+  splitPanel={<Marketing />}
+  title="Sign in"
+>
+  {fields}
+</AuthShell>
+```
+
+## layout/containers
+
+```tsx
+import { … } from "themelia-ui/layout/containers"
+import "themelia-ui/layout/containers.css"
+```
+
+Preview route: Containers — `/containers`
+
+### The four blocks
+
+```tsx
+<PageViewport>
+  <Container maxWidth="xl" gutter="md">
+    <Section>
+      <PageHeading title="Invoices" />
+      <Card>…</Card>
+    </Section>
+  </Container>
+</PageViewport>
+```
+
+### TwoColumnLayout
+
+```tsx
+<TwoColumnLayout
+  main={<InvoiceForm />}
+  aside={<SummaryCard />}
+  asidePosition="end"
+  stickyAside
+/>
+```
+
+## layout/header
+
+```tsx
+import { … } from "themelia-ui/layout/header"
+import "themelia-ui/layout/header.css"
+```
+
+Preview route: Header — `/header`
+
+### Header
+
+```tsx
+<Header
+  breadcrumbs={[{ label: "Billing", href: "/billing" }, { label: "Invoices" }]}
+  slots={{
+    center: <SearchInput />,
+    right: <><Notifications /><Account /></>,
+  }}
+/>
+```
+
+### Breadcrumbs are built in
+
+```tsx
+<Header
+  homeCrumb={{ label: "Home", href: "/" }}
+  breadcrumbs={[{ label: "Settings", href: "/settings" }, { label: "Members" }]}
+/>
+```
+
+## layout/navigation
+
+```tsx
+import { … } from "themelia-ui/layout/navigation"
+import "themelia-ui/layout/navigation.css"
+```
+
+Preview route: Side nav & section nav — `/side-nav`
+
+### SideNav
+
+```tsx
+<SideNav groups={settingsNav} currentPath="/settings/members" />
+```
+
+### SectionNav
+
+```tsx
+<SectionNav
+  items={[
+    { id: "side-nav", label: "SideNav" },
+    { id: "section-nav", label: "SectionNav", depth: 2 },
+  ]}
+/>
+```
+
+## layout/page
+
+```tsx
+import { … } from "themelia-ui/layout/page"
+import "themelia-ui/layout/page.css"
+```
+
+Preview route: Page & page header — `/page`
+
+### PageHeading
+
+```tsx
+<PageHeading
+  breadcrumbs={<Breadcrumbs items={trail} />}
+  eyebrow="Workspace"
+  title="Invoices"
+  badges={[{ label: "Live", tone: "success" }]}
+  description="Everything issued in this workspace."
+  actions={<Button>New invoice</Button>}
+  withSeparator
+/>
+```
+
+### The slots, and why titlePrefix is not leading
+
+```tsx
+<PageHeading
+  titlePrefix={<FileTextIcon />}
+  title="Invoice #4417"
+  titleSuffix={<Text size="xs" type="secondary">v3</Text>}
+  description="Northwind Traders."
+  afterDescription={<Text size="xs" type="discrete">Updated 3 days ago</Text>}
+/>
+```
+
+### PageHeader
+
+```tsx
+<PageHeader
+  backHref="/invoices"
+  titleIcon={FileTextIcon}
+  title="Invoice #4417"
+  titleBadges={[{ label: "Paid", tone: "success" }]}
+  description="Northwind Traders — issued 1 September 2026."
+  actions={<PageActions actions={actions} />}
+/>
+```
+
+### PageActions
+
+```tsx
+<PageActions actions={actions} maxInlineActions={3} />
+<PageActions actions={actions} display="menu" />
+```
+
+### Page
+
+```tsx
+<Page
+  maxWidth="xl"
+  header={{ title: "Invoices", description: "Newest first." }}
+>
+  <Card title="September" />
+</Page>
+```
+
+## layout/settings
+
+```tsx
+import { … } from "themelia-ui/layout/settings"
+import "themelia-ui/layout/settings.css"
+```
+
+Preview route: Settings shell — `/settings-shell`
+
+### SettingsShell
+
+```tsx
+<SettingsShell
+  title="Settings"
+  groups={settingsNav}
+  currentPath="/settings/members"
+>
+  <Card title="Members" />
+</SettingsShell>
+```
+
+## layout/workspace
+
+```tsx
+import { … } from "themelia-ui/layout/workspace"
+import "themelia-ui/layout/workspace.css"
+```
+
+Preview route: Workspace record header — `/workspace-header`
+
+### WorkspaceRecordHeader
+
+```tsx
+<WorkspaceRecordHeader
+  title="Invoice #4417"
+  media={<Avatar />}
+  badges={<Badge tone="success" dot>Paid</Badge>}
+  metadata={[{ label: "Owner", value: "Jane McDonald" }]}
+  actions={<Button>Edit</Button>}
+/>
+```
+
+### Two tiers of action
+
+```tsx
+<WorkspaceRecordHeader
+  title="Deployment 41a9c2"
+  actions={<Button>Redeploy</Button>}
+  secondaryActions={<PillRadioGroup options={views} />}
+/>
+```
+
+## patterns/analytics
+
+```tsx
+import { … } from "themelia-ui/patterns/analytics"
+import "themelia-ui/patterns/analytics.css"
+```
+
+Preview route: Analytics — `/analytics`
+
+### Metric bar
+
+```tsx
+<MetricBar
+  metrics={metrics}
+  period={{ label: "Last 30 days", value: "30d" }}
+  footerText="Updated 10 minutes ago"
+/>
+```
+
+### Metric grid
+
+```tsx
+<MetricGrid metrics={metrics} variant="card" />
+```
+
+### Seven variants, one shape
+
+```tsx
+<Metric data={revenue} variant="bordered" />
+```
+
+### Comparison
+
+```tsx
+<MetricComparison
+  current={{ id: "c", label: "Revenue", value: 48200, valueType: "currency", currency: "EUR" }}
+  previous={{ id: "p", label: "Revenue", value: 42900, valueType: "currency", currency: "EUR" }}
+  currentPeriod="Aug 2026"
+  previousPeriod="Jul 2026"
+/>
+```
+
+### Gradient hero
+
+```tsx
+<MetricGradient title="Sessions" value="18,204" data={points} theme="ocean" />
+```
+
+### Micro grid
+
+```tsx
+<MetricMicroGrid cells={cells} />
+```
+
+### Chart card
+
+```tsx
+<ChartCard title="Sessions" config={config} surface="bordered">
+  <AreaChart data={series}>…</AreaChart>
+</ChartCard>
+```
+
+### Activity heatmap
+
+```tsx
+<ActivityHeatmap data={days} />
+```
+
+### Time ruler
+
+```tsx
+<TimeRuler hours={hours} currentHour={14} />
+```
+
+## patterns/timelines
+
+```tsx
+import { … } from "themelia-ui/patterns/timelines"
+import "themelia-ui/patterns/timelines.css"
+```
+
+Preview route: Timelines, onboarding & admin — `/blocks-admin`
+
+### Changelog
+
+```tsx
+<ChangelogTimeline
+  entries={[
+    { id: "1", kind: "added", title: "Saved views", version: "v3.4.0", timestamp: "16 Aug" },
+  ]}
+/>
+```
+
+### Milestones
+
+```tsx
+<MilestonesTimeline
+  milestones={[
+    { id: "3", title: "Token consolidation", status: "inProgress", progress: 68 },
+  ]}
+/>
+```
+
+### Steps, vertical and horizontal
+
+```tsx
+<Steps steps={steps} />
+<StepsBar steps={steps} />
+```
+
+### Onboarding checklist
+
+```tsx
+<Checklist
+  steps={[
+    { id: "3", status: "inProgress", title: "Connect a data source", content: <Form /> },
+  ]}
+/>
+```
+
+### Credential list
+
+```tsx
+<CredentialList items={keys} onAdd={add} onDelete={remove} />
+```
+
+### Role permissions
+
+```tsx
+<RolePermissions roleName="Editor" groups={groups} memberCount={12} onEdit={edit} />
+```
+
+### Sensitive action
+
+```tsx
+<SensitiveAction
+  title="Delete this workspace"
+  confirmation="Every dashboard, source and saved view goes with it."
+  action={<Button tone="destructive">Delete</Button>}
+/>
+```
+
+## primitives
+
+```tsx
+import { … } from "themelia-ui/primitives"
+import "themelia-ui/primitives.css"
+```
+
+Preview route: Address — `/primitive-address`
+
+### Ordered by country
+
+```tsx
+<Address value={{ line1, city, postalCode, country: "GB" }} />
+```
+
+### Inline, for a cell
+
+```tsx
+<Address value={value} format="inline" />
+```
+
+### Missing fields
+
+```tsx
+<Address value={{ line1: "221B Baker Street", city: "London" }} />
+```
+
+### Coordinates
+
+```tsx
+<Coordinates latitude={48.85837} longitude={2.29448} />
+<Coordinates latitude={48.85837} longitude={2.29448} format="dms" />
+```
+
+### DateRange
+
+```tsx
+<DateRange start={MARCH_3} end={MARCH_7} />
+<DateRange start={MARCH_3} end={APRIL_2} />
+<DateRange start={MARCH_3} end={NEXT_JAN} />
+<DateRange start={MARCH_3} end={APRIL_2} separator=" to " />
+<DateRange start={MARCH_3} end={null} />
+```
+
+### Dates and times
+
+```tsx
+<DatePrimitive value={WHEN} />
+<Time value={WHEN} />
+<DateTime value={WHEN} />
+<DatePrimitive value={WHEN} pattern="EEEE d MMMM yyyy" />
+<DatePrimitive value={null} />
+```
+
+### Localised names
+
+```tsx
+import { de } from "date-fns/locale"
+
+<UIProvider config={{ formatting: { locale: "de-DE" }, dates: { locale: de } }}>
+  <DatePrimitive value={when} pattern="EEEE d MMMM yyyy" />
+</UIProvider>
+```
+
+### Dimensions
+
+```tsx
+<Dimensions width={30} height={20} unit="cm" />
+<Dimensions width={30} height={20} depth={12} unit="cm" />
+<Dimensions width={1920} height={1080} unit="px" />
+<Dimensions width={null} height={null} />
+```
+
+### Duration
+
+```tsx
+<Duration value={45} />
+<Duration value={4520} />
+<Duration value={90} from="minutes" />
+<Duration value={4520} maxParts={1} />
+<Duration value={4520} unitDisplay="short" />
+<Duration value={null} />
+```
+
+### Email
+
+```tsx
+<Email value="jane@northwind.example" />
+<Email value="raj@northwind.example" display="Raj Patel" />
+<Email value={null} />
+```
+
+### File size
+
+```tsx
+<FileSize value={512} />
+<FileSize value={1_100_000} />
+<FileSize value={85_800_000} />
+<FileSize value={4_100_000_000} />
+<FileSize value={null} />
+```
+
+### Which megabyte
+
+```tsx
+<FileSize value={1_100_000} />                    {/* 1 MB */}
+<FileSize value={1_100_000} base="decimal" />    {/* 1.1 MB */}
+<FileSize value={1_100_000} base="iec" />        {/* 1 MiB */}
+```
+
+### Initials
+
+```tsx
+<Initials value="Jane McDonald" />
+<Initials value="Mei Chen" />
+<Initials value="Jane McDonald" maxCharacters={1} />
+<Initials value="Ana Sofia Reyes" strategy="first-words" />
+<Initials value="Ana Sofia Reyes" maxCharacters={3} />
+<Initials value="—" fallback="?" />
+<Initials value={null} />
+```
+
+### Inline list
+
+```tsx
+<InlineList items={["Alice", "Bob", "Carol"]} />
+<InlineList items={["red", "green", "blue"]} join="or" />
+<InlineList items={items} max={2} />
+```
+
+### The same list, three locales
+
+```tsx
+<InlineList items={names} locale="en-GB" />
+<InlineList items={names} locale="es-ES" />
+<InlineList items={names} locale="ja-JP" />
+```
+
+### Money
+
+```tsx
+<Money amount={1299.5} currency="EUR" />
+<Money amount={1299.5} currency="USD" />
+<Money amount={-42} currency="GBP" />
+<Money amount={0} currency="JPY" />
+<Money amount={null} currency="EUR" />
+```
+
+### Minor units
+
+```tsx
+<Money amount={129950} currency="EUR" unit="minor" />
+<Money amount={1299} currency="JPY" unit="minor" minorUnitScale={1} />
+<Money amount={129950} currency="KWD" unit="minor" minorUnitScale={1000} />
+```
+
+### How the amount is written
+
+```tsx
+<Money amount={1299.5} currency="EUR" formatMode="with-symbol" />
+<Money amount={1299.5} currency="EUR" formatMode="with-code" />
+<Money amount={1299.5} currency="EUR" formatMode="decimal" />
+```
+
+### Two currencies
+
+```tsx
+<Money
+  amount={1299.5}
+  currency="EUR"
+  secondary={{ amount: 1416.2, currency: "USD" }}
+/>
+```
+
+### Decided once, not per amount
+
+```tsx
+<UIProvider
+  config={{
+    formatting: { locale: "de-DE" },
+    money: {
+      defaultCurrency: "EUR",
+      displayCurrency: "USD",
+      dualPricingEnabled: true,
+      displayMode: "dynamic",
+      layout: "stacked",
+    },
+  }}
+>
+  <Money amount={1299.5} secondary={{ amount: 1416.2 }} />
+</UIProvider>
+```
+
+### Name
+
+```tsx
+<Name value="Jane McDonald" />
+<Name value="  jane   mcdonald " />
+<Name value="JANE MCDONALD" force />
+<Name value={null} />
+```
+
+### Number and percent
+
+```tsx
+<Number value={1234567.891} />
+<Number value={-42} />
+<Percent value={0.214} />
+<Percent value={1} />
+<Percent value={21.4} scaled />
+<Number value={null} />
+```
+
+### Phone
+
+```tsx
+<Phone value="+31 6 1234 5678" />
+<Phone value="+1 (555) 010-4417" />
+<Phone value={null} />
+```
+
+### Quantity
+
+```tsx
+<Quantity value={1} unit={{ one: "item", other: "items" }} />
+<Quantity value={0} unit={ITEM} zeroLabel="no items" />
+```
+
+### Measure
+
+```tsx
+<Measure value={2.5} unit="kilogram" />
+<Measure value={2.5} unit="kilogram" unitDisplay="long" />
+```
+
+### Range
+
+```tsx
+<Range from={10} to={50} />
+<Range from={10} to={50} currency="GBP" />
+<Range from={2} to={5} unit="day" />
+```
+
+### Ratio
+
+```tsx
+<Ratio value={3} total={10} />
+<Ratio value={3} total={10} format="fraction" />
+<Ratio value={3} />
+```
+
+### Rating
+
+```tsx
+<Rating value={4.5} />
+<Rating value={4} hideMax />
+```
+
+### RelativeTime
+
+```tsx
+<RelativeTime value={HOURS_AGO} now={NOW} />
+<RelativeTime value={DAYS_AGO} now={NOW} />
+<RelativeTime value={MONTHS_AGO} now={NOW} />
+<RelativeTime value={null} />
+```
+
+### Suffix and precision
+
+```tsx
+<RelativeTime value={date} now={now} addSuffix={false} />
+<RelativeTime value={date} now={now} includeSeconds />
+```
+
+### In another language
+
+```tsx
+import { de } from "date-fns/locale"
+
+<UIProvider config={{ dates: { locale: de } }}>…</UIProvider>
+
+{/* or hand the wording over completely */}
+<UIProvider
+  config={{ dates: { formatRelativeTime: (date, now) => t.relative(date, now) } }}
+/>
+```
+
+### URL
+
+```tsx
+<Url value="https://northwind.example/invoices/4417" />
+<Url value="https://northwind.example/invoices/4417" external />
+<Url value="https://northwind.example" display="Northwind" />
+<Url value={null} />
+```
+
+### Value
+
+```tsx
+<Value>Northwind Traders</Value>
+<SecondaryValue>Supporting detail</SecondaryValue>
+<MutedValue>Quieter still</MutedValue>
+<MonoValue>req_8f21c440</MonoValue>
+<EmptyValue />
+```
+
+## ui-provider
+
+```tsx
+import { … } from "themelia-ui/ui-provider"
+```
+
+Preview route: UIRoot & UIScope — `/ui-root-scope`
+
+### A scope is a region
+
+```tsx
+<UIScope config={{ density: "compact" }}>
+  <Toolbar />
+</UIScope>
+```
+
+### Nesting merges
+
+```tsx
+<UIScope config={{ colorScheme: "dark" }}>
+  <UIScope config={{ density: "compact" }}>…</UIScope>
+</UIScope>
+```
+
+### render decides the element
+
+```tsx
+<UIScope render={<aside />} config={{ density: "compact" }}>…</UIScope>
+```
+
+### Popups stay inside the scope
+
+```tsx
+<UIScope config={{ density: "compact" }}>
+  <UIPortalHost>
+    <DropdownMenu>
+      <DropdownMenuTrigger render={<Button>Actions</Button>} />
+      <DropdownMenuContent>
+        <DropdownMenuItem>Duplicate</DropdownMenuItem>
+      </DropdownMenuContent>
+    </DropdownMenu>
+  </UIPortalHost>
+</UIScope>
+```