themelia-react-ui 1.0.2 → 2.0.1

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

@@ -141,10 +141,14 @@ export interface MediaLibraryItemRenderContext<TItem = MediaLibraryItem> {
     selected: boolean;
     /** Whether one asset or several can be selected at a time. */
     selectionMode: MediaLibrarySelectionMode;
+    /** Whether the library is in selection mode, where activating an asset toggles it. */
+    selecting: boolean;
     /** Reads id, name, URL, type, and size off your own asset shape. */
     accessors: ResolvedMediaLibraryAccessors<TItem>;
     toggle: () => void;
     openDetails: () => void;
+    /** Opens the asset: `onItemOpen` when supplied, otherwise the detail panel. */
+    open: () => void;
 }
 export interface MediaLibraryDetailRenderContext<TItem = MediaLibraryItem> {
     /** Reads id, name, URL, type, and size off your own asset shape. */
@@ -187,6 +191,13 @@ export interface MediaLibraryState<TItem = MediaLibraryItem> {
     selectedSet: Set<string>;
     toggleSelection: (id: string) => void;
     clearSelection: () => void;
+    /**
+     * Whether selection mode is on: requested explicitly (`setSelecting(true)`,
+     * a picker) or implied because at least one asset is selected.
+     */
+    selecting: boolean;
+    /** Turns selection mode on or off. Turning it off also clears the selection. */
+    setSelecting: (selecting: boolean) => void;
     clearFilters: () => void;
     loading: boolean;
     error: unknown;
@@ -298,6 +309,20 @@ export interface UseMediaLibraryOptions<TItem = MediaLibraryItem> {
     defaultUploadOptions?: Partial<MediaLibraryUploadOptions>;
     /** Fired with the fully resolved upload options whenever they change. */
     onUploadOptionsChange?: (options: MediaLibraryUploadOptions) => void;
+    /**
+     * Explicit selection mode, for controlled use. Selection mode is also on
+     * whenever an asset is selected; turning it off clears the selection.
+     */
+    selecting?: boolean;
+    /**
+     * Explicit selection mode on first render for uncontrolled use. Default:
+     * `false`, so activating an asset opens it. `MediaLibrary` starts selecting
+     * when `confirmOnSelect` is set and `MediaLibraryDialog` always starts
+     * selecting, because both are pickers.
+     */
+    defaultSelecting?: boolean;
+    /** Fired when explicit selection mode is turned on or off. */
+    onSelectingChange?: (selecting: boolean) => void;
 }
 export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<ComponentPropsWithoutRef<'section'>, 'children' | 'defaultValue' | 'onError' | 'onSelect' | 'title'>, UseMediaLibraryOptions<TItem> {
     /** Heading above the browser. */
@@ -306,6 +331,12 @@ export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<Compon
     titleSuffix?: ReactNode;
     /** Requests replacement of the inspected asset. The consumer owns file selection, persistence, identity, and refreshed `items`; omitted callbacks hide Replace file. */
     onItemReplace?: (item: TItem) => void;
+    /**
+     * Fired when an asset is activated outside selection mode (click, Enter or
+     * Space) — for a preview, a lightbox or navigation. Without it the asset's
+     * detail panel opens. In selection mode activation toggles the asset instead.
+     */
+    onItemOpen?: (item: TItem) => void;
     /** Supporting line under the title. */
     description?: ReactNode;
     /** Copy for the confirm action. */
@@ -333,6 +364,15 @@ export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<Compon
     onCancel?: () => void;
     /** Fired after the surface closes, however it was dismissed. */
     onClose?: () => void;
+    /**
+     * Bulk actions for the selected assets, rendered in a floating
+     * `BatchActionBar` (count, these actions, Clear) while assets are selected.
+     * Browsing only: a picker (`onConfirm` without `confirmOnSelect`, or
+     * `MediaLibraryDialog`) reports its selection in the footer instead, so the
+     * bar is not rendered there. While the bar is in use the library tab drops
+     * the picker footer; the upload tab keeps its own.
+     */
+    bulkActions?: (context: MediaLibraryBulkActionContext<TItem>) => ReactNode;
     /** Overrides the library's own copy. */
     strings?: StringsProp<MediaLibraryStrings>;
     /** Replaces individual regions — the toolbar, cards, detail panel, or footer. */
@@ -340,8 +380,21 @@ export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<Compon
     /** Height utility for the scrollable browse region. */
     heightClassName?: string;
 }
+/** What a media library bulk action receives; mirrors the product variants' bulk context. */
+export interface MediaLibraryBulkActionContext<TItem = MediaLibraryItem> {
+    /** The selected assets that are loaded. */
+    selectedItems: TItem[];
+    /** Every selected id, including any not currently loaded. */
+    selectedIds: string[];
+    selectedCount: number;
+    /** Assets passing the current query and filters, not the whole library. */
+    visibleCount: number;
+    /** Assets in the whole library. */
+    totalCount: number;
+    clearSelection: () => void;
+}
 /** 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'> {
+export interface MediaLibraryDialogProps<TItem = MediaLibraryItem> extends Omit<MediaLibraryProps<TItem>, 'title' | 'description' | 'bulkActions'> {
     /** Visibility, for controlled use. Omit to let `trigger` own it. */
     open?: boolean;
     /** Fired whenever the dialog wants to open or close. */
@@ -430,6 +483,14 @@ export interface MediaLibraryCardProps<TItem = MediaLibraryItem> {
     /** Fired when an entry is toggled. */
     onToggle?: () => void;
     onDetails?: () => void;
+    /**
+     * Opens the asset. When set and the card is not `selecting`, activating the
+     * card opens it and a separate check control selects it. Without it,
+     * activating the card toggles its selection.
+     */
+    onOpen?: () => void;
+    /** Selection mode: activating the card toggles it and the check shows on every card. */
+    selecting?: boolean;
     /** Merged onto the outermost node. */
     className?: string;
 }
@@ -447,6 +508,14 @@ export interface MediaLibraryListProps<TItem = MediaLibraryItem> {
     /** Fired when an entry is toggled. */
     onToggle: (id: string) => void;
     onDetails: (id: string) => void;
+    /**
+     * Opens an asset. When set and the list is not `selecting`, activating a row
+     * opens it and a separate check control selects it. Without it, activating a
+     * row toggles its selection.
+     */
+    onOpen?: (id: string) => void;
+    /** Selection mode: activating a row toggles it. */
+    selecting?: boolean;
 }
 export interface MediaLibraryDetailPanelProps<TItem = MediaLibraryItem> {
     /** The asset this row or card represents. */
@@ -510,6 +579,10 @@ export interface MediaLibraryToolbarProps {
     onClearFilters: () => void;
     /** Content at the end of the toolbar row. */
     toolbarEnd?: ReactNode;
+    /** Whether selection mode is on; drives the pressed state of the Select toggle. */
+    selecting?: boolean;
+    /** Renders the Select toggle, which turns selection mode on or off. */
+    onSelectingChange?: (selecting: boolean) => void;
 }
 export interface MediaLibraryFooterSummaryProps {
     /** Which tab is showing — browse or upload. */

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

@@ -1,8 +1,8 @@
 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 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 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 MediaLibraryFooterSummary({ tab, selectedIds, selectionMode, stagedFiles, strings, onClearSelection, className, }: MediaLibraryFooterSummaryProps): import("react").JSX.Element;

package/dist/components/features/mentions/partials/mention-kind-toggles.d.ts

@@ -0,0 +1,16 @@
+import type { MentionResource, MentionSuggestion } from '../mentions.types';
+interface MentionKindTogglesProps<TResource extends string> {
+    kinds: ReadonlyArray<TResource>;
+    activeKind: TResource | null;
+    resources?: Partial<Record<TResource, MentionResource<TResource>>>;
+    /** Per-kind results; a count follows the label when present. */
+    counts?: Readonly<Record<string, ReadonlyArray<MentionSuggestion<TResource>>>>;
+    onKindChange: (kind: TResource) => void;
+}
+/**
+ * The resource-kind filter shared by the inline suggestions and the picker:
+ * compact toggles that press with the accent fill and hover with muted, like
+ * every other toggle, rather than a primary command fill.
+ */
+export declare function MentionKindToggles<TResource extends string>({ kinds, activeKind, resources, counts, onKindChange, }: MentionKindTogglesProps<TResource>): import("react").JSX.Element;
+export {};

package/dist/components/features/overlays/alert-dialog.d.ts

@@ -1,4 +1,4 @@
 import type { ConfirmDialogProps } from './overlays.types';
-declare function ConfirmDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, initialFocusRef, closeOnEscape, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, tone, showIcon, alertMessage, trigger, destructive, }: ConfirmDialogProps): import("react").JSX.Element;
+declare function ConfirmDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, surfaceStyle, initialFocusRef, closeOnEscape, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, tone, showIcon, alertMessage, trigger, destructive, align, }: ConfirmDialogProps): import("react").JSX.Element;
 export declare const ConfirmDialog: import("react").MemoExoticComponent<typeof ConfirmDialogImpl>;
 export {};

