themelia-ui 3.1.0 → 3.2.0

package/docs/generated/imports.md

@@ -7,7 +7,7 @@ siblings do not exist, because one specifier would pull an entire tier and every
 peer inside it. The root carries the provider and the display primitives, both peer-free.
 
 A component brings its own CSS in a bundled app. Pages with no bundler link `style.css`; see
-docs/learn/installation.md.
+[Installation](../learn/installation.md).
 
 ## general profile — 95 modules
 

package/docs/generated/recipes.json

@@ -125,6 +125,25 @@
       "import": "themelia-ui/base/action-menu",
       "code": "import { ArchiveIcon, SendIcon, PencilIcon, TrashIcon } from \"lucide-react\"\n\nimport {\n\tActionButtons, resolveContextActions, type ContextAction,\n} from \"themelia-ui/base/action-menu\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Text } from \"themelia-ui/base/typography\"\n\nimport { QUIET } from \"./data\"\n\ninterface Invoice { number: string; paid: boolean; locked: boolean }\n\n/* Declared once against the record type; predicates run per record and handlers receive it. */\nconst INVOICE_ACTIONS: ContextAction<Invoice>[] = [\n\t{ id: \"send\", label: \"Send reminder\", icon: SendIcon, visible: (invoice) => !invoice.paid, placement: \"inline\" },\n\t{ id: \"edit\", label: \"Edit\", icon: PencilIcon, disabled: (invoice) => invoice.locked, ...QUIET },\n\t{ id: \"archive\", label: \"Archive\", icon: ArchiveIcon, ...QUIET },\n\t{ id: \"delete\", label: \"Delete\", icon: TrashIcon, tone: \"destructive\", placement: \"menu\" },\n]\n\nconst INVOICES: Invoice[] = [\n\t{ number: \"INV-1042\", paid: false, locked: false },\n\t{ number: \"INV-1038\", paid: true, locked: true },\n]\n\nexport default function ContextActions() {\n\treturn (\n\t\t<Stack style={{ width: \"100%\" }}>\n\t\t\t{INVOICES.map((invoice) => (\n\t\t\t\t<Stack key={invoice.number} gap=\"sm\">\n\t\t\t\t\t<Text size=\"xs\" type=\"secondary\">\n\t\t\t\t\t\t{invoice.number} · {invoice.paid ? \"paid, locked\" : \"unpaid\"}\n\t\t\t\t\t</Text>\n\t\t\t\t\t<ActionButtons actions={resolveContextActions(INVOICE_ACTIONS, invoice)} max={2} />\n\t\t\t\t</Stack>\n\t\t\t))}\n\t\t</Stack>\n\t)\n}"
     },
+    {
+      "id": "nested-action-reference",
+      "title": "Nested action flow",
+      "route": "/action-overlays",
+      "page": "Action overlays",
+      "module": "features/overlays",
+      "modules": [
+        "features/overlays"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/forms",
+        "base/structure",
+        "base/text-inputs",
+        "base/typography"
+      ],
+      "import": "themelia-ui/features/overlays",
+      "code": "import { useRef, useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { FormField } from \"themelia-ui/base/forms\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Input } from \"themelia-ui/base/text-inputs\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { ActionDialog } from \"themelia-ui/features/overlays\"\n\nexport default function NestedActionReference() {\n\tconst [open, setOpen] = useState(false)\n\tconst [child, setChild] = useState(false)\n\tconst [name, setName] = useState(\"Draft record\")\n\tconst [error, setError] = useState<string>()\n\tconst [saved, setSaved] = useState(0)\n\tconst session = useRef(0)\n\tconst changeOpen = (next: boolean) => { session.current++; setOpen(next); setChild(false) }\n\treturn <Stack>\n\t\t<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}>\n\t\t\t<Stack>\n\t\t\t\t<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>\n\t\t\t\t<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}\n\t\t\t\t\talertMessage={error} onError={() => setError(\"Could not save; your draft is still here.\")}\n\t\t\t\t\tonAsyncConfirm={async () => {\n\t\t\t\t\t\tconst attempt = session.current\n\t\t\t\t\t\tawait new Promise(resolve => setTimeout(resolve, 300))\n\t\t\t\t\t\tif (attempt !== session.current) return\n\t\t\t\t\t\tif (name === \"offline\") throw new Error(\"Unavailable\")\n\t\t\t\t\t\tif (name.trim().length < 3) { setError(\"Enter at least three characters.\"); return }\n\t\t\t\t\t\tsetError(undefined); setSaved(count => count + 1); changeOpen(false)\n\t\t\t\t\t}}>\n\t\t\t\t\t<Text>{name}</Text>\n\t\t\t\t</ActionDialog>\n\t\t\t\t{/* A native form can instead use formId: its submit handler owns validation and closure. */}\n\t\t\t\t<Text size=\"xs\" type=\"secondary\">Confirmation {child ? \"open\" : \"closed\"}</Text>\n\t\t\t</Stack>\n\t\t</ActionDialog>\n\t\t<Text role=\"status\">Successful saves {saved}</Text>\n\t</Stack>\n}"
+    },
     {
       "id": "action-dialog",
       "title": "ActionDialog",
@@ -385,6 +404,25 @@
       "import": "themelia-ui/base/feedback",
       "code": "import { SearchXIcon } from \"lucide-react\"\n\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { Alert, AlertAction, AlertDescription, AlertTitle } from \"themelia-ui/base/feedback\"\n\nexport default function AlertLayout() {\n\treturn (\n\t\t<>\n\t\t\t<Alert tone=\"destructive\" icon={<SearchXIcon />}>\n\t\t\t\t<AlertTitle>With a leading icon</AlertTitle>\n\t\t\t\t<AlertDescription>The grid becomes two columns automatically.</AlertDescription>\n\t\t\t</Alert>\n\t\t\t<Alert tone=\"info\">\n\t\t\t\t<AlertTitle>With an action</AlertTitle>\n\t\t\t\t<AlertDescription>Inline space is reserved on the trailing edge.</AlertDescription>\n\t\t\t\t<AlertAction>\n\t\t\t\t\t<Button tone=\"neutral\" appearance=\"ghost\">\n\t\t\t\t\t\tUndo\n\t\t\t\t\t</Button>\n\t\t\t\t</AlertAction>\n\t\t\t</Alert>\n\t\t\t<Alert>\n\t\t\t\t<AlertTitle>Neither — single column</AlertTitle>\n\t\t\t\t<AlertDescription>No icon, no action, no reserved space.</AlertDescription>\n\t\t\t</Alert>\n\t\t</>\n\t)\n}"
     },
