@xemahq/ui-kernel 0.6.0 → 0.7.0

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/charts/bar-chart.tsx

@@ -0,0 +1,135 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// BarChart — categorical bars, pure SVG (Wave 9.2)
+// ═══════════════════════════════════════════════════════════════════════════
+import type { ReactNode } from 'react';
+
+import { ChartEmpty, ChartFrame, type ChartLegendItem } from './chart-frame';
+import type { ChartBaseProps, ChartDatum } from './chart-types';
+import {
+  buildAriaSummary,
+  chartColorAt,
+  defaultFormatValue,
+  finitePoints,
+  niceScale,
+} from './chart-utils';
+
+// Internal coordinate space — the `viewBox`. `width="100%"` makes the SVG scale
+// to its container (D20 fluid), so these are ratios, not device pixels.
+const VIEW_W = 640;
+const VIEW_H = 360;
+const PAD = { top: 12, right: 12, bottom: 44, left: 48 } as const;
+const PLOT_L = PAD.left;
+const PLOT_R = VIEW_W - PAD.right;
+const PLOT_T = PAD.top;
+const PLOT_B = VIEW_H - PAD.bottom;
+const PLOT_W = PLOT_R - PLOT_L;
+const PLOT_H = PLOT_B - PLOT_T;
+
+export interface BarChartProps extends ChartBaseProps {
+  /** The bars — one per labelled datum. */
+  readonly data: readonly ChartDatum[];
+}
+
+export function BarChart({
+  data,
+  title,
+  ariaLabel,
+  formatValue,
+  className,
+  emptyLabel = 'No data',
+}: BarChartProps): ReactNode {
+  const format = formatValue ?? defaultFormatValue;
+  const points = finitePoints(data);
+
+  if (points.length === 0) {
+    return <ChartEmpty title={title} label={emptyLabel} className={className} />;
+  }
+
+  const values = points.map((p) => p.value);
+  const scale = niceScale(Math.min(...values), Math.max(...values));
+  const span = scale.max - scale.min;
+  const yToPx = (v: number): number => PLOT_B - ((v - scale.min) / span) * PLOT_H;
+  const baseline = yToPx(0);
+
+  const band = PLOT_W / points.length;
+  const barW = Math.min(band * 0.62, 72);
+
+  const legend: ChartLegendItem[] = points.map((p, i) => ({
+    label: p.label,
+    value: format(p.value),
+    color: chartColorAt(i, p.color),
+  }));
+
+  const summary = ariaLabel ?? buildAriaSummary(title, points, format, 'bar');
+
+  const plot = (
+    <svg
+      role="img"
+      aria-label={summary}
+      width="100%"
+      viewBox={`0 0 ${VIEW_W} ${VIEW_H}`}
+      preserveAspectRatio="xMidYMid meet"
+      className="block h-auto w-full overflow-visible text-ink-4"
+    >
+      {/* y gridlines + tick labels */}
+      {scale.ticks.map((t) => {
+        const y = yToPx(t);
+        return (
+          <g key={`y-${t}`}>
+            <line
+              x1={PLOT_L}
+              x2={PLOT_R}
+              y1={y}
+              y2={y}
+              stroke="currentColor"
+              strokeOpacity={t === 0 ? 0.35 : 0.12}
+            />
+            <text
+              x={PLOT_L - 8}
+              y={y}
+              textAnchor="end"
+              dominantBaseline="middle"
+              fontSize={12}
+              fill="currentColor"
+            >
+              {format(t)}
+            </text>
+          </g>
+        );
+      })}
+
+      {/* bars + x labels */}
+      {points.map((p, i) => {
+        const cx = PLOT_L + band * i + band / 2;
+        const yv = yToPx(p.value);
+        const top = Math.min(yv, baseline);
+        const h = Math.max(1, Math.abs(baseline - yv));
+        return (
+          <g key={`bar-${p.label}-${i}`}>
+            <rect
+              x={cx - barW / 2}
+              y={top}
+              width={barW}
+              height={h}
+              rx={3}
+              fill={chartColorAt(i, p.color)}
+            >
+              <title>{`${p.label}: ${format(p.value)}`}</title>
+            </rect>
+            <text
+              x={cx}
+              y={PLOT_B + 16}
+              textAnchor="middle"
+              fontSize={12}
+              fill="currentColor"
+            >
+              {p.label}
+            </text>
+          </g>
+        );
+      })}
+    </svg>
+  );
+
+  return <ChartFrame plot={plot} legend={legend} className={className} />;
+}