package/dist/components/features/overlays/dialog.d.ts

@@ -1,4 +1,4 @@
 import type { ActionDialogProps } from './overlays.types';
-declare function ActionDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, showCloseButton, surfaceStyle, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, size, trigger, }: ActionDialogProps): import("react").JSX.Element;
+declare function ActionDialogImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, className, contentClassName, showCloseButton, surfaceStyle, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, size, trigger, align, }: ActionDialogProps): import("react").JSX.Element;
 export declare const ActionDialog: import("react").MemoExoticComponent<typeof ActionDialogImpl>;
 export {};

package/dist/components/features/overlays/drawer.d.ts

@@ -1,4 +1,4 @@
 import type { ActionDrawerProps } from './overlays.types';
-declare function ActionDrawerImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, showCloseButton, className, contentClassName, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, direction, width, showFooter, modal, trigger, }: ActionDrawerProps): import("react").JSX.Element;
+declare function ActionDrawerImpl({ open, onOpenChange, onClose, children, title, description, visuallyHideHeader, showCloseButton, className, contentClassName, surfaceStyle, initialFocusRef, closeOnEscape, closeOnBackdropClick, strings: customStrings, showCancel, showConfirm, onCancel, onConfirm, onAsyncConfirm, onError, closeOnAsyncComplete, confirmTone, confirmStyle, loading, formId, footer, emphasis, tone, showIcon, alertMessage, direction, width, showFooter, modal, trigger, }: ActionDrawerProps): import("react").JSX.Element;
 export declare const ActionDrawer: import("react").MemoExoticComponent<typeof ActionDrawerImpl>;
 export {};

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

