themelia-ui 2.0.1 → 3.0.0

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

@@ -20,7 +20,7 @@ import "themelia-ui/features/media-library.css"
 
 ## Composition
 
-This family composes `base/badge`, `base/batch-action-bar`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/navigation`, `base/structure`, `base/table`, `base/text-inputs`, `base/typography`, `base/upload`, `base/value-inputs`, `features/overlays`.
+This module composes `base/badge`, `base/batch-action-bar`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/navigation`, `base/structure`, `base/table`, `base/text-inputs`, `base/typography`, `base/upload`, `base/value-inputs`, `features/overlays`.
 
 Application policy—routing, fetching, persistence, permissions, and translation—stays
 outside the package and arrives through the public props, callbacks, slots, or accessors below.
@@ -55,6 +55,9 @@ Kind: callable.
 
 Kind: callable.
 
+The asset browser, as a panel. The detail panel is a column beside the grid, not an overlay,
+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
 ```
@@ -101,6 +104,8 @@ What a bulk action is handed; mirrors the product variants' context.
 
 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
 ```
@@ -143,6 +148,9 @@ Kind: type.
 
 Kind: callable.
 
+The panel for the selected asset. The detail is a COLUMN rather than an overlay: an overlay
+would cover the grid the reader is comparing against.
+
 ```text
 ({ item, collections, accessors, strings, onClose, onUpdate, onRemove, renderDetail }: MediaLibraryDetailPanelProps<TItem>) => import("react").JSX.Element | null
 ```
@@ -205,7 +213,7 @@ Extends: `Omit<MediaLibraryProps<TItem>, "title" | "description">`.
 
 Kind: callable.
 
-The browser's empty state: bordered and inset, since it stands in for a grid.
+The state with no assets: bordered and inset, since it stands in for a grid.
 
 ```text
 ({ title, description, icon, action, className, }: MediaLibraryEmptyStateProps) => import("react").JSX.Element
@@ -259,6 +267,9 @@ Kind: interface.
 
 Kind: callable.
 
+The selection bar: what is chosen, and what can be done with it — the summary and the actions
+together.
+
 ```text
 ({ tab, selectedItems, selectedIds, selectionMode, stagedFiles, uploading, strings, visibleCount, totalCount, confirmLabel, cancelLabel, onCancel, onConfirm, onClearSelection, onUpload, onCancelUpload, chrome, className, }: MediaLibraryFooterProps<TItem>) => import("react").JSX.Element
 ```
@@ -267,6 +278,9 @@ Kind: callable.
 
 Kind: callable.
 
+The footer's verbs: what can be done with the selection, or with the staged files. Split from
+the summary, so a consumer can keep the count and supply their own verbs.
+
 ```text
 ({ tab, selectedIds, selectedItems, stagedFiles, uploading, strings, confirmLabel, cancelLabel, onCancel, onConfirm, onUpload, onCancelUpload, className, }: MediaLibraryFooterActionsProps<TItem>) => import("react").JSX.Element
 ```
@@ -305,8 +319,9 @@ Extends: `MediaLibraryFooterSummaryProps`, `Omit<MediaLibraryFooterActionsProps<
 
 Kind: callable.
 
-The footer line: a selection count while browsing, a staged-file tally while uploading.
-A live region, so keyboard picks inside the grid are announced.
+The footer line: what is chosen — a selection count while browsing, a staged-file tally while
+uploading. A live region, so keyboard picks inside the grid are announced. Split from the
+actions, so a consumer can keep the count and supply their own verbs.
 
 ```text
 ({ tab, selectedIds, selectionMode, stagedFiles, strings, visibleCount, totalCount, onClearSelection, className, }: MediaLibraryFooterSummaryProps) => import("react").JSX.Element
@@ -332,6 +347,9 @@ Kind: interface.
 
 Kind: callable.
 
+The composable visual grid. Like the list and the table, it uses the same accessors and
+selection callbacks.
+
 ```text
 ({ items, selectedSet, accessors, strings, onToggle, onDetails, density, selectionMode, showMeta, renderItem, className }: MediaLibraryGridProps<TItem>) => import("react").JSX.Element
 ```
@@ -412,6 +430,9 @@ Kind: type.
 
 Kind: callable.
 
+The composable compact rows. Like the grid and the table, it uses the same accessors and
+selection callbacks.
+
 ```text
 ({ items, selectedSet, accessors, strings, onToggle, onDetails, }: MediaLibraryListProps<TItem>) => import("react").JSX.Element
 ```
@@ -445,19 +466,22 @@ Extends: `Omit<ComponentPropsWithoutRef<"section">, "children" | "defaultValue"
 | `density` | no | `MediaLibraryDensity` |  |
 | `showMeta` | no | `boolean` | Shows each asset's size and dimensions under its name. |
 | `allowUpload` | no | `boolean` |  |
