@fogpipe/forma-core 0.15.0 → 0.17.0

package/dist/index.js

@@ -19,6 +19,7 @@ import {
   isDisplayField,
   isEnabled,
   isFieldVisible,
+  isMatrixField,
   isReadonly,
   isRequired,
   isSelectionField,
@@ -26,7 +27,7 @@ import {
   parseDecimalFormat,
   validate,
   validateSingleField
-} from "./chunk-COAUJ3IL.js";
+} from "./chunk-K7STGGGJ.js";
 import {
   evaluate,
   evaluateBoolean,
@@ -62,6 +63,7 @@ export {
   isDisplayField,
   isEnabled,
   isFieldVisible,
+  isMatrixField,
   isReadonly,
   isRequired,
   isSelectionField,

package/dist/types.d.ts

@@ -51,7 +51,7 @@ export interface JSONSchemaString extends JSONSchemaBase {
     minLength?: number;
     maxLength?: number;
     pattern?: string;
-    format?: "date" | "date-time" | "email" | "uri" | "uuid";
+    format?: "date" | "date-time" | "email" | "uri" | "uuid" | "phone";
     enum?: string[];
     default?: string;
 }
@@ -69,6 +69,7 @@ export interface JSONSchemaInteger extends JSONSchemaBase {
     minimum?: number;
     maximum?: number;
     multipleOf?: number;
+    enum?: number[];
     default?: number;
 }
 export interface JSONSchemaBoolean extends JSONSchemaBase {
@@ -94,7 +95,7 @@ export interface JSONSchemaEnum extends JSONSchemaBase {
 /**
  * Field type enumeration - maps to UI component types
  */
-export type FieldType = "text" | "password" | "number" | "integer" | "boolean" | "select" | "multiselect" | "date" | "datetime" | "email" | "url" | "textarea" | "array" | "object" | "computed" | "display";
+export type FieldType = "text" | "phone" | "password" | "number" | "integer" | "boolean" | "select" | "multiselect" | "date" | "datetime" | "email" | "url" | "textarea" | "array" | "object" | "computed" | "display" | "matrix";
 /**
  * Validation rule with FEEL expression
  */
@@ -167,7 +168,7 @@ export interface FieldDefinitionBase {
  * rather than inside variantConfig.
  */
 export interface AdornableFieldDefinition extends FieldDefinitionBase {
-    type: "text" | "email" | "url" | "password" | "textarea" | "number" | "integer";
+    type: "text" | "phone" | "email" | "url" | "password" | "textarea" | "number" | "integer";
     /** Text/symbol displayed before input (e.g., "$", "https://") */
     prefix?: string;
     /** Text/symbol displayed after input (e.g., "USD", "kg", "%") */
@@ -226,6 +227,45 @@ export interface DisplayFieldDefinition extends FieldDefinitionBase {
     /** Display format (e.g., "currency", "percent", "decimal(2)", or template "{value} Nm") */
     format?: string;
 }
+/**
+ * Row definition for matrix fields.
+ */
+export interface MatrixRow {
+    /** Unique row identifier (snake_case, used in data keys and FEEL expressions) */
+    id: string;
+    /** Display label for this row */
+    label: string;
+    /** When to show this row */
+    visibleWhen?: FEELExpression;
+}
+/**
+ * Column definition for matrix fields.
+ */
+export interface MatrixColumn {
+    /** Column value — use numbers for numeric scales, strings for categorical */
+    value: string | number;
+    /** Display label for this column */
+    label: string;
+}
+/**
+ * Matrix/grid fields — a 2D grid where rows are items/statements and
+ * columns are shared response options. Each row produces a single value
+ * (or multiple values in multi-select mode).
+ *
+ * Data shape (single-select): `{ speed: 4, quality: 5, support: 3 }`
+ * Data shape (multi-select): `{ comm: ["beginner", "intermediate"], lead: ["advanced"] }`
+ *
+ * FEEL access: `fieldId.rowId` (e.g., `service_rating.speed >= 4`)
+ */
+export interface MatrixFieldDefinition extends FieldDefinitionBase {
+    type: "matrix";
+    /** Row definitions (items/statements to rate) */
+    rows: MatrixRow[];
+    /** Column definitions (shared response options) */
+    columns: MatrixColumn[];
+    /** Allow multiple selections per row (default: false) */
+    multiSelect?: boolean;
+}
 /**
  * Computed fields (read-only calculated values).
  * Note: Computed field definitions live in Forma.computed, not Forma.fields.
@@ -250,7 +290,7 @@ export interface ComputedFieldDefinition extends FieldDefinitionBase {
  *   field.options; // SelectOption[] | undefined
  * }
  */
-export type FieldDefinition = AdornableFieldDefinition | SelectionFieldDefinition | SimpleFieldDefinition | ArrayFieldDefinition | ObjectFieldDefinition | DisplayFieldDefinition | ComputedFieldDefinition;
+export type FieldDefinition = AdornableFieldDefinition | SelectionFieldDefinition | SimpleFieldDefinition | ArrayFieldDefinition | ObjectFieldDefinition | DisplayFieldDefinition | ComputedFieldDefinition | MatrixFieldDefinition;
 /** Check if field supports prefix/suffix adorners */
 export declare function isAdornableField(field: FieldDefinition): field is AdornableFieldDefinition;
 /** Check if field is a display-only field (no data) */
@@ -259,6 +299,8 @@ export declare function isDisplayField(field: FieldDefinition): field is Display
 export declare function isSelectionField(field: FieldDefinition): field is SelectionFieldDefinition;
 /** Check if field is an array field */
 export declare function isArrayField(field: FieldDefinition): field is ArrayFieldDefinition;
+/** Check if field is a matrix field */
+export declare function isMatrixField(field: FieldDefinition): field is MatrixFieldDefinition;
 /** Check if field collects data (not display) */
 export declare function isDataField(field: FieldDefinition): boolean;
 /**

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fogpipe/forma-core",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Forma core runtime: Types and evaluation engines for dynamic forms with FEEL expressions",
   "type": "module",
   "main": "./dist/index.js",

package/src/__tests__/matrix.test.ts

@@ -0,0 +1,379 @@
+/**
+ * Tests for matrix field type - validation and visibility
+ */
+
+import { describe, it, expect } from "vitest";
+import { validate } from "../engine/validate.js";
+import { getVisibility } from "../engine/visibility.js";
+import type { Forma, MatrixFieldDefinition } from "../types.js";
+import { isMatrixField, isDataField } from "../types.js";
+
+/**
+ * Helper to create a minimal Forma spec with a matrix field
+ */
+function createMatrixSpec(options: {
+  fieldDef?: Partial<MatrixFieldDefinition>;
+  schemaProperties?: Record<string, unknown>;
+  required?: string[];
+  data?: Record<string, unknown>;
+}): Forma {
+  const {
+    fieldDef = {},
+    schemaProperties,
+    required = [],
+  } = options;
+
+  const matrixField: MatrixFieldDefinition = {
+    type: "matrix",
+    label: "Service Rating",
+    rows: [
+      { id: "speed", label: "Speed" },
+      { id: "quality", label: "Quality" },
+      { id: "support", label: "Support" },
+    ],
+    columns: [
+      { value: 1, label: "Poor" },
+      { value: 2, label: "Fair" },
+      { value: 3, label: "Good" },
+      { value: 4, label: "Very Good" },
+      { value: 5, label: "Excellent" },
+    ],
+    ...fieldDef,
+  };
+
+  const schema = schemaProperties ?? {
+    service_rating: {
+      type: "object",
+      properties: {
+        speed: { type: "integer", enum: [1, 2, 3, 4, 5] },
+        quality: { type: "integer", enum: [1, 2, 3, 4, 5] },
+        support: { type: "integer", enum: [1, 2, 3, 4, 5] },
+      },
+      required: ["speed", "quality", "support"],
+    },
+  };
+
+  return {
+    version: "1.0",
+    meta: { id: "test", title: "Test" },
+    schema: {
+      type: "object",
+      properties: schema as Forma["schema"]["properties"],
+      required: required.length > 0 ? required : undefined,
+    },
+    fields: {
+      service_rating: matrixField,
+    } as Forma["fields"],
+    fieldOrder: ["service_rating"],
+  };
+}
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+describe("type guards", () => {
+  it("isMatrixField should return true for matrix fields", () => {
+    const field: MatrixFieldDefinition = {
+      type: "matrix",
+      rows: [{ id: "a", label: "A" }],
+      columns: [{ value: 1, label: "1" }],
+    };
+    expect(isMatrixField(field)).toBe(true);
+  });
+
+  it("isMatrixField should return false for non-matrix fields", () => {
+    expect(isMatrixField({ type: "text" })).toBe(false);
+    expect(isMatrixField({ type: "select" })).toBe(false);
+    expect(isMatrixField({ type: "array" })).toBe(false);
+  });
+
+  it("isDataField should return true for matrix fields", () => {
+    const field: MatrixFieldDefinition = {
+      type: "matrix",
+      rows: [{ id: "a", label: "A" }],
+      columns: [{ value: 1, label: "1" }],
+    };
+    expect(isDataField(field)).toBe(true);
+  });
+});
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+describe("matrix validation", () => {
+  describe("valid data", () => {
+    it("should pass with valid numeric column values", () => {
+      const spec = createMatrixSpec({});
+      const data = {
+        service_rating: { speed: 4, quality: 5, support: 3 },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(true);
+      expect(result.errors).toHaveLength(0);
+    });
+
+    it("should pass with valid string column values", () => {
+      const spec = createMatrixSpec({
+        fieldDef: {
+          columns: [
+            { value: "agree", label: "Agree" },
+            { value: "disagree", label: "Disagree" },
+          ],
+        },
+        schemaProperties: {
+          service_rating: {
+            type: "object",
+            properties: {
+              speed: { type: "string", enum: ["agree", "disagree"] },
+              quality: { type: "string", enum: ["agree", "disagree"] },
+              support: { type: "string", enum: ["agree", "disagree"] },
+            },
+          },
+        },
+      });
+      const data = {
+        service_rating: { speed: "agree", quality: "disagree", support: "agree" },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(true);
+    });
+
+    it("should pass with partial answers when not required", () => {
+      const spec = createMatrixSpec({});
+      const data = {
+        service_rating: { speed: 4 },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(true);
+    });
+
+    it("should pass with null value when not required", () => {
+      const spec = createMatrixSpec({});
+      const result = validate({ service_rating: null }, spec);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("invalid data", () => {
+    it("should fail with invalid column values", () => {
+      const spec = createMatrixSpec({});
+      const data = {
+        service_rating: { speed: 99, quality: 5, support: 3 },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(1);
+      expect(result.errors[0].field).toBe("service_rating.speed");
+    });
+
+    it("should fail when required and empty", () => {
+      const spec = createMatrixSpec({ required: ["service_rating"] });
+      const result = validate({}, spec);
+      expect(result.valid).toBe(false);
+      expect(result.errors.some((e) => e.field === "service_rating")).toBe(true);
+    });
+
+    it("should fail when required and not all visible rows answered", () => {
+      const spec = createMatrixSpec({ required: ["service_rating"] });
+      const data = {
+        service_rating: { speed: 4 }, // quality and support missing
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(false);
+      expect(result.errors).toHaveLength(2);
+      expect(result.errors[0].field).toBe("service_rating.quality");
+      expect(result.errors[1].field).toBe("service_rating.support");
+    });
+
+    it("should pass when required and all visible rows answered", () => {
+      const spec = createMatrixSpec({ required: ["service_rating"] });
+      const data = {
+        service_rating: { speed: 4, quality: 5, support: 3 },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(true);
+    });
+  });
+
+  describe("multi-select mode", () => {
+    it("should pass with array values in multi-select mode", () => {
+      const spec = createMatrixSpec({
+        fieldDef: {
+          multiSelect: true,
+          columns: [
+            { value: "beginner", label: "Beginner" },
+            { value: "intermediate", label: "Intermediate" },
+            { value: "advanced", label: "Advanced" },
+          ],
+        },
+        schemaProperties: {
+          service_rating: {
+            type: "object",
+            properties: {
+              speed: {
+                type: "array",
+                items: { type: "string", enum: ["beginner", "intermediate", "advanced"] },
+              },
+              quality: {
+                type: "array",
+                items: { type: "string", enum: ["beginner", "intermediate", "advanced"] },
+              },
+              support: {
+                type: "array",
+                items: { type: "string", enum: ["beginner", "intermediate", "advanced"] },
+              },
+            },
+          },
+        },
+      });
+      const data = {
+        service_rating: {
+          speed: ["beginner", "intermediate"],
+          quality: ["advanced"],
+          support: [],
+        },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(true);
+    });
+
+    it("should fail with invalid values in multi-select array", () => {
+      const spec = createMatrixSpec({
+        fieldDef: {
+          multiSelect: true,
+          columns: [
+            { value: "beginner", label: "Beginner" },
+            { value: "advanced", label: "Advanced" },
+          ],
+        },
+        schemaProperties: {
+          service_rating: {
+            type: "object",
+            properties: {
+              speed: {
+                type: "array",
+                items: { type: "string", enum: ["beginner", "advanced"] },
+              },
+              quality: {
+                type: "array",
+                items: { type: "string", enum: ["beginner", "advanced"] },
+              },
+              support: {
+                type: "array",
+                items: { type: "string", enum: ["beginner", "advanced"] },
+              },
+            },
+          },
+        },
+      });
+      const data = {
+        service_rating: {
+          speed: ["beginner", "INVALID"],
+          quality: ["advanced"],
+          support: [],
+        },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].field).toBe("service_rating.speed");
+    });
+
+    it("should fail when multi-select row has non-array value", () => {
+      const spec = createMatrixSpec({
+        fieldDef: {
+          multiSelect: true,
+          columns: [
+            { value: "a", label: "A" },
+            { value: "b", label: "B" },
+          ],
+        },
+        schemaProperties: {
+          service_rating: {
+            type: "object",
+            properties: {
+              speed: { type: "array", items: { type: "string" } },
+              quality: { type: "array", items: { type: "string" } },
+              support: { type: "array", items: { type: "string" } },
+            },
+          },
+        },
+      });
+      const data = {
+        service_rating: {
+          speed: "a", // should be array
+          quality: ["a"],
+          support: ["b"],
+        },
+      };
+      const result = validate(data, spec);
+      expect(result.valid).toBe(false);
+      expect(result.errors[0].field).toBe("service_rating.speed");
+      expect(result.errors[0].message).toContain("list");
+    });
+  });
+});
+
+// ============================================================================
+// Visibility
+// ============================================================================
+
+describe("matrix visibility", () => {
+  it("should compute visibility for all matrix rows", () => {
+    const spec = createMatrixSpec({});
+    const visibility = getVisibility({}, spec);
+    expect(visibility["service_rating"]).toBe(true);
+    expect(visibility["service_rating.speed"]).toBe(true);
+    expect(visibility["service_rating.quality"]).toBe(true);
+    expect(visibility["service_rating.support"]).toBe(true);
+  });
+
+  it("should hide matrix field when visibleWhen evaluates to false", () => {
+    const spec = createMatrixSpec({
+      fieldDef: { visibleWhen: "show_rating = true" },
+    });
+    const visibility = getVisibility({ show_rating: false }, spec);
+    expect(visibility["service_rating"]).toBe(false);
+    // Row visibility should not be computed for hidden fields
+    expect(visibility["service_rating.speed"]).toBeUndefined();
+  });
+
+  it("should hide individual rows with visibleWhen", () => {
+    const spec = createMatrixSpec({
+      fieldDef: {
+        rows: [
+          { id: "speed", label: "Speed" },
+          { id: "quality", label: "Quality", visibleWhen: "show_quality = true" },
+          { id: "support", label: "Support" },
+        ],
+      },
+    });
+
+    const visibilityHidden = getVisibility({ show_quality: false }, spec);
+    expect(visibilityHidden["service_rating.speed"]).toBe(true);
+    expect(visibilityHidden["service_rating.quality"]).toBe(false);
+    expect(visibilityHidden["service_rating.support"]).toBe(true);
+
+    const visibilityShown = getVisibility({ show_quality: true }, spec);
+    expect(visibilityShown["service_rating.quality"]).toBe(true);
+  });
+
+  it("should skip hidden rows during validation", () => {
+    const spec = createMatrixSpec({
+      fieldDef: {
+        rows: [
+          { id: "speed", label: "Speed" },
+          { id: "quality", label: "Quality", visibleWhen: "show_quality = true" },
+          { id: "support", label: "Support" },
+        ],
+      },
+    });
+    // quality row is hidden but has an invalid value — should NOT produce error
+    const data = {
+      service_rating: { speed: 4, quality: 99, support: 3 },
+    };
+    const result = validate(data, spec, { onlyVisible: true });
+    expect(result.valid).toBe(true);
+  });
+});

package/src/engine/validate.ts

@@ -13,6 +13,7 @@ import type {
   Forma,
   FieldDefinition,
   ArrayFieldDefinition,
+  MatrixFieldDefinition,
   ValidationRule,
   EvaluationContext,
   ValidationResult,
@@ -199,6 +200,24 @@ function validateField(
     errors.push(...arrayErrors);
   }
 
+  // 5. Matrix validation
+  if (
+    fieldDef.type === "matrix" &&
+    value !== null &&
+    value !== undefined &&
+    typeof value === "object" &&
+    !Array.isArray(value)
+  ) {
+    const matrixErrors = validateMatrix(
+      path,
+      value as Record<string, unknown>,
+      fieldDef,
+      visibility,
+      required,
+    );
+    errors.push(...matrixErrors);
+  }
+
   return errors;
 }
 
@@ -687,6 +706,84 @@ function validateArrayItem(
   return errors;
 }
 
+// ============================================================================
+// Matrix Validation
+// ============================================================================
+
+/**
+ * Validate matrix field values against row/column definitions.
+ * Each row value must be a valid column value (or array of column values if multiSelect).
+ */
+function validateMatrix(
+  path: string,
+  value: Record<string, unknown>,
+  fieldDef: MatrixFieldDefinition,
+  visibility: Record<string, boolean>,
+  required: boolean,
+): FieldError[] {
+  const errors: FieldError[] = [];
+  const label = fieldDef.label ?? path;
+  const validColumnValues = new Set(fieldDef.columns.map((c) => c.value));
+
+  for (const row of fieldDef.rows) {
+    // Skip hidden rows
+    const rowPath = `${path}.${row.id}`;
+    if (visibility[rowPath] === false) {
+      continue;
+    }
+
+    const rowValue = value[row.id];
+
+    // Required: all visible rows must be answered
+    if (required && (rowValue === null || rowValue === undefined)) {
+      errors.push({
+        field: rowPath,
+        message: `${row.label} is required`,
+        severity: "error",
+      });
+      continue;
+    }
+
+    // Skip empty row values for non-required fields
+    if (rowValue === null || rowValue === undefined) {
+      continue;
+    }
+
+    if (fieldDef.multiSelect) {
+      // Multi-select: value should be an array of column values
+      if (!Array.isArray(rowValue)) {
+        errors.push({
+          field: rowPath,
+          message: `${row.label} must be a list of selections`,
+          severity: "error",
+        });
+        continue;
+      }
+      for (const item of rowValue) {
+        if (!validColumnValues.has(item as string | number)) {
+          errors.push({
+            field: rowPath,
+            message: `${row.label} contains an invalid selection`,
+            severity: "error",
+          });
+          break;
+        }
+      }
+    } else {
+      // Single-select: value should be a single column value
+      if (!validColumnValues.has(rowValue as string | number)) {
+        errors.push({
+          field: rowPath,
+          message: `${row.label} has an invalid value for ${label}`,
+          severity: "error",
+        });
+      }
+    }
+  }
+
+  return errors;
+}
+
 // ============================================================================
 // Single Field Validation
 // ============================================================================