@xemahq/ui-kernel 0.6.1 → 0.7.0

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]);
+}

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

@@ -0,0 +1,134 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// useWizard — headless multi-step engine
+//
+// The state machine the hand-rolled wizards lack: step index, next/prev, goTo,
+// isFirst/isLast, per-step advance gating, and a `status(i)` that maps 1:1 onto
+// the presentational `FormStepper`'s `FormStepStatus`. Controlled (pass `step`)
+// and uncontrolled (pass `initialStep`) modes. No timers, no side effects.
+// ═══════════════════════════════════════════════════════════════════════════
+import { useCallback, useMemo, useState } from 'react';
+
+import { FormStepStatus } from '../primitives/form-stepper';
+
+export interface WizardStepDef {
+  readonly key: string;
+  readonly label: string;
+  readonly hint?: string;
+}
+
+export interface UseWizardOptions {
+  readonly steps: readonly WizardStepDef[];
+  /**
+   * Per-step forward gate. `canAdvance(i)` must return true before the wizard
+   * will move PAST step `i`. Backward navigation is always allowed. Defaults to
+   * always-advanceable.
+   */
+  readonly canAdvance?: (index: number) => boolean;
+  /** Uncontrolled initial index (default 0). Ignored when `step` is provided. */
+  readonly initialStep?: number;
+  /** Controlled active index. When set, the hook is controlled. */
+  readonly step?: number;
+  /** Fired on every requested index change (both modes). */
+  readonly onStepChange?: (index: number) => void;
+}
+
+export interface WizardApi {
+  readonly steps: readonly WizardStepDef[];
+  readonly activeIndex: number;
+  readonly activeStep: WizardStepDef;
+  readonly isFirst: boolean;
+  readonly isLast: boolean;
+  /** Whether the CURRENT step's forward gate is satisfied. */
+  readonly canAdvance: boolean;
+  /** 0..1 progress across the steps. */
+  readonly progress: number;
+  readonly next: () => void;
+  readonly prev: () => void;
+  /** Jump to `index`. Backward is free; forward requires every intervening gate. */
+  readonly goTo: (index: number) => void;
+  /** {@link FormStepStatus} for step `index` — feeds `<FormStepper>`. */
+  readonly status: (index: number) => FormStepStatus;
+}
+
+/**
+ * @example
+ * const wizard = useWizard({
+ *   steps: [{ key: 'details', label: 'Details' }, { key: 'review', label: 'Review' }],
+ *   canAdvance: (i) => (i === 0 ? isValid : true),
+ * });
+ * <Wizard api={wizard} onFinish={submit}>
+ *   <WizardStep stepKey="details"><SchemaForm … /></WizardStep>
+ *   <WizardStep stepKey="review"><DocumentPreview … /></WizardStep>
+ * </Wizard>
+ */
+export function useWizard(options: UseWizardOptions): WizardApi {
+  const { steps, canAdvance, initialStep = 0, step, onStepChange } = options;
+  const count = steps.length;
+  const clamp = useCallback((i: number) => Math.max(0, Math.min(count - 1, i)), [count]);
+
+  const isControlled = step !== undefined;
+  const [internal, setInternal] = useState(() => clamp(initialStep));
+  const activeIndex = clamp(isControlled ? (step as number) : internal);
+
+  const gate = useCallback((i: number) => (canAdvance ? canAdvance(i) : true), [canAdvance]);
+
+  const request = useCallback(
+    (target: number) => {
+      const next = clamp(target);
+      if (next === activeIndex) return;
+      onStepChange?.(next);
+      if (!isControlled) setInternal(next);
+    },
+    [activeIndex, clamp, isControlled, onStepChange],
+  );
+
+  const goTo = useCallback(
+    (index: number) => {
+      const target = clamp(index);
+      if (target <= activeIndex) {
+        request(target); // backward is always allowed
+        return;
+      }
+      // Forward: every step from active..target-1 must pass its gate.
+      for (let i = activeIndex; i < target; i += 1) {
+        if (!gate(i)) return;
+      }
+      request(target);
+    },
+    [activeIndex, clamp, gate, request],
+  );
+
+  const next = useCallback(() => {
+    if (activeIndex >= count - 1) return;
+    if (!gate(activeIndex)) return;
+    request(activeIndex + 1);
+  }, [activeIndex, count, gate, request]);
+
+  const prev = useCallback(() => request(activeIndex - 1), [activeIndex, request]);
+
+  const status = useCallback(
+    (index: number): FormStepStatus => {
+      if (index < activeIndex) return FormStepStatus.DONE;
+      if (index === activeIndex) return FormStepStatus.ACTIVE;
+      return FormStepStatus.PENDING;
+    },
+    [activeIndex],
+  );
+
+  return useMemo<WizardApi>(
+    () => ({
+      steps,
+      activeIndex,
+      activeStep: steps[activeIndex],
+      isFirst: activeIndex === 0,
+      isLast: activeIndex === count - 1,
+      canAdvance: gate(activeIndex),
+      progress: count <= 1 ? 1 : activeIndex / (count - 1),
+      next,
+      prev,
+      goTo,
+      status,
+    }),
+    [steps, activeIndex, count, gate, next, prev, goTo, status],
+  );
+}