+    {
+      "id": "communications-reference",
+      "title": "Communications overview reference",
+      "route": "/analytics",
+      "page": "Analytics",
+      "module": "blocks/analytics",
+      "modules": [
+        "blocks/analytics"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/cards",
+        "base/display",
+        "base/structure",
+        "base/typography"
+      ],
+      "import": "themelia-ui/blocks/analytics",
+      "code": "import { useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { Card } from \"themelia-ui/base/cards\"\nimport { MetadataList } from \"themelia-ui/base/display\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { MetricGrid } from \"themelia-ui/blocks/analytics\"\n\nexport default function CommunicationsReference() {\n\tconst [retried, setRetried] = useState(false)\n\treturn <Stack>\n\t\t<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\" />\n\t\t<Card title=\"Latest communication\" headerAction={<Button disabled={retried} onClick={() => setRetried(true)}>Retry delivery</Button>}>\n\t\t\t<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\" }]} />\n\t\t\t<Text>The application owns delivery policy and permission checks. Metrics describe quantities; this subject and its delivery facts stay in a record surface.</Text>\n\t\t</Card>\n\t\t<Text role=\"status\">{retried ? \"Mock retry completed\" : \"Mock delivery is waiting\"}</Text>\n\t</Stack>\n}"
+    },
     {
       "id": "analytics-bar",
       "title": "Metric bar",
@@ -525,6 +563,22 @@
       "import": "themelia-ui/base/badge",
       "code": "import { ArrowUpIcon, CreditCardIcon } from \"lucide-react\"\n\nimport { Badge } from \"themelia-ui/base/badge\"\nimport { Card } from \"themelia-ui/base/cards\"\nimport { Sparkline } from \"themelia-ui/base/chart\"\nimport { IconBadge } from \"themelia-ui/base/display\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { DisplayLabel, Text } from \"themelia-ui/base/typography\"\nimport { Money } from \"themelia-ui/primitives\"\n\nexport default function AnalyticsBlueprint() {\n\treturn (\n\t\t<Card style={{ maxWidth: \"20rem\" }}>\n\t\t\t<Stack gap=\"sm\">\n\t\t\t\t<Stack direction=\"horizontal\" align=\"center\" gap=\"sm\">\n\t\t\t\t\t<IconBadge icon={CreditCardIcon} tone=\"primary\" />\n\t\t\t\t\t<DisplayLabel>Revenue</DisplayLabel>\n\t\t\t\t</Stack>\n\t\t\t\t<Stack direction=\"horizontal\" align=\"center\" justify=\"between\" gap=\"sm\">\n\t\t\t\t\t<Money amount={48200} currency=\"EUR\" size=\"xl\" weight=\"semibold\" />\n\t\t\t\t\t<Badge tone=\"success\">\n\t\t\t\t\t\t<ArrowUpIcon />\n\t\t\t\t\t\t12.4%\n\t\t\t\t\t</Badge>\n\t\t\t\t</Stack>\n\t\t\t\t<Sparkline data={[18, 22, 19, 27, 24, 31, 29, 38]} tone=\"success\" label=\"Revenue rising over eight weeks\" />\n\t\t\t\t<Text size=\"xs\" type=\"secondary\">\n\t\t\t\t\tNet of refunds, this quarter\n\t\t\t\t</Text>\n\t\t\t</Stack>\n\t\t</Card>\n\t)\n}"
     },
