themelia-ui 3.1.0 → 3.2.0

package/docs/generated/components/base--display.md

@@ -207,8 +207,8 @@ MetadataListStrings
 
 Kind: callable.
 
-A glyph in a tinted medallion. Its size comes from `--_icon-badge-size`, so a caller
-needing a smaller mark re-points the variable instead of redrawing the badge.
+A glyph in a tinted medallion. `tone` coordinates fill and glyph; `shape` chooses
+rounded or circular geometry. Internal sizing variables are not consumer overrides.
 
 ```text
 ({ icon, children, tone, shape, solid, bordered, className, ...props }: IconBadgeProps) => import("react").JSX.Element

package/docs/generated/components/base--forms.md

@@ -14,7 +14,7 @@ Assembling a form's visible structure — label, control, support text, sections
 ## Import
 
 ```tsx fragment — import-only example
-import { DirtyStateBanner } from "themelia-ui/base/forms"
+import { FormField, FormSection } from "themelia-ui/base/forms"
 ```
 
 ## Composition
@@ -135,6 +135,16 @@ Several fields sharing one label and one supporting line — a date range, a nam
 two. A real `<fieldset>` and `<legend>`, so the legend is announced when focus enters the
 group.
 
+**Use when:** Related controls sharing an announced fieldset legend.
+
+**Avoid when:** A whole independently titled subject surface.
+
+**Compose:** Use one legend for the group and distinct FormField labels for its controls.
+
+**Capabilities:** semantic fieldset legend; related editable controls.
+
+**Alternatives:** FormSection.
+
 ```text
 ({ legend, description, className, children, ...props }: FieldGroupProps) => React.JSX.Element
 ```
@@ -230,6 +240,16 @@ Kind: callable.
 
 A titled group of fields, on a card's surface.
 
+**Use when:** Editable form sections, including groups inside an existing Card.
+
+**Avoid when:** Read-only facts or a semantic fieldset with one shared legend.
+
+**Compose:** Use flat inside a surface; flat retains Card region insets. Let its title name the section and FormField name each field.
+
+**Capabilities:** editable form sections; existing surface grouping.
+
+**Alternatives:** ContentBlock, FieldGroup.
+
 ```text
 ({ title, description, actions, children, footer, surface, className, }: FormSectionProps) => import("react").JSX.Element
 ```
@@ -391,6 +411,57 @@ export default function FieldGroupExample() {
 }
 ```
 