-| `typeFilters` | no | `readonly MediaLibraryTypeFilter[]` |  |
-| `confirmOnSelect` | no | `boolean` | Picking confirms and the footer is removed. For a single-select picker. |
+| `typeFilters` | no | `readonly MediaLibraryTypeFilter[]` | The type filters the toolbar offers. A single type filter draws no control. |
+| `confirmOnSelect` | no | `boolean` | Picking is confirming: fires `onConfirm` immediately and removes the footer. The shape a<br>single-select picker wants. |
 | `onConfirm` | no | `(items: TItem[], ids: string[]) => void` |  |
 | `onCancel` | no | `() => void` |  |
 | `onClose` | no | `() => void` |  |
 | `bulkActions` | no | `(context: MediaLibraryBulkActionContext<TItem>) => ReactNode` | Bulk actions for a selection, rendered in the shared BatchActionBar. Browsing only:<br>a picker's footer already reports the selection, so the bar is suppressed there. |
 | `strings` | no | `Partial<MediaLibraryStrings>` |  |
-| `slots` | no | `MediaLibrarySlots<TItem>` |  |
+| `slots` | no | `MediaLibrarySlots<TItem>` | `headerStart`/`headerEnd`, `toolbarEnd`, `empty`, `loading`, `error`, `footer`,<br>`uploadEmpty`, plus `renderItem` and `renderDetail`. |
 
 ### `MediaLibrarySelectionBar`
 
 Kind: callable.
 
+Result counts, pending announcements, and selection of the visible results. Selections the
+current filters hide are preserved.
+
 ```text
 ({ visibleCount, totalCount, selectedVisibleCount, onSelectVisible, onDeselectVisible, status, disabled, strings, className }: MediaLibrarySelectionBarProps) => import("react").JSX.Element
 ```
@@ -636,7 +660,8 @@ Kind: type.
 
 Kind: callable.
 
-A metadata table for inspecting assets; selection and details remain separate controls.
+The composable metadata table for inspecting assets; selection and details remain separate
+controls. Like the grid and the list, it uses the same accessors and selection callbacks.
 
 ```text
 ({ items, selectedSet, accessors, strings, onToggle, onDetails, className, collections }: MediaLibraryTableProps<TItem>) => import("react").JSX.Element
@@ -657,6 +682,8 @@ Extends: `MediaLibraryListProps<TItem>`.
 
 Kind: callable.
 
+Search, filter and view controls. A single type filter draws no control.
+
 ```text
 ({ query, onQueryChange, type, onTypeChange, typeFilters, collection, onCollectionChange, collections, sort, onSortChange, view, onViewChange, hasFilters, onClearFilters, strings, end, className, }: MediaLibraryToolbarProps) => import("react").JSX.Element
 ```
@@ -728,6 +755,9 @@ Kind: interface.
 
 Kind: callable.
 
+The drop target and queue inside the library, so uploading happens where the assets are
+rather than behind a second dialog.
+
 ```text
 ({ stagedFiles, uploading, uploadOptions, collections, strings, onAddFiles, onRemoveFile, onClear, onOptionsChange, onStart, onCancel, empty, showActions, }: MediaLibraryUploadPanelProps) => import("react").JSX.Element
 ```
@@ -772,8 +802,10 @@ Kind: type.
 
 Kind: callable.
 
-The asset's picture, or a stand-in: a broken `src` falls back to the type glyph, and
-`tint` gives an asset without a preview a recognisable colour.
+The thumbnail that handles an image, a video, a PDF and a file with no preview at all — the
+last being the case a gallery usually forgets. It shows the asset's picture, or a stand-in: a
+broken `src` falls back to the type glyph, and `tint` gives an asset without a preview a
+recognisable colour.
 
 ```text
 ({ item, accessors, className, }: { item: TItem; accessors: ResolvedMediaLibraryAccessors<TItem>; className?: string; }) => import("react").JSX.Element
