themelia-ui 3.0.0 → 3.2.0

package/docs/generated/components/features--media-library.md

@@ -15,7 +15,6 @@ Existing assets are browsed, previewed, searched and picked.
 
 ```tsx fragment — import-only example
 import { MediaLibrary } from "themelia-ui/features/media-library"
-import "themelia-ui/features/media-library.css"
 ```
 
 ## Composition
@@ -59,7 +58,7 @@ The asset browser, as a panel. The detail panel is a column beside the grid, not
 so several assets can be edited in a row.
 
 ```text
-({ title, description, confirmLabel, cancelLabel, density, showMeta, allowUpload, typeFilters, confirmOnSelect, onConfirm, onCancel, onClose, bulkActions, strings, slots, className, collections, selectionMode, ...options }: MediaLibraryProps<TItem>) => import("react").JSX.Element
+({ title, description, confirmLabel, cancelLabel, size, showMeta, allowUpload, typeFilters, confirmOnSelect, onConfirm, onCancel, onClose, bulkActions, strings, slots, className, collections, selectionMode, ...options }: MediaLibraryProps<TItem>) => import("react").JSX.Element
 ```
 
 ### `MediaLibraryAccessors`
@@ -107,7 +106,7 @@ Kind: callable.
 One asset in the grid, with its preview, name and selection control.
 
 ```text
-({ item, selected, density, showMeta, accessors, strings, onToggle, onDetails, className, }: MediaLibraryCardProps<TItem>) => import("react").JSX.Element
+({ item, selected, size, showMeta, accessors, strings, onToggle, onDetails, className, }: MediaLibraryCardProps<TItem>) => import("react").JSX.Element
 ```
 
 ### `MediaLibraryCardProps`
@@ -118,7 +117,7 @@ Kind: interface.
 | --- | :-: | --- | --- |
 | `item` | yes | `TItem` |  |
 | `selected` | no | `boolean` |  |
-| `density` | no | `MediaLibraryDensity` |  |
+| `size` | no | `MediaLibrarySize` | Tile size: `sm` fits more tiles in a row. |
 | `showMeta` | no | `boolean` |  |
 | `selectionMode` | no | `MediaLibrarySelectionMode` |  |
 | `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
@@ -136,14 +135,6 @@ Kind: interface.
 | `value` | yes | `string` |  |
 | `label` | yes | `ReactNode` |  |
 
-### `MediaLibraryDensity`
-
-Kind: type.
-
-```text
-"comfortable" | "compact"
-```
-
 ### `MediaLibraryDetailPanel`
 
 Kind: callable.
@@ -351,7 +342,7 @@ The composable visual grid. Like the list and the table, it uses the same access
 selection callbacks.
 
 ```text
-({ items, selectedSet, accessors, strings, onToggle, onDetails, density, selectionMode, showMeta, renderItem, className }: MediaLibraryGridProps<TItem>) => import("react").JSX.Element
+({ items, selectedSet, accessors, strings, onToggle, onDetails, size, selectionMode, showMeta, renderItem, className }: MediaLibraryGridProps<TItem>) => import("react").JSX.Element
 ```
 
 ### `MediaLibraryGridProps`
@@ -362,7 +353,7 @@ Extends: `MediaLibraryListProps<TItem>`.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `density` | no | `MediaLibraryDensity` |  |
+| `size` | no | `MediaLibrarySize` | Tile size: `sm` fits more tiles in a row. |
 | `showMeta` | no | `boolean` |  |
 | `renderItem` | no | `MediaLibrarySlots<TItem>["renderItem"]` |  |
 | `className` | no | `string` |  |
@@ -463,7 +454,7 @@ Extends: `Omit<ComponentPropsWithoutRef<"section">, "children" | "defaultValue"
 | `description` | no | `ReactNode` |  |
 | `confirmLabel` | no | `ReactNode` |  |
 | `cancelLabel` | no | `ReactNode` |  |
-| `density` | no | `MediaLibraryDensity` |  |
+| `size` | no | `MediaLibrarySize` | Tile size: `sm` fits more tiles in a row. |
 | `showMeta` | no | `boolean` | Shows each asset's size and dimensions under its name. |
 | `allowUpload` | no | `boolean` |  |
 | `typeFilters` | no | `readonly MediaLibraryTypeFilter[]` | The type filters the toolbar offers. A single type filter draws no control. |