+### Multi-section form reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useRef, useState } from "react"
+import { Card } from "themelia-ui/base/cards"
+import { ContentBlock } from "themelia-ui/base/display"
+import { FieldGroup, FormField, FormSection, FormActionsBar, SubmitStateButton } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { useFormFieldBinding, useStateFormControl, type FormControl } from "themelia-ui/forms"
+
+type Draft = { firstName: string; lastName: string; company: string }
+function BoundField({ control, name, label, error }: { control: FormControl<Draft>; name: keyof Draft; label: string; error?: string }) {
+	const field = useFormFieldBinding<string, Draft>({ control, name })
+	return <FormField label={label} error={error} hint={name === "company" ? "The name shown on invoices." : undefined}><Input required value={field.value ?? ""} onChange={event => field.onValueChange(event.target.value)} onBlur={field.onBlur} /></FormField>
+}
+
+export default function MultiSectionReference() {
+	const control = useStateFormControl<Draft>({ firstName: "Alex", lastName: "Example", company: "Example team" })
+	const [pending, setPending] = useState(false)
+	const [error, setError] = useState<string>()
+	const [rootError, setRootError] = useState<string>()
+	const [saved, setSaved] = useState(0)
+	const running = useRef(false)
+	return <Stack>
+		<Card title="Account details" description="One outer surface, editable sections with retained region insets.">
+			<form onSubmit={async event => {
+				event.preventDefault(); if (running.current) return
+				running.current = true; setPending(true); setError(undefined); setRootError(undefined)
+				try {
+					await new Promise(resolve => setTimeout(resolve, 250))
+					if (control.values.company === "offline") throw new Error("Request failed. Your values remain here.")
+					if (control.values.company.length < 3) { setError("Company must have at least three characters."); return }
+					setSaved(count => count + 1)
+				} catch (failure) { setRootError((failure as Error).message) }
+				finally { running.current = false; setPending(false) }
+			}}>
+				<Stack gap="none">
+					{rootError && <Text role="alert" type="error">{rootError}</Text>}
+					<FormSection surface="flat" title="Contact"><FieldGroup legend="Legal name" disabled={pending}><BoundField control={control} name="firstName" label="First name" /><BoundField control={control} name="lastName" label="Last name" /></FieldGroup></FormSection>
+					<FormSection surface="flat" title="Billing"><fieldset disabled={pending} style={{ border: 0, padding: 0, margin: 0 }}><BoundField control={control} name="company" label="Company" error={error} /></fieldset></FormSection>
+					<FormActionsBar leading={<Text role="status">Successful submissions {saved}</Text>}><SubmitStateButton type="submit" state={pending ? "submitting" : "idle"} strings={{ idle: "Save account" }} /></FormActionsBar>
+				</Stack>
+			</form>
+		</Card>
+		<Card title="Preferences" description="A sibling subject owns its own surface."><ContentBlock surface="plain" title="Delivery instructions"><Text>Use ContentBlock for supporting prose; FieldGroup supplies fieldset semantics for related controls.</Text></ContentBlock></Card>
+	</Stack>
+}
+```
+
 ### FormSection
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application

package/docs/generated/components/base--structure.md

@@ -30,6 +30,16 @@ outside the package and arrives through the public props, callbacks, slots, or a
 
 Kind: const.
 
+**Use when:** Equal tracks should be added as minimum-width columns fit the available panel.
+
+**Avoid when:** The design requires an explicit column count or a fixed summary rail.
+
+**Compose:** Set minColumnWidth and shared gaps. Column count follows available width; responsive gap and alignment use viewport steps.
+
+**Capabilities:** auto fit columns; minimum column width; responsive panel grid.
+
+**Alternatives:** Grid, Split.
+
 ```text
 React.ForwardRefExoticComponent<Omit<AdaptiveGridProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -58,6 +68,16 @@ Extends: `React.ComponentProps<"div">`.
 
 Kind: const.
 
+**Use when:** Intentional media or a rule must escape a known parent inset.
+
+**Avoid when:** Removing duplicate wrapper padding or hiding accidental overflow.
+
+**Compose:** Match amount to the actual inset. Shipped padding and gap pairs match; check custom themes and focus visibility.
+
+**Capabilities:** edge to edge inset escape; inline block negative margins.
+
+**Alternatives:** ContentBlock.
+
 ```text
 React.ForwardRefExoticComponent<Omit<BleedProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -81,7 +101,7 @@ Extends: `React.ComponentProps<"div">`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `amount` | no | `ResponsiveValue<StructureGap>` | How far to escape: one of the two gaps, which equal the two paddings. Match it to the<br>padding being cancelled — a surface padded by `--padding-sm` bleeds `sm` — so the two<br>move together under a density change. @default "none" |
-| `axis` | no | `BleedAxis` | Which way to escape; `both` covers every direction. Sideways is the common case: an<br>image bleeds across and keeps its vertical rhythm. |
+| `axis` | no | `BleedAxis` | Which way to escape; `both` covers every direction. Sideways is the common case: an<br>image bleeds across and keeps its vertical rhythm. @default "inline" |
 
 ### `CssLength`
 
@@ -97,6 +117,16 @@ A CSS length: a number with a unit or a percentage, or a math or `var()` express
 
 Kind: const.
 
+**Use when:** Passive siblings need an explicit responsive column count.
+
+**Avoid when:** The column count should follow how many minimum-width tracks fit, or a feature already arranges its children.
+
+**Compose:** Grid owns gaps, not child insets. It uses nearest-container thresholds when containment exists, otherwise viewport thresholds.
+
+**Capabilities:** responsive columns; grid row column gaps; nearest container width.
+
+**Alternatives:** AdaptiveGrid, Stack.
+
 ```text
 React.ForwardRefExoticComponent<Omit<GridProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -105,6 +135,16 @@ React.ForwardRefExoticComponent<Omit<GridProps, "ref"> & React.RefAttributes<HTM
 
 Kind: const.
 
