@xemahq/ui-kernel 0.6.1 → 0.8.0

package/src/ui/capture/schema-field-input.tsx

@@ -0,0 +1,314 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// SchemaFieldInput — one typed input per CaptureFieldType
+//
+// Mirrors app-forge-web's `FieldInput` (the 10 typed inputs) using ui-kernel
+// primitives, and ADDS the `object` (nested group) and `list` (repeatable
+// items) composites. `reference` is source-agnostic here: it defaults to a text
+// input, but a caller can inject a picker via `renderReference` (that is the
+// seam app-forge uses to plug its record-backed `ReferenceSelect`).
+// ═══════════════════════════════════════════════════════════════════════════
+import { Plus, Trash2 } from 'lucide-react';
+import { useCallback, useRef, useState, type ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { Button } from '../primitives/button';
+import { Checkbox } from '../primitives/checkbox';
+import { Input } from '../primitives/input';
+import { Label } from '../primitives/label';
+import { Textarea } from '../primitives/textarea';
+
+import { CaptureFieldType, type CaptureFieldSpec, type CaptureValues } from './field-spec';
+import { asString } from './value-format';
+
+const SELECT_CLASS =
+  'mt-1 flex h-10 w-full rounded-md border border-input bg-background px-3 py-2 text-body-1 text-foreground ring-offset-background focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50';
+
+/** Optional override for the `reference` field type (record-backed picker). */
+export type RenderReference = (args: {
+  readonly field: CaptureFieldSpec;
+  readonly value: unknown;
+  readonly onChange: (value: unknown) => void;
+  readonly disabled?: boolean;
+  readonly inputId: string;
+}) => ReactNode;
+
+export interface SchemaFieldInputProps {
+  readonly field: CaptureFieldSpec;
+  readonly value: unknown;
+  readonly onChange: (value: unknown) => void;
+  readonly disabled?: boolean;
+  /** Dot-path prefix for nested/list item fields (labels/ids stay unique). */
+  readonly path: string;
+  /** Per-field errors keyed by dot-path (from `useSchemaValidation` or server). */
+  readonly errors?: Readonly<Record<string, string>>;
+  readonly renderReference?: RenderReference;
+}
+
+export function SchemaFieldInput(props: SchemaFieldInputProps) {
+  const { field, value, onChange, disabled, path, renderReference } = props;
+  const inputId = `field-${path}`;
+
+  switch (field.type) {
+    case CaptureFieldType.Text:
+      return <Textarea id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} rows={4} placeholder={field.placeholder} />;
+    case CaptureFieldType.Number:
+      return (
+        <Input
+          id={inputId}
+          type="number"
+          value={asString(value)}
+          onChange={(e) => onChange(e.target.value === '' ? '' : Number(e.target.value))}
+          disabled={disabled}
+          placeholder={field.placeholder}
+        />
+      );
+    case CaptureFieldType.Decimal:
+      // NUMERIC carried verbatim as text — never Number()-coerced (precision).
+      return <Input id={inputId} type="text" inputMode="decimal" value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? '0.00'} />;
+    case CaptureFieldType.User:
+      return <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? 'subject id'} />;
+    case CaptureFieldType.Boolean:
+      return (
+        <div className="mt-1">
+          <Checkbox id={inputId} checked={value === true} onCheckedChange={(checked) => onChange(checked === true)} disabled={disabled} />
+        </div>
+      );
+    case CaptureFieldType.Date:
+      return <Input id={inputId} type="date" value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} />;
+    case CaptureFieldType.Datetime:
+      return <Input id={inputId} type="datetime-local" value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} />;
+    case CaptureFieldType.Enum:
+      return (
+        <select id={inputId} className={SELECT_CLASS} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled}>
+          <option value="">— select —</option>
+          {(field.enumValues ?? []).map((v) => (
+            <option key={v} value={v}>
+              {v}
+            </option>
+          ))}
+        </select>
+      );
+    case CaptureFieldType.Reference:
+      return renderReference ? (
+        <>{renderReference({ field, value, onChange, disabled, inputId })}</>
+      ) : (
+        <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder ?? 'reference id'} />
+      );
+    case CaptureFieldType.Object:
+      return <ObjectInput {...props} />;
+    case CaptureFieldType.List:
+      return <ListInput {...props} />;
+    case CaptureFieldType.Image:
+    case CaptureFieldType.File:
+      return <MediaFieldInput {...props} />;
+    case CaptureFieldType.Audio:
+      return <AudioFieldInput {...props} />;
+    // string (and any unknown) — plain single-line input.
+    default:
+      return <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder} />;
+  }
+}
+
+const FILE_INPUT_CLASS =
+  'block w-full text-body-2 text-foreground file:mr-3 file:rounded-md file:border-0 file:bg-secondary file:px-3 file:py-1.5 file:text-body-2 file:text-secondary-foreground hover:file:bg-secondary/80 disabled:cursor-not-allowed disabled:opacity-50';
+
+/** Read a File/Blob as a base64 data-URL (JSON-serializable, offline-safe). */
+function readAsDataUrl(file: Blob, onDone: (dataUrl: string) => void): void {
+  const reader = new FileReader();
+  reader.onload = () =>
+    onDone(typeof reader.result === 'string' ? reader.result : '');
+  reader.readAsDataURL(file);
+}
+
+/**
+ * `image`/`file` capture. On mobile, `field.capture` makes an image field open
+ * the camera directly. The value is a data-URL so it stays JSON-serializable and
+ * flows unchanged through the record model + offline outbox.
+ */
+function MediaFieldInput({ field, value, onChange, disabled, path }: SchemaFieldInputProps) {
+  const inputId = `field-${path}`;
+  const current = asString(value);
+  const isImage = field.type === CaptureFieldType.Image;
+  const accept = field.accept ?? (isImage ? 'image/*' : undefined);
+  return (
+    <div className="mt-1 space-y-2">
+      <input
+        id={inputId}
+        type="file"
+        className={FILE_INPUT_CLASS}
+        disabled={disabled}
+        {...(accept ? { accept } : {})}
+        {...(field.capture ? { capture: field.capture } : {})}
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          if (file) {
+            readAsDataUrl(file, onChange);
+          }
+        }}
+      />
+      {current ? (
+        <div className="flex items-center gap-2">
+          {isImage && current.startsWith('data:image') ? (
+            <img src={current} alt={field.label} className="max-h-32 rounded-md border border-input" />
+          ) : (
+            <span className="truncate text-body-2 text-muted-foreground">Attached</span>
+          )}
+          <Button type="button" variant="ghost" size="sm" onClick={() => onChange('')} disabled={disabled}>
+            Clear
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * `audio` capture — records a voice memo via MediaRecorder and stores it as a
+ * data-URL. Browser APIs are touched only inside the record handler (SSR-safe).
+ */
+function AudioFieldInput({ value, onChange, disabled, path }: SchemaFieldInputProps) {
+  const inputId = `field-${path}`;
+  const current = asString(value);
+  const [recording, setRecording] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const recorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+
+  const start = useCallback(async () => {
+    setError(null);
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      const recorder = new MediaRecorder(stream);
+      chunksRef.current = [];
+      recorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          chunksRef.current.push(e.data);
+        }
+      };
+      recorder.onstop = () => {
+        for (const track of stream.getTracks()) {
+          track.stop();
+        }
+        readAsDataUrl(
+          new Blob(chunksRef.current, { type: recorder.mimeType || 'audio/webm' }),
+          onChange,
+        );
+      };
+      recorderRef.current = recorder;
+      recorder.start();
+      setRecording(true);
+    } catch {
+      setError('Microphone unavailable or permission denied.');
+    }
+  }, [onChange]);
+
+  const stop = useCallback(() => {
+    recorderRef.current?.stop();
+    recorderRef.current = null;
+    setRecording(false);
+  }, []);
+
+  return (
+    <div className="mt-1 space-y-2">
+      <div className="flex items-center gap-2">
+        {recording ? (
+          <Button type="button" variant="secondary" size="sm" onClick={stop} disabled={disabled}>
+            Stop
+          </Button>
+        ) : (
+          <Button type="button" variant="secondary" size="sm" onClick={() => void start()} disabled={disabled}>
+            {current ? 'Re-record' : 'Record'}
+          </Button>
+        )}
+        {current ? (
+          <Button type="button" variant="ghost" size="sm" onClick={() => onChange('')} disabled={disabled}>
+            Clear
+          </Button>
+        ) : null}
+      </div>
+      {error ? <p className="text-body-2 text-destructive">{error}</p> : null}
+      {current && !recording ? <audio id={inputId} controls src={current} className="w-full" /> : null}
+    </div>
+  );
+}
+
+/** Renders one label + input + error block for a nested field. */
+function NestedField(props: SchemaFieldInputProps) {
+  const { field, path, errors } = props;
+  const error = errors?.[path];
+  return (
+    <div>
+      <Label htmlFor={`field-${path}`}>
+        {field.label}
+        {field.required ? <span className="text-destructive"> *</span> : null}
+      </Label>
+      {field.description ? <p className="mb-1 text-caption text-ink-3">{field.description}</p> : null}
+      <SchemaFieldInput {...props} />
+      {error ? <p className="mt-1 text-caption text-destructive">{error}</p> : null}
+    </div>
+  );
+}
+
+function ObjectInput({ field, value, onChange, disabled, path, errors, renderReference }: SchemaFieldInputProps) {
+  const record = (value && typeof value === 'object' && !Array.isArray(value) ? value : {}) as CaptureValues;
+  const fields = field.fields ?? [];
+  return (
+    <div className="mt-1 space-y-3 rounded-lg border border-rule bg-paper-elev/40 p-3">
+      {fields.map((child) => (
+        <NestedField
+          key={child.key}
+          field={child}
+          value={record[child.key]}
+          onChange={(v) => onChange({ ...record, [child.key]: v })}
+          disabled={disabled}
+          path={`${path}.${child.key}`}
+          errors={errors}
+          renderReference={renderReference}
+        />
+      ))}
+    </div>
+  );
+}
+
+function ListInput({ field, value, onChange, disabled, path, errors, renderReference }: SchemaFieldInputProps) {
+  const items = (Array.isArray(value) ? value : []) as CaptureValues[];
+  const fields = field.fields ?? [];
+  const atMax = typeof field.max === 'number' && items.length >= field.max;
+
+  const setItem = (index: number, next: CaptureValues) => onChange(items.map((it, i) => (i === index ? next : it)));
+  const removeItem = (index: number) => onChange(items.filter((_, i) => i !== index));
+  const addItem = () => onChange([...items, {}]);
+
+  return (
+    <div className="mt-1 space-y-2">
+      {items.map((item, index) => (
+        <div key={index} className="relative space-y-3 rounded-lg border border-rule bg-paper-elev/40 p-3">
+          <div className="flex items-center justify-between">
+            <span className="text-caption font-medium text-ink-3">
+              {field.label} #{index + 1}
+            </span>
+            <Button type="button" variant="ghost" size="icon" onClick={() => removeItem(index)} disabled={disabled} aria-label={`Remove ${field.label} ${index + 1}`}>
+              <Trash2 className="h-4 w-4" />
+            </Button>
+          </div>
+          {fields.map((child) => (
+            <NestedField
+              key={child.key}
+              field={child}
+              value={item[child.key]}
+              onChange={(v) => setItem(index, { ...item, [child.key]: v })}
+              disabled={disabled}
+              path={`${path}.${index}.${child.key}`}
+              errors={errors}
+              renderReference={renderReference}
+            />
+          ))}
+        </div>
+      ))}
+      <Button type="button" variant="outline" size="sm" onClick={addItem} disabled={disabled || atMax} className={cn(items.length === 0 && 'w-full')}>
+        <Plus className="mr-1.5 h-3.5 w-3.5" />
+        Add {field.label}
+      </Button>
+    </div>
+  );
+}

