themelia-ui 2.0.0 → 3.0.0

package/.agents/skills/themelia-ui/references/components/features--media-library.md

@@ -1,987 +0,0 @@
-<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
-
-# `features/media-library`
-
-Existing assets are browsed, previewed, searched and picked.
-
-## Selection
-
-- **Use when:** Existing assets are browsed, previewed, searched and picked.
-- **Avoid when:** The user is contributing new files, or one image is being replaced.
-- **Consider instead:** `base/upload`
-- **Stability:** stable.
-
-## Import
-
-```tsx fragment — import-only example
-import { MediaLibrary } from "themelia-ui/features/media-library"
-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`.
-
-Application policy—routing, fetching, persistence, permissions, and translation—stays
-outside the package and arrives through the public props, callbacks, slots, or accessors below.
-
-## Public declarations
-
-### `defaultMediaLibraryStrings`
-
-Kind: const.
-
-```text
-{ title: string; description: string; tabs: { library: string; upload: string; }; views: { grid: string; table: string; list: string; }; selectVisible: string; deselectVisible: string; refreshError: string; table: { name: string; collection: string; size: string; uploaded: string; usage: string; actions: string; }; searchPlaceholder: string; clearSearch: string; clearFilters: string; types: { all: string; image: string; video: string; file: string; }; sorts: { newest: string; name: string; size: string; usage: string; }; collectionAll: string; collectionLabel: string; sortLabel: string; typeLabel: string; viewLabel: string; activeSearchLabel: string; loading: string; error: string; retry: string; emptyTitle: string; emptyDescription: string; emptyFilteredTitle: string; emptyFilteredDescription: string; selectedCount: (count: number) => string; showingCount: (shown: number, total: number) => string; select: string; deselect: string; assetAction: (action: string, name: string) => string; details: string; close: string; confirm: string; cancel: string; clearSelection: string; footer: { pickOne: string; pickMany: string; noFiles: string; stagedSummary: (count: number, size: string) => string; uploadStaged: (count: number) => string; }; detail: { 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: { 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: { title: string; description: string; add: string; remove: string; primary: string; makePrimary: string; moveEarlier: string; moveLater: string; emptyTitle: string; emptyDescription: string; limitReached: (max: number) => string; }; }
-```
-
-### `formatMediaLibrarySize`
-
-Kind: callable.
-
-```text
-(bytes?: number) => string
-```
-
-### `getMediaLibraryDimensions`
-
-Kind: callable.
-
-```text
-(item: TItem, accessors: ResolvedMediaLibraryAccessors<TItem>) => string
-```
-
-### `MediaLibrary`
-
-Kind: callable.
-
-```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
-```
-
-### `MediaLibraryAccessors`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `getId` | no | `(item: TItem) => string` |  |
-| `getName` | no | `(item: TItem) => string` |  |
-| `getType` | no | `(item: TItem) => MediaLibraryItemType` |  |
-| `getSrc` | no | `(item: TItem) => string \| undefined` |  |
-| `getAlt` | no | `(item: TItem) => string \| undefined` |  |
-| `getSize` | no | `(item: TItem) => number \| undefined` |  |
-| `getWidth` | no | `(item: TItem) => number \| undefined` |  |
-| `getHeight` | no | `(item: TItem) => number \| undefined` |  |
-| `getDuration` | no | `(item: TItem) => string \| undefined` |  |
-| `getCollection` | no | `(item: TItem) => string \| undefined` |  |
-| `getTags` | no | `(item: TItem) => string[]` |  |
-| `getPublic` | no | `(item: TItem) => boolean \| undefined` |  |
-| `getUploadedAt` | no | `(item: TItem) => Date \| string \| undefined` |  |
-| `getUsageCount` | no | `(item: TItem) => number \| undefined` |  |
-| `getTint` | no | `(item: TItem) => string \| undefined` |  |
-| `getMimeType` | no | `(item: TItem) => string \| undefined` |  |
-
-### `MediaLibraryBulkActionContext`
-
-Kind: interface.
-
-What a bulk action is handed; mirrors the product variants' context.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `selectedItems` | yes | `TItem[]` |  |
-| `selectedIds` | yes | `string[]` |  |
-| `selectedCount` | yes | `number` |  |
-| `visibleCount` | yes | `number` | Items passing the current filters, not the whole library. |
-| `totalCount` | yes | `number` |  |
-| `clearSelection` | yes | `() => void` |  |
-
-### `MediaLibraryCard`
-
-Kind: callable.
-
-```text
-({ item, selected, density, showMeta, accessors, strings, onToggle, onDetails, className, }: MediaLibraryCardProps<TItem>) => import("react").JSX.Element
-```
-
-### `MediaLibraryCardProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `item` | yes | `TItem` |  |
-| `selected` | no | `boolean` |  |
-| `density` | no | `MediaLibraryDensity` |  |
-| `showMeta` | no | `boolean` |  |
-| `selectionMode` | no | `MediaLibrarySelectionMode` |  |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `onToggle` | no | `() => void` |  |
-| `onDetails` | no | `() => void` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibraryCollectionOption`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `value` | yes | `string` |  |
-| `label` | yes | `ReactNode` |  |
-
-### `MediaLibraryDensity`
-
-Kind: type.
-
-```text
-"comfortable" | "compact"
-```
-
-### `MediaLibraryDetailPanel`
-
-Kind: callable.
-
-```text
-({ item, collections, accessors, strings, onClose, onUpdate, onRemove, renderDetail }: MediaLibraryDetailPanelProps<TItem>) => import("react").JSX.Element | null
-```
-
-### `MediaLibraryDetailPanelProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `item` | yes | `TItem \| null` |  |
-| `collections` | no | `readonly MediaLibraryCollectionOption[]` |  |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `onClose` | yes | `() => void` |  |
-| `onUpdate` | yes | `(patch: MediaLibraryItemPatch) => Promise<boolean>` |  |
-| `onRemove` | yes | `() => Promise<boolean>` |  |
-| `renderDetail` | no | `MediaLibrarySlots<TItem>["renderDetail"]` |  |
-
-### `MediaLibraryDetailRenderContext`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-| `update` | yes | `(patch: MediaLibraryItemPatch) => Promise<boolean>` | Resolves `false` after a rollback when the consumer's mutation failed. |
-| `remove` | yes | `() => Promise<boolean>` |  |
-| `close` | yes | `() => void` |  |
-
-### `MediaLibraryDialog`
-
-Kind: callable.
-
-The same library in a modal, for picking assets from elsewhere on a page.
-
-```text
-({ open, onOpenChange, trigger, dialogTitle, dialogDescription, dialogClassName, contentClassName, closeOnEscape, closeOnBackdropClick, onClose, strings, ...props }: MediaLibraryDialogProps<TItem>) => import("react").JSX.Element
-```
-
-### `MediaLibraryDialogProps`
-
-Kind: interface.
-
-Extends: `Omit<MediaLibraryProps<TItem>, "title" | "description">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `open` | no | `boolean` |  |
-| `onOpenChange` | no | `(open: boolean) => void` |  |
-| `trigger` | no | `ReactNode` |  |
-| `dialogTitle` | no | `string` |  |
-| `dialogDescription` | no | `string` |  |
-| `dialogClassName` | no | `string` |  |
-| `contentClassName` | no | `string` |  |
-| `closeOnEscape` | no | `boolean` |  |
-| `closeOnBackdropClick` | no | `boolean` |  |
-
-### `MediaLibraryEmptyState`
-
-Kind: callable.
-
-The browser's empty state: bordered and inset, since it stands in for a grid.
-
-```text
-({ title, description, icon, action, className, }: MediaLibraryEmptyStateProps) => import("react").JSX.Element
-```
-
-### `MediaLibraryEmptyStateProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | yes | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `icon` | no | `ReactNode` |  |
-| `action` | no | `ReactNode` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibraryFetcher`
-
-Kind: type.
-
-A bare array is accepted too, for a fetcher with nothing to say about totals.
-
-```text
-(params: MediaLibraryFetchParams) => Promise<MediaLibraryFetchResult<TItem> | TItem[]>
-```
-
-### `MediaLibraryFetchParams`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `query` | yes | `string` |  |
-| `type` | yes | `MediaLibraryTypeFilter` |  |
-| `collection` | no | `string` | `undefined` rather than "all", so a server need not know that word. |
-| `sort` | yes | `MediaLibrarySort` |  |
-| `limit` | no | `number` |  |
-| `signal` | no | `AbortSignal` |  |
-
-### `MediaLibraryFetchResult`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `items` | yes | `TItem[]` |  |
-| `total` | no | `number` | Across every page. Without it the count reflects only what is loaded. |
-
-### `MediaLibraryFooter`
-
-Kind: callable.
-
-```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
-```
-
-### `MediaLibraryFooterActions`
-
-Kind: callable.
-
-```text
-({ tab, selectedIds, selectedItems, stagedFiles, uploading, strings, confirmLabel, cancelLabel, onCancel, onConfirm, onUpload, onCancelUpload, className, }: MediaLibraryFooterActionsProps<TItem>) => import("react").JSX.Element
-```
-
-### `MediaLibraryFooterActionsProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `tab` | yes | `MediaLibraryTab` |  |
-| `selectedItems` | yes | `readonly TItem[]` |  |
-| `selectedIds` | yes | `readonly string[]` |  |
-| `stagedFiles` | yes | `readonly MediaLibraryStagedFile[]` |  |
-| `uploading` | no | `boolean` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `confirmLabel` | no | `ReactNode` |  |
-| `cancelLabel` | no | `ReactNode` |  |
-| `onCancel` | no | `() => void` |  |
-| `onConfirm` | no | `() => void` |  |
-| `onUpload` | no | `() => void` |  |
-| `onCancelUpload` | no | `() => void` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibraryFooterProps`
-
-Kind: interface.
-
-Extends: `MediaLibraryFooterSummaryProps`, `Omit<MediaLibraryFooterActionsProps<TItem>, "className">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `chrome` | no | `"section" \| "bare"` | `section` draws the rule and the inset; `bare` leaves both to a surrounding shell. |
-
-### `MediaLibraryFooterSummary`
-
-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.
-
-```text
-({ tab, selectedIds, selectionMode, stagedFiles, strings, visibleCount, totalCount, onClearSelection, className, }: MediaLibraryFooterSummaryProps) => import("react").JSX.Element
-```
-
-### `MediaLibraryFooterSummaryProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `tab` | yes | `MediaLibraryTab` |  |
-| `selectedIds` | yes | `readonly string[]` |  |
-| `selectionMode` | yes | `MediaLibrarySelectionMode` |  |
-| `stagedFiles` | yes | `readonly MediaLibraryStagedFile[]` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `visibleCount` | no | `number` | With nothing selected and a filter on, the count replaces the hint. |
-| `totalCount` | no | `number` |  |
-| `onClearSelection` | no | `() => void` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibraryGrid`
-
-Kind: callable.
-
-```text
-({ items, selectedSet, accessors, strings, onToggle, onDetails, density, selectionMode, showMeta, renderItem, className }: MediaLibraryGridProps<TItem>) => import("react").JSX.Element
-```
-
-### `MediaLibraryGridProps`
-
-Kind: interface.
-
-Extends: `MediaLibraryListProps<TItem>`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `density` | no | `MediaLibraryDensity` |  |
-| `showMeta` | no | `boolean` |  |
-| `renderItem` | no | `MediaLibrarySlots<TItem>["renderItem"]` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibraryItem`
-
-Kind: interface.
-
-The default shape, and what the default accessors read.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `name` | yes | `string` |  |
-| `type` | yes | `MediaLibraryItemType` |  |
-| `src` | no | `string` |  |
-| `alt` | no | `string` |  |
-| `size` | no | `number` | In bytes. |
-| `width` | no | `number` |  |
-| `height` | no | `number` |  |
-| `duration` | no | `string` |  |
-| `collection` | no | `string` |  |
-| `tags` | no | `string[]` |  |
-| `public` | no | `boolean` |  |
-| `uploadedAt` | no | `Date \| string` |  |
-| `usageCount` | no | `number` | How many places reference it; decides whether a delete is safe. |
-| `tint` | no | `string` | A placeholder colour for an asset with no preview. |
-| `mimeType` | no | `string` |  |
-
-### `MediaLibraryItemPatch`
-
-Kind: interface.
-
-The editable fields. Everything else about an asset belongs to whatever made it.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `alt` | no | `string` |  |
-| `collection` | no | `string` |  |
-| `tags` | no | `string[]` |  |
-| `public` | no | `boolean` |  |
-
-### `MediaLibraryItemRenderContext`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `selected` | yes | `boolean` |  |
-| `selectionMode` | yes | `MediaLibrarySelectionMode` |  |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-| `toggle` | yes | `() => void` |  |
-| `openDetails` | yes | `() => void` |  |
-
-### `MediaLibraryItemType`
-
-Kind: type.
-
-```text
-"image" | "video" | "file"
-```
-
-### `MediaLibraryList`
-
-Kind: callable.
-
-```text
-({ items, selectedSet, accessors, strings, onToggle, onDetails, }: MediaLibraryListProps<TItem>) => import("react").JSX.Element
-```
-
-### `MediaLibraryListProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `items` | yes | `readonly TItem[]` |  |
-| `selectedSet` | yes | `Set<string>` |  |
-| `selectionMode` | no | `MediaLibrarySelectionMode` |  |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `onToggle` | yes | `(id: string) => void` |  |
-| `onDetails` | yes | `(id: string) => void` |  |
-
-### `MediaLibraryProps`
-
-Kind: interface.
-
-Extends: `Omit<ComponentPropsWithoutRef<"section">, "children" | "defaultValue" | "onError" | "onSelect" | "title">`, `UseMediaLibraryOptions<TItem>`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `title` | no | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `confirmLabel` | no | `ReactNode` |  |
-| `cancelLabel` | no | `ReactNode` |  |
-| `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. |
-| `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>` |  |
-
-### `MediaLibrarySelectionBar`
-
-Kind: callable.
-
-```text
-({ visibleCount, totalCount, selectedVisibleCount, onSelectVisible, onDeselectVisible, status, disabled, strings, className }: MediaLibrarySelectionBarProps) => import("react").JSX.Element
-```
-
-### `MediaLibrarySelectionBarProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `visibleCount` | yes | `number` |  |
-| `totalCount` | yes | `number` |  |
-| `selectedVisibleCount` | yes | `number` |  |
-| `onSelectVisible` | no | `() => void` |  |
-| `onDeselectVisible` | no | `() => void` |  |
-| `status` | no | `ReactNode` |  |
-| `disabled` | no | `boolean` |  |
-| `strings` | no | `Partial<MediaLibraryStrings>` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibrarySelectionMode`
-
-Kind: type.
-
-```text
-"single" | "multiple"
-```
-
-### `MediaLibrarySlots`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `headerStart` | no | `ReactNode` |  |
-| `headerEnd` | no | `ReactNode` |  |
-| `toolbarEnd` | no | `ReactNode` |  |
-| `empty` | no | `ReactNode` |  |
-| `loading` | no | `ReactNode` |  |
-| `error` | no | `ReactNode` |  |
-| `footer` | no | `ReactNode` |  |
-| `uploadEmpty` | no | `ReactNode` |  |
-| `renderItem` | no | `(item: TItem, context: MediaLibraryItemRenderContext<TItem>) => ReactNode` |  |
-| `renderDetail` | no | `(item: TItem, context: MediaLibraryDetailRenderContext<TItem>) => ReactNode` |  |
-
-### `MediaLibrarySort`
-
-Kind: type.
-
-```text
-"newest" | "name" | "size" | "usage"
-```
-
-### `MediaLibraryStagedFile`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `file` | yes | `File` |  |
-| `name` | yes | `string` |  |
-| `size` | yes | `number` |  |
-| `type` | yes | `MediaLibraryItemType` |  |
-| `src` | no | `string` | An object URL for an image preview. Revoked when the file leaves. |
-| `progress` | yes | `number` |  |
-| `status` | yes | `MediaLibraryUploadStatus` |  |
-| `error` | no | `string` |  |
-
-### `MediaLibraryState`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `tab` | yes | `MediaLibraryTab` |  |
-| `setTab` | yes | `(tab: MediaLibraryTab) => void` |  |
-| `view` | yes | `MediaLibraryView` |  |
-| `setView` | yes | `(view: MediaLibraryView) => void` |  |
-| `query` | yes | `string` |  |
-| `setQuery` | yes | `(query: string) => void` |  |
-| `type` | yes | `MediaLibraryTypeFilter` |  |
-| `setType` | yes | `(type: MediaLibraryTypeFilter) => void` |  |
-| `collection` | yes | `string` |  |
-| `setCollection` | yes | `(collection: string) => void` |  |
-| `sort` | yes | `MediaLibrarySort` |  |
-| `setSort` | yes | `(sort: MediaLibrarySort) => void` |  |
-| `detailId` | yes | `string \| null` |  |
-| `setDetailId` | yes | `(id: string \| null) => void` |  |
-| `items` | yes | `TItem[]` | Every asset, after local edits and deletions. |
-| `visibleItems` | yes | `TItem[]` | What the current filters and sort leave. |
-| `selectedIds` | yes | `string[]` |  |
-| `selectedItems` | yes | `TItem[]` |  |
-| `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` |  |
-| `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. |
-| `hasFilters` | yes | `boolean` |  |
-| `totalCount` | yes | `number` |  |
-| `filteredCount` | yes | `number` |  |
-| `stagedFiles` | yes | `MediaLibraryStagedFile[]` |  |
-| `addFiles` | yes | `(files: File[]) => void` |  |
-| `removeStagedFile` | yes | `(id: string) => void` |  |
-| `clearStagedFiles` | yes | `() => void` |  |
-| `uploadOptions` | yes | `MediaLibraryUploadOptions` |  |
-| `updateUploadOptions` | yes | `(patch: Partial<MediaLibraryUploadOptions>) => void` |  |
-| `uploading` | yes | `boolean` |  |
-| `startUpload` | yes | `() => Promise<void>` |  |
-| `cancelUpload` | yes | `() => void` |  |
-| `updateItem` | yes | `(item: TItem, patch: MediaLibraryItemPatch) => Promise<boolean>` |  |
-| `removeItem` | yes | `(item: TItem) => Promise<boolean>` |  |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-
-### `MediaLibraryStrings`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `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; }` |  |
-| `searchPlaceholder` | yes | `string` |  |
-| `clearSearch` | yes | `string` |  |
-| `clearFilters` | yes | `string` |  |
-| `types` | yes | `{ all: string; image: string; video: string; file: string; }` |  |
-| `sorts` | yes | `{ newest: string; name: string; size: string; usage: string; }` |  |
-| `collectionAll` | yes | `string` |  |
-| `collectionLabel` | yes | `string` |  |
-| `sortLabel` | yes | `string` |  |
-| `typeLabel` | yes | `string` |  |
-| `viewLabel` | yes | `string` |  |
-| `activeSearchLabel` | yes | `string` |  |
-| `loading` | yes | `string` |  |
-| `error` | yes | `string` |  |
-| `retry` | no | `string` | Optional so existing complete translations keep working; defaults to "Try again". |
-| `emptyTitle` | yes | `string` |  |
-| `emptyDescription` | yes | `string` |  |
-| `emptyFilteredTitle` | yes | `string` |  |
-| `emptyFilteredDescription` | yes | `string` |  |
-| `selectedCount` | yes | `(count: number) => string` |  |
-| `showingCount` | yes | `(shown: number, total: number) => string` |  |
-| `select` | yes | `string` |  |
-| `deselect` | yes | `string` |  |
-| `assetAction` | no | `(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; }` |  |
-| `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; }` |  |
-
-### `MediaLibraryTab`
-
-Kind: type.
-
-```text
-"library" | "upload"
-```
-
-### `MediaLibraryTable`
-
-Kind: callable.
-
-A metadata table for inspecting assets; selection and details remain separate controls.
-
-```text
-({ items, selectedSet, accessors, strings, onToggle, onDetails, className, collections }: MediaLibraryTableProps<TItem>) => import("react").JSX.Element
-```
-
-### `MediaLibraryTableProps`
-
-Kind: interface.
-
-Extends: `MediaLibraryListProps<TItem>`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `className` | no | `string` |  |
-| `collections` | no | `readonly MediaLibraryCollectionOption[]` |  |
-
-### `MediaLibraryToolbar`
-
-Kind: callable.
-
-```text
-({ query, onQueryChange, type, onTypeChange, typeFilters, collection, onCollectionChange, collections, sort, onSortChange, view, onViewChange, hasFilters, onClearFilters, strings, end, className, }: MediaLibraryToolbarProps) => import("react").JSX.Element
-```
-
-### `MediaLibraryToolbarProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `query` | yes | `string` |  |
-| `onQueryChange` | yes | `(query: string) => void` |  |
-| `type` | yes | `MediaLibraryTypeFilter` |  |
-| `onTypeChange` | yes | `(type: MediaLibraryTypeFilter) => void` |  |
-| `typeFilters` | yes | `readonly MediaLibraryTypeFilter[]` |  |
-| `collection` | yes | `string` |  |
-| `onCollectionChange` | yes | `(collection: string) => void` |  |
-| `collections` | yes | `readonly MediaLibraryCollectionOption[]` |  |
-| `sort` | yes | `MediaLibrarySort` |  |
-| `onSortChange` | yes | `(sort: MediaLibrarySort) => void` |  |
-| `view` | yes | `MediaLibraryView` |  |
-| `onViewChange` | yes | `(view: MediaLibraryView) => void` |  |
-| `hasFilters` | yes | `boolean` |  |
-| `onClearFilters` | yes | `() => void` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `end` | no | `ReactNode` |  |
-| `className` | no | `string` |  |
-
-### `MediaLibraryTypeFilter`
-
-Kind: type.
-
-```text
-"all" | MediaLibraryItemType
-```
-
-### `MediaLibraryUploadHandler`
-
-Kind: type.
-
-Returning the created items adds AND selects them; returning nothing just finishes.
-
-```text
-(files: File[], options: MediaLibraryUploadOptions, helpers: MediaLibraryUploadHelpers) => Promise<TItem[] | void> | TItem[] | void
-```
-
-### `MediaLibraryUploadHelpers`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `files` | no | `readonly MediaLibraryStagedFile[]` | Stable IDs for the submitted batch, used by the progress/status callbacks. |
-| `signal` | yes | `AbortSignal` | Aborted when the reader cancels, or when the library unmounts. |
-| `setProgress` | yes | `(fileId: string, progress: number) => void` |  |
-| `setFileStatus` | yes | `(fileId: string, status: MediaLibraryUploadStatus, error?: string) => void` |  |
-
-### `MediaLibraryUploadOptions`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `collection` | no | `string` |  |
-| `tags` | yes | `string[]` |  |
-| `public` | yes | `boolean` |  |
-
-### `MediaLibraryUploadPanel`
-
-Kind: callable.
-
-```text
-({ stagedFiles, uploading, uploadOptions, collections, strings, onAddFiles, onRemoveFile, onClear, onOptionsChange, onStart, onCancel, empty, showActions, }: MediaLibraryUploadPanelProps) => import("react").JSX.Element
-```
-
-### `MediaLibraryUploadPanelProps`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `showActions` | no | `boolean` | Hide when a composed picker footer owns upload actions. |
-| `stagedFiles` | yes | `MediaLibraryStagedFile[]` |  |
-| `uploading` | yes | `boolean` |  |
-| `uploadOptions` | yes | `MediaLibraryUploadOptions` |  |
-| `collections` | no | `readonly MediaLibraryCollectionOption[]` |  |
-| `strings` | yes | `MediaLibraryStrings` |  |
-| `onAddFiles` | yes | `(files: File[]) => void` |  |
-| `onRemoveFile` | yes | `(id: string) => void` |  |
-| `onClear` | yes | `() => void` |  |
-| `onOptionsChange` | yes | `(patch: Partial<MediaLibraryUploadOptions>) => void` |  |
-| `onStart` | yes | `() => void` |  |
-| `onCancel` | yes | `() => void` |  |
-| `empty` | no | `ReactNode` |  |
-
-### `MediaLibraryUploadStatus`
-
-Kind: type.
-
-```text
-"staged" | "uploading" | "done" | "error"
-```
-
-### `MediaLibraryView`
-
-Kind: type.
-
-```text
-"grid" | "table" | "list"
-```
-
-### `MediaPreview`
-
-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.
-
-```text
-({ item, accessors, className, }: { item: TItem; accessors: ResolvedMediaLibraryAccessors<TItem>; className?: string; }) => import("react").JSX.Element
-```
-
-### `MediaResourceGallery`
-
-Kind: callable.
-
-```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
-```
-
-### `MediaResourceGalleryItemRenderContext`
-
-Kind: interface.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `id` | yes | `string` |  |
-| `index` | yes | `number` |  |
-| `total` | yes | `number` |  |
-| `primary` | yes | `boolean` |  |
-| `accessors` | yes | `ResolvedMediaLibraryAccessors<TItem>` |  |
-| `canMovePrevious` | yes | `boolean` |  |
-| `canMoveNext` | yes | `boolean` |  |
-| `setPrimary` | yes | `() => void` |  |
-| `remove` | yes | `() => void` |  |
-| `movePrevious` | yes | `() => void` |  |
-| `moveNext` | yes | `() => void` |  |
-
-### `MediaResourceGalleryLayout`
-
-Kind: type.
-
-```text
-"field" | "grid" | "list"
-```
-
-### `MediaResourceGalleryProps`
-
-Kind: interface.
-
-Extends: `Omit<ComponentPropsWithoutRef<"section">, "children" | "title">`.
-
-| member | required | type | description / documented default |
-| --- | :-: | --- | --- |
-| `items` | yes | `readonly TItem[]` |  |
-| `accessors` | no | `MediaLibraryAccessors<TItem>` |  |
-| `title` | no | `ReactNode` |  |
-| `description` | no | `ReactNode` |  |
-| `primaryId` | no | `string` | The cover. |
-| `onPrimaryChange` | no | `(id: string, item: TItem) => void` |  |
-| `onRemove` | no | `(id: string, item: TItem) => void` |  |
-| `onReorder` | no | `(ids: string[], items: TItem[]) => void` |  |
-| `onAdd` | no | `() => void` | Usually opens the library dialog. |
-| `maxItems` | no | `number` | The add control hides once reached. |
-| `layout` | no | `MediaResourceGalleryLayout` |  |
-| `density` | no | `MediaLibraryDensity` |  |
-| `readOnly` | no | `boolean` |  |
-| `empty` | no | `ReactNode` |  |
-| `action` | no | `ReactNode` |  |
-| `renderItem` | no | `(item: TItem, context: MediaResourceGalleryItemRenderContext<TItem>) => ReactNode` |  |
-| `strings` | no | `Partial<MediaLibraryStrings>` |  |
-
-### `ResolvedMediaLibraryAccessors`
-
-Kind: type.
-
-```text
-Required<MediaLibraryAccessors<TItem>>
-```
-
-### `resolveMediaLibraryAccessors`
-
-Kind: callable.
-
-```text
-(accessors?: MediaLibraryAccessors<TItem>) => ResolvedMediaLibraryAccessors<TItem>
-```
-
-### `useMediaLibrary`
-
-Kind: callable.
-
-```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>
-```
-
-### `UseMediaLibraryOptions`
-
-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>` |  |
-| `onError` | no | `(error: unknown) => void` | Receives failures from the fetcher, uploads, updates, and deletes. |
-| `tab` | no | `MediaLibraryTab` |  |
-| `defaultTab` | no | `MediaLibraryTab` |  |
-| `onTabChange` | no | `(tab: MediaLibraryTab) => void` |  |
-| `view` | no | `MediaLibraryView` |  |
-| `defaultView` | no | `MediaLibraryView` |  |
-| `onViewChange` | no | `(view: MediaLibraryView) => void` |  |
-| `query` | no | `string` |  |
-| `defaultQuery` | no | `string` |  |
-| `onQueryChange` | no | `(query: string) => void` |  |
-| `type` | no | `MediaLibraryTypeFilter` |  |
-| `defaultType` | no | `MediaLibraryTypeFilter` |  |
-| `onTypeChange` | no | `(type: MediaLibraryTypeFilter) => void` |  |
-| `collection` | no | `string` |  |
-| `defaultCollection` | no | `string` |  |
-| `onCollectionChange` | no | `(collection: string) => void` |  |
-| `sort` | no | `MediaLibrarySort` |  |
-| `defaultSort` | no | `MediaLibrarySort` |  |
-| `onSortChange` | no | `(sort: MediaLibrarySort) => void` |  |
-| `uploadOptions` | no | `Partial<MediaLibraryUploadOptions>` |  |
-| `defaultUploadOptions` | no | `Partial<MediaLibraryUploadOptions>` |  |
-| `onUploadOptionsChange` | no | `(options: MediaLibraryUploadOptions) => void` |  |
-
-## Preview recipes
-
-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)}
-/>
-```
-
-### 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" }}
-/>
-```
-
-### 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>
-    </>
-  )}
-/>
-```
-
-### 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)}
-/>
-```
-
-### 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}
-/>
-```