@@ -510,6 +501,14 @@ Kind: type.
 "single" | "multiple"
 ```
 
+### `MediaLibrarySize`
+
+Kind: type.
+
+```text
+"default" | "sm"
+```
+
 ### `MediaLibrarySlots`
 
 Kind: interface.
@@ -578,13 +577,13 @@ Kind: interface.
 | `selectedSet` | yes | `Set<string>` | For a per-row lookup that would otherwise be O(n) inside a map. |
 | `toggleSelection` | yes | `(id: string) => void` |  |
 | `clearSelection` | yes | `() => void` |  |
-| `selectVisible` | no | `() => void` | Select/deselect only the currently visible records, preserving other selections. |
-| `deselectVisible` | no | `() => void` |  |
+| `selectVisible` | yes | `() => void` | Select/deselect only the currently visible records, preserving other selections. |
+| `deselectVisible` | yes | `() => void` |  |
 | `clearFilters` | yes | `() => void` |  |
 | `loading` | yes | `boolean` |  |
 | `error` | yes | `unknown` | Most recent fetch or mutation failure; cleared when an operation starts. |
-| `fetchError` | no | `unknown` | Always supplied by useMediaLibrary; optional for existing consumer-owned states. |
-| `refetch` | no | `() => void` | Stable query reload, always supplied by useMediaLibrary; a no-op in local mode. |
+| `fetchError` | yes | `unknown` | Fetch failure, separate from mutation failures. |
+| `refetch` | yes | `() => void` | Stable query reload; a no-op in local mode. |
 | `hasFilters` | yes | `boolean` |  |
 | `totalCount` | yes | `number` |  |
 | `filteredCount` | yes | `number` |  |
@@ -610,11 +609,11 @@ Kind: interface.
 | `title` | yes | `string` |  |
 | `description` | yes | `string` |  |
 | `tabs` | yes | `{ library: string; upload: string; }` |  |
-| `views` | yes | `{ grid: string; table: string; list?: string; }` |  |
-| `selectVisible` | no | `string` |  |
-| `deselectVisible` | no | `string` |  |
-| `refreshError` | no | `string` |  |
-| `table` | no | `{ name: string; collection: string; size: string; uploaded: string; usage: string; actions: string; }` |  |
+| `views` | yes | `{ grid: string; table: string; list: string; }` |  |
+| `selectVisible` | yes | `string` |  |
+| `deselectVisible` | yes | `string` |  |
+| `refreshError` | yes | `string` |  |
+| `table` | yes | `{ name: string; collection: string; size: string; uploaded: string; usage: string; actions: string; }` |  |
 | `searchPlaceholder` | yes | `string` |  |
 | `clearSearch` | yes | `string` |  |
 | `clearFilters` | yes | `string` |  |
@@ -628,7 +627,7 @@ Kind: interface.
 | `activeSearchLabel` | yes | `string` |  |
 | `loading` | yes | `string` |  |
 | `error` | yes | `string` |  |
-| `retry` | no | `string` | Optional so existing complete translations keep working; defaults to "Try again". |
+| `retry` | yes | `string` |  |
 | `emptyTitle` | yes | `string` |  |
 | `emptyDescription` | yes | `string` |  |
 | `emptyFilteredTitle` | yes | `string` |  |
@@ -637,14 +636,14 @@ Kind: interface.
 | `showingCount` | yes | `(shown: number, total: number) => string` |  |
 | `select` | yes | `string` |  |
 | `deselect` | yes | `string` |  |
-| `assetAction` | no | `(action: string, name: string) => string` |  |
+| `assetAction` | yes | `(action: string, name: string) => string` |  |
 | `details` | yes | `string` |  |
 | `close` | yes | `string` |  |
 | `confirm` | yes | `string` |  |
 | `cancel` | yes | `string` |  |
 | `clearSelection` | yes | `string` |  |
 | `footer` | yes | `{ pickOne: string; pickMany: string; noFiles: string; stagedSummary: (count: number, size: string) => string; uploadStaged: (count: number) => string; }` | The picker's footer, which changes with the tab it is under. |
-| `detail` | yes | `{ altLabel: string; altPlaceholder: string; collectionLabel: string; tagsLabel: string; tagsPlaceholder: string; publicLabel: string; publicDescription: string; save: string; saving: string; delete: string; deleting: string; saved?: string; unsaved?: string; saveFailed?: string; deleteFailed?: string; reset?: string; dimensions: string; size: string; uploaded: string; type: string; }` |  |
+| `detail` | yes | `{ altLabel: string; altPlaceholder: string; collectionLabel: string; tagsLabel: string; tagsPlaceholder: string; publicLabel: string; publicDescription: string; save: string; saving: string; delete: string; deleting: string; saved: string; unsaved: string; saveFailed: string; deleteFailed: string; reset: string; dimensions: string; size: string; uploaded: string; type: string; }` |  |
 | `upload` | yes | `{ dropTitle: string; dropDescription: string; browse: string; staged: (count: number) => string; start: string; uploading: string; cancel: string; clear: string; remove: string; failed: string; emptyTitle: string; emptyDescription: string; optionsTitle: string; }` |  |
 | `gallery` | yes | `{ title: string; description: string; add: string; remove: string; primary: string; makePrimary: string; moveEarlier: string; moveLater: string; emptyTitle: string; emptyDescription: string; limitReached: (max: number) => string; }` |  |
 
@@ -820,7 +819,7 @@ The assets attached to a record, in order — with reorder, cover, and detach. N
 works with keyboard, screen reader and touch.
 
 ```text