package/src/ui/capture/value-format.ts

@@ -0,0 +1,22 @@
+// Shared value coercion/formatting for the capture kit — used by the input
+// boundary (SchemaForm) and the read-only view (DocumentPreview) so the two
+// never disagree on how a stored value maps to its display/edit string.
+import { CaptureFieldType, type CaptureFieldSpec } from './field-spec';
+
+/** Coerce any stored value to a display/edit string (empty for absent). */
+export function asString(value: unknown): string {
+  if (typeof value === 'string') return value;
+  if (value === undefined || value === null) return '';
+  return String(value);
+}
+
+/** Human-readable rendering of a scalar field value for the read-only preview. */
+export function formatScalar(field: CaptureFieldSpec, value: unknown, emptyText: string): string {
+  if (value === undefined || value === null || value === '') return emptyText;
+  switch (field.type) {
+    case CaptureFieldType.Boolean:
+      return value === true ? 'Yes' : 'No';
+    default:
+      return asString(value);
+  }
+}

package/src/ui/capture/wizard.tsx

@@ -0,0 +1,100 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// <Wizard> / <WizardStep> — thin presentational shell over useWizard
+//
+// Composes the existing `<FormStepper>` for the numbered rail (with the ACTIVE
+// step's body rendered inline, guided-style — pending steps stay empty) and
+// renders a Back / Next / Finish nav bar. All state lives in the `useWizard`
+// engine you pass via `api`; this component is presentation only.
+// ═══════════════════════════════════════════════════════════════════════════
+import { Children, isValidElement, type ReactElement, type ReactNode } from 'react';
+
+import { cn } from '../cn';
+import { Button } from '../primitives/button';
+import { FormStepper, type FormStep } from '../primitives/form-stepper';
+
+import type { WizardApi } from './use-wizard';
+
+export interface WizardStepProps {
+  /** Must match a `useWizard` step `key`. */
+  readonly stepKey: string;
+  readonly children: ReactNode;
+}
+
+/**
+ * Declarative wrapper for one wizard step's body. Rendered by `<Wizard>` only
+ * when its `stepKey` is the active step.
+ */
+export function WizardStep(_props: WizardStepProps): null {
+  // Rendering is orchestrated by <Wizard>; this component only carries props.
+  return null;
+}
+
+export interface WizardProps {
+  readonly api: WizardApi;
+  readonly children: ReactNode;
+  /** Called when Finish is pressed on the last step (gate already satisfied). */
+  readonly onFinish?: () => void;
+  readonly nextLabel?: string;
+  readonly backLabel?: string;
+  readonly finishLabel?: string;
+  /** Hide the built-in nav bar (caller renders its own using `api`). */
+  readonly hideNav?: boolean;
+  readonly className?: string;
+}
+
+function stepBodies(children: ReactNode): Map<string, ReactNode> {
+  const map = new Map<string, ReactNode>();
+  Children.forEach(children, (child) => {
+    if (isValidElement(child) && (child as ReactElement<WizardStepProps>).props?.stepKey) {
+      const p = (child as ReactElement<WizardStepProps>).props;
+      map.set(p.stepKey, p.children);
+    }
+  });
+  return map;
+}
+
+export function Wizard({
+  api,
+  children,
+  onFinish,
+  nextLabel = 'Continue',
+  backLabel = 'Back',
+  finishLabel = 'Finish',
+  hideNav = false,
+  className,
+}: WizardProps) {
+  const bodies = stepBodies(children);
+
+  const formSteps: FormStep[] = api.steps.map((step, index) => ({
+    key: step.key,
+    label: step.label,
+    hint: step.hint,
+    status: api.status(index),
+    // Render the active step's body inline; pending/done steps stay empty so
+    // the rail reads as a guided one-step-at-a-time flow.
+    children: index === api.activeIndex ? bodies.get(step.key) ?? null : null,
+  }));
+
+  return (
+    <div className={cn('space-y-5', className)}>
+      <FormStepper steps={formSteps} />
+
+      {!hideNav && (
+        <div className="flex items-center justify-between gap-2 border-t border-rule pt-4">
+          <Button variant="ghost" onClick={api.prev} disabled={api.isFirst}>
+            {backLabel}
+          </Button>
+          {api.isLast ? (
+            <Button onClick={onFinish} disabled={!api.canAdvance}>
+              {finishLabel}
+            </Button>
+          ) : (
+            <Button onClick={api.next} disabled={!api.canAdvance}>
+              {nextLabel}
+            </Button>
+          )}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/ui/index.ts

@@ -88,3 +88,6 @@ export { default as LoadingState, type LoadingStateVariant } from './chrome/Load
 export { default as AsyncBoundary } from './chrome/AsyncBoundary';
 
 export { PdfPreview, type PdfPreviewProps } from './pdf/pdf-preview';
+
+// ── guided-capture UX kit (B5 — wizard, validation, prefill, schema form) ──
+export * from './capture';