@fogpipe/forma-react 0.16.0 → 0.17.1

package/src/__tests__/canProceed.test.ts

@@ -915,4 +915,247 @@ describe("canProceed", () => {
       expect(result.current.wizard?.currentPage?.id).toBe("page1");
     });
   });
+
+  describe("handleNext - safe wizard navigation", () => {
+    it("handleNext advances page but does NOT call onSubmit", async () => {
+      const submitHandler = vi.fn();
+
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+          email: { type: "email", label: "Email" },
+          phone: { type: "text", label: "Phone" },
+        },
+        pages: [
+          { id: "page1", title: "Page 1", fields: ["name"] },
+          { id: "page2", title: "Page 2", fields: ["email"] },
+          { id: "page3", title: "Page 3", fields: ["phone"] },
+        ],
+      });
+
+      const { result } = renderHook(() =>
+        useForma({
+          spec,
+          initialData: {
+            name: "John",
+            email: "john@test.com",
+            phone: "123",
+          },
+          onSubmit: submitHandler,
+        }),
+      );
+
+      // On page 1
+      expect(result.current.wizard?.currentPageIndex).toBe(0);
+      expect(result.current.wizard?.isLastPage).toBe(false);
+
+      // Use handleNext from page 1 → page 2
+      act(() => {
+        result.current.wizard?.handleNext();
+      });
+
+      expect(result.current.wizard?.currentPageIndex).toBe(1);
+      expect(submitHandler).not.toHaveBeenCalled();
+
+      // Use handleNext from page 2 → page 3 (last page)
+      act(() => {
+        result.current.wizard?.handleNext();
+      });
+
+      expect(result.current.wizard?.currentPageIndex).toBe(2);
+      expect(result.current.wizard?.isLastPage).toBe(true);
+      // Critically: onSubmit was NOT called
+      expect(submitHandler).not.toHaveBeenCalled();
+    });
+
+    it("handleNext does nothing on the last page", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+          email: { type: "email", label: "Email" },
+        },
+        pages: [
+          { id: "page1", title: "Page 1", fields: ["name"] },
+          { id: "page2", title: "Page 2", fields: ["email"] },
+        ],
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // Navigate to last page
+      act(() => {
+        result.current.wizard?.nextPage();
+      });
+      expect(result.current.wizard?.isLastPage).toBe(true);
+
+      // handleNext on last page — should stay on last page
+      act(() => {
+        result.current.wizard?.handleNext();
+      });
+      expect(result.current.wizard?.currentPageIndex).toBe(1);
+      expect(result.current.wizard?.isLastPage).toBe(true);
+    });
+
+    it("nextPage() from second-to-last page does not trigger submitForm", () => {
+      const submitHandler = vi.fn();
+
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+          email: { type: "email", label: "Email" },
+          phone: { type: "text", label: "Phone" },
+        },
+        pages: [
+          { id: "page1", title: "Page 1", fields: ["name"] },
+          { id: "page2", title: "Page 2", fields: ["email"] },
+          { id: "page3", title: "Page 3", fields: ["phone"] },
+        ],
+      });
+
+      const { result } = renderHook(() =>
+        useForma({
+          spec,
+          initialData: { name: "John", email: "test@test.com" },
+          onSubmit: submitHandler,
+        }),
+      );
+
+      // Navigate to page 2 (second-to-last)
+      act(() => {
+        result.current.wizard?.nextPage();
+      });
+      expect(result.current.wizard?.currentPageIndex).toBe(1);
+
+      // Navigate from page 2 → page 3 (last)
+      act(() => {
+        result.current.wizard?.nextPage();
+      });
+
+      // Should be on last page but NOT have submitted
+      expect(result.current.wizard?.currentPageIndex).toBe(2);
+      expect(result.current.wizard?.isLastPage).toBe(true);
+      expect(submitHandler).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("untouched required fields", () => {
+    it("canProceed is false when required fields have no initialData", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+          email: { type: "email", label: "Email", required: true },
+        },
+        pages: [{ id: "page1", title: "Page 1", fields: ["name", "email"] }],
+      });
+
+      // No initialData at all
+      const { result } = renderHook(() => useForma({ spec }));
+
+      // canProceed should be false immediately — fields are untouched and empty
+      expect(result.current.wizard?.canProceed).toBe(false);
+      expect(result.current.touched.name).toBeUndefined();
+      expect(result.current.touched.email).toBeUndefined();
+    });
+
+    it("canProceed is false with explicit empty initialData", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+          email: { type: "email", label: "Email", required: true },
+        },
+        pages: [{ id: "page1", title: "Page 1", fields: ["name", "email"] }],
+      });
+
+      const { result } = renderHook(() => useForma({ spec, initialData: {} }));
+
+      expect(result.current.wizard?.canProceed).toBe(false);
+    });
+
+    it("canProceed becomes true when user fills all required fields", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+          email: { type: "email", label: "Email", required: true },
+        },
+        pages: [{ id: "page1", title: "Page 1", fields: ["name", "email"] }],
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      expect(result.current.wizard?.canProceed).toBe(false);
+
+      act(() => {
+        result.current.setFieldValue("name", "John");
+      });
+      // Still false — email is empty
+      expect(result.current.wizard?.canProceed).toBe(false);
+
+      act(() => {
+        result.current.setFieldValue("email", "john@example.com");
+      });
+      expect(result.current.wizard?.canProceed).toBe(true);
+    });
+
+    it("canProceed is false for required number field with undefined value", () => {
+      const spec = createTestSpec({
+        fields: {
+          age: { type: "number", label: "Age", required: true },
+        },
+        pages: [{ id: "page1", title: "Page 1", fields: ["age"] }],
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      expect(result.current.wizard?.canProceed).toBe(false);
+    });
+
+    it("canProceed is false for required select field with no selection", () => {
+      const spec = createTestSpec({
+        fields: {
+          country: {
+            type: "select",
+            label: "Country",
+            required: true,
+            options: [
+              { label: "USA", value: "us" },
+              { label: "Canada", value: "ca" },
+            ],
+          },
+        },
+        pages: [{ id: "page1", title: "Page 1", fields: ["country"] }],
+      });
+
+      const { result } = renderHook(() => useForma({ spec }));
+
+      expect(result.current.wizard?.canProceed).toBe(false);
+    });
+
+    it("touchCurrentPageFields then canProceed still works as expected", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+        pages: [{ id: "page1", title: "Page 1", fields: ["name"] }],
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      // canProceed is false before touching
+      expect(result.current.wizard?.canProceed).toBe(false);
+
+      // Touch all fields — canProceed should still be false (empty field)
+      act(() => {
+        result.current.wizard?.touchCurrentPageFields();
+      });
+      expect(result.current.wizard?.canProceed).toBe(false);
+
+      // Fill the field
+      act(() => {
+        result.current.setFieldValue("name", "John");
+      });
+      expect(result.current.wizard?.canProceed).toBe(true);
+    });
+  });
 });

