themelia-react-ui 2.0.3 → 2.0.4

package/docs/consumer-skill/examples/app-layout.tsx

@@ -3,7 +3,7 @@ import { Card } from 'themelia-react-ui/base/cards';
 import { SidebarTrigger } from 'themelia-react-ui/base/sidebar';
 import { AppLayout, type AppLayoutVariant } from 'themelia-react-ui/layout/app-shell';
 import { HeaderUserMenu, type HeaderUserMenuProps } from 'themelia-react-ui/layout/header';
-import { Page } from 'themelia-react-ui/layout/page';
+import { Page, type PageProps } from 'themelia-react-ui/layout/page';
 import { AppSidebar, LayoutSidebarProvider, SidebarNavigationUser, type AppSidebarProps } from 'themelia-react-ui/layout/sidebar';
 import type { UIConfig } from 'themelia-react-ui/ui-provider';
 import { Text } from 'themelia-react-ui/typography';
@@ -26,15 +26,13 @@ export interface WorkspaceLayoutProps {
   workspaceSwitcher?: ReactNode;
   user?: HeaderUserMenuProps['user'];
   onLogout?: () => void;
-  onCreate: () => void;
-  narrow?: boolean;
   children?: ReactNode;
 }
 
 /** The app accepts route/identity data and wires navigation/persistence callbacks. */
 export function WorkspaceLayout({ variant = 'inset', sidebar, navigationGroups = {},
   currentUrl, renderLink, workspaceLinks, workspaceSwitcher, user, onLogout,
-  onCreate, narrow, children }: WorkspaceLayoutProps) {
+  children }: WorkspaceLayoutProps) {
   const sidebarAccount = !sidebar && (variant === 'sidebar' || variant === 'inset');
   const brand = <Text weight="semibold">Admin</Text>;
   const account = user && !sidebarAccount ? <HeaderUserMenu user={user} onLogout={onLogout} /> : null;
@@ -42,18 +40,30 @@ export function WorkspaceLayout({ variant = 'inset', sidebar, navigationGroups =
     currentUrl={currentUrl} renderLink={renderLink} navigationGroups={navigationGroups}
     workspaceLinks={workspaceSwitcher ? undefined : workspaceLinks}
     slots={{ headerEnd: workspaceSwitcher, footer: user && sidebarAccount ? <SidebarNavigationUser user={user} onLogout={onLogout} /> : undefined }} />;
-  const content = <Page narrow={narrow} gutter={variant === 'stacked' ? 'none' : undefined}
-    header={{ title: 'Workspace', description: 'Review activity and manage your records.',
-      primaryAction: { label: 'Create record', onClick: onCreate } }}>
-    {children ?? <Card title="Activity" footerText="Latest workspace activity"><Text>Application content goes here.</Text></Card>}
-  </Page>;
   const trigger = <SidebarTrigger />;
   return <LayoutSidebarProvider adaptTo="container" className="min-h-0">
     {variant === 'stacked' ? <AppLayout variant="stacked" className="h-svh min-h-0" logo={brand}
-      slots={{headerEnd: account}}>{content}</AppLayout>
+      slots={{headerEnd: account}}>{children}</AppLayout>
       : variant === 'sidebar' || variant === 'inset' ? <AppLayout variant={variant} className="h-svh min-h-0"
-        sidebar={navigation} sidebarTrigger={trigger} slots={{ toolbarStart: brand, toolbarEnd: account }}>{content}</AppLayout>
+        sidebar={navigation} sidebarTrigger={trigger} slots={{ toolbarStart: brand, toolbarEnd: account }}>{children}</AppLayout>
       : <AppLayout variant={variant} className="h-svh min-h-0" logo={brand} sidebar={navigation}
-        sidebarTrigger={trigger} slots={{headerEnd: account}}>{content}</AppLayout>}
+        sidebarTrigger={trigger} slots={{headerEnd: account}}>{children}</AppLayout>}
   </LayoutSidebarProvider>;
 }
+
+export interface WorkspaceExamplePageProps {
+  onCreate: () => void;
+  narrow?: boolean;
+  /** Use none when a stacked/contained parent already owns the inline gutter. */
+  gutter?: PageProps['gutter'];
+  children?: ReactNode;
+}
+
+/** Illustrative route content; mount this or another route Page inside the shell. */
+export function WorkspaceExamplePage({ onCreate, narrow, gutter, children }: WorkspaceExamplePageProps) {
+  return <Page narrow={narrow} gutter={gutter}
+    header={{ title: 'Workspace', description: 'Review activity and manage your records.',
+      primaryAction: { label: 'Create record', onClick: onCreate } }}>
+    {children ?? <Card title="Activity" footerText="Latest workspace activity"><Text>Application content goes here.</Text></Card>}
+  </Page>;
+}

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

@@ -0,0 +1,77 @@
+import { useId, useRef, useState, type FormEvent } from 'react';
+import { Button } from 'themelia-react-ui/base/buttons';
+import { Checkbox } from 'themelia-react-ui/base/choice-inputs';
+import { FormField } from 'themelia-react-ui/base/forms';
+import { Stack } from 'themelia-react-ui/base/structure';
+import { Input, PasswordInput } from 'themelia-react-ui/base/text-inputs';
+import { AuthFooterLinks, AuthForm, AuthFormRow, AuthShell, type AuthShellProps } from 'themelia-react-ui/layout/auth';
+import { Text } from 'themelia-react-ui/typography';
+
+export interface PasswordSignInValue {
+  email: string;
+  password: string;
+  rememberDevice: boolean;
+}
+
+export interface PasswordSignInProps {
+  productName: string;
+  recoveryHref: string;
+  /** Optional public destination relevant to this sign-in flow. */
+  returnHref?: string;
+  renderLink?: AuthShellProps['renderLink'];
+  /** The app authenticates and navigates after success; reject on failure. */
+  onSignIn: (value: PasswordSignInValue) => Promise<void>;
+}
+
+export function PasswordSignIn({ productName, recoveryHref, returnHref, renderLink, onSignIn }: PasswordSignInProps) {
+  const id = useId();
+  const inFlight = useRef(false);
+  const [email, setEmail] = useState('');
+  const [password, setPassword] = useState('');
+  const [rememberDevice, setRememberDevice] = useState(false);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string>();
+
+  async function submit(event: FormEvent<HTMLFormElement>) {
+    event.preventDefault();
+    if (inFlight.current) return;
+    inFlight.current = true;
+    setError(undefined);
+    setPending(true);
+    try {
+      await onSignIn({ email, password, rememberDevice });
+    } catch {
+      setError('Sign-in failed. Check your details and try again.');
+    } finally {
+      inFlight.current = false;
+      setPending(false);
+    }
+  }
+
+  return <AuthShell brand={{ label: productName }} title="Sign in"
+    description="Use your account to continue." renderLink={renderLink}
+    footerLinks={returnHref ? [{ id: 'return', label: 'Return to application', href: returnHref }] : []}>
+    <AuthForm onSubmit={submit} aria-label="Password sign in" aria-busy={pending}>
+      <FormField label="Email" htmlFor={`${id}-email`} required>
+        <Input id={`${id}-email`} name="email" type="email" autoComplete="username"
+          required disabled={pending} value={email} onChange={event => setEmail(event.target.value)} />
+      </FormField>
+      <FormField label="Password" htmlFor={`${id}-password`} required>
+        <PasswordInput id={`${id}-password`} name="password" autoComplete="current-password"
+          required disabled={pending} value={password} onChange={event => setPassword(event.target.value)} />
+      </FormField>
+      <AuthFormRow>
+        <Stack render={<label htmlFor={`${id}-remember`} />} direction="horizontal" gap="md" wrap={false}>
+          <Checkbox id={`${id}-remember`} name="rememberDevice" checked={rememberDevice}
+            disabled={pending} onCheckedChange={checked => setRememberDevice(checked === true)} />
+          <Text tag="span">Remember this device</Text>
+        </Stack>
+        <AuthFooterLinks aria-label="Account recovery" renderLink={renderLink}
+          links={[{ id: 'recovery', label: 'Forgot password?', href: recoveryHref, disabled: pending }]} />
+      </AuthFormRow>
+      {error && <Text type="error" role="alert">{error}</Text>}
+      <Button tone="primary" type="submit" fullWidth loading={pending}
+        strings={{ loading: 'Signing in…' }}>Sign in</Button>
+    </AuthForm>
+  </AuthShell>;
+}

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/manifest.json

@@ -105,7 +105,8 @@
     {
       "file": "app-layout.tsx",
       "exports": [
-        "WorkspaceLayout"
+        "WorkspaceLayout",
+        "WorkspaceExamplePage"
       ],
       "phase": "basic",
       "optionalPeers": []
@@ -137,6 +138,55 @@
       ],
       "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"
+      ],
+      "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/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
+    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>;
+}

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