+    {
+      "id": "workspace-navigation-reference",
+      "title": "Workspace navigation reference",
+      "route": "/app-shell",
+      "page": "App shell",
+      "module": "layout/app-shell",
+      "modules": [
+        "layout/app-shell",
+        "layout/sidebar"
+      ],
+      "supportingModules": [
+        "base/typography"
+      ],
+      "import": "themelia-ui/layout/app-shell",
+      "code": "import { useState } from \"react\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { TopbarSidebarLayout } from \"themelia-ui/layout/app-shell\"\nimport { AppSidebar, type LinkRenderer } from \"themelia-ui/layout/sidebar\"\n\nexport default function WorkspaceNavigationReference() {\n\tconst [route, setRoute] = useState(\"/a/overview\")\n\tconst [navigations, setNavigations] = useState(0)\n\tconst workspace = route.startsWith(\"/b/\") ? \"B\" : \"A\"\n\tconst renderLink: LinkRenderer = ({ href, children, external, active, disabled, onClick, ...props }) => {\n\t\tvoid active\n\t\tif (disabled || !href) return <span {...props}>{children}</span>\n\t\treturn <a {...props} href={href} target={props.target ?? (external ? \"_blank\" : undefined)} rel={props.rel ?? (external ? \"noopener noreferrer\" : undefined)} onClick={event => {\n\t\t\tonClick?.(event)\n\t\t\tif (event.defaultPrevented || external || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return\n\t\t\tevent.preventDefault(); setRoute(href); setNavigations(count => count + 1)\n\t\t}}>{children}</a>\n\t}\n\treturn <div style={{ width: \"100%\", height: \"28rem\", minWidth: 0 }}>\n\t\t<TopbarSidebarLayout contained contentRender={<div />} logo=\"Reference workspace\" sidebarProviderProps={{ persist: false, keyboardShortcut: false }} sidebar={<AppSidebar logo={`Workspace ${workspace}`} renderLink={renderLink} currentUrl={route}\n\t\t\tworkspaceLinks={[{ 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\" }]}\n\t\t\tnavigationGroups={{ \"\": [{ label: `${workspace} overview`, href: `/${workspace.toLowerCase()}/overview` }, { label: `${workspace} settings`, href: `/${workspace.toLowerCase()}/settings` }] }} />}>\n\t\t\t<Text role=\"status\">Workspace {workspace}; route {route}; navigations {navigations}</Text>\n\t\t</TopbarSidebarLayout>\n\t</div>\n}"
+    },
     {
       "id": "sidebar-shell",
       "title": "The shell",
@@ -1808,6 +1862,25 @@
       "import": "themelia-ui/base/value-inputs",
       "code": "import { FormField } from \"themelia-ui/base/forms\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { ColorInput } from \"themelia-ui/base/value-inputs\"\n\n\nexport default function ColorFormats() {\n\treturn (\n\t\t<Stack style={{ maxWidth: \"26rem\", width: \"100%\" }}>\n\t\t\t<FormField label=\"oklch (default)\" helperText=\"Pick a colour from the swatch to see the notation change.\">\n\t\t\t\t<ColorInput defaultValue=\"oklch(0.45 0.12 155)\" />\n\t\t\t</FormField>\n\t\t\t<FormField label=\"hex\">\n\t\t\t\t<ColorInput format=\"hex\" defaultValue=\"#2f6f4e\" />\n\t\t\t</FormField>\n\t\t\t<FormField label=\"rgb\">\n\t\t\t\t<ColorInput format=\"rgb\" defaultValue=\"rgb(47, 111, 78)\" />\n\t\t\t</FormField>\n\t\t\t<FormField label=\"hsl\">\n\t\t\t\t<ColorInput format=\"hsl\" defaultValue=\"hsl(151, 40%, 31%)\" />\n\t\t\t</FormField>\n\t\t</Stack>\n\t)\n}"
     },
+    {
+      "id": "scoped-resource-reference",
+      "title": "Scoped resource selection",
+      "route": "/combobox",
+      "page": "Combobox",
+      "module": "features/combobox",
+      "modules": [
+        "features/combobox"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/forms",
+        "base/overlay",
+        "base/structure",
+        "base/typography"
+      ],
+      "import": "themelia-ui/features/combobox",
+      "code": "import { useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { FormField } from \"themelia-ui/base/forms\"\nimport { Overlay, OverlayTrigger, OverlayContent, OverlayHeader, OverlayTitle, OverlayDescription, OverlayBody } from \"themelia-ui/base/overlay\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { ResourceCombobox } from \"themelia-ui/features/combobox\"\n\ntype Resource = { id: string; label: string }\ntype Mode = \"results\" | \"pending\" | \"empty\" | \"error\"\n\nexport default function ScopedResourceReference() {\n\tconst [scope, setScope] = useState(\"A\")\n\tconst [mode, setMode] = useState<Mode>(\"results\")\n\tconst [query, setQuery] = useState(\"\")\n\tconst [value, setValue] = useState<Resource | null>({ id: \"A-1\", label: \"A project\" })\n\tconst [selections, setSelections] = useState(0)\n\tconst [submissions, setSubmissions] = useState(0)\n\tconst [completions, setCompletions] = useState(0)\n\treturn <Overlay>\n\t\t<OverlayTrigger render={<Button />}>Choose scoped resource</OverlayTrigger>\n\t\t<OverlayContent>\n\t\t\t<OverlayHeader><OverlayTitle>Assign resource</OverlayTitle><OverlayDescription>Lookup validity belongs to a workspace. The application decides whether a selected resource remains valid.</OverlayDescription></OverlayHeader>\n\t\t\t<OverlayBody>\n\t\t\t\t<form onSubmit={event => { event.preventDefault(); setSubmissions(count => count + 1) }}>\n\t\t\t\t\t<Stack>\n\t\t\t\t\t\t<Stack direction=\"horizontal\" gap=\"sm\" wrap>\n\t\t\t\t\t\t\t{[\"A\", \"B\"].map(key => <Button key={key} tone=\"neutral\" appearance=\"outline\" onClick={() => { setScope(key); setValue(null) }}>Workspace {key}</Button>)}\n\t\t\t\t\t\t</Stack>\n\t\t\t\t\t\t<Stack direction=\"horizontal\" gap=\"sm\" wrap>\n\t\t\t\t\t\t\t{([\"results\", \"pending\", \"empty\", \"error\"] as const).map(key => <Button key={key} tone=\"neutral\" appearance=\"ghost\" onClick={() => setMode(key)}>{key}</Button>)}\n\t\t\t\t\t\t</Stack>\n\t\t\t\t\t\t<FormField label=\"Resource\" hint={`Searching workspace ${scope}`}>\n\t\t\t\t\t\t\t<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}\n\t\t\t\t\t\t\t\tfetcher={async ({ query: search, signal }) => {\n\t\t\t\t\t\t\t\t\t// The mock deliberately ignores abort; the picker must suppress its late answer.\n\t\t\t\t\t\t\t\t\tvoid signal\n\t\t\t\t\t\t\t\t\tawait new Promise(resolve => setTimeout(resolve, mode === \"pending\" ? 2400 : scope === \"A\" ? 600 : 80))\n\t\t\t\t\t\t\t\t\tif (mode === \"error\") throw new Error(\"Lookup unavailable\")\n\t\t\t\t\t\t\t\t\treturn mode === \"empty\" || (search && !\"project\".includes(search.toLowerCase())) ? [] : [{ id: `${scope}-1`, label: `${scope} project` }]\n\t\t\t\t\t\t\t\t}} onAfterFetch={() => setCompletions(count => count + 1)} />\n\t\t\t\t\t\t</FormField>\n\t\t\t\t\t\t<Button type=\"submit\">Assign</Button>\n\t\t\t\t\t\t<Text role=\"status\">Selections {selections}; submissions {submissions}; completions {completions}</Text>\n\t\t\t\t\t</Stack>\n\t\t\t\t</form>\n\t\t\t</OverlayBody>\n\t\t</OverlayContent>\n\t</Overlay>\n}"
+    },
     {
       "id": "combobox-picker",
       "title": "A picker that fetches",
@@ -2242,6 +2315,24 @@
       "import": "themelia-ui/base/forms-numeric",
       "code": "import { useState } from \"react\"\n\nimport { FormField } from \"themelia-ui/base/forms\"\nimport { CurrencyInput } from \"themelia-ui/base/forms-numeric\"\nimport { Stack } from \"themelia-ui/base/structure\"\n\n\nexport default function Currency() {\n\tconst [amount, setAmount] = useState(\"1299.50\")\n\tconst [currency, setCurrency] = useState(\"EUR\")\n\n\treturn (\n\t\t<Stack style={{ maxWidth: \"26rem\", width: \"100%\" }}>\n\t\t\t<FormField label=\"Invoice total\">\n\t\t\t\t<CurrencyInput\n\t\t\t\t\tvalue={amount}\n\t\t\t\t\tonChange={(event) => setAmount(event.target.value)}\n\t\t\t\t\tcurrency={currency}\n\t\t\t\t\tonCurrencyChange={setCurrency}\n\t\t\t\t\tcurrencies={[\"EUR\", \"USD\", \"GBP\"]}\n\t\t\t\t/>\n\t\t\t</FormField>\n\t\t\t<FormField label=\"Selector at the end\">\n\t\t\t\t<CurrencyInput defaultValue=\"49.00\" defaultCurrency=\"USD\" currencyPosition=\"end\" />\n\t\t\t</FormField>\n\t\t</Stack>\n\t)\n}"
     },
