@fogpipe/forma-react 0.13.0 → 0.14.0

package/README.md

@@ -193,6 +193,69 @@ function WizardForm({ spec }: { spec: Forma }) {
 }
 ```
 
+## Event System
+
+The event system lets you observe form lifecycle events for side effects like analytics, data injection, and external state sync. Events do not trigger React re-renders.
+
+### 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                     |
+
+### Declarative Registration
+
+Pass listeners via the `on` option — callbacks are stable (ref-based):
+
+```tsx
+const forma = useForma({
+  spec,
+  onSubmit: handleSubmit,
+  on: {
+    fieldChanged: (event) => {
+      analytics.track("field_changed", { path: event.path, source: event.source });
+    },
+    preSubmit: async (event) => {
+      event.data.token = await getCSRFToken();
+    },
+    postSubmit: (event) => {
+      if (event.success) router.push("/thank-you");
+    },
+  },
+});
+```
+
+### Imperative Registration
+
+Register listeners dynamically — returns an unsubscribe function:
+
+```tsx
+const forma = useForma({ spec, onSubmit: handleSubmit });
+
+useEffect(() => {
+  const unsubscribe = forma.on("fieldChanged", (event) => {
+    console.log(`${event.path}: ${event.previousValue} → ${event.value}`);
+  });
+  return unsubscribe;
+}, [forma]);
+```
+
+### Event Payloads
+
+**`fieldChanged`**: `{ path, value, previousValue, source }` where `source` is `'user' | 'reset' | 'setValues'`
+
+**`preSubmit`**: `{ data, computed }` — mutate `data` to inject fields before validation
+
+**`postSubmit`**: `{ data, success, error?, validationErrors? }`
+
+**`pageChanged`**: `{ fromIndex, toIndex, page }`
+
+**`formReset`**: `{}` (no payload)
+
 ## API Reference
 
 ### FormRenderer Props
@@ -239,15 +302,16 @@ 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
 
@@ -260,6 +324,7 @@ formRef.current?.setValues({ name: "John" });
 | `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

@@ -4,6 +4,84 @@ import * as React$1 from 'react';
 import React__default from 'react';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 
+/**
+ * Event system for forma-react
+ *
+ * Lightweight event emitter for form lifecycle events.
+ * Events are for side effects (analytics, data injection, external state sync)
+ * — they do not trigger React re-renders.
+ */
+
+/**
+ * Map of all forma event names to their payload types.
+ */
+interface FormaEventMap {
+    /**
+     * Fires after a field value changes via user input, setFieldValue, setValues, or resetForm.
+     * Does NOT fire for computed/calculated field changes or on initial mount.
+     */
+    fieldChanged: {
+        /** Field path (e.g., "age" or "medications[0].dosage") */
+        path: string;
+        /** New value */
+        value: unknown;
+        /** Value before the change */
+        previousValue: unknown;
+        /** What triggered the change */
+        source: "user" | "reset" | "setValues";
+    };
+    /**
+     * Fires at the start of submitForm(), before validation.
+     * The `data` object is mutable — consumers can inject extra fields.
+     * Async handlers are awaited before proceeding to validation.
+     */
+    preSubmit: {
+        /** Mutable form data — add/modify fields here */
+        data: Record<string, unknown>;
+        /** Read-only snapshot of computed values */
+        computed: Record<string, unknown>;
+    };
+    /**
+     * Fires after onSubmit resolves/rejects or after validation failure.
+     */
+    postSubmit: {
+        /** The submitted data (reflects any preSubmit mutations) */
+        data: Record<string, unknown>;
+        /** Whether submission succeeded */
+        success: boolean;
+        /** Present when onSubmit threw an error */
+        error?: Error;
+        /** Present when validation failed (onSubmit was never called) */
+        validationErrors?: FieldError[];
+    };
+    /**
+     * Fires when the wizard page changes via nextPage, previousPage, or goToPage.
+     * Does NOT fire on initial render or automatic page clamping.
+     */
+    pageChanged: {
+        /** Previous page index */
+        fromIndex: number;
+        /** New page index */
+        toIndex: number;
+        /** The new current page */
+        page: PageState;
+    };
+    /**
+     * Fires after resetForm() completes and state is back to initial values.
+     */
+    formReset: Record<string, never>;
+}
+/**
+ * Listener function type for a specific event.
+ */
+type FormaEventListener<K extends keyof FormaEventMap> = (event: FormaEventMap[K]) => void | Promise<void>;
+/**
+ * Declarative event listener map for useForma `on` option.
+ */
+type FormaEvents = Partial<{
+    [K in keyof FormaEventMap]: FormaEventListener<K>;
+}>;
+
 /**
  * Type definitions for forma-react components
  */
