@fogpipe/forma-core 0.10.2 → 0.10.4

package/src/__tests__/format.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect } from "vitest";
+import {
+  formatValue,
+  isValidFormat,
+  parseDecimalFormat,
+  SUPPORTED_FORMATS,
+  DECIMAL_FORMAT_PATTERN,
+} from "../format/index.js";
+
+describe("format module", () => {
+  describe("constants", () => {
+    it("SUPPORTED_FORMATS includes expected formats", () => {
+      expect(SUPPORTED_FORMATS).toContain("currency");
+      expect(SUPPORTED_FORMATS).toContain("percent");
+      expect(SUPPORTED_FORMATS).toContain("date");
+      expect(SUPPORTED_FORMATS).toContain("datetime");
+    });
+
+    it("DECIMAL_FORMAT_PATTERN matches valid decimal formats", () => {
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal(0)")).toBe(true);
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal(1)")).toBe(true);
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal(2)")).toBe(true);
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal(10)")).toBe(true);
+    });
+
+    it("DECIMAL_FORMAT_PATTERN rejects invalid formats", () => {
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal")).toBe(false);
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal()")).toBe(false);
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal(-1)")).toBe(false);
+      expect(DECIMAL_FORMAT_PATTERN.test("decimal(a)")).toBe(false);
+      expect(DECIMAL_FORMAT_PATTERN.test("DECIMAL(2)")).toBe(false);
+    });
+  });
+
+  describe("isValidFormat", () => {
+    it("returns true for supported formats", () => {
+      expect(isValidFormat("currency")).toBe(true);
+      expect(isValidFormat("percent")).toBe(true);
+      expect(isValidFormat("date")).toBe(true);
+      expect(isValidFormat("datetime")).toBe(true);
+    });
+
+    it("returns true for valid decimal formats", () => {
+      expect(isValidFormat("decimal(0)")).toBe(true);
+      expect(isValidFormat("decimal(2)")).toBe(true);
+      expect(isValidFormat("decimal(5)")).toBe(true);
+    });
+
+    it("returns false for invalid formats", () => {
+      expect(isValidFormat("invalid")).toBe(false);
+      expect(isValidFormat("decimal")).toBe(false);
+      expect(isValidFormat("decimal()")).toBe(false);
+      expect(isValidFormat("CURRENCY")).toBe(false);
+    });
+  });
+
+  describe("parseDecimalFormat", () => {
+    it("extracts decimal places from valid format", () => {
+      expect(parseDecimalFormat("decimal(0)")).toBe(0);
+      expect(parseDecimalFormat("decimal(1)")).toBe(1);
+      expect(parseDecimalFormat("decimal(2)")).toBe(2);
+      expect(parseDecimalFormat("decimal(10)")).toBe(10);
+    });
+
+    it("returns null for non-decimal formats", () => {
+      expect(parseDecimalFormat("currency")).toBeNull();
+      expect(parseDecimalFormat("percent")).toBeNull();
+      expect(parseDecimalFormat("invalid")).toBeNull();
+    });
+  });
+
+  describe("formatValue", () => {
+    describe("no format specified", () => {
+      it("converts values to strings", () => {
+        expect(formatValue(123)).toBe("123");
+        expect(formatValue("hello")).toBe("hello");
+        expect(formatValue(true)).toBe("true");
+        expect(formatValue(false)).toBe("false");
+      });
+
+      it("handles null and undefined", () => {
+        expect(formatValue(null)).toBe("null");
+        expect(formatValue(undefined)).toBe("undefined");
+      });
+    });
+
+    describe("decimal format", () => {
+      it("formats numbers with specified decimal places", () => {
+        expect(formatValue(123.456, "decimal(0)")).toBe("123");
+        expect(formatValue(123.456, "decimal(1)")).toBe("123.5");
+        expect(formatValue(123.456, "decimal(2)")).toBe("123.46");
+        expect(formatValue(123.456, "decimal(5)")).toBe("123.45600");
+      });
+
+      it("pads with zeros when needed", () => {
+        expect(formatValue(123, "decimal(2)")).toBe("123.00");
+      });
+
+      it("handles negative numbers", () => {
+        expect(formatValue(-123.456, "decimal(2)")).toBe("-123.46");
+      });
+
+      it("falls back to string for non-numbers", () => {
+        expect(formatValue("not a number", "decimal(2)")).toBe("not a number");
+      });
+    });
+
+    describe("currency format", () => {
+      it("formats numbers as USD currency by default", () => {
+        const result = formatValue(1234.56, "currency");
+        expect(result).toBe("$1,234.56");
+      });
+
+      it("formats zero", () => {
+        expect(formatValue(0, "currency")).toBe("$0.00");
+      });
+
+      it("formats negative numbers", () => {
+        expect(formatValue(-100, "currency")).toBe("-$100.00");
+      });
+
+      it("respects currency option", () => {
+        const result = formatValue(1234.56, "currency", { currency: "EUR" });
+        // EUR formatting varies by locale
+        expect(result).toContain("1,234.56");
+      });
+
+      it("falls back to string for non-numbers", () => {
+        expect(formatValue("not a number", "currency")).toBe("not a number");
+      });
+    });
+
+    describe("percent format", () => {
+      it("formats numbers as percentages", () => {
+        expect(formatValue(0.5, "percent")).toBe("50%");
+        expect(formatValue(1, "percent")).toBe("100%");
+        expect(formatValue(0.156, "percent")).toBe("15.6%");
+      });
+
+      it("handles edge cases", () => {
+        expect(formatValue(0, "percent")).toBe("0%");
+        expect(formatValue(-0.5, "percent")).toBe("-50%");
+      });
+
+      it("falls back to string for non-numbers", () => {
+        expect(formatValue("not a number", "percent")).toBe("not a number");
+      });
+    });
+
+    describe("date format", () => {
+      it("formats Date objects", () => {
+        const date = new Date("2024-03-15T10:30:00Z");
+        const result = formatValue(date, "date");
+        // Contains month, day, year in some format
+        expect(result).toMatch(/3\/15\/2024|15\/3\/2024/);
+      });
+
+      it("formats date strings", () => {
+        const result = formatValue("2024-03-15", "date");
+        expect(result).toMatch(/3\/15\/2024|15\/3\/2024|3\/14\/2024|14\/3\/2024/);
+      });
+
+      it("falls back to string for invalid dates", () => {
+        expect(formatValue("not a date", "date")).toBe("not a date");
+      });
+    });
+
+    describe("datetime format", () => {
+      it("formats Date objects with time", () => {
+        const date = new Date("2024-03-15T10:30:00Z");
+        const result = formatValue(date, "datetime");
+        // Contains both date and time components
+        expect(result).toMatch(/\d{1,2}\/\d{1,2}\/\d{2,4}/);
+        expect(result).toMatch(/\d{1,2}:\d{2}/);
+      });
+
+      it("falls back to string for invalid dates", () => {
+        expect(formatValue("not a date", "datetime")).toBe("not a date");
+      });
+    });
+
+    describe("unknown format", () => {
+      it("falls back to string conversion", () => {
+        expect(formatValue(123, "unknown")).toBe("123");
+        expect(formatValue("hello", "invalid")).toBe("hello");
+      });
+    });
+
+    describe("nullDisplay option", () => {
+      it("uses nullDisplay for null values", () => {
+        expect(formatValue(null, undefined, { nullDisplay: "—" })).toBe("—");
+        expect(formatValue(null, "decimal(2)", { nullDisplay: "N/A" })).toBe("N/A");
+      });
+
+      it("uses nullDisplay for undefined values", () => {
+        expect(formatValue(undefined, undefined, { nullDisplay: "—" })).toBe("—");
+        expect(formatValue(undefined, "currency", { nullDisplay: "-" })).toBe("-");
+      });
+
+      it("does not affect non-null values", () => {
+        expect(formatValue(123, "decimal(2)", { nullDisplay: "—" })).toBe("123.00");
+        expect(formatValue(0, "decimal(2)", { nullDisplay: "—" })).toBe("0.00");
+      });
+    });
+
+    describe("locale option", () => {
+      it("respects locale for currency formatting", () => {
+        const result = formatValue(1234.56, "currency", { locale: "de-DE", currency: "EUR" });
+        // German locale uses comma for decimals
+        expect(result).toContain("1.234,56");
+      });
+
+      it("respects locale for percent formatting", () => {
+        const result = formatValue(0.5, "percent", { locale: "de-DE" });
+        // German locale uses comma for decimals
+        expect(result).toContain("50");
+        expect(result).toContain("%");
+      });
+    });
+
+    describe("edge cases", () => {
+      it("handles NaN", () => {
+        expect(formatValue(NaN, "decimal(2)")).toBe("NaN");
+      });
+
+      it("handles Infinity", () => {
+        expect(formatValue(Infinity, "decimal(2)")).toBe("Infinity");
+        expect(formatValue(-Infinity, "decimal(2)")).toBe("-Infinity");
+      });
+
+      it("handles very large numbers", () => {
+        const result = formatValue(1e15, "currency");
+        expect(result).toContain("$");
+      });
+
+      it("handles very small numbers", () => {
+        expect(formatValue(0.0001, "decimal(4)")).toBe("0.0001");
+      });
+    });
+  });
+});