+    {
+      "id": "resource-index-reference",
+      "title": "Server resource index reference",
+      "route": "/data-view",
+      "page": "Data view & data table",
+      "module": "features/data-view",
+      "modules": [
+        "features/data-view"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/structure",
+        "base/typography",
+        "features/filters"
+      ],
+      "import": "themelia-ui/features/data-view",
+      "code": "import { useEffect, useRef, useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Heading, Text } from \"themelia-ui/base/typography\"\nimport { DataView, type DataViewProps } from \"themelia-ui/features/data-view\"\nimport { FilterType, type ActiveFilter, type FilterConfig } from \"themelia-ui/features/filters\"\n\ntype RecordRow = { id: string; name: string; status: string; searchTerms: string }\nconst RECORDS: RecordRow[] = Array.from({ length: 6 }, (_, index) => ({ id: `r${index + 1}`, name: `Resource ${index + 1}`, status: index % 2 ? \"Closed\" : \"Open\", searchTerms: \"hidden reference term\" }))\nconst COLUMNS: DataViewProps<RecordRow>[\"columns\"] = [{ accessorKey: \"name\", header: \"Resource\" }, { accessorKey: \"status\", header: \"Status\" }]\nconst 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\" }] }]\n\nexport default function ResourceIndexReference() {\n\tconst [filters, setFilters] = useState<ActiveFilter[]>([])\n\tconst [page, setPage] = useState(0)\n\tconst [rows, setRows] = useState<RecordRow[]>([])\n\tconst [hasNext, setHasNext] = useState(false)\n\tconst [pending, setPending] = useState(true)\n\tconst [error, setError] = useState<string>()\n\tconst [refresh, setRefresh] = useState(0)\n\tconst [selection, setSelection] = useState<Record<string, true>>({})\n\tconst [answeredQuery, setAnsweredQuery] = useState(\"\")\n\tconst [commands, setCommands] = useState(\"\")\n\tconst failNext = useRef(false)\n\tuseEffect(() => {\n\t\tlet active = true\n\t\tasync function load() {\n\t\t\tsetPending(true); setError(undefined)\n\t\t\tawait new Promise(resolve => setTimeout(resolve, 250))\n\t\t\tif (!active) return\n\t\t\tif (failNext.current) { failNext.current = false; setError(\"Refresh failed. Previous rows remain available.\"); setPending(false); return }\n\t\t\tconst search = filters.find(filter => filter.key === \"search\")?.value[0]?.toLowerCase() ?? \"\"\n\t\t\tconst status = filters.find(filter => filter.key === \"status\")?.value[0]\n\t\t\tconst matches = RECORDS.filter(row => `${row.name} ${row.searchTerms}`.toLowerCase().includes(search) && (!status || row.status === status))\n\t\t\tsetAnsweredQuery(search); setRows(matches.slice(page * 2, page * 2 + 2)); setHasNext(matches.length > page * 2 + 2); setPending(false)\n\t\t}\n\t\tvoid load()\n\t\treturn () => { active = false }\n\t}, [filters, page, refresh])\n\treturn <div style={{ width: \"100%\", minWidth: 0, maxWidth: \"48rem\" }}>\n\t\t<Stack>\n\t\t\t<Heading level={3}>Resource index</Heading>\n\t\t\t<Text type=\"secondary\">Server matching includes fields absent from the visible columns. Totals are unknown; selection applies to the current page.</Text>\n\t\t\t{error && <Text role=\"alert\" type=\"error\">{error}</Text>}\n\t\t\t<DataView data={rows} columns={COLUMNS} filtering={{ filters: FILTERS, activeFilters: filters, onFilterChange: next => { setFilters(next); setPage(0); setSelection({}) }, filterRows: ({ data }) => [...data], isFiltering: pending }}\n\t\t\t\ttable={{ 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> }}\n\t\t\t\tslots={{ 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> }} />\n\t\t\t<Text role=\"status\">{pending ? \"Loading page\" : `${rows.length} rows supplied by server; matched ${answeredQuery || \"all\"}`}{commands && `; ${commands}`}</Text>\n\t\t</Stack>\n\t</div>\n}"
+    },
     {
       "id": "data-view",
       "title": "An index",
@@ -2864,6 +2955,26 @@
       "import": "themelia-ui/base/forms",
       "code": "import { FieldGroup, FormField } from \"themelia-ui/base/forms\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Input } from \"themelia-ui/base/text-inputs\"\n\n\nexport default function FieldGroupExample() {\n\treturn (\n\t\t<div style={{ maxWidth: \"34rem\", width: \"100%\" }}>\n\t\t\t<FieldGroup legend=\"Reporting period\" description=\"Both ends are inclusive.\">\n\t\t\t\t<Stack direction=\"horizontal\" gap=\"sm\">\n\t\t\t\t\t<FormField label=\"From\">\n\t\t\t\t\t\t<Input type=\"date\" defaultValue=\"2026-03-01\" />\n\t\t\t\t\t</FormField>\n\t\t\t\t\t<FormField label=\"To\">\n\t\t\t\t\t\t<Input type=\"date\" defaultValue=\"2026-03-31\" />\n\t\t\t\t\t</FormField>\n\t\t\t\t</Stack>\n\t\t\t</FieldGroup>\n\t\t</div>\n\t)\n}"
     },
