themelia-ui 1.0.0

package/.agents/skills/themelia-ui/references/components/features--products.md

@@ -0,0 +1,786 @@
+<!-- GENERATED by scripts/gen-consumer-docs.mjs — do not edit. -->
+
+# `features/products`
+
+Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.
+
+## Selection
+
+- **Use when:** Presenting catalogue records — options, readiness, policies and quotes — in the admin profile.
+- **Avoid when:** The record is an order, invoice or shipment.
+- **Consider instead:** `admin/patterns/commerce`, `features/resource`
+- **Stability:** stable.
+
+## Import
+
+```tsx fragment — import-only example
+import { ProductContractOverview } from "themelia-ui/features/products"
+import "themelia-ui/features/products.css"
+```
+
+## Optional peers
+
+Install these only when importing this family:
+
+```bash
+npm install @tanstack/react-table
+```
+
+## Composition
+
+This family composes `base/action-menu`, `base/badge`, `base/batch-action-bar`, `base/buttons`, `base/choice-inputs`, `base/display`, `base/feedback`, `base/forms`, `base/item`, `base/repeaters`, `base/structure`, `base/table`, `base/text-inputs`, `base/typography`, `base/upload`, `features/overlays`, `features/table`.
+
+Application policy—routing, fetching, persistence, permissions, and translation—stays
+outside the package and arrives through the public props, callbacks, slots, or accessors below.
+
+## Public declarations
+
+### `clampProductPercent`
+
+Kind: callable.
+
+```text
+(value: number) => number
+```
+
+### `defaultProductContractOverviewStrings`
+
+Kind: const.
+
+```text
+ProductContractOverviewStrings
+```
+
+### `defaultProductDetailsCardStrings`
+
+Kind: const.
+
+```text
+ProductDetailsCardStrings
+```
+
+### `defaultProductOperationsCardStrings`
+
+Kind: const.
+
+```text
+ProductOperationsCardStrings
+```
+
+### `defaultProductOptionActionMenuStrings`
+
+Kind: const.
+
+```text
+ProductOptionActionMenuStrings
+```
+
+### `defaultProductOptionsMatrixStrings`
+
+Kind: const.
+
+```text
+ProductOptionsMatrixStrings
+```
+
+### `defaultProductOptionsSummaryStrings`
+
+Kind: const.
+
+```text
+ProductOptionsSummaryStrings
+```
+
+### `defaultProductOverviewStrings`
+
+Kind: const.
+
+```text
+ProductOverviewStrings
+```
+
+### `defaultProductPoliciesCardStrings`
+
+Kind: const.
+
+```text
+ProductPoliciesCardStrings
+```
+
+### `defaultProductQuotePreviewCardStrings`
+
+Kind: const.
+
+```text
+ProductQuotePreviewCardStrings
+```
+
+### `defaultProductReadinessCardStrings`
+
+Kind: const.
+
+```text
+ProductReadinessCardStrings
+```
+
+### `defaultProductStructureCardStrings`
+
+Kind: const.
+
+```text
+ProductStructureCardStrings
+```
+
+### `defaultProductVariantActionMenuStrings`
+
+Kind: const.
+
+```text
+ProductVariantActionMenuStrings
+```
+
+### `defaultProductVariantBulkTableStrings`
+
+Kind: const.
+
+```text
+ProductVariantBulkTableStrings
+```
+
+### `defaultProductVariantDetailsStrings`
+
+Kind: const.
+
+```text
+ProductVariantDetailsStrings
+```
+
+### `defaultProductVariantEditorStrings`
+
+Kind: const.
+
+```text
+ProductVariantEditorStrings
+```
+
+### `defaultProductVariantsManagerStrings`
+
+Kind: const.
+
+```text
+ProductVariantsManagerStrings
+```
+
+### `defaultProductVariantsTableStrings`
+
+Kind: const.
+
+```text
+ProductVariantsTableStrings
+```
+
+### `PRODUCT_EMPTY_VALUE`
+
+Kind: const.
+
+```text
+unknown
+```
+
+### `PRODUCT_TONE_BADGE`
+
+Kind: const.
+
+```text
+Record<ProductTone, BadgeTone>
+```
+
+### `ProductContractOverview`
+
+Kind: callable.
+
+```text
+({ metricColumns, metrics, terms, rules, onOpenContract, onEditContract, onCreateRule, onSelectRule, onEditRule, onDeleteRule, renderRuleActions, actions, footerSlot, empty, className, strings, }: ProductContractOverviewProps) => import("react").JSX.Element
+```
+
+### `ProductContractOverviewStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `termsTitle` | yes | `string` |
+| `rulesTitle` | yes | `string` |
+| `openLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `createRuleLabel` | yes | `string` |
+| `editRuleLabel` | yes | `string` |
+| `deleteRuleLabel` | yes | `string` |
+| `ruleActionsLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductDetailsCard`
+
+Kind: callable.
+
+```text
+({ title, description, metadata, media, onEditDetails, actions, headerEnd: end, footerSlot, empty, className, strings, }: ProductDetailsCardProps) => import("react").JSX.Element
+```
+
+### `ProductDetailsCardStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductEmptyState`
+
+Kind: callable.
+
+```text
+({ title, description, action, className, }: { title: ReactNode; description: ReactNode; action?: ReactNode; className?: string; }) => import("react").JSX.Element
+```
+
+### `ProductOperationRow`
+
+Kind: callable.
+
+```text
+({ item, actionFallback, onSelect, actions, }: { item: ProductOperationsItem; actionFallback: ReactNode; onSelect?: () => void; actions?: ReactNode; }) => import("react").JSX.Element
+```
+
+### `ProductOperationsCard`
+
+Kind: callable.
+
+```text
+({ items, onCreateOperation, onSelectOperation, onEditOperation, onDeleteOperation, renderOperationActions, actions, footerSlot, renderItem, empty, className, strings, }: ProductOperationsCardProps) => import("react").JSX.Element
+```
+
+### `ProductOperationsCardStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductOptionActionMenu`
+
+Kind: callable.
+
+```text
+({ option, index, onSelectOption, onEditOption, onDeleteOption, renderOptionActions, menuLabel, className, strings, }: ProductOptionActionMenuProps) => import("react").JSX.Element
+```
+
+### `ProductOptionActionMenuStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `viewLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+
+### `ProductOptionsMatrix`
+
+Kind: callable.
+
+```text
+({ 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
+```
+
+### `ProductOptionsMatrixStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+| `nameLabel` | yes | `string` |
+| `namePlaceholder` | yes | `string` |
+| `valuesLabel` | yes | `string` |
+| `valuePlaceholder` | yes | `string` |
+| `addValueLabel` | yes | `string` |
+| `removeValueLabel` | yes | `string` |
+| `usedForVariantsLabel` | yes | `string` |
+| `usedForVariantsDescription` | yes | `string` |
+| `saveLabel` | yes | `string` |
+| `cancelLabel` | yes | `string` |
+| `doneLabel` | yes | `string` |
+| `noValues` | yes | `string` |
+| `confirmDeleteTitle` | yes | `string` |
+| `confirmDeleteDescription` | yes | `(name: string) => string` |
+| `confirmDeleteConfirm` | yes | `string` |
+| `confirmDeleteCancel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductOptionsSummary`
+
+Kind: callable.
+
+```text
+({ options, onManageOptions, onCreateOption, onSelectOption, onEditOption, onDeleteOption, renderOptionActions, actions, footerSlot, empty, className, strings, }: ProductOptionsSummaryProps) => import("react").JSX.Element
+```
+
+### `ProductOptionsSummaryStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `manageLabel` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductOverview`
+
+Kind: callable.
+
+```text
+({ metricColumns, title, description, metrics, media, status, statusTone, actions, headerEnd: end, footerSlot, className, strings, }: ProductOverviewProps) => import("react").JSX.Element
+```
+
+### `ProductOverviewStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+
+### `ProductPoliciesCard`
+
+Kind: callable.
+
+```text
+({ policies, onCreatePolicy, onSelectPolicy, onEditPolicy, onDeletePolicy, renderPolicyActions, actions, footerSlot, empty, className, strings, }: ProductPoliciesCardProps) => import("react").JSX.Element
+```
+
+### `ProductPoliciesCardStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductQuotePreviewCard`
+
+Kind: callable.
+
+```text
+({ lines, summary, note, onRecalculate, actions, footerSlot, empty, className, strings, }: ProductQuotePreviewCardProps) => import("react").JSX.Element
+```
+
+### `ProductQuotePreviewCardStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `recalculateLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductReadinessCard`
+
+Kind: callable.
+
+```text
+({ items, score, scoreLabel, summary, onCreateReadinessItem, onSelectReadinessItem, onEditReadinessItem, onDeleteReadinessItem, renderReadinessItemActions, actions, footerSlot, renderItem, empty, className, strings, }: ProductReadinessCardProps) => import("react").JSX.Element
+```
+
+### `ProductReadinessCardStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `scoreLabel` | yes | `string` |
+| `progressLabel` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductReadinessRow`
+
+Kind: callable.
+
+```text
+({ item, actionFallback, onSelect, actions, }: { item: ProductReadinessItem; actionFallback: ReactNode; onSelect?: () => void; actions?: ReactNode; }) => import("react").JSX.Element
+```
+
+### `ProductRowActions`
+
+Kind: callable.
+
+```text
+({ item, actions, menuLabel, className, }: { item: TItem; actions: TableAction<TItem>[]; menuLabel: string; className?: string; }) => import("react").JSX.Element | null
+```
+
+### `ProductStructureCard`
+
+Kind: callable.
+
+```text
+({ metrics, onCreateMetric, onSelectMetric, onEditMetric, onDeleteMetric, renderMetricActions, actions, footerSlot, empty, className, strings, }: ProductStructureCardProps) => import("react").JSX.Element
+```
+
+### `ProductStructureCardStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `actionsLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+### `ProductStructureMetricRow`
+
+Kind: callable.
+
+```text
+({ metric, actions, }: { metric: ProductStructureMetric; actions?: ReactNode; }) => import("react").JSX.Element
+```
+
+### `ProductSummaryRow`
+
+Kind: callable.
+
+```text
+({ item, actionLabel, onSelect, actions, }: { item: ProductOptionSummary | ProductPolicySummary; actionLabel?: ReactNode; onSelect?: () => void; actions?: ReactNode; }) => import("react").JSX.Element
+```
+
+### `ProductThumbnail`
+
+Kind: callable.
+
+```text
+({ src, alt, media, onSelect, label, className, }: { src?: string; alt?: string; media?: ReactNode; onSelect?: () => void; label?: string; className?: string; }) => import("react").JSX.Element
+```
+
+### `ProductToneDot`
+
+Kind: callable.
+
+```text
+({ tone }: { tone?: ProductTone; }) => import("react").JSX.Element
+```
+
+### `ProductVariantActionMenu`
+
+Kind: callable.
+
+```text
+({ variant, index, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, menuLabel, className, strings, }: ProductVariantActionMenuProps) => import("react").JSX.Element | null
+```
+
+### `ProductVariantActionMenuStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `menuLabel` | yes | `string` |
+| `openLabel` | yes | `string` |
+| `editLabel` | yes | `string` |
+| `duplicateLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+
+### `ProductVariantBulkTableStrings`
+
+Kind: interface.
+
+Extends: `ProductVariantsTableStrings`.
+
+| member | required | type |
+| --- | :-: | --- |
+| `generateLabel` | yes | `string` |
+| `selectAllLabel` | yes | `string` |
+| `selectRowLabel` | yes | `(name: string) => string` |
+| `selectedCount` | yes | `(count: number, total: number) => string` |
+| `clearSelection` | yes | `string` |
+| `bulkEditLabel` | yes | `string` |
+| `bulkDeleteLabel` | yes | `string` |
+| `groupLabel` | yes | `(option: string, value: string) => string` |
+| `ungrouped` | yes | `string` |
+| `groupCount` | yes | `(count: number) => string` |
+| `selectGroupLabel` | yes | `(group: string) => string` |
+| `expandGroup` | yes | `string` |
+| `collapseGroup` | yes | `string` |
+| `setImageLabel` | yes | `(name: string) => string` |
+
+### `ProductVariantCell`
+
+Kind: callable.
+
+```text
+({ label, weight, className, children, }: { label: ReactNode; weight?: "normal" | "medium" | "semibold" | "bold"; className?: string; children: ReactNode; }) => import("react").JSX.Element
+```
+
+### `ProductVariantDetails`
+
+Kind: callable.
+
+```text
+({ variant, metadata, optionItems, media, onBack, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, onSelectOption, actions, headerEnd, footerSlot, empty, renderActions, renderMetadata, renderOption, className, strings, }: ProductVariantDetailsProps) => import("react").JSX.Element
+```
+
+### `ProductVariantDetailsStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `backLabel` | yes | `string` |
+| `factsTitle` | yes | `string` |
+| `selectedOptionsTitle` | yes | `string` |
+| `relatedOptionsTitle` | yes | `string` |
+| `viewOptionLabel` | yes | `string` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+| `metadata` | yes | `{ price: string; inventory: string; sku: string; channels: string; updated: string; }` |
+
+### `ProductVariantEditor`
+
+Kind: callable.
+
+```text
+({ value: valueProp, defaultValue, optionFields, statusOptions, onValueChange, onSubmit, onError, onCancel, onDelete, actions, headerEnd, footerSlot, disabled, submitting, className, strings, }: ProductVariantEditorProps) => import("react").JSX.Element
+```
+
+### `ProductVariantEditorStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `identityTitle` | yes | `string` |
+| `commercialTitle` | yes | `string` |
+| `optionsTitle` | yes | `string` |
+| `saveLabel` | yes | `string` |
+| `savingLabel` | yes | `string` |
+| `cancelLabel` | yes | `string` |
+| `deleteLabel` | yes | `string` |
+| `statusPlaceholder` | yes | `string` |
+| `optionPlaceholder` | yes | `string` |
+| `fields` | yes | `{ name: string; description: string; sku: string; price: string; inventory: string; status: string; channels: string; }` |
+| `placeholders` | yes | `{ name: string; description: string; sku: string; price: string; inventory: string; status: string; channels: string; }` |
+
+### `ProductVariantsBulkTable`
+
+Kind: callable.
+
+```text
+({ 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
+```
+
+### `ProductVariantsManager`
+
+Kind: callable.
+
+```text
+({ className, strings, optionsStrings, variantsStrings, optionGroups, editingOptionId, defaultEditingOptionId, onEditingOptionIdChange, onCreateOption, onEditOption, onDeleteOption, onAddValue, onDeleteValue, onOptionNameChange, onValueLabelChange, onSaveEditingOption, onCancelEditingOption, onToggleUsedForVariants, onReorderOptions, confirmDelete, groupByOptionId: groupByProp, defaultGroupByOptionId, onGroupByOptionIdChange, showGroupBy, ...variantProps }: ProductVariantsManagerProps) => import("react").JSX.Element
+```
+
+### `ProductVariantsManagerStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `groupByLabel` | yes | `string` |
+| `groupByNone` | yes | `string` |
+
+### `ProductVariantsTable`
+
+Kind: callable.
+
+```text
+({ variants, onCreateVariant, onSelectVariant, onEditVariant, onDuplicateVariant, onDeleteVariant, renderVariantActions, actions, footerSlot, empty, className, strings, }: ProductVariantsTableProps) => import("react").JSX.Element
+```
+
+### `ProductVariantsTableStrings`
+
+Kind: interface.
+
+| member | required | type |
+| --- | :-: | --- |
+| `title` | yes | `string` |
+| `description` | yes | `string` |
+| `createLabel` | yes | `string` |
+| `columns` | yes | `{ variant: string; sku: string; price: string; inventory: string; channels: string; status: string; updated: string; actions: string; }` |
+| `emptyTitle` | yes | `string` |
+| `emptyDescription` | yes | `string` |
+
+## Preview recipes
+
+Preview route: Options & variants — `/product-variants`
+
+### Options and variants together
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductVariantsManager
+  optionGroups={options}
+  variants={variants}
+  groupByOptionId="size"
+  cellDisplay="field"
+  onCreateOption={createOption}
+  onSaveEditingOption={(option, draft) => save(option.id, draft)}
+  onAddValue={addValue}
+  onGenerateVariants={generate}
+  onVariantFieldBlur={(variant, field, value) => patch(variant.id, field, value)}
+/>
+```
+
+### The two option surfaces
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductOptionsSummary options={summary} onManageOptions={openMatrix} />
+
+<ProductOptionsMatrix
+  optionGroups={groups}
+  onSaveEditingOption={(option, draft) => save(option.id, draft)}
+  onAddValue={addValue}
+  onDeleteOption={remove}
+  confirmDelete            // on by default — removing an option removes its variants
+/>
+```
+
+### Variants
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductVariantsBulkTable
+  variants={variants}
+  optionGroups={groups}
+  groupByOptionId="size"
+  cellDisplay={{ sku: "field", price: "field", inventory: "text" }}
+  onVariantFieldBlur={(variant, field, value) => api.patch(variant.id, { [field]: value })}
+  onBulkDelete={(rows) => api.removeMany(rows.map((row) => row.id))}
+/>
+```
+
+### One variant, read and edited
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductVariantDetails
+  variant={selected}
+  optionItems={options}
+  onBack={() => setSelected(null)}
+  onEditVariant={(variant) => setEditing(variant)}
+/>
+
+<ProductVariantEditor
+  defaultValue={{ name: "M · Trail", sku: "TRL-29-M-TR", price: "€1,850" }}
+  optionFields={[{ id: "size", label: "Frame size", choices: sizes }]}
+  statusOptions={statuses}
+  onSubmit={(values) => api.save(values)}
+  onDelete={(values) => api.remove(values)}
+/>
+```
+
+### Nothing yet
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductVariantsBulkTable
+  variants={[]}
+  onGenerateVariants={() => api.generate(productId)}
+/>
+```
+
+### Overview and quote
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductOverview
+  title="Trailhead 29er"
+  status="Live"
+  statusTone="success"
+  metrics={[{ id: "variants", label: "Variants", value: "18" }]}
+/>
+
+<ProductQuotePreviewCard
+  lines={[…, { id: "total", label: "Total", value: "€2,268", emphasis: true }]}
+  onRecalculate={() => api.quote(id)}
+/>
+```
+
+### Readiness, structure, operations
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductReadinessCard
+  score={72}
+  items={[{ id: "price", label: "Pricing", tone: "warning", value: "1 missing" }]}
+  onSelectReadinessItem={(item) => open(item.id)}
+/>
+```
+
+### Details, contract, policies
+
+```tsx fragment — excerpt from the live preview; surrounding values are supplied by the application
+<ProductContractOverview
+  metrics={metrics}
+  terms={terms}          // MetadataListItem[]
+  rules={rules}
+  onCreateRule={() => …}
+/>
+```