themelia-ui 3.1.0 → 3.2.0

package/docs/generated/workflows/media-picking/media-library/media-picking-reference.tsx

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

package/docs/generated/workflows/media-picking/media-library/reference-data.ts

@@ -0,0 +1,3 @@
+import type { MediaLibraryItem } from "themelia-ui/features/media-library"
+
+export const SAMPLE_MEDIA: MediaLibraryItem[] = [{ id: "image-1", name: "Garden exterior", type: "image", alt: "A garden with a stone path", collection: "site", public: true }, { id: "image-2", name: "Meeting room", type: "image", alt: "A meeting room with daylight", collection: "site", public: true }]

package/docs/generated/workflows/multi-section-form/form-workflow/multi-section-reference.tsx

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

package/docs/generated/workflows/nested-action-flow/action-overlays/nested-action-reference.tsx

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

package/docs/generated/workflows/record-detail/page-layout/record-detail-reference.tsx

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

package/docs/generated/workflows/resource-index/data-view/resource-index-reference.tsx

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

package/docs/generated/workflows/scoped-resource-selection/combobox/scoped-resource-reference.tsx

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

package/docs/generated/workflows/website-content-editor/media-library/reference-data.ts

@@ -0,0 +1,3 @@
+import type { MediaLibraryItem } from "themelia-ui/features/media-library"
+
+export const SAMPLE_MEDIA: MediaLibraryItem[] = [{ id: "image-1", name: "Garden exterior", type: "image", alt: "A garden with a stone path", collection: "site", public: true }, { id: "image-2", name: "Meeting room", type: "image", alt: "A meeting room with daylight", collection: "site", public: true }]

package/docs/generated/workflows/website-content-editor/rich-text-editor/website-content-reference.tsx

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

package/docs/generated/workflows/workspace-navigation/app-shell/workspace-navigation-reference.tsx

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

package/docs/learn/api-compatibility.md

@@ -1,6 +1,6 @@
 # API compatibility
 
-Within a major version, exact package subpaths, exported names, callable signatures, and
+Exact package subpaths, exported names, callable signatures, and
 exported props/type members are compatibility surfaces. Public global theme tokens, documented
 `data-slot` and BEM hooks, and the `strings` contracts are also consumer contracts.
 
@@ -15,7 +15,8 @@ exported props/type members are compatibility surfaces. Public global theme toke
 | a documented default changes | behavioural change; release notes required |
 | component token or hashed CSS Module name changes | internal unless documented as an extension point |
 
-3.1 removes obsolete aliases and adapters. Removed names do not stay available solely for an
+3.1 includes breaking changes despite its minor version number: it removes obsolete aliases
+and adapters. Removed names do not stay available solely for an
 upgrade window. A breaking release records the replacement in the migration reference and
 the changelog; consumers pin the old version until they are ready to update.
 

package/docs/learn/blocks.md