+    {
+      "id": "multi-section-reference",
+      "title": "Multi-section form reference",
+      "route": "/form-workflow",
+      "page": "Form workflow",
+      "module": "base/forms",
+      "modules": [
+        "base/forms"
+      ],
+      "supportingModules": [
+        "base/cards",
+        "base/display",
+        "base/structure",
+        "base/text-inputs",
+        "base/typography",
+        "forms"
+      ],
+      "import": "themelia-ui/base/forms",
+      "code": "import { useRef, useState } from \"react\"\nimport { Card } from \"themelia-ui/base/cards\"\nimport { ContentBlock } from \"themelia-ui/base/display\"\nimport { FieldGroup, FormField, FormSection, FormActionsBar, SubmitStateButton } from \"themelia-ui/base/forms\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Input } from \"themelia-ui/base/text-inputs\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { useFormFieldBinding, useStateFormControl, type FormControl } from \"themelia-ui/forms\"\n\ntype Draft = { firstName: string; lastName: string; company: string }\nfunction BoundField({ control, name, label, error }: { control: FormControl<Draft>; name: keyof Draft; label: string; error?: string }) {\n\tconst field = useFormFieldBinding<string, Draft>({ control, name })\n\treturn <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>\n}\n\nexport default function MultiSectionReference() {\n\tconst control = useStateFormControl<Draft>({ firstName: \"Alex\", lastName: \"Example\", company: \"Example team\" })\n\tconst [pending, setPending] = useState(false)\n\tconst [error, setError] = useState<string>()\n\tconst [rootError, setRootError] = useState<string>()\n\tconst [saved, setSaved] = useState(0)\n\tconst running = useRef(false)\n\treturn <Stack>\n\t\t<Card title=\"Account details\" description=\"One outer surface, editable sections with retained region insets.\">\n\t\t\t<form onSubmit={async event => {\n\t\t\t\tevent.preventDefault(); if (running.current) return\n\t\t\t\trunning.current = true; setPending(true); setError(undefined); setRootError(undefined)\n\t\t\t\ttry {\n\t\t\t\t\tawait new Promise(resolve => setTimeout(resolve, 250))\n\t\t\t\t\tif (control.values.company === \"offline\") throw new Error(\"Request failed. Your values remain here.\")\n\t\t\t\t\tif (control.values.company.length < 3) { setError(\"Company must have at least three characters.\"); return }\n\t\t\t\t\tsetSaved(count => count + 1)\n\t\t\t\t} catch (failure) { setRootError((failure as Error).message) }\n\t\t\t\tfinally { running.current = false; setPending(false) }\n\t\t\t}}>\n\t\t\t\t<Stack gap=\"none\">\n\t\t\t\t\t{rootError && <Text role=\"alert\" type=\"error\">{rootError}</Text>}\n\t\t\t\t\t<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>\n\t\t\t\t\t<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>\n\t\t\t\t\t<FormActionsBar leading={<Text role=\"status\">Successful submissions {saved}</Text>}><SubmitStateButton type=\"submit\" state={pending ? \"submitting\" : \"idle\"} strings={{ idle: \"Save account\" }} /></FormActionsBar>\n\t\t\t\t</Stack>\n\t\t\t</form>\n\t\t</Card>\n\t\t<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>\n\t</Stack>\n}"
+    },
     {
       "id": "form-section",
       "title": "FormSection",
@@ -3332,6 +3443,23 @@
       "import": "themelia-ui/features/map",
       "code": "import { useState } from \"react\"\n\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport {\n\tMap, MapSearchControl, MapTileLayer, MapZoomControl, PlaceAutocomplete, type PlaceFeature,\n} from \"themelia-ui/features/map\"\n\nimport { MARLOW } from \"./data\"\n\nexport default function PlaceAutocompleteExample() {\n\tconst [place, setPlace] = useState<PlaceFeature | null>(null)\n\n\treturn (\n\t\t<>\n\t\t\t<Stack gap=\"sm\" maxWidth=\"24rem\">\n\t\t\t\t<PlaceAutocomplete limit={5} onPlaceSelect={setPlace} />\n\t\t\t</Stack>\n\t\t\t{!!place && (\n\t\t\t\t<Text size=\"sm\" type=\"secondary\" numeric>\n\t\t\t\t\t{place.properties.name} — {place.geometry.coordinates[1].toFixed(4)},{\" \"}\n\t\t\t\t\t{place.geometry.coordinates[0].toFixed(4)}\n\t\t\t\t</Text>\n\t\t\t)}\n\n\t\t\t<Map center={MARLOW} zoom={13} height=\"26rem\">\n\t\t\t\t<MapTileLayer />\n\t\t\t\t<MapSearchControl position=\"top-left\" limit={5} />\n\t\t\t\t<MapZoomControl position=\"top-right\" />\n\t\t\t</Map>\n\t\t</>\n\t)\n}"
     },
