admin-ui-starter-kit 0.1.3 → 0.4.2

package/.agents/skills/component-library-rules/references/components/features__media-library.md

@@ -0,0 +1,796 @@
+---
+id: features/media-library
+title: "Features · Media Library"
+description: "Framework-agnostic media picker for admin product, CMS, and campaign flows. Provides an embeddable library surface, a Dialog-backed picker wrapper, upload staging, details editing, controlled selection, async fetching, slots, render hooks, and headless state through useMediaLibrary."
+layer: features
+family: "Assets"
+sourcePath: src/components/features/media-library
+examples:
+  - EmbeddedLibrary
+  - ProductMediaDialog
+  - ResourceGalleryList
+  - ExternalResourceGallery
+  - ConfirmOnSelectDialog
+  - AsyncFetcherLibrary
+  - EmptyAndErrorStates
+  - HeadlessSelection
+imports:
+  - @/components/base/badge
+  - @/components/base/buttons
+  - @/components/base/cards
+  - @/components/features/media-library
+  - @/components/typography
+publicImport: admin-ui-starter-kit/features/media-library
+tags:
+  - features
+  - assets
+  - media-library
+  - media
+  - library
+  - framework
+  - agnostic
+---
+
+# Features · Media Library
+
+Framework-agnostic media picker for admin product, CMS, and campaign flows. Provides an embeddable library surface, a Dialog-backed picker wrapper, upload staging, details editing, controlled selection, async fetching, slots, render hooks, and headless state through useMediaLibrary.
+
+**Layer:** `features`
+**Source:** `src/components/features/media-library`
+**Consumer import:** `admin-ui-starter-kit/features/media-library`
+
+## Consumer import
+
+Consumers import this surface from `admin-ui-starter-kit/features/media-library`.
+The examples below use repository source aliases because they run inside the preview app; do not copy those aliases into consuming applications.
+
+## Embedded library
+
+<Example name="EmbeddedLibrary" source={examplesSource}>
+	<Examples.EmbeddedLibrary />
+</Example>
+
+## Dialog picker
+
+<Example name="ProductMediaDialog" source={examplesSource}>
+	<Examples.ProductMediaDialog />
+</Example>
+
+<Example name="ConfirmOnSelectDialog" source={examplesSource}>
+	<Examples.ConfirmOnSelectDialog />
+</Example>
+
+## Resource galleries
+
+<Example name="ResourceGalleryList" source={examplesSource}>
+	<Examples.ResourceGalleryList />
+</Example>
+
+<Example name="ExternalResourceGallery" source={examplesSource}>
+	<Examples.ExternalResourceGallery />
+</Example>
+
+## Async and states
+
+<Example name="AsyncFetcherLibrary" source={examplesSource}>
+	<Examples.AsyncFetcherLibrary />
+</Example>
+
+<Example name="EmptyAndErrorStates" source={examplesSource}>
+	<Examples.EmptyAndErrorStates />
+</Example>
+
+## Headless selection
+
+<Example name="HeadlessSelection" source={examplesSource}>
+	<Examples.HeadlessSelection />
+</Example>
+
+## Usage Notes
+
+Use `MediaLibrary` when the picker is part of a page, drawer, or feature shell. Use `MediaLibraryDialog` only when you need modal behavior; it delegates to `features/overlays/Dialog` for portal, backdrop, escape handling, trigger support, and overlay chrome.
+
+Use `MediaResourceGallery` for the resource field that sits beside the picker: selected media order, primary/cover asset, remove controls, and add-more entry points. Its default `layout="field"` is the product-form shape with a cover tile and inline add tile; use `layout="list"` for dense CMS/resource rows and `layout="grid"` when filenames and metadata should remain visible.
+
+Consumers own persistence and routing. Pass `items` for local collections or `fetcher` for remote search. Pass `value` and `onValueChange` for controlled form fields, `onConfirm` to commit the selected items, `onUpload` to stage uploads into your storage flow, and `onItemUpdate` / `onItemDelete` for metadata actions.
+
+The picker toolbar uses segmented type filters. By default it shows `all`, `image`, and `video`; pass `typeFilters={['all', 'image', 'video', 'file']}` when documents or generic files should be filterable.
+
+The feature is generic. Use `accessors` to adapt app-owned media records without reshaping data before render.
+
+## Examples
+
+```tsx
+import { useCallback, useMemo, useState } from 'react';
+import {
+	CheckCircle2,
+	ImagePlus,
+	Images,
+	Search,
+	Star,
+	UploadCloud,
+} from 'lucide-react';
+
+import { Badge } from '@/components/base/badge';
+import { Button } from '@/components/base/buttons';
+import { SmartCard } from '@/components/base/cards';
+import {
+	defaultMediaLibraryStrings,
+	MediaLibrary,
+	MediaLibraryCard,
+	MediaLibraryDialog,
+	MediaResourceGallery,
+	useMediaLibrary,
+} from '@/components/features/media-library';
+import type {
+	MediaLibraryFetchParams,
+	MediaLibraryItem,
+	MediaLibraryUploadOptions,
+} from '@/components/features/media-library';
+import { Text } from '@/components/typography';
+
+const collections = [
+	{ value: 'Products', label: 'Products' },
+	{ value: 'Lifestyle', label: 'Lifestyle' },
+	{ value: 'Banners', label: 'Banners' },
+];
+
+function demoMediaSource(label: string, from: string, to: string) {
+	const svg = `
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 360">
+	<defs>
+		<linearGradient id="g" x1="0" x2="1" y1="0" y2="1">
+			<stop offset="0" stop-color="${from}"/>
+			<stop offset="1" stop-color="${to}"/>
+		</linearGradient>
+	</defs>
+	<rect width="480" height="360" fill="url(#g)"/>
+	<circle cx="386" cy="78" r="92" fill="rgba(255,255,255,.22)"/>
+	<circle cx="94" cy="304" r="138" fill="rgba(0,0,0,.12)"/>
+	<path d="M42 270c68-54 126-58 176-12s111 42 220-12v114H42V270Z" fill="rgba(255,255,255,.18)"/>
+	<text x="40" y="58" fill="rgba(255,255,255,.92)" font-family="Inter, ui-sans-serif, system-ui" font-size="28" font-weight="700">${label}</text>
+	<text x="40" y="91" fill="rgba(255,255,255,.72)" font-family="Inter, ui-sans-serif, system-ui" font-size="15" font-weight="500">Preview asset</text>
+</svg>`;
+	return `data:image/svg+xml,${encodeURIComponent(svg)}`;
+}
+
+const mediaItems: MediaLibraryItem[] = [
+	{
+		id: 'm01',
+		name: 'balsamic-bottle-front.jpg',
+		type: 'image',
+		src: demoMediaSource('Bottle front', '#a16207', '#f5d0a9'),
+		alt: 'Front view of aged balsamic bottle on white',
+		size: 318_500,
+		width: 1600,
+		height: 2000,
+		collection: 'Products',
+		tags: ['bottle', 'primary'],
+		public: true,
+		uploadedAt: 'May 28, 2026',
+		usageCount: 5,
+	},
+	{
+		id: 'm02',
+		name: 'balsamic-bottle-back.jpg',
+		type: 'image',
+		src: demoMediaSource('Bottle back', '#78350f', '#d6a15f'),
+		alt: 'Back label with ingredients',
+		size: 287_200,
+		width: 1600,
+		height: 2000,
+		collection: 'Products',
+		tags: ['bottle', 'label'],
+		public: true,
+		uploadedAt: 'May 28, 2026',
+		usageCount: 2,
+	},
+	{
+		id: 'm03',
+		name: 'label-detail-macro.jpg',
+		type: 'image',
+		src: demoMediaSource('Label detail', '#7f1d1d', '#fca5a5'),
+		alt: 'Macro shot of embossed label',
+		size: 412_800,
+		width: 2000,
+		height: 1500,
+		collection: 'Products',
+		tags: ['label', 'macro'],
+		public: true,
+		uploadedAt: 'May 26, 2026',
+		usageCount: 3,
+	},
+	{
+		id: 'm04',
+		name: 'olive-grove-hero.jpg',
+		type: 'image',
+		src: demoMediaSource('Olive grove', '#365314', '#bef264'),
+		alt: 'Olive grove at golden hour',
+		size: 1_228_800,
+		width: 2400,
+		height: 1600,
+		collection: 'Lifestyle',
+		tags: ['hero', 'estate'],
+		public: true,
+		uploadedAt: 'May 24, 2026',
+		usageCount: 3,
+	},
+	{
+		id: 'm05',
+		name: 'tasting-set-overhead.jpg',
+		type: 'image',
+		src: demoMediaSource('Tasting set', '#334155', '#cbd5e1'),
+		alt: 'Overhead tasting set on linen',
+		size: 689_400,
+		width: 2000,
+		height: 2000,
+		collection: 'Lifestyle',
+		tags: ['tasting', 'flat-lay'],
+		public: true,
+		uploadedAt: 'May 22, 2026',
+		usageCount: 1,
+	},
+	{
+		id: 'm06',
+		name: 'harvest-table.mp4',
+		type: 'video',
+		src: demoMediaSource('Harvest table', '#166534', '#86efac'),
+		alt: '',
+		size: 15_500_000,
+		width: 1920,
+		height: 1080,
+		duration: '0:42',
+		collection: 'Lifestyle',
+		tags: ['harvest', 'b-roll'],
+		public: false,
+		uploadedAt: 'May 20, 2026',
+		usageCount: 0,
+	},
+	{
+		id: 'm07',
+		name: 'press-room-tour.mp4',
+		type: 'video',
+		src: demoMediaSource('Press room', '#1e3a8a', '#93c5fd'),
+		alt: '',
+		size: 37_960_000,
+		width: 1920,
+		height: 1080,
+		duration: '1:58',
+		collection: 'Lifestyle',
+		tags: ['tour', 'process'],
+		public: true,
+		uploadedAt: 'May 18, 2026',
+		usageCount: 1,
+	},
+	{
+		id: 'm08',
+		name: 'gift-box-closed.jpg',
+		type: 'image',
+		src: demoMediaSource('Gift closed', '#581c87', '#d8b4fe'),
+		alt: 'Closed gift box with ribbon',
+		size: 254_100,
+		width: 1600,
+		height: 1200,
+		collection: 'Products',
+		tags: ['gift', 'packaging'],
+		public: true,
+		uploadedAt: 'May 15, 2026',
+		usageCount: 2,
+	},
+	{
+		id: 'm09',
+		name: 'gift-box-open.jpg',
+		type: 'image',
+		src: demoMediaSource('Gift open', '#831843', '#f9a8d4'),
+		alt: 'Open gift box showing two bottles',
+		size: 301_700,
+		width: 1600,
+		height: 1200,
+		collection: 'Products',
+		tags: ['gift', 'packaging'],
+		public: true,
+		uploadedAt: 'May 15, 2026',
+		usageCount: 2,
+	},
+	{
+		id: 'm10',
+		name: 'vineyard-autumn.jpg',
+		type: 'image',
+		src: demoMediaSource('Vineyard autumn', '#7c2d12', '#fdba74'),
+		alt: 'Wide autumn vineyard banner',
+		size: 2_867_200,
+		width: 2880,
+		height: 1200,
+		collection: 'Banners',
+		tags: ['banner', 'seasonal'],
+		public: true,
+		uploadedAt: 'May 12, 2026',
+		usageCount: 1,
+	},
+	{
+		id: 'm11',
+		name: 'spring-menu-banner.jpg',
+		type: 'image',
+		src: demoMediaSource('Spring menu', '#14532d', '#bbf7d0'),
+		alt: 'Spring menu campaign banner',
+		size: 1_945_600,
+		width: 2880,
+		height: 1200,
+		collection: 'Banners',
+		tags: ['banner', 'campaign'],
+		public: false,
+		uploadedAt: 'May 10, 2026',
+		usageCount: 0,
+	},
+	{
+		id: 'm12',
+		name: 'pour-shot-slowmo.mp4',
+		type: 'video',
+		src: demoMediaSource('Pour shot', '#4c0519', '#fb7185'),
+		alt: '',
+		size: 8_290_000,
+		width: 1080,
+		height: 1350,
+		duration: '0:15',
+		collection: 'Products',
+		tags: ['pour', 'social'],
+		public: true,
+		uploadedAt: 'May 8, 2026',
+		usageCount: 4,
+	},
+	{
+		id: 'm13',
+		name: 'cellar-barrels.jpg',
+		type: 'image',
+		src: demoMediaSource('Cellar barrels', '#3f2a1d', '#a16207'),
+		alt: 'Oak barrels in the aging cellar',
+		size: 874_500,
+		width: 2400,
+		height: 1600,
+		collection: 'Lifestyle',
+		tags: ['cellar', 'aging'],
+		public: true,
+		uploadedAt: 'May 5, 2026',
+		usageCount: 1,
+	},
+	{
+		id: 'm14',
+		name: 'chef-pairing-event.jpg',
+		type: 'image',
+		src: demoMediaSource('Chef pairing', '#111827', '#9ca3af'),
+		alt: 'Chef plating at pairing event',
+		size: 763_900,
+		width: 2000,
+		height: 1334,
+		collection: 'Lifestyle',
+		tags: ['event', 'pairing'],
+		public: false,
+		uploadedAt: 'May 2, 2026',
+		usageCount: 0,
+	},
+	{
+		id: 'm15',
+		name: 'bottle-trio-white.jpg',
+		type: 'image',
+		src: demoMediaSource('Bottle trio', '#f8fafc', '#64748b'),
+		alt: 'Three bottles on white backdrop',
+		size: 356_200,
+		width: 2000,
+		height: 1500,
+		collection: 'Products',
+		tags: ['trio', 'primary'],
+		public: true,
+		uploadedAt: 'Apr 29, 2026',
+		usageCount: 6,
+	},
+	{
+		id: 'm16',
+		name: 'cork-and-wax-seal.jpg',
+		type: 'image',
+		src: demoMediaSource('Wax seal', '#7f1d1d', '#f87171'),
+		alt: 'Wax seal close-up',
+		size: 298_300,
+		width: 1600,
+		height: 1600,
+		collection: 'Products',
+		tags: ['detail', 'seal'],
+		public: true,
+		uploadedAt: 'Apr 25, 2026',
+		usageCount: 1,
+	},
+	{
+		id: 'm17',
+		name: 'estate-map-illustrated.png',
+		type: 'image',
+		src: demoMediaSource('Estate map', '#0f766e', '#99f6e4'),
+		alt: 'Illustrated map of the estate',
+		size: 1_126_400,
+		width: 2400,
+		height: 1800,
+		collection: 'Banners',
+		tags: ['map', 'illustration'],
+		public: true,
+		uploadedAt: 'Apr 20, 2026',
+		usageCount: 1,
+	},
+	{
+		id: 'm18',
+		name: 'winter-campaign.jpg',
+		type: 'image',
+		src: demoMediaSource('Winter campaign', '#1e3a8a', '#bfdbfe'),
+		alt: 'Winter campaign banner',
+		size: 2_150_400,
+		width: 2880,
+		height: 1200,
+		collection: 'Banners',
+		tags: ['banner', 'seasonal'],
+		public: false,
+		uploadedAt: 'Apr 14, 2026',
+		usageCount: 0,
+	},
+];
+
+interface ExternalMediaRecord {
+	assetKey: string;
+	label: string;
+	kind: MediaLibraryItem['type'];
+	previewUrl?: string;
+	altText?: string;
+	bytes?: number;
+	folder: string;
+	references: number;
+}
+
+const externalMediaRecords: ExternalMediaRecord[] = [
+	{
+		assetKey: 'dam:landing-hero',
+		label: 'landing-page-hero.avif',
+		kind: 'image',
+		previewUrl: demoMediaSource('DAM hero', '#0f172a', '#38bdf8'),
+		altText: 'Hero image prepared by the external DAM',
+		bytes: 1_240_000,
+		folder: 'DAM / Marketing',
+		references: 14,
+	},
+	{
+		assetKey: 'dam:press-kit',
+		label: 'brand-press-kit.zip',
+		kind: 'file',
+		bytes: 4_620_000,
+		folder: 'DAM / Documents',
+		references: 6,
+	},
+];
+
+function inferUploadType(file: File): MediaLibraryItem['type'] {
+	if (file.type.startsWith('image/')) return 'image';
+	if (file.type.startsWith('video/')) return 'video';
+	return 'file';
+}
+
+function filePreview(file: File) {
+	if (!file.type.startsWith('image/')) return undefined;
+	if (typeof URL === 'undefined' || typeof URL.createObjectURL !== 'function') {
+		return undefined;
+	}
+	return URL.createObjectURL(file);
+}
+
+function uploadedItems(files: File[], options: MediaLibraryUploadOptions): MediaLibraryItem[] {
+	return files.map((file, index) => ({
+		id: `uploaded-${Date.now()}-${index}`,
+		name: file.name,
+		type: inferUploadType(file),
+		src: filePreview(file),
+		size: file.size,
+		collection: options.collection ?? 'Products',
+		tags: options.tags,
+		public: options.public,
+		uploadedAt: new Date().toISOString(),
+		usageCount: 0,
+	}));
+}
+
+function filterForFetcher(items: MediaLibraryItem[], params: MediaLibraryFetchParams) {
+	const query = params.query.trim().toLowerCase();
+	return items
+		.filter((item) => {
+			if (params.type !== 'all' && item.type !== params.type) return false;
+			if (params.collection && item.collection !== params.collection) return false;
+			if (!query) return true;
+			return [item.name, item.alt, item.collection, ...(item.tags ?? [])]
+				.filter(Boolean)
+				.join(' ')
+				.toLowerCase()
+				.includes(query);
+		})
+		.sort((a, b) => {
+			if (params.sort === 'name') return a.name.localeCompare(b.name);
+			if (params.sort === 'size') return (b.size ?? 0) - (a.size ?? 0);
+			if (params.sort === 'usage') return (b.usageCount ?? 0) - (a.usageCount ?? 0);
+			return new Date(b.uploadedAt ?? 0).getTime() - new Date(a.uploadedAt ?? 0).getTime();
+		});
+}
+
+function moveByIds(ids: string[], nextItems: MediaLibraryItem[]) {
+	const order = new Map(nextItems.map((item, index) => [item.id, index]));
+	return ids.slice().sort((a, b) => (order.get(a) ?? 0) - (order.get(b) ?? 0));
+}
+
+export function EmbeddedLibrary() {
+	const [selectedIds, setSelectedIds] = useState<string[]>(['m01']);
+
+	return (
+		<MediaLibrary
+			title="Campaign media"
+			description="Search, inspect metadata, edit alt text, and stage uploads from one surface."
+			items={mediaItems}
+			collections={collections}
+			value={selectedIds}
+			onValueChange={setSelectedIds}
+			onUpload={(files, options) => uploadedItems(files, options)}
+			onConfirm={(items) => {
+				setSelectedIds(items.map((item) => item.id));
+			}}
+			onItemUpdate={() => undefined}
+			onItemDelete={() => undefined}
+			defaultUploadOptions={{ collection: 'Products', tags: ['product'] }}
+			slots={{
+				headerEnd: (
+					<Badge variant="info">
+						<CheckCircle2 className="size-3" />
+						Admin ready
+					</Badge>
+				),
+			}}
+		/>
+	);
+}
+
+export function ProductMediaDialog() {
+	const [open, setOpen] = useState(false);
+	const [selectedIds, setSelectedIds] = useState<string[]>([
+		'm01',
+		'm03',
+	]);
+	const [primaryId, setPrimaryId] = useState('m01');
+	const selectedItems = useMemo(
+		() => mediaItems.filter((item) => selectedIds.includes(item.id)),
+		[selectedIds],
+	);
+	const handleRemove = (id: string) => {
+		setSelectedIds((current) => {
+			const next = current.filter((selectedId) => selectedId !== id);
+			if (primaryId === id) setPrimaryId(next[0] ?? '');
+			return next;
+		});
+	};
+
+	return (
+		<>
+			<MediaResourceGallery
+				items={selectedItems}
+				primaryId={primaryId}
+				title="Media"
+				description="Images and videos shown on the product page"
+				onAdd={() => setOpen(true)}
+				onPrimaryChange={setPrimaryId}
+				onRemove={handleRemove}
+				onReorder={(_, nextItems) => setSelectedIds((current) => moveByIds(current, nextItems))}
+				maxItems={5}
+			/>
+			<MediaLibraryDialog
+				open={open}
+				onOpenChange={setOpen}
+				dialogTitle="Add media"
+				dialogDescription="Pick from the library, or upload new files"
+				items={mediaItems}
+				collections={collections}
+				value={selectedIds}
+				onValueChange={setSelectedIds}
+				onConfirm={(_, ids) => {
+					setSelectedIds(ids);
+					setPrimaryId((current) => ids.includes(current) ? current : ids[0] ?? '');
+					setOpen(false);
+				}}
+				onClose={() => setOpen(false)}
+				onUpload={(files, options) => uploadedItems(files, options)}
+				defaultUploadOptions={{ collection: 'Products', public: true }}
+			/>
+		</>
+	);
+}
+
+export function ResourceGalleryList() {
+	const [selectedIds, setSelectedIds] = useState<string[]>([
+		'm04',
+		'm06',
+		'm15',
+	]);
+	const [primaryId, setPrimaryId] = useState('m04');
+	const selectedItems = useMemo(
+		() => mediaItems.filter((item) => selectedIds.includes(item.id)),
+		[selectedIds],
+	);
+
+	return (
+		<MediaResourceGallery
+			items={selectedItems}
+			primaryId={primaryId}
+			title="CMS resource gallery"
+			description="List mode keeps filenames, position, size, cover state, and row actions scannable in dense admin forms."
+			layout="list"
+			onAdd={() => undefined}
+			onPrimaryChange={setPrimaryId}
+			onRemove={(id) => setSelectedIds((current) => current.filter((selectedId) => selectedId !== id))}
+			onReorder={(_, nextItems) => setSelectedIds((current) => moveByIds(current, nextItems))}
+			maxItems={3}
+			strings={{ gallery: { maxReached: '3 of 3 attached' } }}
+		/>
+	);
+}
+
+export function ExternalResourceGallery() {
+	return (
+		<MediaResourceGallery
+			items={externalMediaRecords}
+			title="External DAM attachments"
+			description="Accessors let app-owned media records render without reshaping API responses."
+			layout="grid"
+			primaryId="dam:landing-hero"
+			readOnly
+			accessors={{
+				getId: (item) => item.assetKey,
+				getName: (item) => item.label,
+				getType: (item) => item.kind,
+				getSrc: (item) => item.previewUrl,
+				getAlt: (item) => item.altText,
+				getSize: (item) => item.bytes,
+				getCollection: (item) => item.folder,
+				getUsageCount: (item) => item.references,
+			}}
+		/>
+	);
+}
+
+export function ConfirmOnSelectDialog() {
+	const [picked, setPicked] = useState<MediaLibraryItem | null>(null);
+
+	return (
+		<SmartCard
+			icon={<Star className="size-4" />}
+			title="Single-pick strategy"
+			description="Use confirmOnSelect for avatar, cover, or logo pickers where clicking one asset should commit and close."
+			headerEnd={picked ? <Badge variant="success">{picked.name}</Badge> : <Badge variant="secondary">No asset</Badge>}
+		>
+			<MediaLibraryDialog
+				trigger={<Button type="button" icon={ImagePlus}>Pick cover</Button>}
+				items={mediaItems}
+				collections={collections}
+				selectionMode="single"
+				confirmOnSelect
+				allowUpload={false}
+				dialogTitle="Pick cover media"
+				dialogDescription="The dialog closes immediately after the selected item is confirmed."
+				onConfirm={(items) => setPicked(items[0] ?? null)}
+			/>
+		</SmartCard>
+	);
+}
+
+export function AsyncFetcherLibrary() {
+	const fetcher = useCallback(async (params: MediaLibraryFetchParams) => {
+		await new Promise((resolve) => window.setTimeout(resolve, 240));
+		const items = filterForFetcher(mediaItems, params);
+		return { items, total: items.length };
+	}, []);
+
+	return (
+		<MediaLibrary
+			title="Remote media source"
+			description="The fetcher receives query, type, collection, sort, and abort signal; the consumer owns the API call."
+			fetcher={fetcher}
+			collections={collections}
+			selectionMode="single"
+			allowUpload={false}
+			defaultView="table"
+			slots={{
+				headerStart: (
+					<span className="inline-flex size-9 items-center justify-center rounded-lg bg-info/10 text-info">
+						<Search className="size-4" />
+					</span>
+				),
+			}}
+		/>
+	);
+}
+
+export function EmptyAndErrorStates() {
+	const failingFetcher = useCallback(async () => {
+		await new Promise((resolve) => window.setTimeout(resolve, 120));
+		throw new Error('Preview fetch failed');
+	}, []);
+
+	return (
+		<div className="grid gap-4 lg:grid-cols-2">
+			<MediaLibrary
+				title="Empty asset library"
+				description="Empty state gives users a route into upload when no assets exist yet."
+				items={[]}
+				collections={collections}
+				heightClassName="h-[520px]"
+			/>
+			<MediaLibrary
+				title="Remote error"
+				description="Fetcher errors render a tokenized alert while the consumer handles retry strategy."
+				fetcher={failingFetcher}
+				collections={collections}
+				allowUpload={false}
+				heightClassName="h-[520px]"
+			/>
+		</div>
+	);
+}
+
+export function HeadlessSelection() {
+	const state = useMediaLibrary({
+		items: mediaItems,
+		selectionMode: 'single',
+		defaultValue: ['m04'],
+		defaultType: 'image',
+	});
+
+	return (
+		<SmartCard
+			icon={<Images className="size-4" />}
+			title="Headless selection"
+			description="useMediaLibrary exposes the same filtering, selection, and accessors for custom layouts."
+			headerEnd={<Badge variant="secondary">{state.visibleItems.length} images</Badge>}
+		>
+			<div className="grid gap-3 sm:grid-cols-4">
+				{state.visibleItems.slice(0, 4).map((item) => {
+					const id = state.accessors.getId(item);
+					return (
+						<MediaLibraryCard
+							key={id}
+							item={item}
+							selected={state.selectedSet.has(id)}
+							selectionMode="single"
+							accessors={state.accessors}
+							strings={defaultMediaLibraryStrings}
+							onToggle={() => state.toggleSelection(id)}
+							onDetails={() => state.setDetailId(id)}
+						/>
+					);
+				})}
+			</div>
+			<div className="mt-3 flex items-center justify-between rounded-lg border border-border bg-muted/20 px-3 py-2">
+				<Text size="xs" type="secondary">
+					Selected: {state.selectedItems[0] ? state.accessors.getName(state.selectedItems[0]) : 'None'}
+				</Text>
+				<Button
+					type="button"
+					variant="secondary"
+					buttonStyle="ghost"
+					icon={UploadCloud}
+					onClick={state.clearSelection}
+				>
+					Clear
+				</Button>
+			</div>
+		</SmartCard>
+	);
+}
+```
+
+## Example exports
+
+- `EmbeddedLibrary`
+- `ProductMediaDialog`
+- `ResourceGalleryList`
+- `ExternalResourceGallery`
+- `ConfirmOnSelectDialog`
+- `AsyncFetcherLibrary`
+- `EmptyAndErrorStates`
+- `HeadlessSelection`
+