@fogpipe/forma-react 0.17.0 → 0.17.1

package/src/FieldRenderer.tsx

@@ -132,6 +132,9 @@ export function FieldRenderer({
 
   const errors = forma.errors.filter((e) => e.field === fieldPath);
   const touched = forma.touched[fieldPath] ?? false;
+  // FieldRenderer doesn't have access to validateOn (it's a FormRenderer prop),
+  // so it uses the default "blur" behavior: show errors after touch or submit.
+  const visibleErrors = touched || forma.isSubmitted ? errors : [];
   const required = forma.required[fieldPath] ?? false;
   const disabled = forma.enabled[fieldPath] === false;
 
@@ -148,6 +151,7 @@ export function FieldRenderer({
     required,
     disabled,
     errors,
+    visibleErrors,
     onChange: (value: unknown) => forma.setFieldValue(fieldPath, value),
     onBlur: () => forma.setFieldTouched(fieldPath),
     // Convenience properties
@@ -318,7 +322,10 @@ export function FieldRenderer({
   } else if (fieldType === "matrix" && fieldDef.type === "matrix") {
     // Matrix fields — compute visible rows from visibility engine
     const matrixValue =
-      (baseProps.value as Record<string, string | number | string[] | number[]> | null) ?? null;
+      (baseProps.value as Record<
+        string,
+        string | number | string[] | number[]
+      > | null) ?? null;
     const rows = fieldDef.rows.map((row) => ({
       id: row.id,
       label: row.label,
@@ -340,12 +347,13 @@ export function FieldRenderer({
     const sourceValue = fieldDef.source
       ? (forma.data[fieldDef.source] ?? forma.computed[fieldDef.source])
       : undefined;
-    // eslint-disable-next-line @typescript-eslint/no-unused-vars
     const {
-      onChange: _onChange,
-      value: _value,
+      onChange: _onChange, // omit from display props
+      value: _value, // omit from display props
       ...displayBaseProps
     } = baseProps;
+    void _onChange;
+    void _value;
     fieldProps = {
       ...displayBaseProps,
       fieldType: "display",

package/src/FormRenderer.tsx

@@ -86,12 +86,7 @@ export interface FormRendererHandle {
  */
 function DefaultLayout({ children, onSubmit, isSubmitting }: LayoutProps) {
   return (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault();
-        onSubmit();
-      }}
-    >
+    <form onSubmit={onSubmit}>
       {children}
       <button type="submit" disabled={isSubmitting}>
         {isSubmitting ? "Submitting..." : "Submit"}
@@ -242,7 +237,7 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
       layout: Layout = DefaultLayout,
       fieldWrapper: FieldWrapper = DefaultFieldWrapper,
       pageWrapper: PageWrapper = DefaultPageWrapper,
-      validateOn,
+      validateOn = "blur",
     } = props;
 
     const forma = useForma({
@@ -299,6 +294,7 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
       optionsVisibility: formaOptionsVisibility,
       touched: formaTouched,
       errors: formaErrors,
+      isSubmitted: formaIsSubmitted,
       setFieldValue,
       setFieldTouched,
       getArrayHelpers,
@@ -342,6 +338,11 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
 
         const errors = formaErrors.filter((e) => e.field === fieldPath);
         const touched = formaTouched[fieldPath] ?? false;
+        const showErrors =
+          validateOn === "change" ||
+          (validateOn === "blur" && touched) ||
+          formaIsSubmitted;
+        const visibleErrors = showErrors ? errors : [];
         const required = formaRequired[fieldPath] ?? false;
         const disabled = formaEnabled[fieldPath] === false;
 
@@ -367,6 +368,7 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
           required,
           disabled,
           errors,
+          visibleErrors,
           onChange: (value: unknown) => setFieldValue(fieldPath, value),
           onBlur: () => setFieldTouched(fieldPath),
           // Convenience properties
@@ -487,7 +489,10 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
           } as ArrayFieldProps;
         } else if (fieldType === "matrix" && fieldDef.type === "matrix") {
           const matrixValue =
-            (baseProps.value as Record<string, string | number | string[] | number[]> | null) ?? null;
+            (baseProps.value as Record<
+              string,
+              string | number | string[] | number[]
+            > | null) ?? null;
           const rows = fieldDef.rows.map((row) => ({
             id: row.id,
             label: row.label,
@@ -574,6 +579,8 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
         formaOptionsVisibility,
         formaTouched,
         formaErrors,
+        formaIsSubmitted,
+        validateOn,
         setFieldValue,
         setFieldTouched,
         getArrayHelpers,
@@ -607,10 +614,20 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
       return <>{renderedFields}</>;
     }, [spec.pages, forma.wizard, PageWrapper, renderedFields]);
 
+    // Wrap submitForm to always call preventDefault when invoked from a form event.
+    // This prevents page refreshes when consumers put onSubmit on a <form> element.
+    const handleSubmit = useCallback(
+      (e?: React.FormEvent) => {
+        e?.preventDefault();
+        forma.submitForm();
+      },
+      [forma.submitForm],
+    );
+
     return (
       <FormaContext.Provider value={forma}>
         <Layout
-          onSubmit={forma.submitForm}
+          onSubmit={handleSubmit}
           isSubmitting={forma.isSubmitting}
           isValid={forma.isValid}
         >

package/src/__tests__/FieldRenderer.test.tsx

@@ -815,7 +815,11 @@ describe("FieldRenderer", () => {
             label: "Rating",
             rows: [
               { id: "speed", label: "Speed" },
-              { id: "quality", label: "Quality", visibleWhen: "show_quality = true" },
+              {
+                id: "quality",
+                label: "Quality",
+                visibleWhen: "show_quality = true",
+              },
             ],
             columns: [
               { value: 1, label: "Poor" },

package/src/__tests__/FormRenderer.test.tsx

@@ -1386,4 +1386,150 @@ describe("FormRenderer", () => {
       });
     });
   });
+
+  // ============================================================================
+  // onSubmit preventDefault
+  // ============================================================================
+
+  describe("onSubmit preventDefault", () => {
+    it("should call preventDefault when onSubmit is invoked with a form event", async () => {
+      const submitHandler = vi.fn();
+
+      // Custom layout that puts onSubmit directly on a <form> element
+      function CustomLayout({ children, onSubmit }: LayoutProps) {
+        return (
+          <form onSubmit={onSubmit} data-testid="form">
+            {children}
+            <button type="submit">Submit</button>
+          </form>
+        );
+      }
+
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+        },
+      });
+
+      render(
+        <FormRenderer
+          spec={spec}
+          components={createTestComponentMap()}
+          layout={CustomLayout}
+          onSubmit={submitHandler}
+          initialData={{ name: "John" }}
+        />,
+      );
+
+      const form = screen.getByTestId("form");
+
+      // Create a real submit event and spy on preventDefault
+      const preventDefaultSpy = vi.fn();
+      const submitEvent = new Event("submit", {
+        bubbles: true,
+        cancelable: true,
+      });
+      Object.defineProperty(submitEvent, "preventDefault", {
+        value: preventDefaultSpy,
+      });
+
+      await act(async () => {
+        form.dispatchEvent(submitEvent);
+      });
+
+      // preventDefault should have been called by the wrapper
+      expect(preventDefaultSpy).toHaveBeenCalled();
+    });
+
+    it("should work when onSubmit is called without an event (programmatic)", async () => {
+      const submitHandler = vi.fn();
+
+      // Custom layout that calls onSubmit programmatically (no event)
+      function CustomLayout({ children, onSubmit }: LayoutProps) {
+        return (
+          <div>
+            {children}
+            <button
+              type="button"
+              onClick={() => onSubmit()}
+              data-testid="submit-btn"
+            >
+              Submit
+            </button>
+          </div>
+        );
+      }
+
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name" },
+        },
+      });
+
+      render(
+        <FormRenderer
+          spec={spec}
+          components={createTestComponentMap()}
+          layout={CustomLayout}
+          onSubmit={submitHandler}
+          initialData={{ name: "John" }}
+        />,
+      );
+
+      await act(async () => {
+        screen.getByTestId("submit-btn").click();
+      });
+
+      await waitFor(() => {
+        expect(submitHandler).toHaveBeenCalledWith({ name: "John" });
+      });
+    });
+
+    it("LayoutProps.onSubmit accepts an optional event parameter", () => {
+      // Type-level test: verify the signature compiles
+      const _layout: React.FC<LayoutProps> = ({ onSubmit }) => {
+        return (
+          <form onSubmit={onSubmit}>
+            <button onClick={() => onSubmit()}>Submit</button>
+          </form>
+        );
+      };
+      expect(_layout).toBeDefined();
+    });
+  });
+
+  // ============================================================================
+  // visibleErrors
+  // ============================================================================
+
+  describe("visibleErrors", () => {
+    it("FormRenderer passes visibleErrors to components", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      let capturedVisibleErrors: unknown[] | undefined;
+
+      const components = {
+        ...createTestComponentMap(),
+        text: ({ field: props }: { field: { visibleErrors?: unknown[] } }) => {
+          capturedVisibleErrors = props.visibleErrors;
+          return <div data-testid="text-field">text</div>;
+        },
+      };
+
+      render(
+        <FormRenderer
+          spec={spec}
+          components={components as ReturnType<typeof createTestComponentMap>}
+          validateOn="blur"
+        />,
+      );
+
+      // visibleErrors should be an empty array (field not touched, validateOn=blur)
+      expect(capturedVisibleErrors).toEqual([]);
+    });
+  });
 });

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");
+          },
         },
       }),
     );