package/src/ui/capture/schema-form.tsx

@@ -0,0 +1,108 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// <SchemaForm> — the ONE kernel schema→form renderer
+//
+// Consolidates the three parallel schema→form implementations (app-forge-web's
+// RecordForm/FieldInput, the pipelines with-schema-form, the rjsf install
+// wizard) into a single reusable primitive. Give it a flat `fields` list OR
+// titled `sections`; it renders one typed input per field (10 scalar types +
+// nested `object` + repeatable `list`), inline per-field errors, and an "AI
+// suggested" badge for machine-prefilled fields.
+//
+// Controlled: owns no value state — `values` in, `onChange` out. Pair it with
+// `useSchemaValidation` for live errors and `usePrefill` for suggestions.
+// ═══════════════════════════════════════════════════════════════════════════
+import { Sparkles } from 'lucide-react';
+import { type ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { Badge } from '../primitives/badge';
+import { Label } from '../primitives/label';
+
+import { type CaptureFieldSpec, type CaptureSchema, type CaptureSection, type CaptureValues, toSections } from './field-spec';
+import { SchemaFieldInput, type RenderReference } from './schema-field-input';
+
+export interface SchemaFormProps {
+  /** Flat schema. Mutually exclusive with `sections`. */
+  readonly fields?: readonly CaptureFieldSpec[];
+  /** Sectioned schema. Mutually exclusive with `fields`. */
+  readonly sections?: readonly CaptureSection[];
+  /** Pre-built schema object (either face). Lowest precedence. */
+  readonly schema?: CaptureSchema;
+  readonly values: CaptureValues;
+  readonly onChange: (values: CaptureValues) => void;
+  /** Per-field errors keyed by dot-path (from `useSchemaValidation` / server). */
+  readonly errors?: Readonly<Record<string, string>>;
+  /** Field keys to badge as machine-suggested (from `usePrefill`). */
+  readonly suggestedKeys?: ReadonlySet<string> | readonly string[];
+  readonly disabled?: boolean;
+  /** Inject a record-backed picker for `reference` fields. */
+  readonly renderReference?: RenderReference;
+  /** Show section titles (default true when a section has a title). */
+  readonly className?: string;
+  /** Optional slot rendered after the fields (e.g. a submit bar). */
+  readonly footer?: ReactNode;
+}
+
+function toSet(keys: SchemaFormProps['suggestedKeys']): ReadonlySet<string> {
+  if (!keys) return new Set();
+  return keys instanceof Set ? keys : new Set(keys as readonly string[]);
+}
+
+/**
+ * @example
+ * const [values, setValues] = useState({});
+ * const { errors } = useSchemaValidation(fields, values);
+ * <SchemaForm fields={fields} values={values} onChange={setValues} errors={errors} />
+ */
+export function SchemaForm({ fields, sections, schema, values, onChange, errors, suggestedKeys, disabled, renderReference, className, footer }: SchemaFormProps) {
+  const resolved: readonly CaptureSection[] = toSections(sections ?? (fields ? fields : schema) ?? []);
+  const suggested = toSet(suggestedKeys);
+
+  const setField = (key: string, value: unknown) => onChange({ ...values, [key]: value });
+
+  return (
+    <div className={cn('space-y-6', className)}>
+      {resolved.map((section) => (
+        <fieldset key={section.key} className="space-y-3 border-0 p-0" disabled={disabled}>
+          {section.title ? (
+            <legend className="mb-1 text-subtitle font-semibold text-ink">
+              {section.title}
+              {section.description ? <span className="mt-0.5 block text-caption font-normal text-ink-3">{section.description}</span> : null}
+            </legend>
+          ) : null}
+          {section.fields.map((field) => {
+            const error = errors?.[field.key];
+            const isSuggested = suggested.has(field.key);
+            return (
+              <div key={field.key}>
+                <div className="flex items-center gap-2">
+                  <Label htmlFor={`field-${field.key}`}>
+                    {field.label}
+                    {field.required ? <span className="text-destructive"> *</span> : null}
+                  </Label>
+                  {isSuggested ? (
+                    <Badge variant="outline" className="gap-1 border-primary/30 bg-primary/10 px-1.5 py-0 text-caption text-primary">
+                      <Sparkles className="h-3 w-3" /> AI suggested
+                    </Badge>
+                  ) : null}
+                </div>
+                {field.description ? <p className="mb-1 text-caption text-ink-3">{field.description}</p> : null}
+                <SchemaFieldInput
+                  field={field}
+                  value={values[field.key]}
+                  onChange={(v) => setField(field.key, v)}
+                  disabled={disabled}
+                  path={field.key}
+                  errors={errors}
+                  renderReference={renderReference}
+                />
+                {error ? <p className="mt-1 text-caption text-destructive">{error}</p> : null}
+              </div>
+            );
+          })}
+        </fieldset>
+      ))}
+      {footer}
+    </div>
+  );
+}

package/src/ui/capture/use-prefill.ts

@@ -0,0 +1,150 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// usePrefill — field-level pre-fill from an async, source-agnostic default
+// source (AI, prior-context, a template service — the caller supplies it).
+//
+// It populates initial field values WITHOUT clobbering user edits, and tracks
+// which fields were machine-suggested so the UI can badge them. A field the
+// user has touched is never overwritten by a (re)load, and reading a field back
+// after the user edits it clears its "suggested" mark.
+// ═══════════════════════════════════════════════════════════════════════════
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { CaptureValues } from './field-spec';
+
+export interface UsePrefillOptions<T extends CaptureValues = CaptureValues> {
+  /**
+   * Async source of default values keyed by field key. Called on mount (unless
+   * `enabled` is false) and on `reload()`. May return a partial record — only
+   * the keys it returns are considered suggestions.
+   */
+  readonly fetchDefaults: () => Promise<Partial<T>>;
+  /** Seed values (e.g. an edit form's existing record). Never treated as suggested. */
+  readonly initialValues?: T;
+  /** Gate the initial fetch (default true). */
+  readonly enabled?: boolean;
+}
+
+export interface UsePrefillResult<T extends CaptureValues = CaptureValues> {
+  readonly values: T;
+  /** Set one field (a user edit) — clears its suggested mark. */
+  readonly setValue: (key: string, value: unknown) => void;
+  /** Replace/patch values (a user edit) — clears suggested marks for changed keys. */
+  readonly setValues: (updater: Partial<T> | ((prev: T) => T)) => void;
+  /** Keys populated by the default source and NOT yet edited by the user. */
+  readonly suggestedKeys: ReadonlySet<string>;
+  readonly isSuggested: (key: string) => boolean;
+  readonly loading: boolean;
+  readonly error: unknown;
+  /** Re-run `fetchDefaults`; still respects user-touched keys. */
+  readonly reload: () => void;
+}
+
+/**
+ * @example
+ * const prefill = usePrefill({
+ *   fetchDefaults: () => api.suggestDefaults(contextId), // → { title: 'Draft', owner: 'me' }
+ *   initialValues: { title: '', owner: '' },
+ * });
+ * <SchemaForm
+ *   fields={fields}
+ *   values={prefill.values}
+ *   onChange={prefill.setValues}
+ *   suggestedKeys={prefill.suggestedKeys}   // renders an "AI suggested" badge
+ * />
+ */
+export function usePrefill<T extends CaptureValues = CaptureValues>(
+  options: UsePrefillOptions<T>,
+): UsePrefillResult<T> {
+  const { fetchDefaults, initialValues, enabled = true } = options;
+
+  const [values, setValuesState] = useState<T>(() => ({ ...(initialValues ?? ({} as T)) }));
+  const [suggested, setSuggested] = useState<ReadonlySet<string>>(() => new Set());
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<unknown>(null);
+
+  // Keys the user has explicitly touched — a (re)load must never clobber these.
+  const touched = useRef<Set<string>>(new Set());
+  // Monotonic request id guards against a stale fetch resolving after a newer
+  // one (or after user edits) — no timeout-based races.
+  const requestId = useRef(0);
+
+  const setValue = useCallback((key: string, value: unknown) => {
+    touched.current.add(key);
+    setValuesState((prev) => ({ ...prev, [key]: value }));
+    setSuggested((prev) => {
+      if (!prev.has(key)) return prev;
+      const next = new Set(prev);
+      next.delete(key);
+      return next;
+    });
+  }, []);
+
+  const setValues = useCallback((updater: Partial<T> | ((prev: T) => T)) => {
+    setValuesState((prev) => {
+      const next = typeof updater === 'function' ? (updater as (p: T) => T)(prev) : { ...prev, ...updater };
+      const changed = new Set<string>();
+      for (const k of Object.keys(next)) {
+        if (next[k] !== prev[k]) {
+          touched.current.add(k);
+          changed.add(k);
+        }
+      }
+      if (changed.size > 0) {
+        setSuggested((prevSug) => {
+          if (![...changed].some((k) => prevSug.has(k))) return prevSug;
+          const n = new Set(prevSug);
+          for (const k of changed) n.delete(k);
+          return n;
+        });
+      }
+      return next;
+    });
+  }, []);
+
+  const run = useCallback(() => {
+    const id = ++requestId.current;
+    setLoading(true);
+    setError(null);
+    void fetchDefaults()
+      .then((defaults) => {
+        if (id !== requestId.current) return; // superseded — drop
+        const applied: string[] = [];
+        setValuesState((prev) => {
+          const next = { ...prev };
+          for (const [key, value] of Object.entries(defaults)) {
+            // Only fill keys the user hasn't touched and that are still empty.
+            const current = prev[key];
+            const isEmpty = current === undefined || current === null || current === '';
+            if (!touched.current.has(key) && isEmpty && value !== undefined) {
+              (next as CaptureValues)[key] = value;
+              applied.push(key);
+            }
+          }
+          return next;
+        });
+        setSuggested((prev) => {
+          if (applied.length === 0) return prev;
+          const n = new Set(prev);
+          for (const k of applied) n.add(k);
+          return n;
+        });
+      })
+      .catch((e: unknown) => {
+        if (id !== requestId.current) return;
+        setError(e);
+      })
+      .finally(() => {
+        if (id === requestId.current) setLoading(false);
+      });
+  }, [fetchDefaults]);
+
+  useEffect(() => {
+    if (enabled) run();
+    // Run once on mount / when re-enabled; `reload()` is the explicit re-fetch.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled]);
+
+  const isSuggested = useCallback((key: string) => suggested.has(key), [suggested]);
+
+  return { values, setValue, setValues, suggestedKeys: suggested, isSuggested, loading, error, reload: run };
+}

package/src/ui/capture/use-schema-validation.ts

@@ -0,0 +1,113 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// useSchemaValidation — client-side validation + "missing info" sweep
+//
+// Runs BEFORE any server round-trip, on every change/blur. Accepts either a
+// hand-written `zod` schema OR a `CaptureFieldSpec[]` / `CaptureSection[]` /
+// `CaptureSchema` (auto-adapted via `fieldSpecToZod`). Returns per-field errors
+// keyed by dot-path plus a deterministic `missingRequired` list so a guided UX
+// can nudge "you still need to fill X" without waiting for a 422.
+// ═══════════════════════════════════════════════════════════════════════════
+import { useMemo } from 'react';
+import { z } from 'zod';
+
+import { CaptureFieldType, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, type CaptureValues, toFieldList } from './field-spec';
+import { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+
+export interface SchemaValidationResult {
+  /** First error per field, keyed by dot-path (`tags.0.name`, `address.city`). */
+  readonly errors: Readonly<Record<string, string>>;
+  /** Dot-paths of required fields still empty — the "missing info" sweep. */
+  readonly missingRequired: readonly string[];
+  /** True when there are no errors AND nothing required is missing. */
+  readonly isValid: boolean;
+}
+
+type ValidationInput =
+  | z.ZodType
+  | CaptureSchema
+  | readonly CaptureFieldSpec[]
+  | readonly CaptureSection[];
+
+function isZodSchema(input: ValidationInput): input is z.ZodType {
+  return typeof (input as z.ZodType)?.safeParse === 'function';
+}
+
+/** Deterministic required sweep over the flat spec list (nested-aware). */
+function sweepMissing(fields: readonly CaptureFieldSpec[], values: CaptureValues, prefix = ''): string[] {
+  const missing: string[] = [];
+  for (const field of fields) {
+    const path = prefix ? `${prefix}.${field.key}` : field.key;
+    const value = values?.[field.key];
+    if (field.type === CaptureFieldType.Object) {
+      if (field.required && isEmptyValue(value)) missing.push(path);
+      if (value && typeof value === 'object' && !Array.isArray(value)) {
+        missing.push(...sweepMissing(field.fields ?? [], value as CaptureValues, path));
+      }
+      continue;
+    }
+    if (field.type === CaptureFieldType.List) {
+      if (field.required && isEmptyValue(value)) missing.push(path);
+      if (Array.isArray(value)) {
+        value.forEach((item, i) => {
+          if (item && typeof item === 'object') {
+            missing.push(...sweepMissing(field.fields ?? [], item as CaptureValues, `${path}.${i}`));
+          }
+        });
+      }
+      continue;
+    }
+    if (field.required && isEmptyValue(value)) missing.push(path);
+  }
+  return missing;
+}
+
+/**
+ * @example
+ * const { errors, missingRequired, isValid } = useSchemaValidation(fields, values);
+ * // live under each input:
+ * errors['email']            // → 'Email must be a valid address' | undefined
+ * missingRequired            // → ['email', 'address.city']
+ * // gate a wizard step / submit button:
+ * <Button disabled={!isValid}>Continue</Button>
+ */
+export function useSchemaValidation(input: ValidationInput, values: CaptureValues): SchemaValidationResult {
+  // Field specs (when supplied) drive the deterministic required sweep and the
+  // auto-adapted zod schema; a raw zod schema is used as-is.
+  const fields = useMemo<readonly CaptureFieldSpec[] | null>(
+    () => (isZodSchema(input) ? null : toFieldList(input)),
+    [input],
+  );
+  const schema = useMemo<z.ZodType>(
+    () => (isZodSchema(input) ? input : fieldSpecToZod(input)),
+    [input],
+  );
+
+  return useMemo<SchemaValidationResult>(() => {
+    const errors: Record<string, string> = {};
+    const result = schema.safeParse(values);
+    if (!result.success) {
+      for (const issue of result.error.issues) {
+        const path = issue.path.map(String).join('.');
+        // First error per path wins (deterministic, matches display order).
+        if (!(path in errors)) errors[path] = issue.message;
+      }
+    }
+
+    // Deterministic sweep when we have specs; otherwise derive "missing" from
+    // zod issues that fired on an empty value (so a bare zod schema still works).
+    const missingRequired = fields
+      ? sweepMissing(fields, values)
+      : Object.keys(errors).filter((path) => {
+          const segments = path.split('.');
+          let cur: unknown = values;
+          for (const seg of segments) cur = (cur as CaptureValues | undefined)?.[seg];
+          return isEmptyValue(cur);
+        });
+
+    return {
+      errors,
+      missingRequired,
+      isValid: Object.keys(errors).length === 0 && missingRequired.length === 0,
+    };
+  }, [schema, fields, values]);
+}