-({ items, accessors: accessorsProp, title, description, primaryId, onPrimaryChange, onRemove, onReorder, onAdd, maxItems, layout, density, readOnly, empty, action, renderItem, strings, className, ...props }: MediaResourceGalleryProps<TItem>) => import("react").JSX.Element
+({ items, accessors: accessorsProp, title, description, primaryId, onPrimaryChange, onRemove, onReorder, onAdd, maxItems, layout, size, readOnly, empty, action, renderItem, strings, className, ...props }: MediaResourceGalleryProps<TItem>) => import("react").JSX.Element
 ```
 
 ### `MediaResourceGalleryItemRenderContext`
@@ -868,7 +867,7 @@ Extends: `Omit<ComponentPropsWithoutRef<"section">, "children" | "title">`.
 | `onAdd` | no | `() => void` | Usually opens the library dialog. |
 | `maxItems` | no | `number` | The add control hides once reached. |
 | `layout` | no | `MediaResourceGalleryLayout` |  |
-| `density` | no | `MediaLibraryDensity` |  |
+| `size` | no | `MediaLibrarySize` | Tile size: `sm` fits more tiles in a row. |
 | `readOnly` | no | `boolean` |  |
 | `empty` | no | `ReactNode` |  |
 | `action` | no | `ReactNode` |  |
@@ -900,7 +899,7 @@ clearing filters or selection; `fetchError` identifies fetch failures separately
 mutation errors.
 
 ```text
