themelia-ui 3.1.0 → 3.2.0

package/dist/styles/TOKENS.md

@@ -2,9 +2,10 @@
 
 The theme is `src/styles/theme/*.css`: about eighty variables, declared once at `:root`. Every
 colour is `light-dark(light, dark)`, and the element's `color-scheme` (set by `.light`,
-`.dark`, `data-theme` or the operating system) picks the half. Nothing below `:root`
-declares a theme variable again, so a value set anywhere reaches every reader below it, and
-a dark region inside a light page needs no second set of values.
+`.dark`, `data-theme` or the operating system) picks the half. Component styles inherit
+theme defaults rather than redeclaring them. Explicit scope overrides and density presets
+replace the corresponding inherited values on their regions. A dark region inside a light
+page needs no second set of colour declarations.
 
 Components read the theme and compute the rest in the rule that uses it. The package's checks
 fail on a `var()` nothing defines, a literal colour, radius, spacing or hairline in a

package/dist/{table-DT_20ity.js → table-B7dtIFUx.js}

@@ -10,13 +10,13 @@ import { B as p, D as m, E as h, H as g, I as _, L as ee, O as te, S as ne, T as
 import { t as de } from "./badge-VlJVZjdm.js";
 import { t as fe } from "./batch-action-bar-DZVMVW83.js";
 import { p as pe } from "./feedback-D4qVsKlD.js";
-import { t as me } from "./skeleton-CubvHel9.js";
-import { d as b, v as x } from "./display-BGN834xV.js";
+import { t as me } from "./skeleton-BTKNKTdj.js";
+import { d as b, v as x } from "./display-a7AoX_u7.js";
 import { t as S } from "./scroll-edges-CWjEJktN.js";
-import { x as C } from "./choice-inputs-CCw-0gD6.js";
+import { x as C } from "./choice-inputs-NwRxvmZN.js";
 import { l as w } from "./text-inputs-BboE77nZ.js";
 import { t as T } from "./use-latest-CF0678ae.js";
-import { s as he } from "./navigation-BTX5Ti0Z.js";
+import { s as he } from "./navigation-Bgu7Vc0M.js";
 import { r as ge } from "./navigation-B4eUU9E8.js";
 import { c as _e, i as ve, l as E, n as D, s as O, t as ye } from "./table-Ds_eO9av.js";
 import { n as k, o as A, t as j } from "./toolbar-DBK-c4yy.js";

package/dist/{timeline-BRZbSdhf.js → timeline-BR_jNgvz.js}

@@ -2,7 +2,7 @@ import "#core.css";
 import { s as e } from "./typography-DmeR05Er.js";
 import { t } from "./cx--CBrhWH0.js";
 import { t as n } from "./strings-Co9_qArR.js";
-import { d as r } from "./display-BGN834xV.js";
+import { d as r } from "./display-a7AoX_u7.js";
 import { CheckIcon as i } from "lucide-react";
 import { Fragment as a, jsx as o, jsxs as s } from "react/jsx-runtime";
 import "#css/timeline.css";

package/dist/{timelines-DczZKW5p.js → timelines-DXG1BfIN.js}

@@ -5,7 +5,7 @@ import { t as n } from "./strings-Co9_qArR.js";
 import { B as r, T as i } from "./primitives-BskKlf35.js";
 import { t as a } from "./badge-VlJVZjdm.js";
 import { s as o } from "./feedback-D4qVsKlD.js";
-import { r as s, t as c } from "./timeline-BRZbSdhf.js";
+import { r as s, t as c } from "./timeline-BR_jNgvz.js";
 import { CheckIcon as l, CircleIcon as u, ClockIcon as d, XIcon as f } from "lucide-react";
 import { Fragment as p, jsx as m, jsxs as h } from "react/jsx-runtime";
 import "#css/timelines.css";

package/dist/{upload-C_6mlbfl.js → upload-CYuoJykZ.js}

@@ -6,7 +6,7 @@ import { t as r } from "./strings-Co9_qArR.js";
 import { C as i, S as a } from "./primitives-BskKlf35.js";
 import { t as o } from "./badge-VlJVZjdm.js";
 import { h as s } from "./feedback-D4qVsKlD.js";
-import { d as c } from "./display-BGN834xV.js";
+import { d as c } from "./display-a7AoX_u7.js";
 import { CheckIcon as l, CircleAlertIcon as u, ClockIcon as d, FileIcon as f, ImageIcon as p, ImagePlusIcon as m, Loader2Icon as h, PaperclipIcon as g, PencilIcon as _, RotateCwIcon as v, TrashIcon as y, UploadCloudIcon as b, UserIcon as x, XIcon as S } from "lucide-react";
 import { useCallback as C, useEffect as w, useId as T, useMemo as E, useRef as D, useState as O } from "react";
 import { Fragment as k, jsx as A, jsxs as j } from "react/jsx-runtime";

package/dist/{value-inputs-CnO6RZeT.js → value-inputs-ng8aVJJZ.js}

@@ -1,11 +1,11 @@
 import "#core.css";
 import { c as e, s as t } from "./typography-DmeR05Er.js";
 import { t as n } from "./cx--CBrhWH0.js";
-import { o as r } from "./structure-B9Y5NkP_.js";
-import { d as i } from "./display-BGN834xV.js";
-import { s as a } from "./choice-inputs-CCw-0gD6.js";
+import { o as r } from "./structure-CynEZ-OY.js";
+import { d as i } from "./display-a7AoX_u7.js";
+import { s as a } from "./choice-inputs-NwRxvmZN.js";
 import { d as o, l as s } from "./text-inputs-BboE77nZ.js";
-import { c, u as l } from "./date-pickers-C2HgjpFU.js";
+import { c, u as l } from "./date-pickers-BwCwKIVM.js";
 import { XIcon as u } from "lucide-react";
 import * as d from "react";
 import { forwardRef as f, useCallback as p, useId as m, useMemo as h, useRef as g, useState as _ } from "react";

package/docs/README.md

@@ -4,7 +4,7 @@ Documents are grouped by audience. The first three directories ship in the npm p
 
 | Directory | Audience | What belongs there |
 |---|---|---|
-| `learn/` | **Learn** | Installation, composition, framework wiring, provider and scoping, theming, forms, i18n, troubleshooting, verification, and migration policy. |
+| `learn/` | **Learn** | Installation, composition, structure and spacing, subject blocks, framework wiring, provider and scoping, theming, forms, i18n, troubleshooting, verification, and migration policy. |
 | `generated/` | **Components** | The exact public API — imports, props, types, recipes, and choose/avoid guidance. Written by generators, never edited by hand. |
 | `build/` | **Build** | Adaptable live-preview recipes, with surrounding app-owned responsibilities called out. |
 | `adr/` | Decisions | Why an expensive or irreversible choice was made, and what evidence would justify revisiting it. Repository only. |
@@ -21,6 +21,8 @@ docs/generated/profiles.md              which modules each profile ships
 docs/generated/component-index.json     the machine-readable catalogue the component finder and the skill read
 docs/generated/components/              one complete API reference per module
 docs/generated/recipes.json             live-preview recipes, keyed by task
+docs/generated/workflows/index.json     complete workflow source/helper inventory and package version
+docs/generated/consumer-contract.json   generated export and private-style facts for read-only diagnosis
 ```
 
 ## Where to start
@@ -30,6 +32,14 @@ Start with [Installation](./learn/installation.md), then read
 [component API](./generated/components/INDEX.md), use [Framework wiring](./learn/framework-wiring.md)
 to connect application policy, and finish with the [consumer verification](./learn/verification.md)
 matrix. [Troubleshooting](./learn/troubleshooting.md) covers the common integration failures.
+Use [complete workflows](./learn/reference-workflows.md) where several modules meet.
+
+For layout decisions, use [Structure and spacing](./learn/structure-and-spacing.md): page
+scroll, gutters, reading widths, responsive columns, surface insets and the two gaps.
+[Choosing blocks](./learn/blocks.md) maps ready subject presentations to their data,
+permission and mutation seams. Use [Theming](./learn/theming.md) for global geometry and
+type, and [Provider and scoping](./learn/provider-and-scoping.md) for regional overrides
+and portals.
 
 To find a component by task, run the offline finder; `--explain` adds the matched
 components, selection reasons and API anchors:

package/docs/build/browser-composition-fixture.ts

@@ -0,0 +1,28 @@
+/** Caller supplies an already open fixture. This observer performs no navigation or actions. */
+export interface CompositionPage {
+  evaluate<Result, Arg>(callback: (arg: Arg) => Result, arg: Arg): Promise<Result>
+}
+export async function observeComposition(page: CompositionPage, selector: string) {
+  return page.evaluate(rootSelector => {
+    const root = document.querySelector<HTMLElement>(rootSelector)
+    if (!root) return { complete: false, reason: "Caller fixture root is missing", findings: [] }
+    const visible = (element: Element) => {
+      const box = element.getBoundingClientRect(), style = getComputedStyle(element)
+      return box.width > 0 && box.height > 0 && style.visibility !== "hidden" && style.display !== "none"
+    }
+    const findings: { ruleId: string; evidence: string; severity: "warning" }[] = []
+    if (root.scrollWidth > root.clientWidth + 1) findings.push({ ruleId: "horizontal-overflow", severity: "warning", evidence: `scrollWidth ${root.scrollWidth}; clientWidth ${root.clientWidth}` })
+    const headings = [...root.querySelectorAll("h1,h2,h3,h4,h5,h6,[role=heading]")].filter(visible)
+    for (const heading of headings) {
+      const text = heading.textContent?.trim()
+      const sameScope = headings.filter(other => other !== heading && other.parentElement === heading.parentElement && other.textContent?.trim() === text)
+      if (text && sameScope.length) findings.push({ ruleId: "duplicate-heading", severity: "warning", evidence: `${text}; same parent, ${sameScope.length + 1} occurrences` })
+    }
+    for (const control of root.querySelectorAll("button,input,select,textarea,a[href]")) {
+      if (!visible(control) || control.closest("[hidden],[inert],[aria-hidden=true]")) continue
+      const box = control.getBoundingClientRect()
+      if (box.right < 0 || box.left > innerWidth) findings.push({ ruleId: "control-outside-viewport", severity: "warning", evidence: `${control.getAttribute("aria-label") ?? control.textContent?.trim() ?? control.tagName}; left ${box.left}; right ${box.right}` })
+    }
+    return { complete: true, reason: "Observed caller fixture geometry and visible DOM only", findings }
+  }, selector)
+}

package/docs/build/recipes.md

@@ -2,7 +2,7 @@
 
 # Recipes
 
-400 adaptable live-preview snippets, taken from the pages that render them —
+409 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 for the module.
@@ -3729,6 +3729,57 @@ export default function FieldGroupExample() {
 }
 ```
 
+### Multi-section form reference
+
+```tsx
+import { useRef, useState } from "react"
+import { Card } from "themelia-ui/base/cards"
+import { ContentBlock } from "themelia-ui/base/display"
+import { FieldGroup, FormField, FormSection, FormActionsBar, SubmitStateButton } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { useFormFieldBinding, useStateFormControl, type FormControl } from "themelia-ui/forms"
+
+type Draft = { firstName: string; lastName: string; company: string }
+function BoundField({ control, name, label, error }: { control: FormControl<Draft>; name: keyof Draft; label: string; error?: string }) {
+	const field = useFormFieldBinding<string, Draft>({ control, name })
+	return <FormField label={label} error={error} hint={name === "company" ? "The name shown on invoices." : undefined}><Input required value={field.value ?? ""} onChange={event => field.onValueChange(event.target.value)} onBlur={field.onBlur} /></FormField>
+}
+
+export default function MultiSectionReference() {
+	const control = useStateFormControl<Draft>({ firstName: "Alex", lastName: "Example", company: "Example team" })
+	const [pending, setPending] = useState(false)
+	const [error, setError] = useState<string>()
+	const [rootError, setRootError] = useState<string>()
+	const [saved, setSaved] = useState(0)
+	const running = useRef(false)
+	return <Stack>
+		<Card title="Account details" description="One outer surface, editable sections with retained region insets.">
+			<form onSubmit={async event => {
+				event.preventDefault(); if (running.current) return
+				running.current = true; setPending(true); setError(undefined); setRootError(undefined)
+				try {
+					await new Promise(resolve => setTimeout(resolve, 250))
+					if (control.values.company === "offline") throw new Error("Request failed. Your values remain here.")
+					if (control.values.company.length < 3) { setError("Company must have at least three characters."); return }
+					setSaved(count => count + 1)
+				} catch (failure) { setRootError((failure as Error).message) }
+				finally { running.current = false; setPending(false) }
+			}}>
+				<Stack gap="none">
+					{rootError && <Text role="alert" type="error">{rootError}</Text>}
+					<FormSection surface="flat" title="Contact"><FieldGroup legend="Legal name" disabled={pending}><BoundField control={control} name="firstName" label="First name" /><BoundField control={control} name="lastName" label="Last name" /></FieldGroup></FormSection>
+					<FormSection surface="flat" title="Billing"><fieldset disabled={pending} style={{ border: 0, padding: 0, margin: 0 }}><BoundField control={control} name="company" label="Company" error={error} /></fieldset></FormSection>
+					<FormActionsBar leading={<Text role="status">Successful submissions {saved}</Text>}><SubmitStateButton type="submit" state={pending ? "submitting" : "idle"} strings={{ idle: "Save account" }} /></FormActionsBar>
+				</Stack>
+			</form>
+		</Card>
+		<Card title="Preferences" description="A sibling subject owns its own surface."><ContentBlock surface="plain" title="Delivery instructions"><Text>Use ContentBlock for supporting prose; FieldGroup supplies fieldset semantics for related controls.</Text></ContentBlock></Card>
+	</Stack>
+}
+```
+
 ### FormSection
 
 ```tsx
@@ -6274,6 +6325,7 @@ export default function GridExample() {
 			<GridCell><Box>three</Box></GridCell>
 			<GridCell span={{ base: 1, md: 2 }}><Box>span 2 from md</Box></GridCell>
 			<GridCell><Box>four</Box></GridCell>
+			<GridCell span={{ base: 1, md: "full", xl: 2 }}><Box>responsive full row</Box></GridCell>
 		</Grid>
 	)
 }
@@ -8718,6 +8770,30 @@ import { … } from "themelia-ui/blocks/analytics"
 
 Preview route: Analytics — `/analytics`
 
+### Communications overview reference
+
+```tsx
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
+
+export default function CommunicationsReference() {
+	const [retried, setRetried] = useState(false)
+	return <Stack>
+		<MetricGrid metrics={[{ id: "delivered", label: "Messages delivered during the selected reporting period", value: 128, valueType: "number" }, { id: "retry", label: "Messages awaiting retry", value: retried ? 0 : 3, valueType: "number" }]} variant="card" />
+		<Card title="Latest communication" headerAction={<Button disabled={retried} onClick={() => setRetried(true)}>Retry delivery</Button>}>
+			<MetadataList items={[{ id: "subject", label: "Subject", value: "Workspace invitation" }, { id: "status", label: "Delivery state", value: retried ? "Delivered" : "Retry available" }, { id: "recipient", label: "Recipient", value: "member@example.test" }, { id: "time", label: "Last attempt", value: { kind: "datetime", value: "2026-09-01T09:30:00Z" } }, { id: "opened", label: "Opened", value: "Unknown; tracking unavailable" }]} />
+			<Text>The application owns delivery policy and permission checks. Metrics describe quantities; this subject and its delivery facts stay in a record surface.</Text>
+		</Card>
+		<Text role="status">{retried ? "Mock retry completed" : "Mock delivery is waiting"}</Text>
+	</Stack>
+}
+```
+
 ### Metric bar
 
 ```tsx
@@ -10007,6 +10083,61 @@ import { … } from "themelia-ui/features/combobox"
 
 Preview route: Combobox — `/combobox`
 
+### Scoped resource selection
+
+```tsx
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { FormField } from "themelia-ui/base/forms"
+import { Overlay, OverlayTrigger, OverlayContent, OverlayHeader, OverlayTitle, OverlayDescription, OverlayBody } from "themelia-ui/base/overlay"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { ResourceCombobox } from "themelia-ui/features/combobox"
+
+type Resource = { id: string; label: string }
+type Mode = "results" | "pending" | "empty" | "error"
+
+export default function ScopedResourceReference() {
+	const [scope, setScope] = useState("A")
+	const [mode, setMode] = useState<Mode>("results")
+	const [query, setQuery] = useState("")
+	const [value, setValue] = useState<Resource | null>({ id: "A-1", label: "A project" })
+	const [selections, setSelections] = useState(0)
+	const [submissions, setSubmissions] = useState(0)
+	const [completions, setCompletions] = useState(0)
+	return <Overlay>
+		<OverlayTrigger render={<Button />}>Choose scoped resource</OverlayTrigger>
+		<OverlayContent>
+			<OverlayHeader><OverlayTitle>Assign resource</OverlayTitle><OverlayDescription>Lookup validity belongs to a workspace. The application decides whether a selected resource remains valid.</OverlayDescription></OverlayHeader>
+			<OverlayBody>
+				<form onSubmit={event => { event.preventDefault(); setSubmissions(count => count + 1) }}>
+					<Stack>
+						<Stack direction="horizontal" gap="sm" wrap>
+							{["A", "B"].map(key => <Button key={key} tone="neutral" appearance="outline" onClick={() => { setScope(key); setValue(null) }}>Workspace {key}</Button>)}
+						</Stack>
+						<Stack direction="horizontal" gap="sm" wrap>
+							{(["results", "pending", "empty", "error"] as const).map(key => <Button key={key} tone="neutral" appearance="ghost" onClick={() => setMode(key)}>{key}</Button>)}
+						</Stack>
+						<FormField label="Resource" hint={`Searching workspace ${scope}`}>
+							<ResourceCombobox<Resource> scopeKey={`${scope}:${mode}`} value={value} onValueChange={next => { setValue(next); setSelections(count => count + 1) }} searchValue={query} onSearchValueChange={setQuery} debounceMs={100} getKey={item => item.id} getLabel={item => item.label}
+								fetcher={async ({ query: search, signal }) => {
+									// The mock deliberately ignores abort; the picker must suppress its late answer.
+									void signal
+									await new Promise(resolve => setTimeout(resolve, mode === "pending" ? 2400 : scope === "A" ? 600 : 80))
+									if (mode === "error") throw new Error("Lookup unavailable")
+									return mode === "empty" || (search && !"project".includes(search.toLowerCase())) ? [] : [{ id: `${scope}-1`, label: `${scope} project` }]
+								}} onAfterFetch={() => setCompletions(count => count + 1)} />
+						</FormField>
+						<Button type="submit">Assign</Button>
+						<Text role="status">Selections {selections}; submissions {submissions}; completions {completions}</Text>
+					</Stack>
+				</form>
+			</OverlayBody>
+		</OverlayContent>
+	</Overlay>
+}
+```
+
 ### A picker that fetches
 
 ```tsx
@@ -10599,6 +10730,62 @@ import { … } from "themelia-ui/features/data-view"
 
 Preview route: Data view & data table — `/data-view`
 
+### Server resource index reference
+
+```tsx
+import { useEffect, useRef, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Heading, Text } from "themelia-ui/base/typography"
+import { DataView, type DataViewProps } from "themelia-ui/features/data-view"
+import { FilterType, type ActiveFilter, type FilterConfig } from "themelia-ui/features/filters"
+
+type RecordRow = { id: string; name: string; status: string; searchTerms: string }
+const RECORDS: RecordRow[] = Array.from({ length: 6 }, (_, index) => ({ id: `r${index + 1}`, name: `Resource ${index + 1}`, status: index % 2 ? "Closed" : "Open", searchTerms: "hidden reference term" }))
+const COLUMNS: DataViewProps<RecordRow>["columns"] = [{ accessorKey: "name", header: "Resource" }, { accessorKey: "status", header: "Status" }]
+const FILTERS: FilterConfig[] = [{ key: "search", label: "Search hidden metadata and resource names", type: FilterType.SEARCH }, { key: "status", label: "Publication and review status with a long translated label", type: FilterType.SELECT, options: [{ value: "Open", label: "Open" }, { value: "Closed", label: "Closed" }] }]
+
+export default function ResourceIndexReference() {
+	const [filters, setFilters] = useState<ActiveFilter[]>([])
+	const [page, setPage] = useState(0)
+	const [rows, setRows] = useState<RecordRow[]>([])
+	const [hasNext, setHasNext] = useState(false)
+	const [pending, setPending] = useState(true)
+	const [error, setError] = useState<string>()
+	const [refresh, setRefresh] = useState(0)
+	const [selection, setSelection] = useState<Record<string, true>>({})
+	const [answeredQuery, setAnsweredQuery] = useState("")
+	const [commands, setCommands] = useState("")
+	const failNext = useRef(false)
+	useEffect(() => {
+		let active = true
+		async function load() {
+			setPending(true); setError(undefined)
+			await new Promise(resolve => setTimeout(resolve, 250))
+			if (!active) return
+			if (failNext.current) { failNext.current = false; setError("Refresh failed. Previous rows remain available."); setPending(false); return }
+			const search = filters.find(filter => filter.key === "search")?.value[0]?.toLowerCase() ?? ""
+			const status = filters.find(filter => filter.key === "status")?.value[0]
+			const matches = RECORDS.filter(row => `${row.name} ${row.searchTerms}`.toLowerCase().includes(search) && (!status || row.status === status))
+			setAnsweredQuery(search); setRows(matches.slice(page * 2, page * 2 + 2)); setHasNext(matches.length > page * 2 + 2); setPending(false)
+		}
+		void load()
+		return () => { active = false }
+	}, [filters, page, refresh])
+	return <div style={{ width: "100%", minWidth: 0, maxWidth: "48rem" }}>
+		<Stack>
+			<Heading level={3}>Resource index</Heading>
+			<Text type="secondary">Server matching includes fields absent from the visible columns. Totals are unknown; selection applies to the current page.</Text>
+			{error && <Text role="alert" type="error">{error}</Text>}
+			<DataView data={rows} columns={COLUMNS} filtering={{ filters: FILTERS, activeFilters: filters, onFilterChange: next => { setFilters(next); setPage(0); setSelection({}) }, filterRows: ({ data }) => [...data], isFiltering: pending }}
+				table={{ enableColumnVisibility: true, enableRowSelection: true, getRowId: row => row.id, rowSelection: selection, onRowSelectionChange: setSelection, bulkActions: ({ selectedRows }) => <Button onClick={() => setCommands(`Selected-page command: ${selectedRows.map(row => row.id).join(", ")}`)}>Archive selected page rows</Button> }}
+				slots={{ topbarEnd: <Stack direction="horizontal" gap="sm" wrap><Button tone="neutral" appearance="outline" disabled={pending} onClick={() => setRefresh(count => count + 1)}>Refresh</Button><Button tone="neutral" appearance="outline" onClick={() => { failNext.current = true; setRefresh(count => count + 1) }}>Fail next refresh</Button><Button tone="neutral" appearance="outline" onClick={() => setCommands(`Export current page: ${rows.map(row => row.id).join(", ")}`)}>Export page</Button></Stack>, footer: <Stack direction="horizontal" wrap align="center"><Text>Total unknown; page {page + 1}</Text><Button disabled={pending || page === 0} onClick={() => { setPage(value => value - 1); setSelection({}) }}>Previous page</Button><Button disabled={pending || !hasNext} onClick={() => { setPage(value => value + 1); setSelection({}) }}>Next page</Button></Stack> }} />
+			<Text role="status">{pending ? "Loading page" : `${rows.length} rows supplied by server; matched ${answeredQuery || "all"}`}{commands && `; ${commands}`}</Text>
+		</Stack>
+	</div>
+}
+```
+
 ### An index
 
 ```tsx
@@ -11385,6 +11572,74 @@ import { … } from "themelia-ui/features/media-library"
 
 Preview route: Media library — `/media-library`
 
+### Media picking reference
+
+```tsx
+import { useEffect, useMemo, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { MediaLibraryDialog, type MediaLibraryItem, type MediaLibraryFetcher } from "themelia-ui/features/media-library"
+
+import { SAMPLE_MEDIA } from "./reference-data"
+
+export default function MediaPickingReference() {
+	const [open, setOpen] = useState(false)
+	const [scope, setScope] = useState("site")
+	const [fail, setFail] = useState(false)
+	const [selected, setSelected] = useState<string[]>(["unavailable-id"])
+	const [pickerDraft, setPickerDraft] = useState(selected)
+	const [resolved, setResolved] = useState<{ scope: string; ids: string[]; items: MediaLibraryItem[] }>()
+	const [page, setPage] = useState(0)
+	const [query, setQuery] = useState("")
+	const [pending, setPending] = useState(true)
+	const [hasNext, setHasNext] = useState(false)
+	// A saved id is resolved separately from the current browser page, with scope access applied.
+	useEffect(() => {
+		const controller = new AbortController()
+		const timer = setTimeout(() => {
+			if (!controller.signal.aborted) setResolved({ scope, ids: selected, items: SAMPLE_MEDIA.filter(item => selected.includes(item.id) && item.collection === scope) })
+		}, 150)
+		return () => { controller.abort(); clearTimeout(timer) }
+	}, [selected, scope])
+	const chosen = resolved?.scope === scope && resolved.ids === selected ? resolved.items : []
+	const unavailable = resolved?.scope === scope && resolved.ids === selected && chosen.length < selected.length
+	const changeOpen = (next: boolean) => {
+		if (next) setPickerDraft(selected)
+		setOpen(next)
+	}
+	const fetcher = useMemo<MediaLibraryFetcher>(() => async ({ query: search, signal }) => {
+		setPending(true)
+		try {
+			await new Promise(resolve => setTimeout(resolve, 200))
+			if (signal?.aborted) throw new DOMException("Aborted", "AbortError")
+			if (fail) throw new Error("Media lookup unavailable")
+			const matches = SAMPLE_MEDIA.filter(item => item.collection === scope && item.name.toLowerCase().includes(search.toLowerCase()))
+			const window = matches.slice(page, page + 2)
+			setHasNext(window.length > 1)
+			return { items: window.slice(0, 1) }
+		} finally { if (!signal?.aborted) setPending(false) }
+	}, [scope, fail, page])
+	return <Stack>
+		{unavailable && <Text role="alert">The saved asset is unavailable. Choose a replacement; the draft id is retained until then.</Text>}
+		<Stack direction="horizontal" gap="sm" wrap>
+			<MediaLibraryDialog open={open} trigger={<Button>Choose reference media</Button>} onOpenChange={changeOpen} fetcher={fetcher} value={pickerDraft} onValueChange={setPickerDraft} query={query} onQueryChange={next => { setQuery(next); setPage(0); setPending(true) }} selectionMode="single" allowUpload={false}
+				strings={{ showingCount: shown => `${shown} loaded on this page; total unknown` }}
+				slots={{ footer: <Stack direction="horizontal" gap="sm" wrap align="center">
+					<Text>Media page {page + 1}; total unknown</Text>
+					<Button disabled={pending || page === 0} onClick={() => { setPage(value => value - 1); setPending(true) }}>Previous media page</Button>
+					<Button disabled={pending || !hasNext} onClick={() => { setPage(value => value + 1); setPending(true) }}>Next media page</Button>
+				</Stack> }}
+				onConfirm={(items, ids) => { setSelected(ids); setResolved({ scope, ids, items }); setOpen(false) }} />
+			<Button tone="neutral" appearance="outline" onClick={() => setSelected(["image-2"])}>Load saved media draft</Button>
+			<Button tone="neutral" appearance="outline" onClick={() => { setScope(value => value === "site" ? "other" : "site"); setPage(0); setPending(true) }}>Switch media scope</Button>
+			<Button tone="neutral" appearance="outline" onClick={() => { setFail(value => !value); setPending(true) }}>Toggle media failure</Button>
+		</Stack>
+		<Text role="status">{chosen.length ? `Hydrated selection: ${chosen.map(item => `${item.name} — ${item.alt}`).join(", ")}` : `Saved draft ids: ${selected.join(", ")}`}</Text>
+	</Stack>
+}
+```
+
 ### Asset manager
 
 ```tsx
@@ -11933,6 +12188,50 @@ import { … } from "themelia-ui/features/overlays"
 
 Preview route: Action overlays — `/action-overlays`
 
+### Nested action flow
+
+```tsx
+import { useRef, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { ActionDialog } from "themelia-ui/features/overlays"
+
+export default function NestedActionReference() {
+	const [open, setOpen] = useState(false)
+	const [child, setChild] = useState(false)
+	const [name, setName] = useState("Draft record")
+	const [error, setError] = useState<string>()
+	const [saved, setSaved] = useState(0)
+	const session = useRef(0)
+	const changeOpen = (next: boolean) => { session.current++; setOpen(next); setChild(false) }
+	return <Stack>
+		<ActionDialog open={open} trigger={<Button>Inspect draft</Button>} onOpenChange={changeOpen} title="Record inspector" description="The draft remains here after cancellation, validation failure or transport failure." showConfirm={false}>
+			<Stack>
+				<FormField label="Record name" error={error} hint="Use at least three characters. Use offline to simulate a rejected request."><Input value={name} onChange={event => setName(event.target.value)} /></FormField>
+				<ActionDialog open={child} trigger={<Button>Review save</Button>} onOpenChange={setChild} title="Save this draft?" description="A resolved response can contain validation errors. Closure follows business success." closeOnAsyncComplete={false}
+					alertMessage={error} onError={() => setError("Could not save; your draft is still here.")}
+					onAsyncConfirm={async () => {
+						const attempt = session.current
+						await new Promise(resolve => setTimeout(resolve, 300))
+						if (attempt !== session.current) return
+						if (name === "offline") throw new Error("Unavailable")
+						if (name.trim().length < 3) { setError("Enter at least three characters."); return }
+						setError(undefined); setSaved(count => count + 1); changeOpen(false)
+					}}>
+					<Text>{name}</Text>
+				</ActionDialog>
+				{/* A native form can instead use formId: its submit handler owns validation and closure. */}
+				<Text size="xs" type="secondary">Confirmation {child ? "open" : "closed"}</Text>
+			</Stack>
+		</ActionDialog>
+		<Text role="status">Successful saves {saved}</Text>
+	</Stack>
+}
+```
+
 ### ActionDialog
 
 ```tsx
@@ -12966,6 +13265,44 @@ import { … } from "themelia-ui/features/rich-text-editor"
 
 Preview route: Rich text editor — `/rich-text-editor`
 
+### Website content reference
+
+```tsx
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { RichText, Text } from "themelia-ui/base/typography"
+import { MediaLibraryDialog, type MediaLibraryItem } from "themelia-ui/features/media-library"
+import { RichTextEditor } from "themelia-ui/features/rich-text-editor"
+import { SAMPLE_MEDIA } from "../media-library/reference-data"
+
+export default function WebsiteContentReference() {
+	const [locale, setLocale] = useState("en")
+	const [drafts, setDrafts] = useState<Record<string, string>>({ en: "<p>Welcome to our workspace.</p>", ar: "<p>مرحباً بكم</p>" })
+	const [mediaOpen, setMediaOpen] = useState(false)
+	const [image, setImage] = useState<MediaLibraryItem>()
+	const [alt, setAlt] = useState("")
+	const [failed, setFailed] = useState(true)
+	const [pending, setPending] = useState(false)
+	const [message, setMessage] = useState("Drafts are local until saved")
+	return <Card title="Website content" description="Each locale owns a retained draft. Preview sanitizes HTML; the application also validates and sanitizes persisted content.">
+		<Stack>
+			<PillRadioGroup aria-label="Content locale" name="reference-content-locale" value={locale} onValueChange={value => value && setLocale(value)} options={[{ value: "en", label: "English" }, { value: "ar", label: "العربية" }]} />
+			<div dir={locale === "ar" ? "rtl" : "ltr"}><RichTextEditor value={drafts[locale] ?? ""} onValueChange={html => setDrafts(current => ({ ...current, [locale]: html }))} /></div>
+			<MediaLibraryDialog open={mediaOpen} trigger={<Button tone="neutral" appearance="outline">Choose hero media</Button>} onOpenChange={setMediaOpen} items={SAMPLE_MEDIA} selectionMode="single" confirmOnSelect allowUpload={false} onConfirm={items => { const item = items[0]; setImage(item); setAlt(item?.alt ?? ""); setMediaOpen(false) }} />
+			{image && <FormField label="Hero image alternative text" hint={image.name}><Input value={alt} onChange={event => setAlt(event.target.value)} /></FormField>}
+			<Stack direction="horizontal" wrap gap="sm"><Button disabled={pending} onClick={async () => { if (pending) return; setPending(true); await new Promise(resolve => setTimeout(resolve, 250)); setMessage(failed ? "Save failed. All locale drafts and image text remain here." : "Mock website save completed"); setPending(false) }}>Save website content</Button><Button tone="neutral" appearance="outline" onClick={() => setFailed(value => !value)}>Toggle save failure</Button></Stack>
+			<Text role="status">{message}</Text>
+			<RichText html={drafts[locale] ?? ""} />
+		</Stack>
+	</Card>
+}
+```
+
 ### The editor and what comes out
 
 ```tsx
@@ -13840,6 +14177,37 @@ import { … } from "themelia-ui/layout/app-shell"
 
 Preview route: App shell — `/app-shell`
 
+### Workspace navigation reference
+
+```tsx
+import { useState } from "react"
+import { Text } from "themelia-ui/base/typography"
+import { TopbarSidebarLayout } from "themelia-ui/layout/app-shell"
+import { AppSidebar, type LinkRenderer } from "themelia-ui/layout/sidebar"
+
+export default function WorkspaceNavigationReference() {
+	const [route, setRoute] = useState("/a/overview")
+	const [navigations, setNavigations] = useState(0)
+	const workspace = route.startsWith("/b/") ? "B" : "A"
+	const renderLink: LinkRenderer = ({ href, children, external, active, disabled, onClick, ...props }) => {
+		void active
+		if (disabled || !href) return <span {...props}>{children}</span>
+		return <a {...props} href={href} target={props.target ?? (external ? "_blank" : undefined)} rel={props.rel ?? (external ? "noopener noreferrer" : undefined)} onClick={event => {
+			onClick?.(event)
+			if (event.defaultPrevented || external || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+			event.preventDefault(); setRoute(href); setNavigations(count => count + 1)
+		}}>{children}</a>
+	}
+	return <div style={{ width: "100%", height: "28rem", minWidth: 0 }}>
+		<TopbarSidebarLayout contained contentRender={<div />} logo="Reference workspace" sidebarProviderProps={{ persist: false, keyboardShortcut: false }} sidebar={<AppSidebar logo={`Workspace ${workspace}`} renderLink={renderLink} currentUrl={route}
+			workspaceLinks={[{ label: "Workspace A home", url: "/a/overview", external: false }, { label: "Workspace B home", url: "/b/overview", external: false }, { label: "External workspace", url: "https://example.com" }]}
+			navigationGroups={{ "": [{ label: `${workspace} overview`, href: `/${workspace.toLowerCase()}/overview` }, { label: `${workspace} settings`, href: `/${workspace.toLowerCase()}/settings` }] }} />}>
+			<Text role="status">Workspace {workspace}; route {route}; navigations {navigations}</Text>
+		</TopbarSidebarLayout>
+	</div>
+}
+```
+
 ### The shell
 
 ```tsx
@@ -14538,6 +14906,35 @@ import { … } from "themelia-ui/layout/page"
 
 Preview route: Page & page header — `/page`
 
+### Record detail reference
+
+```tsx
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Card, CardContent, CardHeader } from "themelia-ui/base/cards"
+import { ContentBlock, MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from "themelia-ui/base/table"
+import { Page } from "themelia-ui/layout/page"
+
+export default function RecordDetailReference() {
+	const [activity, setActivity] = useState("No commands yet")
+	return <Page header={{ title: "Record R-104", description: "A record with independent subjects and related records.", actions: <Button onClick={() => setActivity("Route command: export R-104")}>Export record</Button> }}>
+		<Stack>
+			<Card title="Identity" titleLevel={2} headerAction={<Button tone="neutral" appearance="outline" onClick={() => setActivity("Identity command: edit R-104")}>Edit identity</Button>}>
+				<MetadataList items={[{ id: "owner", label: "Owner", value: "Example team" }, { id: "state", label: "State", value: "Active" }]} />
+				<ContentBlock title="Notes" surface="plain"><Text>A long description belongs to prose, while the name and status above are facts. Commands stay beside the subject they affect. Repeated records can each have their own headings without repeating the route heading.</Text></ContentBlock>
+			</Card>
+			<Card><CardHeader title="Related records" titleLevel={2} description="The header is composed from parts; omit Card title props when supplying it." /><CardContent>
+				<Table aria-label="Related records"><TableHeader><TableRow><TableHead>Record</TableHead><TableHead>Relationship</TableHead></TableRow></TableHeader><TableBody><TableRow><TableCell>R-105</TableCell><TableCell>Follow-up</TableCell></TableRow></TableBody></Table>
+			</CardContent></Card>
+			<Text role="status">{activity}</Text>
+		</Stack>
+	</Page>
+}
+```
+
 ### PageHeader
 
 ```tsx