themelia-ui 3.0.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,9 +15,10 @@ 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 |
 
-A deprecated API introduced during a stable major remains available for that major with a
-named replacement and migration instructions. It is removed only in the next major unless
-security or correctness makes retaining it unsafe.
+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.
 
 A removal, a newly required member or an incompatible type change ships with a migration
 record: the [migration reference](../generated/migration.md) names each one with its

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.