@@ -499,6 +577,12 @@ interface UseFormaOptions {
      * Set to 0 (default) for immediate validation.
      */
     validationDebounceMs?: number;
+    /**
+     * Declarative event listeners for form lifecycle events.
+     * Listeners are stable for the lifetime of the hook — the latest
+     * callback is always invoked via refs, without causing dependency changes.
+     */
+    on?: FormaEvents;
 }
 /**
  * Page state for multi-page forms
@@ -575,6 +659,11 @@ interface UseFormaReturn {
     submitForm: () => Promise<void>;
     /** Reset the form */
     resetForm: () => void;
+    /**
+     * Register an imperative event listener. Returns an unsubscribe function.
+     * Multiple listeners per event are supported; they fire in registration order.
+     */
+    on: <K extends keyof FormaEventMap>(event: K, listener: (payload: FormaEventMap[K]) => void | Promise<void>) => () => void;
     /** Get props for any field */
     getFieldProps: (path: string) => GetFieldPropsResult;
     /** Get props for select field (includes options) */
@@ -722,4 +811,4 @@ declare const FormaContext: React$1.Context<UseFormaReturn | null>;
  */
 declare function useFormaContext(): UseFormaReturn;
 
-export { type ArrayComponentProps, type ArrayFieldProps, type ArrayHelpers, type ArrayItemFieldProps, type ArrayItemFieldPropsResult, type BaseFieldProps, type BooleanComponentProps, type BooleanFieldProps, type ComponentMap, type ComputedComponentProps, type ComputedFieldProps, type DateComponentProps, type DateFieldProps, type DateTimeComponentProps, type DateTimeFieldProps, type DisplayComponentProps, type DisplayFieldProps, type FieldComponentProps, type FieldProps, FieldRenderer, type FieldRendererProps, type FieldWrapperProps, FormRenderer, type FormRendererHandle, type FormRendererProps, type UseFormaReturn as FormState, FormaContext, FormaErrorBoundary, type FormaErrorBoundaryProps, type GetArrayHelpersResult, type GetFieldPropsResult, type GetSelectFieldPropsResult, type IntegerComponentProps, type IntegerFieldProps, type LayoutProps, type LegacyFieldProps, type MultiSelectComponentProps, type MultiSelectFieldProps, type NumberComponentProps, type NumberFieldProps, type ObjectComponentProps, type ObjectFieldProps, type PageState, type PageWrapperProps, type SelectComponentProps, type SelectFieldProps, type SelectionFieldProps, type TextComponentProps, type TextFieldProps, type UseFormaOptions, type UseFormaReturn, type WizardHelpers, useForma, useFormaContext };
+export { type ArrayComponentProps, type ArrayFieldProps, type ArrayHelpers, type ArrayItemFieldProps, type ArrayItemFieldPropsResult, type BaseFieldProps, type BooleanComponentProps, type BooleanFieldProps, type ComponentMap, type ComputedComponentProps, type ComputedFieldProps, type DateComponentProps, type DateFieldProps, type DateTimeComponentProps, type DateTimeFieldProps, type DisplayComponentProps, type DisplayFieldProps, type FieldComponentProps, type FieldProps, FieldRenderer, type FieldRendererProps, type FieldWrapperProps, FormRenderer, type FormRendererHandle, type FormRendererProps, type UseFormaReturn as FormState, FormaContext, FormaErrorBoundary, type FormaErrorBoundaryProps, type FormaEventListener, type FormaEventMap, type FormaEvents, type GetArrayHelpersResult, type GetFieldPropsResult, type GetSelectFieldPropsResult, type IntegerComponentProps, type IntegerFieldProps, type LayoutProps, type LegacyFieldProps, type MultiSelectComponentProps, type MultiSelectFieldProps, type NumberComponentProps, type NumberFieldProps, type ObjectComponentProps, type ObjectFieldProps, type PageState, type PageWrapperProps, type SelectComponentProps, type SelectFieldProps, type SelectionFieldProps, type TextComponentProps, type TextFieldProps, type UseFormaOptions, type UseFormaReturn, type WizardHelpers, useForma, useFormaContext };

package/dist/index.js

@@ -8,6 +8,74 @@ import {
   useState
 } from "react";
 import { isAdornableField } from "@fogpipe/forma-core";
