themelia-react-ui 0.0.0-stage → 1.0.0

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

@@ -0,0 +1,906 @@
+import type { ReactNode } from 'react';
+import type { BadgeTone } from '../../base/badge';
+import type { ActionMenuAction } from '../../base/action-menu';
+import type { MetadataListItem } from '../../blocks/data-display/metadata';
+import type { StringsProp } from '../../../lib/strings';
+import type { SemanticTone } from '../../../lib/component-vocabulary';
+import type { ProductContractOverviewStrings, ProductDetailsCardStrings, ProductOperationsCardStrings, ProductOptionActionMenuStrings, ProductOptionsMatrixStrings, ProductOptionsSummaryStrings, ProductOverviewStrings, ProductPoliciesCardStrings, ProductQuotePreviewCardStrings, ProductReadinessCardStrings, ProductStructureCardStrings, ProductVariantActionMenuStrings, ProductVariantBulkTableStrings, ProductVariantDetailsStrings, ProductVariantEditorStrings, ProductVariantsManagerStrings, ProductVariantsTableStrings } from './products.strings';
+export type ProductTone = Exclude<SemanticTone, 'secondary'>;
+export interface ProductReadinessItem {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Value shown beside the label. */
+    value?: ReactNode;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ProductTone;
+    /** Marks the entry as done. */
+    completed?: boolean;
+    /** Text for the entry’s inline action. */
+    actionLabel?: ReactNode;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+}
+export interface ProductReadinessCardProps {
+    /** Entries to render. */
+    items?: ProductReadinessItem[];
+    /** Completion score, 0–100. */
+    score?: number;
+    /** Caption shown beside the score. */
+    scoreLabel?: ReactNode;
+    /** Sentence summarising the card’s state. */
+    summary?: ReactNode;
+    /** Fired when the user asks to create a readiness item. */
+    onCreateReadinessItem?: () => void;
+    /** Fired when a readiness item is activated. */
+    onSelectReadinessItem?: (item: ProductReadinessItem) => void;
+    /** Fired when a readiness item is edited. */
+    onEditReadinessItem?: (item: ProductReadinessItem) => void;
+    /** Fired when a readiness item is removed. */
+    onDeleteReadinessItem?: (item: ProductReadinessItem) => void;
+    /** Replaces the per-readiness item action controls. */
+    renderReadinessItemActions?: (item: ProductReadinessItem, context: ProductReadinessItemActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Replaces the default item rendering. */
+    renderItem?: (item: ProductReadinessItem, index: number) => ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductReadinessCardStrings>;
+}
+export interface ProductReadinessItemActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductStructureMetric {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Value shown beside the label. */
+    value: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ProductTone;
+    /** Leading glyph. */
+    icon?: ReactNode;
+}
+export interface ProductStructureCardProps {
+    /** Metrics to render. */
+    metrics?: ProductStructureMetric[];
+    /** Fired when the user asks to create a metric. */
+    onCreateMetric?: () => void;
+    /** Fired when a metric is activated. */
+    onSelectMetric?: (metric: ProductStructureMetric) => void;
+    /** Fired when a metric is edited. */
+    onEditMetric?: (metric: ProductStructureMetric) => void;
+    /** Fired when a metric is removed. */
+    onDeleteMetric?: (metric: ProductStructureMetric) => void;
+    /** Replaces the per-metric action controls. */
+    renderMetricActions?: (metric: ProductStructureMetric, context: ProductStructureMetricActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductStructureCardStrings>;
+}
+export interface ProductStructureMetricActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductOperationsItem {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Value shown beside the label. */
+    value?: ReactNode;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ProductTone;
+    /** Text for the entry’s inline action. */
+    actionLabel?: ReactNode;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+}
+export interface ProductOperationsCardProps {
+    /** Entries to render. */
+    items?: ProductOperationsItem[];
+    /** Fired when the user asks to create an operation. */
+    onCreateOperation?: () => void;
+    /** Fired when an operation is activated. */
+    onSelectOperation?: (item: ProductOperationsItem) => void;
+    /** Fired when an operation is edited. */
+    onEditOperation?: (item: ProductOperationsItem) => void;
+    /** Fired when an operation is removed. */
+    onDeleteOperation?: (item: ProductOperationsItem) => void;
+    /** Replaces the per-operation action controls. */
+    renderOperationActions?: (item: ProductOperationsItem, context: ProductOperationActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Replaces the default item rendering. */
+    renderItem?: (item: ProductOperationsItem, index: number) => ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductOperationsCardStrings>;
+}
+export interface ProductOperationActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductDetailsCardProps {
+    /** Card title. */
+    title?: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode | false;
+    /** Label/value facts rendered as a metadata list. */
+    metadata?: MetadataListItem[];
+    /** Leading media for the card. */
+    media?: ReactNode;
+    /** Fired when a details is edited. */
+    onEditDetails?: () => void;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content at the end of the header, before the overflow menu. */
+    headerEnd?: ReactNode;
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductDetailsCardStrings>;
+}
+export interface ProductMetricSummary {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Value shown beside the label. */
+    value: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ProductTone;
+}
+export interface ProductPolicySummary {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Value shown beside the label. */
+    value?: ReactNode;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ProductTone;
+    /** Chip rendered beside the label. */
+    badge?: ReactNode;
+}
+export interface ProductContractOverviewProps {
+    /** Metrics to render. */
+    metrics?: ProductMetricSummary[];
+    /** Contract terms rendered as a metadata list. */
+    terms?: MetadataListItem[];
+    /** Policy rules to render. */
+    rules?: ProductPolicySummary[];
+    /** Fired when a contract is opened. */
+    onOpenContract?: () => void;
+    /** Fired when a contract is edited. */
+    onEditContract?: () => void;
+    /** Fired when the user asks to create a rule. */
+    onCreateRule?: () => void;
+    /** Fired when a rule is activated. */
+    onSelectRule?: (rule: ProductPolicySummary) => void;
+    /** Fired when a rule is edited. */
+    onEditRule?: (rule: ProductPolicySummary) => void;
+    /** Fired when a rule is removed. */
+    onDeleteRule?: (rule: ProductPolicySummary) => void;
+    /** Replaces the per-rule action controls. */
+    renderRuleActions?: (rule: ProductPolicySummary, context: ProductRuleActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductContractOverviewStrings>;
+}
+export interface ProductRuleActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductOptionSummary {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Values belonging to this option. */
+    values?: readonly ReactNode[];
+    /** Value shown beside the label. */
+    value?: ReactNode;
+    /** Semantic tone driving the entry's colour. */
+    tone?: ProductTone;
+    /** Chip rendered beside the label. */
+    badge?: ReactNode;
+}
+export interface ProductOptionValue {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Chip rendered beside the label. */
+    badge?: ReactNode;
+}
+export interface ProductOptionGroup {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display name. */
+    name: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Values belonging to this option. */
+    values?: readonly ProductOptionValue[];
+    /** Whether this option takes part in variant generation. */
+    usedForVariants?: boolean;
+    /** Sort order among sibling options. */
+    position?: number;
+    /** Chip rendered beside the label. */
+    badge?: ReactNode;
+}
+export interface ProductOptionsSummaryProps {
+    /** Options to render. */
+    options?: ProductOptionSummary[];
+    /** Fired when the user asks to manage options. */
+    onManageOptions?: () => void;
+    /** Fired when the user asks to create an option. */
+    onCreateOption?: () => void;
+    /** Fired when an option is activated. */
+    onSelectOption?: (option: ProductOptionSummary) => void;
+    /** Fired when an option is edited. */
+    onEditOption?: (option: ProductOptionSummary) => void;
+    /** Fired when an option is removed. */
+    onDeleteOption?: (option: ProductOptionSummary) => void;
+    /** Replaces the per-option action controls. */
+    renderOptionActions?: (option: ProductOptionSummary, context: ProductOptionActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Replaces the default option rendering. */
+    renderOption?: (option: ProductOptionSummary, index: number) => ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductOptionsSummaryStrings>;
+}
+export interface ProductOptionActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductOptionsMatrixActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+    /** Fired when a value is added. */
+    onAddValue?: () => void;
+    /** Fired when a collapsed is toggled. */
+    onToggleCollapsed?: () => void;
+    /** Whether the option is currently collapsed. */
+    collapsed?: boolean;
+}
+export interface ProductOptionValueActionContext {
+    /** The option group the value belongs to. */
+    option: ProductOptionGroup;
+    /** Zero-based position of the option group. */
+    optionIndex: number;
+    /** Zero-based position of the value inside its group. */
+    valueIndex: number;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductOptionEditDraft {
+    /** Display name. */
+    name: string;
+    /** Values belonging to this option. */
+    values: ProductOptionValue[];
+}
+export type ProductVariantsSurface = 'card' | 'embedded';
+export interface ProductOptionsMatrixProps {
+    /** Option groups to render, in display order. */
+    optionGroups?: ProductOptionGroup[];
+    /** `card` frames the table; `embedded` renders it bare inside an existing surface. */
+    surface?: ProductVariantsSurface;
+    /** Ids of the collapsed option groups. Controlled. */
+    collapsedOptionIds?: string[];
+    /** Initially collapsed option group ids. */
+    defaultCollapsedOptionIds?: string[];
+    onCollapsedOptionIdsChange?: (optionIds: string[], options: ProductOptionGroup[]) => void;
+    /** Id of the option group currently being edited. Controlled. */
+    editingOptionId?: string | null;
+    /** Option group opened for editing on first render. */
+    defaultEditingOptionId?: string | null;
+    onEditingOptionIdChange?: (optionId: string | null, option?: ProductOptionGroup) => void;
+    /** Fired when the user asks to create an option. */
+    onCreateOption?: () => void;
+    /** Fired when an option is edited. */
+    onEditOption?: (option: ProductOptionGroup) => void;
+    /** Fired when an option is removed. */
+    onDeleteOption?: (option: ProductOptionGroup) => void;
+    /**
+     * Confirms before deleting an option group. Default: `true`. Set `false`
+     * when the app already confirms upstream, so the user is not asked twice.
+     */
+    confirmDelete?: boolean;
+    /** Fired when a value is added. */
+    onAddValue?: (option: ProductOptionGroup) => void;
+    /** Fired when a value is removed. */
+    onDeleteValue?: (option: ProductOptionGroup, value: ProductOptionValue) => void;
+    onOptionNameChange?: (option: ProductOptionGroup, value: string) => void;
+    onValueLabelChange?: (option: ProductOptionGroup, value: ProductOptionValue, label: string) => void;
+    /** Fired when editing an editing option finishes. */
+    onDoneEditingOption?: (option: ProductOptionGroup) => void;
+    /** Fired when an editing option is saved. */
+    onSaveEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
+    /** Fired when editing an editing option is cancelled. */
+    onCancelEditingOption?: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void;
+    /** Fired when an used for variants is toggled. */
+    onToggleUsedForVariants?: (option: ProductOptionGroup, used: boolean) => void;
+    /** Replaces the per-option action controls. */
+    renderOptionActions?: (option: ProductOptionGroup, context: ProductOptionsMatrixActionContext) => ReactNode;
+    /** Replaces the default value rendering. */
+    renderValue?: (value: ProductOptionValue, context: ProductOptionValueActionContext) => ReactNode;
+    /** Renders the header. */
+    showHeader?: boolean;
+    /** Renders the collapse controls. */
+    showCollapseControls?: boolean;
+    /** Renders the inline actions. */
+    showInlineActions?: boolean;
+    /** Renders the variant toggle. */
+    showVariantToggle?: boolean;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content at the end of the header, before the overflow menu. */
+    headerEnd?: ReactNode;
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductOptionsMatrixStrings>;
+}
+export interface ProductOptionActionMenuProps {
+    /** The option group the value belongs to. */
+    option: ProductOptionSummary;
+    /** Zero-based position of the entry in its list. */
+    index?: number;
+    /** Fired when an option is activated. */
+    onSelectOption?: ProductOptionsSummaryProps['onSelectOption'];
+    /** Fired when an option is edited. */
+    onEditOption?: ProductOptionsSummaryProps['onEditOption'];
+    /** Fired when an option is removed. */
+    onDeleteOption?: ProductOptionsSummaryProps['onDeleteOption'];
+    /** Replaces the per-option action controls. */
+    renderOptionActions?: ProductOptionsSummaryProps['renderOptionActions'];
+    /** Accessible name for the overflow trigger. */
+    menuLabel?: string;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductOptionActionMenuStrings>;
+}
+export interface ProductQuoteLine {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Formatted quantity for the line. */
+    quantity?: ReactNode;
+    /** Formatted amount for the line. */
+    amount: ReactNode;
+}
+export interface ProductQuotePreviewCardProps {
+    /** Quote lines to render. */
+    lines?: ProductQuoteLine[];
+    /** Formatted amount before tax and discounts. */
+    subtotal?: ReactNode;
+    /** Formatted tax amount. */
+    tax?: ReactNode;
+    /** Formatted discount, shown as a deduction. */
+    discount?: ReactNode;
+    /** Formatted quote total. */
+    total?: ReactNode;
+    /** Fired when a quote is opened. */
+    onOpenQuote?: () => void;
+    /** Fired when the user asks to create a line. */
+    onCreateLine?: () => void;
+    /** Fired when a line is activated. */
+    onSelectLine?: (line: ProductQuoteLine) => void;
+    /** Fired when a line is edited. */
+    onEditLine?: (line: ProductQuoteLine) => void;
+    /** Fired when a line is removed. */
+    onDeleteLine?: (line: ProductQuoteLine) => void;
+    /** Replaces the per-line action controls. */
+    renderLineActions?: (line: ProductQuoteLine, context: ProductQuoteLineActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductQuotePreviewCardStrings>;
+}
+export interface ProductQuoteLineActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductPoliciesCardProps {
+    /** Policies card configuration. */
+    policies?: ProductPolicySummary[];
+    /** Fired when the user asks to create a policy. */
+    onCreatePolicy?: () => void;
+    /** Fired when a policy is activated. */
+    onSelectPolicy?: (policy: ProductPolicySummary) => void;
+    /** Fired when a policy is edited. */
+    onEditPolicy?: (policy: ProductPolicySummary) => void;
+    /** Fired when a policy is removed. */
+    onDeletePolicy?: (policy: ProductPolicySummary) => void;
+    /** Replaces the per-policy action controls. */
+    renderPolicyActions?: (policy: ProductPolicySummary, context: ProductPolicyActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Replaces the default policy rendering. */
+    renderPolicy?: (policy: ProductPolicySummary, index: number) => ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductPoliciesCardStrings>;
+}
+export interface ProductPolicyActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+}
+export interface ProductVariantSummary {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display name. */
+    name: ReactNode;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Options to render. */
+    options?: readonly ReactNode[];
+    sku?: ReactNode;
+    price?: ReactNode;
+    inventory?: ReactNode;
+    channels?: ReactNode;
+    updatedAt?: ReactNode;
+    status?: ReactNode;
+    statusTone?: BadgeTone;
+}
+export interface ProductVariantRow extends ProductVariantSummary {
+    optionValues?: Record<string, ReactNode>;
+    optionValueIds?: Record<string, string | undefined>;
+}
+export interface ProductVariantActionContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    /** Fired when an entry is activated. */
+    onSelect?: () => void;
+    /** Fired when an entry is edited. */
+    onEdit?: () => void;
+    onDuplicate?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: () => void;
+    isSelected?: boolean;
+    /** Fired when a selected is toggled. */
+    onToggleSelected?: (checked: boolean) => void;
+}
+export interface ProductVariantActionMenuProps {
+    /** Shell treatment. */
+    variant: ProductVariantSummary;
+    /** Zero-based position of the entry in its list. */
+    index?: number;
+    /** Fired when a variant is activated. */
+    onSelectVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when a variant is edited. */
+    onEditVariant?: (variant: ProductVariantSummary) => void;
+    onDuplicateVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when a variant is removed. */
+    onDeleteVariant?: (variant: ProductVariantSummary) => void;
+    /** Replaces the per-variant action controls. */
+    renderVariantActions?: (variant: ProductVariantSummary, context: ProductVariantActionContext) => ReactNode;
+    /** Accessible name for the overflow trigger. */
+    menuLabel?: string;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductVariantActionMenuStrings>;
+}
+export interface ProductVariantsTableProps {
+    /** Variant rows to render. */
+    variants?: ProductVariantSummary[];
+    /** Fired when the user asks to create a variant. */
+    onCreateVariant?: () => void;
+    /** Fired when a variant is activated. */
+    onSelectVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when a variant is edited. */
+    onEditVariant?: (variant: ProductVariantSummary) => void;
+    onDuplicateVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when a variant is removed. */
+    onDeleteVariant?: (variant: ProductVariantSummary) => void;
+    /** Replaces the per-variant action controls. */
+    renderVariantActions?: (variant: ProductVariantSummary, context: ProductVariantActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductVariantsTableStrings>;
+}
+export interface ProductVariantBulkActionContext {
+    selectedRows: ProductVariantRow[];
+    selectedIds: string[];
+    allRows: ProductVariantRow[];
+    selectedCount: number;
+    totalCount: number;
+    allRowsSelected: boolean;
+    clearSelection: () => void;
+    setSelectedIds: (variantIds: string[]) => void;
+}
+export type ProductVariantsBulkTableColumn = 'variant' | 'sku' | 'price' | 'inventory' | 'status' | 'updated';
+export type ProductVariantOptionCombinationDisplay = 'text' | 'tags' | 'none';
+export type ProductVariantCellDisplay = 'text' | 'field';
+export type ProductVariantCellDisplayConfig = ProductVariantCellDisplay | Partial<Record<ProductVariantEditableField, ProductVariantCellDisplay>>;
+export type ProductVariantEditableField = 'sku' | 'price' | 'inventory';
+export type ProductVariantSelectionMode = 'multiple' | 'none';
+export interface ProductVariantOptionCombinationContext {
+    /** Option groups to render, in display order. */
+    optionGroups: ProductOptionGroup[];
+    optionValues: ReactNode[];
+    optionLabel: string;
+    display: ProductVariantOptionCombinationDisplay;
+}
+export interface ProductVariantFieldChangeContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    field: ProductVariantEditableField;
+    previousValue?: ReactNode;
+    /** Value shown beside the label. */
+    value: string;
+}
+export interface ProductVariantCellRenderContext {
+    /** Zero-based position of the entry in its list. */
+    index: number;
+    column: ProductVariantsBulkTableColumn;
+    /** Value shown beside the label. */
+    value?: ReactNode;
+    variantName: ReactNode;
+    optionValues: ReactNode[];
+    optionLabel: string;
+    /** Which editable fields each row exposes, and how. */
+    cellDisplay: ProductVariantCellDisplay;
+    /** Fired with the next value. */
+    onValueChange?: (value: string) => void;
+    onBlur?: (value: string) => void;
+}
+export interface ProductVariantsBulkTableProps {
+    /** Variant rows to render. */
+    variants?: ProductVariantRow[];
+    /** Option groups to render, in display order. */
+    optionGroups?: ProductOptionGroup[];
+    /** Groups rows under the values of this option. `null` leaves the list flat. */
+    groupByOptionId?: string | null;
+    /** Columns to show, in order. Omit for the default set. */
+    visibleColumns?: readonly ProductVariantsBulkTableColumn[];
+    /** How each row's option combination is presented. */
+    optionCombinationDisplay?: ProductVariantOptionCombinationDisplay;
+    /** Which editable fields each row exposes, and how. */
+    cellDisplay?: ProductVariantCellDisplayConfig;
+    /** Whether one variant or several can be selected at a time. */
+    selectionMode?: ProductVariantSelectionMode;
+    /** Replaces the default option combination rendering. */
+    renderOptionCombination?: (variant: ProductVariantRow, context: ProductVariantOptionCombinationContext) => ReactNode;
+    /** Replaces the default cell rendering. */
+    renderCell?: (variant: ProductVariantRow, context: ProductVariantCellRenderContext) => ReactNode;
+    /** Ids of the selected variants. Controlled. */
+    selectedVariantIds?: string[];
+    /** Initially selected variant ids, for uncontrolled use. */
+    defaultSelectedVariantIds?: string[];
+    onSelectedVariantIdsChange?: (variantIds: string[], variants: ProductVariantRow[]) => void;
+    onVariantFieldChange?: (
+    /** Shell treatment. */
+    variant: ProductVariantRow, field: ProductVariantEditableField, 
+    /** Current value. Controlled. */
+    value: string, context: ProductVariantFieldChangeContext) => void;
+    onVariantFieldBlur?: (
+    /** Shell treatment. */
+    variant: ProductVariantRow, field: ProductVariantEditableField, 
+    /** Current value. Controlled. */
+    value: string, context: ProductVariantFieldChangeContext) => void;
+    /** Fired when the user asks to create a variant. */
+    onCreateVariant?: () => void;
+    onGenerateVariants?: () => void;
+    /** Fired when a variant is activated. */
+    onSelectVariant?: (variant: ProductVariantRow) => void;
+    /** Fired when a variant is edited. */
+    onEditVariant?: (variant: ProductVariantRow) => void;
+    onDuplicateVariant?: (variant: ProductVariantRow) => void;
+    /** Fired when a variant is removed. */
+    onDeleteVariant?: (variant: ProductVariantRow) => void;
+    onBulkEdit?: (variants: ProductVariantRow[]) => void;
+    onBulkApply?: (variants: ProductVariantRow[]) => void;
+    onBulkDelete?: (variants: ProductVariantRow[]) => void;
+    /** Replaces the per-variant action controls. */
+    renderVariantActions?: (variant: ProductVariantRow, context: ProductVariantActionContext) => ReactNode;
+    /** Replaces the per-bulk action controls. */
+    renderBulkActions?: (context: ProductVariantBulkActionContext) => ReactNode;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content at the end of the header, before the overflow menu. */
+    headerEnd?: ReactNode;
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** `card` frames the table; `embedded` renders it bare inside an existing surface. */
+    surface?: ProductVariantsSurface;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductVariantBulkTableStrings>;
+}
+export interface ProductVariantsManagerProps extends Pick<ProductOptionsMatrixProps, 'optionGroups' | 'collapsedOptionIds' | 'defaultCollapsedOptionIds' | 'onCollapsedOptionIdsChange' | 'editingOptionId' | 'defaultEditingOptionId' | 'onEditingOptionIdChange' | 'onCreateOption' | 'onEditOption' | 'onDeleteOption' | 'onAddValue' | 'onDeleteValue' | 'onOptionNameChange' | 'onValueLabelChange' | 'onDoneEditingOption' | 'onSaveEditingOption' | 'onCancelEditingOption' | 'onToggleUsedForVariants' | 'renderOptionActions' | 'renderValue'>, Pick<ProductVariantsBulkTableProps, 'variants' | 'groupByOptionId' | 'visibleColumns' | 'optionCombinationDisplay' | 'cellDisplay' | 'selectionMode' | 'renderOptionCombination' | 'renderCell' | 'selectedVariantIds' | 'defaultSelectedVariantIds' | 'onSelectedVariantIdsChange' | 'onVariantFieldChange' | 'onVariantFieldBlur' | 'onCreateVariant' | 'onGenerateVariants' | 'onSelectVariant' | 'onEditVariant' | 'onDuplicateVariant' | 'onDeleteVariant' | 'onBulkEdit' | 'onBulkApply' | 'onBulkDelete' | 'renderVariantActions' | 'renderBulkActions'> {
+    /** Groups rows under the values of this option. `null` leaves the list flat. */
+    groupByOptionId?: string | null;
+    /** Option group used for grouping on first render. */
+    defaultGroupByOptionId?: string | null;
+    onGroupByOptionIdChange?: (optionId: string | undefined, option?: ProductOptionGroup) => void;
+    onSearchVariants?: () => void;
+    onFilterVariants?: () => void;
+    /** Content at the end of the manager's control row. */
+    controlsEnd?: ReactNode;
+    /** Controls offered on the surface. */
+    actions?: ActionMenuAction[];
+    /** Content at the end of the header. */
+    headerEnd?: ReactNode;
+    footerSlot?: ReactNode;
+    className?: string;
+    strings?: StringsProp<ProductVariantsManagerStrings>;
+    /** Copy overrides for the options matrix. */
+    optionsStrings?: ProductOptionsMatrixProps['strings'];
+    /** Copy overrides for the variants table. */
+    variantsStrings?: ProductVariantsBulkTableProps['strings'];
+}
+export interface ProductVariantDetailsProps {
+    /** Shell treatment. */
+    variant?: ProductVariantSummary;
+    /** Label/value facts rendered as a metadata list. */
+    metadata?: MetadataListItem[];
+    optionItems?: ProductOptionSummary[];
+    /** Leading media for the card. */
+    media?: ReactNode;
+    onBack?: () => void;
+    /** Fired when a variant is activated. */
+    onSelectVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when a variant is edited. */
+    onEditVariant?: (variant: ProductVariantSummary) => void;
+    onDuplicateVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when a variant is removed. */
+    onDeleteVariant?: (variant: ProductVariantSummary) => void;
+    /** Fired when an option is activated. */
+    onSelectOption?: (option: ProductOptionSummary) => void;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content at the end of the header, before the overflow menu. */
+    headerEnd?: ReactNode;
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Shown in place of the collection when it has no entries. */
+    empty?: ReactNode;
+    /** Replaces the default actions rendering. */
+    renderActions?: ProductVariantActionMenuProps['renderVariantActions'];
+    /** Replaces the default metadata rendering. */
+    renderMetadata?: (variant: ProductVariantSummary) => ReactNode;
+    /** Replaces the default option rendering. */
+    renderOption?: (option: ProductOptionSummary, index: number) => ReactNode;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductVariantDetailsStrings>;
+}
+export interface ProductChoice {
+    /** Value shown beside the label. */
+    value: string;
+    /** Display label. */
+    label: string;
+    /** Supporting copy shown under the label. */
+    description?: ReactNode;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+}
+export interface ProductVariantOptionField {
+    /** Stable identity for this entry. */
+    id: string;
+    /** Display label. */
+    label: string;
+    /** Value shown beside the label. */
+    value?: string;
+    choices?: ProductChoice[];
+    placeholder?: string;
+    helperText?: string;
+}
+export interface ProductVariantEditorValues {
+    /** Display name. */
+    name?: string;
+    /** Supporting copy shown under the label. */
+    description?: string;
+    sku?: string;
+    price?: string;
+    inventory?: string;
+    status?: string;
+    channels?: string;
+    /** Options to render. */
+    options?: Record<string, string | undefined>;
+}
+export interface ProductVariantEditorProps {
+    /** Value shown beside the label. */
+    value?: ProductVariantEditorValues;
+    defaultValue?: ProductVariantEditorValues;
+    /** Editable option values for the variant. */
+    optionFields?: ProductVariantOptionField[];
+    /** Choices for the variant status select. */
+    statusOptions?: ProductChoice[];
+    onValueChange?: (value: ProductVariantEditorValues) => void;
+    /** Fired when an entry is submitted. */
+    onSubmit?: (value: ProductVariantEditorValues) => void | Promise<void>;
+    /** Receives rejected submissions; persistence and user feedback remain consumer-owned. */
+    onError?: (error: unknown) => void;
+    /** Fired when editing an entry is cancelled. */
+    onCancel?: () => void;
+    /** Fired when an entry is removed. */
+    onDelete?: (value: ProductVariantEditorValues) => void;
+    /** Overflow menu for the surface as a whole. */
+    actions?: ActionMenuAction[];
+    /** Content at the end of the header, before the overflow menu. */
+    headerEnd?: ReactNode;
+    /** Content rendered in the footer. */
+    footerSlot?: ReactNode;
+    /** Renders the entry as unselectable. */
+    disabled?: boolean;
+    /** Shows the pending state and blocks repeat submissions. */
+    submitting?: boolean;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductVariantEditorStrings>;
+}
+export interface ProductOverviewSlots {
+    before?: ReactNode;
+    mainTop?: ReactNode;
+    mainBottom?: ReactNode;
+    railTop?: ReactNode;
+    railBottom?: ReactNode;
+    after?: ReactNode;
+}
+export interface ProductOverviewProps {
+    /** Details card configuration. */
+    details?: ProductDetailsCardProps;
+    /** Contract overview configuration. */
+    contract?: ProductContractOverviewProps;
+    /** Options to render. */
+    options?: ProductOptionsSummaryProps;
+    /** Variant rows to render. */
+    variants?: ProductVariantsTableProps;
+    /** Readiness card configuration. */
+    readiness?: ProductReadinessCardProps;
+    /** Structure card configuration. */
+    structure?: ProductStructureCardProps;
+    /** Operations card configuration. */
+    operations?: ProductOperationsCardProps;
+    /** Quote preview configuration. */
+    quote?: ProductQuotePreviewCardProps;
+    /** Policies card configuration. */
+    policies?: ProductPoliciesCardProps;
+    /** Replaces individual cards in the overview. */
+    slots?: ProductOverviewSlots;
+    /** Merged onto the outermost node. */
+    className?: string;
+    /** Merged onto the main. */
+    mainClassName?: string;
+    /** Merged onto the rail. */
+    railClassName?: string;
+    /** Overrides this surface’s own copy. */
+    strings?: StringsProp<ProductOverviewStrings>;
+}