@xemahq/ui-kernel 0.6.1 → 0.7.0

package/src/ui/capture/field-spec-to-zod.test.ts

@@ -0,0 +1,59 @@
+// Pure-logic proofs for the CaptureFieldSpec → zod adapter. Runs under the
+// host-web vitest runner (this package carries no vitest dep — see tsconfig
+// exclude), mirroring the repo convention used by i18n-port.test.ts.
+import { describe, expect, it } from 'vitest';
+
+import { CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+import { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+
+describe('isEmptyValue', () => {
+  it('treats undefined/null/empty-string/empty-array as absent', () => {
+    expect(isEmptyValue(undefined)).toBe(true);
+    expect(isEmptyValue(null)).toBe(true);
+    expect(isEmptyValue('')).toBe(true);
+    expect(isEmptyValue([])).toBe(true);
+    expect(isEmptyValue('x')).toBe(false);
+    expect(isEmptyValue(0)).toBe(false);
+    expect(isEmptyValue(false)).toBe(false);
+  });
+});
+
+describe('fieldSpecToZod', () => {
+  const fields: CaptureFieldSpec[] = [
+    { key: 'title', label: 'Title', type: CaptureFieldType.String, required: true },
+    { key: 'count', label: 'Count', type: CaptureFieldType.Number, required: false, min: 0 },
+    { key: 'status', label: 'Status', type: CaptureFieldType.Enum, enumValues: ['open', 'closed'], required: true },
+    {
+      key: 'tags',
+      label: 'Tags',
+      type: CaptureFieldType.List,
+      min: 1,
+      fields: [{ key: 'name', label: 'Name', type: CaptureFieldType.String, required: true }],
+    },
+  ];
+
+  it('accepts a valid record', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: 'Hi', count: 3, status: 'open', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an empty required string', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: '', status: 'open', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(false);
+  });
+
+  it('allows an omitted optional field', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'closed', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(true);
+  });
+
+  it('rejects an enum value outside the set', () => {
+    const r = fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'bogus', tags: [{ name: 'a' }] });
+    expect(r.success).toBe(false);
+  });
+
+  it('enforces list min and nested required item fields', () => {
+    expect(fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'open', tags: [] }).success).toBe(false);
+    expect(fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'open', tags: [{ name: '' }] }).success).toBe(false);
+  });
+});

package/src/ui/capture/field-spec-to-zod.ts