@@ -783,6 +815,10 @@ The asset's picture, or a stand-in: a broken `src` falls back to the type glyph,
 
 Kind: callable.
 
+The assets attached to a record, in order — with reorder, cover, and detach. Not a browser:
+`onAdd` usually opens the library dialog. Reordering uses move buttons rather than drag, so it
+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
 ```
@@ -859,6 +895,10 @@ Kind: callable.
 
 Kind: callable.
 
+The whole state without the chrome. Its stable `refetch()` retries the current query without
+clearing filters or selection; `fetchError` identifies fetch failures separately from
+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>
 ```
@@ -869,18 +909,18 @@ Kind: interface.
 
 | member | required | type | description / documented default |
 | --- | :-: | --- | --- |
-| `items` | no | `readonly TItem[]` | Ignored entirely when `fetcher` is set. |
-| `fetcher` | no | `MediaLibraryFetcher<TItem>` | Supplying it hands searching, filtering, and sorting to the server. |
-| `accessors` | no | `MediaLibraryAccessors<TItem>` |  |
-| `collections` | no | `readonly MediaLibraryCollectionOption[]` |  |
-| `selectionMode` | no | `MediaLibrarySelectionMode` |  |
-| `value` | no | `readonly string[]` |  |
-| `defaultValue` | no | `readonly string[]` |  |
-| `onValueChange` | no | `(ids: string[], items: TItem[]) => void` |  |
-| `onItemUpdate` | no | `(item: TItem, patch: MediaLibraryItemPatch) => void \| Promise<void>` |  |
-| `applyItemPatch` | no | `(item: TItem, patch: MediaLibraryItemPatch) => TItem` | Applies editable fields to a custom record shape without mutating the original. |
-| `onItemDelete` | no | `(item: TItem) => void \| Promise<void>` |  |
-| `onUpload` | no | `MediaLibraryUploadHandler<TItem>` |  |
+| `items` | no | `readonly TItem[]` | The assets, when the library searches, filters and sorts them itself. Supply this or<br>`fetcher`, not both: it is ignored entirely when `fetcher` is set. |
+| `fetcher` | no | `MediaLibraryFetcher<TItem>` | Supplying it hands searching, filtering, and sorting to the server: the fetcher owns all<br>three, and `items` is ignored. |
+| `accessors` | no | `MediaLibraryAccessors<TItem>` | Reads id, name, src, type, size, and the rest off your own shape. Supply only the ones that<br>differ from MediaLibraryItem's names. |
+| `collections` | no | `readonly MediaLibraryCollectionOption[]` | The collections the toolbar offers. |
+| `selectionMode` | no | `MediaLibrarySelectionMode` | `single` replaces the selection rather than toggling off, so a picker never ends up empty<br>by accident. |
+| `value` | no | `readonly string[]` | Controlled: the selected ids. |
+| `defaultValue` | no | `readonly string[]` | Uncontrolled: the ids selected at first. |
+| `onValueChange` | no | `(ids: string[], items: TItem[]) => void` | Receives the selected ids, controlled or not, and the resolved assets too, so a consumer<br>never has to look them up again. |
+| `onItemUpdate` | no | `(item: TItem, patch: MediaLibraryItemPatch) => void \| Promise<void>` | Awaited. A rejection rolls the local overlay back and reaches `onError`; the panel stays<br>open so the reader can see what failed. |
+| `applyItemPatch` | no | `(item: TItem, patch: MediaLibraryItemPatch) => TItem` | Maps a standard metadata patch onto a consumer-owned record shape, without mutating the<br>original. Defaults to merging fields onto MediaLibraryItem. |
+| `onItemDelete` | no | `(item: TItem) => void \| Promise<void>` | Awaited. A rejection keeps the asset and reaches `onError`; the panel stays open so the<br>reader can see what failed. |
+| `onUpload` | no | `MediaLibraryUploadHandler<TItem>` | Receives the files, the upload options, and helpers carrying stable staged files and IDs,<br>an AbortSignal, `setProgress`, and `setFileStatus`. Failed files stay queued for retry.<br>Returning the created items adds AND selects them — the reader uploaded them in order to<br>use them. |
 | `onError` | no | `(error: unknown) => void` | Receives failures from the fetcher, uploads, updates, and deletes. |
 | `tab` | no | `MediaLibraryTab` |  |
 | `defaultTab` | no | `MediaLibraryTab` |  |
