themelia-react-ui 2.0.4 → 2.0.5

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." />}

package/docs/consumer-skill/examples/rhf-overlay-form.tsx

@@ -5,7 +5,7 @@ import { ControlledFormField, ErrorSummary } from 'themelia-react-ui/base/forms'
 import { Input } from 'themelia-react-ui/base/text-inputs';
 import { Select, ToggleField } from 'themelia-react-ui/base/choice-inputs';
 import { Stack } from 'themelia-react-ui/base/structure';
-import { ActionDrawer, useOverlayVisibility } from 'themelia-react-ui/features/overlays';
+import { ActionDialog, ActionDrawer, useOverlayVisibility } from 'themelia-react-ui/features/overlays';
 
 export interface CustomerDraft { name: string; email: string; segment: string; notify: boolean; }
 export interface CustomerDraftRecord extends CustomerDraft { id: string; }
@@ -21,7 +21,18 @@ export interface RHFOverlayFormProps {
 const empty: CustomerDraft = { name: '', email: '', segment: 'standard', notify: true };
 
 /** Mount with a record key if the selected customer changes while editing. */
-export function RHFOverlayForm({ record, onSave, onSaved }: RHFOverlayFormProps) {
+export function RHFOverlayForm(props: RHFOverlayFormProps) {
+  const { trigger, ...surfaceProps } = useCustomerOverlayForm(props);
+  return <>{trigger}<ActionDrawer {...surfaceProps} /></>;
+}
+
+/** The same form/transport contract in a dialog, with its generated actions. */
+export function RHFDialogForm(props: RHFOverlayFormProps) {
+  const { trigger, ...surfaceProps } = useCustomerOverlayForm(props);
+  return <>{trigger}<ActionDialog {...surfaceProps} /></>;
+}
+
+function useCustomerOverlayForm({ record, onSave, onSaved }: RHFOverlayFormProps) {
   const id = useId();
   const overlay = useOverlayVisibility();
   const lock = useRef(false);
@@ -65,12 +76,15 @@ export function RHFOverlayForm({ record, onSave, onSaved }: RHFOverlayFormProps)
       form.setError('root.server', { type: 'transport', message: 'Customer could not be saved. Your draft is kept; retry Save customer.' });
     } finally { lock.current = false; }
   });
-  return <>
-    <Button onClick={open}>{record ? 'Edit customer' : 'Create customer'}</Button>
-    <ActionDrawer {...overlay.overlayProps} title={record ? 'Edit customer' : 'Create customer'}
-      description="Update contact details and communication preferences."
-      formId={`${id}-form`} loading={isSubmitting} strings={{ confirm: 'Save customer', loading: 'Saving customer…' }}>
-      <form id={`${id}-form`} onSubmit={submit} noValidate aria-busy={isSubmitting}>
+  return {
+    ...overlay.overlayProps,
+    trigger: <Button onClick={open}>{record ? 'Edit customer' : 'Create customer'}</Button>,
+    title: record ? 'Edit customer' : 'Create customer',
+    description: 'Update contact details and communication preferences.',
+    formId: `${id}-form`,
+    loading: isSubmitting,
+    strings: { confirm: 'Save customer', loading: 'Saving customer…' },
+    children: <form id={`${id}-form`} onSubmit={submit} noValidate aria-busy={isSubmitting}>
         <Stack gap="xl">
           {summary.length > 0 && <ErrorSummary title="Customer could not be saved" errors={summary} />}
           <ControlledFormField control={form.control} name="name" label="Customer name" required rules={{ required: 'Enter a customer name.', minLength: { value: 2, message: 'Enter at least two characters.' } }}>
@@ -86,7 +100,6 @@ export function RHFOverlayForm({ record, onSave, onSaved }: RHFOverlayFormProps)
             {(field, _error, invalid) => <ToggleField label="Send account updates" name={field.name} value={field.value} controlRef={field.ref} onBlur={field.onBlur} onValueChange={value => field.onChange(value)} invalid={invalid} disabled={isSubmitting} />}
           </ControlledFormField>
         </Stack>
-      </form>
-    </ActionDrawer>
-  </>;
+      </form>,
+  };
 }