@@ -7,8 +7,8 @@ export interface UseOverlayActionsOptions extends Pick<OverlayActionProps, 'onCo
     customStrings?: StringsProp<OverlayStrings>;
     emphasis?: boolean;
     tone?: OverlayTone;
-    /** Called when `onAsyncConfirm` throws. Library DEV-logs the error;
-     *  consumer wires telemetry. */
+    /** Called when `onAsyncConfirm` throws; the consumer reports or retries.
+     *  Without it the library logs the rejection in development only. */
     onError?: (error: unknown) => void;
 }
 export interface UseOverlayActionsReturn {

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

@@ -1,17 +1,21 @@
 import { type Dispatch, type SetStateAction } from 'react';
 export type OverlayOpenSetter = Dispatch<SetStateAction<boolean>>;
 export interface OverlayVisibilityProps {
+    /** Current visibility. */
     open: boolean;
-    /** Fired when a change is opened. */
+    /** Requests a visibility change; spread both onto an overlay. */
     onOpenChange: (open: boolean) => void;
 }
 export interface UseOverlayVisibilityOptions {
+    /** Initial visibility when uncontrolled. Default: `false`. */
     defaultOpen?: boolean;
+    /** Controlled visibility. Omit to let the hook own it. */
     open?: boolean;
-    /** Fired when a change is opened. */
+    /** Fired once for every actual visibility change. */
     onOpenChange?: (open: boolean) => void;
-    /** Fired when an entry is opened. */
+    /** Fired after a change to open. */
     onOpen?: () => void;
+    /** Fired after a change to closed, whatever dismissed the overlay. */
     onClose?: () => void;
 }
 export interface UseOverlayVisibilityReturn {
@@ -25,10 +29,13 @@ export interface UseOverlayVisibilityReturn {
 }
 export type OverlayVisibilityGroupState<TKey extends string = string> = Record<TKey, boolean>;
 export interface UseOverlayVisibilityGroupOptions<TKey extends string = string> {
+    /** Initial visibility per key when uncontrolled. */
     defaultOpen?: Partial<Record<TKey, boolean>>;
+    /** Controlled visibility per key. */
     open?: Partial<Record<TKey, boolean>>;
-    /** Fired when a change is opened. */
+    /** Fired once for every actual change, with the key, its visibility and the next 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;
 }
 export type UseOverlayVisibilityGroupReturn<TKey extends string = string> = Record<TKey, UseOverlayVisibilityReturn>;

package/dist/components/features/overlays/index.d.ts

@@ -2,5 +2,5 @@ export { ActionDialog } from './dialog';
 export { ActionDrawer } from './drawer';
 export { ConfirmDialog } from './alert-dialog';
 export { useOverlayActions, type UseOverlayActionsOptions, type UseOverlayActionsReturn, useOverlayVisibility, useOverlayVisibilityGroup, type OverlayOpenSetter, type OverlayVisibilityGroupState, type OverlayVisibilityProps, type UseOverlayVisibilityGroupOptions, type UseOverlayVisibilityGroupReturn, type UseOverlayVisibilityOptions, type UseOverlayVisibilityReturn, } from './hooks';
-export type { OverlayTone, OverlaySize, DrawerDirection, OverlayButtonTone, OverlayButtonStyle, OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps, ActionDialogProps, ActionDrawerProps, ConfirmDialogProps, } from './overlays.types';
+export type { OverlayTone, OverlaySize, DrawerDirection, OverlayAlign, OverlayButtonTone, OverlayButtonStyle, OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps, ActionDialogProps, ActionDrawerProps, ConfirmDialogProps, } from './overlays.types';
 export { defaultOverlayStrings, defaultAlertDialogStrings, type OverlayStrings, } from './overlays.strings';

package/dist/components/features/overlays/overlay-tone-icon.d.ts

@@ -0,0 +1,37 @@
+import type { OverlayTone } from './overlays.types';
+/** One glyph and colour per tone, shared by every overlay's opt-in `showIcon`. */
+export declare const overlayToneGlyphs: {
+    readonly neutral: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-muted-foreground";
+        readonly surface: "bg-muted";
+    };
+    readonly destructive: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-destructive";
+        readonly surface: "bg-destructive/10";
+    };
+    readonly warning: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-warning-accent";
+        readonly surface: "bg-warning/20";
+    };
+    readonly info: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-info";
+        readonly surface: "bg-info/20";
+    };
+    readonly success: {
+        readonly Glyph: import("lucide-react").LucideIcon;
+        readonly color: "text-success";
+        readonly surface: "bg-success/20";
+    };
+};
+/**
+ * Inline tone glyph for a heading row. The wrapper takes the title's own line
+ * box (base size, snug leading, `h-lh`), so the glyph centres on the first title
+ * line at any density instead of relying on an optical offset.
+ */
+export declare function OverlayToneIcon({ tone }: {
+    tone: OverlayTone;
+}): import("react").JSX.Element;

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

