themelia-react-ui 2.0.4 → 2.0.6

package/docs/consumer-skill/examples/commerce-lines.tsx

@@ -0,0 +1,271 @@
+import { CreditCard, FileText, Send } from 'lucide-react';
+import { Badge } from 'themelia-react-ui/base/badge';
+import { Card } from 'themelia-react-ui/base/cards';
+import { Alert, AlertDescription, AlertTitle } from 'themelia-react-ui/base/feedback';
+import { Stack } from 'themelia-react-ui/base/structure';
+import {
+	AddressCard,
+	AmountRow,
+	FulfillmentGroup,
+	InvoiceHeader,
+	InvoiceLineItems,
+	OrderCustomer,
+	OrderLineItem,
+	OrderSummary,
+	OrderTimeline,
+	OrderTransactions,
+	PaymentTimeline,
+	ShipmentTracking,
+	SummaryPanel,
+	type InvoiceColumn,
+	type InvoiceLineItem,
+} from 'themelia-react-ui/blocks/commerce';
+import { Page } from 'themelia-react-ui/layout/page';
+import { Money, Number as NumberValue } from 'themelia-react-ui/primitives';
+import { Text } from 'themelia-react-ui/typography';
+
+/** Mock accepted order values; the app owns tax, shipping and price calculations. */
+export function SoldProductWithSummary() {
+	return (
+		<Card title="Items and totals">
+			<Stack gap="xl">
+				<OrderLineItem
+					id="mug-sand-350"
+					title="Ceramic mug"
+					variantTitle="350 ml / Sand"
+					sku="MUG-350-SAND"
+					unitPrice="€18.00"
+					quantity={2}
+					total="€36.00"
+				/>
+				<SummaryPanel>
+					<AmountRow label="Subtotal" amount="€36.00" />
+					<AmountRow label="Shipping" amount="€6.50" />
+					<AmountRow label="Tax" note="20%" amount="€8.50" />
+					<AmountRow label="Grand total" amount="€51.00" total rollup />
+				</SummaryPanel>
+			</Stack>
+		</Card>
+	);
+}
+
+/** Custom JSX values keep their roles: quiet regular breakdown, bold financial total. */
+export function CustomServiceInvoice() {
+	// Custom columns replace the default four-column/mobile recipe with this two-column grid.
+	const serviceColumns: InvoiceColumn<InvoiceLineItem>[] = [
+		{
+			id: 'service',
+			header: 'Service',
+			width: 'minmax(0, 1fr)',
+			cell: (item) => (
+				<Stack gap="xs">
+					<Text type="inherit" className="wrap-anywhere">{item.description}</Text>
+					<Text tag="span" size="xs" type="secondary">
+						<NumberValue value={item.qty} /> × <Money amount={item.price} currency="EUR" />
+					</Text>
+				</Stack>
+			),
+		},
+		{
+			id: 'line-total',
+			header: 'Line total',
+			width: 'max-content',
+			align: 'right',
+			cell: (item) => <Money type="inherit" amount={item.total} currency="EUR" weight="regular" />,
+		},
+	];
+
+	return (
+		<InvoiceLineItems
+			items={[
+				{ description: 'Design services', qty: 1, price: 335, total: 335 },
+				{ description: 'Research workshop', qty: 2, price: 380, total: 760 },
+				{ description: 'Implementation support', qty: 3, price: 425, total: 1275 },
+			]}
+			columns={serviceColumns}
+			footerRows={[
+				{ label: 'Subtotal', value: <Money type="inherit" amount={2370} currency="EUR" weight="regular" /> },
+				{ label: 'VAT (20%)', value: <Money type="inherit" amount={474} currency="EUR" weight="regular" /> },
+				// emphasis controls the label/spacing; this React-node value owns its weight.
+				{ label: 'Invoice total', value: <Money type="inherit" amount={2844} currency="EUR" weight="bold" />, emphasis: 'total' },
+			]}
+		/>
+	);
+}
+
+export interface OrderFulfillmentDetailProps {
+	/** Requests fulfillment of the open group; the app accepts and reloads the order. */
+	onFulfill: () => void;
+	onPrintPackingSlip: () => void;
+	/** Opens the app's refund workflow, for example in an ActionDrawer. */
+	onRefund: () => void;
+}
+
+/**
+ * One order route: Page owns the heading and commands, each subject is framed
+ * once, and the buyer and payment ledger sit in the aside. Mock accepted values.
+ */
+export function OrderFulfillmentDetail({ onFulfill, onPrintPackingSlip, onRefund }: OrderFulfillmentDetailProps) {
+	return (
+		<Page
+			header={{
+				title: 'Order #1042',
+				slots: { titleSuffix: <><Badge tone="warning">Partially fulfilled</Badge><Badge tone="success">Paid</Badge></> },
+				primaryAction: { label: 'Fulfill items', onClick: onFulfill },
+				secondaryActions: [{ label: 'Print packing slip', onClick: onPrintPackingSlip }, { label: 'Refund', onClick: onRefund }],
+			}}
+			aside={(
+				<>
+					<OrderCustomer
+						surface="card"
+						name="Ava Chen"
+						email="ava.chen@example.com"
+						orderCount={4}
+						shippingAddress={{ name: 'Ava Chen', line1: '18 Ermou Street', city: 'Athens', postalCode: '105 63', country: 'Greece' }}
+						billingSameAsShipping
+					/>
+					<OrderSummary
+						surface="card"
+						goods={[{ label: 'Subtotal', amount: '€104.00' }, { label: 'Shipping', amount: '€6.50' }]}
+						total={{ label: 'Total', amount: '€110.50' }}
+						payments={[{ label: 'Paid by card', amount: '€110.50' }]}
+						paymentStatus="paid"
+					/>
+					<OrderTransactions
+						surface="card"
+						transactions={[
+							{ id: 'auth', kind: 'authorization', status: 'success', amount: '€110.50', processedAt: '12 Oct, 09:14', method: 'Visa •••• 4242' },
+							{ id: 'capture', kind: 'capture', status: 'success', amount: '€110.50', processedAt: '12 Oct, 09:15', reference: 'ch_3PqL2x' },
+						]}
+					/>
+				</>
+			)}
+		>
+			<Alert tone="warning">
+				<AlertTitle>Confirm the delivery address</AlertTitle>
+				<AlertDescription>The courier flagged the postal code; confirm it with the customer before the Athens parcel ships.</AlertDescription>
+			</Alert>
+			<FulfillmentGroup
+				status="unfulfilled"
+				location="Athens warehouse"
+				items={[{ id: 'shirt', title: 'Linen overshirt', variantTitle: 'Navy / M', sku: 'LIN-OVR-NVY-M', unitPrice: '€68.00', quantity: 1, total: '€68.00' }]}
+				actions={[{ id: 'fulfill', label: 'Fulfill items', onClick: onFulfill }, { id: 'slip', label: 'Print packing slip', onClick: onPrintPackingSlip }]}
+			/>
+			<FulfillmentGroup
+				status="fulfilled"
+				location="Thessaloniki store"
+				items={[{ id: 'mug', title: 'Stoneware mug', variantTitle: 'Salt', sku: 'MUG-STW-SALT', unitPrice: '€18.00', quantity: 2, total: '€36.00' }]}
+			/>
+			<ShipmentTracking
+				surface="card"
+				carrier="ACS Courier"
+				trackingNumber="7781 2290 114"
+				status="in_transit"
+				steps={[
+					{ label: 'Label created', done: true, timestamp: '12 Oct, 11:02' },
+					{ label: 'Picked up', done: true, timestamp: '12 Oct, 16:40' },
+					{ label: 'Out for delivery', done: false },
+					{ label: 'Delivered', done: false },
+				]}
+			/>
+			{/* OrderTimeline owns its title; the Card only frames it. */}
+			<Card>
+				<OrderTimeline
+					title="History"
+					events={[
+						{ id: 'placed', title: 'Order placed', timestamp: '12 Oct, 09:14', status: 'completed' },
+						{ id: 'shipped', title: 'Mugs shipped from Thessaloniki', timestamp: '12 Oct, 16:40', status: 'completed' },
+						{ id: 'athens', title: 'Overshirt awaiting fulfillment', timestamp: 'Now', status: 'current' },
+					]}
+				/>
+			</Card>
+		</Page>
+	);
+}
+
+export interface ReceivableInvoiceDetailProps {
+	onRecordPayment: () => void;
+	onSendReminder: () => void;
+	onApplyCredit: () => void;
+	onExportPdf: () => void;
+}
+
+/**
+ * One invoice route: the document Card is the only frame around its header,
+ * flat line items and ledger; settlement and history are separate subjects.
+ * Long secondary labels stay in the More actions menu beside the primary command.
+ */
+export function ReceivableInvoiceDetail({ onRecordPayment, onSendReminder, onApplyCredit, onExportPdf }: ReceivableInvoiceDetailProps) {
+	return (
+		<Page
+			header={{
+				title: 'INV-2026-118',
+				slots: { titleSuffix: <Badge tone="destructive">Overdue</Badge> },
+				primaryAction: { label: 'Record payment', onClick: onRecordPayment },
+				secondaryActions: [
+					{ label: 'Send reminder', onClick: onSendReminder },
+					{ label: 'Apply approved credit', onClick: onApplyCredit },
+					{ label: 'Export PDF', onClick: onExportPdf },
+				],
+				maxVisibleSecondaryActions: 1,
+			}}
+			aside={(
+				<>
+					<Card title="Settlement">
+						<SummaryPanel>
+							<AmountRow label="Invoice total" amount="€2,199.76" />
+							<AmountRow label="Bank transfer, 14 Oct" amount="€1,000.00" deduction />
+							<AmountRow label="Balance due" amount="€1,199.76" total rollup />
+						</SummaryPanel>
+					</Card>
+					<AddressCard
+						surface="card"
+						kind="billing"
+						name="Kalliope Studio IKE"
+						line1="42 Tsimiski Street"
+						city="Thessaloniki"
+						postalCode="546 23"
+						country="Greece"
+					/>
+				</>
+			)}
+		>
+			<Card>
+				<Stack gap="2xl">
+					<InvoiceHeader
+						invoiceNumber="INV-2026-118"
+						status="overdue"
+						from={{ name: 'Ledgerline Accounting', location: 'Athens' }}
+						to={{ name: 'Kalliope Studio IKE', location: 'Thessaloniki' }}
+						issuedDate="12 Oct 2026"
+						dueDate="26 Oct 2026"
+						amount="€1,199.76"
+					/>
+					<InvoiceLineItems
+						surface="flat"
+						currency="EUR"
+						items={[
+							{ description: 'Quarterly bookkeeping retainer, July to September 2026', qty: 1, price: 1275, total: 1275 },
+							{ description: 'Payroll processing (per employee)', qty: 14, price: 18.5, total: 259 },
+							{ description: 'VAT return preparation', qty: 1, price: 240, total: 240 },
+						]}
+						footerRows={[
+							{ label: 'Subtotal', value: <Money type="inherit" amount={1774} currency="EUR" weight="regular" /> },
+							{ label: 'VAT (24%)', value: <Money type="inherit" amount={425.76} currency="EUR" weight="regular" /> },
+							{ label: 'Invoice total', value: <Money type="inherit" amount={2199.76} currency="EUR" weight="bold" />, emphasis: 'total' },
+						]}
+					/>
+				</Stack>
+			</Card>
+			<Card title="Payment history">
+				<PaymentTimeline
+					events={[
+						{ label: 'Invoice issued', date: '12 Oct', icon: FileText, done: true },
+						{ label: 'Partial payment received', date: '14 Oct', amount: '€1,000.00', icon: CreditCard, done: true },
+						{ label: 'Reminder due', date: '28 Oct', icon: Send, done: false },
+					]}
+				/>
+			</Card>
+		</Page>
+	);
+}

