themelia-react-ui 2.0.4 → 2.0.6

package/dist/components/features/filters/filters.types.d.ts

@@ -64,6 +64,7 @@ export interface FilterOption {
     value: string;
     /** Leading glyph. */
     icon: ReactNode;
+    /** Nested options. SELECT and MULTI_SELECT editors show them level by level, and a chosen option reads as its path. */
     children?: FilterOption[];
     /** Renders the entry as unselectable. */
     disabled?: boolean;
@@ -134,9 +135,9 @@ export interface AsyncSelectConfig<TItem = unknown> {
     preload?: boolean;
     /** Debounce delay in ms (default: 300) */
     debounceMs?: number;
-    /** Freshness window in ms before a cached result refetches (default: 60_000). */
+    /** Freshness window in ms for cached results within one mounted editor (default: 60_000). */
     staleTime?: number;
-    /** Retention window in ms before a cached result is discarded (default: 300_000). */
+    /** Retention window in ms within one mounted editor (default: 300_000). Closing the editor discards its cache. */
     gcTime?: number;
 }
 /**
@@ -167,6 +168,8 @@ export interface FilterConfig {
     validation?: ValidationConfig;
     dependencies?: FilterDependency[];
     multiple?: boolean;
+    /** For nested options: only leaves can be chosen (default), or any option, including a branch. */
+    selectableOptions?: 'leaf' | 'any';
     closeOnSelect?: boolean;
     maxSelected?: number;
     /** Async option loading config for ASYNC_SELECT filters. */
@@ -193,7 +196,7 @@ export interface ActiveFilter {
     key: string;
     /** Comparison currently chosen. */
     operator: FilterOperator;
-    /** Current value of the filter. */
+    /** Current value of the filter. RANGE uses [min, max], with an empty string for an open bound. */
     value: string[];
 }
 export interface FilterGroup {

package/dist/components/features/filters/partials/date-filter-content.d.ts

@@ -1,7 +1,8 @@
-import type { FilterConfig, FilterTriggerSource } from '../filters.types';
+import type { FilterConfig, FilterOperator, FilterTriggerSource } from '../filters.types';
 interface DateFilterContentProps {
     /** Definition of the filter this control edits. */
     filter: FilterConfig;
+    operator?: FilterOperator;
     /** Current value. */
     value: string[];
     /** Fired when the change filters change. */
@@ -10,5 +11,5 @@ interface DateFilterContentProps {
     /** Origin of the editor, which determines back-button behavior. */
     triggerSource?: FilterTriggerSource;
 }
-export declare function DateFilterContent({ filter, value, onFilterChange, onBackToFilterList, triggerSource, }: DateFilterContentProps): import("react").JSX.Element;
+export declare function DateFilterContent({ filter, operator, value, onFilterChange, onBackToFilterList, triggerSource, }: DateFilterContentProps): import("react").JSX.Element;
 export {};

package/dist/components/features/filters/partials/filter-editor-header.d.ts

@@ -0,0 +1,16 @@
+import type { ReactNode } from 'react';
+interface FilterEditorHeaderProps {
+    /** The filter label shown as the editor title. */
+    title: ReactNode;
+    /** Optional supporting line under the title. */
+    description?: ReactNode;
+    /** Returns to the filter list; the back button shows only when this is set. */
+    onBack?: () => void;
+}
+/**
+ * The one header every value editor uses — list, date and tag editors alike:
+ * an optional back button and the filter label as the popover title, set in
+ * the compact editor surface so every editor starts on the same band.
+ */
+export declare function FilterEditorHeader({ title, description, onBack }: FilterEditorHeaderProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/filter-popover-content.d.ts

@@ -1,9 +1,11 @@
-import type { ComponentProps } from 'react';
+import { type ComponentProps } from 'react';
 import { PopoverContent } from '../../../base/popover';
-import { type FilterConfig, type FilterTriggerSource } from '../filters.types';
+import { type FilterConfig, type FilterOperator, type FilterTriggerSource } from '../filters.types';
 export interface FilterPopoverContentProps {
     /** Which filter the popover is currently editing. */
     activeFilterInPopover: FilterConfig | null;
+    /** Active operator when the caller already owns the displayed selection. */
+    operator?: FilterOperator;
     /** Filters the user may add. */
     availableFilters: FilterConfig[];
     /** Filters currently applied. */
@@ -33,4 +35,4 @@ export interface FilterPopoverContentProps {
  * The component is used to wrap filter content in a consistent
  * popover interface across different filter types.
  */
-export declare function FilterPopoverContent({ activeFilterInPopover, availableFilters, activeFilters, getFilterValue, setFilterValue, onFilterSelect, onBackToFilterList, onClose, triggerSource, finalFocus, }: FilterPopoverContentProps): import("react").JSX.Element;
+export declare function FilterPopoverContent({ activeFilterInPopover, operator, availableFilters, activeFilters, getFilterValue, setFilterValue, onFilterSelect, onBackToFilterList, onClose, triggerSource, finalFocus, }: FilterPopoverContentProps): import("react").JSX.Element;

package/dist/components/features/filters/partials/nested-filter-options.d.ts

@@ -0,0 +1,21 @@
+import { type ReactNode } from 'react';
+import type { FilterConfig } from '../filters.types';
+interface NestedFilterOptionsProps {
+    /** Definition of the filter this control edits; its options nest `children`. */
+    filter: FilterConfig;
+    /** Current draft value. */
+    value: string[];
+    /** Whether several options can be chosen. */
+    multiple: boolean;
+    /** Receives the next draft value. */
+    onChange: (value: string[]) => void;
+    /** The editor's header, shown at the root level; a drilled level shows its own header and path instead. */
+    header: ReactNode;
+}
+/**
+ * NestedFilterOptions — the SELECT / MULTI_SELECT editor body for options with
+ * `children`. It shows one level at a time through the shared cascader panel,
+ * with path search across every level, inside the filter's own popover.
+ */
+export declare function NestedFilterOptions({ filter, value, multiple, onChange, header }: NestedFilterOptionsProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/range-filter-content.d.ts

@@ -0,0 +1,12 @@
+import type { FilterConfig, FilterOperator, FilterTriggerSource } from '../filters.types';
+interface RangeFilterContentProps {
+    filter: FilterConfig;
+    operator: FilterOperator;
+    value: string[];
+    onFilterChange: (value: string[]) => void;
+    onBackToFilterList: () => void;
+    onClose: () => void;
+    triggerSource: FilterTriggerSource;
+}
+export declare function RangeFilterContent({ filter, operator, value, onFilterChange, onBackToFilterList, onClose, triggerSource }: RangeFilterContentProps): import("react").JSX.Element;
+export {};

package/dist/components/features/filters/partials/regular-filter-content.d.ts

@@ -22,7 +22,8 @@ interface RegularFilterContentProps {
  *     the trailing edge — only rendered when the user has changed selection.
  *
  * Sizes are tuned to feel like a native menu, not a card. Popover width
- * stays at ~260-300px so labels read at one glance.
+ * stays at ~260-300px so labels read at one glance. Options with `children`
+ * replace the flat list with one level at a time (NestedFilterOptions).
  */
 export declare function RegularFilterContent({ filter, value, onFilterChange, onBackToFilterList, onClose, triggerSource, }: RegularFilterContentProps): import("react").JSX.Element;
 export {};

package/dist/components/features/filters/utils/filter-utils.d.ts

@@ -1,9 +1,31 @@
 import type { ReactNode } from 'react';
-import type { FilterConfig, FilterDependency } from '../filters.types';
+import type { CascaderNode } from '../../../base/cascader';
+import type { FilterConfig, FilterDependency, FilterOperator, FilterOption } from '../filters.types';
+export declare function getRangeBounds(value: readonly string[], operator?: FilterOperator): [min: string, max: string];
+export declare function isCompleteDateRange(value: readonly string[]): boolean;
+/** Filter dates use local calendar days or the app's explicit parameter format. */
+export declare function parseFilterDate(value: string | undefined, pattern?: string): Date | undefined;
 /**
- * Gets the label for a filter option
+ * The option for a value and its ancestors, searching nested options.
  */
-export declare function getFilterOptionLabel(filter: FilterConfig, value: string): string | undefined;
+export declare function findFilterOptionPath(options: readonly FilterOption[] | undefined, value: string): FilterOption[];
+/**
+ * A sentence-case label inside running text, such as a footer count:
+ * "Created date" reads "created date", while acronyms such as "SKU" stay.
+ */
+export declare function labelInRunningText(label: string): string;
+/**
+ * Whether any option nests children, so the editor shows them level by level.
+ */
+export declare function hasNestedFilterOptions(options?: readonly FilterOption[]): boolean;
+/**
+ * Nested filter options as cascader nodes.
+ */
+export declare function toCascaderNodes(options: readonly FilterOption[]): CascaderNode[];
+/**
+ * Gets the label for a filter option; a nested option reads as its path, such as "Europe / Greece".
+ */
+export declare function getFilterOptionLabel(filter: FilterConfig, value: string, separator?: string): string | undefined;
 /**
  * Gets the icon for a filter option
  */

package/dist/components/features/global-search/global-search.types.d.ts

@@ -85,6 +85,8 @@ export interface GlobalSearchRenderResultContext {
     query: string;
     /** Fired when an entry is activated. */
     onSelect: () => void;
+    /** Id of the option wrapping this row, which the search field names as its active descendant. */
+    optionId?: string;
 }
 /** Slot map — every consumer-overridable surface. */
 export interface GlobalSearchSlots<TGroup extends string = string> {

package/dist/components/features/global-search/partials/global-search-input.d.ts

@@ -13,5 +13,15 @@ export interface GlobalSearchInputProps {
     loading?: boolean;
     /** Focuses the control on mount. */
     autoFocus?: boolean;
+    /**
+     * Whether the results list is showing. Setting it makes the field a
+     * combobox (`role="combobox"`, `aria-expanded`), the pattern for a search
+     * whose results are navigated with the arrow keys while focus stays here.
+     */
+    expanded?: boolean;
+    /** Id(s) of the results listbox(es) the combobox controls, while expanded. */
+    controls?: string;
+    /** Id of the highlighted result, announced as the active option. */
+    activeDescendant?: string;
 }
 export declare const GlobalSearchInput: React.ForwardRefExoticComponent<GlobalSearchInputProps & React.RefAttributes<HTMLInputElement>>;

package/dist/components/features/global-search/partials/global-search-result-row.d.ts

@@ -10,7 +10,13 @@ export interface GlobalSearchResultRowProps<TGroup extends string = string> {
     /** Fired when an entry is activated. */
     onSelect?: () => void;
     onMouseEnter?: () => void;
+    /**
+     * Id of this row as an option of a results listbox. When set, the row is a
+     * `role="option"` reached through the search field's active descendant
+     * rather than by Tab; standalone rows stay plain buttons.
+     */
+    optionId?: string;
     /** Merged onto the outermost node. */
     className?: string;
 }
-export declare function GlobalSearchResultRow<TGroup extends string = string>({ result, active, query, onSelect, onMouseEnter, className, }: GlobalSearchResultRowProps<TGroup>): React.JSX.Element;
+export declare function GlobalSearchResultRow<TGroup extends string = string>({ result, active, query, onSelect, onMouseEnter, optionId, className, }: GlobalSearchResultRowProps<TGroup>): React.JSX.Element;

package/dist/components/features/media-library/hooks/use-media-library.d.ts

@@ -2,4 +2,4 @@ import type { MediaLibraryAccessors, MediaLibraryItem, ResolvedMediaLibraryAcces
 export declare function resolveMediaLibraryAccessors<TItem = MediaLibraryItem>(accessors?: MediaLibraryAccessors<TItem>): ResolvedMediaLibraryAccessors<TItem>;
 export declare function formatMediaLibrarySize(bytes?: number): string;
 export declare function getMediaLibraryDimensions<TItem>(item: TItem, accessors: ResolvedMediaLibraryAccessors<TItem>): string;
-export declare function useMediaLibrary<TItem = MediaLibraryItem>({ items: itemsProp, fetcher, accessors: accessorsProp, selectionMode, value, defaultValue, onValueChange, onItemUpdate, 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, selecting: selectingProp, defaultSelecting, onSelectingChange, }?: UseMediaLibraryOptions<TItem>): MediaLibraryState<TItem>;
+export declare function useMediaLibrary<TItem = MediaLibraryItem>({ items: itemsProp, fetcher, refreshKey, accessors: accessorsProp, selectionMode, value, defaultValue, onValueChange, onItemUpdate, 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, selecting: selectingProp, defaultSelecting, onSelectingChange, }?: UseMediaLibraryOptions<TItem>): MediaLibraryState<TItem>;

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

@@ -1,3 +1,3 @@
 import type { MediaLibraryDialogProps, MediaLibraryProps } from './media-library.types';
-export declare function MediaLibrary<TItem = import('./media-library.types').MediaLibraryItem>({ title, titleSuffix, description, confirmLabel, cancelLabel, selectionMode, density, showMeta, allowUpload, typeFilters, confirmOnSelect, onConfirm, onCancel, onClose, bulkActions, strings: stringsProp, slots, heightClassName, className, items, fetcher, accessors, collections, value, defaultValue, onValueChange, onItemUpdate, onItemDelete, onItemReplace, onItemOpen, onUpload, onError, selecting, defaultSelecting, onSelectingChange, tab, defaultTab, onTabChange, view, defaultView, onViewChange, query, defaultQuery, onQueryChange, type, defaultType, onTypeChange, collection, defaultCollection, onCollectionChange, sort, defaultSort, onSortChange, uploadOptions, defaultUploadOptions, onUploadOptionsChange, ...props }: MediaLibraryProps<TItem>): import("react").JSX.Element;
+export declare function MediaLibrary<TItem = import('./media-library.types').MediaLibraryItem>({ title, titleSuffix, description, confirmLabel, cancelLabel, selectionMode, density, showMeta, allowUpload, typeFilters, confirmOnSelect, onConfirm, onCancel, onClose, bulkActions, strings: stringsProp, slots, heightClassName, className, items, fetcher, refreshKey, accessors, collections, value, defaultValue, onValueChange, onItemUpdate, onItemDelete, onItemReplace, onItemOpen, onUpload, onError, selecting, defaultSelecting, onSelectingChange, tab, defaultTab, onTabChange, view, defaultView, onViewChange, query, defaultQuery, onQueryChange, type, defaultType, onTypeChange, collection, defaultCollection, onCollectionChange, sort, defaultSort, onSortChange, uploadOptions, defaultUploadOptions, onUploadOptionsChange, ...props }: MediaLibraryProps<TItem>): import("react").JSX.Element;
 export declare function MediaLibraryDialog<TItem = import('./media-library.types').MediaLibraryItem>({ open, onOpenChange, trigger, dialogTitle, dialogDescription, onClose, className, dialogClassName, contentClassName, closeOnEscape, closeOnBackdropClick, ...props }: MediaLibraryDialogProps<TItem>): import("react").JSX.Element;

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

@@ -39,6 +39,8 @@ export interface MediaLibraryStrings {
     loading: string;
     errorTitle: string;
     errorDescription: string;
+    /** Retry action in the load error state. Defaults to "Try again". */
+    retry?: string;
     cardDetails: string;
     /** Toolbar toggle that turns selection mode on or off. */
     selectMode: string;
@@ -79,6 +81,11 @@ export interface MediaLibraryStrings {
         replace: string;
         delete: string;
         close: string;
+        mutationError?: string;
+        confirmDeleteTitle?: string;
+        confirmDeleteDescription?: string;
+        confirmDeleteLabel?: string;
+        confirmDeleteError?: string;
     };
     upload: {
         dropTitle: string;
@@ -94,6 +101,7 @@ export interface MediaLibraryStrings {
         removeFile: string;
         uploading: string;
         done: string;
+        error?: string;
     };
     footer: {
         pickOne: string;

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

@@ -89,6 +89,8 @@ export type MediaLibraryFetcher<TItem = MediaLibraryItem> = (params: MediaLibrar
 export interface MediaLibraryUploadHelpers {
     /** Aborted when the user cancels or the media-library instance unmounts. */
     signal: AbortSignal;
+    /** IDs in the same order as the files passed to this upload call. */
+    fileIds?: readonly string[];
     setProgress: (fileId: string, progress: number) => void;
     setFileStatus: (fileId: string, status: MediaLibraryUploadStatus, error?: string) => void;
 }
@@ -154,6 +156,9 @@ 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>;
+    /** The most recent failed mutation for this asset. */
+    mutationError?: MediaLibraryState<TItem>['mutationError'];
+    /** In MediaLibrary, resolves after the user confirms or cancels removal. */
     remove: () => Promise<boolean>;
     /** Requests the consumer's replacement workflow for this inspected item, when supported. */
     replace?: () => void;
@@ -185,7 +190,7 @@ export interface MediaLibraryState<TItem = MediaLibraryItem> {
     visibleItems: TItem[];
     /** Ids of the currently selected assets. */
     selectedIds: string[];
-    /** The currently selected assets, resolved from their ids. */
+    /** The selected assets that have been loaded or uploaded, including earlier server results. */
     selectedItems: TItem[];
     /** Ids of the currently selected assets, for fast lookup per row. */
     selectedSet: Set<string>;
@@ -200,7 +205,22 @@ export interface MediaLibraryState<TItem = MediaLibraryItem> {
     setSelecting: (selecting: boolean) => void;
     clearFilters: () => void;
     loading: boolean;
+    /** Whether remote or newly uploaded results are available during a request. */
+    hasLoadedResults?: boolean;
+    /** Legacy operation error. Cleared when the next load, mutation or upload starts. */
     error: unknown;
+    /** The current fetch failure. Local mode has no load error. */
+    loadError?: unknown;
+    /** The most recent failed update or delete, with the affected asset ID. */
+    mutationError?: {
+        itemId: string;
+        operation: 'update' | 'delete';
+        cause: unknown;
+    } | null;
+    /** The current upload request failure, separate from individual file statuses. */
+    uploadError?: unknown;
+    /** Runs the fetcher again for the current query after a failure; does nothing in local mode. */
+    retry: () => void;
     hasFilters: boolean;
     totalCount: number;
     filteredCount: number;
@@ -216,9 +236,9 @@ export interface MediaLibraryState<TItem = MediaLibraryItem> {
     uploading: boolean;
     startUpload: () => Promise<void>;
     cancelUpload: () => void;
-    /** Resolves `false` after rollback when the consumer mutation fails. */
+    /** Requires `onItemUpdate`. Resolves `false` when unavailable or after a failed edit rolls back. */
     updateItem: (item: TItem, patch: MediaLibraryItemPatch) => Promise<boolean>;
-    /** Resolves `false` after rollback when the consumer mutation fails. */
+    /** Requires `onItemDelete`. Resolves `false` when unavailable or after a failed delete rolls back. */
     removeItem: (item: TItem) => Promise<boolean>;
     /** Reads id, name, URL, type, and size off your own asset shape. */
     accessors: ResolvedMediaLibraryAccessors<TItem>;
@@ -244,6 +264,8 @@ export interface UseMediaLibraryOptions<TItem = MediaLibraryItem> {
      * the returned assets itself.
      */
     fetcher?: MediaLibraryFetcher<TItem>;
+    /** Change this key to reload the current remote query. Callback identity alone does not reload it. */
+    refreshKey?: string | number;
     /**
      * Reads id, name, URL, type, and size off your own asset shape. Omit only
      * when items already match `MediaLibraryItem`.
@@ -257,11 +279,11 @@ export interface UseMediaLibraryOptions<TItem = MediaLibraryItem> {
     value?: readonly string[];
     /** Initially selected asset ids, for uncontrolled use. */
     defaultValue?: readonly string[];
-    /** Fired with the selected ids and their resolved assets. */
+    /** Fired with every selected id and the records loaded or uploaded so far. */
     onValueChange?: (ids: string[], items: TItem[]) => void;
-    /** Applies an edit to an asset's metadata. May be awaited. */
+    /** Applies a metadata edit. Without it, details are read-only. May be awaited. */
     onItemUpdate?: (item: TItem, patch: MediaLibraryItemPatch) => void | Promise<void>;
-    /** Removes an asset. May be awaited. */
+    /** Persists removal. The built-in library asks for confirmation and only offers Delete with this callback. */
     onItemDelete?: (item: TItem) => void | Promise<void>;
     /** Fired when an entry is uploaded. */
     onUpload?: MediaLibraryUploadHandler<TItem>;
@@ -358,7 +380,7 @@ export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<Compon
      * and skipping the footer. Suits single-select pickers.
      */
     confirmOnSelect?: boolean;
-    /** Fired with the chosen assets and their ids. */
+    /** Fired with every chosen ID and the selected records loaded or uploaded so far. */
     onConfirm?: (items: TItem[], ids: string[]) => void;
     /** Fired when the user backs out without choosing. */
     onCancel?: () => void;
@@ -419,14 +441,18 @@ export interface MediaResourceGalleryItemRenderContext<TItem = MediaLibraryItem>
     id: string;
     /** Zero-based position of the entry in its list. */
     index: number;
-    /** Total number of records across all pages. */
+    /** Number of attached items in this gallery. */
     total: number;
     primary: boolean;
     /** Reads id, name, URL, type, and size off your own asset shape. */
     accessors: ResolvedMediaLibraryAccessors<TItem>;
+    /** Whether reordering is supported, writable, and an earlier position exists. */
     canMovePrevious: boolean;
+    /** Whether reordering is supported, writable, and a later position exists. */
     canMoveNext: boolean;
+    /** Keeps its callable shape; does nothing in read-only mode or without its handler. */
     setPrimary: () => void;
+    /** Keeps its callable shape; does nothing in read-only mode or without its handler. */
     remove: () => void;
     movePrevious: () => void;
     moveNext: () => void;
@@ -442,11 +468,11 @@ export interface MediaResourceGalleryProps<TItem = MediaLibraryItem> extends Omi
     description?: ReactNode;
     /** Id of the asset marked primary — the resource's cover image. */
     primaryId?: string;
-    /** Fired when a different asset is promoted to primary. */
+    /** Fired when a different asset is promoted to primary. Omit to hide the default primary command. */
     onPrimaryChange?: (id: string, item: TItem) => void;
-    /** Fired when an asset is detached from the resource. */
+    /** Fired when an asset is detached from the resource. Omit to hide the default remove command. */
     onRemove?: (id: string, item: TItem) => void;
-    /** Fired with the next order after a drag. */
+    /** Fired with the next order from a move command. Omit to hide default reorder commands. */
     onReorder?: (ids: string[], items: TItem[]) => void;
     /** Fired when the user asks to attach more assets — usually opens the library dialog. */
     onAdd?: () => void;
@@ -528,8 +554,14 @@ export interface MediaLibraryDetailPanelProps<TItem = MediaLibraryItem> {
     strings: MediaLibraryStrings;
     onClose: () => void;
     onUpdate: (patch: MediaLibraryItemPatch) => Promise<boolean>;
-    /** Fired when an entry is removed. */
+    /** Keeps metadata visible while preventing edits. */
+    readOnly?: boolean;
+    /** A failed mutation for the inspected asset. */
+    mutationError?: MediaLibraryState<TItem>['mutationError'];
+    /** Requests removal. */
     onRemove: () => Promise<boolean>;
+    /** Offers the Delete action and enables removal from custom details. Defaults to true. */
+    allowDelete?: boolean;
     /** Opens the consumer-owned replacement workflow for the inspected item. */
     onReplace?: () => void;
     /** Replaces the default detail rendering. */
@@ -544,6 +576,8 @@ export interface MediaLibraryUploadPanelProps {
     collections?: readonly MediaLibraryCollectionOption[];
     /** Whether an upload is in flight. */
     uploading?: boolean;
+    /** Shows an inline notice for a failed upload request. */
+    hasUploadError?: boolean;
     /** Overrides this surface's own copy. */
     strings: MediaLibraryStrings;
     onFiles: (files: File[]) => void;
@@ -583,6 +617,10 @@ export interface MediaLibraryToolbarProps {
     selecting?: boolean;
     /** Renders the Select toggle, which turns selection mode on or off. */
     onSelectingChange?: (selecting: boolean) => void;
+    /** Result summary, such as the item count; it sits with the view controls. */
+    summary?: ReactNode;
+    /** Disables every control, for example while the collection failed to load. */
+    disabled?: boolean;
 }
 export interface MediaLibraryFooterSummaryProps {
     /** Which tab is showing — browse or upload. */

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

@@ -1,10 +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, selecting, onSelectingChange, }: MediaLibraryToolbarProps): import("react").JSX.Element;
+export declare function MediaLibraryToolbar({ query, type, typeFilters, collection, sort, view, collections, strings, onQueryChange, onTypeChange, onCollectionChange, onSortChange, onViewChange, onClearFilters, toolbarEnd, selecting, onSelectingChange, summary, disabled, }: MediaLibraryToolbarProps): import("react").JSX.Element;
 export declare function MediaLibraryCard<TItem>({ item, selected, density, showMeta, accessors, strings, onToggle, onDetails, onOpen, selecting, className, }: MediaLibraryCardProps<TItem>): import("react").JSX.Element;
 export declare function MediaLibraryList<TItem>({ items, selectedSet, accessors, strings, onToggle, onDetails, onOpen, selecting, }: MediaLibraryListProps<TItem>): import("react").JSX.Element;
-export declare function MediaLibraryDetailPanel<TItem>({ item, collections, accessors, strings, onClose, onUpdate, onRemove, onReplace, 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 MediaLibraryDetailPanel<TItem>({ item, collections, accessors, strings, onClose, onUpdate, readOnly, mutationError, onRemove, allowDelete, onReplace, renderDetail, }: MediaLibraryDetailPanelProps<TItem>): import("react").JSX.Element | null;
+export declare function MediaLibraryUploadPanel({ stagedFiles, uploadOptions, collections, uploading, hasUploadError, 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 MediaLibraryFooterActions<TItem>({ tab, 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/use-mentions.d.ts

@@ -1,4 +1,4 @@
-import type { RefObject } from 'react';
+import type { FocusEvent, RefObject } from 'react';
 import type { Mention, MentionSuggestion } from '../mentions.types';
 import { type UseMentionsSearchOptions, type UseMentionsSearchReturn } from './use-mentions-search';
 /**
@@ -25,6 +25,21 @@ export interface UseMentionsReturn<TResource extends string = string> extends Us
     triggerActive: boolean;
     /** Wire to the editor's `onCaretChange` to enable inline triggers. */
     handleCaretChange: () => void;
+    /** Whether the inline suggestions panel is open. */
+    inlineOpen: boolean;
+    /** ID to pass to the inline suggestion list. */
+    listboxId: string;
+    /** Highlighted option index, or -1 when no option is highlighted. */
+    activeIndex: number;
+    /** Completion metadata for the editable body while options are available. */
+    suggestionPopup?: {
+        listboxId: string;
+        activeOptionId?: string;
+    };
+    /** Handles inline navigation and returns whether the editor should consume the key. */
+    handleKeyDown: (event: KeyboardEvent) => boolean;
+    /** Bind to the wrapper containing both the editor and inline suggestions. */
+    handleBlur: (event: FocusEvent<HTMLElement>) => void;
     /**
      * Convert a suggestion into a Mention, register it, insert the chip
      * into the editor (replacing the trigger range when one is active),

package/dist/components/features/mentions/partials/mention-inline-suggestions.d.ts

@@ -17,6 +17,10 @@ export interface MentionInlineSuggestionsProps<TResource extends string = string
     suggestionsByKind?: Readonly<Record<string, ReadonlyArray<MentionSuggestion<TResource>>>>;
     /** Matches for the text typed after the trigger character. */
     suggestions: ReadonlyArray<MentionSuggestion<TResource>>;
+    /** ID shared with the editor's controlled listbox. */
+    listboxId?: string;
+    /** Highlighted option supplied by the editor's keyboard navigation. */
+    activeIndex?: number;
     /** Replaces the content with the loading state. */
     loading: boolean;
     /** Live query the panel echoes in the header; the consumer owns the editor input. */
@@ -33,4 +37,4 @@ export interface MentionInlineSuggestionsProps<TResource extends string = string
     /** Merged onto the outermost node. */
     className?: string;
 }
-export declare function MentionInlineSuggestions<TResource extends string = string>({ open, activeKind, setActiveKind, kinds, resources, suggestionsByKind, suggestions, loading, query, onManualKindChange, onSelect, strings: stringsProp, className, }: MentionInlineSuggestionsProps<TResource>): import("react").JSX.Element | null;
+export declare function MentionInlineSuggestions<TResource extends string = string>({ open, activeKind, setActiveKind, kinds, resources, suggestionsByKind, suggestions, listboxId, activeIndex, loading, query, onManualKindChange, onSelect, strings: stringsProp, className, }: MentionInlineSuggestionsProps<TResource>): import("react").JSX.Element | null;

package/dist/components/features/mentions/utils/split-html-by-mentions.d.ts

@@ -1,10 +1,3 @@
-/**
- * Split an HTML string into a list of `html` chunks and `mention`
- * placeholders, keyed by the `data-ref-id` attribute the writer set.
- *
- * Used by `<MentionContent>` to render the body once with React chips
- * for the references and `dangerouslySetInnerHTML` for everything else.
- */
 export type MentionHtmlSegment = {
     kind: 'html';
     value: string;
@@ -13,4 +6,5 @@ export type MentionHtmlSegment = {
     refId: string;
     fallback: string;
 };
+/** @deprecated Render mentions within the original HTML tree with MentionContent. */
 export declare function splitHtmlByMentions(html: string): MentionHtmlSegment[];

package/dist/components/features/overlays/hooks/use-overlay-visibility.d.ts

@@ -11,7 +11,7 @@ export interface UseOverlayVisibilityOptions {
     defaultOpen?: boolean;
     /** Controlled visibility. Omit to let the hook own it. */
     open?: boolean;
-    /** Fired once for every actual visibility change. */
+    /** Fired for each request that differs from the current visibility. */
     onOpenChange?: (open: boolean) => void;
     /** Fired after a change to open. */
     onOpen?: () => void;
@@ -33,7 +33,7 @@ export interface UseOverlayVisibilityGroupOptions<TKey extends string = string>
     defaultOpen?: Partial<Record<TKey, boolean>>;
     /** Controlled visibility per key. */
     open?: Partial<Record<TKey, boolean>>;
-    /** Fired once for every actual change, with the key, its visibility and the next group state. */
+    /** Fired for each requested change, with the key, its visibility and the proposed group state. */
     onOpenChange?: (key: TKey, open: boolean, state: OverlayVisibilityGroupState<TKey>) => void;
     /** Opening one key closes the others, for one-at-a-time overlays. Default: `false`. */
     closeOthersOnOpen?: boolean;

package/dist/components/features/products/components/product-options-matrix.d.ts

@@ -1,5 +1,5 @@
 import type { ProductOptionsMatrixProps } from '../products.types';
-export declare function ProductOptionsMatrix({ optionGroups, surface, collapsedOptionIds, defaultCollapsedOptionIds, onCollapsedOptionIdsChange, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, confirmDelete, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onDoneEditingOption, onSaveEditingOption, onCancelEditingOption, onToggleUsedForVariants, renderOptionActions, renderValue, showHeader: showHeaderProp, showCollapseControls, showInlineActions, showVariantToggle, actions, headerEnd, footerSlot, empty, className, strings: stringsProp, }: ProductOptionsMatrixProps): import("react").JSX.Element;
+export declare function ProductOptionsMatrix({ optionGroups, surface, collapsedOptionIds, defaultCollapsedOptionIds, onCollapsedOptionIdsChange, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, confirmDelete, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onDoneEditingOption, onSaveEditingOption, onError, onCancelEditingOption, onToggleUsedForVariants, renderOptionActions, renderValue, showHeader: showHeaderProp, showCollapseControls, showInlineActions, showVariantToggle, actions, headerEnd, footerSlot, empty, className, strings: stringsProp, }: ProductOptionsMatrixProps): import("react").JSX.Element;
 export declare namespace ProductOptionsMatrix {
     var displayName: string;
 }

package/dist/components/features/products/components/product-variant-editor.d.ts

@@ -1,5 +1,5 @@
 import type { ProductVariantEditorProps } from '../products.types';
-export declare function ProductVariantEditor({ value: valueProp, defaultValue, optionFields, statusOptions, onValueChange, onSubmit, onError, onCancel, onDelete, actions, headerEnd, footerSlot, disabled, submitting, className, strings: stringsProp, }: ProductVariantEditorProps): import("react").JSX.Element;
+export declare function ProductVariantEditor({ value: valueProp, defaultValue, optionFields, statusOptions, onValueChange, onSubmit, onError, onCancel, onDelete, actions, headerEnd, footerSlot, visibleFields, errors, formId: formIdProp, showHeader, children, disabled, submitting, className, strings: stringsProp, }: ProductVariantEditorProps): import("react").JSX.Element;
 export declare namespace ProductVariantEditor {
     var displayName: string;
 }

package/dist/components/features/products/components/product-variants-manager.d.ts

@@ -1,5 +1,5 @@
 import type { ProductVariantsManagerProps } from '../products.types';
-export declare function ProductVariantsManager({ optionGroups, variants, visibleColumns, optionCombinationDisplay, cellDisplay, selectionMode, renderOptionCombination, renderCell, selectedVariantIds, defaultSelectedVariantIds, onSelectedVariantIdsChange, onVariantFieldChange, onVariantFieldBlur, collapsedOptionIds, defaultCollapsedOptionIds, onCollapsedOptionIdsChange, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onDoneEditingOption, onSaveEditingOption, onCancelEditingOption, onToggleUsedForVariants, renderOptionActions, renderValue, onCreateVariant, onGenerateVariants, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onBulkEdit, onBulkApply, onBulkDelete, renderVariantActions, renderBulkActions, groupByOptionId, defaultGroupByOptionId, onGroupByOptionIdChange, onSearchVariants, onFilterVariants, controlsEnd, actions, headerEnd, footerSlot, surface, padding, headerDivider, footerDivider, className, strings: stringsProp, optionsStrings, variantsStrings, }: ProductVariantsManagerProps): import("react").JSX.Element;
+export declare function ProductVariantsManager({ optionGroups, variants, visibleColumns, optionCombinationDisplay, cellDisplay, selectionMode, renderOptionCombination, renderCell, selectedVariantIds, defaultSelectedVariantIds, onSelectedVariantIdsChange, onVariantFieldChange, onVariantFieldBlur, collapsedOptionIds, defaultCollapsedOptionIds, onCollapsedOptionIdsChange, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onDoneEditingOption, onSaveEditingOption, onError, onCancelEditingOption, onToggleUsedForVariants, renderOptionActions, renderValue, onCreateVariant, onGenerateVariants, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onBulkEdit, onBulkApply, onBulkDelete, renderVariantActions, renderBulkActions, groupByOptionId, defaultGroupByOptionId, onGroupByOptionIdChange, showGroupBy, onSearchVariants, onFilterVariants, controlsEnd, actions, headerEnd, footerSlot, surface, padding, headerDivider, footerDivider, className, strings: stringsProp, optionsStrings, variantsStrings, }: ProductVariantsManagerProps): import("react").JSX.Element;
 export declare namespace ProductVariantsManager {
     var displayName: string;
 }

package/dist/components/features/products/products.strings.d.ts

@@ -109,7 +109,7 @@ export interface ProductOptionsMatrixStrings {
     /** Title of the confirmation shown when saving would drop option values. */
     confirmRemoveValuesTitle: string;
     /**
-     * Consequence of saving an edit that drops values. Receives `{count}`, the
+     * Consequence of saving an edit that drops values. Receives `{{count}}`, the
      * number of values the save removes.
      */
     confirmRemoveValuesDescription: string;
@@ -119,6 +119,14 @@ export interface ProductOptionsMatrixStrings {
     confirmDeleteOptionDescription: string;
     doneLabel: string;
     saveLabel: string;
+    /** Pending option-save copy. Optional for compatibility with complete legacy string objects. */
+    savingLabel?: string;
+    /** Heading for a rejected option save. */
+    saveErrorTitle?: string;
+    /** Fallback when a rejection has no displayable Error message. */
+    saveErrorMessage?: string;
+    /** Save command after a rejected option save. */
+    retrySaveLabel?: string;
     cancelLabel: string;
     expandOptionLabel: string;
     collapseOptionLabel: string;