+    {
+      "id": "media-picking-reference",
+      "title": "Media picking reference",
+      "route": "/media-library",
+      "page": "Media library",
+      "module": "features/media-library",
+      "modules": [
+        "features/media-library"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/structure",
+        "base/typography"
+      ],
+      "import": "themelia-ui/features/media-library",
+      "code": "import { useEffect, useMemo, useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { MediaLibraryDialog, type MediaLibraryItem, type MediaLibraryFetcher } from \"themelia-ui/features/media-library\"\n\nimport { SAMPLE_MEDIA } from \"./reference-data\"\n\nexport default function MediaPickingReference() {\n\tconst [open, setOpen] = useState(false)\n\tconst [scope, setScope] = useState(\"site\")\n\tconst [fail, setFail] = useState(false)\n\tconst [selected, setSelected] = useState<string[]>([\"unavailable-id\"])\n\tconst [pickerDraft, setPickerDraft] = useState(selected)\n\tconst [resolved, setResolved] = useState<{ scope: string; ids: string[]; items: MediaLibraryItem[] }>()\n\tconst [page, setPage] = useState(0)\n\tconst [query, setQuery] = useState(\"\")\n\tconst [pending, setPending] = useState(true)\n\tconst [hasNext, setHasNext] = useState(false)\n\t// A saved id is resolved separately from the current browser page, with scope access applied.\n\tuseEffect(() => {\n\t\tconst controller = new AbortController()\n\t\tconst timer = setTimeout(() => {\n\t\t\tif (!controller.signal.aborted) setResolved({ scope, ids: selected, items: SAMPLE_MEDIA.filter(item => selected.includes(item.id) && item.collection === scope) })\n\t\t}, 150)\n\t\treturn () => { controller.abort(); clearTimeout(timer) }\n\t}, [selected, scope])\n\tconst chosen = resolved?.scope === scope && resolved.ids === selected ? resolved.items : []\n\tconst unavailable = resolved?.scope === scope && resolved.ids === selected && chosen.length < selected.length\n\tconst changeOpen = (next: boolean) => {\n\t\tif (next) setPickerDraft(selected)\n\t\tsetOpen(next)\n\t}\n\tconst fetcher = useMemo<MediaLibraryFetcher>(() => async ({ query: search, signal }) => {\n\t\tsetPending(true)\n\t\ttry {\n\t\t\tawait new Promise(resolve => setTimeout(resolve, 200))\n\t\t\tif (signal?.aborted) throw new DOMException(\"Aborted\", \"AbortError\")\n\t\t\tif (fail) throw new Error(\"Media lookup unavailable\")\n\t\t\tconst matches = SAMPLE_MEDIA.filter(item => item.collection === scope && item.name.toLowerCase().includes(search.toLowerCase()))\n\t\t\tconst window = matches.slice(page, page + 2)\n\t\t\tsetHasNext(window.length > 1)\n\t\t\treturn { items: window.slice(0, 1) }\n\t\t} finally { if (!signal?.aborted) setPending(false) }\n\t}, [scope, fail, page])\n\treturn <Stack>\n\t\t{unavailable && <Text role=\"alert\">The saved asset is unavailable. Choose a replacement; the draft id is retained until then.</Text>}\n\t\t<Stack direction=\"horizontal\" gap=\"sm\" wrap>\n\t\t\t<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}\n\t\t\t\tstrings={{ showingCount: shown => `${shown} loaded on this page; total unknown` }}\n\t\t\t\tslots={{ footer: <Stack direction=\"horizontal\" gap=\"sm\" wrap align=\"center\">\n\t\t\t\t\t<Text>Media page {page + 1}; total unknown</Text>\n\t\t\t\t\t<Button disabled={pending || page === 0} onClick={() => { setPage(value => value - 1); setPending(true) }}>Previous media page</Button>\n\t\t\t\t\t<Button disabled={pending || !hasNext} onClick={() => { setPage(value => value + 1); setPending(true) }}>Next media page</Button>\n\t\t\t\t</Stack> }}\n\t\t\t\tonConfirm={(items, ids) => { setSelected(ids); setResolved({ scope, ids, items }); setOpen(false) }} />\n\t\t\t<Button tone=\"neutral\" appearance=\"outline\" onClick={() => setSelected([\"image-2\"])}>Load saved media draft</Button>\n\t\t\t<Button tone=\"neutral\" appearance=\"outline\" onClick={() => { setScope(value => value === \"site\" ? \"other\" : \"site\"); setPage(0); setPending(true) }}>Switch media scope</Button>\n\t\t\t<Button tone=\"neutral\" appearance=\"outline\" onClick={() => { setFail(value => !value); setPending(true) }}>Toggle media failure</Button>\n\t\t</Stack>\n\t\t<Text role=\"status\">{chosen.length ? `Hydrated selection: ${chosen.map(item => `${item.name} — ${item.alt}`).join(\", \")}` : `Saved draft ids: ${selected.join(\", \")}`}</Text>\n\t</Stack>\n}"
+    },
     {
       "id": "library",
       "title": "Asset manager",
@@ -3803,6 +3931,26 @@
       "import": "themelia-ui/base/dialog",
       "code": "import { Button } from \"themelia-ui/base/buttons\"\nimport { DialogContent } from \"themelia-ui/base/dialog\"\nimport {\n\tOverlay, OverlayDescription, OverlayHeader, OverlayTitle, OverlayTrigger,\n} from \"themelia-ui/base/overlay\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { UIProvider } from \"themelia-ui/ui-provider\"\n\nexport default function OverlayBackdrop() {\n\treturn (\n\t\t<Stack direction=\"horizontal\" wrap align=\"center\">\n\t\t\t<Overlay>\n\t\t\t\t<OverlayTrigger render={<Button tone=\"neutral\" appearance=\"outline\" />}>\n\t\t\t\t\tDefault scrim\n\t\t\t\t</OverlayTrigger>\n\t\t\t\t<DialogContent>\n\t\t\t\t\t<OverlayHeader>\n\t\t\t\t\t\t<OverlayTitle>Default scrim</OverlayTitle>\n\t\t\t\t\t\t<OverlayDescription>A tint only — the page behind stays sharp.</OverlayDescription>\n\t\t\t\t\t</OverlayHeader>\n\t\t\t\t</DialogContent>\n\t\t\t</Overlay>\n\n\t\t\t<UIProvider config={{ overlay: { backdropBlur: 4 } }}>\n\t\t\t\t<Overlay>\n\t\t\t\t\t<OverlayTrigger render={<Button tone=\"neutral\" appearance=\"outline\" />}>\n\t\t\t\t\t\tBlurred scrim\n\t\t\t\t\t</OverlayTrigger>\n\t\t\t\t\t<DialogContent>\n\t\t\t\t\t\t<OverlayHeader>\n\t\t\t\t\t\t\t<OverlayTitle>Blurred scrim</OverlayTitle>\n\t\t\t\t\t\t\t<OverlayDescription>The same dialog under a provider that asks for a 4px blur.</OverlayDescription>\n\t\t\t\t\t\t</OverlayHeader>\n\t\t\t\t\t</DialogContent>\n\t\t\t\t</Overlay>\n\t\t\t</UIProvider>\n\t\t</Stack>\n\t)\n}"
     },
