themelia-ui 2.0.0 → 3.0.0

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

@@ -184,20 +184,58 @@ export interface MediaLibraryState<TItem = MediaLibraryItem> {
     accessors: ResolvedMediaLibraryAccessors<TItem>;
 }
 export interface UseMediaLibraryOptions<TItem = MediaLibraryItem> {
-    /** Ignored entirely when `fetcher` is set. */
+    /**
+     * The assets, when the library searches, filters and sorts them itself. Supply this or
+     * `fetcher`, not both: it is ignored entirely when `fetcher` is set.
+     */
     items?: readonly TItem[];
-    /** Supplying it hands searching, filtering, and sorting to the server. */
+    /**
+     * Supplying it hands searching, filtering, and sorting to the server: the fetcher owns all
+     * three, and `items` is ignored.
+     */
     fetcher?: MediaLibraryFetcher<TItem>;
+    /**
+     * Reads id, name, src, type, size, and the rest off your own shape. Supply only the ones that
+     * differ from MediaLibraryItem's names.
+     */
     accessors?: MediaLibraryAccessors<TItem>;
+    /** The collections the toolbar offers. */
     collections?: readonly MediaLibraryCollectionOption[];
+    /**
+     * `single` replaces the selection rather than toggling off, so a picker never ends up empty
+     * by accident.
+     */
     selectionMode?: MediaLibrarySelectionMode;
+    /** Controlled: the selected ids. */
     value?: readonly string[];
+    /** Uncontrolled: the ids selected at first. */
     defaultValue?: readonly string[];
+    /**
+     * Receives the selected ids, controlled or not, and the resolved assets too, so a consumer
+     * never has to look them up again.
+     */
     onValueChange?: (ids: string[], items: TItem[]) => void;
+    /**
+     * Awaited. A rejection rolls the local overlay back and reaches `onError`; the panel stays
+     * open so the reader can see what failed.
+     */
     onItemUpdate?: (item: TItem, patch: MediaLibraryItemPatch) => void | Promise<void>;
-    /** Applies editable fields to a custom record shape without mutating the original. */
+    /**
+     * Maps a standard metadata patch onto a consumer-owned record shape, without mutating the
+     * original. Defaults to merging fields onto MediaLibraryItem.
+     */
     applyItemPatch?: (item: TItem, patch: MediaLibraryItemPatch) => TItem;
+    /**
+     * Awaited. A rejection keeps the asset and reaches `onError`; the panel stays open so the
+     * reader can see what failed.
+     */
     onItemDelete?: (item: TItem) => void | Promise<void>;
+    /**
+     * Receives the files, the upload options, and helpers carrying stable staged files and IDs,
+     * an AbortSignal, `setProgress`, and `setFileStatus`. Failed files stay queued for retry.
+     * Returning the created items adds AND selects them — the reader uploaded them in order to
+     * use them.
+     */
     onUpload?: MediaLibraryUploadHandler<TItem>;
     /** Receives failures from the fetcher, uploads, updates, and deletes. */
     onError?: (error: unknown) => void;
@@ -232,8 +270,12 @@ export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<Compon
     /** Shows each asset's size and dimensions under its name. */
     showMeta?: boolean;
     allowUpload?: boolean;
+    /** The type filters the toolbar offers. A single type filter draws no control. */
     typeFilters?: readonly MediaLibraryTypeFilter[];
-    /** Picking confirms and the footer is removed. For a single-select picker. */
+    /**
+     * Picking is confirming: fires `onConfirm` immediately and removes the footer. The shape a
+     * single-select picker wants.
+     */
     confirmOnSelect?: boolean;
     onConfirm?: (items: TItem[], ids: string[]) => void;
     onCancel?: () => void;
@@ -244,6 +286,10 @@ export interface MediaLibraryProps<TItem = MediaLibraryItem> extends Omit<Compon
      */
     bulkActions?: (context: MediaLibraryBulkActionContext<TItem>) => ReactNode;
     strings?: Partial<MediaLibraryStrings>;
+    /**
+     * `headerStart`/`headerEnd`, `toolbarEnd`, `empty`, `loading`, `error`, `footer`,
+     * `uploadEmpty`, plus `renderItem` and `renderDetail`.
+     */
     slots?: MediaLibrarySlots<TItem>;
 }
 /** What a bulk action is handed; mirrors the product variants' context. */

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

