@fogpipe/forma-react 0.12.0 → 0.14.0

package/README.md

@@ -25,22 +25,28 @@ npm install @fogpipe/forma-core @fogpipe/forma-react
 Components receive `{ field, spec }` props. The `field` object contains all field state and handlers:
 
 ```tsx
-import type { ComponentMap, TextComponentProps, BooleanComponentProps } from '@fogpipe/forma-react';
+import type {
+  ComponentMap,
+  TextComponentProps,
+  BooleanComponentProps,
+} from "@fogpipe/forma-react";
 
 const TextInput = ({ field }: TextComponentProps) => (
   <div>
     <input
       type="text"
-      value={field.value || ''}
+      value={field.value || ""}
       onChange={(e) => field.onChange(e.target.value)}
       onBlur={field.onBlur}
       placeholder={field.placeholder}
-      aria-invalid={field['aria-invalid']}
-      aria-describedby={field['aria-describedby']}
-      aria-required={field['aria-required']}
+      aria-invalid={field["aria-invalid"]}
+      aria-describedby={field["aria-describedby"]}
+      aria-required={field["aria-required"]}
     />
     {field.errors.map((e, i) => (
-      <span key={i} className="error">{e.message}</span>
+      <span key={i} className="error">
+        {e.message}
+      </span>
     ))}
   </div>
 );
@@ -67,21 +73,21 @@ const components: ComponentMap = {
 ### 2. Render the Form
 
 ```tsx
