themelia-react-ui 0.0.0-stage → 1.0.0

package/dist/components/features/media-library/media-library.types.d.ts

@@ -0,0 +1,568 @@
+import type { ComponentPropsWithoutRef, KeyboardEvent, ReactNode } from 'react';
+import type { StringsProp } from '../../../lib/strings';
+import type { MediaLibraryStrings } from './media-library.strings';
+export type MediaLibraryItemType = 'image' | 'video' | 'file';
+export type MediaLibrarySelectionMode = 'single' | 'multiple';
+export type MediaLibraryView = 'grid' | 'table';
+export type MediaLibraryTab = 'library' | 'upload';
+export type MediaLibraryDensity = 'comfortable' | 'compact';
+export type MediaResourceGalleryLayout = 'field' | 'grid' | 'list';
+export type MediaLibrarySort = 'newest' | 'name' | 'size' | 'usage';
+export type MediaLibraryTypeFilter = 'all' | MediaLibraryItemType;
+export type MediaLibraryUploadStatus = 'staged' | 'uploading' | 'done' | 'error';
+export interface MediaLibraryItem {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display name. */
+    name: string;
+    /** Current type filter. */
+    type: MediaLibraryItemType;
+    src?: string;
+    alt?: string;
+    /** Size preset. */
+    size?: number;
+    width?: number;
+    height?: number;
+    duration?: string;
+    /** Current collection filter. */
+    collection?: string;
+    tags?: string[];
+    public?: boolean;
+    uploadedAt?: Date | string;
+    usageCount?: number;
+    tint?: string;
+    mimeType?: string;
+}
+export interface MediaLibraryItemPatch {
+    alt?: string;
+    /** Current collection filter. */
+    collection?: string;
+    tags?: string[];
+    public?: boolean;
+}
+export interface MediaLibraryCollectionOption {
+    /** Current value. Controlled. */
+    value: string;
+    /** Display label. */
+    label: ReactNode;
+}
+export interface MediaLibraryUploadOptions {
+    /** Current collection filter. */
+    collection?: string;
+    tags: string[];
+    public: boolean;
+}
+export interface MediaLibraryStagedFile {
+    /** Stable identity for this entry. */
+    id: string;
+    file: File;
+    /** Display name. */
+    name: string;
+    /** Size preset. */
+    size: number;
+    /** Current type filter. */
+    type: MediaLibraryItemType;
+    src?: string;
+    progress: number;
+    status: MediaLibraryUploadStatus;
+    error?: string;
+}
+export interface MediaLibraryFetchParams {
+    /** Current search text. */
+    query: string;
+    /** Current type filter. */
+    type: MediaLibraryTypeFilter;
+    /** Current collection filter. */
+    collection?: string;
+    /** Current sort order. */
+    sort: MediaLibrarySort;
+    limit?: number;
+    signal?: AbortSignal;
+}
+export interface MediaLibraryFetchResult<TItem = MediaLibraryItem> {
+    /** Assets to render. */
+    items: TItem[];
+    /** Total number of records across all pages. */
+    total?: number;
+}
+export type MediaLibraryFetcher<TItem = MediaLibraryItem> = (params: MediaLibraryFetchParams) => Promise<MediaLibraryFetchResult<TItem> | TItem[]>;
+export interface MediaLibraryUploadHelpers {
+    /** Aborted when the user cancels or the media-library instance unmounts. */
+    signal: AbortSignal;
+    setProgress: (fileId: string, progress: number) => void;
+    setFileStatus: (fileId: string, status: MediaLibraryUploadStatus, error?: string) => void;
+}
+export type MediaLibraryUploadHandler<TItem = MediaLibraryItem> = (files: File[], options: MediaLibraryUploadOptions, helpers: MediaLibraryUploadHelpers) => Promise<TItem[] | void> | TItem[] | void;
+export interface MediaLibraryAccessors<TItem = MediaLibraryItem> {
+    getId?: (item: TItem) => string;
+    getName?: (item: TItem) => string;
+    getType?: (item: TItem) => MediaLibraryItemType;
+    getSrc?: (item: TItem) => string | undefined;
+    getAlt?: (item: TItem) => string | undefined;
+    getSize?: (item: TItem) => number | undefined;
+    getWidth?: (item: TItem) => number | undefined;
+    getHeight?: (item: TItem) => number | undefined;
+    getDuration?: (item: TItem) => string | undefined;
+    getCollection?: (item: TItem) => string | undefined;
+    getTags?: (item: TItem) => string[];
+    getPublic?: (item: TItem) => boolean | undefined;
+    getUploadedAt?: (item: TItem) => Date | string | undefined;
+    getUsageCount?: (item: TItem) => number | undefined;
+    getTint?: (item: TItem) => string | undefined;
+    getMimeType?: (item: TItem) => string | undefined;
+}
+export type ResolvedMediaLibraryAccessors<TItem = MediaLibraryItem> = Required<MediaLibraryAccessors<TItem>>;
+export interface MediaLibrarySlots<TItem = MediaLibraryItem> {
+    headerStart?: ReactNode;
+    /** Content at the end of the header, before the overflow menu. */
+    headerEnd?: ReactNode;
+    /** Content at the end of the toolbar row. */
+    toolbarEnd?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    loading?: ReactNode;
+    error?: ReactNode;
+    /** Content below the body. */
+    footer?: ReactNode;
+    uploadEmpty?: ReactNode;
+    /** Replaces the default item rendering. */
+    renderItem?: (
+    /** The asset this row or card represents. */
+    item: TItem, ctx: MediaLibraryItemRenderContext<TItem>) => ReactNode;
+    /** Replaces the default detail rendering. */
+    renderDetail?: (
+    /** The asset this row or card represents. */
+    item: TItem, ctx: MediaLibraryDetailRenderContext<TItem>) => ReactNode;
+}
+export interface MediaLibraryItemRenderContext<TItem = MediaLibraryItem> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Whether the entry is selected. */
+    selected: boolean;
+    /** Whether one asset or several can be selected at a time. */
+    selectionMode: MediaLibrarySelectionMode;
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+    toggle: () => void;
+    openDetails: () => void;
+}
+export interface MediaLibraryDetailRenderContext<TItem = MediaLibraryItem> {
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+    update: (patch: MediaLibraryItemPatch) => Promise<boolean>;
+    remove: () => Promise<boolean>;
+    close: () => void;
+}
+export interface MediaLibraryState<TItem = MediaLibraryItem> {
+    /** Which tab is showing — browse or upload. */
+    tab: MediaLibraryTab;
+    setTab: (tab: MediaLibraryTab) => void;
+    /** Whether the browser is showing the grid or the table. */
+    view: MediaLibraryView;
+    setView: (view: MediaLibraryView) => void;
+    /** Current search text. */
+    query: string;
+    setQuery: (query: string) => void;
+    /** Current type filter. */
+    type: MediaLibraryTypeFilter;
+    setType: (type: MediaLibraryTypeFilter) => void;
+    /** Current collection filter. */
+    collection: string;
+    setCollection: (collection: string) => void;
+    /** Current sort order. */
+    sort: MediaLibrarySort;
+    setSort: (sort: MediaLibrarySort) => void;
+    detailId: string | null;
+    setDetailId: (id: string | null) => void;
+    /** Assets to render. */
+    items: TItem[];
+    visibleItems: TItem[];
+    /** Ids of the currently selected assets. */
+    selectedIds: string[];
+    /** The currently selected assets, resolved from their ids. */
+    selectedItems: TItem[];
+    /** Ids of the currently selected assets, for fast lookup per row. */
+    selectedSet: Set<string>;
+    toggleSelection: (id: string) => void;
+    clearSelection: () => void;
+    clearFilters: () => void;
+    loading: boolean;
+    error: unknown;
+    hasFilters: boolean;
+    totalCount: number;
+    filteredCount: number;
+    /** Files chosen for upload but not yet sent. */
+    stagedFiles: MediaLibraryStagedFile[];
+    addFiles: (files: File[]) => void;
+    removeStagedFile: (id: string) => void;
+    clearStagedFiles: () => void;
+    updateUploadOptions: (patch: Partial<MediaLibraryUploadOptions>) => void;
+    /** Collection, tags, and visibility applied to the staged files. */
+    uploadOptions: MediaLibraryUploadOptions;
+    /** Whether an upload is in flight. */
+    uploading: boolean;
+    startUpload: () => Promise<void>;
+    cancelUpload: () => void;
+    /** Resolves `false` after rollback when the consumer mutation fails. */
+    updateItem: (item: TItem, patch: MediaLibraryItemPatch) => Promise<boolean>;
+    /** Resolves `false` after rollback when the consumer mutation fails. */
+    removeItem: (item: TItem) => Promise<boolean>;
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+}
+/**
+ * Data and behaviour for the media library, shared by the panel, the dialog,
+ * and the `useMediaLibrary` hook.
+ *
+ * The library runs in one of two modes:
+ *
+ * - **Local** (no `fetcher`) — it owns searching, type/collection filtering,
+ *   and sorting over `items`.
+ * - **Server** (`fetcher` set) — the fetcher owns all of that. `items` is
+ *   ignored entirely, and the query, type, collection, and sort are handed to
+ *   the fetcher rather than applied to its results.
+ */
+export interface UseMediaLibraryOptions<TItem = MediaLibraryItem> {
+    /** Assets to browse in local mode. Ignored when `fetcher` is set. */
+    items?: readonly TItem[];
+    /**
+     * Loads assets for the current query, type, collection, and sort. Supplying
+     * it switches the library to server mode, where it never filters or sorts
+     * the returned assets itself.
+     */
+    fetcher?: MediaLibraryFetcher<TItem>;
+    /**
+     * Reads id, name, URL, type, and size off your own asset shape. Omit only
+     * when items already match `MediaLibraryItem`.
+     */
+    accessors?: MediaLibraryAccessors<TItem>;
+    /** Collections offered in the filter, for grouping assets by album or folder. */
+    collections?: readonly MediaLibraryCollectionOption[];
+    /** Whether one asset or several can be selected at a time. */
+    selectionMode?: MediaLibrarySelectionMode;
+    /** Selected asset ids, for controlled use. */
+    value?: readonly string[];
+    /** Initially selected asset ids, for uncontrolled use. */
+    defaultValue?: readonly string[];
+    /** Fired with the selected ids and their resolved assets. */
+    onValueChange?: (ids: string[], items: TItem[]) => void;
+    /** Applies an edit to an asset's metadata. May be awaited. */
+    onItemUpdate?: (item: TItem, patch: MediaLibraryItemPatch) => void | Promise<void>;
+    /** Removes an asset. May be awaited. */
+    onItemDelete?: (item: TItem) => void | Promise<void>;
+    /** Fired when an entry is uploaded. */
+    onUpload?: MediaLibraryUploadHandler<TItem>;
+    /** Receives failures from the fetcher, uploads, updates, and deletes. */
+    onError?: (error: unknown) => void;
+    /** Current browse/upload tab, for controlled use. */
+    tab?: MediaLibraryTab;
+    /** Tab shown on first render for uncontrolled use. */
+    defaultTab?: MediaLibraryTab;
+    /** Fired whenever the active tab changes. */
+    onTabChange?: (tab: MediaLibraryTab) => void;
+    /** Current grid or list layout, for controlled use. */
+    view?: MediaLibraryView;
+    /** Grid or list layout on first render for uncontrolled use. */
+    defaultView?: MediaLibraryView;
+    /** Fired whenever the layout changes. */
+    onViewChange?: (view: MediaLibraryView) => void;
+    /** Current search text, for controlled use. */
+    query?: string;
+    /** Search text on first render for uncontrolled use. */
+    defaultQuery?: string;
+    /** Fired whenever the search text changes. */
+    onQueryChange?: (query: string) => void;
+    /** Current type filter, for controlled use. */
+    type?: MediaLibraryTypeFilter;
+    /** Type filter on first render for uncontrolled use. */
+    defaultType?: MediaLibraryTypeFilter;
+    /** Fired whenever the type filter changes. */
+    onTypeChange?: (type: MediaLibraryTypeFilter) => void;
+    /** Current collection filter, for controlled use. */
+    collection?: string;
+    /** Collection filter on first render for uncontrolled use. */
+    defaultCollection?: string;
+    /** Fired whenever the collection filter changes. */
+    onCollectionChange?: (collection: string) => void;
+    /** Current sort order, for controlled use. */
+    sort?: MediaLibrarySort;
+    /** Sort order on first render for uncontrolled use. */
+    defaultSort?: MediaLibrarySort;
+    /** Fired whenever the sort order changes. */
+    onSortChange?: (sort: MediaLibrarySort) => void;
+    /** Current upload constraints, for controlled use. */
+    uploadOptions?: Partial<MediaLibraryUploadOptions>;
+    /** Initial upload constraints for uncontrolled use. */
+    defaultUploadOptions?: Partial<MediaLibraryUploadOptions>;
+    /** Fired with the fully resolved upload options whenever they change. */
+    onUploadOptionsChange?: (options: MediaLibraryUploadOptions) => void;
+}
+export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<ComponentPropsWithoutRef<'section'>, 'children' | 'defaultValue' | 'onError' | 'onSelect' | 'title'>, UseMediaLibraryOptions<TItem> {
+    /** Heading above the browser. */
+    title?: ReactNode;
+    /** Supporting line under the title. */
+    description?: ReactNode;
+    /** Copy for the confirm action. */
+    confirmLabel?: ReactNode;
+    /** Copy for the cancel action. */
+    cancelLabel?: ReactNode;
+    /** Whether one asset or several can be selected at a time. */
+    selectionMode?: MediaLibrarySelectionMode;
+    /** Tile size and spacing of the asset grid. */
+    density?: MediaLibraryDensity;
+    /** Shows each asset's size and dimensions under its name. */
+    showMeta?: boolean;
+    /** Offers the upload tab. */
+    allowUpload?: boolean;
+    /** Type filters offered in the toolbar. Defaults to every supported type. */
+    typeFilters?: readonly MediaLibraryTypeFilter[];
+    /**
+     * Treats picking an asset as confirming it, firing `onConfirm` immediately
+     * and skipping the footer. Suits single-select pickers.
+     */
+    confirmOnSelect?: boolean;
+    /** Fired with the chosen assets and their ids. */
+    onConfirm?: (items: TItem[], ids: string[]) => void;
+    /** Fired when the user backs out without choosing. */
+    onCancel?: () => void;
+    /** Fired after the surface closes, however it was dismissed. */
+    onClose?: () => void;
+    /** Overrides the library's own copy. */
+    strings?: StringsProp<MediaLibraryStrings>;
+    /** Replaces individual regions — the toolbar, cards, detail panel, or footer. */
+    slots?: MediaLibrarySlots<TItem>;
+    /** Height utility for the scrollable browse region. */
+    heightClassName?: string;
+}
+/** The media library in a modal, for picking assets from elsewhere in a page. */
+export interface MediaLibraryDialogProps<TItem = MediaLibraryItem> extends Omit<MediaLibraryProps<TItem>, 'title' | 'description'> {
+    /** Visibility, for controlled use. Omit to let `trigger` own it. */
+    open?: boolean;
+    /** Fired whenever the dialog wants to open or close. */
+    onOpenChange?: (open: boolean) => void;
+    /** Element that opens the dialog. */
+    trigger?: ReactNode;
+    /** Dialog heading. Replaces the panel's `title`. */
+    dialogTitle?: string;
+    /** Dialog supporting line. Replaces the panel's `description`. */
+    dialogDescription?: string;
+    /** Merged onto the dialog surface. */
+    dialogClassName?: string;
+    /** Merged onto the dialog's scrollable content region. */
+    contentClassName?: string;
+    /** Allows Escape to dismiss. */
+    closeOnEscape?: boolean;
+    /** Allows a backdrop click to dismiss. */
+    closeOnBackdropClick?: boolean;
+}
+export interface MediaResourceGalleryItemRenderContext<TItem = MediaLibraryItem> {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Total number of records across all pages. */
+    total: number;
+    primary: boolean;
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+    canMovePrevious: boolean;
+    canMoveNext: boolean;
+    setPrimary: () => void;
+    remove: () => void;
+    movePrevious: () => void;
+    moveNext: () => void;
+}
+export interface MediaResourceGalleryProps<TItem = MediaLibraryItem> extends Omit<ComponentPropsWithoutRef<'section'>, 'children' | 'title'> {
+    /** Assets attached to the resource, in display order. */
+    items: readonly TItem[];
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors?: MediaLibraryAccessors<TItem>;
+    /** Heading above the gallery. */
+    title?: ReactNode;
+    /** Supporting line under the title. */
+    description?: ReactNode;
+    /** Id of the asset marked primary — the resource's cover image. */
+    primaryId?: string;
+    /** Fired when a different asset is promoted to primary. */
+    onPrimaryChange?: (id: string, item: TItem) => void;
+    /** Fired when an asset is detached from the resource. */
+    onRemove?: (id: string, item: TItem) => void;
+    /** Fired with the next order after a drag. */
+    onReorder?: (ids: string[], items: TItem[]) => void;
+    /** Fired when the user asks to attach more assets — usually opens the library dialog. */
+    onAdd?: () => void;
+    /** Caps how many assets may be attached. The add control hides once reached. */
+    maxItems?: number;
+    /** Arrangement of the tiles. */
+    layout?: MediaResourceGalleryLayout;
+    /** Tile size and spacing. */
+    density?: MediaLibraryDensity;
+    /** Renders the gallery without the add, remove, reorder, and primary controls. */
+    readOnly?: boolean;
+    /** Shown when no assets are attached. */
+    empty?: ReactNode;
+    /** Control rendered in the gallery header. */
+    action?: ReactNode;
+    renderItem?: (item: TItem, ctx: MediaResourceGalleryItemRenderContext<TItem>) => ReactNode;
+    strings?: StringsProp<MediaLibraryStrings>;
+}
+export interface MediaLibraryCardProps<TItem = MediaLibraryItem> {
+    /** The asset this row or card represents. */
+    item: TItem;
+    /** Whether the entry is selected. */
+    selected?: boolean;
+    /** Tile size and spacing. */
+    density?: MediaLibraryDensity;
+    /** Renders the meta. */
+    showMeta?: boolean;
+    /** Whether one asset or several can be selected at a time. */
+    selectionMode?: MediaLibrarySelectionMode;
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    /** Fired when an entry is toggled. */
+    onToggle?: () => void;
+    onDetails?: () => void;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface MediaLibraryListProps<TItem = MediaLibraryItem> {
+    /** Assets to render. */
+    items: readonly TItem[];
+    /** Ids of the currently selected assets, for fast lookup per row. */
+    selectedSet: Set<string>;
+    /** Whether one asset or several can be selected at a time. */
+    selectionMode?: MediaLibrarySelectionMode;
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    /** Fired when an entry is toggled. */
+    onToggle: (id: string) => void;
+    onDetails: (id: string) => void;
+}
+export interface MediaLibraryDetailPanelProps<TItem = MediaLibraryItem> {
+    /** The asset this row or card represents. */
+    item: TItem | null;
+    /** Collections offered in the filter. */
+    collections?: readonly MediaLibraryCollectionOption[];
+    /** Reads id, name, URL, type, and size off your own asset shape. */
+    accessors: ResolvedMediaLibraryAccessors<TItem>;
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    onClose: () => void;
+    onUpdate: (patch: MediaLibraryItemPatch) => Promise<boolean>;
+    /** Fired when an entry is removed. */
+    onRemove: () => Promise<boolean>;
+    /** Replaces the default detail rendering. */
+    renderDetail?: MediaLibrarySlots<TItem>['renderDetail'];
+}
+export interface MediaLibraryUploadPanelProps {
+    /** Files chosen for upload but not yet sent. */
+    stagedFiles: readonly MediaLibraryStagedFile[];
+    /** Collection, tags, and visibility applied to the staged files. */
+    uploadOptions: MediaLibraryUploadOptions;
+    /** Collections offered in the filter. */
+    collections?: readonly MediaLibraryCollectionOption[];
+    /** Whether an upload is in flight. */
+    uploading?: boolean;
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    onFiles: (files: File[]) => void;
+    /** Fired when a file is removed. */
+    onRemoveFile: (id: string) => void;
+    onOptionsChange: (patch: Partial<MediaLibraryUploadOptions>) => void;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+}
+export interface MediaLibraryToolbarProps {
+    /** Current search text. */
+    query: string;
+    /** Current type filter. */
+    type: MediaLibraryTypeFilter;
+    /** Current collection filter. */
+    collection: string;
+    /** Current sort order. */
+    sort: MediaLibrarySort;
+    /** Whether the browser is showing the grid or the table. */
+    view: MediaLibraryView;
+    /** Collections offered in the filter. */
+    collections?: readonly MediaLibraryCollectionOption[];
+    /** Type filters offered in the toolbar. */
+    typeFilters?: readonly MediaLibraryTypeFilter[];
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    onQueryChange: (query: string) => void;
+    onTypeChange: (type: MediaLibraryTypeFilter) => void;
+    onCollectionChange: (collection: string) => void;
+    /** Fired when the change sort changes. */
+    onSortChange: (sort: MediaLibrarySort) => void;
+    onViewChange: (view: MediaLibraryView) => void;
+    onClearFilters: () => void;
+    /** Content at the end of the toolbar row. */
+    toolbarEnd?: ReactNode;
+}
+export interface MediaLibraryFooterSummaryProps {
+    /** Which tab is showing — browse or upload. */
+    tab: MediaLibraryTab;
+    /** Ids of the currently selected assets. */
+    selectedIds: readonly string[];
+    /** Whether one asset or several can be selected at a time. */
+    selectionMode: MediaLibrarySelectionMode;
+    /** Files chosen for upload but not yet sent. */
+    stagedFiles: readonly MediaLibraryStagedFile[];
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    onClearSelection?: () => void;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface MediaLibraryFooterActionsProps<TItem = MediaLibraryItem> {
+    /** Which tab is showing — browse or upload. */
+    tab: MediaLibraryTab;
+    /** The currently selected assets, resolved from their ids. */
+    selectedItems: readonly TItem[];
+    /** Ids of the currently selected assets. */
+    selectedIds: readonly string[];
+    /** Files chosen for upload but not yet sent. */
+    stagedFiles: readonly MediaLibraryStagedFile[];
+    /** Whether an upload is in flight. */
+    uploading?: boolean;
+    /** Overrides this surface's own copy. */
+    strings: MediaLibraryStrings;
+    /** Copy for the confirm action. */
+    confirmLabel?: ReactNode;
+    /** Copy for the cancel action. */
+    cancelLabel?: ReactNode;
+    /** Fired when entry editing is cancelled. */
+    onCancel?: () => void;
+    onConfirm?: () => void;
+    /** Fired when an entry is uploaded. */
+    onUpload?: () => void;
+    /** Fired when upload editing is cancelled. */
+    onCancelUpload?: () => void;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface MediaLibraryFooterProps<TItem = MediaLibraryItem> extends Omit<MediaLibraryFooterSummaryProps, 'className'>, Omit<MediaLibraryFooterActionsProps<TItem>, 'className'> {
+    chrome?: 'section' | 'bare';
+    className?: string;
+}
+export interface MediaLibraryEmptyStateProps {
+    /** Leading glyph. */
+    icon?: ReactNode;
+    /** Surface title. */
+    title: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Control offered alongside the empty message. */
+    action?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+}
+export interface MediaLibraryKeyboardSelectOptions {
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+}
+export type MediaLibraryKeyboardEvent = KeyboardEvent<HTMLElement>;

package/dist/components/features/media-library/media-resource-gallery.d.ts

@@ -0,0 +1,2 @@
+import type { MediaResourceGalleryProps } from './media-library.types';
+export declare function MediaResourceGallery<TItem = import('./media-library.types').MediaLibraryItem>({ items, accessors: accessorsProp, title, description, primaryId, onPrimaryChange, onRemove, onReorder, onAdd, maxItems, layout, density, readOnly, empty, action, renderItem, strings: stringsProp, className, ...props }: MediaResourceGalleryProps<TItem>): import("react").JSX.Element;

package/dist/components/features/media-library/partials/index.d.ts

@@ -0,0 +1 @@
+export { MediaLibraryCard, MediaLibraryDetailPanel, MediaLibraryEmptyState, MediaLibraryFooter, MediaLibraryList, MediaLibraryToolbar, MediaLibraryUploadPanel, } from './media-library-partials';

package/dist/components/features/media-library/partials/media-library-partials.d.ts

@@ -0,0 +1,10 @@
+import type { MediaLibraryCardProps, MediaLibraryDetailPanelProps, MediaLibraryEmptyStateProps, MediaLibraryFooterActionsProps, MediaLibraryFooterProps, MediaLibraryFooterSummaryProps, MediaLibraryListProps, MediaLibraryToolbarProps, MediaLibraryUploadPanelProps } from '../media-library.types';
+export declare function MediaLibraryEmptyState({ icon, title, description, action, className, }: MediaLibraryEmptyStateProps): import("react").JSX.Element;
+export declare function MediaLibraryToolbar({ query, type, typeFilters, collection, sort, view, collections, strings, onQueryChange, onTypeChange, onCollectionChange, onSortChange, onViewChange, onClearFilters, toolbarEnd, }: MediaLibraryToolbarProps): import("react").JSX.Element;
+export declare function MediaLibraryCard<TItem>({ item, selected, density, showMeta, accessors, strings, onToggle, onDetails, className, }: MediaLibraryCardProps<TItem>): import("react").JSX.Element;
+export declare function MediaLibraryList<TItem>({ items, selectedSet, accessors, strings, onToggle, onDetails, }: MediaLibraryListProps<TItem>): import("react").JSX.Element;
+export declare function MediaLibraryDetailPanel<TItem>({ item, collections, accessors, strings, onClose, onUpdate, onRemove, renderDetail, }: MediaLibraryDetailPanelProps<TItem>): import("react").JSX.Element | null;
+export declare function MediaLibraryUploadPanel({ stagedFiles, uploadOptions, collections, uploading, strings, onFiles, onRemoveFile, onOptionsChange, empty, }: MediaLibraryUploadPanelProps): import("react").JSX.Element;
+export declare function MediaLibraryFooterSummary({ tab, selectedIds, selectionMode, stagedFiles, strings, onClearSelection, className, }: MediaLibraryFooterSummaryProps): import("react").JSX.Element;
+export declare function MediaLibraryFooterActions<TItem>({ tab, selectedItems, selectedIds, stagedFiles, uploading, strings, confirmLabel, cancelLabel, onCancel, onConfirm, onUpload, onCancelUpload, className, }: MediaLibraryFooterActionsProps<TItem>): import("react").JSX.Element;
+export declare function MediaLibraryFooter<TItem>({ tab, selectedItems, selectedIds, selectionMode, stagedFiles, uploading, strings, confirmLabel, cancelLabel, onCancel, onConfirm, onClearSelection, onUpload, onCancelUpload, chrome, className, }: MediaLibraryFooterProps<TItem>): import("react").JSX.Element;

package/dist/components/features/mentions/hooks/index.d.ts

@@ -0,0 +1,2 @@
+export { useMentionsSearch, type UseMentionsSearchOptions, type UseMentionsSearchReturn, } from './use-mentions-search';
+export { useMentions, type UseMentionsOptions, type UseMentionsReturn, type MentionEditorHandle, } from './use-mentions';

package/dist/components/features/mentions/hooks/use-mentions-search.d.ts

@@ -0,0 +1,41 @@
+import type { Mention, MentionResource, MentionSuggestion, MentionsResourceSearch, MentionsSearchErrorHandler } from '../mentions.types';
+export interface UseMentionsSearchOptions<TResource extends string = string> {
+    resources?: Partial<Record<TResource, MentionResource<TResource>>>;
+    onResourceSearch?: MentionsResourceSearch<TResource>;
+    initialMentions?: ReadonlyArray<Mention<TResource>>;
+    /** Debounce window for async search. Defaults to `DEFAULT_DEBOUNCE_MS`. */
+    debounceMs?: number;
+    /** Receives non-abort failures for each resource kind that could not be searched. */
+    onError?: MentionsSearchErrorHandler<TResource>;
+}
+export interface UseMentionsSearchReturn<TResource extends string = string> {
+    kinds: ReadonlyArray<TResource>;
+    activeKind: TResource | null;
+    setActiveKind: (kind: TResource | null) => void;
+    activeResource: MentionResource<TResource> | null;
+    query: string;
+    setQuery: (q: string) => void;
+    /** Suggestions for the active kind (`suggestionsByKind[activeKind]`). */
+    suggestions: ReadonlyArray<MentionSuggestion<TResource>>;
+    /** Per-kind suggestion buckets — useful for cross-kind UIs. */
+    suggestionsByKind: Readonly<Record<string, ReadonlyArray<MentionSuggestion<TResource>>>>;
+    /** Replaces the content with the loading state. */
+    isLoading: boolean;
+    error: unknown | null;
+    isError: boolean;
+    errorsByKind: Readonly<Partial<Record<TResource, unknown>>>;
+    retry: () => void;
+    mentions: ReadonlyArray<Mention<TResource>>;
+    addMention: (mention: Mention<TResource>) => void;
+    removeMention: (id: string) => void;
+    setMentions: (next: ReadonlyArray<Mention<TResource>>) => void;
+    reset: () => void;
+    selectSuggestion: (suggestion: MentionSuggestion<TResource>) => Mention<TResource>;
+    /** True if the consumer manually picked a tab. The trigger detector
+     * checks this and refuses to override the active kind on next caret
+     * change while it's true. Reset on `setManualKindOverride(false)` or
+     * `reset()`. */
+    manualKindOverride: boolean;
+    setManualKindOverride: (override: boolean) => void;
+}
+export declare function useMentionsSearch<TResource extends string = string>(options?: UseMentionsSearchOptions<TResource>): UseMentionsSearchReturn<TResource>;

package/dist/components/features/mentions/hooks/use-mentions.d.ts

@@ -0,0 +1,35 @@
+import type { RefObject } from 'react';
+import type { Mention, MentionSuggestion } from '../mentions.types';
+import { type UseMentionsSearchOptions, type UseMentionsSearchReturn } from './use-mentions-search';
+/**
+ * Minimal editor handle the trigger detector needs. Compatible with the
+ * library's `<RichTextEditor>` handle — implement these on any custom
+ * editor to plug in.
+ */
+export interface MentionEditorHandle {
+    getCaretContext(): {
+        textBefore: string;
+    } | null;
+    insertHTML(html: string): void;
+    replaceBeforeCaret(length: number, html: string): void;
+    focus(): void;
+}
+export interface UseMentionsOptions<TResource extends string = string> extends UseMentionsSearchOptions<TResource> {
+    /** Ref to the editor surface the trigger detector reads from. */
+    editorRef?: RefObject<MentionEditorHandle | null>;
+}
+export interface UseMentionsReturn<TResource extends string = string> extends UseMentionsSearchReturn<TResource> {
+    pickerOpen: boolean;
+    setPickerOpen: (open: boolean) => void;
+    /** True while the picker is open from an inline `@`/`#` trigger. */
+    triggerActive: boolean;
+    /** Wire to the editor's `onCaretChange` to enable inline triggers. */
+    handleCaretChange: () => void;
+    /**
+     * Convert a suggestion into a Mention, register it, insert the chip
+     * into the editor (replacing the trigger range when one is active),
+     * and close the picker. Returns the Mention.
+     */
+    pickSuggestion: (suggestion: MentionSuggestion<TResource>) => Mention<TResource>;
+}
+export declare function useMentions<TResource extends string = string>(options?: UseMentionsOptions<TResource>): UseMentionsReturn<TResource>;