+    {
+      "id": "record-detail-reference",
+      "title": "Record detail reference",
+      "route": "/page",
+      "page": "Page & page header",
+      "module": "layout/page",
+      "modules": [
+        "layout/page"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/cards",
+        "base/display",
+        "base/structure",
+        "base/table",
+        "base/typography"
+      ],
+      "import": "themelia-ui/layout/page",
+      "code": "import { useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { Card, CardContent, CardHeader } from \"themelia-ui/base/cards\"\nimport { ContentBlock, MetadataList } from \"themelia-ui/base/display\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Text } from \"themelia-ui/base/typography\"\nimport { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from \"themelia-ui/base/table\"\nimport { Page } from \"themelia-ui/layout/page\"\n\nexport default function RecordDetailReference() {\n\tconst [activity, setActivity] = useState(\"No commands yet\")\n\treturn <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> }}>\n\t\t<Stack>\n\t\t\t<Card title=\"Identity\" titleLevel={2} headerAction={<Button tone=\"neutral\" appearance=\"outline\" onClick={() => setActivity(\"Identity command: edit R-104\")}>Edit identity</Button>}>\n\t\t\t\t<MetadataList items={[{ id: \"owner\", label: \"Owner\", value: \"Example team\" }, { id: \"state\", label: \"State\", value: \"Active\" }]} />\n\t\t\t\t<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>\n\t\t\t</Card>\n\t\t\t<Card><CardHeader title=\"Related records\" titleLevel={2} description=\"The header is composed from parts; omit Card title props when supplying it.\" /><CardContent>\n\t\t\t\t<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>\n\t\t\t</CardContent></Card>\n\t\t\t<Text role=\"status\">{activity}</Text>\n\t\t</Stack>\n\t</Page>\n}"
+    },
     {
       "id": "page-heading",
       "title": "PageHeading",
@@ -4957,6 +5105,28 @@
       "import": "themelia-ui/features/resource",
       "code": "import { PlusIcon } from \"lucide-react\"\n\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { StackedCardsIllustration } from \"themelia-ui/base/feedback\"\nimport { ResourceEmptyState } from \"themelia-ui/features/resource\"\n\nexport default function ResourceEmpty() {\n\treturn (\n\t\t<ResourceEmptyState\n\t\t\tmediaVariant=\"illustration\"\n\t\t\tmedia={<StackedCardsIllustration />}\n\t\t\ttitle=\"No invoices yet\"\n\t\t\tdescription=\"Invoices appear here once a customer is billed.\"\n\t\t\taction={<Button><PlusIcon />New invoice</Button>}\n\t\t\tborder\n\t\t/>\n\t)\n}"
     },