package/src/__tests__/validate.test.ts

@@ -275,4 +275,349 @@ describe("validate", () => {
       expect(result.errors[0].message).toBe("Name must be at least 2 characters");
     });
   });
+
+  // ============================================================================
+  // Array validation
+  // ============================================================================
+
+  describe("array validation", () => {
+    describe("minItems/maxItems from schema", () => {
+      it("should validate minItems from schema when fieldDef does not specify it", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              items: {
+                type: "array",
+                items: { type: "string" },
+                minItems: 2,
+              },
+            },
+          },
+          fields: {
+            items: { label: "Items", type: "array" },
+          },
+          fieldOrder: ["items"],
+        };
+
+        // Valid - has minimum 2 items
+        expect(validate({ items: ["a", "b"] }, spec).valid).toBe(true);
+        expect(validate({ items: ["a", "b", "c"] }, spec).valid).toBe(true);
+
+        // Invalid - less than minItems
+        const result = validate({ items: ["a"] }, spec);
+        expect(result.valid).toBe(false);
+        expect(result.errors[0].field).toBe("items");
+        expect(result.errors[0].message).toBe("Items must have at least 2 items");
+      });
+
+      it("should validate maxItems from schema when fieldDef does not specify it", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              tags: {
+                type: "array",
+                items: { type: "string" },
+                maxItems: 3,
+              },
+            },
+          },
+          fields: {
+            tags: { label: "Tags", type: "array" },
+          },
+          fieldOrder: ["tags"],
+        };
+
+        // Valid - has maximum 3 items
+        expect(validate({ tags: ["a", "b", "c"] }, spec).valid).toBe(true);
+        expect(validate({ tags: ["a"] }, spec).valid).toBe(true);
+
+        // Invalid - more than maxItems
+        const result = validate({ tags: ["a", "b", "c", "d"] }, spec);
+        expect(result.valid).toBe(false);
+        expect(result.errors[0].field).toBe("tags");
+        expect(result.errors[0].message).toBe("Tags must have no more than 3 items");
+      });
+
+      it("should allow fieldDef.minItems to override schema.minItems", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              items: {
+                type: "array",
+                items: { type: "string" },
+                minItems: 5, // schema says 5
+              },
+            },
+          },
+          fields: {
+            items: {
+              label: "Items",
+              type: "array",
+              minItems: 2, // fieldDef overrides to 2
+            },
+          },
+          fieldOrder: ["items"],
+        };
+
+        // fieldDef.minItems (2) should take precedence over schema.minItems (5)
+        expect(validate({ items: ["a", "b"] }, spec).valid).toBe(true);
+        expect(validate({ items: ["a"] }, spec).valid).toBe(false);
+      });
+    });
+
+    describe("array item validation from schema", () => {
+      it("should validate array item type constraints from schema", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              scores: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    score: { type: "number", minimum: 0, maximum: 100 },
+                  },
+                  required: ["name", "score"],
+                },
+              },
+            },
+          },
+          fields: {
+            scores: { label: "Scores", type: "array" },
+          },
+          fieldOrder: ["scores"],
+        };
+
+        // Valid data
+        const validResult = validate(
+          {
+            scores: [
+              { name: "Alice", score: 95 },
+              { name: "Bob", score: 87 },
+            ],
+          },
+          spec
+        );
+        expect(validResult.valid).toBe(true);
+
+        // Invalid - score above maximum
+        const maxResult = validate(
+          {
+            scores: [
+              { name: "Alice", score: 105 },
+              { name: "Bob", score: 87 },
+            ],
+          },
+          spec
+        );
+        expect(maxResult.valid).toBe(false);
+        expect(maxResult.errors[0].field).toBe("scores[0].score");
+        expect(maxResult.errors[0].message).toContain("no more than 100");
+
+        // Invalid - score below minimum
+        const minResult = validate(
+          {
+            scores: [
+              { name: "Alice", score: -5 },
+              { name: "Bob", score: 87 },
+            ],
+          },
+          spec
+        );
+        expect(minResult.valid).toBe(false);
+        expect(minResult.errors[0].field).toBe("scores[0].score");
+        expect(minResult.errors[0].message).toContain("at least 0");
+      });
+
+      it("should validate required fields in array items from schema", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              people: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    name: { type: "string" },
+                    age: { type: "integer" },
+                  },
+                  required: ["name"],
+                },
+              },
+            },
+          },
+          fields: {
+            people: { label: "People", type: "array" },
+          },
+          fieldOrder: ["people"],
+        };
+
+        // Valid - name is present (age is optional)
+        expect(
+          validate({ people: [{ name: "Alice" }, { name: "Bob", age: 30 }] }, spec).valid
+        ).toBe(true);
+
+        // Invalid - missing required name
+        const result = validate({ people: [{ age: 25 }] }, spec);
+        expect(result.valid).toBe(false);
+        expect(result.errors[0].field).toBe("people[0].name");
+        expect(result.errors[0].message).toContain("required");
+      });
+
+      it("should validate nested string constraints in array items", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              emails: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    address: { type: "string", format: "email" },
+                    label: { type: "string", minLength: 1, maxLength: 20 },
+                  },
+                  required: ["address"],
+                },
+              },
+            },
+          },
+          fields: {
+            emails: { label: "Emails", type: "array" },
+          },
+          fieldOrder: ["emails"],
+        };
+
+        // Valid
+        expect(
+          validate({ emails: [{ address: "test@example.com", label: "Work" }] }, spec).valid
+        ).toBe(true);
+
+        // Invalid email format
+        const emailResult = validate({ emails: [{ address: "not-an-email" }] }, spec);
+        expect(emailResult.valid).toBe(false);
+        expect(emailResult.errors[0].field).toBe("emails[0].address");
+        expect(emailResult.errors[0].message).toContain("valid email");
+
+        // Invalid label (too long)
+        const labelResult = validate(
+          { emails: [{ address: "test@example.com", label: "This label is way too long for the constraint" }] },
+          spec
+        );
+        expect(labelResult.valid).toBe(false);
+        expect(labelResult.errors[0].field).toBe("emails[0].label");
+        expect(labelResult.errors[0].message).toContain("no more than 20");
+      });
+
+      it("should validate multipleOf in array item fields", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              prices: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    amount: { type: "number", multipleOf: 0.01 },
+                  },
+                },
+              },
+            },
+          },
+          fields: {
+            prices: { label: "Prices", type: "array" },
+          },
+          fieldOrder: ["prices"],
+        };
+
+        // Valid - correct precision
+        expect(validate({ prices: [{ amount: 10.99 }, { amount: 5.0 }] }, spec).valid).toBe(true);
+
+        // Invalid - wrong precision
+        const result = validate({ prices: [{ amount: 10.999 }] }, spec);
+        expect(result.valid).toBe(false);
+        expect(result.errors[0].field).toBe("prices[0].amount");
+        expect(result.errors[0].message).toContain("multiple of 0.01");
+      });
+    });
+
+    describe("combined fieldDef and schema validation", () => {
+      it("should use itemFields for custom validations while using schema for type constraints", () => {
+        const spec: Forma = {
+          version: "1.0",
+          meta: { id: "test", title: "Test" },
+          schema: {
+            type: "object",
+            properties: {
+              orders: {
+                type: "array",
+                items: {
+                  type: "object",
+                  properties: {
+                    quantity: { type: "integer", minimum: 1 },
+                    price: { type: "number", minimum: 0 },
+                  },
+                },
+                minItems: 1,
+              },
+            },
+          },
+          fields: {
+            orders: {
+              label: "Orders",
+              type: "array",
+              itemFields: {
+                quantity: {
+                  label: "Quantity",
+                  validations: [
+                    { rule: "value <= 100", message: "Cannot order more than 100 items" },
+                  ],
+                },
+              },
+            },
+          },
+          fieldOrder: ["orders"],
+        };
+
+        // Valid
+        expect(validate({ orders: [{ quantity: 5, price: 10.0 }] }, spec).valid).toBe(true);
+
+        // Invalid - schema minimum violated
+        const minResult = validate({ orders: [{ quantity: 0, price: 10.0 }] }, spec);
+        expect(minResult.valid).toBe(false);
+        expect(minResult.errors[0].message).toContain("at least 1");
+
+        // Invalid - custom FEEL validation violated
+        const customResult = validate({ orders: [{ quantity: 150, price: 10.0 }] }, spec);
+        expect(customResult.valid).toBe(false);
+        expect(customResult.errors.some((e) => e.message.includes("more than 100"))).toBe(true);
+
+        // Invalid - empty array (minItems from schema)
+        const emptyResult = validate({ orders: [] }, spec);
+        expect(emptyResult.valid).toBe(false);
+        expect(emptyResult.errors[0].message).toContain("at least 1 items");
+      });
+    });
+  });
 });