@@ -1,7 +1,9 @@
 import { ResolvedMediaLibraryAccessors } from './media-library.types.js';
 /**
- * The asset's picture, or a stand-in: a broken `src` falls back to the type glyph, and
- * `tint` gives an asset without a preview a recognisable colour.
+ * The thumbnail that handles an image, a video, a PDF and a file with no preview at all — the
+ * last being the case a gallery usually forgets. It shows the asset's picture, or a stand-in: a
+ * broken `src` falls back to the type glyph, and `tint` gives an asset without a preview a
+ * recognisable colour.
  */
 export declare function MediaPreview<TItem>({ item, accessors, className, }: {
     item: TItem;

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

@@ -1,2 +1,7 @@
 import { MediaLibraryItem, MediaResourceGalleryProps } from './media-library.types.js';
+/**
+ * The assets attached to a record, in order — with reorder, cover, and detach. Not a browser:
+ * `onAdd` usually opens the library dialog. Reordering uses move buttons rather than drag, so it
+ * works with keyboard, screen reader and touch.
+ */
 export declare function MediaResourceGallery<TItem = MediaLibraryItem>({ items, accessors: accessorsProp, title, description, primaryId, onPrimaryChange, onRemove, onReorder, onAdd, maxItems, layout, density, readOnly, empty, action, renderItem, strings, className, ...props }: MediaResourceGalleryProps<TItem>): import("react").JSX.Element;

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

@@ -1,8 +1,13 @@
 import { MediaLibraryAccessors, MediaLibraryItem, MediaLibraryState, ResolvedMediaLibraryAccessors, UseMediaLibraryOptions } from './media-library.types.js';
-/** The hook supplies recovery controls even when a legacy state adapter omits them. */
+/** The hook supplies the recovery controls, which a state adapter may omit. */
 type ResolvedMediaLibraryState<TItem> = MediaLibraryState<TItem> & Required<Pick<MediaLibraryState<TItem>, "fetchError" | "refetch" | "selectVisible" | "deselectVisible">>;
 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;
+/**
+ * The whole state without the chrome. Its stable `refetch()` retries the current query without
+ * clearing filters or selection; `fetchError` identifies fetch failures separately from
+ * mutation errors.
+ */
 export declare function useMediaLibrary<TItem = MediaLibraryItem>({ items: itemsProp, fetcher, accessors: accessorsProp, selectionMode, value, defaultValue, onValueChange, onItemUpdate, applyItemPatch, onItemDelete, onUpload, onError, tab: tabProp, defaultTab, onTabChange, view: viewProp, defaultView, onViewChange, query: queryProp, defaultQuery, onQueryChange, type: typeProp, defaultType, onTypeChange, collection: collectionProp, defaultCollection, onCollectionChange, sort: sortProp, defaultSort, onSortChange, uploadOptions: uploadOptionsProp, defaultUploadOptions, onUploadOptionsChange, }: UseMediaLibraryOptions<TItem>): ResolvedMediaLibraryState<TItem>;
 export {};

package/dist/components/features/mentions/mention-content.d.ts

@@ -6,9 +6,15 @@ export interface MentionContentProps<TResource extends string = string> extends
     /** The mentions the record carries, resolved against the body by `data-ref-id`. */
     mentions?: ReadonlyArray<Mention<TResource>>;
     resources?: MentionsConfig<TResource>["resources"];
-    /** Takes over every chip. More specific than `resources.<kind>.renderChip`. */
+    /**
+     * Takes over every chip. More specific than `resources.<kind>.renderChip`, which is more
+     * specific than `resources.<kind>.tone`.
+     */
     renderMention?: (mention: Mention<TResource>) => ReactNode;
-    /** Replaces the kit's allow-list. Sanitising cannot be turned off, only swapped. */
+    /**
+     * Replaces the kit's allow-list. There is no way to turn sanitising off — the escape hatch is
+     * a different sanitiser, not the absence of one.
+     */
     sanitizer?: (html: string) => string;
 }
 export declare function MentionContent<TResource extends string = string>({ html, mentions, resources, renderMention, sanitizer, ...props }: MentionContentProps<TResource>): import("react").JSX.Element | null;

package/dist/components/features/mentions/mention-html.d.ts

@@ -8,9 +8,10 @@ export declare function buildMentionHtml<TKind extends string = string>(mention:
     tone?: MentionTone;
 }): string;
 /**
- * Reads the mentions back out of a body, e.g. so a composer's list shrinks when a chip is
- * deleted. First occurrence wins. Returns id, kind and label only; merge with known
- * mentions to keep `href` and `data`.
+ * Reads the mentions back out of a body — the other direction from `buildMentionHtml` — e.g. so
+ * a composer's list shrinks when a chip is deleted. First occurrence wins. Returns id, kind and
+ * label only; merge against the mentions you already know to keep `href` and `data`, which
+ * HTML cannot express.
  */
 export declare function parseMentionsFromHtml<TKind extends string = string>(html: string): Array<Mention<TKind>>;
 export type MentionHtmlSegment = {

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

@@ -16,9 +16,16 @@ export interface MentionInlineSuggestionsProps<TResource extends string = string
     /** Fires when the writer picks a tab, so the hook can stop auto-switching. */
     onManualKindChange?: () => void;
     onSelect: (suggestion: MentionSuggestion<TResource>) => void;
-    /** Escape or leaving the editor dismisses the current completion session. */
+    /**
+     * Closes the completion session on Escape or editor blur. Wire to `setPickerOpen(false)`.
+     * Unchanged caret callbacks do not reopen a dismissed query.
+     */
     onDismiss?: () => void;
     strings?: Partial<MentionInlineSuggestionsStrings>;
     className?: string;
 }