+**Use when:** A direct Grid child needs a numeric span or a full row.
+
+**Avoid when:** The parent is not a Grid, or a span would exceed its current column count.
+
+**Compose:** Coordinate numeric spans with the parent columns. GridCell spans use viewport steps even when Grid uses container steps.
+
+**Capabilities:** responsive cell span; full row span.
+
+**Alternatives:** Stack.
+
 ```text
 React.ForwardRefExoticComponent<Omit<GridCellProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -117,7 +157,7 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `span` | no | `ResponsiveValue<GridSpan>` | Columns occupied. `full` spans whatever the grid currently has. |
+| `span` | no | `ResponsiveValue<GridSpan>` | Columns occupied. `full` spans whatever the grid currently has, including in a<br>responsive object. Span breakpoints follow the viewport, not Grid's container. |
 
 ### `GridColumns`
 
@@ -135,7 +175,7 @@ Extends: `React.ComponentProps<"div">`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `columns` | no | `ResponsiveValue<GridColumns>` | Defaults to one column, then two from the md breakpoint. |
+| `columns` | no | `ResponsiveValue<GridColumns>` | Defaults to one column, then two from md. Uses the nearest inline-size query<br>container when present (md = 32rem), otherwise the viewport (md = 48rem). |
 | `gap` | no | `ResponsiveValue<StructureGap>` |  |
 | `rowGap` | no | `ResponsiveValue<StructureGap>` |  |
 | `columnGap` | no | `ResponsiveValue<StructureGap>` |  |
@@ -164,6 +204,16 @@ T | Partial<Record<Breakpoint, T>>
 
 Kind: const.
 
+**Use when:** A fluid main region sits beside a constrained rail that collapses at a chosen viewport step.
+
+**Avoid when:** Needing equal tracks or the standard semantic main/aside layout.
+
+**Compose:** Supply main first and side second. side changes visual placement, not DOM order. Width is a rail maximum, with collapseBelow controlling stacking.
+
+**Capabilities:** fluid main fixed rail; responsive two columns; collapse breakpoint.
+
+**Alternatives:** TwoColumnLayout, Grid.
+
 ```text
 React.ForwardRefExoticComponent<Omit<SplitProps, "ref"> & React.RefAttributes<HTMLDivElement>>
 ```
@@ -179,7 +229,7 @@ Extends: `React.ComponentProps<"div">`.
 | `side` | no | `SplitSide` | Which visual column is the fixed one. The DOM order never changes with it: the first<br>child is the main content and the second the side on both settings, so a reader<br>tabbing through reaches the content first either way. |
 | `sideWidth` | no | `ResponsiveValue<StructureWidth \| CssLength>` | The fixed column's width — a step or any CSS length. A maximum rather than an exact<br>size, so a narrow viewport shrinks the rail instead of squeezing the content beside it<br>to nothing. @default "18rem" |
 | `gap` | no | `ResponsiveValue<StructureGap>` | Space between the two columns. @default "default" |
-| `collapseBelow` | no | `"sm" \| "md" \| "lg" \| "xl" \| "never"` | Below this breakpoint the two columns become one. `never` keeps them side by side at<br>every width. |
+| `collapseBelow` | no | `"sm" \| "md" \| "lg" \| "xl" \| "never"` | Below this breakpoint the two columns become one. `never` keeps them side by side at<br>every width. @default "md" |
 
 ### `SplitSide`
 
@@ -199,7 +249,7 @@ Kind: const.
 
 **Avoid when:** An existing component already owns the layout.
 
-**Compose:** Use shared gap and inset props; do not pin local pixel spacing.
+**Compose:** Use gap, direction and alignment props; Stack adds no inset. Let child surfaces own padding.
 
 **Capabilities:** vertical horizontal gap spacing; responsive arrangement.
 
@@ -751,6 +801,7 @@ export default function GridExample() {
 			<GridCell><Box>three</Box></GridCell>
 			<GridCell span={{ base: 1, md: 2 }}><Box>span 2 from md</Box></GridCell>
 			<GridCell><Box>four</Box></GridCell>
+			<GridCell span={{ base: 1, md: "full", xl: 2 }}><Box>responsive full row</Box></GridCell>
 		</Grid>
 	)
 }

package/docs/generated/components/base--typography.md

@@ -427,6 +427,44 @@ export default function RolesBlueprint() {
 }
 ```
 
