@xemahq/ui-kernel 0.9.2 → 0.11.0

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

@@ -8,35 +8,66 @@
 // ═══════════════════════════════════════════════════════════════════════════
 import { z } from 'zod';
 
-import { CaptureFieldType, type CaptureFieldSpec, type CaptureSchema, type CaptureSection, toFieldList } from './field-spec';
+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);
+  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}` });
+      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` });
+      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();
+      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` });
+      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` });
+      return z
+        .string()
+        .min(1, { message: `${field.label} must be a date/time` });
     // string / text / user / reference — plain text.
     default:
       return z.string();
@@ -69,8 +100,16 @@ function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
     });
   } 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)` });
+    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);
@@ -88,7 +127,9 @@ function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
         field.type === CaptureFieldType.File ||
         field.type === CaptureFieldType.Audio)
     ) {
-      base = (base as z.ZodString).min(1, { message: `${field.label} is required` });
+      base = (base as z.ZodString).min(1, {
+        message: `${field.label} is required`,
+      });
     }
   }
 
@@ -101,9 +142,13 @@ function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
   return base;
 }
 
-function objectSchema(fields: readonly CaptureFieldSpec[]): z.ZodObject<z.ZodRawShape> {
+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);
+  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);
 }
@@ -120,7 +165,10 @@ function objectSchema(fields: readonly CaptureFieldSpec[]): z.ZodObject<z.ZodRaw
  * schema.safeParse({ title: 'Hi', tags: [{ name: 'a' }] }); // { success: true }
  */
 export function fieldSpecToZod(
-  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+  schema:
+    | CaptureSchema
+    | readonly CaptureFieldSpec[]
+    | readonly CaptureSection[],
 ): z.ZodObject<z.ZodRawShape> {
   return objectSchema(toFieldList(schema));
 }

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

@@ -10,10 +10,18 @@
 // 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));
+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>>;
 
@@ -25,72 +33,117 @@ function asRecord(value: unknown): 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;
+  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;
+  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;
+  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;
+  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;
+  if (required === null) {
+    return null;
+  }
   const isSecret = optionalBoolean(record.isSecret);
-  if (isSecret === null) return null;
+  if (isSecret === null) {
+    return null;
+  }
   const description = optionalString(record.description);
-  if (description === null) return null;
+  if (description === null) {
+    return null;
+  }
   const placeholder = optionalString(record.placeholder);
-  if (placeholder === null) return null;
+  if (placeholder === null) {
+    return null;
+  }
   const section = optionalString(record.section);
-  if (section === null) return null;
+  if (section === null) {
+    return null;
+  }
   const referenceEntity = optionalString(record.referenceEntity);
-  if (referenceEntity === null) return null;
+  if (referenceEntity === null) {
+    return null;
+  }
   const accept = optionalString(record.accept);
-  if (accept === null) return null;
+  if (accept === null) {
+    return null;
+  }
   const min = optionalNumber(record.min);
-  if (min === null) return null;
+  if (min === null) {
+    return null;
+  }
   const max = optionalNumber(record.max);
-  if (max === null) return null;
+  if (max === null) {
+    return null;
+  }
 
   let transform: CaptureFieldTransform | undefined;
   if (record.transform !== undefined) {
-    if (typeof record.transform !== 'string' || !TRANSFORMS.has(record.transform)) return null;
+    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;
+    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;
+    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;
+    if (nested === null) {
+      return null;
+    }
     fields = nested;
   }
 
@@ -111,21 +164,51 @@ export function validateCaptureField(raw: unknown): CaptureFieldSpec | null {
     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;
+  } = {
+    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;
 }
@@ -135,12 +218,18 @@ export function validateCaptureField(raw: unknown): CaptureFieldSpec | null {
  * 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;
+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;
+    if (spec === null) {
+      return null;
+    }
     out.push(spec);
   }
   return out;

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

@@ -34,8 +34,8 @@ 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']);
+    expect(grouped[0]?.fields.map((f) => f.key)).toEqual(['a', 'b']);
+    expect(grouped[1]?.fields.map((f) => f.key)).toEqual(['c']);
   });
 });
 

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

@@ -174,8 +174,14 @@ export interface CaptureSection {
  * either face.
  */
 export type CaptureSchema =
-  | { readonly fields: readonly CaptureFieldSpec[]; readonly sections?: undefined }
-  | { readonly sections: readonly CaptureSection[]; readonly fields?: undefined };
+  | {
+      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>;
@@ -184,7 +190,11 @@ export type CaptureValues = Record<string, unknown>;
 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);
+  return (
+    !Array.isArray(x) &&
+    'sections' in (x as object) &&
+    Array.isArray((x as { sections?: unknown }).sections)
+  );
 }
 
 /**
@@ -194,17 +204,25 @@ export function isSectioned(
  * `CaptureSchema`.
  */
 export function toFieldList(
-  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+  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))) {
+    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);
+  if (isSectioned(schema)) {
+    return schema.sections.flatMap((s) => s.fields);
+  }
   return (schema as { fields: readonly CaptureFieldSpec[] }).fields;
 }
 
@@ -214,13 +232,22 @@ export function toFieldList(
  * `section` key when present).
  */
 export function toSections(
-  schema: CaptureSchema | readonly CaptureFieldSpec[] | readonly CaptureSection[],
+  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)) {
+  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;
+  if (!Array.isArray(schema) && isSectioned(schema)) {
+    return schema.sections;
+  }
   return groupFieldsBySection(toFieldList(schema), fallbackTitle);
 }
 
@@ -239,5 +266,9 @@ export function groupFieldsBySection(
     }
     byKey.get(key)!.push(f);
   }
-  return order.map((key) => ({ key: key || '_', title: key || fallbackTitle, fields: byKey.get(key)! }));
+  return order.map((key) => ({
+    key: key || '_',
+    title: key || fallbackTitle,
+    fields: byKey.get(key)!,
+  }));
 }