-({ items: itemsProp, fetcher, accessors: accessorsProp, selectionMode, value, defaultValue, onValueChange, onItemUpdate, applyItemPatch, onItemDelete, onUpload, onError, tab: tabProp, defaultTab, onTabChange, view: viewProp, defaultView, onViewChange, query: queryProp, defaultQuery, onQueryChange, type: typeProp, defaultType, onTypeChange, collection: collectionProp, defaultCollection, onCollectionChange, sort: sortProp, defaultSort, onSortChange, uploadOptions: uploadOptionsProp, defaultUploadOptions, onUploadOptionsChange, }: UseMediaLibraryOptions<TItem>) => ResolvedMediaLibraryState<TItem>
+({ items: itemsProp, fetcher, accessors: accessorsProp, selectionMode, value, defaultValue, onValueChange, onItemUpdate, applyItemPatch, onItemDelete, onUpload, onError, tab: tabProp, defaultTab, onTabChange, view: viewProp, defaultView, onViewChange, query: queryProp, defaultQuery, onQueryChange, type: typeProp, defaultType, onTypeChange, collection: collectionProp, defaultCollection, onCollectionChange, sort: sortProp, defaultSort, onSortChange, uploadOptions: uploadOptionsProp, defaultUploadOptions, onUploadOptionsChange, }: UseMediaLibraryOptions<TItem>) => MediaLibraryState<TItem>
 ```
 
 ### `UseMediaLibraryOptions`
@@ -948,6 +947,74 @@ Kind: interface.
 
 Preview route: Media library — `/media-library`
 
+### Media picking reference
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useEffect, useMemo, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { MediaLibraryDialog, type MediaLibraryItem, type MediaLibraryFetcher } from "themelia-ui/features/media-library"
+
+import { SAMPLE_MEDIA } from "./reference-data"
+
+export default function MediaPickingReference() {
+	const [open, setOpen] = useState(false)
+	const [scope, setScope] = useState("site")
+	const [fail, setFail] = useState(false)
+	const [selected, setSelected] = useState<string[]>(["unavailable-id"])
+	const [pickerDraft, setPickerDraft] = useState(selected)
+	const [resolved, setResolved] = useState<{ scope: string; ids: string[]; items: MediaLibraryItem[] }>()
+	const [page, setPage] = useState(0)
+	const [query, setQuery] = useState("")
+	const [pending, setPending] = useState(true)
+	const [hasNext, setHasNext] = useState(false)
+	// A saved id is resolved separately from the current browser page, with scope access applied.
+	useEffect(() => {
+		const controller = new AbortController()
+		const timer = setTimeout(() => {
+			if (!controller.signal.aborted) setResolved({ scope, ids: selected, items: SAMPLE_MEDIA.filter(item => selected.includes(item.id) && item.collection === scope) })
+		}, 150)
+		return () => { controller.abort(); clearTimeout(timer) }
+	}, [selected, scope])
+	const chosen = resolved?.scope === scope && resolved.ids === selected ? resolved.items : []
+	const unavailable = resolved?.scope === scope && resolved.ids === selected && chosen.length < selected.length
+	const changeOpen = (next: boolean) => {
+		if (next) setPickerDraft(selected)
+		setOpen(next)
+	}
+	const fetcher = useMemo<MediaLibraryFetcher>(() => async ({ query: search, signal }) => {
+		setPending(true)
+		try {
+			await new Promise(resolve => setTimeout(resolve, 200))
+			if (signal?.aborted) throw new DOMException("Aborted", "AbortError")
+			if (fail) throw new Error("Media lookup unavailable")
+			const matches = SAMPLE_MEDIA.filter(item => item.collection === scope && item.name.toLowerCase().includes(search.toLowerCase()))
+			const window = matches.slice(page, page + 2)
+			setHasNext(window.length > 1)
+			return { items: window.slice(0, 1) }
+		} finally { if (!signal?.aborted) setPending(false) }
+	}, [scope, fail, page])
+	return <Stack>
+		{unavailable && <Text role="alert">The saved asset is unavailable. Choose a replacement; the draft id is retained until then.</Text>}
+		<Stack direction="horizontal" gap="sm" wrap>
+			<MediaLibraryDialog open={open} trigger={<Button>Choose reference media</Button>} onOpenChange={changeOpen} fetcher={fetcher} value={pickerDraft} onValueChange={setPickerDraft} query={query} onQueryChange={next => { setQuery(next); setPage(0); setPending(true) }} selectionMode="single" allowUpload={false}
+				strings={{ showingCount: shown => `${shown} loaded on this page; total unknown` }}
+				slots={{ footer: <Stack direction="horizontal" gap="sm" wrap align="center">
+					<Text>Media page {page + 1}; total unknown</Text>
+					<Button disabled={pending || page === 0} onClick={() => { setPage(value => value - 1); setPending(true) }}>Previous media page</Button>
+					<Button disabled={pending || !hasNext} onClick={() => { setPage(value => value + 1); setPending(true) }}>Next media page</Button>
+				</Stack> }}
+				onConfirm={(items, ids) => { setSelected(ids); setResolved({ scope, ids, items }); setOpen(false) }} />
+			<Button tone="neutral" appearance="outline" onClick={() => setSelected(["image-2"])}>Load saved media draft</Button>
+			<Button tone="neutral" appearance="outline" onClick={() => { setScope(value => value === "site" ? "other" : "site"); setPage(0); setPending(true) }}>Switch media scope</Button>
+			<Button tone="neutral" appearance="outline" onClick={() => { setFail(value => !value); setPending(true) }}>Toggle media failure</Button>
+		</Stack>
+		<Text role="status">{chosen.length ? `Hydrated selection: ${chosen.map(item => `${item.name} — ${item.alt}`).join(", ")}` : `Saved draft ids: ${selected.join(", ")}`}</Text>
+	</Stack>
+}
+```
+
 ### Asset manager
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -996,7 +1063,7 @@ export default function Library() {
 				onConfirm={(items) => setNote(`using ${items.length}`)}
 			/>
 			<Stack direction="horizontal" align="center" gap="sm" wrap>
-				<Button tone="neutral" buttonStyle="outline" onClick={() => { failNext.current = true; setNote("The next save, delete, or upload will fail once.") }}>
+				<Button tone="neutral" appearance="outline" onClick={() => { failNext.current = true; setNote("The next save, delete, or upload will fail once.") }}>
 					Fail next action
 				</Button>
 				<Text size="sm" type="secondary">Preview recovery without mixing test controls into the library toolbar.</Text>
@@ -1064,15 +1131,15 @@ export default function AsyncLibrary() {
 	}, [scenario])
 
 	return (
-		<Stack>
-			<Stack direction="horizontal" wrap>
-				<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => load("assets")}>
+		<Stack gap="sm">
+			<Stack gap="sm" direction="horizontal" wrap>
+				<Button type="button" tone="neutral" appearance="outline" onClick={() => load("assets")}>
 					Load sample assets
 				</Button>