+### Website content reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { PillRadioGroup } from "themelia-ui/base/choice-inputs"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { RichText, Text } from "themelia-ui/base/typography"
+import { MediaLibraryDialog, type MediaLibraryItem } from "themelia-ui/features/media-library"
+import { RichTextEditor } from "themelia-ui/features/rich-text-editor"
+import { SAMPLE_MEDIA } from "../media-library/reference-data"
+
+export default function WebsiteContentReference() {
+	const [locale, setLocale] = useState("en")
+	const [drafts, setDrafts] = useState<Record<string, string>>({ en: "<p>Welcome to our workspace.</p>", ar: "<p>مرحباً بكم</p>" })
+	const [mediaOpen, setMediaOpen] = useState(false)
+	const [image, setImage] = useState<MediaLibraryItem>()
+	const [alt, setAlt] = useState("")
+	const [failed, setFailed] = useState(true)
+	const [pending, setPending] = useState(false)
+	const [message, setMessage] = useState("Drafts are local until saved")
+	return <Card title="Website content" description="Each locale owns a retained draft. Preview sanitizes HTML; the application also validates and sanitizes persisted content.">
+		<Stack>
+			<PillRadioGroup aria-label="Content locale" name="reference-content-locale" value={locale} onValueChange={value => value && setLocale(value)} options={[{ value: "en", label: "English" }, { value: "ar", label: "العربية" }]} />
+			<div dir={locale === "ar" ? "rtl" : "ltr"}><RichTextEditor value={drafts[locale] ?? ""} onValueChange={html => setDrafts(current => ({ ...current, [locale]: html }))} /></div>
+			<MediaLibraryDialog open={mediaOpen} trigger={<Button tone="neutral" appearance="outline">Choose hero media</Button>} onOpenChange={setMediaOpen} items={SAMPLE_MEDIA} selectionMode="single" confirmOnSelect allowUpload={false} onConfirm={items => { const item = items[0]; setImage(item); setAlt(item?.alt ?? ""); setMediaOpen(false) }} />
+			{image && <FormField label="Hero image alternative text" hint={image.name}><Input value={alt} onChange={event => setAlt(event.target.value)} /></FormField>}
+			<Stack direction="horizontal" wrap gap="sm"><Button disabled={pending} onClick={async () => { if (pending) return; setPending(true); await new Promise(resolve => setTimeout(resolve, 250)); setMessage(failed ? "Save failed. All locale drafts and image text remain here." : "Mock website save completed"); setPending(false) }}>Save website content</Button><Button tone="neutral" appearance="outline" onClick={() => setFailed(value => !value)}>Toggle save failure</Button></Stack>
+			<Text role="status">{message}</Text>
+			<RichText html={drafts[locale] ?? ""} />
+		</Stack>
+	</Card>
+}
+```
+
 ### The editor and what comes out
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application

package/docs/generated/components/blocks--admin--access.md

@@ -118,6 +118,16 @@ Kind: interface.
 
 Kind: callable.
 
+**Use when:** A read-only role permission summary grouped by product area.
+
+**Avoid when:** Editing permission values or enforcing authorization.
+
+**Compose:** Supply roleName and grouped permission records. The app computes authorization and owns the edit callback; the block supplies visible and accessible state presentation.
+
+**Capabilities:** role permissions; permission summary; granted denied access facts.
+
+**Alternatives:** Table, FormSection.
+
 ```text
 ({ roleName, description, memberCount, groups, onEdit, strings, className, ...props }: RolePermissionsProps) => import("react").JSX.Element
 ```

package/docs/generated/components/blocks--analytics.md

@@ -161,6 +161,16 @@ Kind: callable.
 
 Kind: callable.
 
+**Use when:** One quantitative measure needs value hierarchy and optional comparison, trend or progress.
+
+**Avoid when:** An ordinary fact or a group that MetricGrid already arranges.
+
+**Compose:** Read MetricProps for state and surface variants; they are not shared by every analytics export. The analytics module requires recharts.
+
+**Capabilities:** single quantitative measure; metric comparison trend.
+
+**Alternatives:** MetricGrid, MetadataList.
+
 ```text
 ({ data, variant, tone, showSparkline, showChange, showIcon, loading, error, strings, progress, className, ...props }: MetricProps) => import("react").JSX.Element
 ```
@@ -318,6 +328,16 @@ Four pairs off the categorical ramp. Named for the look, not for a meaning.
 
 Kind: callable.
 
+**Use when:** Several quantitative measures need responsive tiles with comparison or trend.
+
+**Avoid when:** Ordinary label/value facts, identifiers or prose summaries.
+
+**Compose:** Pass MetricData and the period context. Use null for an unavailable quantity, zero for measured zero. The module requires recharts and already owns tile arrangement.
+
+**Capabilities:** quantitative metrics; dashboard figures; responsive metric tiles.
+
+**Alternatives:** Metric, MetadataList.
+
 ```text
 ({ metrics, variant, tone, columns, showSparklines, showChanges, showIcons, loading, className, ...props }: MetricGridProps) => import("react").JSX.Element
 ```
@@ -569,6 +589,30 @@ Kind: interface.
 
 Preview route: Analytics — `/analytics`
 
+### Communications overview reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Card } from "themelia-ui/base/cards"
+import { MetadataList } from "themelia-ui/base/display"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { MetricGrid } from "themelia-ui/blocks/analytics"
+
+export default function CommunicationsReference() {
+	const [retried, setRetried] = useState(false)
+	return <Stack>
+		<MetricGrid metrics={[{ id: "delivered", label: "Messages delivered during the selected reporting period", value: 128, valueType: "number" }, { id: "retry", label: "Messages awaiting retry", value: retried ? 0 : 3, valueType: "number" }]} variant="card" />
+		<Card title="Latest communication" headerAction={<Button disabled={retried} onClick={() => setRetried(true)}>Retry delivery</Button>}>
+			<MetadataList items={[{ id: "subject", label: "Subject", value: "Workspace invitation" }, { id: "status", label: "Delivery state", value: retried ? "Delivered" : "Retry available" }, { id: "recipient", label: "Recipient", value: "member@example.test" }, { id: "time", label: "Last attempt", value: { kind: "datetime", value: "2026-09-01T09:30:00Z" } }, { id: "opened", label: "Opened", value: "Unknown; tracking unavailable" }]} />
+			<Text>The application owns delivery policy and permission checks. Metrics describe quantities; this subject and its delivery facts stay in a record surface.</Text>
+		</Card>
+		<Text role="status">{retried ? "Mock retry completed" : "Mock delivery is waiting"}</Text>
+	</Stack>
+}
+```
+
 ### Metric bar
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application