package/docs/consumer-skill/examples/custom-composition.tsx

@@ -0,0 +1,21 @@
+import type { ReactNode } from 'react';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { InlineStat } from 'themelia-react-ui/blocks/data-display';
+import { Money } from 'themelia-react-ui/primitives';
+
+/** Card-free app content: its parent owns the subject title and any surface. */
+export function AssessmentComparison({declared, assessed, currency, labels, actions}: {
+  declared: number;
+  assessed: number;
+  currency: string;
+  labels: {declared: string; assessed: string};
+  actions?: ReactNode;
+}) {
+  return <Stack gap="xl" className="@container min-w-0">
+    <div className="grid min-w-0 grid-cols-1 gap-space-xl @lg:grid-cols-2">
+      <InlineStat layout="stacked" label={labels.declared} value={<Money amount={declared} currency={currency} />} />
+      <InlineStat layout="stacked" label={labels.assessed} value={<Money amount={assessed} currency={currency} />} />
+    </div>
+    {actions && <Stack direction="horizontal" justify="end" gap="md">{actions}</Stack>}
+  </Stack>;
+}

package/docs/consumer-skill/examples/detail.tsx

@@ -1,4 +1,5 @@
 import { useState, type ReactNode } from 'react';
+import { Badge } from 'themelia-react-ui/base/badge';
 import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
 import { MetadataList } from 'themelia-react-ui/base/metadata-list';
