themelia-react-ui 2.0.3 → 2.0.5

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

@@ -1,7 +1,8 @@
-import { useId, useRef, useState, type FormEvent } from 'react';
+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 { FormField } from 'themelia-react-ui/base/forms';
+import { ControlledFormField, DirtyStateBanner, ErrorSummary, FormActionsBar, 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';
@@ -9,52 +10,43 @@ import { Text } from 'themelia-react-ui/typography';
 export interface AccountEditValue { id: string; name: string; }
 export interface AccountEditProps {
   initial: AccountEditValue;
-  // Resolve with the authoritative saved value; reject if persistence failed.
   onSave: (value: AccountEditValue) => Promise<AccountEditValue>;
   onCancel: () => void;
 }
 
-// Mount with key={initial.id} when switching records. Draft state belongs to this mount.
+/** Small embedded subject; full routes start from rhf-edit-page.tsx. */
 export function AccountEdit({ initial, onSave, onCancel }: AccountEditProps) {
-  const id = useId();
-  const input = useRef<HTMLInputElement>(null);
-  const inFlight = useRef(false);
-  const [name, setName] = useState(initial.name);
-  const [validation, setValidation] = useState<string>();
-  const [error, setError] = useState<string>();
-  const [pending, setPending] = useState(false);
+  const lock = useRef(false);
   const [saved, setSaved] = useState(false);
-  async function submit(event: FormEvent<HTMLFormElement>) {
-    event.preventDefault();
-    if (inFlight.current) return;
-    setError(undefined); setSaved(false);
-    const trimmed = name.trim();
-    if (trimmed.length < 2) {
-      setValidation('Enter at least two characters.'); input.current?.focus(); return;
-    }
-    setValidation(undefined); inFlight.current = true; setPending(true);
+  const form = useForm<AccountEditValue>({ defaultValues: initial });
+  const { isDirty, isSubmitting, errors } = form.formState;
+  const submit = form.handleSubmit(async values => {
+    if (lock.current) return;
+    lock.current = true;
+    setSaved(false);
+    form.clearErrors('root.server');
     try {
-      const result = await onSave({ id: initial.id, name: trimmed });
-      setName(result.name); setSaved(true);
+      form.reset(await onSave({ ...values, name: values.name.trim() }));
+      setSaved(true);
     } catch {
-      setError('Saving failed. Your draft is kept; retry Save account.');
-    } finally { inFlight.current = false; setPending(false); }
-  }
+      form.setError('root.server', { type: 'transport', message: 'Saving failed. Your draft is kept; retry Save account.' });
+    } finally { lock.current = false; }
+  });
   return <Card title="Edit account" surface="card">
-    <form onSubmit={submit} noValidate aria-busy={pending}>
+    <form onSubmit={submit} noValidate aria-busy={isSubmitting}>
       <Stack gap="lg">
-        <FormField label="Account name" htmlFor={id} required error={validation}
-          hint="At least two characters." supportingTextId={`${id}-help`}>
-          <Input ref={input} id={id} value={name} required disabled={pending}
-            aria-invalid={Boolean(validation)} aria-describedby={`${id}-help`}
-            onChange={event => { setName(event.target.value); setValidation(undefined); setError(undefined); setSaved(false); }} />
-        </FormField>
-        {error && <Text role="alert" type="error">{error}</Text>}
-        {saved && <Text role="status">Account saved.</Text>}
-        <Stack direction={{ base: 'vertical', sm: 'horizontal' }} gap="sm">
-          <Button tone="primary" type="submit" loading={pending} strings={{ loading: 'Saving account…' }}>Save account</Button>
-          <Button type="button" disabled={pending} onClick={onCancel}>Cancel edit</Button>
-        </Stack>
+        {isDirty && <DirtyStateBanner title="Unsaved changes" />}
+        {errors.root?.server?.message && <ErrorSummary title="Account could not be saved" errors={[errors.root.server.message]} />}
+        <ControlledFormField control={form.control} name="name" label="Account name" required
+          hint="At least two characters." rules={{ validate: value => value.trim().length >= 2 || 'Enter at least two characters.' }}>
+          {(field, _error, invalid) => <Input ref={field.ref} name={field.name} value={field.value}
+            onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+        </ControlledFormField>
+        {saved && !isDirty && <Text role="status">Account saved.</Text>}
+        <FormActionsBar>
+          <Button type="button" disabled={isSubmitting} onClick={onCancel}>Cancel edit</Button>
+          <SubmitStateButton dirty={isDirty} disableWhenPristine submitting={isSubmitting}>Save account</SubmitStateButton>
+        </FormActionsBar>
       </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": [
@@ -105,7 +141,8 @@
     {
       "file": "app-layout.tsx",
       "exports": [
-        "WorkspaceLayout"
+        "WorkspaceLayout",
+        "WorkspaceExamplePage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -137,6 +174,56 @@
       ],
       "phase": "basic",
       "optionalPeers": []
+    },
+    {
+      "file": "authentication.tsx",
+      "exports": [
+        "PasswordSignIn"
+      ],
+      "phase": "optional",
+      "optionalPeers": [
+        "react-hook-form"
+      ]
+    },
+    {
+      "file": "rhf-edit-page.tsx",
+      "exports": [
+        "RHFEditPage"
+      ],
+      "phase": "optional",
+      "optionalPeers": [
+        "react-hook-form"
+      ]
+    },
+    {
+      "file": "rhf-overlay-form.tsx",
+      "exports": [
+        "RHFOverlayForm",
+        "RHFDialogForm"
+      ],
+      "phase": "optional",
+      "optionalPeers": [
+        "react-hook-form"
+      ]
+    },
+    {
+      "file": "rhf-bindings.tsx",
+      "exports": [
+        "TypedControlBindings"
+      ],
+      "phase": "optional",
+      "optionalPeers": [
+        "react-day-picker",
+        "react-hook-form"
+      ]
+    },
+    {
+      "file": "rhf-transport.tsx",
+      "exports": [
+        "awaitCallbackSave"
+      ],
+      "phase": "basic",
+      "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-bindings.tsx

@@ -0,0 +1,86 @@
+import { useId } from 'react';
+import { useForm } from 'react-hook-form';
+import { ControlledFormField } from 'themelia-react-ui/base/forms';
+import { Input, Textarea } from 'themelia-react-ui/base/text-inputs';
+import { Checkbox, Select, Switch, SwitchCard, ToggleField } from 'themelia-react-ui/base/choice-inputs';
+import { DatePicker } from 'themelia-react-ui/base/date-pickers';
+import { ColorInput, DateTimeInput, PhoneInput, SliderField, TagsInput } from 'themelia-react-ui/base/value-inputs';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { Text } from 'themelia-react-ui/typography';
+
+export interface BindingValues {
+  title: string; description: string; category: string;
+  enabled: boolean; accepted: boolean; notifications: boolean; automation: boolean;
+  dueDate: Date | null; appointment: string; phone: string; tags: string[];
+  threshold: number; color: string;
+}
+
+/** Each binding follows the public control's actual value contract. */
+export function TypedControlBindings() {
+  const id = useId();
+  const { control } = useForm<BindingValues>({ defaultValues: {
+    title: '', description: '', category: 'standard', enabled: false, accepted: false,
+    notifications: true, automation: false, dueDate: null, appointment: '', phone: '',
+    tags: [], threshold: 50, color: '#335577',
+  } });
+  return <Stack gap="xl">
+    <ControlledFormField control={control} name="title" label="Title">
+      {(field, _error, invalid) => <Input ref={field.ref} name={field.name}
+        value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="description" label="Description">
+      {(field, _error, invalid) => <Textarea ref={field.ref} name={field.name}
+        value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="category" label="Category">
+      {(field, _error, invalid) => <Select ref={field.ref} name={field.name}
+        value={field.value} onValueChange={value => field.onChange(value ?? '')} onBlur={field.onBlur}
+        invalid={invalid} options={[{ value: 'standard', label: 'Standard' }, { value: 'priority', label: 'Priority' }]} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="enabled" label="Enabled">
+      {(field, _error, invalid) => <Switch ref={field.ref} name={field.name}
+        checked={field.value} onValueChange={checked => field.onChange(checked)} onBlur={field.onBlur} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="accepted" label="Accept terms" rules={{ validate: value => value || 'Accept the terms.' }}>
+      {(field, _error, invalid) => <Checkbox ref={field.ref} name={field.name}
+        checked={field.value} onValueChange={checked => field.onChange(checked)} onBlur={field.onBlur} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="notifications">
+      {(field, _error, invalid) => <ToggleField label="Email notifications" name={field.name}
+        value={field.value} controlRef={field.ref} onBlur={field.onBlur} onValueChange={checked => field.onChange(checked)}
+        invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="automation">
+      {(field, _error, invalid) => <SwitchCard label="Automatic processing" name={field.name}
+        value={field.value} controlRef={field.ref} onBlur={field.onBlur} onValueChange={checked => field.onChange(checked)}
+        invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="dueDate" label="Due date">
+      {(field, _error, invalid) => <DatePicker mode="single" value={field.value ?? undefined}
+        triggerRef={field.ref} onBlur={field.onBlur} onValueChange={output => field.onChange(output.date ?? null)} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="appointment" label="Appointment">
+      {(field, _error, invalid) => <DateTimeInput value={field.value || undefined}
+        triggerRef={field.ref} onBlur={field.onBlur} onValueChange={value => field.onChange(value ?? '')} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="phone" label="Phone">
+      {(field, _error, invalid) => <PhoneInput ref={field.ref} name={field.name}
+        value={field.value} onChange={event => field.onChange(event.target.value)} onBlur={field.onBlur} invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="tags" label="Tags">
+      {(field, _error, invalid) => <TagsInput<string> name={field.name} value={field.value}
+        inputRef={field.ref} onBlur={field.onBlur} onValueChange={value => field.onChange(value)} aria-invalid={invalid} />}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="threshold" hint="Choose a value between 0 and 100." supportingTextId={`${id}-threshold-help`}>
+      {(field, _error, invalid) => <Stack gap="xs">
+        <Text tag="span" id={`${id}-threshold-label`} weight="medium">Threshold</Text>
+        <SliderField name={field.name} value={field.value} aria-labelledby={`${id}-threshold-label`} aria-describedby={`${id}-threshold-help`}
+          onValueChange={value => field.onChange(value)} inputRef={field.ref} onBlur={field.onBlur} invalid={invalid} showValue />
+      </Stack>}
+    </ControlledFormField>
+    <ControlledFormField control={control} name="color" label="Brand color">
+      {(field, _error, invalid) => <ColorInput ref={field.ref} name={field.name}
+        value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} />}
+    </ControlledFormField>
+  </Stack>;
+}

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

@@ -0,0 +1,141 @@
+import { useEffect, useId, useRef, useState } from 'react';
+import { useFieldArray, useForm, useWatch, type FieldErrors } from 'react-hook-form';
+import { Button } from 'themelia-react-ui/base/buttons';
+import { ControlledFormField, DirtyStateBanner, ErrorSummary, FormActionsBar, FormSection, SubmitStateButton } from 'themelia-react-ui/base/forms';
+import { Select, ToggleField } from 'themelia-react-ui/base/choice-inputs';
+import { Input, Textarea } from 'themelia-react-ui/base/text-inputs';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { MetadataList } from 'themelia-react-ui/base/metadata-list';
+import { TwoColumnLayout } from 'themelia-react-ui/layout/containers';
+import { Page } from 'themelia-react-ui/layout/page';
+import { Money } from 'themelia-react-ui/primitives';
+import { Text } from 'themelia-react-ui/typography';
+
+export interface OrderEditValues {
+  reference: string; email: string; notes: string; priority: string; notify: boolean;
+  lines: { product: string; quantity: number; priceMinor: number }[];
+}
+export type OrderSaveResult =
+  | { ok: true; values: OrderEditValues }
+  | { ok: false; errors: Partial<Record<'reference' | 'email' | 'notes' | 'lines', string>>; message?: string };
+export interface RHFEditPageProps {
+  initial: OrderEditValues;
+  /** Await the complete request and return the accepted server representation. */
+  onSave: (values: OrderEditValues) => Promise<OrderSaveResult>;
+  onCancel: () => void;
+}
+
+function messages(errors: FieldErrors<OrderEditValues>): string[] {
+  const result: string[] = [];
+  for (const error of [errors.reference, errors.email, errors.notes, errors.priority, errors.lines, errors.lines?.root, errors.root?.server]) {
+    if (typeof error?.message === 'string') result.push(error.message);
+  }
+  for (const line of Array.isArray(errors.lines) ? errors.lines : []) for (const error of [line?.product, line?.quantity, line?.priceMinor]) {
+    if (typeof error?.message === 'string') result.push(error.message);
+  }
+  return result;
+}
+
+/** Mount with key={record.id}; background revalidation must not reset a dirty draft. */
+export function RHFEditPage({ initial, onSave, onCancel }: RHFEditPageProps) {
+  const id = useId();
+  const lock = useRef(false);
+  const pendingFocus = useRef<'reference' | 'email' | 'notes' | 'lines.0.product' | undefined>(undefined);
+  const [saved, setSaved] = useState(false);
+  const form = useForm<OrderEditValues>({ defaultValues: initial, mode: 'onBlur' });
+  const lines = useFieldArray({ control: form.control, name: 'lines', rules: { minLength: { value: 1, message: 'Keep at least one line item.' } } });
+  const draftLines = useWatch({ control: form.control, name: 'lines' });
+  const totalMinor = draftLines.reduce((sum, line) => sum + (line.quantity || 0) * (line.priceMinor || 0), 0);
+  const { isDirty, isSubmitting, errors } = form.formState;
+  const summary = messages(errors);
+  const { setFocus } = form;
+  useEffect(() => {
+    if (!isSubmitting && pendingFocus.current) {
+      setFocus(pendingFocus.current);
+      pendingFocus.current = undefined;
+    }
+  }, [isSubmitting, setFocus]);
+  const submit = form.handleSubmit(async values => {
+    if (lock.current) return;
+    lock.current = true;
+    setSaved(false);
+    pendingFocus.current = undefined;
+    form.clearErrors();
+    try {
+      const result = await onSave(values);
+      if (!result.ok) {
+        let focused = false;
+        for (const name of ['reference', 'email', 'notes', 'lines'] as const) {
+          const message = result.errors[name];
+          if (message) {
+            form.setError(name, { type: 'server', message });
+            if (!focused) pendingFocus.current = name === 'lines' ? (values.lines.length ? 'lines.0.product' : undefined) : name;
+            focused = true;
+          }
+        }
+        form.setError('root.server', { type: 'server', message: result.message ?? 'Review the highlighted fields. Your draft is kept.' });
+        return;
+      }
+      form.reset(result.values);
+      setSaved(true);
+    } catch {
+      form.setError('root.server', { type: 'transport', message: 'Saving failed. Your draft is kept; retry Save order.' });
+    } finally { lock.current = false; }
+  });
+  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." />}
+        {summary.length > 0 && <ErrorSummary title="Order could not be saved" errors={summary} />}
+        {saved && !isDirty && <Text role="status">Order saved.</Text>}
+        <TwoColumnLayout adaptTo="container" main={<>
+          <FormSection title="Customer" description="The customer receives order updates at this address.">
+            <ControlledFormField control={form.control} name="reference" label="Order reference" required rules={{ required: 'Enter an order reference.' }}>
+              {(field, _error, invalid) => <Input ref={field.ref} name={field.name} value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+            </ControlledFormField>
+            <ControlledFormField control={form.control} name="email" label="Customer email" required rules={{ required: 'Enter an email.', pattern: { value: /^[^\s@]+@[^\s@]+\.[^\s@]+$/, message: 'Enter a valid email.' } }}>
+              {(field, _error, invalid) => <Input type="email" ref={field.ref} name={field.name} value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+            </ControlledFormField>
+          </FormSection>
+          <FormSection title="Line items" actions={<Button type="button" disabled={isSubmitting} onClick={() => lines.append({ product: '', quantity: 1, priceMinor: 0 })}>Add item</Button>}>
+            {lines.fields.map((line, index) => <Stack key={line.id} gap="md">
+              <ControlledFormField control={form.control} name={`lines.${index}.product`} label={`Item ${index + 1}`} rules={{ required: 'Enter a product.' }}>
+                {(field, _error, invalid) => <Input ref={field.ref} name={field.name} value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+              </ControlledFormField>
+              <Stack direction={{ base: 'vertical', sm: 'horizontal' }} gap="md" align="end">
+                <ControlledFormField control={form.control} name={`lines.${index}.quantity`} label="Quantity" rules={{ validate: value => (Number.isFinite(value) && Number.isInteger(value) && value >= 1) || 'Enter a whole quantity of at least one.' }}>
+                  {(field, _error, invalid) => <Input ref={field.ref} type="number" name={field.name} min={1} value={Number.isNaN(field.value) ? '' : String(field.value)} onChange={event => field.onChange(event.target.valueAsNumber)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+                </ControlledFormField>
+                <ControlledFormField control={form.control} name={`lines.${index}.priceMinor`} label="Unit price (cents)" rules={{ validate: value => (Number.isFinite(value) && Number.isInteger(value) && value >= 0) || 'Enter a whole price in cents of zero or more.' }}>
+                  {(field, _error, invalid) => <Input ref={field.ref} type="number" name={field.name} min={0} value={Number.isNaN(field.value) ? '' : String(field.value)} onChange={event => field.onChange(event.target.valueAsNumber)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+                </ControlledFormField>
+                <Button type="button" disabled={isSubmitting || lines.fields.length < 2} onClick={() => lines.remove(index)}>Remove item {index + 1}</Button>
+              </Stack>
+            </Stack>)}
+          </FormSection>
+          <FormSection title="Internal notes">
+            <ControlledFormField control={form.control} name="notes" label="Notes" hint="Visible to your team only.">
+              {(field, _error, invalid) => <Textarea ref={field.ref} name={field.name} value={field.value} onValueChange={value => field.onChange(value)} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} />}
+            </ControlledFormField>
+          </FormSection>
+        </>} aside={<>
+          <FormSection title="Fulfillment">
+            <ControlledFormField control={form.control} name="priority" label="Priority">
+              {(field, _error, invalid) => <Select ref={field.ref} name={field.name} value={field.value} onValueChange={value => field.onChange(value ?? '')} onBlur={field.onBlur} invalid={invalid} disabled={isSubmitting} options={[{ value: 'standard', label: 'Standard' }, { value: 'express', label: 'Express' }]} />}
+            </ControlledFormField>
+            <ControlledFormField control={form.control} name="notify">
+              {(field, _error, invalid) => <ToggleField label="Email customer on save" name={field.name} value={field.value} controlRef={field.ref} onBlur={field.onBlur} onValueChange={value => field.onChange(value)} invalid={invalid} disabled={isSubmitting} />}
+            </ControlledFormField>
+          </FormSection>
+          <FormSection title="Summary"><MetadataList items={[
+            { id: 'items', label: 'Line items', value: lines.fields.length },
+            { id: 'total', label: 'Draft total', value: <Money amount={totalMinor} currency="USD" unit="minor" /> },
+          ]} /></FormSection>
+        </>} />
+        <FormActionsBar sticky leading={isDirty ? 'Changes are not saved yet.' : 'All changes saved.'}>
+          <Button type="button" disabled={isSubmitting} onClick={onCancel}>Cancel</Button>
+          <Button type="button" disabled={isSubmitting || !isDirty} onClick={() => { form.reset(); setSaved(false); }}>Discard changes</Button>
+          <SubmitStateButton dirty={isDirty} disableWhenPristine submitting={isSubmitting}>Save order</SubmitStateButton>
+        </FormActionsBar>
+  </Page>;
+}