+/**
+ * The panel for the inline-trigger flow. Not a popover: the editor keeps focus and the caret.
+ * The consumer wraps the editor in a relatively positioned element; this pins itself below it.
+ */
 export declare function MentionInlineSuggestions<TResource extends string = string>({ open, activeKind, setActiveKind, kinds, resources, suggestionsByKind, suggestions, loading, query, onManualKindChange, onSelect, onDismiss, strings, className, }: MentionInlineSuggestionsProps<TResource>): import("react").JSX.Element | null;

package/dist/components/features/mentions/mention-picker.d.ts

@@ -15,4 +15,9 @@ export interface MentionPickerProps<TResource extends string = string> {
     strings?: Partial<MentionPickerStrings>;
     className?: string;
 }
+/**
+ * The popover for the button flow — the same tabs and rows as the inline panel, plus a search
+ * field of its own, because a reader who pressed a button has typed nothing to search with. The
+ * consumer supplies the Popover and its trigger.
+ */
 export declare function MentionPicker<TResource extends string = string>({ open, activeKind, setActiveKind, kinds, resources, suggestionsByKind, query, setQuery, suggestions, loading, onSelect, strings, className, }: MentionPickerProps<TResource>): import("react").JSX.Element | null;

package/dist/components/features/mentions/mention-suggestion-list.d.ts

@@ -10,6 +10,10 @@ export interface MentionKindTabsProps<TResource extends string = string> {
     /** Inline completion keeps all keyboard focus in the editor. */
     focusable?: boolean;
 }
+/**
+ * The kind tabs, one of the parts both mention surfaces are built from, so the inline panel and
+ * the popover cannot drift into showing the same data two ways.
+ */
 export declare function MentionKindTabs<TResource extends string = string>({ kinds, activeKind, onSelect, resources, suggestionsByKind, focusable, }: MentionKindTabsProps<TResource>): import("react").JSX.Element | null;
 export interface MentionRowsProps<TResource extends string = string> {
     suggestions: ReadonlyArray<MentionSuggestion<TResource>>;
@@ -29,4 +33,8 @@ export interface MentionRowsProps<TResource extends string = string> {
     /** Connects an inline editor to its active suggestion. */
     id?: string;
 }
+/**
+ * The suggestion rows, one of the parts both mention surfaces are built from, so the inline
+ * panel and the popover cannot drift into showing the same data two ways.
+ */
 export declare function MentionRows<TResource extends string = string>({ suggestions, activeKind, loading, loadingLabel, emptyLabel, listLabel, onSelect, className, resources, command, activeIndex, onActiveIndexChange, focusable, id, }: MentionRowsProps<TResource>): import("react").JSX.Element;

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

@@ -46,7 +46,10 @@ export interface MentionResource<TKind extends string = string, TData = unknown>
     }>;
     /** Names the tab: "Person", "Booking". */
     label?: string;
-    /** The character that opens the picker inline. Optional: a kind without one is reached from the picker button. */
+    /**
+     * The character that opens the picker inline. Optional — a kind with no trigger is still
+     * reachable from the picker button, which is right for one that is browsed rather than typed.
+     */
     trigger?: string;
     /** Per-kind search. Wins over the global fallback. */
     search?: (query: string, context?: MentionSearchRequestContext<TKind>) => Promise<MentionSuggestion<TKind, TData>[]> | MentionSuggestion<TKind, TData>[];

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

