@fogpipe/forma-react 0.12.0 → 0.14.0

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,
@@ -72,6 +140,15 @@ function getDefaultBooleanValues(spec) {
   }
   return defaults;
 }
+function getFieldDefaults(spec) {
+  const defaults = {};
+  for (const [fieldPath, fieldDef] of Object.entries(spec.fields)) {
+    if (fieldDef.defaultValue !== void 0) {
+      defaults[fieldPath] = fieldDef.defaultValue;
+    }
+  }
+  return defaults;
+}
 function useForma(options) {
   const {
     spec: inputSpec,
@@ -80,7 +157,8 @@ function useForma(options) {
     onChange,
     validateOn = "blur",
     referenceData,
-    validationDebounceMs = 0
+    validationDebounceMs = 0,
+    on: onEvents
   } = options;
   const spec = useMemo(() => {
     if (!referenceData) return inputSpec;
@@ -93,8 +171,11 @@ function useForma(options) {
     };
   }, [inputSpec, referenceData]);
   const [state, dispatch] = useReducer(formReducer, {
-    data: { ...getDefaultBooleanValues(spec), ...initialData },
-    // Boolean defaults merged UNDER initialData
+    data: {
+      ...getDefaultBooleanValues(spec),
+      ...getFieldDefaults(spec),
+      ...initialData
+    },
     touched: {},
     isSubmitting: false,
     isSubmitted: false,
@@ -104,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]
@@ -184,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);
@@ -209,19 +342,84 @@ 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 });
-  }, [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;
     const pageVisibility = getPageVisibility(state.data, spec, { computed });
@@ -251,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,
@@ -291,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);
@@ -544,6 +781,10 @@ function useForma(options) {
       optionsVisibility
     ]
   );
+  const on = useCallback(
+    (event, listener) => emitterRef.current.on(event, listener),
+    []
+  );
   return useMemo(
     () => ({
       data: state.data,
@@ -568,6 +809,7 @@ function useForma(options) {
       validateForm,
       submitForm,
       resetForm,
+      on,
       getFieldProps,
       getSelectFieldProps,
       getArrayHelpers
@@ -595,6 +837,7 @@ function useForma(options) {
       validateForm,
       submitForm,
       resetForm,
+      on,
       getFieldProps,
       getSelectFieldProps,
       getArrayHelpers
@@ -618,7 +861,9 @@ var FormaContext = createContext(null);
 function useFormaContext() {
   const context = useContext(FormaContext);
   if (!context) {
-    throw new Error("useFormaContext must be used within a FormaContext.Provider");
+    throw new Error(
+      "useFormaContext must be used within a FormaContext.Provider"
+    );
   }
   return context;
 }
@@ -699,7 +944,9 @@ function getNumberConstraints(schema) {
 function createDefaultItem(itemFields) {
   const item = {};
   for (const [fieldName, fieldDef] of Object.entries(itemFields)) {
-    if (fieldDef.type === "boolean") {
+    if (fieldDef.defaultValue !== void 0) {
+      item[fieldName] = fieldDef.defaultValue;
+    } else if (fieldDef.type === "boolean") {
       item[fieldName] = false;
     } else if (fieldDef.type === "number" || fieldDef.type === "integer") {
       item[fieldName] = null;
@@ -1006,7 +1253,9 @@ function getNumberConstraints2(schema) {
 function createDefaultItem2(itemFields) {
   const item = {};
   for (const [fieldName, fieldDef] of Object.entries(itemFields)) {
-    if (fieldDef.type === "boolean") {
+    if (fieldDef.defaultValue !== void 0) {
+      item[fieldName] = fieldDef.defaultValue;
+    } else if (fieldDef.type === "boolean") {
       item[fieldName] = false;
     } else if (fieldDef.type === "number" || fieldDef.type === "integer") {
       item[fieldName] = null;
@@ -1227,7 +1476,10 @@ function FieldRenderer({
 // src/ErrorBoundary.tsx
 import React3 from "react";
 import { jsx as jsx3, jsxs as jsxs2 } from "react/jsx-runtime";
-function DefaultErrorFallback({ error, onReset }) {
+function DefaultErrorFallback({
+  error,
+  onReset
+}) {
   return /* @__PURE__ */ jsxs2("div", { className: "forma-error-boundary", role: "alert", children: [
     /* @__PURE__ */ jsx3("h3", { children: "Something went wrong" }),
     /* @__PURE__ */ jsx3("p", { children: "An error occurred while rendering the form." }),