@@ -0,0 +1,93 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// CaptureFieldSpec → Zod adapter
+//
+// Bridges the JSON-Schema-like field spec (name/type/required/enum, and the
+// nested object/list composites) to a `zod` schema so `useSchemaValidation`
+// works with app definitions, not only hand-written zod. Deterministic and
+// pure — no side effects, safe to memoize on the spec identity.
+// ═══════════════════════════════════════════════════════════════════════════
+import { z } from 'zod';
+
+import { CaptureFieldType, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, toFieldList } from './field-spec';
+
+/** `''`, `null`, `undefined` all mean "absent" at the capture boundary. */
+export function isEmptyValue(value: unknown): boolean {
+  return value === undefined || value === null || value === '' || (Array.isArray(value) && value.length === 0);
+}
+
+function scalarSchema(field: CaptureFieldSpec): z.ZodTypeAny {
+  switch (field.type) {
+    case CaptureFieldType.Number: {
+      let s = z.number({ message: `${field.label} must be a number` });
+      if (typeof field.min === 'number') s = s.min(field.min, { message: `${field.label} must be ≥ ${field.min}` });
+      if (typeof field.max === 'number') s = s.max(field.max, { message: `${field.label} must be ≤ ${field.max}` });
+      return s;
+    }
+    case CaptureFieldType.Boolean:
+      return z.boolean({ message: `${field.label} must be true or false` });
+    case CaptureFieldType.Decimal:
+      // NUMERIC carried as a string to avoid float precision loss.
+      return z.string().regex(/^-?\d+(\.\d+)?$/, { message: `${field.label} must be a decimal number` });
+    case CaptureFieldType.Enum: {
+      const values = [...(field.enumValues ?? [])];
+      if (values.length === 0) return z.string();
+      return z.enum(values as [string, ...string[]]);
+    }
+    case CaptureFieldType.Date:
+      return z.string().regex(/^\d{4}-\d{2}-\d{2}$/, { message: `${field.label} must be a date` });
+    case CaptureFieldType.Datetime:
+      return z.string().min(1, { message: `${field.label} must be a date/time` });
+    // string / text / user / reference — plain text.
+    default:
+      return z.string();
+  }
+}
+
+function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
+  let base: z.ZodTypeAny;
+  if (field.type === CaptureFieldType.Object) {
+    base = objectSchema(field.fields ?? []);
+  } else if (field.type === CaptureFieldType.List) {
+    let arr = z.array(objectSchema(field.fields ?? []));
+    if (typeof field.min === 'number') arr = arr.min(field.min, { message: `${field.label} needs at least ${field.min} item(s)` });
+    if (typeof field.max === 'number') arr = arr.max(field.max, { message: `${field.label} allows at most ${field.max} item(s)` });
+    base = arr;
+  } else {
+    base = scalarSchema(field);
+    if (field.required && (field.type === CaptureFieldType.String || field.type === CaptureFieldType.Text || field.type === CaptureFieldType.User || field.type === CaptureFieldType.Reference || field.type === CaptureFieldType.Datetime)) {
+      base = (base as z.ZodString).min(1, { message: `${field.label} is required` });
+    }
+  }
+
+  if (!field.required) {
+    // Optional: `.optional()` makes the object KEY absent-safe (zod v4 does not
+    // infer that from a union with z.undefined()); the union additionally
+    // accepts the empty-string / null sentinels the inputs emit for "cleared".
+    return z.union([base, z.literal(''), z.null()]).optional();
+  }
+  return base;
+}
+
+function objectSchema(fields: readonly CaptureFieldSpec[]): z.ZodObject<z.ZodRawShape> {
+  const shape: Record<string, z.ZodTypeAny> = {};
+  for (const f of fields) shape[f.key] = fieldSchema(f);
+  // Non-strict: unknown keys are ignored (the server is the strict fence).
+  return z.object(shape);
+}
+
+/**
+ * Build a `zod` object schema from a capture schema (flat fields, sections, or
+ * a `CaptureSchema`). The result validates the whole values record.
+ *
+ * @example
+ * const schema = fieldSpecToZod([
+ *   { key: 'title', label: 'Title', type: 'string', required: true },
+ *   { key: 'tags', label: 'Tags', type: 'list', fields: [{ key: 'name', label: 'Name', type: 'string', required: true }] },
+ * ]);
+ * schema.safeParse({ title: 'Hi', tags: [{ name: 'a' }] }); // { success: true }
+ */
+export function fieldSpecToZod(
+  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+): z.ZodObject<z.ZodRawShape> {
+  return objectSchema(toFieldList(schema));
+}

package/src/ui/capture/field-spec.test.ts

@@ -0,0 +1,49 @@
+// Pure-logic proofs for the schema-face normalizers. Runs under host-web
+// vitest (this package carries no vitest dep — see tsconfig exclude).
+import { describe, expect, it } from 'vitest';
+
+import { CaptureFieldType, groupFieldsBySection, toFieldList, toSections, type CaptureFieldSpec, type CaptureSection } from './field-spec';
+
+const fields: CaptureFieldSpec[] = [
+  { key: 'a', label: 'A', type: CaptureFieldType.String, section: 'one' },
+  { key: 'b', label: 'B', type: CaptureFieldType.Number, section: 'one' },
+  { key: 'c', label: 'C', type: CaptureFieldType.Boolean, section: 'two' },
+];
+
+const sections: CaptureSection[] = [
+  { key: 's1', title: 'S1', fields: [{ key: 'a', label: 'A', type: CaptureFieldType.String }] },
+  { key: 's2', title: 'S2', fields: [{ key: 'b', label: 'B', type: CaptureFieldType.String }] },
+];
+
+describe('toFieldList', () => {
+  it('returns a flat field list unchanged', () => {
+    expect(toFieldList(fields).map((f) => f.key)).toEqual(['a', 'b', 'c']);
+  });
+  it('flattens sections to their fields', () => {
+    expect(toFieldList(sections).map((f) => f.key)).toEqual(['a', 'b']);
+  });
+  it('reads the { fields } schema face', () => {
+    expect(toFieldList({ fields }).map((f) => f.key)).toEqual(['a', 'b', 'c']);
+  });
+  it('reads the { sections } schema face', () => {
+    expect(toFieldList({ sections }).map((f) => f.key)).toEqual(['a', 'b']);
+  });
+});
+
+describe('groupFieldsBySection', () => {
+  it('splits a flat list by each field section key, preserving order', () => {
+    const grouped = groupFieldsBySection(fields);
+    expect(grouped.map((s) => s.key)).toEqual(['one', 'two']);
+    expect(grouped[0].fields.map((f) => f.key)).toEqual(['a', 'b']);
+    expect(grouped[1].fields.map((f) => f.key)).toEqual(['c']);
+  });
+});
+
+describe('toSections', () => {
+  it('passes explicit sections through', () => {
+    expect(toSections(sections).map((s) => s.title)).toEqual(['S1', 'S2']);
+  });
+  it('derives sections from a flat list', () => {
+    expect(toSections(fields).map((s) => s.key)).toEqual(['one', 'two']);
+  });
+});