@@ -1,6 +1,14 @@
 import { Mention, MentionResource, MentionSuggestion, MentionsResourceSearch, MentionsSearchErrorHandler } from './mentions.types.js';
 export interface UseMentionsSearchOptions<TResource extends string = string> {
+    /**
+     * The registry. Each kind supplies a label, an icon, a tone, an optional trigger character,
+     * and either its own search or a static catalogue.
+     */
     resources?: Partial<Record<TResource, MentionResource<TResource>>>;
+    /**
+     * The fallback, for a kind that registers neither `search` nor `suggestions`. One endpoint
+     * taking a kind is the common shape.
+     */
     onResourceSearch?: MentionsResourceSearch<TResource>;
     initialMentions?: ReadonlyArray<Mention<TResource>>;
     debounceMs?: number;
@@ -21,7 +29,10 @@ export interface UseMentionsSearchReturn<TResource extends string = string> {
     isLoading: boolean;
     error: unknown | null;
     isError: boolean;
-    /** Failures per kind; one kind failing still leaves the others' results usable. */
+    /**
+     * Failures per kind. One kind failing is not the search failing: three registries answering
+     * and a fourth timing out is still a usable panel.
+     */
     errorsByKind: Readonly<Partial<Record<TResource, unknown>>>;
     retry: () => void;
     mentions: ReadonlyArray<Mention<TResource>>;
@@ -35,8 +46,18 @@ export interface UseMentionsSearchReturn<TResource extends string = string> {
     setMentions: (next: ReadonlyArray<Mention<TResource>> | ((prev: ReadonlyArray<Mention<TResource>>) => ReadonlyArray<Mention<TResource>>)) => void;
     reset: () => void;
     selectSuggestion: (suggestion: MentionSuggestion<TResource>) => Mention<TResource>;
-    /** True once the writer has picked a tab. Suspends the auto-jump. */
+    /**
+     * True once the writer has picked a tab, set by the panel. Suspends the auto-jump, because a
+     * list that keeps moving under someone who just said where to look is worse than one showing
+     * nothing.
+     */
     manualKindOverride: boolean;
     setManualKindOverride: (override: boolean) => void;
 }
+/**
+ * The picker's suggestion state. Every kind is searched rather than only the active tab, so the
+ * tab counts are true the moment the panel opens, and the panel can jump to the kind that
+ * matched. Lookup per kind: its `search`, then its static `suggestions`, then the global
+ * `onResourceSearch`.
+ */
 export declare function useMentionsSearch<TResource extends string = string>(options?: UseMentionsSearchOptions<TResource>): UseMentionsSearchReturn<TResource>;

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

@@ -15,14 +15,26 @@ export interface MentionEditorHandle {
 export interface UseMentionsOptions<TResource extends string = string> extends UseMentionsSearchOptions<TResource> {
     editorRef?: RefObject<MentionEditorHandle | null>;
 }
+/** What `useMentions` returns: the picker's state, the search state, and the editor's wiring. */
 export interface UseMentionsReturn<TResource extends string = string> extends UseMentionsSearchReturn<TResource> {
     pickerOpen: boolean;
     setPickerOpen: (open: boolean) => void;
     /** True while the picker is open because of an inline trigger, not the button. */
     triggerActive: boolean;
-    /** Wire to the editor's caret-change callback. */
+    /**
+     * Wire to the editor's caret-change callback. The trigger must follow start-of-line or
+     * whitespace, so an email address does not open the picker at its @.
+     */
     handleCaretChange: () => void;
-    /** Registers the mention, writes the chip into the editor, closes the picker. */
+    /**
+     * Registers the mention, writes the chip into the editor, closes the picker. The chip is
+     * written in ONE editor operation — deleting the needle and inserting separately leaves a
+     * frame where the caret is elsewhere.
+     */
     pickSuggestion: (suggestion: MentionSuggestion<TResource>) => Mention<TResource>;
 }
+/**
+ * The search state plus trigger detection from the text before the caret. Any editor
+ * implementing `MentionEditorHandle` plugs in; the kit's rich-text editor does.
+ */
 export declare function useMentions<TResource extends string = string>(options?: UseMentionsOptions<TResource>): UseMentionsReturn<TResource>;

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

@@ -1,2 +1,7 @@
 import { ActionDialogProps } from './overlays.types.js';
+/**
+ * A dialog with a generated footer: cancel and confirm in a fixed order, an async- and
+ * form-aware confirm, and a tone for the glyph and the confirm colour. Use the base Dialog when
+ * the body owns its actions.
+ */
 export declare function ActionDialog({ width, surfaceStyle, ...props }: ActionDialogProps): import("react").JSX.Element;

package/dist/components/features/overlays/action-sheet.d.ts

@@ -1,2 +1,6 @@
 import { ActionSheetProps } from './overlays.types.js';
+/**
+ * ActionDialog's recipe over a sheet, for longer work: a filter rail, an inspector, a long
+ * form. Its own props are the edge's — side, size, length, inset, modality.
+ */
 export declare function ActionSheet({ side, size, length, inset, modality, showFooter, ...props }: ActionSheetProps): import("react").JSX.Element;

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

@@ -9,6 +9,7 @@ export type OverlayButtonTone = SemanticTone;
 /** Ghost is excluded: a footer's confirm must look like a commitment. */
 export type OverlayButtonStyle = Exclude<ButtonStyle, "ghost">;
 export interface OverlayBaseProps {
+    /** Controlled: hands the open state to the caller. Supply this OR `trigger`, not both. */
     open?: boolean;
     onOpenChange?: (open: boolean) => void;
     /** Fires after it closes, whatever dismissed it. */
@@ -45,37 +46,69 @@ export interface OverlayActionProps {
     showCancel?: boolean;
     showConfirm?: boolean;
     onCancel?: () => void;
+    /**
+     * Runs, then the overlay closes. The second of the three confirm paths: `formId` wins over
+     * it, and it wins over `onAsyncConfirm`.
+     */
     onConfirm?: () => void;
+    /**
+     * Awaited with a spinner; closes on success, stays open on rejection and reports through
+     * `onError`. The last of the three confirm paths, after `formId` and `onConfirm`.
+     */
     onAsyncConfirm?: () => Promise<void>;
-    /** Receives a rejected async confirm, so a consumer can toast or report it. */
+    /**
+     * Receives a rejected async confirm, so a consumer can toast or report it. The overlay stays
+     * open.
+     */
     onError?: (error: unknown) => void;
-    /** `false` keeps the overlay open after a resolved async confirm (multi-step flows). */
+    /**
+     * `false` keeps the overlay open after a resolved async confirm — a multi-step flow.
+     * @default true
+     */
     closeOnAsyncComplete?: boolean;
     confirmTone?: OverlayButtonTone;
     confirmStyle?: OverlayButtonStyle;
     /** Forces the pending presentation, for confirm work owned outside the overlay. */
     loading?: boolean;
+    /**
+     * The first of the three confirm paths: the confirm button calls `requestSubmit()` on that
+     * form, so native validation runs and the form's own `onSubmit` owns the outcome. Neither
+     * callback fires.
+     */
     formId?: string;
-    /** Replaces the generated footer. Every prop above stops applying. */
+    /** Replaces the generated footer. Every action prop stops applying. */
     footer?: ReactNode;
 }
 export interface OverlayEmphasisProps {
     /**
-     * Lets `tone` drive the header glyph and the confirm button's colour. Without it the
-     * tone is presentational only (a warning notice with an ordinary primary confirm).
+     * Lets `tone` drive the confirm button's colour as well as the header glyph. Without it the
+     * tone is presentational only — a warning-toned dialog whose action is just the action, with
+     * an ordinary primary confirm, is a real combination.
      */
     emphasis?: boolean;
+    /** The semantic tone of the header glyph and the notice, and with `emphasis` the confirm. */
     tone?: OverlayTone;
+    /** Draws the tone's glyph beside the title. */
     showIcon?: boolean;
-    /** A notice between the header and the body: the consequence, before committing. */
+    /**
+     * A notice between the header and the body — the consequence, before committing — inside the
+     * scroll region: a warning pinned above it would stay while the thing it warns about scrolls
+     * away.
+     */
     alertMessage?: ReactNode;
 }
 /** A named step or any CSS length. */
 export type OverlayWidth = "sm" | "md" | "lg" | "xl" | "full" | (string & {});
 export interface ActionDialogProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
-    /** Maximum width. A CSS length, or one of the kit's steps. */
+    /**
+     * Maximum width: one of the kit's steps, or a CSS length. A dialog's max width is a real
+     * per-dialog decision — a confirmation is narrow and a form is wide.
+     */
     width?: OverlayWidth;
-    /** The element that opens it. Supply this OR `open`, not both. */
+    /**
+     * The element that opens it, which makes the overlay uncontrolled. Supply this OR `open`,
+     * not both.
+     */
     trigger?: ReactNode;
 }
 export interface ActionSheetProps extends OverlayBaseProps, OverlayActionProps, OverlayEmphasisProps {
@@ -87,17 +120,26 @@ export interface ActionSheetProps extends OverlayBaseProps, OverlayActionProps,
     inset?: boolean | string;
     showFooter?: boolean;
     /**
-     * `modal` traps focus, locks scroll and makes the page inert; `non-modal` sits beside
-     * the app (inspectors, filter rails); `trap-focus` is in between. A non-modal panel is
-     * not announced as a dialog, so never use it for a question that must be answered.
+     * How much of the page it takes hostage. `modal` traps focus, locks scroll and makes the page
+     * inert; `non-modal` sits beside the app (inspectors, filter rails) and leaves the
+     * surrounding page interactive; `trap-focus` is in between. A non-modal panel is not
+     * announced as a dialog, so never use it for a question that must be answered.
      */
     modality?: "modal" | "trap-focus" | "non-modal";
+    /**
+     * The element that opens it, which makes the overlay uncontrolled. Supply this OR `open`,
+     * not both.
+     */
     trigger?: ReactNode;
 }
 export interface ConfirmDialogProps extends OverlayBaseProps, OverlayActionProps {
     tone?: OverlayTone;
     showIcon?: boolean;
     alertMessage?: ReactNode;
+    /**
+     * The element that opens it, which makes the overlay uncontrolled. Supply this OR `open`,
+     * not both.
+     */
     trigger?: ReactNode;
     /** Shorthand for the destructive presentation: tone, icon and confirm colour. */
     destructive?: boolean;

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

@@ -20,4 +20,9 @@ export interface UseOverlayActionsReturn {
     /** `pending`, or the caller's own `loading`. Both disable the footer. */
     busy: boolean;
 }
+/**
+ * The confirm button's behaviour — the pending state, the error routing, and the close on
+ * success — shared by the three overlays, so they agree on what "confirm" means. For a bespoke
+ * surface that still needs that lifecycle.
+ */
 export declare function useOverlayActions({ close, open, onConfirm, onAsyncConfirm, closeOnAsyncComplete, confirmTone, loading, formId, onCancel, onError, strings, defaults, emphasis, tone, }: UseOverlayActionsOptions): UseOverlayActionsReturn;

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

@@ -23,6 +23,11 @@ export interface UseOverlayVisibilityReturn {
     /** `{...visibility.overlayProps}` on the overlay. */
     overlayProps: OverlayVisibilityProps;
 }
+/**
+ * One overlay's state, controlled or not, so a component that supports both its own trigger
+ * and external openers keeps one source of truth: `open`, `setOpen`, `show`, `hide`, `toggle`,
+ * and `overlayProps`, which spreads straight onto any overlay in the kit.
+ */
 export declare function useOverlayVisibility({ defaultOpen, open: controlledOpen, onOpenChange, onOpen, onClose, }?: UseOverlayVisibilityOptions): UseOverlayVisibilityReturn;
 export type OverlayVisibilityGroupState<TKey extends string = string> = Record<TKey, boolean>;
 export interface UseOverlayVisibilityGroupOptions<TKey extends string = string> {
@@ -33,5 +38,9 @@ export interface UseOverlayVisibilityGroupOptions<TKey extends string = string>
     closeOthersOnOpen?: boolean;
 }
 export type UseOverlayVisibilityGroupReturn<TKey extends string = string> = Record<TKey, UseOverlayVisibilityReturn>;
-/** Several overlays keyed by name from one hook, coordinated by `closeOthersOnOpen`. */
+/**
+ * Several overlays keyed by name from one hook: one handle per overlay when a component drives
+ * several — create, edit, delete. Three separate useState calls is how two of them end up open
+ * at once; `closeOthersOnOpen` is for a set where two open at once is never right.
+ */
 export declare function useOverlayVisibilityGroup<TKey extends string>(keys: readonly TKey[], { defaultOpen, open: controlledOpen, onOpenChange, closeOthersOnOpen, }?: UseOverlayVisibilityGroupOptions<TKey>): UseOverlayVisibilityGroupReturn<TKey>;

package/dist/components/features/products/product-cards.d.ts

@@ -1,9 +1,25 @@
 import { ProductContractOverviewProps, ProductDetailsCardProps, ProductOperationsCardProps, ProductOptionsSummaryProps, ProductOverviewProps, ProductPoliciesCardProps, ProductQuotePreviewCardProps, ProductReadinessCardProps, ProductStructureCardProps } from './products.types.js';
+/**
+ * What a product still needs before it is ready: a score and the checks behind it. One of the
+ * cards a product page is assembled from, each a ContentBlock holding a list with the same row
+ * verbs.
+ */
 export declare function ProductReadinessCard({ items, score, scoreLabel, summary, onCreateReadinessItem, onSelectReadinessItem, onEditReadinessItem, onDeleteReadinessItem, renderReadinessItemActions, actions, footerSlot, renderItem, empty, className, strings, }: ProductReadinessCardProps): import("react").JSX.Element;
 export declare function ProductStructureCard({ metrics, onCreateMetric, onSelectMetric, onEditMetric, onDeleteMetric, renderMetricActions, actions, footerSlot, empty, className, strings, }: ProductStructureCardProps): import("react").JSX.Element;
 export declare function ProductOperationsCard({ items, onCreateOperation, onSelectOperation, onEditOperation, onDeleteOperation, renderOperationActions, actions, footerSlot, renderItem, empty, className, strings, }: ProductOperationsCardProps): import("react").JSX.Element;
+/**
+ * The facts that identify a product. With ProductPoliciesCard, one of the two remaining cards
+ * a product page is assembled from: each a ContentBlock with a list inside and the same four
+ * verbs on every row.
+ */
 export declare function ProductDetailsCard({ title, description, metadata, media, onEditDetails, actions, headerEnd: end, footerSlot, empty, className, strings, }: ProductDetailsCardProps): import("react").JSX.Element;
+/** The contract a product sells under: its metrics, its terms, and its rules. */
 export declare function ProductContractOverview({ metricColumns, metrics, terms, rules, onOpenContract, onEditContract, onCreateRule, onSelectRule, onEditRule, onDeleteRule, renderRuleActions, actions, footerSlot, empty, className, strings, }: ProductContractOverviewProps): import("react").JSX.Element;
+/**
+ * What the customer agrees to. With ProductDetailsCard, one of the two remaining cards a
+ * product page is assembled from: each a ContentBlock with a list inside and the same four
+ * verbs on every row.
+ */
 export declare function ProductPoliciesCard({ policies, onCreatePolicy, onSelectPolicy, onEditPolicy, onDeletePolicy, renderPolicyActions, actions, footerSlot, empty, className, strings, }: ProductPoliciesCardProps): import("react").JSX.Element;
 export declare function ProductOptionsSummary({ options, onManageOptions, onCreateOption, onSelectOption, onEditOption, onDeleteOption, renderOptionActions, actions, footerSlot, empty, className, strings, }: ProductOptionsSummaryProps): import("react").JSX.Element;
 export declare function ProductOverview({ metricColumns, title, description, metrics, media, status, statusTone, actions, headerEnd: end, footerSlot, className, strings, }: ProductOverviewProps): import("react").JSX.Element;

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

@@ -1,2 +1,7 @@
 import { ProductOptionsMatrixProps } from './products.types.js';
+/**
+ * The option groups a product's variants are generated from: one card with ruled rows, because
+ * the options are one ordered list. The whole row is the edit target, and the editor replaces
+ * it in place.
+ */
 export declare function ProductOptionsMatrix({ optionGroups, surface, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, confirmDelete, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onSaveEditingOption, onCancelEditingOption, onToggleUsedForVariants, onReorderOptions, actions, footerSlot, empty, className, strings, }: ProductOptionsMatrixProps): import("react").JSX.Element;

package/dist/components/features/products/product-parts.d.ts

@@ -1,12 +1,18 @@
 import { ReactNode } from 'react';
 import { TableAction } from '../table/index.js';
 import { ProductOperationsItem, ProductOptionActionMenuProps, ProductOptionSummary, ProductPolicySummary, ProductReadinessItem, ProductStructureMetric, ProductTone } from './products.types.js';
+/**
+ * A row's state as a dot. One of the pieces every product surface shares: tone is a data
+ * attribute rather than six class names, so a row's state is one string in the DOM and the CSS
+ * reads it once.
+ */
 export declare function ProductToneDot({ tone }: {
     tone?: ProductTone;
 }): import("react").JSX.Element;
 /**
  * A variant's picture, or a dashed slot where one would go (a grey square reads as a
- * failed image). Only a button with `onSelect`; otherwise the slot is inert and muted.
+ * failed image). Only a button with `onSelect`; otherwise the slot is inert and muted. One of
+ * the pieces every product surface shares.
  */
 export declare function ProductThumbnail({ src, alt, media, onSelect, label, className, }: {
     src?: string;
@@ -18,34 +24,62 @@ export declare function ProductThumbnail({ src, alt, media, onSelect, label, cla
     label?: string;
     className?: string;
 }): import("react").JSX.Element;
+/**
+ * What a product card shows with nothing in it, sized to the card rather than to the page — a
+ * full-page empty state inside a half-width card reads as a broken layout.
+ */
 export declare function ProductEmptyState({ title, description, action, className, }: {
     title: ReactNode;
     description: ReactNode;
     action?: ReactNode;
     className?: string;
 }): import("react").JSX.Element;
+/**
+ * A row's verbs, built from one array so the overflow cannot offer what the button already
+ * does. Three menus rather than one — this, ProductVariantActionMenu and
+ * ProductOptionActionMenu — because a variant, an option and a row answer to different sets.
+ */
 export declare function ProductRowActions<TItem extends object>({ item, actions, menuLabel, className, }: {
     item: TItem;
     actions: TableAction<TItem>[];
     menuLabel: string;
     className?: string;
 }): import("react").JSX.Element | null;
+/**
+ * A structure metric's row, with the number in the trailing lane. Three cards, one row shape: the
+ * rows differ only in what sits in the trailing lane — a badge, a number, a value — so there is one
+ * row component and three wrappers rather than four near-identical ones.
+ */
 export declare function ProductStructureMetricRow({ metric, actions, }: {
     metric: ProductStructureMetric;
     actions?: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * A readiness check's row, with a badge in the trailing lane. Three cards, one row shape: the
+ * rows differ only in what sits in the trailing lane — a badge, a number, a value — so there is
+ * one row component and three wrappers rather than four near-identical ones.
+ */
 export declare function ProductReadinessRow({ item, actionFallback, onSelect, actions, }: {
     item: ProductReadinessItem;
     actionFallback: ReactNode;
     onSelect?: () => void;
     actions?: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * An operation's row, with a value in the trailing lane. Three cards, one row shape: the rows
+ * differ only in what sits in the trailing lane — a badge, a number, a value — so there is one
+ * row component and three wrappers rather than four near-identical ones.
+ */
 export declare function ProductOperationRow({ item, actionFallback, onSelect, actions, }: {
     item: ProductOperationsItem;
     actionFallback: ReactNode;
     onSelect?: () => void;
     actions?: ReactNode;
 }): import("react").JSX.Element;
+/**
+ * An option's or a policy's row, on the same row shape as the readiness, structure and
+ * operations rows, which differ only in what sits in the trailing lane.
+ */
 export declare function ProductSummaryRow({ item, actionLabel, onSelect, actions, }: {
     item: ProductOptionSummary | ProductPolicySummary;
     actionLabel?: ReactNode;
@@ -54,12 +88,14 @@ export declare function ProductSummaryRow({ item, actionLabel, onSelect, actions
 }): import("react").JSX.Element;
 /**
  * The per-option overflow menu, exported for screens that lay out options themselves and
- * want the same verbs and labels as the summary card.
+ * want the same verbs and labels as the summary card. Built from one array, so the overflow
+ * cannot offer what the button already does.
  */
 export declare function ProductOptionActionMenu({ option, index, onSelectOption, onEditOption, onDeleteOption, renderOptionActions, menuLabel, className, strings, }: ProductOptionActionMenuProps): import("react").JSX.Element;
 /**
- * A label/value pair whose label is visually hidden while a column heading names the value,
- * and shown once the table collapses at narrow widths.
+ * A label/value pair that survives losing its table: the label is screen-reader-only while a
+ * column heading names the value, and becomes visible below the md breakpoint, where the table
+ * collapses and the headings are gone. One of the pieces every product surface shares.
  */
 export declare function ProductVariantCell({ label, weight, className, children, }: {
     label: ReactNode;

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

@@ -1,2 +1,7 @@
 import { ProductVariantDetailsProps } from './products.types.js';
+/**
+ * One variant, read-only: what it is, what it costs, and which options it stands for. `variant`
+ * is optional because the panel is also what a page shows before one is chosen. Facts derive
+ * from the variant's own fields; `metadata` replaces them.
+ */
 export declare function ProductVariantDetails({ variant, metadata, optionItems, media, onBack, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onSelectOption, actions, headerEnd, footerSlot, empty, renderActions, renderMetadata, renderOption, className, strings, }: ProductVariantDetailsProps): import("react").JSX.Element;

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

@@ -1,2 +1,6 @@
 import { ProductVariantEditorProps } from './products.types.js';
+/**
+ * The variant form. Values stay strings — the consumer parses on submit — so "24.00" is never
+ * rewritten under the cursor.
+ */
 export declare function ProductVariantEditor({ value: valueProp, defaultValue, optionFields, statusOptions, onValueChange, onSubmit, onError, onCancel, onDelete, actions, headerEnd, footerSlot, disabled, submitting, className, strings, }: ProductVariantEditorProps): import("react").JSX.Element;