+    {
+      "id": "website-content-reference",
+      "title": "Website content reference",
+      "route": "/rich-text-editor",
+      "page": "Rich text editor",
+      "module": "features/rich-text-editor",
+      "modules": [
+        "base/typography",
+        "features/rich-text-editor"
+      ],
+      "supportingModules": [
+        "base/buttons",
+        "base/cards",
+        "base/choice-inputs",
+        "base/forms",
+        "base/structure",
+        "base/text-inputs",
+        "features/media-library"
+      ],
+      "import": "themelia-ui/features/rich-text-editor",
+      "code": "import { useState } from \"react\"\nimport { Button } from \"themelia-ui/base/buttons\"\nimport { Card } from \"themelia-ui/base/cards\"\nimport { PillRadioGroup } from \"themelia-ui/base/choice-inputs\"\nimport { FormField } from \"themelia-ui/base/forms\"\nimport { Stack } from \"themelia-ui/base/structure\"\nimport { Input } from \"themelia-ui/base/text-inputs\"\nimport { RichText, Text } from \"themelia-ui/base/typography\"\nimport { MediaLibraryDialog, type MediaLibraryItem } from \"themelia-ui/features/media-library\"\nimport { RichTextEditor } from \"themelia-ui/features/rich-text-editor\"\nimport { SAMPLE_MEDIA } from \"../media-library/reference-data\"\n\nexport default function WebsiteContentReference() {\n\tconst [locale, setLocale] = useState(\"en\")\n\tconst [drafts, setDrafts] = useState<Record<string, string>>({ en: \"<p>Welcome to our workspace.</p>\", ar: \"<p>مرحباً بكم</p>\" })\n\tconst [mediaOpen, setMediaOpen] = useState(false)\n\tconst [image, setImage] = useState<MediaLibraryItem>()\n\tconst [alt, setAlt] = useState(\"\")\n\tconst [failed, setFailed] = useState(true)\n\tconst [pending, setPending] = useState(false)\n\tconst [message, setMessage] = useState(\"Drafts are local until saved\")\n\treturn <Card title=\"Website content\" description=\"Each locale owns a retained draft. Preview sanitizes HTML; the application also validates and sanitizes persisted content.\">\n\t\t<Stack>\n\t\t\t<PillRadioGroup aria-label=\"Content locale\" name=\"reference-content-locale\" value={locale} onValueChange={value => value && setLocale(value)} options={[{ value: \"en\", label: \"English\" }, { value: \"ar\", label: \"العربية\" }]} />\n\t\t\t<div dir={locale === \"ar\" ? \"rtl\" : \"ltr\"}><RichTextEditor value={drafts[locale] ?? \"\"} onValueChange={html => setDrafts(current => ({ ...current, [locale]: html }))} /></div>\n\t\t\t<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) }} />\n\t\t\t{image && <FormField label=\"Hero image alternative text\" hint={image.name}><Input value={alt} onChange={event => setAlt(event.target.value)} /></FormField>}\n\t\t\t<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>\n\t\t\t<Text role=\"status\">{message}</Text>\n\t\t\t<RichText html={drafts[locale] ?? \"\"} />\n\t\t</Stack>\n\t</Card>\n}"
+    },
     {
       "id": "editor",
       "title": "The editor and what comes out",
@@ -5500,7 +5670,7 @@
       ],
       "supportingModules": [],
       "import": "themelia-ui/base/structure",
-      "code": "import { Grid, GridCell } from \"themelia-ui/base/structure\"\n\nimport { Box } from \"./_shared\"\n\nexport default function GridExample() {\n\treturn (\n\t\t<Grid columns={{ base: 1, md: 3 }} gap=\"sm\">\n\t\t\t<GridCell span=\"full\"><Box>span full</Box></GridCell>\n\t\t\t<GridCell><Box>one</Box></GridCell>\n\t\t\t<GridCell><Box>two</Box></GridCell>\n\t\t\t<GridCell><Box>three</Box></GridCell>\n\t\t\t<GridCell span={{ base: 1, md: 2 }}><Box>span 2 from md</Box></GridCell>\n\t\t\t<GridCell><Box>four</Box></GridCell>\n\t\t</Grid>\n\t)\n}"
+      "code": "import { Grid, GridCell } from \"themelia-ui/base/structure\"\n\nimport { Box } from \"./_shared\"\n\nexport default function GridExample() {\n\treturn (\n\t\t<Grid columns={{ base: 1, md: 3 }} gap=\"sm\">\n\t\t\t<GridCell span=\"full\"><Box>span full</Box></GridCell>\n\t\t\t<GridCell><Box>one</Box></GridCell>\n\t\t\t<GridCell><Box>two</Box></GridCell>\n\t\t\t<GridCell><Box>three</Box></GridCell>\n\t\t\t<GridCell span={{ base: 1, md: 2 }}><Box>span 2 from md</Box></GridCell>\n\t\t\t<GridCell><Box>four</Box></GridCell>\n\t\t\t<GridCell span={{ base: 1, md: \"full\", xl: 2 }}><Box>responsive full row</Box></GridCell>\n\t\t</Grid>\n\t)\n}"
     },
     {
       "id": "adaptivegrid",

package/docs/generated/workflows/communications-overview/analytics/communications-reference.tsx

@@ -0,0 +1,19 @@
+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>
+}