@fogpipe/forma-react 0.16.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

@@ -1,4 +1,4 @@
-import { FieldError, SelectOption, FieldDefinition, Forma, OptionsVisibilityResult, ValidationResult } from '@fogpipe/forma-core';
+import { FieldError, SelectOption, FieldDefinition, Forma, MatrixColumn, OptionsVisibilityResult, ValidationResult } from '@fogpipe/forma-core';
 export { ComputedField, FieldDefinition, FieldError, FieldType, Forma, PageDefinition, SelectOption, ValidationResult, ValidationRule } from '@fogpipe/forma-core';
 import * as React$1 from 'react';
 import React__default from 'react';
@@ -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 */
@@ -331,10 +336,29 @@ interface DisplayFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
     onChange?: never;
     value?: never;
 }
+/**
+ * Props for matrix/grid fields
+ */
+interface MatrixFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+    fieldType: "matrix";
+    /** Current matrix value: row ID → selected column value(s) */
+    value: Record<string, string | number | string[] | number[]> | null;
+    onChange: (value: Record<string, string | number | string[] | number[]>) => void;
+    /** Row definitions with visibility state */
+    rows: Array<{
+        id: string;
+        label: string;
+        visible: boolean;
+    }>;
+    /** Column definitions (shared options for all rows) */
+    columns: MatrixColumn[];
+    /** Whether multiple selections per row are allowed */
+    multiSelect: boolean;
+}
 /**
  * Union of all field prop types
  */
-type FieldProps = TextFieldProps | NumberFieldProps | IntegerFieldProps | BooleanFieldProps | DateFieldProps | DateTimeFieldProps | SelectFieldProps | MultiSelectFieldProps | ArrayFieldProps | ObjectFieldProps | ComputedFieldProps | DisplayFieldProps;
+type FieldProps = TextFieldProps | NumberFieldProps | IntegerFieldProps | BooleanFieldProps | DateFieldProps | DateTimeFieldProps | SelectFieldProps | MultiSelectFieldProps | ArrayFieldProps | ObjectFieldProps | ComputedFieldProps | DisplayFieldProps | MatrixFieldProps;
 /**
  * Map of field types to React components
  * Components receive wrapper props with { field, spec } structure
@@ -357,6 +381,7 @@ interface ComponentMap {
     object?: React.ComponentType<ObjectComponentProps>;
     computed?: React.ComponentType<ComputedComponentProps>;
     display?: React.ComponentType<DisplayComponentProps>;
+    matrix?: React.ComponentType<MatrixComponentProps>;
     fallback?: React.ComponentType<FieldComponentProps>;
 }
 /**
@@ -364,7 +389,7 @@ interface ComponentMap {
  */
 interface LayoutProps {
     children: React.ReactNode;
-    onSubmit: () => void;
+    onSubmit: (e?: React.FormEvent) => void;
     isSubmitting: boolean;
     isValid: boolean;
 }
@@ -449,6 +474,10 @@ interface DisplayComponentProps {
     field: DisplayFieldProps;
     spec: Forma;
 }
+interface MatrixComponentProps {
+    field: MatrixFieldProps;
+    spec: Forma;
+}
 /**
  * Generic field component props (for fallback/dynamic components)
  */
@@ -489,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 */
@@ -607,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;
@@ -814,4 +854,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 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 };
+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 MatrixComponentProps, type MatrixFieldProps, 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

@@ -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
@@ -1143,6 +1153,22 @@ var FormRenderer = forwardRef(
             minItems,
             maxItems
           };
+        } else if (fieldType === "matrix" && fieldDef.type === "matrix") {
+          const matrixValue = baseProps.value ?? null;
+          const rows = fieldDef.rows.map((row) => ({
+            id: row.id,
+            label: row.label,
+            visible: formaVisibility[`${fieldPath}.${row.id}`] !== false
+          }));
+          fieldProps = {
+            ...baseProps,
+            fieldType: "matrix",
+            value: matrixValue,
+            onChange: baseProps.onChange,
+            rows,
+            columns: fieldDef.columns,
+            multiSelect: fieldDef.multiSelect ?? false
+          };
         } else if (fieldType === "display" && fieldDef.type === "display") {
           const sourceValue = fieldDef.source ? formaData[fieldDef.source] ?? formaComputed[fieldDef.source] : void 0;
           const {
@@ -1196,6 +1222,8 @@ var FormRenderer = forwardRef(
         formaOptionsVisibility,
         formaTouched,
         formaErrors,
+        formaIsSubmitted,
+        validateOn,
         setFieldValue,
         setFieldTouched,
         getArrayHelpers
@@ -1222,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
@@ -1291,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];
@@ -1303,6 +1339,7 @@ function FieldRenderer({
     required,
     disabled,
     errors,
+    visibleErrors,
     onChange: (value) => forma.setFieldValue(fieldPath, value),
     onBlur: () => forma.setFieldTouched(fieldPath),
     // Convenience properties
@@ -1442,13 +1479,33 @@ function FieldRenderer({
       minItems,
       maxItems
     };
+  } else if (fieldType === "matrix" && fieldDef.type === "matrix") {
+    const matrixValue = baseProps.value ?? null;
+    const rows = fieldDef.rows.map((row) => ({
+      id: row.id,
+      label: row.label,
+      visible: forma.visibility[`${fieldPath}.${row.id}`] !== false
+    }));
+    fieldProps = {
+      ...baseProps,
+      fieldType: "matrix",
+      value: matrixValue,
+      onChange: baseProps.onChange,
+      rows,
+      columns: fieldDef.columns,
+      multiSelect: fieldDef.multiSelect ?? false
+    };
   } else if (fieldType === "display" && fieldDef.type === "display") {
     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",