@@ -1,6 +1,7 @@
 import type { ReactNode, RefObject, CSSProperties } from 'react';
 import type { ButtonStyle } from '../../base/buttons';
 import type { SemanticTone } from '../../../lib/component-vocabulary';
+import type { OverlayAlign } from '../../../lib/ui-provider/types';
 import type { StringsProp } from '../../../lib/strings';
 import type { OverlayStrings } from './overlays.strings';
 export type OverlayTone = Extract<SemanticTone, 'neutral' | 'destructive' | 'warning' | 'info' | 'success'>;
@@ -8,6 +9,13 @@ export type OverlayButtonTone = SemanticTone;
 export type OverlayButtonStyle = Exclude<ButtonStyle, 'ghost'>;
 export type OverlaySize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl' | '4xl' | '5xl' | 'full';
 export type DrawerDirection = 'left' | 'right' | 'top' | 'bottom';
+/**
+ * Where the heading (tone icon, title, description) and the actions sit:
+ * `'start'` on the reading edge, `'center'` stacked on the dialog's centre line.
+ * Resolved from the explicit prop, then the provider's `overlay` slice, then the
+ * component's fallback.
+ */
+export type { OverlayAlign };
 /** Presentation and lifecycle shared by every overlay in this family. */
 export interface OverlayBaseProps {
     /** Visibility, for controlled use. Omit to let the overlay own it via `trigger`. */
@@ -34,7 +42,9 @@ export interface OverlayBaseProps {
     /**
      * Renders the corner dismiss control. Default: `true`. Set `false` for
      * overlays whose body is the whole surface — a command palette has nowhere
-     * to put a floating X without it landing on the content.
+     * to put a floating X without it landing on the content. Keep another
+     * visible way to dismiss (a cancel action) so touch screen-reader users can
+     * leave the overlay.
      */
     showCloseButton?: boolean;
     /**
@@ -43,11 +53,15 @@ export interface OverlayBaseProps {
      * on the dialog itself, which no className can express.
      */
     surfaceStyle?: CSSProperties;
-    /** Element to focus on open, instead of the first tabbable node. */
-    initialFocusRef?: RefObject<HTMLElement>;
-    /** Allows Escape to dismiss. Set `false` for destructive or in-progress work. */
+    /**
+     * Element to focus on open, instead of the first tabbable node (the first
+     * field or action; the corner dismiss control comes last). Accepts a
+     * `useRef<HTMLInputElement>(null)` ref directly.
+     */
+    initialFocusRef?: RefObject<HTMLElement | null>;
+    /** Allows Escape to dismiss. Default: `true`. Set `false` for destructive or in-progress work. */
     closeOnEscape?: boolean;
-    /** Allows a backdrop click to dismiss. */
+    /** Allows a backdrop click to dismiss. Default: `true`. */
     closeOnBackdropClick?: boolean;
     /** Overrides the overlay's own copy (confirm/cancel labels). */
     strings?: StringsProp<OverlayStrings>;
@@ -100,37 +114,52 @@ export interface OverlayActionProps {
      * `onSubmit` owns the outcome — `onConfirm` and `onAsyncConfirm` do not fire.
      */
     formId?: string;
-    /** Replaces the generated footer; the consumer owns its action states. Pending dismissal protection still applies. */
+    /**
+     * Replaces the generated footer; the consumer owns its action states.
+     * Pending dismissal protection still applies. Custom actions that close the
+     * overlay use controlled visibility (`useOverlayVisibility`).
+     */
     footer?: ReactNode;
 }
 /** Semantic weight — the header icon and the confirm button's tone. */
 export interface OverlayEmphasisProps {
     /**
-     * Lets `tone` drive the header icon and the confirm button colour. Without
-     * it the tone is presentational only and `confirmTone` decides the button.
+     * Lets `tone` decide the confirm button colour (destructive, warning or
+     * success). Without it `confirmTone` decides the button. Default: `false`.
      */
     emphasis?: boolean;
-    /** Semantic tone of the overlay. Default: `'neutral'`. */
+    /** Semantic tone of the overlay: the `showIcon` glyph and the `alertMessage` notice. Default: `'neutral'`. */
     tone?: OverlayTone;
-    /** Shows the tone's icon beside the title. */
+    /** Shows the tone's glyph beside the title, centred on its first line. Default: `false`. */
     showIcon?: boolean;
     /** Inline notice between the header and the body — a warning or consequence. */
     alertMessage?: string;
 }
 /** A modal dialog with a title, body, and generated action footer. */
 export interface ActionDialogProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
-    /** Maximum dialog width. Default: `md`. */
+    /**
+     * Aligns the heading and the actions. `'center'` stacks the `showIcon` glyph
+     * above the title. Default: the provider's `overlay.defaultDialogAlign`, else
+     * `'start'`.
+     */
+    align?: OverlayAlign;
+    /** Maximum dialog width from the `sm` breakpoint; below it the dialog keeps a 1rem viewport margin. Default: `lg`. */
     size?: OverlaySize;
-    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`. */
+    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`; a string renders a secondary button. */
     trigger?: ReactNode;
 }
 /** An edge-anchored panel for longer work than a dialog comfortably holds. */
 export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
     /** Edge the drawer enters from. Default: `right`. */
     direction?: DrawerDirection;
-    /** Panel measurement along its opening axis — width for left/right, height for top/bottom. */
+    /**
+     * Maximum panel width for left and right drawers from the `sm` breakpoint;
+     * below it the panel spans the viewport. Top and bottom drawers span the
+     * width and size to their content up to 85% of the viewport height.
+     * Default: `lg`.
+     */
     width?: OverlaySize;
-    /** Renders the action footer. Set `false` when the body owns its own actions. */
+    /** Renders the action footer. Default: `true`. Set `false` when the body owns its own actions. */
     showFooter?: boolean;
     /**
      * Whether the drawer takes the page hostage while it is open. Default: `true`.
@@ -140,7 +169,8 @@ export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps,
      * Some side panels are the opposite: a theme editor, an inspector, a live
      * filter rail, anything whose whole purpose is to sit beside the app while
      * you keep working in it. Those need `false`, which drops the scrim and the
-     * inerting and leaves the page interactive.
+     * inerting and leaves the page interactive; pressing the page no longer
+     * dismisses the panel, which closes from its own controls or Escape.
      *
      * `'trap-focus'` is the middle setting — focus stays inside, but the page
      * neither locks its scroll nor stops taking pointer events.
@@ -149,7 +179,7 @@ export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps,
      * confirmation or anything the user must answer before continuing.
      */
     modal?: boolean | 'trap-focus';
-    /** Element that opens the drawer. Supply it for uncontrolled use instead of `open`. */
+    /** Element that opens the drawer. Supply it for uncontrolled use instead of `open`; a string renders a secondary button. */
     trigger?: ReactNode;
 }
 /**
@@ -157,14 +187,27 @@ export interface ActionDrawerProps extends OverlayBaseProps, OverlayActionProps,
  * body needs real content — this one is sized for a question and two answers.
  */
 export interface ConfirmDialogProps extends OverlayBaseProps, OverlayActionProps {
-    /** Semantic tone, driving the icon and confirm button. Default: `'neutral'`. */
+    /**
+     * Aligns the icon, title, description and actions together. Below the `sm`
+     * breakpoint the actions stack full width either way. Default: the
+     * provider's `overlay.defaultConfirmAlign`, else `'center'`.
+     */
+    align?: OverlayAlign;
+    /** Semantic tone, driving the confirm button, the `showIcon` glyph and the notice. Default: `'neutral'`. */
     tone?: OverlayTone;
-    /** Shows the tone's icon beside the title. */
+    /** Shows the tone's glyph above the title. Default: `false`; the confirm button and copy carry the tone. */
     showIcon?: boolean;
     /** Inline notice explaining the consequence before the user commits. */
     alertMessage?: string;
-    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`. */
+    /** Element that opens the dialog. Supply it for uncontrolled use instead of `open`; a string renders a secondary button. */
     trigger?: ReactNode;
     /** Shorthand for the destructive presentation. */
     destructive?: boolean;
+    /**
+     * Not used: a confirmation needs an explicit answer, so an outside press
+     * never dismisses it. Escape still cancels unless `closeOnEscape` is `false`.
+     */
+    closeOnBackdropClick?: boolean;
+    /** Not used: a confirmation has no corner dismiss control; Cancel or Escape declines. */
+    showCloseButton?: boolean;
 }

package/dist/components/features/products/components/product-contract-overview.d.ts

@@ -1,4 +1,9 @@
 import type { ProductContractOverviewProps } from '../products.types';
+/**
+ * One main column region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `contract` prop (still typed `ProductContractOverviewProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductContractOverview({ metrics, terms, rules, onOpenContract, onEditContract, onCreateRule, onSelectRule, onEditRule, onDeleteRule, renderRuleActions, actions, footerSlot, empty, className, strings: stringsProp, }: ProductContractOverviewProps): import("react").JSX.Element;
 export declare namespace ProductContractOverview {
     var displayName: string;

package/dist/components/features/products/components/product-details-card.d.ts

@@ -1,4 +1,9 @@
 import type { ProductDetailsCardProps } from '../products.types';
+/**
+ * One main column region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `details` prop (still typed `ProductDetailsCardProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductDetailsCard({ title, description, metadata, media, onEditDetails, actions, headerEnd, footerSlot, empty, className, strings: stringsProp, }: ProductDetailsCardProps): import("react").JSX.Element;
 export declare namespace ProductDetailsCard {
     var displayName: string;

package/dist/components/features/products/components/product-operations-card.d.ts

@@ -1,4 +1,9 @@
 import type { ProductOperationsCardProps } from '../products.types';
+/**
+ * One support rail region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `operations` prop (still typed `ProductOperationsCardProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductOperationsCard({ items, onCreateOperation, onSelectOperation, onEditOperation, onDeleteOperation, renderOperationActions, actions, footerSlot, renderItem, empty, className, strings: stringsProp, }: ProductOperationsCardProps): import("react").JSX.Element;
 export declare namespace ProductOperationsCard {
     var displayName: string;

package/dist/components/features/products/components/product-option-action-menu.d.ts

@@ -1,4 +1,9 @@
 import type { ProductOptionActionMenuProps } from '../products.types';
+/**
+ * Row menu for one product option.
+ *
+ * @deprecated An internal part of `ProductOptionsSummary` (and so of `ProductOverview`), which renders it for every option. Replace it there with `renderOptionActions`, composing the base `ActionMenu` if needed. Kept exported for compatibility.
+ */
 export declare function ProductOptionActionMenu({ option, index, onSelectOption, onEditOption, onDeleteOption, renderOptionActions, menuLabel, className, strings: stringsProp, }: ProductOptionActionMenuProps): import("react").JSX.Element | null;
 export declare namespace ProductOptionActionMenu {
     var displayName: string;

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

@@ -1,4 +1,9 @@
 import type { ProductOptionsSummaryProps } from '../products.types';
+/**
+ * One main column region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `options` prop (still typed `ProductOptionsSummaryProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductOptionsSummary({ options, onManageOptions, onCreateOption, onSelectOption, onEditOption, onDeleteOption, renderOptionActions, actions, footerSlot, renderOption, empty, className, strings: stringsProp, }: ProductOptionsSummaryProps): import("react").JSX.Element;
 export declare namespace ProductOptionsSummary {
     var displayName: string;

package/dist/components/features/products/components/product-policies-card.d.ts

@@ -1,4 +1,9 @@
 import type { ProductPoliciesCardProps } from '../products.types';
+/**
+ * One support rail region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `policies` prop (still typed `ProductPoliciesCardProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductPoliciesCard({ policies, onCreatePolicy, onSelectPolicy, onEditPolicy, onDeletePolicy, renderPolicyActions, actions, footerSlot, renderPolicy, empty, className, strings: stringsProp, }: ProductPoliciesCardProps): import("react").JSX.Element;
 export declare namespace ProductPoliciesCard {
     var displayName: string;

package/dist/components/features/products/components/product-quote-preview-card.d.ts

@@ -1,4 +1,9 @@
 import type { ProductQuotePreviewCardProps } from '../products.types';
+/**
+ * One support rail region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `quote` prop (still typed `ProductQuotePreviewCardProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductQuotePreviewCard({ lines, subtotal, tax, discount, total, onOpenQuote, onCreateLine, onSelectLine, onEditLine, onDeleteLine, renderLineActions, actions, footerSlot, empty, className, strings: stringsProp, }: ProductQuotePreviewCardProps): import("react").JSX.Element;
 export declare namespace ProductQuotePreviewCard {
     var displayName: string;

package/dist/components/features/products/components/product-readiness-card.d.ts

@@ -1,4 +1,9 @@
 import type { ProductReadinessCardProps } from '../products.types';
+/**
+ * One support rail region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `readiness` prop (still typed `ProductReadinessCardProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductReadinessCard({ items, score, scoreLabel, summary, onCreateReadinessItem, onSelectReadinessItem, onEditReadinessItem, onDeleteReadinessItem, renderReadinessItemActions, actions, footerSlot, renderItem, empty, className, strings: stringsProp, }: ProductReadinessCardProps): import("react").JSX.Element;
 export declare namespace ProductReadinessCard {
     var displayName: string;

package/dist/components/features/products/components/product-structure-card.d.ts

@@ -1,4 +1,9 @@
 import type { ProductStructureCardProps } from '../products.types';
+/**
+ * One support rail region of the product editor.
+ *
+ * @deprecated An internal region of `ProductOverview`, which renders it from its `structure` prop (still typed `ProductStructureCardProps`). Pass the same props there and add custom content through the overview's slots. Kept exported for compatibility.
+ */
 export declare function ProductStructureCard({ metrics, onCreateMetric, onSelectMetric, onEditMetric, onDeleteMetric, renderMetricActions, actions, footerSlot, empty, className, strings: stringsProp, }: ProductStructureCardProps): import("react").JSX.Element;
 export declare namespace ProductStructureCard {
     var displayName: string;

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

@@ -1,5 +1,27 @@
-import type { ProductVariantActionMenuProps } from '../products.types';
+import type { ReactNode } from 'react';
+import { type ProductVariantActionMenuStrings } from '../products.strings';
+import type { ProductVariantActionMenuProps, ProductVariantSummary } from '../products.types';
+type VariantCommandHandlers = Pick<ProductVariantActionMenuProps, 'onSelectVariant' | 'onEditVariant' | 'onDuplicateVariant' | 'onDeleteVariant'>;
+interface VariantCommand {
+    id: string;
+    label: string;
+    icon: ReactNode;
+    onClick: () => void;
+    tone: 'secondary' | 'destructive';
+    buttonStyle?: 'ghost';
+}
+/**
+ * The default variant commands, in order, with the destructive one last. The
+ * row menu and the details card's single overflow menu both build on these.
+ */
+export declare function productVariantMenuActions(variant: ProductVariantSummary, { onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant }: VariantCommandHandlers, strings: ProductVariantActionMenuStrings): VariantCommand[];
+/**
+ * Row menu for one product variant.
+ *
+ * @deprecated An internal part of the variant tables and `ProductVariantDetails`, which render it for every variant. Replace it there with `renderVariantActions`, composing the base `ActionMenu` if needed. Kept exported for compatibility.
+ */
 export declare function ProductVariantActionMenu({ variant, index, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, menuLabel, className, strings: stringsProp, }: ProductVariantActionMenuProps): import("react").JSX.Element | null;
 export declare namespace ProductVariantActionMenu {
     var displayName: string;
 }
+export {};

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, 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, 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 namespace ProductVariantsManager {
     var displayName: string;
 }

package/dist/components/features/products/partials/index.d.ts

@@ -2,6 +2,6 @@ export { ProductRowActions } from './product-actions';
 export { ProductEmptyState } from './product-empty-state';
 export { ProductMetricTile } from './product-metric-tile';
 export { ProductOperationRow, ProductReadinessRow, ProductStructureMetricRow, ProductSummaryRow, } from './product-rows';
-export { PRODUCT_TONE_BADGE, PRODUCT_TONE_SURFACE, ProductToneDot, clampProductPercent, } from './product-tone';
+export { PRODUCT_TONE_BADGE, PRODUCT_TONE_TEXT, ProductToneDot, clampProductPercent, isProductStatusTone, } from './product-tone';
 export { ProductVariantActions, ProductVariantCell, } from './product-variant-table-parts';
 export { PRODUCT_EMPTY_VALUE } from './product-values';

package/dist/components/features/products/partials/product-metric-tile.d.ts

@@ -1,4 +1,10 @@
 import type { ProductMetricSummary, ProductStructureMetric } from '../products.types';
+/**
+ * A headline fact: label above an emphasised value, in the same label-over-value
+ * anatomy as the metadata lists beside it. No tile chrome — the parent grid's
+ * gap separates metrics — and colour appears only as a status dot when the
+ * metric's tone states a status.
+ */
 export declare function ProductMetricTile({ metric }: {
     metric: ProductStructureMetric | ProductMetricSummary;
 }): import("react").JSX.Element;