package/docs/generated/components/features--combobox.md

@@ -228,6 +228,16 @@ Browsable from the first keystroke, and preloaded on mount so the list is there
 failed fetch replaces the list content, as `AsyncCombobox`'s `showListContent` does when
 off, but keeps the selection and the query, for retry.
 
+**Use when:** Resource selection with self-owned debounce, abort and scoped requests.
+
+**Avoid when:** An existing application query/cache already owns lookup results.
+
+**Compose:** Change scopeKey when workspace/tenant/parent changes; preserve query/open state and explicitly clear an invalid controlled selection.
+
+**Capabilities:** resource selection; scoped resource lookup; pending empty error retry.
+
+**Alternatives:** AsyncCombobox, SuggestionsCombobox.
+
 ```text
 ({ fetcher, onAfterFetch, onError, getKey, getLabel, limit, debounceMs, preload, minSearchLength, defaultValue, errorMessage, ...props }: ResourceComboboxProps<T>) => import("react").JSX.Element
 ```
@@ -280,6 +290,7 @@ Extends: `Omit<AsyncComboboxProps<T>, "items" | "selectedValue" | "onSelectedVal
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `fetcher` | yes | `ResourceComboboxFetcher<T>` | Fetches the options for a query. Debounce, abort, and the race guard are owned for you,<br>and the query arrives trimmed. Honour `signal`, so an abort does not surface as a failure. |
+| `scopeKey` | no | `string \| number` | Resource scope identity. A change aborts stale lookups and refetches the current<br>eligible query. The application owns clearing a selection invalid in the new scope. |
 | `value` | no | `T \| null` | Controlled. Omit entirely to let the component own the selection. |
 | `defaultValue` | no | `T \| null` | The starting selection when uncontrolled. Ignored once `value` is passed. |
 | `onValueChange` | no | `(value: T \| null) => void` |  |
@@ -438,6 +449,7 @@ Kind: interface.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `fetchData` | yes | `(query: string, context?: SuggestionsFetchContext) => MaybePromise<T[]>` | Fetches the suggestions for a query, as an array or a promise of one. Pass<br>`context.signal` to the request: it aborts when a newer query starts. |
+| `scopeKey` | no | `string \| number` | Identity of the resource scope (workspace, tenant or parent record). Changing it<br>aborts previous work, hides its results/errors and immediately refetches an eligible<br>query. Compared with Object.is; callback identity alone never refetches. Selection,<br>query and open state survive: the application clears selections invalid in the new scope. |
 | `minQueryLength` | no | `number` | Characters required before a request is issued, not counting surrounding whitespace.<br>Defaults to 1. |
 | `debounceMs` | no | `number` | The quiet period that collapses a burst of typing into one request. Defaults to 300. |
 | `requestDelay` | no | `number` | A further wait before the fetcher runs, after the loading state is showing (unlike<br>`debounceMs`, which delays deciding to fetch). For rate-limited endpoints. @default 0 |
@@ -475,6 +487,61 @@ Kind: interface.
 
 Preview route: Combobox — `/combobox`
 
+### Scoped resource selection
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { FormField } from "themelia-ui/base/forms"
+import { Overlay, OverlayTrigger, OverlayContent, OverlayHeader, OverlayTitle, OverlayDescription, OverlayBody } from "themelia-ui/base/overlay"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { ResourceCombobox } from "themelia-ui/features/combobox"
+
+type Resource = { id: string; label: string }
+type Mode = "results" | "pending" | "empty" | "error"
+
+export default function ScopedResourceReference() {
+	const [scope, setScope] = useState("A")
+	const [mode, setMode] = useState<Mode>("results")
+	const [query, setQuery] = useState("")
+	const [value, setValue] = useState<Resource | null>({ id: "A-1", label: "A project" })
+	const [selections, setSelections] = useState(0)
+	const [submissions, setSubmissions] = useState(0)
+	const [completions, setCompletions] = useState(0)
+	return <Overlay>
+		<OverlayTrigger render={<Button />}>Choose scoped resource</OverlayTrigger>
+		<OverlayContent>
+			<OverlayHeader><OverlayTitle>Assign resource</OverlayTitle><OverlayDescription>Lookup validity belongs to a workspace. The application decides whether a selected resource remains valid.</OverlayDescription></OverlayHeader>
+			<OverlayBody>
+				<form onSubmit={event => { event.preventDefault(); setSubmissions(count => count + 1) }}>
+					<Stack>
+						<Stack direction="horizontal" gap="sm" wrap>
+							{["A", "B"].map(key => <Button key={key} tone="neutral" appearance="outline" onClick={() => { setScope(key); setValue(null) }}>Workspace {key}</Button>)}
+						</Stack>
+						<Stack direction="horizontal" gap="sm" wrap>
+							{(["results", "pending", "empty", "error"] as const).map(key => <Button key={key} tone="neutral" appearance="ghost" onClick={() => setMode(key)}>{key}</Button>)}
+						</Stack>
+						<FormField label="Resource" hint={`Searching workspace ${scope}`}>
+							<ResourceCombobox<Resource> scopeKey={`${scope}:${mode}`} value={value} onValueChange={next => { setValue(next); setSelections(count => count + 1) }} searchValue={query} onSearchValueChange={setQuery} debounceMs={100} getKey={item => item.id} getLabel={item => item.label}
+								fetcher={async ({ query: search, signal }) => {
+									// The mock deliberately ignores abort; the picker must suppress its late answer.
+									void signal
+									await new Promise(resolve => setTimeout(resolve, mode === "pending" ? 2400 : scope === "A" ? 600 : 80))
+									if (mode === "error") throw new Error("Lookup unavailable")
+									return mode === "empty" || (search && !"project".includes(search.toLowerCase())) ? [] : [{ id: `${scope}-1`, label: `${scope} project` }]
+								}} onAfterFetch={() => setCompletions(count => count + 1)} />
+						</FormField>
+						<Button type="submit">Assign</Button>
+						<Text role="status">Selections {selections}; submissions {submissions}; completions {completions}</Text>
+					</Stack>
+				</form>
+			</OverlayBody>
+		</OverlayContent>
+	</Overlay>
+}
+```
+
 ### A picker that fetches
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application

