themelia-react-ui 2.0.4 → 2.0.6

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.6 -->
 ## 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:
+Read node_modules/themelia-react-ui/docs/consumer-skills/<name>/SKILL.md:
+themelia-components: setup/APIs/forms; themelia-tokenization: themes/portals;
+themelia-composition: owners/hierarchy; themelia-design: briefs/specs/critique.
+Verify declarations. Shared root: package docs/consumer-skill.
+View design/review: shared agents/themelia-ui-designer.md; follow its prompt
+or delegate if supported. Agent setup: references/installation.md.
+Before JSX choose task, subject, scopes, frame/inset owners:
+node_modules/themelia-react-ui/docs/consumer-skill/references/screen-decisions.md.
 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.
-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.
+Page owns h1/gutters; route commands use header.primaryAction/secondaryActions.
+Local forms own submits; whole-page editors may use one header submit.
+Keep Page width stable across tabs; narrow only the focused panel.
+Card owns footer insets/dividers: put buttons in footerSlot, not FormActionsBar.
+Choose FormSection framing per parent; Stack/Grid own gaps, Text/Heading copy.
+Semantic colors; neutral badges except meaningful status.
+Dialogs: features/overlays only. Confirm destructive commands with ConfirmDialog.
+Done: node node_modules/themelia-react-ui/docs/consumer-skill/scripts/check-composition.mjs <changed files>
+Fix checker errors (up to three rounds); run app type/lint/tests.
+Inspect narrow/wide light/dark and opened states; execute focus/error/callbacks.
+Source/appearance/behavior proof separately; missing proof stays 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
@@ -44,6 +44,13 @@ copy, `change.direction` describes movement, and `trend` can override whether
 movement is positive, negative or neutral. A decline in churn can be positive.
 Keep the selected period and baseline clear in application context.
 
+Use `tone` for a bordered metric's surface or a colored metric's progress
+indicator. MetricGrid forwards the tone to its cells. When both props are
+present, `tone` takes precedence over the deprecated `colorScheme`. Use
+`destructive` in place of `danger` and `neutral` for a plain bordered
+surface. Colored metrics still default to primary progress. Set
+`tone="neutral"` for neutral progress.
+
 `MetricGrid` forwards one `variant`, size and state recipe to its peers. Its
 default `gap="xl"` and Card insets remain independent from text/media `size`.
 Narrow parents reduce track count even on a wide viewport. Use `columns` and
@@ -55,6 +62,31 @@ 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.
+
+ChartCard already supplies ChartContainer; do not nest a second one. For
+multiple series, put `ChartLegend content={<ChartLegendContent />}` inside the
+Recharts chart, or supply accessible direct series labels. Use config keys for
+series colors so the legend and marks agree in both themes. Footer copy can
+state a source or qualification; prose color explanations are a fragile legend.
+Substantial tables and disclosures belong in a body or peer region below the
+chart, with their own appropriate surface/inset owner.
+
+`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.