@@ -911,77 +951,286 @@ Preview route: Media library — `/media-library`
 ### Asset manager
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MediaLibrary
-  items={assets}
-  collections={collections}
-  value={selected}
-  onValueChange={setSelected}
-  onItemUpdate={(item, patch) => api.updateAsset(item.id, patch)}
-  onItemDelete={(item) => api.deleteAsset(item.id)}
-  onUpload={(files, options, helpers) =>
-    api.upload(files, options, helpers.files, helpers.setProgress, helpers.signal)}
-  onConfirm={(items) => attach(items)}
-/>
+import { useRef, 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 { MediaLibrary, type MediaLibraryItem } from "themelia-ui/features/media-library"
+
+import { ASSETS, COLLECTIONS } from "./data"
+
+export default function Library() {
+	const [selected, setSelected] = useState<string[]>(["m1"])
+	const [note, setNote] = useState<string | null>(null)
+	const failNext = useRef(false)
+	const uploadSequence = useRef(0)
+
+	return (
+		<>
+			<MediaLibrary
+				items={ASSETS}
+				collections={COLLECTIONS}
+				value={selected}
+				onValueChange={setSelected}
+				onItemUpdate={async (item) => {
+					await new Promise((resolve) => setTimeout(resolve, 400))
+					if (failNext.current) { failNext.current = false; throw new Error("Sample save failed") }
+					setNote(`Saved ${item.name}`)
+				}}
+				onItemDelete={async (item) => {
+					await new Promise((resolve) => setTimeout(resolve, 400))
+					if (failNext.current) { failNext.current = false; throw new Error("Sample delete failed") }
+					setNote(`Deleted ${item.name}`)
+				}}
+				onUpload={async (files, options, { files: staged, setProgress, signal }) => {
+					for (let step = 20; step <= 100; step += 20) {
+						await new Promise((resolve) => setTimeout(resolve, 120))
+						if (signal.aborted) return
+						for (const file of staged ?? []) setProgress(file.id, step)
+					}
+					if (failNext.current) { failNext.current = false; throw new Error("Sample upload failed") }
+					setNote(`Uploaded ${files.length}`)
+					return files.map((file): MediaLibraryItem => ({ id: `uploaded-${++uploadSequence.current}`, name: file.name, type: file.type.startsWith("image/") ? "image" : file.type.startsWith("video/") ? "video" : "file", size: file.size, uploadedAt: new Date(), ...options }))
+				}}
+				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.") }}>
+					Fail next action
+				</Button>
+				<Text size="sm" type="secondary">Preview recovery without mixing test controls into the library toolbar.</Text>
+			</Stack>
+			{!!note && <Text role="status" size="sm" type="secondary">{note}</Text>}
+		</>
+	)
+}
 ```
 
 ### Loading and recovery
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-const fetchAssets = useCallback(
-  ({ query, type, collection, sort, signal }) =>
-    api.listAssets({ query, type, collection, sort, signal }),
-  [],
-)
-
-<MediaLibrary
-  fetcher={fetchAssets}
-  collections={collections}
-  allowUpload={false}
-  onConfirm={(items) => attach(items)}
-  strings={{ retry: "Try again" }}
-/>
+import { useMemo, useRef, 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 { MediaLibrary, type MediaLibraryFetcher } from "themelia-ui/features/media-library"
+
+import { ASSETS, COLLECTIONS } from "./data"
+
+/** A local stand-in for a service: cancellation, filtering and sorting belong here. */
+export default function AsyncLibrary() {
+	const [scenario, setScenario] = useState<{ kind: "assets" | "failure" | "empty" }>({ kind: "assets" })
+	const [selected, setSelected] = useState<string[]>([])
+	const [attached, setAttached] = useState("")
+	const failurePending = useRef(false)
+	const load = (kind: "assets" | "failure" | "empty") => {
+		failurePending.current = kind === "failure"
+		setScenario({ kind })
+	}
+	const fetcher = useMemo<MediaLibraryFetcher>(() => {
+		return async ({ query, type, collection, sort, signal }) => {
+			await new Promise<void>((resolve, reject) => {
+				const cancel = () => {
+					clearTimeout(timer)
+					reject(new DOMException("Request cancelled", "AbortError"))
+				}
+				const timer = setTimeout(() => {
+					signal?.removeEventListener("abort", cancel)
+					resolve()
+				}, 700)
+				if (signal?.aborted) cancel()
+				else signal?.addEventListener("abort", cancel, { once: true })
+			})
+			if (failurePending.current) {
+				failurePending.current = false
+				throw new Error("Simulated service interruption")
+			}
+			const needle = query.trim().toLowerCase()
+			const items = (scenario.kind === "empty" ? [] : ASSETS).filter((asset) =>
+				(type === "all" || asset.type === type)
+				&& (!collection || asset.collection === collection)
+				&& `${asset.name} ${asset.collection} ${asset.tags?.join(" ")}`.toLowerCase().includes(needle),
+			)
+			items.sort((left, right) => {
+				if (sort === "name") return left.name.localeCompare(right.name)
+				if (sort === "size") return (right.size ?? 0) - (left.size ?? 0)
+				if (sort === "usage") return (right.usageCount ?? 0) - (left.usageCount ?? 0)
+				return new Date(right.uploadedAt!).getTime() - new Date(left.uploadedAt!).getTime()
+			})
+			return { items, total: items.length }
+		}
+	}, [scenario])
+
+	return (
+		<Stack>
+			<Stack direction="horizontal" wrap>
+				<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => load("assets")}>
+					Load sample assets
+				</Button>
+				<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => load("failure")}>
+					Simulate failure
+				</Button>
+				<Button type="button" tone="neutral" buttonStyle="outline" onClick={() => load("empty")}>
+					Show empty library
+				</Button>
+			</Stack>
+			<MediaLibrary
+				fetcher={fetcher}
+				collections={COLLECTIONS}
+				allowUpload={false}
+				strings={{ emptyDescription: "This sample library is empty. Load sample assets to continue." }}
+				value={selected}
+				onValueChange={setSelected}
+				onConfirm={(items) => setAttached(`Attached ${items.length} ${items.length === 1 ? "asset" : "assets"}: ${items.map(item => item.name).join(", ")}.`)}
+			/>
+			<Text role="status" type="secondary">{attached || "Choose assets and use the selection to attach them."}</Text>
+		</Stack>
+	)
+}
 ```
 
 ### Acting on a selection
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MediaLibrary
-  items={assets}
-  bulkActions={({ selectedItems, clearSelection }) => (
-    <>
-      <Button tone="neutral" buttonStyle="ghost">Download</Button>
-      <Button tone="destructive" buttonStyle="ghost"
-        onClick={() => { remove(selectedItems); clearSelection() }}>
-        Delete
-      </Button>
-    </>
-  )}
-/>
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Text } from "themelia-ui/base/typography"
+import { MediaLibrary } from "themelia-ui/features/media-library"
+
+import { ASSETS, COLLECTIONS } from "./data"
+
+export default function BulkActions() {
+	const [assets, setAssets] = useState(ASSETS)
+	const [selected, setSelected] = useState<string[]>([ASSETS[0]!.id, ASSETS[1]!.id])
+	const [note, setNote] = useState<string | null>(null)
+
+	return (
+		<>
+			{/*
+			 * `transform` makes this box the containing block for the floating bar, so it docks
+			 * to the example rather than the viewport. The same applies in an app: a floating
+			 * bar inside a transformed ancestor docks to that ancestor.
+			 */}
+			<div style={{ transform: "translate(0)", position: "relative", width: "100%" }}>
+				<MediaLibrary
+					items={assets}
+					collections={COLLECTIONS}
+					value={selected}
+					onValueChange={setSelected}
+					bulkActions={({ selectedCount, clearSelection }) => (
+						<>
+							<Button
+								type="button"
+								tone="neutral"
+								buttonStyle="ghost"
+								onClick={() => {
+									setAssets((current) => current.map((asset) => selected.includes(asset.id) ? { ...asset, public: true } : asset))
+									setNote(`Made ${selectedCount} assets public`)
+									clearSelection()
+								}}
+							>
+								Make public
+							</Button>
+							<Button
+								type="button"
+								tone="destructive"
+								buttonStyle="ghost"
+								onClick={() => {
+									setAssets((current) => current.filter((asset) => !selected.includes(asset.id)))
+									setNote(`Deleted ${selectedCount}`)
+									clearSelection()
+								}}
+							>
+								Delete
+							</Button>
+						</>
+					)}
+				/>
+			</div>
+			{!!note && <Text role="status" size="sm" type="secondary">{note}</Text>}
+		</>
+	)
+}
 ```
 
 ### As a picker
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MediaLibraryDialog
-  open={open}
-  onOpenChange={setOpen}
-  items={assets}
-  selectionMode="single"
-  confirmOnSelect
-  onConfirm={([asset]) => setCover(asset)}
-/>
+import { useState } from "react"
+
+import { Button } from "themelia-ui/base/buttons"
+import { Text } from "themelia-ui/base/typography"
+import { MediaLibraryDialog } from "themelia-ui/features/media-library"
+
+import { ASSETS, COLLECTIONS } from "./data"
+
+export default function LibraryDialog() {
+	const [open, setOpen] = useState(false)
+	const [picked, setPicked] = useState<string | null>(null)
+
+	return (
+		<>
+			<Button type="button" onClick={() => setOpen(true)}>Pick an asset</Button>
+			<MediaLibraryDialog
+				open={open}
+				onOpenChange={setOpen}
+				items={ASSETS}
+				collections={COLLECTIONS}
+				selectionMode="single"
+				confirmOnSelect
+				allowUpload={false}
+				onConfirm={(items) => setPicked(items[0]?.name ?? null)}
+			/>
+			{!!picked && <Text role="status" size="sm" type="secondary">picked {picked}</Text>}
+		</>
+	)
+}
 ```
 
 ### Attached to a record
 
 ```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
-<MediaResourceGallery
-  items={attached}
-  primaryId={coverId}
-  onPrimaryChange={setCoverId}
-  onReorder={(ids, items) => setAttached(items)}
-  onRemove={(id) => detach(id)}
-  onAdd={() => setPickerOpen(true)}
-  maxItems={8}
-/>
+import { useState } from "react"
+
+import {
+	MediaLibraryDialog, MediaResourceGallery, type MediaLibraryItem,
+} from "themelia-ui/features/media-library"
+
+import { ASSETS, COLLECTIONS } from "./data"
+
+export default function Gallery() {
+	const [attached, setAttached] = useState<MediaLibraryItem[]>(ASSETS.slice(0, 4))
+	const [primary, setPrimary] = useState("m1")
+	const [picking, setPicking] = useState(false)
+
+	return (
+		<>
+			<MediaResourceGallery
+				items={attached}
+				title="Venue media"
+				description="The first is the cover."
+				primaryId={primary}
+				onPrimaryChange={setPrimary}
+				onReorder={(_ids, items) => setAttached(items)}
+				onRemove={(id) => setAttached((current) => current.filter((item) => item.id !== id))}
+				onAdd={() => setPicking(true)}
+				maxItems={6}
+			/>
+			{/* Add opens the library as a picker, offering only what is not attached yet. */}
+			<MediaLibraryDialog
+				open={picking}
+				onOpenChange={setPicking}
+				items={ASSETS.filter((asset) => !attached.some((item) => item.id === asset.id))}
+				collections={COLLECTIONS}
+				selectionMode="single"
+				confirmOnSelect
+				allowUpload={false}
+				onConfirm={(items) => setAttached((current) => [...current, ...items])}
+			/>
+		</>
+	)
+}
 ```