-				<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => load("failure")}>
+				<Button type="button" tone="neutral" appearance="outline" onClick={() => load("failure")}>
 					Simulate failure
 				</Button>
-				<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => load("empty")}>
+				<Button type="button" tone="neutral" appearance="outline" onClick={() => load("empty")}>
 					Show empty library
 				</Button>
 			</Stack>
@@ -1125,7 +1192,7 @@ export default function BulkActions() {
 							<Button
 								type="button"
 								tone="neutral"
-								buttonStyle="ghost"
+								appearance="ghost"
 								onClick={() => {
 									setAssets((current) => current.map((asset) => selected.includes(asset.id) ? { ...asset, public: true } : asset))
 									setNote(`Made ${selectedCount} assets public`)
@@ -1137,7 +1204,7 @@ export default function BulkActions() {
 							<Button
 								type="button"
 								tone="destructive"
-								buttonStyle="ghost"
+								appearance="ghost"
 								onClick={() => {
 									setAssets((current) => current.filter((asset) => !selected.includes(asset.id)))
 									setNote(`Deleted ${selectedCount}`)

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

@@ -15,7 +15,6 @@ Typing a trigger character suggests entities and inserts them as chips.
 
 ```tsx fragment — import-only example
 import { MentionChip } from "themelia-ui/features/mentions"
-import "themelia-ui/features/mentions.css"
 ```
 
 ## Composition
@@ -492,7 +491,7 @@ import { useCallback, useImperativeHandle, useRef, useState, type Ref } from "re
 import { Button } from "themelia-ui/base/buttons"
 import { Popover, PopoverTrigger } from "themelia-ui/base/popover"
 import { Stack } from "themelia-ui/base/structure"
-import { Text } from "themelia-ui/base/typography"
+import { Text, textClassName } from "themelia-ui/base/typography"
 import {
 	MentionChip, MentionInlineSuggestions, MentionPicker, parseMentionsFromHtml, useMentions,
 	type MentionEditorHandle,
@@ -558,6 +557,7 @@ function MiniEditor({
 			ref={host}
 			contentEditable
 			suppressContentEditableWarning
+			tabIndex={0}
 			role="textbox"
 			aria-multiline
 			aria-label={placeholder}
@@ -568,7 +568,7 @@ function MiniEditor({
 				onInput(event.currentTarget.innerHTML)
 				onCaretChange()
 			}}
-			className={styles.editor}
+			className={`${styles.editor} ${textClassName({ lineHeight: "relaxed" })}`}
 		/>
 	)
 }
@@ -619,11 +619,11 @@ export default function MentionInline() {
 				/>
 			</div>
 
-			<Stack direction="horizontal" gap="md" align="center" wrap>
+			<Stack direction="horizontal" gap="sm" align="center" wrap>
 				<Popover open={mentions.pickerOpen && !mentions.triggerActive} onOpenChange={mentions.setPickerOpen}>
 					<PopoverTrigger
 						render={
-							<Button tone="neutral" buttonStyle="outline">
+							<Button tone="neutral" appearance="outline">
 								Insert reference
 							</Button>
 						}
@@ -662,7 +662,7 @@ export default function MentionInline() {
 			)}
 
 			{!!html && (
-				<Text size="xs" type="secondary" className={styles.source}>
+				<Text size="xs" type="secondary" mono className={styles.source}>
 					{html}
 				</Text>
 			)}
@@ -703,7 +703,7 @@ const TONES: NonNullable<MentionResource["tone"]>[] = ["primary", "secondary", "
 
 export default function MentionTones() {
 	return (
-		<Stack gap="lg">
+		<Stack>
 			<Text>
 				The same chip in body copy:{" "}
 				<MentionChip mention={STORED_MENTIONS[0]!} resource={RESOURCES.user} />{" "}

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

@@ -15,7 +15,6 @@ Any application modal — dialog, sheet or confirmation — including its async
 
 ```tsx fragment — import-only example
 import { ActionDialog } from "themelia-ui/features/overlays"
-import "themelia-ui/features/overlays.css"
 ```
 
 ## Composition
@@ -35,6 +34,16 @@ A dialog with a generated footer: cancel and confirm in a fixed order, an async-
 form-aware confirm, and a tone for the glyph and the confirm colour. Use the base Dialog when
 the body owns its actions.
 
+**Use when:** A temporary focused task or nested confirmation with explicit completion.
+
+**Avoid when:** Persistent route content or application-owned business policy.
+
+**Compose:** Use controlled open and closeOnAsyncComplete=false when resolved validation can fail; use formId for a native form with one submit owner. Busy confirmation blocks dismissal.
+
+**Capabilities:** nested confirmation; resolved validation failure; async form completion.
+
+**Alternatives:** ActionSheet, ConfirmDialog.
+
 ```text
 ({ width, surfaceStyle, ...props }: ActionDialogProps) => import("react").JSX.Element
 ```
@@ -70,9 +79,9 @@ Extends: `OverlayBaseProps`, `OverlayActionProps`, `OverlayEmphasisProps`.
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
 | `side` | no | `SheetSide` |  |
-| `size` | no | `string` | Cross-axis extent: a side panel's width. |
-| `length` | no | `string` | How far it runs along its edge; `inset` sets the gap from the viewport. See base/sheet. |
-| `inset` | no | `boolean \| string` |  |
+| `size` | no | `OverlaySize` | Cross-axis extent: a side panel's width, `default`, `sm`, `full` or a CSS length. |
+| `length` | no | `OverlayLength` | How far it runs along its edge; `inset` sets the gap from the viewport. See base/sheet. |
+| `inset` | no | `OverlayInset` |  |
 | `showFooter` | no | `boolean` |  |
 | `modality` | no | `"modal" \| "trap-focus" \| "non-modal"` | How much of the page it takes hostage. `modal` traps focus, locks scroll and makes the page<br>inert; `non-modal` sits beside the app (inspectors, filter rails) and leaves the<br>surrounding page interactive; `trap-focus` is in between. A non-modal panel is not<br>announced as a dialog, so never use it for a question that must be answered. |
 | `trigger` | no | `ReactNode` | The element that opens it, which makes the overlay uncontrolled. Supply this OR `open`,<br>not both. |
@@ -139,7 +148,7 @@ Passing `onConfirm` alongside `onAsyncConfirm` therefore skips the async one.
 | `onError` | no | `(error: unknown) => void` | Receives a rejected async confirm, so a consumer can toast or report it. The overlay stays<br>open. |
 | `closeOnAsyncComplete` | no | `boolean` | `false` keeps the overlay open after a resolved async confirm — a multi-step flow. @default true |
 | `confirmTone` | no | `OverlayButtonTone` |  |
-| `confirmStyle` | no | `OverlayButtonStyle` |  |
+| `confirmAppearance` | no | `OverlayButtonAppearance` |  |
 | `loading` | no | `boolean` | Forces the pending presentation, for confirm work owned outside the overlay. |
 | `formId` | no | `string` | The first of the three confirm paths: the confirm button calls `requestSubmit()` on that<br>form, so native validation runs and the form's own `onSubmit` owns the outcome. Neither<br>callback fires. |
 | `footer` | no | `ReactNode` | Replaces the generated footer. Every action prop stops applying. |
@@ -175,14 +184,14 @@ Kind: interface.
 | `contentClassName` | no | `string` |  |
 | `strings` | no | `Partial<OverlayActionStrings>` |  |
 
-### `OverlayButtonStyle`
+### `OverlayButtonAppearance`
 
 Kind: type.
 
 Ghost is excluded: a footer's confirm must look like a commitment.
 
 ```text
-Exclude<ButtonStyle, "ghost">
+Exclude<ButtonAppearance, "ghost">
 ```
 
 ### `OverlayButtonTone`
@@ -363,6 +372,50 @@ Kind: interface.
 
 Preview route: Action overlays — `/action-overlays`
 
+### Nested action flow
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+import { useRef, useState } from "react"
+import { Button } from "themelia-ui/base/buttons"
+import { FormField } from "themelia-ui/base/forms"
+import { Stack } from "themelia-ui/base/structure"
+import { Input } from "themelia-ui/base/text-inputs"
+import { Text } from "themelia-ui/base/typography"
+import { ActionDialog } from "themelia-ui/features/overlays"
+
+export default function NestedActionReference() {
+	const [open, setOpen] = useState(false)
+	const [child, setChild] = useState(false)
+	const [name, setName] = useState("Draft record")
+	const [error, setError] = useState<string>()
+	const [saved, setSaved] = useState(0)
+	const session = useRef(0)
+	const changeOpen = (next: boolean) => { session.current++; setOpen(next); setChild(false) }
+	return <Stack>
+		<ActionDialog open={open} trigger={<Button>Inspect draft</Button>} onOpenChange={changeOpen} title="Record inspector" description="The draft remains here after cancellation, validation failure or transport failure." showConfirm={false}>
+			<Stack>
+				<FormField label="Record name" error={error} hint="Use at least three characters. Use offline to simulate a rejected request."><Input value={name} onChange={event => setName(event.target.value)} /></FormField>
+				<ActionDialog open={child} trigger={<Button>Review save</Button>} onOpenChange={setChild} title="Save this draft?" description="A resolved response can contain validation errors. Closure follows business success." closeOnAsyncComplete={false}
+					alertMessage={error} onError={() => setError("Could not save; your draft is still here.")}
+					onAsyncConfirm={async () => {
+						const attempt = session.current
+						await new Promise(resolve => setTimeout(resolve, 300))
+						if (attempt !== session.current) return
+						if (name === "offline") throw new Error("Unavailable")
+						if (name.trim().length < 3) { setError("Enter at least three characters."); return }
+						setError(undefined); setSaved(count => count + 1); changeOpen(false)
+					}}>
+					<Text>{name}</Text>
+				</ActionDialog>
+				{/* A native form can instead use formId: its submit handler owns validation and closure. */}
+				<Text size="xs" type="secondary">Confirmation {child ? "open" : "closed"}</Text>
+			</Stack>
+		</ActionDialog>
+		<Text role="status">Successful saves {saved}</Text>
+	</Stack>
+}
+```
+
 ### ActionDialog
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
@@ -382,12 +435,12 @@ export default function ActionDialogExample() {
 	const [failure, setFailure] = useState<string | null>(null)
 
 	return (
-		<Stack direction="horizontal" gap="lg" wrap align="center">
-			<Stack direction="horizontal" gap="lg" wrap>
+		<Stack direction="horizontal" wrap align="center">
+			<Stack direction="horizontal" wrap>
 				<ActionDialog
 					title="Rename workspace"
 					description="The name appears in the sidebar and in invitations."
-					trigger={<Button tone="neutral" buttonStyle="outline">Plain</Button>}
+					trigger={<Button tone="neutral" appearance="outline">Plain</Button>}
 					onConfirm={() => setSaved("renamed")}
 				>
 					<FormField label="Name">
@@ -402,14 +455,14 @@ export default function ActionDialogExample() {
 					emphasis
 					showIcon
 					alertMessage="Members are notified by email as soon as it publishes."
-					trigger={<Button tone="neutral" buttonStyle="outline">Toned</Button>}
+					trigger={<Button tone="neutral" appearance="outline">Toned</Button>}
 					onConfirm={() => setSaved("published")}
 				/>
 
 				<ActionDialog
 					title="Saving takes a moment"
 					description="The confirm shows a spinner and both buttons disable until it settles."
-					trigger={<Button tone="neutral" buttonStyle="outline">Async confirm</Button>}
+					trigger={<Button tone="neutral" appearance="outline">Async confirm</Button>}
 					onAsyncConfirm={async () => {
 						await wait(1200)
 						setSaved("saved after a delay")
@@ -422,7 +475,7 @@ export default function ActionDialogExample() {
 					tone="destructive"
 					onOpenChange={() => setFailure(null)}
 					description="A rejection leaves the overlay open and reports through onError — closing it would take the form away at the moment you most need to see what went wrong."
-					trigger={<Button tone="neutral" buttonStyle="outline">Async that rejects</Button>}
+					trigger={<Button tone="neutral" appearance="outline">Async that rejects</Button>}
 					onAsyncConfirm={async () => {
 						await wait(900)
 						throw new Error("Could not reach the server")
@@ -451,11 +504,11 @@ import { wait } from "./data"
 
 export default function ConfirmDialogExample() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap>
+		<Stack direction="horizontal" wrap>
 			<ConfirmDialog
 				title="Discard your changes?"
 				description="The draft has unsaved edits."
-				trigger={<Button tone="neutral" buttonStyle="outline">Neutral</Button>}
+				trigger={<Button tone="neutral" appearance="outline">Neutral</Button>}
 			/>
 			<ConfirmDialog
 				destructive
@@ -484,14 +537,14 @@ import { wait } from "./data"
 
 export default function ActionSheetExample() {
 	return (
-		<Stack direction="horizontal" gap="lg" wrap>
+		<Stack direction="horizontal" wrap>
 			<ActionSheet
 				title="Edit invoice"
 				description="Longer work than a dialog comfortably holds."
-				trigger={<Button tone="neutral" buttonStyle="outline">Modal sheet</Button>}
+				trigger={<Button tone="neutral" appearance="outline">Modal sheet</Button>}
 				onAsyncConfirm={() => wait(700)}
 			>
-				<Stack gap="md">
+				<Stack gap="sm">
 					<FormField label="Reference">
 						<Input defaultValue="INV-4417" />
 					</FormField>
@@ -507,7 +560,7 @@ export default function ActionSheetExample() {
 				modality="non-modal"
 				showFooter={false}
 				inset
-				trigger={<Button tone="neutral" buttonStyle="outline">Non-modal inspector</Button>}
+				trigger={<Button tone="neutral" appearance="outline">Non-modal inspector</Button>}
 			>
 				<Text size="sm" type="secondary">
 					Scroll and click the page behind this panel — it is not inert.
@@ -534,11 +587,11 @@ export default function OverlayVisibility() {
 
 	return (
 		<>
-			<Stack direction="horizontal" gap="lg" wrap>
-				<Button tone="neutral" buttonStyle="outline" onClick={overlays.edit.show}>
+			<Stack direction="horizontal" wrap>
+				<Button tone="neutral" appearance="outline" onClick={overlays.edit.show}>
 					Open edit
 				</Button>
-				<Button tone="neutral" buttonStyle="outline" onClick={overlays.remove.show}>
+				<Button tone="neutral" appearance="outline" onClick={overlays.remove.show}>
 					Open remove
 				</Button>
 			</Stack>

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

@@ -8,14 +8,13 @@ Presenting catalogue records — options, readiness, policies and quotes — in
 
 - **Use when:** Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.
 - **Avoid when:** The record is an order, invoice or shipment.
-- **Consider instead:** `admin/patterns/commerce`, `features/resource`
+- **Consider instead:** `blocks/admin/commerce`, `features/resource`
 - **Stability:** stable.
 
 ## Import
 
 ```tsx fragment — import-only example
 import { ProductContractOverview } from "themelia-ui/features/products"
-import "themelia-ui/features/products.css"
 ```
 
 ## Optional peers
@@ -1505,7 +1504,7 @@ export default function Manager() {
 				{catalogue.variants.length} rows exist
 			</Text>
 
-			<Grid gap="lg">
+			<Grid>
 				<ProductOptionsSummary
 					options={OPTION_SUMMARY}
 					onManageOptions={() => note("manage options")}
@@ -1524,7 +1523,7 @@ export default function Manager() {
 				onDeleteVariant={(variant) => note(`delete ${variant.id}`)}
 			/>
 
-			<Stack direction="horizontal" gap="md" align="center">
+			<Stack direction="horizontal" gap="sm" align="center">
 				<Text size="sm" type="secondary">Group by</Text>
 				<PillRadioGroup
 					value={groupBy}
@@ -1578,7 +1577,7 @@ export default function VariantDetail() {
 		<>
 			{/* Stacked, not two-up: both of these switch layout on their OWN width, and a
 			    half-column here is narrower than either ever gets in a real rail. */}
-			<Stack gap="lg">
+			<Stack>
 				<ProductVariantDetails
 					variant={{
 						id: "m-trail",
@@ -1668,7 +1667,7 @@ export default function Empty() {
 
 	return (
 		<>
-			<Grid gap="lg">
+			<Grid>
 				<ProductVariantsBulkTable
 					variants={[]}
 					onGenerateVariants={() => note("generate the combinations")}
@@ -1709,7 +1708,7 @@ export default function Overview() {
 
 	return (
 		<>
-			<Grid gap="lg">
+			<Grid>
 				<ProductOverview
 					title="Trailhead 29er"
 					description="Aluminium trail hardtail, sold as a frameset or a complete build."
@@ -1763,14 +1762,14 @@ export default function Rows() {
 
 	return (
 		<>
-			<Grid gap="lg">
+			<Grid>
 				<ProductReadinessCard
 					score={72}
 					items={READINESS}
 					summary="Two checks left before this can be published."
 					onSelectReadinessItem={(item) => note(`readiness: ${item.id}`)}
 				/>
-				<Stack gap="lg">
+				<Stack>
 					<ProductStructureCard
 						metrics={STRUCTURE}
 						onSelectMetric={(metric) => note(`structure: ${metric.id}`)}
@@ -1814,8 +1813,8 @@ export default function Contract() {
 
 	return (
 		<>
-			<Grid gap="lg">
-				<Stack gap="lg">
+			<Grid>
+				<Stack>
 					<ProductDetailsCard
 						metadata={DETAILS}
 						onEditDetails={() => note("edit details")}