package/src/engine/calculate.ts

@@ -6,6 +6,7 @@
  */
 
 import { evaluate } from "../feel/index.js";
+import { formatValue, type FormatOptions } from "../format/index.js";
 import type {
   Forma,
   ComputedField,
@@ -275,12 +276,14 @@ function findComputedDependencies(
  * @param fieldName - Name of the computed field
  * @param data - Current form data
  * @param spec - Form specification
- * @returns Formatted string or null if not displayable
+ * @param options - Formatting options (locale, currency, nullDisplay)
+ * @returns Formatted string or null if field not found or value is null/undefined
  */
 export function getFormattedValue(
   fieldName: string,
   data: Record<string, unknown>,
-  spec: Forma
+  spec: Forma,
+  options?: FormatOptions
 ): string | null {
   if (!spec.computed?.[fieldName]) {
     return null;
@@ -291,54 +294,14 @@ export function getFormattedValue(
   const value = computed[fieldName];
 
   if (value === null || value === undefined) {
+    // If nullDisplay is specified, use formatValue to get it
+    if (options?.nullDisplay !== undefined) {
+      return formatValue(value, fieldDef.format, options);
+    }
     return null;
   }
 
-  return formatValue(value, fieldDef.format);
-}
-
-/**
- * Format a value according to a format specification
- *
- * Supported formats:
- * - decimal(n) - Number with n decimal places
- * - currency - Number formatted as currency
- * - percent - Number formatted as percentage
- * - (none) - Default string conversion
- */
-function formatValue(value: unknown, format?: string): string {
-  if (!format) {
-    return String(value);
-  }
-
-  // Handle decimal(n) format
-  const decimalMatch = format.match(/^decimal\((\d+)\)$/);
-  if (decimalMatch) {
-    const decimals = parseInt(decimalMatch[1], 10);
-    return typeof value === "number" ? value.toFixed(decimals) : String(value);
-  }
-
-  // Handle currency format
-  if (format === "currency") {
-    return typeof value === "number"
-      ? new Intl.NumberFormat("en-US", {
-          style: "currency",
-          currency: "USD",
-        }).format(value)
-      : String(value);
-  }
-
-  // Handle percent format
-  if (format === "percent") {
-    return typeof value === "number"
-      ? new Intl.NumberFormat("en-US", {
-          style: "percent",
-          minimumFractionDigits: 1,
-        }).format(value)
-      : String(value);
-  }
-
-  return String(value);
+  return formatValue(value, fieldDef.format, options);
 }
 
 // ============================================================================

package/src/engine/index.ts

@@ -12,6 +12,17 @@ export {
   getFormattedValue,
 } from "./calculate.js";
 
+// Format
+export {
+  formatValue,
+  isValidFormat,
+  parseDecimalFormat,
+  SUPPORTED_FORMATS,
+  DECIMAL_FORMAT_PATTERN,
+} from "../format/index.js";
+
+export type { FormatOptions, SupportedFormat } from "../format/index.js";
+
 // Visibility
 export {
   getVisibility,