@@ -21,7 +22,7 @@ export interface AccountDetailProps {
 
 /** One framed subject for a drawer or dashboard: one quick control, no page chrome. */
 export function AccountDetail({ account, onEdit }: AccountDetailProps) {
-  return <Card title={account.name} headerPlacement="frame"
+  return <Card title={account.name}
     headerAction={<Button onClick={() => onEdit(account.id)}>Edit</Button>}>
     <AccountFacts account={account}/>
   </Card>;
@@ -52,9 +53,9 @@ export function AccountDetailPage({ account, onEdit, onBack, section, onSectionC
     { label: 'Send statement', onClick: () => onSendStatement(account.id) },
     { label: 'Delete account', destructive: true, onClick: () => { setError(undefined); deletion.show(); } },
   ];
-  return <Page header={{
+  return <Page narrow header={{
     title: account.name, onBack, backLabel: 'Back to accounts',
-    titleBadges: account.overdue ? [{ label: 'Overdue', tone: 'warning' }] : undefined,
+    slots: { titleSuffix: account.overdue ? <Badge tone="warning">Overdue</Badge> : null },
     primaryAction: { label: 'Edit account', onClick: () => onEdit(account.id) },
     secondaryActions: commands,
     tabs: {
@@ -68,7 +69,7 @@ export function AccountDetailPage({ account, onEdit, onBack, section, onSectionC
     },
   }}>
     {section === 'overview'
-      ? <Card title="Contact and billing" headerPlacement="frame"><AccountFacts account={account}/></Card>
+      ? <Card title="Contact and billing"><AccountFacts account={account}/></Card>
       : children}
     <ConfirmDialog {...deletion.overlayProps} destructive
       title={`Delete ${account.name}?`} description="This permanently removes the account."

package/docs/consumer-skill/examples/edit.tsx

@@ -2,7 +2,7 @@ import { useRef, useState } from 'react';
 import { useForm } from 'react-hook-form';
 import { Button } from 'themelia-react-ui/base/buttons';
 import { Card } from 'themelia-react-ui/base/cards';
-import { ControlledFormField, DirtyStateBanner, ErrorSummary, FormActionsBar, SubmitStateButton } from 'themelia-react-ui/base/forms';
+import { ControlledFormField, DirtyStateBanner, ErrorSummary, SubmitStateButton } from 'themelia-react-ui/base/forms';
 import { Stack } from 'themelia-react-ui/base/structure';
 import { Input } from 'themelia-react-ui/base/text-inputs';
 import { Text } from 'themelia-react-ui/typography';
@@ -43,10 +43,10 @@ export function AccountEdit({ initial, onSave, onCancel }: AccountEditProps) {
             onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
         </ControlledFormField>
         {saved && !isDirty && <Text role="status">Account saved.</Text>}
-        <FormActionsBar>
+        <Stack direction="horizontal" wrap justify="end" gap="md">
           <Button type="button" disabled={isSubmitting} onClick={onCancel}>Cancel edit</Button>
           <SubmitStateButton dirty={isDirty} disableWhenPristine submitting={isSubmitting}>Save account</SubmitStateButton>
-        </FormActionsBar>
+        </Stack>
       </Stack>
     </form>
   </Card>;

package/docs/consumer-skill/examples/editable-sections.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from 'themelia-react-ui/base/accordion';
+import { Badge } from 'themelia-react-ui/base/badge';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { Heading, Text } from 'themelia-react-ui/typography';
+
+export interface EditableSection {
+  id: string;
+  title: string;
+  content: ReactNode;
+  /** App-localized validation status, e.g. "2 errors"; omit when valid. */
+  validationMessage?: string;
+}
+
+/** Place inside the app's one form. Closing a panel retains the same field DOM. */
+export function EditableSections({title, sections, openSections, onOpenSectionsChange}: {
+  title: string;
+  sections: EditableSection[];
+  openSections: string[];
+  onOpenSectionsChange: (values: string[]) => void;
+}) {
+  return <Stack gap="xl">
+    <Heading tag="h2" size="base">{title}</Heading>
+    <Accordion multiple value={openSections} onValueChange={onOpenSectionsChange} aria-label={title}>
+      {sections.map(section => <AccordionItem key={section.id} value={section.id}>
+        <AccordionTrigger>
+          <Stack render={<span />} direction="horizontal" gap="md" className="min-w-0">
+            <Text tag="span" size="inherit" type="inherit" weight="medium">{section.title}</Text>
+            {section.validationMessage && <>{' '}<Badge tone="destructive">{section.validationMessage}</Badge></>}
+          </Stack>
+        </AccordionTrigger>
+        <AccordionContent keepMounted>
+          <Stack gap="xl">{section.content}</Stack>
+        </AccordionContent>
+      </AccordionItem>)}
+    </Accordion>
+  </Stack>;
+}

package/docs/consumer-skill/examples/index-table.tsx

@@ -1,5 +1,5 @@
 import { Button } from 'themelia-react-ui/base/buttons';
-import { Card } from 'themelia-react-ui/base/cards';
+import { Page } from 'themelia-react-ui/layout/page';
 import { Stack } from 'themelia-react-ui/base/structure';
 import { DataTable, type DataTableProps } from 'themelia-react-ui/features/table';
 import { Email, Name } from 'themelia-react-ui/primitives';
@@ -23,14 +23,14 @@ export function AccountIndex({ state, onRetry, hrefFor, onNavigate }: AccountInd
     { accessorKey: 'name', header: 'Name', cell: ({ row }) => <Name value={row.original.name} /> },
     { accessorKey: 'email', header: 'Email', cell: ({ row }) => <Email value={row.original.email} /> },
   ];
-  return <Card title="Accounts" surface="card">
+  return <Page header={{ title: 'Accounts' }}>
     {state.status === 'loading' ? <Text role="status">Loading accounts…</Text> :
       state.status === 'error' ? <Stack gap="md">
         <Text role="alert" type="error">{state.message}</Text>
         <Button onClick={onRetry}>Retry loading</Button>
-      </Stack> : <DataTable columns={columns} data={state.records} surface="flat"
+      </Stack> : <DataTable columns={columns} data={state.records}
         getRowId={account => account.id} enablePagination={false} showFullscreenToggle={false}
         emptyStateMessage="No accounts yet." emptyStateAction={<Button onClick={onRetry}>Refresh accounts</Button>}
         rowActions={[{ id: 'open', label: 'Open account', onClick: account => onNavigate(hrefFor(account)) }]} />}
-  </Card>;
+  </Page>;
 }

package/docs/consumer-skill/examples/manifest.json

@@ -1,6 +1,42 @@
 {
   "schemaVersion": 1,
   "examples": [
+    {
+      "file": "product-parts.tsx",
+      "exports": ["ProductOptionDefinitions", "ProductVariantManagement", "VariantComparison", "VariantInspectionAndEditor"],
+      "phase": "optional",
+      "optionalPeers": ["@tanstack/react-table", "react-hook-form"]
+    },
+    {
+      "file": "product-media.tsx",
+      "exports": ["LocalProductImages", "AttachedProductImages", "MediaOnlyProductOverview"],
+      "phase": "optional",
+      "optionalPeers": ["@dnd-kit/core", "@dnd-kit/sortable", "@dnd-kit/utilities", "@tanstack/react-table", "react-hook-form"]
+    },
+    {
+      "file": "token-domain-structure.tsx",
+      "exports": ["AllocationByLocation", "AllocationSubjectExample"],
+      "phase": "basic",
+      "optionalPeers": []
+    },
+    {
+      "file": "commerce-lines.tsx",
+      "exports": ["SoldProductWithSummary", "CustomServiceInvoice", "OrderFulfillmentDetail", "ReceivableInvoiceDetail"],
+      "phase": "optional",
+      "optionalPeers": ["react-day-picker", "react-hook-form", "sonner"]
+    },
+    {
+      "file": "editable-sections.tsx",
+      "exports": ["EditableSections"],
+      "phase": "basic",
+      "optionalPeers": []
+    },
+    {
+      "file": "custom-composition.tsx",
+      "exports": ["AssessmentComparison"],
+      "phase": "basic",
+      "optionalPeers": []
+    },
     {
       "file": "website.tsx",
       "exports": [
@@ -162,7 +198,8 @@
     {
       "file": "rhf-overlay-form.tsx",
       "exports": [
-        "RHFOverlayForm"
+        "RHFOverlayForm",
+        "RHFDialogForm"
       ],
       "phase": "optional",
       "optionalPeers": [

package/docs/consumer-skill/examples/product-media.tsx

@@ -0,0 +1,41 @@
+import { FormField } from 'themelia-react-ui/base/forms';
+import { MediaGallery } from 'themelia-react-ui/base/media-gallery';
+import { MediaResourceGallery, type MediaLibraryAccessors } from 'themelia-react-ui/features/media-library';
+import { ProductOverview } from 'themelia-react-ui/features/products';
+
+/** New local files remain File[]; the caller owns transfer and persistence. */
+export function LocalProductImages({ files, onFilesChange }: { files: File[]; onFilesChange: (files: File[]) => void }) {
+  return <FormField label="New product images" hint="The first image is the cover. Drag or use the keyboard to change order.">
+    <MediaGallery value={files} onValueChange={onFilesChange} accept="image/*" maxFiles={6} />
+  </FormField>;
+}
+
+export interface ProductAsset { key: string; filename: string; url: string; altText: string; }
+const accessors: MediaLibraryAccessors<ProductAsset> = {
+  getId: item => item.key, getName: item => item.filename, getType: () => 'image',
+  getSrc: item => item.url, getAlt: item => item.altText,
+};
+
+/** Existing records stay records; callbacks propose resource attachment changes. */
+export function AttachedProductImages({ assets, primaryId, onAssetsChange, onPrimaryChange, onAdd }: {
+  assets: ProductAsset[];
+  primaryId?: string;
+  onAssetsChange: (assets: ProductAsset[]) => void;
+  onPrimaryChange: (id: string | undefined) => void;
+  onAdd?: () => void;
+}) {
+  return <MediaResourceGallery items={assets} accessors={accessors} title="Product media" layout="grid"
+    primaryId={primaryId} onPrimaryChange={id => onPrimaryChange(id)} onAdd={onAdd}
+    onReorder={(_ids, next) => onAssetsChange(next)} onRemove={id => {
+      const next = assets.filter(asset => asset.key !== id);
+      onAssetsChange(next);
+      if (id === (primaryId ?? assets[0]?.key)) onPrimaryChange(next[0]?.key);
+    }} />;
+}
+
+/** ProductOverview owns the subject; media enters through details.media, not a top-level media prop. */
+export function MediaOnlyProductOverview({ assets }: { assets: ProductAsset[] }) {
+  return <ProductOverview details={{ title: 'Product media', description: false,
+    media: <MediaResourceGallery items={assets} accessors={accessors} readOnly layout="field" />,
+  }} />;
+}

package/docs/consumer-skill/examples/product-parts.tsx

@@ -0,0 +1,81 @@
+import { useState, type ReactNode } from 'react';
+import { Alert, AlertDescription } from 'themelia-react-ui/base/feedback';
+import { Stack } from 'themelia-react-ui/base/structure';
+import {
+  ProductOptionsMatrix, ProductVariantDetails, ProductVariantEditor,
+  ProductVariantsBulkTable, ProductVariantsManager,
+  type ProductOptionEditDraft, type ProductOptionGroup,
+  type ProductVariantEditorValues, type ProductVariantRow,
+} from 'themelia-react-ui/features/products';
+import { Money } from 'themelia-react-ui/primitives';
+
+const colors: ProductOptionGroup[] = [{
+  id: 'color', name: 'Color', values: [{ id: 'olive', label: 'Olive' }, { id: 'natural', label: 'Natural' }],
+}];
+const rows: ProductVariantRow[] = [
+  { id: 'weekender-olive', name: 'Olive', sku: 'WEEK-OLIVE', price: '€68.00', inventory: '7 available', status: 'Active', optionValueIds: { color: 'olive' } },
+  { id: 'weekender-natural', name: 'Natural', sku: 'WEEK-NATURAL', price: '€68.00', inventory: '12 available', status: 'Active', optionValueIds: { color: 'natural' } },
+];
+
+/** Local definition-editing example. Variant reconciliation is a separate app rule. */
+export function ProductOptionDefinitions() {
+  const [groups, setGroups] = useState(colors);
+  const [editingId, setEditingId] = useState<string | null>(null);
+  return <ProductOptionsMatrix optionGroups={groups} editingOptionId={editingId}
+    onEditingOptionIdChange={setEditingId} showVariantToggle={false}
+    onSaveEditingOption={(option, draft) => {
+      setGroups(current => current.map(group => group.id === option.id ? { ...group, name: draft.name, values: draft.values } : group));
+    }} />;
+}
+
+/** Callbacks apply app-owned accepted definitions/rows; the manager does not generate business data. */
+export function ProductVariantManagement({ optionGroups, variants, onSaveOption, onInspectVariant }: {
+  optionGroups: ProductOptionGroup[];
+  variants: ProductVariantRow[];
+  onSaveOption: (option: ProductOptionGroup, draft: ProductOptionEditDraft) => void | Promise<void>;
+  onInspectVariant: (variant: ProductVariantRow) => void;
+}) {
+  const [editingId, setEditingId] = useState<string | null>(null);
+  return <ProductVariantsManager optionGroups={optionGroups} variants={variants}
+    editingOptionId={editingId} onEditingOptionIdChange={setEditingId}
+    onSaveEditingOption={onSaveOption}
+    onSelectVariant={onInspectVariant} groupByOptionId={null}
+    visibleColumns={['variant', 'sku', 'price', 'inventory', 'status']} selectionMode="none" cellDisplay="text" />;
+}
+
+/** A comparison can use the table independently from option-definition editing. */
+export function VariantComparison({ onInspectVariant }: { onInspectVariant: (variant: ProductVariantRow) => void }) {
+  return <ProductVariantsBulkTable variants={rows} optionGroups={colors} groupByOptionId={null}
+    visibleColumns={['variant', 'sku', 'price', 'inventory', 'status']} selectionMode="none"
+    cellDisplay="text" onSelectVariant={onInspectVariant} />;
+}
+
+/** The caller validates/persists and returns accepted fields; a failed save keeps the editor draft. */
+export function VariantInspectionAndEditor({ id, initialValue, media, detailFooter, onSave }: {
+  id: string;
+  initialValue: ProductVariantEditorValues;
+  media?: ReactNode;
+  detailFooter?: ReactNode;
+  onSave: (draft: ProductVariantEditorValues) => Promise<ProductVariantEditorValues>;
+}) {
+  const [accepted, setAccepted] = useState(initialValue);
+  const [draft, setDraft] = useState(initialValue);
+  const [editing, setEditing] = useState(false);
+  const [error, setError] = useState('');
+  return <Stack gap="2xl">
+    <ProductVariantDetails variant={{ id, name: accepted.name || 'Variant', sku: accepted.sku,
+      price: accepted.price ? <Money amount={Number(accepted.price)} currency="EUR" /> : undefined,
+      inventory: accepted.inventory, status: accepted.status,
+      options: Object.values(accepted.options ?? {}).filter((value): value is string => value !== undefined),
+    }} media={media} footerSlot={detailFooter} onEditVariant={() => {
+      setDraft(accepted); setError(''); setEditing(true);
+    }} />
+    {editing && <Stack gap="xl">
+      {error && <Alert tone="destructive"><AlertDescription>{error}</AlertDescription></Alert>}
+      <ProductVariantEditor value={draft} onValueChange={setDraft}
+        onSubmit={async value => { const saved = await onSave(value); setAccepted(saved); setEditing(false); }}
+        onError={() => setError('Variant could not be saved. Your draft is kept; retry Save variant.')}
+        onCancel={() => setEditing(false)} />
+    </Stack>}
+  </Stack>;
+}

package/docs/consumer-skill/examples/rhf-edit-page.tsx

@@ -82,7 +82,7 @@ export function RHFEditPage({ initial, onSave, onCancel }: RHFEditPageProps) {
       form.setError('root.server', { type: 'transport', message: 'Saving failed. Your draft is kept; retry Save order.' });
     } finally { lock.current = false; }
   });
-  return <Page
+  return <Page maxWidth="xl"
     render={<form id={`${id}-form`} onSubmit={submit} noValidate aria-busy={isSubmitting} />}
     header={{ title: 'Edit order', description: 'Update customer, fulfillment and line items.' }}>
         {isDirty && <DirtyStateBanner title="Unsaved changes" description="Save to commit this draft, or discard to restore the last saved version." />}