@fogpipe/forma-react 0.17.0 → 0.17.1

package/README.md

@@ -199,13 +199,13 @@ The event system lets you observe form lifecycle events for side effects like an
 
 ### Available Events
 
-| Event          | Description                                             |
-| -------------- | ------------------------------------------------------- |
-| `fieldChanged` | Fires after a field value changes                       |
-| `preSubmit`    | Fires before validation; `data` is mutable              |
-| `postSubmit`   | Fires after submission (success, error, or invalid)     |
-| `pageChanged`  | Fires when wizard page changes                          |
-| `formReset`    | Fires after `resetForm()` completes                     |
+| Event          | Description                                         |
+| -------------- | --------------------------------------------------- |
+| `fieldChanged` | Fires after a field value changes                   |
+| `preSubmit`    | Fires before validation; `data` is mutable          |
+| `postSubmit`   | Fires after submission (success, error, or invalid) |
+| `pageChanged`  | Fires when wizard page changes                      |
+| `formReset`    | Fires after `resetForm()` completes                 |
 
 ### Declarative Registration
 
@@ -217,7 +217,10 @@ const forma = useForma({
   onSubmit: handleSubmit,
   on: {
     fieldChanged: (event) => {
-      analytics.track("field_changed", { path: event.path, source: event.source });
+      analytics.track("field_changed", {
+        path: event.path,
+        source: event.source,
+      });
     },
     preSubmit: async (event) => {
       event.data.token = await getCSRFToken();
@@ -302,28 +305,28 @@ formRef.current?.setValues({ name: "John" });
 
 ### useForma Methods
 
-| Method                            | Description                          |
-| --------------------------------- | ------------------------------------ |
-| `setFieldValue(path, value)`      | Set field value                      |
-| `setFieldTouched(path, touched?)` | Mark field as touched                |
-| `setValues(values)`               | Set multiple values                  |
-| `validateField(path)`             | Validate single field                |
-| `validateForm()`                  | Validate entire form                 |
-| `submitForm()`                    | Submit the form                      |
-| `resetForm()`                     | Reset to initial values              |
+| Method                            | Description                                  |
+| --------------------------------- | -------------------------------------------- |
+| `setFieldValue(path, value)`      | Set field value                              |
+| `setFieldTouched(path, touched?)` | Mark field as touched                        |
+| `setValues(values)`               | Set multiple values                          |
+| `validateField(path)`             | Validate single field                        |
+| `validateForm()`                  | Validate entire form                         |
+| `submitForm()`                    | Submit the form                              |
+| `resetForm()`                     | Reset to initial values                      |
 | `on(event, listener)`             | Register event listener; returns unsubscribe |
 
 ### useForma Options
 
-| Option                 | Type                             | Default  | Description               |
-| ---------------------- | -------------------------------- | -------- | ------------------------- |
-| `spec`                 | `Forma`                          | required | The Forma specification   |
-| `initialData`          | `Record<string, unknown>`        | `{}`     | Initial form values       |
-| `onSubmit`             | `(data) => void`                 | -        | Submit handler            |
-| `onChange`             | `(data, computed) => void`       | -        | Change handler            |
-| `validateOn`           | `"change" \| "blur" \| "submit"` | `"blur"` | When to validate          |
-| `referenceData`        | `Record<string, unknown>`        | -        | Additional reference data |
-| `validationDebounceMs` | `number`                         | `0`      | Debounce validation (ms)  |
+| Option                 | Type                             | Default  | Description                 |
+| ---------------------- | -------------------------------- | -------- | --------------------------- |
+| `spec`                 | `Forma`                          | required | The Forma specification     |
+| `initialData`          | `Record<string, unknown>`        | `{}`     | Initial form values         |
+| `onSubmit`             | `(data) => void`                 | -        | Submit handler              |
+| `onChange`             | `(data, computed) => void`       | -        | Change handler              |
+| `validateOn`           | `"change" \| "blur" \| "submit"` | `"blur"` | When to validate            |
+| `referenceData`        | `Record<string, unknown>`        | -        | Additional reference data   |
+| `validationDebounceMs` | `number`                         | `0`      | Debounce validation (ms)    |
 | `on`                   | `FormaEvents`                    | -        | Declarative event listeners |
 
 ## Error Boundary

package/dist/index.d.ts

@@ -102,8 +102,13 @@ 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 */
@@ -384,7 +389,7 @@ interface ComponentMap {
  */
 interface LayoutProps {
     children: React.ReactNode;
-    onSubmit: () => void;
+    onSubmit: (e?: React.FormEvent) => void;
     isSubmitting: boolean;
     isValid: boolean;
 }
@@ -513,8 +518,13 @@ 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 */
@@ -631,6 +641,12 @@ 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;

package/dist/index.js

@@ -443,6 +443,20 @@ function useForma(options) {
     const hasNextPage = clampedPageIndex < visiblePages.length - 1;
     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,
@@ -461,20 +475,7 @@ function useForma(options) {
           }
         }
       },
-      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;
@@ -489,6 +490,10 @@ function useForma(options) {
           }
         }
       },
+      // 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: (() => {
@@ -517,7 +522,15 @@ function useForma(options) {
         return pageErrors.length === 0;
       }
     };
-  }, [spec, state.data, state.currentPage, computed, validation, visibility, fireEvent]);
+  }, [
+    spec,
+    state.data,
+    state.currentPage,
+    computed,
+    validation,
+    visibility,
+    fireEvent
+  ]);
   useEffect(() => {
     const events = pendingEventsRef.current;
     if (events.length === 0) return;
@@ -621,9 +634,9 @@ function useForma(options) {
       }
       const fieldErrors = validation.errors.filter((e) => e.field === path);
       const isTouched = state.touched[path] ?? false;
-      const showErrors = validateOn === "change" || validateOn === "blur" && isTouched || state.isSubmitted;
-      const displayedErrors = showErrors ? fieldErrors : [];
-      const hasErrors = displayedErrors.length > 0;
+      const shouldShowErrors = validateOn === "change" || validateOn === "blur" && isTouched || state.isSubmitted;
+      const visibleFieldErrors = shouldShowErrors ? fieldErrors : [];
+      const hasVisibleErrors = visibleFieldErrors.length > 0;
       const isRequired = required[path] ?? false;
       const schemaProperty = spec.schema.properties[path];
       const isBooleanField = (schemaProperty == null ? void 0 : schemaProperty.type) === "boolean" || (fieldDef == null ? void 0 : fieldDef.type) === "boolean";
@@ -643,12 +656,13 @@ function useForma(options) {
         required: isRequired,
         showRequiredIndicator,
         touched: isTouched,
-        errors: displayedErrors,
+        errors: fieldErrors,
+        visibleErrors: visibleFieldErrors,
         onChange: handlers.onChange,
         onBlur: handlers.onBlur,
-        // ARIA accessibility attributes
-        "aria-invalid": hasErrors || void 0,
-        "aria-describedby": hasErrors ? `${path}-error` : void 0,
+        // ARIA accessibility attributes (driven by visibleErrors, not all errors)
+        "aria-invalid": hasVisibleErrors || void 0,
+        "aria-describedby": hasVisibleErrors ? `${path}-error` : void 0,
         "aria-required": isRequired || void 0,
         // Adorner props (only for adornable field types)
         ...adornerProps,
@@ -719,7 +733,8 @@ function useForma(options) {
           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
@@ -871,19 +886,10 @@ function useFormaContext() {
 // src/FormRenderer.tsx
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 function DefaultLayout({ children, onSubmit, isSubmitting }) {
-  return /* @__PURE__ */ jsxs(
-    "form",
-    {
-      onSubmit: (e) => {
-        e.preventDefault();
-        onSubmit();
-      },
-      children: [
-        children,
-        /* @__PURE__ */ jsx("button", { type: "submit", disabled: isSubmitting, children: isSubmitting ? "Submitting..." : "Submit" })
-      ]
-    }
-  );
+  return /* @__PURE__ */ jsxs("form", { onSubmit, children: [
+    children,
+    /* @__PURE__ */ jsx("button", { type: "submit", disabled: isSubmitting, children: isSubmitting ? "Submitting..." : "Submit" })
+  ] });
 }
 function DefaultFieldWrapper({
   fieldPath,
@@ -967,7 +973,7 @@ var FormRenderer = forwardRef(
       layout: Layout = DefaultLayout,
       fieldWrapper: FieldWrapper = DefaultFieldWrapper,
       pageWrapper: PageWrapper = DefaultPageWrapper,
-      validateOn
+      validateOn = "blur"
     } = props;
     const forma = useForma({
       spec,
@@ -1012,6 +1018,7 @@ var FormRenderer = forwardRef(
       optionsVisibility: formaOptionsVisibility,
       touched: formaTouched,
       errors: formaErrors,
+      isSubmitted: formaIsSubmitted,
       setFieldValue,
       setFieldTouched,
       getArrayHelpers
@@ -1045,6 +1052,8 @@ var FormRenderer = forwardRef(
         }
         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;
         const schemaProperty = spec.schema.properties[fieldPath];
@@ -1060,6 +1069,7 @@ var FormRenderer = forwardRef(
           required,
           disabled,
           errors,
+          visibleErrors,
           onChange: (value) => setFieldValue(fieldPath, value),
           onBlur: () => setFieldTouched(fieldPath),
           // Convenience properties
@@ -1212,6 +1222,8 @@ var FormRenderer = forwardRef(
         formaOptionsVisibility,
         formaTouched,
         formaErrors,
+        formaIsSubmitted,
+        validateOn,
         setFieldValue,
         setFieldTouched,
         getArrayHelpers
@@ -1238,10 +1250,17 @@ var FormRenderer = forwardRef(
       }
       return /* @__PURE__ */ jsx(Fragment, { children: renderedFields });
     }, [spec.pages, forma.wizard, PageWrapper, renderedFields]);
+    const handleSubmit = useCallback2(
+      (e) => {
+        e == null ? void 0 : e.preventDefault();
+        forma.submitForm();
+      },
+      [forma.submitForm]
+    );
     return /* @__PURE__ */ jsx(FormaContext.Provider, { value: forma, children: /* @__PURE__ */ jsx(
       Layout,
       {
-        onSubmit: forma.submitForm,
+        onSubmit: handleSubmit,
         isSubmitting: forma.isSubmitting,
         isValid: forma.isValid,
         children: content
@@ -1307,6 +1326,7 @@ function FieldRenderer({
   }
   const errors = forma.errors.filter((e) => e.field === fieldPath);
   const touched = forma.touched[fieldPath] ?? false;
+  const visibleErrors = touched || forma.isSubmitted ? errors : [];
   const required = forma.required[fieldPath] ?? false;
   const disabled = forma.enabled[fieldPath] === false;
   const schemaProperty = spec.schema.properties[fieldPath];
@@ -1319,6 +1339,7 @@ function FieldRenderer({
     required,
     disabled,
     errors,
+    visibleErrors,
     onChange: (value) => forma.setFieldValue(fieldPath, value),
     onBlur: () => forma.setFieldTouched(fieldPath),
     // Convenience properties
@@ -1478,9 +1499,13 @@ function FieldRenderer({
     const sourceValue = fieldDef.source ? forma.data[fieldDef.source] ?? forma.computed[fieldDef.source] : void 0;
     const {
       onChange: _onChange,
+      // omit from display props
       value: _value,
+      // omit from display props
       ...displayBaseProps
     } = baseProps;
+    void _onChange;
+    void _value;
     fieldProps = {
       ...displayBaseProps,
       fieldType: "display",