package/src/ui/capture/field-spec.ts

@@ -0,0 +1,160 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// Guided-capture field spec — the ONE schema shape the capture kit consumes
+//
+// This is the frontend-agnostic superset of app-forge-web's `AppField`. The
+// wire/definition layer (app-forge-api, its renderer's `AppFieldType`) owns 10
+// closed field types; this kit mirrors those 10 verbatim (same string values,
+// so an `AppField` is structurally assignable to `CaptureFieldSpec`) and ADDS
+// two structural composites — `object` and `list` — plus optional `section`
+// grouping. A workbench therefore extends ONE renderer (`<SchemaForm>`) instead
+// of the three parallel schema→form implementations that exist today.
+//
+// Value shape produced/consumed:
+//   scalar field  → string | number | boolean            (per type)
+//   object field  → Record<string, unknown>              (nested record)
+//   list field    → unknown[]                            (array of item records)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Closed set of capture field types. The first ten are value-identical to
+ * app-forge-web's `AppFieldType` (`string`/`text`/`number`/`decimal`/`boolean`/
+ * `date`/`datetime`/`enum`/`reference`/`user`) so definitions authored for the
+ * App Platform pass straight through. `object`/`list` are the structural
+ * composites this kit adds for nested + repeatable capture.
+ *
+ * The string VALUES are the contract — keep them identical to app-forge's enum
+ * (parity is checked there by `check-app-enum-parity.mjs`). Adding a value here
+ * that app-forge lacks is fine (superset); changing an existing value is not.
+ */
+export enum CaptureFieldType {
+  String = 'string',
+  Text = 'text',
+  Number = 'number',
+  Decimal = 'decimal',
+  Boolean = 'boolean',
+  Date = 'date',
+  Datetime = 'datetime',
+  Enum = 'enum',
+  Reference = 'reference',
+  User = 'user',
+  Object = 'object',
+  List = 'list',
+}
+
+/**
+ * A single capture field. Structural superset of app-forge's `AppField`:
+ * `key`/`label`/`type`/`required`/`enumValues`/`referenceEntity` carry the
+ * exact same meaning, so `AppField[]` can be handed to this kit unchanged. The
+ * extra props are additive and all optional.
+ *
+ * `type` accepts the {@link CaptureFieldType} enum OR its bare string value, so
+ * `{ type: 'string' }` (app-forge shape) and `{ type: CaptureFieldType.String }`
+ * both type-check.
+ */
+export interface CaptureFieldSpec {
+  readonly key: string;
+  readonly label: string;
+  readonly type: CaptureFieldType | `${CaptureFieldType}`;
+  readonly required?: boolean;
+  /** Helper text rendered under the label. */
+  readonly description?: string;
+  /** Placeholder for text-like inputs. */
+  readonly placeholder?: string;
+  /** Only for `enum` — the allowed values. */
+  readonly enumValues?: readonly string[];
+  /** Only for `reference` — key of the target entity (opaque to this kit). */
+  readonly referenceEntity?: string;
+  /** Only for `object`/`list` — the nested item shape. */
+  readonly fields?: readonly CaptureFieldSpec[];
+  /** `number`/`decimal`: numeric bounds. `list`: min/max item count. */
+  readonly min?: number;
+  readonly max?: number;
+  /**
+   * Optional section grouping key for FLAT `CaptureFieldSpec[]` schemas. When a
+   * schema is expressed as {@link CaptureSection}[] this is ignored (grouping is
+   * explicit). See {@link groupFieldsBySection}.
+   */
+  readonly section?: string;
+}
+
+/** A titled group of fields — the explicit sectioned schema shape. */
+export interface CaptureSection {
+  readonly key: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly fields: readonly CaptureFieldSpec[];
+}
+
+/**
+ * A capture schema is EITHER a flat field list OR a list of titled sections.
+ * `<SchemaForm>`, `useSchemaValidation`, and `<DocumentPreview>` all accept
+ * either face.
+ */
+export type CaptureSchema =
+  | { readonly fields: readonly CaptureFieldSpec[]; readonly sections?: undefined }
+  | { readonly sections: readonly CaptureSection[]; readonly fields?: undefined };
+
+/** Structured record value the capture kit reads/writes. */
+export type CaptureValues = Record<string, unknown>;
+
+/** True if `x` is the sectioned face of a schema. */
+export function isSectioned(
+  x: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+): x is { readonly sections: readonly CaptureSection[] } {
+  return !Array.isArray(x) && 'sections' in (x as object) && Array.isArray((x as { sections?: unknown }).sections);
+}
+
+/**
+ * Normalize any accepted schema face to the flat list of TOP-LEVEL fields.
+ * (Nested `object`/`list` item fields are NOT flattened — they belong to their
+ * parent's value.) Accepts a `CaptureFieldSpec[]`, a `CaptureSection[]`, or a
+ * `CaptureSchema`.
+ */
+export function toFieldList(
+  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+): readonly CaptureFieldSpec[] {
+  if (Array.isArray(schema)) {
+    const arr = schema as readonly (CaptureFieldSpec | CaptureSection)[];
+    // A CaptureSection has `title`+`fields`; a CaptureFieldSpec has `type`.
+    if (arr.length > 0 && arr.every((e) => 'title' in e && 'fields' in e && !('type' in e))) {
+      return (arr as readonly CaptureSection[]).flatMap((s) => s.fields);
+    }
+    return arr as readonly CaptureFieldSpec[];
+  }
+  if (isSectioned(schema)) return schema.sections.flatMap((s) => s.fields);
+  return (schema as { fields: readonly CaptureFieldSpec[] }).fields;
+}
+
+/**
+ * Resolve any accepted schema face to `CaptureSection[]`. A flat field list
+ * collapses to a single untitled section (or is split by each field's
+ * `section` key when present).
+ */
+export function toSections(
+  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+  fallbackTitle = '',
+): readonly CaptureSection[] {
+  if (Array.isArray(schema) && schema.length > 0 && (schema as readonly object[]).every((e) => 'title' in e && 'fields' in e)) {
+    return schema as readonly CaptureSection[];
+  }
+  if (!Array.isArray(schema) && isSectioned(schema)) return schema.sections;
+  return groupFieldsBySection(toFieldList(schema), fallbackTitle);
+}
+
+/** Split a flat field list into sections by each field's `section` key. */
+export function groupFieldsBySection(
+  fields: readonly CaptureFieldSpec[],
+  fallbackTitle = '',
+): readonly CaptureSection[] {
+  const order: string[] = [];
+  const byKey = new Map<string, CaptureFieldSpec[]>();
+  for (const f of fields) {
+    const key = f.section ?? '';
+    if (!byKey.has(key)) {
+      byKey.set(key, []);
+      order.push(key);
+    }
+    byKey.get(key)!.push(f);
+  }
+  return order.map((key) => ({ key: key || '_', title: key || fallbackTitle, fields: byKey.get(key)! }));
+}