package/docs/consumer-skill/examples/token-domain-structure.tsx

@@ -0,0 +1,68 @@
+import type { ReactNode } from 'react';
+import { Card } from 'themelia-react-ui/base/cards';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { Number as NumberValue } from 'themelia-react-ui/primitives';
+import { Heading, Text } from 'themelia-react-ui/typography';
+
+export interface AllocationLocation {
+	id: string;
+	name: string;
+	lines: { id: string; title: string; selection?: string; reserved: number }[];
+}
+
+/**
+ * Card-free domain content comparing reserved quantities across locations, a
+ * relationship no block represents. Goods that share one fulfillment status and
+ * location, with fulfillment commands, belong to FulfillmentGroup instead.
+ * Accepted quantities and allowed actions are app-owned.
+ */
+export function AllocationByLocation({ locations, unallocated, actions }: {
+	locations: AllocationLocation[];
+	unallocated: { id: string; title: string; quantity: number }[];
+	actions?: ReactNode;
+}) {
+	return <Stack gap="2xl" className="@container/allocation min-w-0">
+		<div className="grid min-w-0 grid-cols-1 gap-space-2xl @lg/allocation:grid-cols-2">
+			{locations.map(location => <Stack key={location.id} gap="md">
+				<Heading tag="h3" size="sm">{location.name}</Heading>
+				<dl className="grid min-w-0 grid-cols-[minmax(0,1fr)_auto] gap-x-space-xl gap-y-space-md">
+					{location.lines.map(line => <div key={line.id} className="contents">
+						<dt className="min-w-0"><Stack gap="dense">
+							<Text type="inherit" className="wrap-anywhere">{line.title}</Text>
+							{line.selection && <Text size="xs" type="secondary">{line.selection}</Text>}
+						</Stack></dt>
+						<dd><Text tag="span" type="secondary"><NumberValue value={line.reserved} /> reserved</Text></dd>
+					</div>)}
+				</dl>
+			</Stack>)}
+		</div>
+		{unallocated.length > 0 && <Stack gap="md">
+			<Heading tag="h3" size="sm">Awaiting allocation</Heading>
+			{unallocated.map(line => <Text key={line.id} type="secondary">
+				<NumberValue value={line.quantity} /> × {line.title}
+			</Text>)}
+		</Stack>}
+		{actions && <Stack direction="horizontal" gap="md" justify="end">{actions}</Stack>}
+	</Stack>;
+}
+
+/** The composition boundary supplies the surface; the subject adds no inset. */
+export function AllocationSubjectExample() {
+	return <Card title="Dispatch allocation" description="Reserved goods grouped by dispatch location.">
+		<AllocationByLocation
+			locations={[
+				{ id: 'sofia', name: 'Sofia studio', lines: [
+					{ id: 'shirt-sofia', title: 'Linen overshirt', selection: 'Navy / M', reserved: 1 },
+					{ id: 'mug-sofia', title: 'Stoneware mug', selection: 'Salt', reserved: 1 },
+				] },
+				{ id: 'plovdiv', name: 'Plovdiv dispatch', lines: [
+					{ id: 'mug-plovdiv', title: 'Stoneware mug', selection: 'Salt', reserved: 1 },
+				] },
+			]}
+			unallocated={[
+				{ id: 'mug', title: 'Stoneware mug · Salt', quantity: 1 },
+				{ id: 'bag', title: 'Canvas bag · Olive', quantity: 1 },
+			]}
+		/>
+	</Card>;
+}

package/docs/consumer-skill/references/agents-md.md

