@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,81 +0,0 @@
-// 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);
-  });
-});
-
-describe('media fields (image/file/audio)', () => {
-  const media: CaptureFieldSpec[] = [
-    { key: 'photo', label: 'Photo', type: CaptureFieldType.Image, required: true },
-    { key: 'attachment', label: 'Attachment', type: CaptureFieldType.File },
-    { key: 'memo', label: 'Voice memo', type: CaptureFieldType.Audio },
-  ];
-  const dataUrl = 'data:image/png;base64,AAAA';
-
-  it('accepts a captured data-URL for a required media field', () => {
-    expect(fieldSpecToZod(media).safeParse({ photo: dataUrl }).success).toBe(true);
-  });
-
-  it('rejects an empty required media field', () => {
-    expect(fieldSpecToZod(media).safeParse({ photo: '' }).success).toBe(false);
-    expect(fieldSpecToZod(media).safeParse({}).success).toBe(false);
-  });
-
-  it('allows omitted optional media fields', () => {
-    expect(fieldSpecToZod(media).safeParse({ photo: dataUrl }).success).toBe(true);
-  });
-})

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

@@ -1,174 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// 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();
-  }
-}
-
-/** True when `value` parses as JSON. Total — never throws. */
-export function isParsableJson(value: string): boolean {
-  try {
-    JSON.parse(value);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
-  let base: z.ZodTypeAny;
-  if (field.type === CaptureFieldType.Object) {
-    base = objectSchema(field.fields ?? []);
-  } else if (field.type === CaptureFieldType.Json) {
-    // A JSON blob is carried as TEXT and validated as parseable. `''` passes
-    // the shape check so an optional blank field stays valid; requiredness is
-    // enforced by the `.min(1)` below, not by the parse rule.
-    const text = field.required
-      ? z.string().min(1, { message: `${field.label} is required` })
-      : z.string();
-    base = text.refine((v) => v === '' || isParsableJson(v), {
-      message: `${field.label} must be valid JSON`,
-    });
-  } 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.Email ||
-        field.type === CaptureFieldType.Url ||
-        field.type === CaptureFieldType.User ||
-        field.type === CaptureFieldType.Reference ||
-        field.type === CaptureFieldType.Datetime ||
-        // Media fields carry a data-URL string; required = a capture was made.
-        field.type === CaptureFieldType.Image ||
-        field.type === CaptureFieldType.File ||
-        field.type === CaptureFieldType.Audio)
-    ) {
-      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-validate.ts

@@ -1,236 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// Total runtime validator for a `CaptureFieldSpec[]` arriving from the wire
-//
-// `fieldSpecToZod` validates the VALUES a form produces. This validates the
-// SCHEMA itself, for the case where the field list is not authored in TypeScript
-// but carried in an envelope (a Vista `form` surface payload, a biome
-// contribution, an agent-authored capture step).
-//
-// Contract: TOTAL and NEVER throws — it returns the narrowed specs or `null`,
-// exactly like the Vista payload validators, so a malformed schema degrades to
-// a visible typed fallback instead of a half-rendered form.
-// ═══════════════════════════════════════════════════════════════════════════
-import {
-  CaptureFieldTransform,
-  CaptureFieldType,
-  type CaptureFieldSpec,
-} from './field-spec';
-
-const FIELD_TYPES: ReadonlySet<string> = new Set(
-  Object.values(CaptureFieldType),
-);
-const TRANSFORMS: ReadonlySet<string> = new Set(
-  Object.values(CaptureFieldTransform),
-);
-
-type UnknownRecord = Readonly<Record<string, unknown>>;
-
-function asRecord(value: unknown): UnknownRecord | null {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? (value as UnknownRecord)
-    : null;
-}
-
-/** `undefined` passes through; a present non-string is a rejection (`null`). */
-function optionalString(value: unknown): string | undefined | null {
-  if (value === undefined) {
-    return undefined;
-  }
-  return typeof value === 'string' ? value : null;
-}
-
-/** `undefined` passes through; a present non-boolean is a rejection (`null`). */
-function optionalBoolean(value: unknown): boolean | undefined | null {
-  if (value === undefined) {
-    return undefined;
-  }
-  return typeof value === 'boolean' ? value : null;
-}
-
-/** `undefined` passes through; a present non-number is a rejection (`null`). */
-function optionalNumber(value: unknown): number | undefined | null {
-  if (value === undefined) {
-    return undefined;
-  }
-  return typeof value === 'number' && Number.isFinite(value) ? value : null;
-}
-
-/** Narrow ONE field spec. Returns `null` for anything malformed. */
-export function validateCaptureField(raw: unknown): CaptureFieldSpec | null {
-  const record = asRecord(raw);
-  if (record === null) {
-    return null;
-  }
-  if (typeof record.key !== 'string' || record.key.length === 0) {
-    return null;
-  }
-  if (typeof record.label !== 'string' || record.label.length === 0) {
-    return null;
-  }
-  if (typeof record.type !== 'string' || !FIELD_TYPES.has(record.type)) {
-    return null;
-  }
-
-  const required = optionalBoolean(record.required);
-  if (required === null) {
-    return null;
-  }
-  const isSecret = optionalBoolean(record.isSecret);
-  if (isSecret === null) {
-    return null;
-  }
-  const description = optionalString(record.description);
-  if (description === null) {
-    return null;
-  }
-  const placeholder = optionalString(record.placeholder);
-  if (placeholder === null) {
-    return null;
-  }
-  const section = optionalString(record.section);
-  if (section === null) {
-    return null;
-  }
-  const referenceEntity = optionalString(record.referenceEntity);
-  if (referenceEntity === null) {
-    return null;
-  }
-  const accept = optionalString(record.accept);
-  if (accept === null) {
-    return null;
-  }
-  const min = optionalNumber(record.min);
-  if (min === null) {
-    return null;
-  }
-  const max = optionalNumber(record.max);
-  if (max === null) {
-    return null;
-  }
-
-  let transform: CaptureFieldTransform | undefined;
-  if (record.transform !== undefined) {
-    if (
-      typeof record.transform !== 'string' ||
-      !TRANSFORMS.has(record.transform)
-    ) {
-      return null;
-    }
-    transform = record.transform as CaptureFieldTransform;
-  }
-
-  let enumValues: readonly string[] | undefined;
-  if (record.enumValues !== undefined) {
-    if (!Array.isArray(record.enumValues)) {
-      return null;
-    }
-    if (!record.enumValues.every((v) => typeof v === 'string')) {
-      return null;
-    }
-    enumValues = record.enumValues;
-  }
-
-  let capture: 'user' | 'environment' | undefined;
-  if (record.capture !== undefined) {
-    if (record.capture !== 'user' && record.capture !== 'environment') {
-      return null;
-    }
-    capture = record.capture;
-  }
-
-  let fields: readonly CaptureFieldSpec[] | undefined;
-  if (record.fields !== undefined) {
-    const nested = validateCaptureFields(record.fields);
-    if (nested === null) {
-      return null;
-    }
-    fields = nested;
-  }
-
-  const spec: {
-    key: string;
-    label: string;
-    type: CaptureFieldType;
-    required?: boolean;
-    isSecret?: boolean;
-    transform?: CaptureFieldTransform;
-    description?: string;
-    placeholder?: string;
-    section?: string;
-    referenceEntity?: string;
-    accept?: string;
-    capture?: 'user' | 'environment';
-    enumValues?: readonly string[];
-    fields?: readonly CaptureFieldSpec[];
-    min?: number;
-    max?: number;
-  } = {
-    key: record.key,
-    label: record.label,
-    type: record.type as CaptureFieldType,
-  };
-
-  if (required !== undefined) {
-    spec.required = required;
-  }
-  if (isSecret !== undefined) {
-    spec.isSecret = isSecret;
-  }
-  if (transform !== undefined) {
-    spec.transform = transform;
-  }
-  if (description !== undefined) {
-    spec.description = description;
-  }
-  if (placeholder !== undefined) {
-    spec.placeholder = placeholder;
-  }
-  if (section !== undefined) {
-    spec.section = section;
-  }
-  if (referenceEntity !== undefined) {
-    spec.referenceEntity = referenceEntity;
-  }
-  if (accept !== undefined) {
-    spec.accept = accept;
-  }
-  if (capture !== undefined) {
-    spec.capture = capture;
-  }
-  if (enumValues !== undefined) {
-    spec.enumValues = enumValues;
-  }
-  if (fields !== undefined) {
-    spec.fields = fields;
-  }
-  if (min !== undefined) {
-    spec.min = min;
-  }
-  if (max !== undefined) {
-    spec.max = max;
-  }
-
-  return spec;
-}
-
-/**
- * Narrow a whole field list. An EMPTY array is valid and narrows to `[]` — an
- * empty schema is a real, meaningful state (the server is the authority on
- * whether a form with no fields may be submitted), not a validation failure.
- */
-export function validateCaptureFields(
-  raw: unknown,
-): readonly CaptureFieldSpec[] | null {
-  if (!Array.isArray(raw)) {
-    return null;
-  }
-  const out: CaptureFieldSpec[] = [];
-  for (const entry of raw) {
-    const spec = validateCaptureField(entry);
-    if (spec === null) {
-      return null;
-    }
-    out.push(spec);
-  }
-  return out;
-}

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

@@ -1,49 +0,0 @@
-// 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']);
-  });
-});