@fogpipe/forma-react 0.12.0 → 0.14.0

package/src/context.ts

@@ -17,7 +17,9 @@ export const FormaContext = createContext<UseFormaReturn | null>(null);
 export function useFormaContext(): UseFormaReturn {
   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;
 }

package/src/events.ts

@@ -0,0 +1,186 @@
+/**
+ * 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.
+ */
+
+import type { FieldError } from "@fogpipe/forma-core";
+import type { PageState } from "./useForma.js";
+
+// ============================================================================
+// Event Type Definitions
+// ============================================================================
+
+/**
+ * Map of all forma event names to their payload types.
+ */
+export 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>;
+}
+
+// ============================================================================
+// Helper Types
+// ============================================================================
+
+/**
+ * Listener function type for a specific event.
+ */
+export type FormaEventListener<K extends keyof FormaEventMap> = (
+  event: FormaEventMap[K],
+) => void | Promise<void>;
+
+/**
+ * Declarative event listener map for useForma `on` option.
+ */
+export type FormaEvents = Partial<{
+  [K in keyof FormaEventMap]: FormaEventListener<K>;
+}>;
+
+// ============================================================================
+// Event Emitter
+// ============================================================================
+
+/**
+ * Lightweight event emitter for forma lifecycle events.
+ * Uses Map<string, Set<listener>> internally — no external dependencies.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type AnyListener = (...args: any[]) => void | Promise<void>;
+
+export class FormaEventEmitter {
+  private listeners = new Map<string, Set<AnyListener>>();
+
+  /**
+   * Register a listener for an event. Returns an unsubscribe function.
+   */
+  on<K extends keyof FormaEventMap>(
+    event: K,
+    listener: FormaEventListener<K>,
+  ): () => void {
+    if (!this.listeners.has(event)) {
+      this.listeners.set(event, 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<K extends keyof FormaEventMap>(event: K, payload: FormaEventMap[K]): void {
+    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<K extends keyof FormaEventMap>(
+    event: K,
+    payload: FormaEventMap[K],
+  ): Promise<void> {
+    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: keyof FormaEventMap): boolean {
+    const set = this.listeners.get(event);
+    return set !== undefined && set.size > 0;
+  }
+
+  /**
+   * Remove all listeners. Called on cleanup.
+   */
+  clear(): void {
+    this.listeners.clear();
+  }
+}

package/src/index.ts

@@ -20,7 +20,12 @@ export type {
 
 // Hook
 export { useForma } from "./useForma.js";
-export type { UseFormaOptions, UseFormaReturn, PageState, WizardHelpers } from "./useForma.js";
+export type {
+  UseFormaOptions,
+  UseFormaReturn,
+  PageState,
+  WizardHelpers,
+} from "./useForma.js";
 
 // Components
 export { FormRenderer } from "./FormRenderer.js";
@@ -90,4 +95,9 @@ export type {
   LayoutProps,
   FieldWrapperProps,
   PageWrapperProps,
+
+  // Event types
+  FormaEventMap,
+  FormaEvents,
+  FormaEventListener,
 } from "./types.js";

package/src/types.ts

@@ -2,7 +2,12 @@
  * Type definitions for forma-react components
  */
 
-import type { Forma, FieldDefinition, FieldError, SelectOption } from "@fogpipe/forma-core";
+import type {
+  Forma,
+  FieldDefinition,
+  FieldError,
+  SelectOption,
+} from "@fogpipe/forma-core";
 
 /**
  * Base props shared by all field components
@@ -52,7 +57,10 @@ export interface BaseFieldProps {
 /**
  * Props for text-based fields (text, email, password, url, textarea)
  */
-export interface TextFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface TextFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "text" | "email" | "password" | "url" | "textarea";
   value: string;
   onChange: (value: string) => void;
@@ -61,7 +69,10 @@ export interface TextFieldProps extends Omit<BaseFieldProps, "value" | "onChange
 /**
  * Props for number fields
  */
-export interface NumberFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface NumberFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "number";
   value: number | null;
   onChange: (value: number | null) => void;
@@ -73,7 +84,10 @@ export interface NumberFieldProps extends Omit<BaseFieldProps, "value" | "onChan
 /**
  * Props for integer fields
  */
-export interface IntegerFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface IntegerFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "integer";
   value: number | null;
   onChange: (value: number | null) => void;
@@ -85,7 +99,10 @@ export interface IntegerFieldProps extends Omit<BaseFieldProps, "value" | "onCha
 /**
  * Props for boolean fields
  */
-export interface BooleanFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface BooleanFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "boolean";
   value: boolean;
   onChange: (value: boolean) => void;
@@ -94,7 +111,10 @@ export interface BooleanFieldProps extends Omit<BaseFieldProps, "value" | "onCha
 /**
  * Props for date fields
  */
-export interface DateFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface DateFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "date";
   value: string | null;
   onChange: (value: string | null) => void;
@@ -103,7 +123,10 @@ export interface DateFieldProps extends Omit<BaseFieldProps, "value" | "onChange
 /**
  * Props for datetime fields
  */
-export interface DateTimeFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface DateTimeFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "datetime";
   value: string | null;
   onChange: (value: string | null) => void;
@@ -112,7 +135,10 @@ export interface DateTimeFieldProps extends Omit<BaseFieldProps, "value" | "onCh
 /**
  * Props for select fields (single selection)
  */
-export interface SelectFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface SelectFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "select";
   value: string | null;
   onChange: (value: string | null) => void;
@@ -122,7 +148,10 @@ export interface SelectFieldProps extends Omit<BaseFieldProps, "value" | "onChan
 /**
  * Props for multi-select fields
  */
-export interface MultiSelectFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface MultiSelectFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "multiselect";
   value: string[];
   onChange: (value: string[]) => void;
@@ -189,7 +218,10 @@ export interface ArrayHelpers {
   /** Swap items at two indices */
   swap: (indexA: number, indexB: number) => void;
   /** Get field props for an item field */
-  getItemFieldProps: (index: number, fieldName: string) => ArrayItemFieldPropsResult;
+  getItemFieldProps: (
+    index: number,
+    fieldName: string,
+  ) => ArrayItemFieldPropsResult;
   /** Minimum number of items allowed */
   minItems: number;
   /** Maximum number of items allowed */
@@ -203,7 +235,10 @@ export interface ArrayHelpers {
 /**
  * Props for array fields
  */
-export interface ArrayFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface ArrayFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "array";
   value: unknown[];
   onChange: (value: unknown[]) => void;
@@ -217,7 +252,10 @@ export interface ArrayFieldProps extends Omit<BaseFieldProps, "value" | "onChang
 /**
  * Props for object fields
  */
-export interface ObjectFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface ObjectFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "object";
   value: Record<string, unknown>;
   onChange: (value: Record<string, unknown>) => void;
@@ -236,7 +274,10 @@ export interface ComputedFieldProps extends Omit<BaseFieldProps, "onChange"> {
 /**
  * Props for array item fields (within array context)
  */
-export interface ArrayItemFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface ArrayItemFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   /** The field type */
   fieldType: string;
   /** Current value */
@@ -252,7 +293,10 @@ export interface ArrayItemFieldProps extends Omit<BaseFieldProps, "value" | "onC
 /**
  * Props for display fields (read-only presentation content)
  */
-export interface DisplayFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+export interface DisplayFieldProps extends Omit<
+  BaseFieldProps,
+  "value" | "onChange"
+> {
   fieldType: "display";
   /** Static content (markdown/text) */
   content?: string;
@@ -432,6 +476,13 @@ export type { UseFormaReturn as FormState } from "./useForma.js";
 export type { UseFormaOptions } from "./useForma.js";
 export type { PageState, WizardHelpers } from "./useForma.js";
 
+// Re-export event types
+export type {
+  FormaEventMap,
+  FormaEvents,
+  FormaEventListener,
+} from "./events.js";
+
 // Re-export ValidationResult for convenience
 export type { ValidationResult } from "@fogpipe/forma-core";