@@ -0,0 +1,92 @@
+import { useEffect, useId, useRef } from 'react';
+import { useForm } from 'react-hook-form';
+import { Button } from 'themelia-react-ui/base/buttons';
+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';
+
+export interface CustomerDraft { name: string; email: string; segment: string; notify: boolean; }
+export interface CustomerDraftRecord extends CustomerDraft { id: string; }
+export type CustomerSaveResult =
+  | { ok: true; record: CustomerDraftRecord }
+  | { ok: false; errors: Partial<Record<'name' | 'email', string>>; message?: string };
+export interface RHFOverlayFormProps {
+  record?: CustomerDraftRecord;
+  /** Resolve only when transport finishes; reject network failures. */
+  onSave: (draft: CustomerDraft, recordId?: string) => Promise<CustomerSaveResult>;
+  onSaved: (record: CustomerDraftRecord) => void;
+}
+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) {
+  const id = useId();
+  const overlay = useOverlayVisibility();
+  const lock = useRef(false);
+  const pendingFocus = useRef<'name' | 'email' | undefined>(undefined);
+  const form = useForm<CustomerDraft>({ defaultValues: record ?? empty, mode: 'onBlur' });
+  const { isSubmitting, errors } = form.formState;
+  const { setFocus } = form;
+  useEffect(() => {
+    if (!isSubmitting && pendingFocus.current) {
+      setFocus(pendingFocus.current);
+      pendingFocus.current = undefined;
+    }
+  }, [isSubmitting, setFocus]);
+  const summary = [errors.name?.message, errors.email?.message, errors.root?.server?.message].filter((message): message is string => Boolean(message));
+  function open() {
+    // Snapshot on an intentional open; never reset from background record updates.
+    form.reset(record ? { name: record.name, email: record.email, segment: record.segment, notify: record.notify } : empty);
+    overlay.show();
+  }
+  const submit = form.handleSubmit(async values => {
+    if (lock.current) return;
+    lock.current = true;
+    pendingFocus.current = undefined;
+    form.clearErrors();
+    try {
+      const result = await onSave(values, record?.id);
+      if (!result.ok) {
+        let focused = false;
+        for (const name of ['name', 'email'] as const) if (result.errors[name]) {
+          form.setError(name, { type: 'server', message: result.errors[name] });
+          if (!focused) pendingFocus.current = name;
+          focused = true;
+        }
+        form.setError('root.server', { type: 'server', message: result.message ?? 'Review the highlighted fields. Your draft is kept.' });
+        return;
+      }
+      form.reset(result.record);
+      onSaved(result.record);
+      overlay.hide();
+    } catch {
+      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}>
+        <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.' } }}>
+            {(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="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>
+          <ControlledFormField control={form.control} name="segment" label="Segment">
+            {(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: 'wholesale', label: 'Wholesale' }]} />}
+          </ControlledFormField>
+          <ControlledFormField control={form.control} name="notify">
+            {(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>
+  </>;
+}