@@ -6,30 +6,32 @@ Claude Code read; in a project that has only `CLAUDE.md`, paste it there. It
 points agents at this installed skill and states when UI work is done.
 
 ```md
-<!-- themelia-react-ui:start 2.0.4 -->
+<!-- themelia-react-ui:start 2.0.5 -->
 ## UI built with themelia-react-ui
 Read the matching node_modules/themelia-react-ui/docs/consumer-skills/<name>/SKILL.md:
-themelia-components: setup, discovery, typed components/forms/workflows;
-themelia-tokenization: semantic themes, typography, spacing/density and portals;
-themelia-composition: business hierarchy, responsive screens and visual repair.
-They share docs/consumer-skill assets. Read installed declarations over memory.
-Find owners, map cooperating subjects, then inspect exact APIs:
+themelia-components: setup, discovery and typed APIs/forms;
+themelia-tokenization: semantic themes, visual roles and portals;
+themelia-composition: data-led subjects, hierarchy, responsive regions and repair;
+themelia-design: data briefs, view specs, scored critique.
+Read installed declarations. Shared assets/agent: docs/consumer-skill.
+Decide task, hierarchy, action priority and surface/inset owners before JSX:
+node_modules/themelia-react-ui/docs/consumer-skill/references/screen-decisions.md.
+Find domain owners/public parts; compare APIs before custom markup:
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/find-components.mjs <task nouns>
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/map-composition.mjs --roles
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-component.mjs <symbol> --import <exact import>
 node node_modules/themelia-react-ui/docs/consumer-skill/scripts/inspect-tokens.mjs <role or root>
-When using Page, it owns the route h1/gutters. Its commands use header.primaryAction
-(one) and ordered header.secondaryActions; destructive ones confirm with ConfirmDialog.
-Use header.tabs for selected/routed sections; continuous detail sections can stay in
-the body. Space siblings with Stack/Grid gap; write copy
-with Heading/Text and values with Money/Date/Number; use semantic colors; badges stay
-neutral unless they state status; dialogs come only from themelia-react-ui/features/overlays.
+Page owns h1/gutters; commands use one header.primaryAction and ordered
+header.secondaryActions. Confirm destructive commands with ConfirmDialog.
+Back links/tabs are optional. Base/layout + token-backed JSX can shape domains.
+Stack/Grid own gaps; Heading/Text own copy; Money/Date/Number format values.
+Semantic colors; neutral badges unless status is meaningful.
+Dialogs come only from themelia-react-ui/features/overlays.
 Done means: node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>
-reports no errors (fix and re-run, at most three rounds), then the app's typecheck, lint
-and tests pass. Completion also requires inspected narrow/wide light/dark appearance
-and executed relevant interactions, including open/focus/error states. Report source,
-rendered and interaction evidence separately; missing proof is unverified. Give kept
-warnings with file:line and reason.
+reports no errors (fix/re-run up to three rounds); app typecheck/lint/tests pass.
+Inspect narrow/wide light/dark hierarchy/insets; execute open/focus/error interactions.
+Report source, appearance and behavior separately; missing proof is unverified.
+Give kept warnings with file:line and reason.
 <!-- themelia-react-ui:end -->
 ```
 

package/docs/consumer-skill/references/analytics.md

@@ -16,7 +16,7 @@ application data and never fetch or define a business metric.
 | Used/limit quotas with shares, daily values and period selection | `UsageCard` from `themelia-react-ui/blocks/analytics/usage-card` | Owns a Card and ready/loading/error/empty presentation with retry/period callbacks. No optional chart peer. |
 | One plain label/value fact | `InlineStat` from `themelia-react-ui/blocks/data-display` | Card-free; app chooses whether this subject needs a Card. |
 | Several facts about one record | `MetadataList` from `themelia-react-ui/base/metadata-list` | Card-free; value primitives own formatting. |
-| Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics` | Card-free chart composition; caller supplies chart content and an optional Card boundary. |
+| Caller-owned chart series | `ChartCard` from `themelia-react-ui/blocks/analytics` with Recharts children | Card-free chart composition; `surface="card"` frames it. It wraps the children in `ChartContainer` with your `config`. |
 
 Start with these subject owners before constructing a Card with a number and
 supporting text. Reuse their formatting, hierarchy and relevant states when
@@ -55,6 +55,23 @@ peer even when a selected presentation hides its sparkline. Read the finder
 result's peers and installed declarations. UsageCard has a focused leaf import;
 its quota model differs from general MetricData.
 
+## Charts
+
+There are no packaged `AreaChart` or `LineChart` components. Charts are Recharts
+primitives (`AreaChart`, `BarChart`, `LineChart`, `PieChart` and their series,
+from the optional `recharts` peer) inside `ChartCard`, or inside `ChartContainer`
+from `themelia-react-ui/base/chart` when another owner supplies the title. Give
+each series a `ChartConfig` entry whose color is a chart token such as
+`var(--chart-1)` and reference it as `var(--color-<key>)` in the series, so the
+chart follows the active theme. Use `ChartTooltip` with `ChartTooltipContent`
+rather than a custom tooltip; its `valueFormatter` formats only the value (for
+example as currency) and keeps the indicator and series label.
+
+`MetricComparison` colours its delta by direction unless `current.trend` says
+whether the movement is good: pass `trend: 'positive'` when a fall in overdue
+balances or churn is the good outcome. Size the chart through the container, not fixed
+pixel widths, and verify it at narrow widths.
+
 ## Usage, facts and verification
 
 For `UsageCard` period/loading/error/retry and quota meaning, read

package/docs/consumer-skill/references/commerce-composition.md

@@ -0,0 +1,97 @@
+# Order and invoice composition capability map
+
+Compare an order, fulfillment, invoice or receivable screen with these public
+owners before writing JSX. They present application data: totals, taxes,
+balances, allocation rules and permitted commands stay app-owned. A relationship
+none of them represents, such as reserved stock compared across warehouses, is
+still a normal [domain structure](domain-structures.md). Inspect the exact
+props with `inspect-component.mjs` before relying on a slot or surface value.
+
+## Canonical imports
+
+Every owner below imports from `themelia-react-ui/blocks/commerce`. Other
+families keep their published spelling: `base/cards`, `base/buttons`,
+`base/feedback`, `base/chart` (Recharts scaffolding), `features/table`,
+`features/filters`, `features/overlays` and `layout/page`. When a path misses,
+`find-components.mjs` reports `importResolution` with the canonical import and,
+for paths such as `blocks/commerce/order-header`, the component it names.
+
+## Order and fulfillment detail
+
+| Subject | Owner | Frame |
+| --- | --- | --- |
+| Order number, status and commands | `Page` header (`title`, status `Badge`s in `slots.titleSuffix`, `primaryAction`, `secondaryActions`); `OrderHeader` only when Page renders no header | Page owns the h1, gutters and command row |
+| Payment hold, fraud review or another standing notice | `Alert` with `AlertTitle` and `AlertDescription` from `base/feedback` | Inline notice, not a Card |
+| Purchased goods and totals | A `Card` holding `OrderLineItem` rows and `SummaryPanel` with `AmountRow`, or `OrderSummary` | The Card frames both; the ledger adds no inset box |
+| Goods grouped by fulfillment status and ship-from location, with their commands | `FulfillmentGroup`; a partial dispatch passes its own rows as `children` and the unit total as `count` | Framed by default; `surface="flat"` inside an existing Card |
+| One parcel and its checkpoints | `ShipmentTracking` | Unframed by default; `surface="card"` on its own |
+| Payment attempts, captures and refunds | `OrderTransactions` | Unframed by default; `surface="card"` on its own |
+| One refund in progress | `RefundStatusCard` | Unframed by default; `surface="card"` on its own |
+| Buyer, contact and addresses | `OrderCustomer` (`shippingMethod` under the shipping address); one address alone is `AddressCard` | Unframed by default; `surface="card"` in an aside |
+| Order or payment history | `OrderTimeline` (it takes its own `title`) or `PaymentTimeline` (title the Card) inside a `Card` | The rails draw no frame of their own |
+
+The [order detail recipe](../examples/commerce-lines.tsx) (`OrderFulfillmentDetail`)
+composes these owners on one Page with real command callbacks: the header owns
+the commands, two fulfillment groups frame themselves, and the buyer, payment
+summary and transactions are aside cards.
+
+## Invoice and receivable detail
+
+| Subject | Owner | Frame |
+| --- | --- | --- |
+| Invoice number, balance status and collection commands | `Page` header; set `maxVisibleSecondaryActions: 1` in it when long secondary labels crowd the primary command | Page owns the h1 and command row |
+| The invoice document | One framed `Card` holding `InvoiceHeader` (party `details` for tax and registration IDs; omit `status` when the page header states it), `InvoiceLineItems surface="flat"` and `TaxBreakdownCard` or a `SummaryPanel` | The document Card is the only frame; its parts stay unframed |
+| Settlement, payments and history | A `Card` with `SummaryPanel` and `AmountRow` (or `OrderSummary surface="card"`), `OrderTransactions surface="card"`, `PaymentTimeline` in a titled Card | One frame per subject |
+| Customer and billing address | `AddressCard kind="billing"`, or `OrderCustomer showShippingAddress={false}`, with `surface="card"` | Aside subjects |
+
+`InvoiceLineItems` paints its own framed table by default; inside the document
+Card pass `surface="flat"` so its rows sit flush with the card edge. Below its
+`@lg` container width each row shows the description with one `qty × price`
+line and the line total; custom `columns` keep their tracks and scroll
+horizontally. Mark secondary custom columns (VAT, discount, work period)
+`wideOnly`: below that width their tracks drop and the description cell repeats
+the values in copy marked `@lg/invoice-line-items:hidden`, so a narrow invoice
+neither scrolls nor crushes the service text. Its default `taxRate` is 0.2, so pass the invoice's real rate or
+custom `footerRows` with the authoritative amounts.
+
+The [invoice detail recipe](../examples/commerce-lines.tsx) (`ReceivableInvoiceDetail`)
+shows the document Card, the settlement ledger and a header that keeps one
+secondary command beside `Record payment`.
+
+Do not set `surface="flat"` on the top-level Cards of a detail page to remove
+box-in-box framing: flatten the inner part instead, so every subject keeps one
+clear frame.
+
+## Frame each subject once
+
+Owners that default unframed and accept `surface="card"`: `AddressCard`,
+`OrderCustomer`, `OrderSummary`, `OrderTransactions`, `PaymentMethod`,
+`ShipmentTracking`, `TaxBreakdownCard`, `DiscountStackPreview`,
+`RefundStatusCard`, `CartSummaryCard`, `InvoiceHeader` and
+`InventorySectionCard`. Owners that frame themselves and accept
+`surface="flat"`: `FulfillmentGroup` and `InvoiceLineItems`. An owner that
+already paints a frame (`surface="card"`, or one of the self-framing pair) is
+never wrapped in a second Card; unframed parts compose inside one, as in the
+invoice document. Page body and aside own the gaps between subjects.
+
+In index tables, `ResourceCell` renders order and invoice identifiers as plain
+text; it draws media only for `imageUrl`, `icon` or `fallback`, and
+`mediaShape="square"` keeps product photos uncropped. Status badges in app-owned
+cells reuse `fulfillmentStatusTone`, `paymentStatusTone`, `transactionStatusTone`
+and `invoiceStatusTone`, so a table colours states exactly as the blocks do.
+`InvoiceStatus` covers `draft`, `pending`, `overdue`, `disputed` and `paid`.
+Notify accepted commands with `toast` from `themelia-react-ui/base/toaster`,
+the same instance its `Toaster` renders.
+
+Line rows, totals, stock meters and progress already have owners
+(`OrderLineItem`, `AmountRow`, `InventoryLevel`, `Progress`). Reach for
+app-owned Tailwind only for a structure those owners do not represent, and
+then on your own elements, never to restyle owner anatomy.
+
+## Verify
+
+Check the order or invoice at narrow and wide widths in light and dark themes:
+the line totals stay on one line, the narrow invoice rows show one quantity line
+each, every subject has exactly one frame, and the header commands that do not
+fit move into the More actions menu. Execute the commands (capture, refund,
+reminder, payment) through their real callbacks, including failure and retry.