+
+// src/events.ts
+var FormaEventEmitter = class {
+  listeners = /* @__PURE__ */ new Map();
+  /**
+   * Register a listener for an event. Returns an unsubscribe function.
+   */
+  on(event, listener) {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, /* @__PURE__ */ new Set());
+    }
+    this.listeners.get(event).add(listener);
+    return () => {
+      const set = this.listeners.get(event);
+      if (set) {
+        set.delete(listener);
+        if (set.size === 0) {
+          this.listeners.delete(event);
+        }
+      }
+    };
+  }
+  /**
+   * Fire an event synchronously. Listener errors are caught and logged
+   * to prevent one listener from breaking others.
+   */
+  fire(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) return;
+    for (const listener of set) {
+      try {
+        listener(payload);
+      } catch (error) {
+        console.error(`[forma] Error in "${event}" event listener:`, error);
+      }
+    }
+  }
+  /**
+   * Fire an event and await all async listeners sequentially.
+   * Used for preSubmit where handlers can be async.
+   */
+  async fireAsync(event, payload) {
+    const set = this.listeners.get(event);
+    if (!set || set.size === 0) return;
+    for (const listener of set) {
+      try {
+        await listener(payload);
+      } catch (error) {
+        console.error(`[forma] Error in "${event}" event listener:`, error);
+      }
+    }
+  }
+  /**
+   * Check if any listeners are registered for an event.
+   */
+  hasListeners(event) {
+    const set = this.listeners.get(event);
+    return set !== void 0 && set.size > 0;
+  }
+  /**
+   * Remove all listeners. Called on cleanup.
+   */
+  clear() {
+    this.listeners.clear();
+  }
+};
+
+// src/useForma.ts
 import {
   getVisibility,
   getRequired,
@@ -89,7 +157,8 @@ function useForma(options) {
     onChange,
     validateOn = "blur",
     referenceData,
-    validationDebounceMs = 0
+    validationDebounceMs = 0,
+    on: onEvents
   } = options;
   const spec = useMemo(() => {
     if (!referenceData) return inputSpec;
@@ -116,6 +185,30 @@ function useForma(options) {
   const stateDataRef = useRef(state.data);
   stateDataRef.current = state.data;
   const hasInitialized = useRef(false);
+  const emitterRef = useRef(new FormaEventEmitter());
+  const onEventsRef = useRef(onEvents);
+  onEventsRef.current = onEvents;
+  const pendingEventsRef = useRef([]);
+  const isFiringEventsRef = useRef(false);
+  useEffect(() => {
+    const emitter = emitterRef.current;
+    return () => {
+      emitter.clear();
+    };
+  }, []);
+  const fireEvent = useCallback(
+    (event, payload) => {
+      var _a;
+      try {
+        const handler = (_a = onEventsRef.current) == null ? void 0 : _a[event];
+        if (handler) handler(payload);
+      } catch (error) {
+        console.error(`[forma] Error in "${event}" event handler:`, error);
+      }
+      emitterRef.current.fire(event, payload);
+    },
+    []
+  );
   const computed = useMemo(
     () => calculate(state.data, spec),
     [state.data, spec]
@@ -196,21 +289,49 @@ function useForma(options) {
     },
     [state.data]
   );
+  const getValueAtPath = useCallback((path) => {
+    const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".");
+    let value = stateDataRef.current;
+    for (const part of parts) {
+      if (value === null || value === void 0) return void 0;
+      value = value[part];
+    }
+    return value;
+  }, []);
+  const queueFieldChangedEvent = useCallback(
+    (path, value, source) => {
+      if (isFiringEventsRef.current) return;
+      const previousValue = getValueAtPath(path);
+      if (previousValue === value) return;
+      pendingEventsRef.current.push({
+        event: "fieldChanged",
+        payload: { path, value, previousValue, source }
+      });
+    },
+    [getValueAtPath]
+  );
   const setFieldValue = useCallback(
     (path, value) => {
+      queueFieldChangedEvent(path, value, "user");
       setNestedValue(path, value);
       if (validateOn === "change") {
         dispatch({ type: "SET_FIELD_TOUCHED", field: path, touched: true });
       }
     },
-    [validateOn, setNestedValue]
+    [validateOn, setNestedValue, queueFieldChangedEvent]
   );
   const setFieldTouched = useCallback((path, touched = true) => {
     dispatch({ type: "SET_FIELD_TOUCHED", field: path, touched });
   }, []);
-  const setValues = useCallback((values) => {
-    dispatch({ type: "SET_VALUES", values });
-  }, []);
+  const setValues = useCallback(
+    (values) => {
+      for (const [key, value] of Object.entries(values)) {
+        queueFieldChangedEvent(key, value, "setValues");
+      }
+      dispatch({ type: "SET_VALUES", values });
+    },
+    [queueFieldChangedEvent]
+  );
   const validateField = useCallback(
     (path) => {
       return validation.errors.filter((e) => e.field === path);
@@ -221,25 +342,83 @@ function useForma(options) {
     return validation;
   }, [validation]);
   const submitForm = useCallback(async () => {
+    var _a;
     dispatch({ type: "SET_SUBMITTING", isSubmitting: true });
+    const submissionData = { ...state.data };
+    let postSubmitPayload;
     try {
-      if (immediateValidation.valid && onSubmit) {
-        await onSubmit(state.data);
+      const preSubmitPayload = {
+        data: submissionData,
+        computed: { ...computed }
+      };
+      const declarativePreSubmit = (_a = onEventsRef.current) == null ? void 0 : _a.preSubmit;
+      if (declarativePreSubmit) {
+        await declarativePreSubmit(preSubmitPayload);
+      }
+      if (emitterRef.current.hasListeners("preSubmit")) {
+        await emitterRef.current.fireAsync("preSubmit", preSubmitPayload);
+      }
+      if (!immediateValidation.valid) {
+        postSubmitPayload = {
+          data: submissionData,
+          success: false,
+          validationErrors: immediateValidation.errors
+        };
+      } else if (onSubmit) {
+        try {
+          await onSubmit(submissionData);
+          postSubmitPayload = { data: submissionData, success: true };
+        } catch (error) {
+          postSubmitPayload = {
+            data: submissionData,
+            success: false,
+            error: error instanceof Error ? error : new Error(String(error))
+          };
+        }
+      } else {
+        postSubmitPayload = { data: submissionData, success: true };
       }
       dispatch({ type: "SET_SUBMITTED", isSubmitted: true });
     } finally {
       dispatch({ type: "SET_SUBMITTING", isSubmitting: false });
+      if (postSubmitPayload) {
+        fireEvent("postSubmit", postSubmitPayload);
+      }
     }
-  }, [immediateValidation, onSubmit, state.data]);
+  }, [immediateValidation, onSubmit, state.data, computed, fireEvent]);
   const resetForm = useCallback(() => {
-    dispatch({
-      type: "RESET",
-      initialData: {
-        ...getDefaultBooleanValues(spec),
-        ...getFieldDefaults(spec),
-        ...initialData
+    const resetData = {
+      ...getDefaultBooleanValues(spec),
+      ...getFieldDefaults(spec),
+      ...initialData
+    };
+    if (!isFiringEventsRef.current) {
+      const currentData = stateDataRef.current;
+      const allKeys = /* @__PURE__ */ new Set([
+        ...Object.keys(currentData),
+        ...Object.keys(resetData)
+      ]);
+      for (const key of allKeys) {
+        const currentVal = currentData[key];
+        const resetVal = resetData[key];
+        if (currentVal !== resetVal) {
+          pendingEventsRef.current.push({
+            event: "fieldChanged",
+            payload: {
+              path: key,
+              value: resetVal,
+              previousValue: currentVal,
+              source: "reset"
+            }
+          });
+        }
       }
-    });
+      pendingEventsRef.current.push({
+        event: "formReset",
+        payload: {}
+      });
+    }
+    dispatch({ type: "RESET", initialData: resetData });
   }, [spec, initialData]);
   const wizard = useMemo(() => {
     if (!spec.pages || spec.pages.length === 0) return null;
@@ -270,16 +449,44 @@ function useForma(options) {
       currentPage,
       goToPage: (index) => {
         const validIndex = Math.min(Math.max(0, index), maxPageIndex);
-        dispatch({ type: "SET_PAGE", page: validIndex });
+        if (validIndex !== clampedPageIndex) {
+          dispatch({ type: "SET_PAGE", page: validIndex });
+          const newPage = visiblePages[validIndex];
+          if (newPage) {
+            fireEvent("pageChanged", {
+              fromIndex: clampedPageIndex,
+              toIndex: validIndex,
+              page: newPage
+            });
+          }
+        }
       },
       nextPage: () => {
         if (hasNextPage) {
-          dispatch({ type: "SET_PAGE", page: clampedPageIndex + 1 });
+          const toIndex = clampedPageIndex + 1;
+          dispatch({ type: "SET_PAGE", page: toIndex });
+          const newPage = visiblePages[toIndex];
+          if (newPage) {
+            fireEvent("pageChanged", {
+              fromIndex: clampedPageIndex,
+              toIndex,
+              page: newPage
+            });
+          }
         }
       },
       previousPage: () => {
         if (hasPreviousPage) {
-          dispatch({ type: "SET_PAGE", page: clampedPageIndex - 1 });
+          const toIndex = clampedPageIndex - 1;
+          dispatch({ type: "SET_PAGE", page: toIndex });
+          const newPage = visiblePages[toIndex];
+          if (newPage) {
+            fireEvent("pageChanged", {
+              fromIndex: clampedPageIndex,
+              toIndex,
+              page: newPage
+            });
+          }
         }
       },
       hasNextPage,
@@ -310,40 +517,51 @@ function useForma(options) {
         return pageErrors.length === 0;
       }
     };
-  }, [spec, state.data, state.currentPage, computed, validation, visibility]);
-  const getValueAtPath = useCallback((path) => {
-    const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".");
-    let value = stateDataRef.current;
-    for (const part of parts) {
-      if (value === null || value === void 0) return void 0;
-      value = value[part];
-    }
-    return value;
-  }, []);
-  const setValueAtPath = useCallback((path, value) => {
-    const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".");
-    if (parts.length === 1) {
-      dispatch({ type: "SET_FIELD_VALUE", field: path, value });
-      return;
-    }
-    const newData = { ...stateDataRef.current };
-    let current = newData;
-    for (let i = 0; i < parts.length - 1; i++) {
-      const part = parts[i];
-      const nextPart = parts[i + 1];
-      const isNextArrayIndex = /^\d+$/.test(nextPart);
-      if (current[part] === void 0) {
-        current[part] = isNextArrayIndex ? [] : {};
-      } else if (Array.isArray(current[part])) {
-        current[part] = [...current[part]];
-      } else {
-        current[part] = { ...current[part] };
+  }, [spec, state.data, state.currentPage, computed, validation, visibility, fireEvent]);
+  useEffect(() => {
+    const events = pendingEventsRef.current;
+    if (events.length === 0) return;
+    pendingEventsRef.current = [];
+    isFiringEventsRef.current = true;
+    try {
+      for (const pending of events) {
+        fireEvent(
+          pending.event,
+          pending.payload
+        );
       }
-      current = current[part];
+    } finally {
+      isFiringEventsRef.current = false;
     }
-    current[parts[parts.length - 1]] = value;
-    dispatch({ type: "SET_VALUES", values: newData });
-  }, []);
+  });
+  const setValueAtPath = useCallback(
+    (path, value) => {
+      queueFieldChangedEvent(path, value, "user");
+      const parts = path.replace(/\[(\d+)\]/g, ".$1").split(".");
+      if (parts.length === 1) {
+        dispatch({ type: "SET_FIELD_VALUE", field: path, value });
+        return;
+      }
+      const newData = { ...stateDataRef.current };
+      let current = newData;
+      for (let i = 0; i < parts.length - 1; i++) {
+        const part = parts[i];
+        const nextPart = parts[i + 1];
+        const isNextArrayIndex = /^\d+$/.test(nextPart);
+        if (current[part] === void 0) {
+          current[part] = isNextArrayIndex ? [] : {};
+        } else if (Array.isArray(current[part])) {
+          current[part] = [...current[part]];
+        } else {
+          current[part] = { ...current[part] };
+        }
+        current = current[part];
+      }
+      current[parts[parts.length - 1]] = value;
+      dispatch({ type: "SET_VALUES", values: newData });
+    },
+    [queueFieldChangedEvent]
+  );
   const fieldHandlers = useRef(/* @__PURE__ */ new Map());
   useEffect(() => {
     const validFields = new Set(spec.fieldOrder);
@@ -563,6 +781,10 @@ function useForma(options) {
       optionsVisibility
     ]
   );
+  const on = useCallback(
+    (event, listener) => emitterRef.current.on(event, listener),
+    []
+  );
   return useMemo(
     () => ({
       data: state.data,
@@ -587,6 +809,7 @@ function useForma(options) {
       validateForm,
       submitForm,
       resetForm,
+      on,
       getFieldProps,
       getSelectFieldProps,
       getArrayHelpers
@@ -614,6 +837,7 @@ function useForma(options) {
       validateForm,
       submitForm,
       resetForm,
+      on,
       getFieldProps,
       getSelectFieldProps,
       getArrayHelpers