@xemahq/ui-kernel 0.11.1 → 0.12.0

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

@@ -1,274 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// Guided-capture field spec — the ONE schema shape the capture kit consumes
-//
-// This is the frontend-agnostic superset of app-forge-web's `AppField`. The
-// wire/definition layer (app-forge-api, its renderer's `AppFieldType`) owns 10
-// closed field types; this kit mirrors those 10 verbatim (same string values,
-// so an `AppField` is structurally assignable to `CaptureFieldSpec`) and ADDS
-// two structural composites — `object` and `list` — plus optional `section`
-// grouping. A workbench therefore extends ONE renderer (`<SchemaForm>`) instead
-// of the three parallel schema→form implementations that exist today.
-//
-// Value shape produced/consumed:
-//   scalar field  → string | number | boolean            (per type)
-//   object field  → Record<string, unknown>              (nested record)
-//   list field    → unknown[]                            (array of item records)
-// ═══════════════════════════════════════════════════════════════════════════
-
-/**
- * Closed set of capture field types. The first ten are value-identical to
- * app-forge-web's `AppFieldType` (`string`/`text`/`number`/`decimal`/`boolean`/
- * `date`/`datetime`/`enum`/`reference`/`user`) so definitions authored for the
- * App Platform pass straight through. `object`/`list` are the structural
- * composites this kit adds for nested + repeatable capture.
- *
- * The string VALUES are the contract — keep the first ten identical to
- * `AppFieldType` in `@xemahq/kernel-contracts/app-definition` (the single
- * source of truth for App Platform field types). Adding a value here that
- * `AppFieldType` lacks is fine (superset); changing an existing shared value is
- * not. This kit can't import the enum (it adds members), so the shared values
- * are mirrored deliberately.
- */
-export enum CaptureFieldType {
-  String = 'string',
-  Text = 'text',
-  Number = 'number',
-  Decimal = 'decimal',
-  Boolean = 'boolean',
-  Date = 'date',
-  Datetime = 'datetime',
-  Enum = 'enum',
-  Reference = 'reference',
-  User = 'user',
-  Object = 'object',
-  List = 'list',
-  // ── Media capture (field-capture kit) ──
-  // Value is a data-URL string (base64), so it stays JSON-serializable and
-  // flows unchanged through the record model + the offline outbox. `Image`
-  // opens the device camera on mobile (`capture`), `File` attaches any file,
-  // `Audio` records a voice memo via MediaRecorder.
-  Image = 'image',
-  File = 'file',
-  Audio = 'audio',
-  // ── Scalar text refinements (absorbed from the connector credential form) ──
-  // These change only the NATIVE INPUT TYPE (keyboard + browser affordances);
-  // the value is a plain string. `Json` additionally renders as a mono textarea
-  // and is validated as parseable JSON.
-  Email = 'email',
-  Url = 'url',
-  Json = 'json',
-}
-
-/**
- * Normalization applied to a captured STRING value at the input boundary.
- *
- * Value-identical in meaning to the connector `CredentialFieldTransform`
- * (`NONE`/`UPPERCASE`/`LOWERCASE`/`TRIM`) but named in this kit's lowercase
- * vocabulary, because the capture kit is domain-agnostic and must not import a
- * connector contract. The connector→capture adapter lives at the consuming
- * seam, not here.
- *
- * This is the ONLY normalization the kit performs. There is deliberately no
- * blanket trim on submit: an undeclared transform would silently override a
- * field that declared {@link CaptureFieldTransform.None}.
- */
-export enum CaptureFieldTransform {
-  None = 'none',
-  Uppercase = 'uppercase',
-  Lowercase = 'lowercase',
-  Trim = 'trim',
-}
-
-/** Apply a declared transform to a string value. Total; absent = unchanged. */
-export function applyCaptureTransform(
-  value: string,
-  transform: CaptureFieldTransform | `${CaptureFieldTransform}` | undefined,
-): string {
-  switch (transform) {
-    case CaptureFieldTransform.Uppercase:
-      return value.toUpperCase();
-    case CaptureFieldTransform.Lowercase:
-      return value.toLowerCase();
-    case CaptureFieldTransform.Trim:
-      return value.trim();
-    case CaptureFieldTransform.None:
-    case undefined:
-      return value;
-    default:
-      return value;
-  }
-}
-
-/**
- * A single capture field. Structural superset of app-forge's `AppField`:
- * `key`/`label`/`type`/`required`/`enumValues`/`referenceEntity` carry the
- * exact same meaning, so `AppField[]` can be handed to this kit unchanged. The
- * extra props are additive and all optional.
- *
- * `type` accepts the {@link CaptureFieldType} enum OR its bare string value, so
- * `{ type: 'string' }` (app-forge shape) and `{ type: CaptureFieldType.String }`
- * both type-check.
- */
-export interface CaptureFieldSpec {
-  readonly key: string;
-  readonly label: string;
-  readonly type: CaptureFieldType | `${CaptureFieldType}`;
-  readonly required?: boolean;
-  /** Helper text rendered under the label. */
-  readonly description?: string;
-  /** Placeholder for text-like inputs. */
-  readonly placeholder?: string;
-  /** Only for `enum` — the allowed values. */
-  readonly enumValues?: readonly string[];
-  /** Only for `reference` — key of the target entity (opaque to this kit). */
-  readonly referenceEntity?: string;
-  /** Only for `object`/`list` — the nested item shape. */
-  readonly fields?: readonly CaptureFieldSpec[];
-  /** `number`/`decimal`: numeric bounds. `list`: min/max item count. */
-  readonly min?: number;
-  readonly max?: number;
-  /**
-   * `image`/`file`/`audio`: the `accept` filter for the file picker (e.g.
-   * `image/*`, `application/pdf`). Defaults per type when omitted.
-   */
-  readonly accept?: string;
-  /**
-   * `image`/`file`: the HTML `capture` hint — `environment` opens the rear
-   * camera, `user` the front camera. Omitted = a normal file picker.
-   */
-  readonly capture?: 'user' | 'environment';
-  /**
-   * Optional section grouping key for FLAT `CaptureFieldSpec[]` schemas. When a
-   * schema is expressed as {@link CaptureSection}[] this is ignored (grouping is
-   * explicit). See {@link groupFieldsBySection}.
-   */
-  readonly section?: string;
-  /**
-   * DECLARED write-only secrecy. When true the input is masked, never
-   * pre-filled from a read, and never echoed back by any read path.
-   *
-   * Secrecy is DECLARED, never inferred from {@link type}: a plain-`string`
-   * field can be a secret and a `password`-shaped field can be public. The
-   * renderer reads this flag and nothing else — do not re-introduce a
-   * `type === password` inference.
-   */
-  readonly isSecret?: boolean;
-  /**
-   * Declared normalization applied to the string value at the input boundary.
-   * Absent = {@link CaptureFieldTransform.None}.
-   */
-  readonly transform?: CaptureFieldTransform | `${CaptureFieldTransform}`;
-}
-
-/** A titled group of fields — the explicit sectioned schema shape. */
-export interface CaptureSection {
-  readonly key: string;
-  readonly title: string;
-  readonly description?: string;
-  readonly fields: readonly CaptureFieldSpec[];
-}
-
-/**
- * A capture schema is EITHER a flat field list OR a list of titled sections.
- * `<SchemaForm>`, `useSchemaValidation`, and `<DocumentPreview>` all accept
- * either face.
- */
-export type CaptureSchema =
-  | {
-      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>;
-
-/** True if `x` is the sectioned face of a schema. */
-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)
-  );
-}
-
-/**
- * Normalize any accepted schema face to the flat list of TOP-LEVEL fields.
- * (Nested `object`/`list` item fields are NOT flattened — they belong to their
- * parent's value.) Accepts a `CaptureFieldSpec[]`, a `CaptureSection[]`, or a
- * `CaptureSchema`.
- */
-export function toFieldList(
-  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))
-    ) {
-      return (arr as readonly CaptureSection[]).flatMap((s) => s.fields);
-    }
-    return arr as readonly CaptureFieldSpec[];
-  }
-  if (isSectioned(schema)) {
-    return schema.sections.flatMap((s) => s.fields);
-  }
-  return (schema as { fields: readonly CaptureFieldSpec[] }).fields;
-}
-
-/**
- * Resolve any accepted schema face to `CaptureSection[]`. A flat field list
- * collapses to a single untitled section (or is split by each field's
- * `section` key when present).
- */
-export function toSections(
-  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)
-  ) {
-    return schema as readonly CaptureSection[];
-  }
-  if (!Array.isArray(schema) && isSectioned(schema)) {
-    return schema.sections;
-  }
-  return groupFieldsBySection(toFieldList(schema), fallbackTitle);
-}
-
-/** Split a flat field list into sections by each field's `section` key. */
-export function groupFieldsBySection(
-  fields: readonly CaptureFieldSpec[],
-  fallbackTitle = '',
-): readonly CaptureSection[] {
-  const order: string[] = [];
-  const byKey = new Map<string, CaptureFieldSpec[]>();
-  for (const f of fields) {
-    const key = f.section ?? '';
-    if (!byKey.has(key)) {
-      byKey.set(key, []);
-      order.push(key);
-    }
-    byKey.get(key)!.push(f);
-  }
-  return order.map((key) => ({
-    key: key || '_',
-    title: key || fallbackTitle,
-    fields: byKey.get(key)!,
-  }));
-}