-import { FormRenderer } from '@fogpipe/forma-react';
-import type { Forma } from '@fogpipe/forma-core';
+import { FormRenderer } from "@fogpipe/forma-react";
+import type { Forma } from "@fogpipe/forma-core";
 
 const myForm: Forma = {
   meta: { title: "Contact Us" },
   fields: [
     { id: "name", type: "text", label: "Name", required: true },
     { id: "email", type: "email", label: "Email", required: true },
-    { id: "subscribe", type: "boolean", label: "Subscribe to newsletter" }
-  ]
+    { id: "subscribe", type: "boolean", label: "Subscribe to newsletter" },
+  ],
 };
 
 function App() {
   const handleSubmit = (data: Record<string, unknown>) => {
-    console.log('Submitted:', data);
+    console.log("Submitted:", data);
   };
 
   return (
@@ -99,7 +105,7 @@ function App() {
 For custom rendering, use the `useForma` hook directly:
 
 ```tsx
-import { useForma } from '@fogpipe/forma-react';
+import { useForma } from "@fogpipe/forma-react";
 
 function CustomForm({ spec }: { spec: Forma }) {
   const {
@@ -114,19 +120,24 @@ function CustomForm({ spec }: { spec: Forma }) {
     submitForm,
   } = useForma({
     spec,
-    onSubmit: (data) => console.log(data)
+    onSubmit: (data) => console.log(data),
   });
 
   return (
-    <form onSubmit={(e) => { e.preventDefault(); submitForm(); }}>
-      {spec.fields.map(field => {
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        submitForm();
+      }}
+    >
+      {spec.fields.map((field) => {
         if (!visibility[field.id]) return null;
 
         return (
           <div key={field.id}>
             <label>{field.label}</label>
             <input
-              value={String(data[field.id] || '')}
+              value={String(data[field.id] || "")}
               onChange={(e) => setFieldValue(field.id, e.target.value)}
               onBlur={() => setFieldTouched(field.id)}
             />
@@ -154,11 +165,13 @@ function WizardForm({ spec }: { spec: Forma }) {
   return (
     <div>
       {/* Page indicator */}
-      <div>Page {wizard.currentPageIndex + 1} of {wizard.pages.length}</div>
+      <div>
+        Page {wizard.currentPageIndex + 1} of {wizard.pages.length}
+      </div>
 
       {/* Current page fields */}
-      {wizard.currentPage?.fields.map(fieldId => {
-        const field = spec.fields.find(f => f.id === fieldId);
+      {wizard.currentPage?.fields.map((fieldId) => {
+        const field = spec.fields.find((f) => f.id === fieldId);
         if (!field) return null;
         // Render field...
       })}
@@ -180,20 +193,83 @@ 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
 
-| Prop | Type | Description |
-|------|------|-------------|
-| `spec` | `Forma` | The Forma specification |
-| `components` | `ComponentMap` | Map of field types to components |
-| `initialData` | `Record<string, unknown>` | Initial form values |
-| `onSubmit` | `(data) => void` | Submit handler |
-| `onChange` | `(data, computed) => void` | Change handler |
-| `layout` | `React.ComponentType<LayoutProps>` | Custom layout |
-| `fieldWrapper` | `React.ComponentType<FieldWrapperProps>` | Custom field wrapper |
-| `validateOn` | `"change" \| "blur" \| "submit"` | Validation timing |
+| Prop           | Type                                     | Description                      |
+| -------------- | ---------------------------------------- | -------------------------------- |
+| `spec`         | `Forma`                                  | The Forma specification          |
+| `components`   | `ComponentMap`                           | Map of field types to components |
+| `initialData`  | `Record<string, unknown>`                | Initial form values              |
+| `onSubmit`     | `(data) => void`                         | Submit handler                   |
+| `onChange`     | `(data, computed) => void`               | Change handler                   |
+| `layout`       | `React.ComponentType<LayoutProps>`       | Custom layout                    |
+| `fieldWrapper` | `React.ComponentType<FieldWrapperProps>` | Custom field wrapper             |
+| `validateOn`   | `"change" \| "blur" \| "submit"`         | Validation timing                |
 
 ### FormRenderer Ref
 
@@ -211,55 +287,57 @@ formRef.current?.setValues({ name: "John" });
 
 ### useForma Return Value
 
-| Property | Type | Description |
-|----------|------|-------------|
-| `data` | `Record<string, unknown>` | Current form values |
-| `computed` | `Record<string, unknown>` | Computed field values |
-| `visibility` | `Record<string, boolean>` | Field visibility map |
-| `required` | `Record<string, boolean>` | Field required state |
-| `enabled` | `Record<string, boolean>` | Field enabled state |
-| `errors` | `FieldError[]` | Validation errors |
-| `isValid` | `boolean` | Form validity |
-| `isSubmitting` | `boolean` | Submission in progress |
-| `isDirty` | `boolean` | Any field modified |
-| `wizard` | `WizardHelpers \| null` | Wizard navigation |
+| Property       | Type                      | Description            |
+| -------------- | ------------------------- | ---------------------- |
+| `data`         | `Record<string, unknown>` | Current form values    |
+| `computed`     | `Record<string, unknown>` | Computed field values  |
+| `visibility`   | `Record<string, boolean>` | Field visibility map   |
+| `required`     | `Record<string, boolean>` | Field required state   |
+| `enabled`      | `Record<string, boolean>` | Field enabled state    |
+| `errors`       | `FieldError[]`            | Validation errors      |
+| `isValid`      | `boolean`                 | Form validity          |
+| `isSubmitting` | `boolean`                 | Submission in progress |
+| `isDirty`      | `boolean`                 | Any field modified     |
+| `wizard`       | `WizardHelpers \| null`   | Wizard navigation      |
 
 ### 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
 
 Wrap forms with `FormaErrorBoundary` to catch render errors gracefully:
 
 ```tsx
-import { FormRenderer, FormaErrorBoundary } from '@fogpipe/forma-react';
+import { FormRenderer, FormaErrorBoundary } from "@fogpipe/forma-react";
 
 function App() {
   return (
     <FormaErrorBoundary
       fallback={<div>Something went wrong with the form</div>}
-      onError={(error) => console.error('Form error:', error)}
+      onError={(error) => console.error("Form error:", error)}
     >
       <FormRenderer spec={myForm} components={components} />
     </FormaErrorBoundary>
@@ -268,6 +346,7 @@ function App() {
 ```
 
 The error boundary supports:
+
 - Custom fallback UI (static or function)
 - `onError` callback for logging
 - `resetKey` prop to reset error state

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 };