themelia-ui 2.0.1 → 3.0.0

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;

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

@@ -1,4 +1,8 @@
 import { ProductVariantActionMenuProps, ProductVariantsBulkTableProps, ProductVariantsManagerProps, ProductVariantsTableProps } from './products.types.js';
+/**
+ * A variant's verbs, built from one array so the overflow cannot offer what the button already
+ * does. A separate menu from an option's or a row's, because each answers to a different set.
+ */
 export declare function ProductVariantActionMenu({ variant, index, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, menuLabel, className, strings, }: ProductVariantActionMenuProps): import("react").JSX.Element | null;
 export declare function ProductVariantsTable({ variants, onCreateVariant, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, actions, footerSlot, empty, className, strings, }: ProductVariantsTableProps): import("react").JSX.Element;
 export declare function ProductVariantsBulkTable({ variants, optionGroups, groupByOptionId, visibleColumns, optionCombinationDisplay, cellDisplay, selectionMode, renderOptionCombination, selectedVariantIds, defaultSelectedVariantIds, onSelectedVariantIdsChange, onVariantFieldChange, onVariantFieldBlur, onCreateVariant, onGenerateVariants, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onSetVariantImage, onBulkEdit, onBulkDelete, renderVariantActions, renderBulkActions, actions, headerEnd, footerSlot, empty, surface, className, strings, }: ProductVariantsBulkTableProps): import("react").JSX.Element;

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

@@ -6,13 +6,22 @@ import { SemanticTone } from '../../../lib/component-vocabulary.js';
 import type * as Strings from "./products.strings.js";
 /** No `secondary`: it means "not this one" rather than a state a product can be in. */
 export type ProductTone = Exclude<SemanticTone, "secondary">;