package/docs/generated/components/features--data-view.md

@@ -2,12 +2,12 @@
 
 # `features/data-view`
 
-One dataset is presented through switchable views with saved tabs, a toolbar and pagination.
+A resource collection needs search, filters, saved views, table controls and paging.
 
 ## Selection
 
-- **Use when:** One dataset is presented through switchable views with saved tabs, a toolbar and pagination.
-- **Avoid when:** There is one table and no view switching, or you need the table body alone.
+- **Use when:** A resource collection needs search, filters, saved views, table controls and paging.
+- **Avoid when:** Only tabular behavior is needed inside an existing application-owned browser shell.
 - **Consider instead:** `features/table`, `base/table`
 - **Stability:** stable.
 
@@ -365,6 +365,62 @@ Kind: interface.
 
 Preview route: Data view & data table — `/data-view`
 
+### Server resource index reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useEffect, useRef, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Heading, Text } from "themelia-ui/base/typography"
+import { DataView, type DataViewProps } from "themelia-ui/features/data-view"
+import { FilterType, type ActiveFilter, type FilterConfig } from "themelia-ui/features/filters"
+
+type RecordRow = { id: string; name: string; status: string; searchTerms: string }
+const RECORDS: RecordRow[] = Array.from({ length: 6 }, (_, index) => ({ id: `r${index + 1}`, name: `Resource ${index + 1}`, status: index % 2 ? "Closed" : "Open", searchTerms: "hidden reference term" }))
+const COLUMNS: DataViewProps<RecordRow>["columns"] = [{ accessorKey: "name", header: "Resource" }, { accessorKey: "status", header: "Status" }]
+const FILTERS: FilterConfig[] = [{ key: "search", label: "Search hidden metadata and resource names", type: FilterType.SEARCH }, { key: "status", label: "Publication and review status with a long translated label", type: FilterType.SELECT, options: [{ value: "Open", label: "Open" }, { value: "Closed", label: "Closed" }] }]
+
+export default function ResourceIndexReference() {
+	const [filters, setFilters] = useState<ActiveFilter[]>([])
+	const [page, setPage] = useState(0)
+	const [rows, setRows] = useState<RecordRow[]>([])
+	const [hasNext, setHasNext] = useState(false)
+	const [pending, setPending] = useState(true)
+	const [error, setError] = useState<string>()
+	const [refresh, setRefresh] = useState(0)
+	const [selection, setSelection] = useState<Record<string, true>>({})
+	const [answeredQuery, setAnsweredQuery] = useState("")
+	const [commands, setCommands] = useState("")
+	const failNext = useRef(false)
+	useEffect(() => {
+		let active = true
+		async function load() {
+			setPending(true); setError(undefined)
+			await new Promise(resolve => setTimeout(resolve, 250))
+			if (!active) return
+			if (failNext.current) { failNext.current = false; setError("Refresh failed. Previous rows remain available."); setPending(false); return }
+			const search = filters.find(filter => filter.key === "search")?.value[0]?.toLowerCase() ?? ""
+			const status = filters.find(filter => filter.key === "status")?.value[0]
+			const matches = RECORDS.filter(row => `${row.name} ${row.searchTerms}`.toLowerCase().includes(search) && (!status || row.status === status))
+			setAnsweredQuery(search); setRows(matches.slice(page * 2, page * 2 + 2)); setHasNext(matches.length > page * 2 + 2); setPending(false)
+		}
+		void load()
+		return () => { active = false }
+	}, [filters, page, refresh])
+	return <div style={{ width: "100%", minWidth: 0, maxWidth: "48rem" }}>
+		<Stack>
+			<Heading level={3}>Resource index</Heading>
+			<Text type="secondary">Server matching includes fields absent from the visible columns. Totals are unknown; selection applies to the current page.</Text>
+			{error && <Text role="alert" type="error">{error}</Text>}
+			<DataView data={rows} columns={COLUMNS} filtering={{ filters: FILTERS, activeFilters: filters, onFilterChange: next => { setFilters(next); setPage(0); setSelection({}) }, filterRows: ({ data }) => [...data], isFiltering: pending }}
+				table={{ enableColumnVisibility: true, enableRowSelection: true, getRowId: row => row.id, rowSelection: selection, onRowSelectionChange: setSelection, bulkActions: ({ selectedRows }) => <Button onClick={() => setCommands(`Selected-page command: ${selectedRows.map(row => row.id).join(", ")}`)}>Archive selected page rows</Button> }}
+				slots={{ topbarEnd: <Stack direction="horizontal" gap="sm" wrap><Button tone="neutral" appearance="outline" disabled={pending} onClick={() => setRefresh(count => count + 1)}>Refresh</Button><Button tone="neutral" appearance="outline" onClick={() => { failNext.current = true; setRefresh(count => count + 1) }}>Fail next refresh</Button><Button tone="neutral" appearance="outline" onClick={() => setCommands(`Export current page: ${rows.map(row => row.id).join(", ")}`)}>Export page</Button></Stack>, footer: <Stack direction="horizontal" wrap align="center"><Text>Total unknown; page {page + 1}</Text><Button disabled={pending || page === 0} onClick={() => { setPage(value => value - 1); setSelection({}) }}>Previous page</Button><Button disabled={pending || !hasNext} onClick={() => { setPage(value => value + 1); setSelection({}) }}>Next page</Button></Stack> }} />
+			<Text role="status">{pending ? "Loading page" : `${rows.length} rows supplied by server; matched ${answeredQuery || "all"}`}{commands && `; ${commands}`}</Text>
+		</Stack>
+	</div>
+}
+```
+
 ### An index
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application

package/docs/generated/components/features--filters.md

@@ -292,6 +292,16 @@ Kind: callable.
 The default bar: saved tabs, search boxes, active pills, always-shown pills, the add button,
 then Clear. For a custom bar, place the exported parts using `useFilterGroups()`.
 
+**Use when:** Responsive filter controls shared between a desktop region and mobile sheet.
+
+**Avoid when:** A complete resource browser already provides its filter layout, or the controls are page commands.
+
+**Compose:** Share controlled filter state across presentations. Place create and export in action slots outside filter controls.
+
+**Capabilities:** responsive filters; mobile sheet desktop filter region.
+
+**Alternatives:** —.
+
 ```text
 ({ className, dynamicFilterOptions, loadingFilters, variant, showClearFilters, tabs, mobilePresentation, }: FilterLayoutProps) => import("react").JSX.Element
 ```