@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,149 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// <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 {
-  type CaptureFieldSpec,
-  type CaptureSchema,
-  type CaptureSection,
-  type CaptureValues,
-  toSections,
-} from './field-spec';
-import { SchemaFieldInput, type RenderReference } from './schema-field-input';
-import { Badge } from '../primitives/badge';
-import { Label } from '../primitives/label';
-
-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/submit-values.test.ts

@@ -1,70 +0,0 @@
-// Pure-logic proofs for the ONE values→wire projection and the declared
-// transform. Runs under the host-web vitest runner (this package carries no
-// vitest dep — see tsconfig exclude).
-import { describe, expect, it } from 'vitest';
-
-import { applyCaptureTransform, CaptureFieldTransform, CaptureFieldType, type CaptureFieldSpec } from './field-spec';
-import { fieldSpecToZod } from './field-spec-to-zod';
-import { captureValuesToStringMap, captureValuesToSubmitPayload } from './submit-values';
-
-const fields: CaptureFieldSpec[] = [
-  { key: 'apiKey', label: 'API key', type: CaptureFieldType.String, required: true, isSecret: true },
-  { key: 'baseUrl', label: 'Base URL', type: CaptureFieldType.Url, required: true },
-  { key: 'serviceAccount', label: 'Service account', type: CaptureFieldType.Json, required: false },
-];
-
-describe('applyCaptureTransform', () => {
-  it('applies only the DECLARED transform', () => {
-    expect(applyCaptureTransform(' a ', CaptureFieldTransform.Trim)).toBe('a');
-    expect(applyCaptureTransform('a', CaptureFieldTransform.Uppercase)).toBe('A');
-    expect(applyCaptureTransform('A', CaptureFieldTransform.Lowercase)).toBe('a');
-    expect(applyCaptureTransform(' a ', CaptureFieldTransform.None)).toBe(' a ');
-    // Absent = no normalization. There is no implicit blanket trim.
-    expect(applyCaptureTransform(' a ', undefined)).toBe(' a ');
-  });
-});
-
-describe('captureValuesToStringMap', () => {
-  it('projects ONLY declared keys, as strings', () => {
-    expect(
-      captureValuesToStringMap(fields, {
-        apiKey: 'sk-1',
-        baseUrl: 'https://acme.test',
-        rogue: 'should not travel',
-      }),
-    ).toEqual({ apiKey: 'sk-1', baseUrl: 'https://acme.test', serviceAccount: '' });
-  });
-});
-
-describe('captureValuesToSubmitPayload', () => {
-  it('parses a json field and leaves the rest untouched', () => {
-    expect(
-      captureValuesToSubmitPayload(fields, {
-        apiKey: 'sk-1',
-        baseUrl: 'https://acme.test',
-        serviceAccount: '{"a":1}',
-      }),
-    ).toEqual({ apiKey: 'sk-1', baseUrl: 'https://acme.test', serviceAccount: { a: 1 } });
-  });
-
-  it('does not drop an unparseable json value — validation is the gate', () => {
-    expect(captureValuesToSubmitPayload(fields, { serviceAccount: '{' }).serviceAccount).toBe('{');
-  });
-});
-
-describe('json field validation', () => {
-  const schema = fieldSpecToZod(fields);
-
-  it('rejects an unparseable json blob', () => {
-    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u', serviceAccount: '{' }).success).toBe(false);
-  });
-
-  it('accepts a parseable json blob and an omitted optional one', () => {
-    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u', serviceAccount: '{"a":1}' }).success).toBe(true);
-    expect(schema.safeParse({ apiKey: 'k', baseUrl: 'u' }).success).toBe(true);
-  });
-
-  it('requires a non-empty url/email field when required', () => {
-    expect(schema.safeParse({ apiKey: 'k', baseUrl: '' }).success).toBe(false);
-  });
-});

package/src/ui/capture/submit-values.ts

@@ -1,63 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// Capture values → submit payload
-//
-// The ONE projection from the form's in-memory `CaptureValues` to what goes on
-// the wire. Two faces, because two wire contracts exist and neither should grow
-// its own inline projection:
-//
-//   • `captureValuesToStringMap` — every field as a STRING (the shape a
-//     credential submit takes: `fields: Record<string, string>`).
-//   • `captureValuesToSubmitPayload` — same, except a `json` field is PARSED
-//     into its structured value (the shape the connection credential write
-//     takes: `credentials: Record<string, unknown>`).
-//
-// Both are field-driven: only DECLARED keys are projected, so a stray key in
-// the values record can never reach the wire. Neither performs an undeclared
-// normalization — trimming/casing is `CaptureFieldTransform`, applied once at
-// the input boundary. A blanket trim here would silently override a field that
-// declared `transform: none`.
-// ═══════════════════════════════════════════════════════════════════════════
-import { CaptureFieldType, toFieldList, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, type CaptureValues } from './field-spec';
-import { asString } from './value-format';
-
-type Schema = CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[];
-
-/** Project the declared fields to a flat `string` map (fields-only wire). */
-export function captureValuesToStringMap(
-  schema: Schema,
-  values: CaptureValues,
-): Record<string, string> {
-  const payload: Record<string, string> = {};
-  for (const field of toFieldList(schema)) {
-    payload[field.key] = asString(values[field.key]);
-  }
-  return payload;
-}
-
-/**
- * Project the declared fields, parsing `json` fields into structured values.
- *
- * A `json` field that does not parse is left as its raw string — validation is
- * `useSchemaValidation`'s job and it must run first; this projection does not
- * silently drop a value it cannot parse.
- */
-export function captureValuesToSubmitPayload(
-  schema: Schema,
-  values: CaptureValues,
-): CaptureValues {
-  const payload: CaptureValues = {};
-  for (const field of toFieldList(schema)) {
-    const raw = values[field.key];
-    if (field.type !== CaptureFieldType.Json) {
-      payload[field.key] = raw;
-      continue;
-    }
-    const text = asString(raw);
-    try {
-      payload[field.key] = JSON.parse(text);
-    } catch {
-      payload[field.key] = text;
-    }
-  }
-  return payload;
-}

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

@@ -1,186 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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(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

@@ -1,145 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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 { type 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 'safeParse' in input && typeof input.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]);
-}