-/** `card` frames the surface; `embedded` renders it bare inside one that already exists. */
+/**
+ * How ProductOptionsMatrix and ProductVariantsBulkTable draw their frame: `card` frames the
+ * surface; `embedded` renders it bare inside one that already exists.
+ */
 export type ProductSurface = "card" | "embedded";
 export interface ProductReadinessItem {
     id: string;
     label: ReactNode;
     description?: ReactNode;
     value?: ReactNode;
+    /**
+     * The row's state colour: `neutral`, `primary`, `success`, `warning`, `destructive` or
+     * `info`. No `secondary`: it means “not this one”, which is not a state a product can be in.
+     * An item that is `completed` with no tone derives success, so ticking a box does not also
+     * mean remembering the colour.
+     */
     tone?: ProductTone;
     completed?: boolean;
     actionLabel?: ReactNode;
@@ -26,7 +35,10 @@ export interface ProductRowActionContext {
 }
 export interface ProductReadinessCardProps {
     items?: ProductReadinessItem[];
-    /** 0–100, clamped. */
+    /**
+     * 0–100, clamped — a percentage bar cannot show 140, and a NaN would render as an empty
+     * track.
+     */
     score?: number;
     scoreLabel?: ReactNode;
     summary?: ReactNode;
@@ -37,6 +49,10 @@ export interface ProductReadinessCardProps {
     renderReadinessItemActions?: (item: ProductReadinessItem, context: ProductRowActionContext) => ReactNode;
     actions?: ActionDefinition[];
     footerSlot?: ReactNode;
+    /**
+     * Replaces a whole row. The rows are one component with three wrappers, so a consumer
+     * replacing one is replacing the same shape everywhere it appears.
+     */
     renderItem?: (item: ProductReadinessItem, index: number) => ReactNode;
     empty?: ReactNode;
     className?: string;
@@ -88,7 +104,10 @@ export interface ProductOperationsCardProps {
 }
 export interface ProductDetailsCardProps {
     title?: ReactNode;
-    /** `false` suppresses the default description rather than showing it empty. */
+    /**
+     * `false` suppresses the default description rather than rendering it empty — which is the
+     * difference between a card with no subtitle and a card with a blank line where one was.
+     */
     description?: ReactNode | false;
     metadata?: MetadataListItem[];
     media?: ReactNode;
@@ -117,6 +136,10 @@ export interface ProductPolicySummary {
 }
 export interface ProductContractOverviewProps {
     metrics?: ProductMetricSummary[];
+    /**
+     * The contract's facts. They go through MetadataList, so an email or an SKU is rendered by
+     * the kind that knows how; this module does not restate it.
+     */
     terms?: MetadataListItem[];
     rules?: ProductPolicySummary[];
     onOpenContract?: () => void;
@@ -200,12 +223,22 @@ export interface ProductOptionsMatrixProps {
     onCreateOption?: () => void;
     onEditOption?: (option: ProductOptionGroup) => void;
     onDeleteOption?: (option: ProductOptionGroup) => void;
-    /** Off when the app already confirms, so nobody is asked twice. */
+    /**
+     * Asks before removing an option. Removing an option removes every variant generated from it
+     * — which is not visible from the option's own row. Off when the app already confirms, so
+     * nobody is asked twice.
+     * @default true
+     */
     confirmDelete?: boolean;
     onAddValue?: (option: ProductOptionGroup) => void;
     onDeleteValue?: (option: ProductOptionGroup, value: ProductOptionValue) => void;
     onOptionNameChange?: (option: ProductOptionGroup, value: string) => void;
     onValueLabelChange?: (option: ProductOptionGroup, value: ProductOptionValue, label: string) => void;
+    /**
+     * The staged name and values, committed together. Cancel discards them; the draft is
+     * re-seeded from the option each time editing opens, so a cancelled edit cannot leak into the
+     * next one.
+     */
     onSaveEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
     onCancelEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
     onToggleUsedForVariants?: (option: ProductOptionGroup, used: boolean) => void;
@@ -300,17 +333,34 @@ export interface ProductVariantFieldChangeContext {
 export interface ProductVariantsBulkTableProps {
     variants?: ProductVariantRow[];
     optionGroups?: ProductOptionGroup[];
-    /** Groups rows under the values of this option. `null` leaves the list flat. */
+    /**
+     * Groups rows under that option's values, in the order the option declares them — not
+     * alphabetically, and not by whichever variant was created first. `null` leaves the list
+     * flat.
+     */
     groupByOptionId?: string | null;
     visibleColumns?: readonly ProductVariantsBulkTableColumn[];
     optionCombinationDisplay?: ProductVariantOptionCombinationDisplay;
+    /**
+     * `text` or `field`, for every editable field or per field, so a table can make price
+     * editable and leave stock read-only — which is what a price update run actually needs.
+     */
     cellDisplay?: ProductVariantCellDisplayConfig;
     selectionMode?: ProductVariantSelectionMode;
     renderOptionCombination?: (variant: ProductVariantRow, values: ReactNode[]) => ReactNode;
     selectedVariantIds?: string[];
     defaultSelectedVariantIds?: string[];
     onSelectedVariantIdsChange?: (variantIds: string[], variants: ProductVariantRow[]) => void;
+    /**
+     * Fires on every edit of an in-place field. Both this and `onVariantFieldBlur` exist, and the
+     * consumer picks: change alone makes every keystroke a state update; blur alone loses the
+     * value if the row is removed mid-edit.
+     */
     onVariantFieldChange?: (variant: ProductVariantRow, field: ProductVariantEditableField, value: string, context: ProductVariantFieldChangeContext) => void;
+    /**
+     * Fires when an in-place field loses focus. Blur alone loses the value if the row is removed
+     * mid-edit; pair it with `onVariantFieldChange` where that matters.
+     */
     onVariantFieldBlur?: (variant: ProductVariantRow, field: ProductVariantEditableField, value: string, context: ProductVariantFieldChangeContext) => void;
     onCreateVariant?: () => void;
     onGenerateVariants?: () => void;
@@ -321,6 +371,11 @@ export interface ProductVariantsBulkTableProps {
     onBulkEdit?: (variants: ProductVariantRow[]) => void;
     onBulkDelete?: (variants: ProductVariantRow[]) => void;
     renderVariantActions?: (variant: ProductVariantRow, context: ProductVariantActionContext) => ReactNode;
+    /**
+     * Replaces the default pair of bulk actions. The context carries the selected rows, the
+     * counts, and both `clearSelection` and `setSelectedIds`, so a custom bar can act and then
+     * deselect.
+     */
     renderBulkActions?: (context: ProductVariantBulkActionContext) => ReactNode;
     /** Makes the picture slot pressable. Without it the slot is inert. */
     onSetVariantImage?: (variant: ProductVariantRow) => void;
@@ -333,7 +388,11 @@ export interface ProductVariantsBulkTableProps {
     strings?: Partial<Strings.ProductVariantBulkTableStrings>;
 }
 export interface ProductVariantsManagerProps extends Pick<ProductOptionsMatrixProps, "optionGroups" | "editingOptionId" | "defaultEditingOptionId" | "onEditingOptionIdChange" | "onCreateOption" | "onEditOption" | "onDeleteOption" | "onAddValue" | "onDeleteValue" | "onOptionNameChange" | "onValueLabelChange" | "onSaveEditingOption" | "onCancelEditingOption" | "onToggleUsedForVariants" | "onReorderOptions" | "confirmDelete">, Pick<ProductVariantsBulkTableProps, "variants" | "visibleColumns" | "optionCombinationDisplay" | "cellDisplay" | "selectionMode" | "selectedVariantIds" | "defaultSelectedVariantIds" | "onSelectedVariantIdsChange" | "onVariantFieldChange" | "onVariantFieldBlur" | "onCreateVariant" | "onGenerateVariants" | "onSelectVariant" | "onEditVariant" | "onDuplicateVariant" | "onDeleteVariant" | "onBulkEdit" | "onBulkDelete" | "renderVariantActions" | "renderBulkActions"> {
-    /** Controlled grouping. Uncontrolled, the manager's own Select drives it. */
+    /**
+     * Controlled grouping: groups rows under that option's values, in the order the option
+     * declares them — not alphabetically, and not by whichever variant was created first. `null`
+     * leaves the list flat. Uncontrolled, the manager's own Select drives it.
+     */
     groupByOptionId?: string | null;
     defaultGroupByOptionId?: string | null;
     onGroupByOptionIdChange?: (optionId: string | null) => void;
@@ -341,7 +400,15 @@ export interface ProductVariantsManagerProps extends Pick<ProductOptionsMatrixPr
     showGroupBy?: boolean;
     className?: string;
     strings?: Partial<Strings.ProductVariantsManagerStrings>;
+    /**
+     * The option matrix's own copy. The two children keep their own copy objects: one merged bag
+     * would collide on title, description and the create labels, which both of them have.
+     */
     optionsStrings?: Partial<Strings.ProductOptionsMatrixStrings>;
+    /**
+     * The variant table's own copy, kept apart from `optionsStrings` because both children have a
+     * title, a description and create labels.
+     */
     variantsStrings?: Partial<Strings.ProductVariantBulkTableStrings>;
 }
 export interface ProductOptionActionContext extends ProductRowActionContext {
@@ -360,7 +427,10 @@ export interface ProductOptionActionMenuProps {
     strings?: Partial<Strings.ProductOptionActionMenuStrings>;
 }
 export interface ProductVariantDetailsProps {
-    /** Absent renders the empty state (this surface is often bound to a selection). */
+    /**
+     * Optional. Absent renders the empty state — this panel is usually bound to a selection, and
+     * “nothing chosen yet” is a thing to say, not a reason to unmount.
+     */
     variant?: ProductVariantSummary;
     /** Replaces the derived facts. The default is built from the variant's own fields. */
     metadata?: MetadataListItem[];
@@ -413,6 +483,10 @@ export interface ProductVariantOptionField {
 export interface ProductVariantEditorProps {
     value?: ProductVariantEditorValues;
     defaultValue?: ProductVariantEditorValues;
+    /**
+     * A select when the field carries choices, a text input when it does not — an app with a
+     * free-text status should not have to invent a list to use this.
+     */
     optionFields?: ProductVariantOptionField[];
     statusOptions?: ProductChoice[];
     onValueChange?: (value: ProductVariantEditorValues) => void;
@@ -425,7 +499,12 @@ export interface ProductVariantEditorProps {
     headerEnd?: ReactNode;
     footerSlot?: ReactNode;
     disabled?: boolean;
-    /** Shows the pending state and blocks a repeat submit. */
+    /**
+     * Shows the pending state and blocks a repeat submit. OR-ed with an internal flag: a
+     * consumer holding the request already knows it is in flight; one that just handed over an
+     * async `onSubmit` does not, and a form that stays live during a save takes the same submit
+     * twice.
+     */
     submitting?: boolean;
     className?: string;
     strings?: Partial<Strings.ProductVariantEditorStrings>;
@@ -451,7 +530,10 @@ export interface ProductQuotePreviewLine {
     value: ReactNode;
     description?: ReactNode;
     tone?: ProductTone;
-    /** Ruled off and emphasised: the line the rest add up to. */
+    /**
+     * Rules the line off and weights it: the line the rest add up to. Not a tint — a filled band
+     * on the last line makes a total look like an alert, which is the one thing a total is not.
+     */
     emphasis?: boolean;
 }
 export interface ProductQuotePreviewCardProps {