package/src/__tests__/events.test.ts

@@ -37,9 +37,15 @@ describe("FormaEventEmitter", () => {
 
   it("should fire multiple listeners in registration order", () => {
     const calls: number[] = [];
-    emitter.on("fieldChanged", () => { calls.push(1); });
-    emitter.on("fieldChanged", () => { calls.push(2); });
-    emitter.on("fieldChanged", () => { calls.push(3); });
+    emitter.on("fieldChanged", () => {
+      calls.push(1);
+    });
+    emitter.on("fieldChanged", () => {
+      calls.push(2);
+    });
+    emitter.on("fieldChanged", () => {
+      calls.push(3);
+    });
 
     emitter.fire("fieldChanged", {
       path: "x",
@@ -582,8 +588,12 @@ describe("formReset event", () => {
         spec,
         initialData: { name: "initial" },
         on: {
-          fieldChanged: () => { events.push("fieldChanged"); },
-          formReset: () => { events.push("formReset"); },
+          fieldChanged: () => {
+            events.push("fieldChanged");
+          },
+          formReset: () => {
+            events.push("formReset");
+          },
         },
       }),
     );

package/src/__tests__/useForma.test.ts

@@ -612,10 +612,14 @@ describe("useForma", () => {
 
       const { result } = renderHook(() => useForma({ spec }));
 
-      // Initially no errors shown (not touched)
-      expect(result.current.getFieldProps("name").errors).toEqual([]);
+      // errors always contains all validation errors (eager validation)
+      expect(
+        result.current.getFieldProps("name").errors.length,
+      ).toBeGreaterThan(0);
+      // visibleErrors should be empty (not touched, default validateOn=blur)
+      expect(result.current.getFieldProps("name").visibleErrors).toEqual([]);
 
-      // After submit, errors should show
+      // After submit, visibleErrors should show
       act(() => {
         result.current.submitForm();
       });
@@ -636,9 +640,12 @@ describe("useForma", () => {
         useForma({ spec, validateOn: "blur" }),
       );
 
-      // Errors exist but not shown
+      // Errors exist (eager validation) but visibleErrors is empty (not touched)
       expect(result.current.isValid).toBe(false);
-      expect(result.current.getFieldProps("name").errors).toEqual([]);
+      expect(
+        result.current.getFieldProps("name").errors.length,
+      ).toBeGreaterThan(0);
+      expect(result.current.getFieldProps("name").visibleErrors).toEqual([]);
     });
 
     it("should show errors immediately when validateOn: change", () => {
@@ -1854,4 +1861,100 @@ describe("useForma", () => {
       ).toBe("Item Name");
     });
   });
+
+  // ============================================================================
+  // visibleErrors
+  // ============================================================================
+
+  describe("visibleErrors", () => {
+    it("visibleErrors is empty for untouched required fields (validateOn=blur)", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+          email: { type: "email", label: "Email", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      const nameProps = result.current.getFieldProps("name");
+
+      // errors should contain the required error (validation runs eagerly)
+      expect(nameProps.errors.length).toBeGreaterThan(0);
+      // visibleErrors should be empty (field not touched)
+      expect(nameProps.visibleErrors).toHaveLength(0);
+    });
+
+    it("visibleErrors populates after field is touched", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      // Before touch
+      expect(result.current.getFieldProps("name").visibleErrors).toHaveLength(
+        0,
+      );
+
+      // Touch the field
+      act(() => {
+        result.current.setFieldTouched("name");
+      });
+
+      // After touch — errors should be visible
+      const props = result.current.getFieldProps("name");
+      expect(props.visibleErrors.length).toBeGreaterThan(0);
+      expect(props.visibleErrors[0].message).toBeDefined();
+    });
+
+    it("visibleErrors populates after form submission", async () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      // Before submit — visibleErrors empty
+      expect(result.current.getFieldProps("name").visibleErrors).toHaveLength(
+        0,
+      );
+
+      // Submit the form (validation will fail)
+      await act(async () => {
+        await result.current.submitForm();
+      });
+
+      // After submit — errors should be visible even without touching
+      expect(
+        result.current.getFieldProps("name").visibleErrors.length,
+      ).toBeGreaterThan(0);
+    });
+
+    it("visibleErrors is always populated when validateOn=change", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "change" }),
+      );
+
+      // With validateOn="change", errors should be visible immediately
+      const props = result.current.getFieldProps("name");
+      expect(props.visibleErrors.length).toBeGreaterThan(0);
+    });
+  });
 });

