@fogpipe/forma-react 0.17.0 → 0.17.1

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/types.ts

@@ -26,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 */
@@ -322,7 +327,9 @@ export interface MatrixFieldProps extends Omit<
   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;
+  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) */
@@ -380,7 +387,7 @@ export interface ComponentMap {
  */
 export interface LayoutProps {
   children: React.ReactNode;
-  onSubmit: () => void;
+  onSubmit: (e?: React.FormEvent) => void;
   isSubmitting: boolean;
   isValid: boolean;
 }
@@ -552,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 */

package/src/useForma.ts

@@ -117,6 +117,12 @@ export interface WizardHelpers {
   goToPage: (index: number) => void;
   nextPage: () => void;
   previousPage: () => void;
+  /**
+   * Safe "Next" handler for wizard navigation.
+   * Advances to the next page if one exists. Never triggers submission.
+   * Use this instead of conditionally calling nextPage/onSubmit in a single button.
+   */
+  handleNext: () => void;
   hasNextPage: boolean;
   hasPreviousPage: boolean;
   canProceed: boolean;
@@ -337,10 +343,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
 
   // Helper: fire an event to both declarative `on` handlers and imperative listeners
   const fireEvent = useCallback(
-    <K extends keyof FormaEventMap>(
-      event: K,
-      payload: FormaEventMap[K],
-    ) => {
+    <K extends keyof FormaEventMap>(event: K, payload: FormaEventMap[K]) => {
       // Declarative handler (via ref for latest callback)
       try {
         const handler = onEventsRef.current?.[event];
@@ -494,11 +497,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
 
   // Queue a fieldChanged event (captures previousValue from current state ref)
   const queueFieldChangedEvent = useCallback(
-    (
-      path: string,
-      value: unknown,
-      source: "user" | "reset" | "setValues",
-    ) => {
+    (path: string, value: unknown, source: "user" | "reset" | "setValues") => {
       if (isFiringEventsRef.current) return; // recursion guard
       const previousValue = getValueAtPath(path);
       if (previousValue === value) return; // no actual change
@@ -584,8 +583,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
           postSubmitPayload = {
             data: submissionData,
             success: false,
-            error:
-              error instanceof Error ? error : new Error(String(error)),
+            error: error instanceof Error ? error : new Error(String(error)),
           };
         }
       } else {
@@ -676,6 +674,21 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
     const hasPreviousPage = clampedPageIndex > 0;
     const isLastPage = clampedPageIndex === visiblePages.length - 1;
 
+    const advanceToNextPage = () => {
+      if (hasNextPage) {
+        const toIndex = clampedPageIndex + 1;
+        dispatch({ type: "SET_PAGE", page: toIndex });
+        const newPage = visiblePages[toIndex];
+        if (newPage) {
+          fireEvent("pageChanged", {
+            fromIndex: clampedPageIndex,
+            toIndex,
+            page: newPage,
+          });
+        }
+      }
+    };
+
     return {
       pages,
       currentPageIndex: clampedPageIndex,
@@ -694,20 +707,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
           }
         }
       },
-      nextPage: () => {
-        if (hasNextPage) {
-          const toIndex = clampedPageIndex + 1;
-          dispatch({ type: "SET_PAGE", page: toIndex });
-          const newPage = visiblePages[toIndex];
-          if (newPage) {
-            fireEvent("pageChanged", {
-              fromIndex: clampedPageIndex,
-              toIndex,
-              page: newPage,
-            });
-          }
-        }
-      },
+      nextPage: advanceToNextPage,
       previousPage: () => {
         if (hasPreviousPage) {
           const toIndex = clampedPageIndex - 1;
@@ -722,6 +722,10 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
           }
         }
       },
+      // Same function as nextPage — exposed as a separate name so consumers can
+      // bind a single "Next" button without risk of accidentally triggering submission.
+      // nextPage is already a no-op on the last page.
+      handleNext: advanceToNextPage,
       hasNextPage,
       hasPreviousPage,
       canProceed: (() => {
@@ -756,7 +760,15 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
         return pageErrors.length === 0;
       },
     };
-  }, [spec, state.data, state.currentPage, computed, validation, visibility, fireEvent]);
+  }, [
+    spec,
+    state.data,
+    state.currentPage,
+    computed,
+    validation,
+    visibility,
+    fireEvent,
+  ]);
 
   // Flush pending events after render (fieldChanged, formReset)
   useEffect(() => {
@@ -885,12 +897,12 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
 
       const fieldErrors = validation.errors.filter((e) => e.field === path);
       const isTouched = state.touched[path] ?? false;
-      const showErrors =
+      const shouldShowErrors =
         validateOn === "change" ||
         (validateOn === "blur" && isTouched) ||
         state.isSubmitted;
-      const displayedErrors = showErrors ? fieldErrors : [];
-      const hasErrors = displayedErrors.length > 0;
+      const visibleFieldErrors = shouldShowErrors ? fieldErrors : [];
+      const hasVisibleErrors = visibleFieldErrors.length > 0;
       const isRequired = required[path] ?? false;
 
       // Boolean fields: hide asterisk unless they have validation rules (consent pattern)
@@ -922,12 +934,13 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
         required: isRequired,
         showRequiredIndicator,
         touched: isTouched,
-        errors: displayedErrors,
+        errors: fieldErrors,
+        visibleErrors: visibleFieldErrors,
         onChange: handlers.onChange,
         onBlur: handlers.onBlur,
-        // ARIA accessibility attributes
-        "aria-invalid": hasErrors || undefined,
-        "aria-describedby": hasErrors ? `${path}-error` : undefined,
+        // ARIA accessibility attributes (driven by visibleErrors, not all errors)
+        "aria-invalid": hasVisibleErrors || undefined,
+        "aria-describedby": hasVisibleErrors ? `${path}-error` : undefined,
         "aria-required": isRequired || undefined,
         // Adorner props (only for adornable field types)
         ...adornerProps,
@@ -1020,7 +1033,8 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
           required: false, // TODO: Evaluate item field required
           showRequiredIndicator: false, // Item fields don't show required indicator
           touched: isTouched,
-          errors: showErrors ? fieldErrors : [],
+          errors: fieldErrors,
+          visibleErrors: showErrors ? fieldErrors : [],
           onChange: handlers.onChange,
           onBlur: handlers.onBlur,
           options: visibleOptions,