package/src/ui/capture/index.ts

@@ -0,0 +1,43 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/ui-kernel — guided-capture UX kit (B5)
+//
+// Headless engines + presentation-thin primitives for schema-driven, guided
+// data capture: a wizard state machine, live client-side validation, AI/context
+// pre-fill, a single consolidated schema→form renderer, and a review-step
+// document preview. Consolidates the three parallel schema→form implementations
+// so a workbench extends ONE renderer.
+// ═══════════════════════════════════════════════════════════════════════════
+
+// ── field-spec model (aligned superset of app-forge's AppFieldType) ──
+export {
+  CaptureFieldType,
+  isSectioned,
+  toFieldList,
+  toSections,
+  groupFieldsBySection,
+  type CaptureFieldSpec,
+  type CaptureSection,
+  type CaptureSchema,
+  type CaptureValues,
+} from './field-spec';
+
+// ── schema → zod adapter ──
+export { fieldSpecToZod, isEmptyValue } from './field-spec-to-zod';
+
+// ── validation + "missing info" ──
+export { useSchemaValidation, type SchemaValidationResult } from './use-schema-validation';
+
+// ── pre-fill ──
+export { usePrefill, type UsePrefillOptions, type UsePrefillResult } from './use-prefill';
+
+// ── wizard engine + shell ──
+export { useWizard, type WizardApi, type WizardStepDef, type UseWizardOptions } from './use-wizard';
+export { Wizard, WizardStep, type WizardProps, type WizardStepProps } from './wizard';
+
+// ── consolidated schema form ──
+export { SchemaForm, type SchemaFormProps } from './schema-form';
+export { SchemaFieldInput, type SchemaFieldInputProps, type RenderReference } from './schema-field-input';
+export { asString, formatScalar } from './value-format';
+
+// ── review-step document preview ──
+export { DocumentPreview, type DocumentPreviewProps } from './document-preview';

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

@@ -0,0 +1,186 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// 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 { 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} />;
+    // 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} />;
+  }
+}
+
+/** 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>
+  );
+}