package/src/events.ts

@@ -136,7 +136,10 @@ export class FormaEventEmitter {
    * Fire an event synchronously. Listener errors are caught and logged
    * to prevent one listener from breaking others.
    */
-  fire<K extends keyof FormaEventMap>(event: K, payload: FormaEventMap[K]): void {
+  fire<K extends keyof FormaEventMap>(
+    event: K,
+    payload: FormaEventMap[K],
+  ): void {
     const set = this.listeners.get(event);
     if (!set || set.size === 0) return;
 

package/src/index.ts

@@ -86,6 +86,8 @@ export type {
   ComputedComponentProps,
   DisplayFieldProps,
   DisplayComponentProps,
+  MatrixFieldProps,
+  MatrixComponentProps,
   ComponentMap,
 
   // Form state

package/src/types.ts

@@ -6,6 +6,7 @@ import type {
   Forma,
   FieldDefinition,
   FieldError,
+  MatrixColumn,
   SelectOption,
 } from "@fogpipe/forma-core";
 
@@ -25,8 +26,13 @@ export interface BaseFieldProps {
   required: boolean;
   /** Whether the field is disabled */
   disabled: boolean;
-  /** Validation errors for this field */
+  /** Validation errors for this field (always populated — use visibleErrors for display) */
   errors: FieldError[];
+  /**
+   * Errors filtered by interaction state (touched or submitted).
+   * Use this for displaying errors in the UI to avoid showing errors on untouched fields.
+   */
+  visibleErrors: FieldError[];
   /** Handler for value changes */
   onChange: (value: unknown) => void;
   /** Handler for blur events */
@@ -311,6 +317,27 @@ export interface DisplayFieldProps extends Omit<
   value?: never;
 }
 
+/**
+ * Props for matrix/grid fields
+ */
+export interface MatrixFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
+  fieldType: "matrix";
+  /** Current matrix value: row ID → selected column value(s) */
+  value: Record<string, string | number | string[] | number[]> | null;
+  onChange: (
+    value: Record<string, string | number | string[] | number[]>,
+  ) => void;
+  /** Row definitions with visibility state */
+  rows: Array<{ id: string; label: string; visible: boolean }>;
+  /** Column definitions (shared options for all rows) */
+  columns: MatrixColumn[];
+  /** Whether multiple selections per row are allowed */
+  multiSelect: boolean;
+}
+
 /**
  * Union of all field prop types
  */
@@ -326,7 +353,8 @@ export type FieldProps =
   | ArrayFieldProps
   | ObjectFieldProps
   | ComputedFieldProps
-  | DisplayFieldProps;
+  | DisplayFieldProps
+  | MatrixFieldProps;
 
 /**
  * Map of field types to React components
@@ -350,6 +378,7 @@ export interface ComponentMap {
   object?: React.ComponentType<ObjectComponentProps>;
   computed?: React.ComponentType<ComputedComponentProps>;
   display?: React.ComponentType<DisplayComponentProps>;
+  matrix?: React.ComponentType<MatrixComponentProps>;
   fallback?: React.ComponentType<FieldComponentProps>;
 }
 
@@ -358,7 +387,7 @@ export interface ComponentMap {
  */
 export interface LayoutProps {
   children: React.ReactNode;
-  onSubmit: () => void;
+  onSubmit: (e?: React.FormEvent) => void;
   isSubmitting: boolean;
   isValid: boolean;
 }
@@ -462,6 +491,11 @@ export interface DisplayComponentProps {
   spec: Forma;
 }
 
+export interface MatrixComponentProps {
+  field: MatrixFieldProps;
+  spec: Forma;
+}
+
 /**
  * Generic field component props (for fallback/dynamic components)
  */
@@ -525,8 +559,13 @@ export interface GetFieldPropsResult {
   showRequiredIndicator: boolean;
   /** Whether field has been touched */
   touched: boolean;
-  /** Validation errors for this field */
+  /** Validation errors for this field (always populated — use visibleErrors for display) */
   errors: FieldError[];
+  /**
+   * Errors filtered by interaction state (touched or submitted).
+   * Use this for displaying errors in the UI to avoid showing errors on untouched fields.
+   */
+  visibleErrors: FieldError[];
   /** Handler for value changes */
   onChange: (value: unknown) => void;
   /** Handler for blur events */