package/src/ui/capture/index.ts

@@ -1,51 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// @xemahq/ui-kernel — guided-capture UX kit (B5)
-//
-// Headless engines + presentation-thin primitives for schema-driven, guided
-// data capture: a wizard state machine, live client-side validation, AI/context
-// pre-fill, a single consolidated schema→form renderer, and a review-step
-// document preview. Consolidates the three parallel schema→form implementations
-// so a workbench extends ONE renderer.
-// ═══════════════════════════════════════════════════════════════════════════
-
-// ── field-spec model (aligned superset of app-forge's AppFieldType) ──
-export {
-  CaptureFieldType,
-  CaptureFieldTransform,
-  applyCaptureTransform,
-  isSectioned,
-  toFieldList,
-  toSections,
-  groupFieldsBySection,
-  type CaptureFieldSpec,
-  type CaptureSection,
-  type CaptureSchema,
-  type CaptureValues,
-} from './field-spec';
-
-// ── total runtime validator for a wire-carried schema ──
-export { validateCaptureField, validateCaptureFields } from './field-spec-validate';
-
-// ── schema → zod adapter ──
-export { fieldSpecToZod, isEmptyValue, isParsableJson } from './field-spec-to-zod';
-
-// ── values → wire payload ──
-export { captureValuesToStringMap, captureValuesToSubmitPayload } from './submit-values';
-
-// ── validation + "missing info" ──
-export { useSchemaValidation, type SchemaValidationResult } from './use-schema-validation';
-
-// ── pre-fill ──
-export { usePrefill, type UsePrefillOptions, type UsePrefillResult } from './use-prefill';
-
-// ── wizard engine + shell ──
-export { useWizard, type WizardApi, type WizardStepDef, type UseWizardOptions } from './use-wizard';
-export { Wizard, WizardStep, type WizardProps, type WizardStepProps } from './wizard';
-
-// ── consolidated schema form ──
-export { SchemaForm, type SchemaFormProps } from './schema-form';
-export { SchemaFieldInput, type SchemaFieldInputProps, type RenderReference } from './schema-field-input';
-export { asString, formatScalar } from './value-format';
-
-// ── review-step document preview ──
-export { DocumentPreview, type DocumentPreviewProps } from './document-preview';