@@ -0,0 +1,123 @@
+# Choosing and composing blocks
+
+A structural block arranges regions; a subject block renders a recognizable job such as
+metrics, onboarding or an order summary. Use [Structure and spacing](./structure-and-spacing.md)
+for page geometry, surfaces and gaps. Start with a ready subject block when its vocabulary
+fits the product, then use its documented props, callbacks or parts. The application keeps
+data, permission checks, routing, mutation and persistence.
+
+## Published subject modules
+
+| Job | Exact subpath and examples | Application owns | Optional peers |
+| --- | --- | --- | --- |
+| Quantities, changes and plots | `themelia-ui/blocks/analytics`: MetricGrid, Metric, MetricComparison, ChartCard, ActivityHeatmap | Measures, period, comparison meaning, loading/errors and metric actions | `recharts`, for the module even when the adopted block has no plot |
+| Setup tasks completed over time | `themelia-ui/blocks/onboarding`: Checklist | Step status, content, submission and persistence | None |
+| Milestones, changelog or linear progress | `themelia-ui/blocks/timelines`: MilestonesTimeline, ChangelogTimeline, Steps, StepsBar | Sequence, status, dates and navigation | None |
+| Permissions and credential management | `themelia-ui/blocks/admin/access`: RolePermissions, CredentialList, SensitiveAction | Authorization, actual secrets, deletion confirmation and mutations | None |
+| Orders, invoices, inventory and payment summaries | `themelia-ui/blocks/admin/commerce`: OrderSummary, InvoiceLineItems, InventorySection, PaymentTimeline | Commerce records, calculation policy, commands and transport | None |
+
+These are modules, not broad barrels: there is no `themelia-ui/blocks` import. General and
+admin profiles come from the same installation. Admin is presentation vocabulary rather
+than an authorization layer; importing an admin block does not protect its actions or data.
+The generated [import table](../generated/imports.md) is authoritative for optional peers.
+Do not assume a symbol is peer-free because its own UI looks simple.
+
+Open the selected API before JSX: [analytics](../generated/components/blocks--analytics.md),
+[onboarding](../generated/components/blocks--onboarding.md),
+[timelines](../generated/components/blocks--timelines.md),
+[admin access](../generated/components/blocks--admin--access.md), or
+[admin commerce](../generated/components/blocks--admin--commerce.md).
+They list exact record shapes, defaults, strings, dependencies and preview recipes.
+
+## Facts versus quantities
+
+MetadataList owns label/value facts such as owner, status, address or a date. A numeric
+identifier is still a fact. MetricGrid/Metric own measures such as delivered messages,
+revenue or a conversion rate, with optional comparison and trend. Put prose facts beside
+quantities rather than turning every value into a metric tile.
+
+```tsx compile
+import { ContentBlock, MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { MetricGrid, type MetricData } from "themelia-ui/blocks/analytics"
+import { Page } from "themelia-ui/layout/page"
+
+const metrics: MetricData[] = [
+  { id: "delivered", label: "Delivered", value: 248 },
+  { id: "opened", label: "Opened", value: null, subtitle: "Tracking unavailable" },
+]
+
+export function DeliveryOverview() {
+  return <Page header={{ title: "Delivery overview", description: "Current campaign" }}>
+    <Stack>
+      <MetricGrid metrics={metrics} variant="card" />
+      <ContentBlock title="Campaign details">
+        <MetadataList items={[
+          { id: "owner", label: "Owner", value: "Alex" },
+          { id: "status", label: "Status", value: "Sending" },
+        ]} />
+      </ContentBlock>
+    </Stack>
+  </Page>
+}
+```
+
+Use `null` for an unavailable MetricData value; zero means a measured zero. MetricGrid's
+loading contract is for initial loading. For error or refresh behavior, inspect the adopted
+component's exact API rather than assuming every analytics block accepts the same props.
+The [communications workflow](./reference-workflows.md) demonstrates retained figures,
+failure feedback, retry, unknown tracking and a separate facts region.
+
+## Compose without duplicating owners
+
+Inspect whether a block already owns its title, surface, controls and responsive layout
+before surrounding it with another Card or Grid. MetricGrid already arranges tiles;
+ChartCard already owns its chart frame; FormSection already owns an editable section's
+header and inset. Use a sibling surface for an independent subject and ContentBlock for
+supporting prose inside one. [Composition](./composition.md#decide-the-owners-before-jsx)
+describes the owners in detail.
+
+Keep default typography and spacing with those owners. Do not invent `size`, `padding`,
+`error` or `strings` props by analogy with another block. Use a documented slot or render
+prop for one region; use public parts or an application composition when the arrangement
+must differ. No block needs every extension seam. The [composition ladder](../generated/composition-ladder.md)
+is a discovery aid; the selected API remains the contract.
+
+## Compose your own subject
+
+When the ready block's vocabulary cannot express the product, start from its public
+lower-tier recipe rather than copying internals. The live block pages include these
+compose-your-own examples; their source is also embedded in
+[recipes.json](../generated/recipes.json) under the exact id below and in the
+[recipe book](../build/recipes.md). The recipe imports identify the adopted modules and
+their peer requirements; they do not require importing the corresponding ready block.
+
+| Subject | Recipe id | Public building blocks |
+| --- | --- | --- |
+| A custom measure | `analytics-blueprint` | Card, Stack, Money, Badge, Sparkline |
+| Setup checklist | `blocks-checklist-blueprint` | Progress, Accordion, IconBadge, Text, Button |
+| Release timeline | `blocks-changelog-blueprint` | Timeline, MonoValue, Badge |
+| Role/permission summary | `blocks-roles-blueprint` | Table, Badge, VisuallyHidden |
+| Custom order summary | `cart-summary-blueprint` | Card, MetadataList, Money, Button, toast |
+
+For example, retrieve the exact checklist source from the installed package:
+
+```bash
+node <<'NODE'
+const fs = require('node:fs')
+const { recipes } = JSON.parse(fs.readFileSync('node_modules/themelia-ui/docs/generated/recipes.json', 'utf8'))
+const recipe = recipes.find(item => item.id === 'blocks-checklist-blueprint')
+if (!recipe) throw new Error('Recipe missing from this installed version')
+process.stdout.write(recipe.code)
+NODE
+```
+
+These examples establish presentation seams, with fixed sample data and mock callbacks.
+Keep the application's real permission model, calculations and completion state in its
+own component. Use the [complete workflows](./reference-workflows.md) when the task needs
+submission, lookup, selection or retained-draft behavior beyond a presentation recipe.
+
+For translated copy, use the selected module's typed strings and exported defaults. Product
+labels and record content remain application copy. Test permissions, loading/empty/error
+states, long labels, keyboard interaction, RTL and the adopted density in the real route;
+the package's previews do not establish application acceptance.

package/docs/learn/composition.md

@@ -20,6 +20,10 @@ ready-made surface does not express the job.
 compose both; neither may import a block. The complete generated graph is in
 [Profiles](../generated/profiles.md).
 
+For structural blocks, spacing roles and responsive widths, use
+[Structure and spacing](./structure-and-spacing.md). For ready analytics, onboarding,
+timeline and admin presentations, use [Choosing blocks](./blocks.md).
+
 ## The composition ladder
 
 Use the lowest rung that solves the real requirement:
@@ -142,6 +146,13 @@ The invoice example above is the canonical shape: `Page` for route geometry,
 `MetadataList` and primitives for facts, then domain callbacks on package actions. Keep the
 record type out of the package.
 
+When the task also fits the standard loading, empty, error and retry presentation, use
+`ResourceShowShell` or `ResourceIndexShell` from `features/resource`. Those shells already
+own a header, body and state replacement; do not duplicate that route header by wrapping
+them in another Page. Page remains appropriate for a custom record arrangement where the
+application already owns lifecycle feedback. Read the
+[resource API](../generated/components/features--resource.md) for state and slot contracts.
+
 ### Form
 
 ```tsx fragment — validation, field values, submit mutation, and product copy remain in the app
@@ -191,7 +202,7 @@ documentation tree whose vocabulary is not settings.
 
 Look up a specific task with the offline finder. Exact symbols take priority; `--explain`
 shows matched components, selection reasons and direct API anchors. `--json` exposes the
-same records for tools. Guidance marked `family` is a fallback, not a component-specific
+same records for tools. Guidance marked `module` is a fallback, not a component-specific
 recommendation. An empty result means refine the query or inspect the catalogue, not invent
 an export.
 
@@ -314,6 +325,92 @@ Only use states the selected module exposes; the API reference is authoritative.
 complete examples above type-check against the built package, but their application
 callbacks are illustrative: verify persistence and browser behaviour in your app.
 
+## Decide the owners before JSX
+
+| Owner | Insets and type | Name and command scope | Parent responsibility |
+| --- | --- | --- | --- |
+| `Page` | Route geometry; header owns heading type | One route heading; route commands | Data, routing and independent subjects |
+| `Card` / parts | Surface and content inset; header owns title/description | A bounded subject; commands for that subject | Arrange sibling subjects, choose heading level |
+| `ContentBlock` | Title/content gap; `plain` has no inset, decorated surfaces add one | Supporting content within a subject | Decide whether another independent surface is warranted |
+| `MetadataList` / values | Fact layout; labels and semantic value formatting | Read-only facts, not editable labels | Permission-filtered records and value descriptors |
+| Analytics blocks | Quantity hierarchy and responsive metric arrangement | Measures and their period; metric actions | Query, unknown quantities and interpretation |
+| `FormSection` | Section inset and heading; `flat` retains its padding | Editable region title; section-specific actions | Form, values, validation and completion |
+| `FieldGroup` | Related control arrangement and support line | Fieldset/legend for a group; children retain distinct labels | Group disabled state and validation policy |
+| `FormField` / binding | Label and support typography, control association | One editable field | Value, mutation and explicit name/ARIA overrides |
+| `Stack` / `Grid` | Shared gaps; no new typography owner | Passive arrangement | Choose whether child insets already supply separation |
+| `DataView` | Filter/table shell and responsive filter presentation | Resource-browser commands | Transport, page totals and selection lifetime |
+| `DataTable` | Tabular interaction and table geometry | Column/row names and row commands | Filters, surrounding surface and server transport |
+| `FilterLayout` / slots | Responsive controls and sheet | Filter controls only | Shared filter state; put export/create in action slots |
+
+`surface="flat"` changes decoration, not the inset contract. Several flat FormSections
+inside CardContent accumulate the card content inset and each section's inset. Use the
+ready Card body when that separation is useful; use parts when you need a different region
+arrangement. `Stack gap="none"` is appropriate when adjacent sections already own their
+vertical separation. Do not compensate by assigning private padding variables or local type.
+
+These are fragments; the [complete workflows](./reference-workflows.md) include state,
+helpers and submission behavior.
+
+```tsx fragment — fields and subject data come from the application
+<Card title="Account details">
+  <Stack gap="none">
+    <FormSection surface="flat" title="Contact">{contactFields}</FormSection>
+    <FormSection surface="flat" title="Billing">{billingFields}</FormSection>
+  </Stack>
+</Card>
+```
+
+```tsx fragment — parts expose the same owners; table rows and columns are application data
+<Card>
+  <CardHeader title="Related records" titleLevel={2} />
+  <CardContent><DataTable data={rows} columns={columns} /></CardContent>
+</Card>
+```
+
+Use sibling Cards for independent subjects. Use ContentBlock inside a Card for supporting
+prose. Repeating the route heading as each Card title adds no new subject. Repeating a
+FormField label in a nested DisplayLabel creates competing names; supply the field label
+once and let FormField associate it. A FieldGroup legend names the group, so its children's
+labels should identify their distinct values. Labels on different records may repeat.
+
+```tsx fragment — each subject supplies its own application-owned facts
+<Grid columns={{ base: 1, md: 2 }}>
+  <Card title="Contact"><MetadataList items={contactFacts} /></Card>
+  <Card title="Billing"><MetadataList items={billingFacts} /></Card>
+</Grid>
+```
+
+Grid owns separation between the sibling subjects and their responsive columns. Each Card
+owns its header and body inset. For a resource browser, DataView already owns the filter/table
+frame: put a Heading and supporting Text beside that frame instead of wrapping it in another
+Card. The [resource workflow](./reference-workflows.md) demonstrates a constrained parent;
+the detail workflow demonstrates a secondary table within an independent titled subject.
+
+Keep a record's command beside that record, a page command in the page header, and a
+selected-row command in the table's bulk-action seam. Filter toolbars communicate query
+state; export and create belong in the action slots. Applications decide destructive policy,
+field-per-row arrangements and permission boundaries.
+
+For server filtering, use `filtering.filterRows: ({ data }) => [...data]` when the server
+already matched the page. DataView's default filtering is local and can remove valid server
+matches whose search fields are absent from the visible columns. Use an app-owned cursor
+footer when totals are unknown; never invent a page count. Drop to DataTable when the app
+already owns the browser shell, filters and command placement.
+
+Selector variants serve different lifecycles: SuggestionsCombobox uses the generic lookup
+hook; AsyncCombobox accepts application-owned results; ResourceCombobox owns the ready
+single-resource fetching presentation. Use `scopeKey` on SuggestionsCombobox or ResourceCombobox when workspace or permission context changes without a
+query change. It invalidates lookup results, not the controlled selection. The application
+clears a value that is invalid in the new context.
+
+```bash
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "editable section" --context=existing-surface --context=editable --explain
+node node_modules/themelia-ui/scripts/consumer/find-component.mjs "resource selector" --context=changing-scope --json
+```
+
+Context matches are positive evidence. Uncurated exports remain visible with unknown
+context coverage; they do not become recommendations by omission.
+
 ## When to wrap, compose, or contribute
 
 - **Wrap** when the product needs a stable local name or defaults around one module.