@fogpipe/forma-react 0.11.2 → 0.12.0-alpha.2

package/src/FormRenderer.tsx

@@ -5,11 +5,36 @@
  * Supports single-page and multi-page (wizard) forms.
  */
 
-import React, { forwardRef, useImperativeHandle, useRef, useMemo, useCallback } from "react";
-import type { Forma, FieldDefinition, ValidationResult, JSONSchemaProperty, SelectOption } from "@fogpipe/forma-core";
+import React, {
+  forwardRef,
+  useImperativeHandle,
+  useRef,
+  useMemo,
+  useCallback,
+} from "react";
+import type {
+  Forma,
+  FieldDefinition,
+  ValidationResult,
+  JSONSchemaProperty,
+  SelectOption,
+} from "@fogpipe/forma-core";
+import { isAdornableField, isSelectionField } from "@fogpipe/forma-core";
 import { useForma } from "./useForma.js";
 import { FormaContext } from "./context.js";
-import type { ComponentMap, LayoutProps, FieldWrapperProps, PageWrapperProps, BaseFieldProps, TextFieldProps, NumberFieldProps, SelectFieldProps, ArrayFieldProps, ArrayHelpers } from "./types.js";
+import type {
+  ComponentMap,
+  LayoutProps,
+  FieldWrapperProps,
+  PageWrapperProps,
+  BaseFieldProps,
+  TextFieldProps,
+  NumberFieldProps,
+  SelectFieldProps,
+  ArrayFieldProps,
+  ArrayHelpers,
+  DisplayFieldProps,
+} from "./types.js";
 
 /**
  * Props for FormRenderer component
@@ -22,7 +47,10 @@ export interface FormRendererProps {
   /** Submit handler */
   onSubmit?: (data: Record<string, unknown>) => void | Promise<void>;
   /** Change handler */
-  onChange?: (data: Record<string, unknown>, computed?: Record<string, unknown>) => void;
+  onChange?: (
+    data: Record<string, unknown>,
+    computed?: Record<string, unknown>,
+  ) => void;
   /** Component map for rendering fields */
   components: ComponentMap;
   /** Custom layout component */
@@ -74,11 +102,20 @@ function DefaultLayout({ children, onSubmit, isSubmitting }: LayoutProps) {
 /**
  * Default field wrapper component with accessibility support
  */
-function DefaultFieldWrapper({ fieldPath, field, children, errors, showRequiredIndicator, visible }: FieldWrapperProps) {
+function DefaultFieldWrapper({
+  fieldPath,
+  field,
+  children,
+  errors,
+  showRequiredIndicator,
+  visible,
+}: FieldWrapperProps) {
   if (!visible) return null;
 
   const errorId = `${fieldPath}-error`;
-  const descriptionId = field.description ? `${fieldPath}-description` : undefined;
+  const descriptionId = field.description
+    ? `${fieldPath}-description`
+    : undefined;
   const hasErrors = errors.length > 0;
 
   return (
@@ -86,8 +123,14 @@ function DefaultFieldWrapper({ fieldPath, field, children, errors, showRequiredI
       {field.label && (
         <label htmlFor={fieldPath}>
           {field.label}
-          {showRequiredIndicator && <span className="required" aria-hidden="true">*</span>}
-          {showRequiredIndicator && <span className="sr-only"> (required)</span>}
+          {showRequiredIndicator && (
+            <span className="required" aria-hidden="true">
+              *
+            </span>
+          )}
+          {showRequiredIndicator && (
+            <span className="sr-only"> (required)</span>
+          )}
         </label>
       )}
       {children}
@@ -117,7 +160,11 @@ function DefaultFieldWrapper({ fieldPath, field, children, errors, showRequiredI
 /**
  * Default page wrapper component
  */
-function DefaultPageWrapper({ title, description, children }: PageWrapperProps) {
+function DefaultPageWrapper({
+  title,
+  description,
+  children,
+}: PageWrapperProps) {
   return (
     <div className="page-wrapper">
       <h2>{title}</h2>
@@ -130,13 +177,23 @@ function DefaultPageWrapper({ title, description, children }: PageWrapperProps)
 /**
  * Extract numeric constraints from JSON Schema property
  */
-function getNumberConstraints(schema?: JSONSchemaProperty): { min?: number; max?: number; step?: number } {
+function getNumberConstraints(schema?: JSONSchemaProperty): {
+  min?: number;
+  max?: number;
+  step?: number;
+} {
   if (!schema) return {};
   if (schema.type !== "number" && schema.type !== "integer") return {};
 
   // Extract min/max from schema
-  const min = "minimum" in schema && typeof schema.minimum === "number" ? schema.minimum : undefined;
-  const max = "maximum" in schema && typeof schema.maximum === "number" ? schema.maximum : undefined;
+  const min =
+    "minimum" in schema && typeof schema.minimum === "number"
+      ? schema.minimum
+      : undefined;
+  const max =
+    "maximum" in schema && typeof schema.maximum === "number"
+      ? schema.maximum
+      : undefined;
 
   // Use multipleOf for step if defined, otherwise default to 1 for integers
   let step: number | undefined;
@@ -152,7 +209,9 @@ function getNumberConstraints(schema?: JSONSchemaProperty): { min?: number; max?
 /**
  * Create a default item for an array field based on item field definitions
  */
-function createDefaultItem(itemFields: Record<string, FieldDefinition>): Record<string, unknown> {
+function createDefaultItem(
+  itemFields: Record<string, FieldDefinition>,
+): Record<string, unknown> {
   const item: Record<string, unknown> = {};
   for (const [fieldName, fieldDef] of Object.entries(itemFields)) {
     if (fieldDef.type === "boolean") {
@@ -221,9 +280,27 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
         isValid: forma.isValid,
         isDirty: forma.isDirty,
       }),
-      [forma, focusField, focusFirstError]
+      [forma, focusField, focusFirstError],
     );
 
+    // Destructure only the values renderField needs from forma.
+    // This prevents renderField from recreating when unrelated state changes
+    // (isSubmitting, isDirty, wizard page navigation, etc.)
+    const {
+      data: formaData,
+      computed: formaComputed,
+      visibility: formaVisibility,
+      required: formaRequired,
+      enabled: formaEnabled,
+      readonly: formaReadonly,
+      optionsVisibility: formaOptionsVisibility,
+      touched: formaTouched,
+      errors: formaErrors,
+      setFieldValue,
+      setFieldTouched,
+      getArrayHelpers,
+    } = forma;
+
     // Determine which fields to render based on pages or fieldOrder
     const fieldsToRender = useMemo(() => {
       if (spec.pages && spec.pages.length > 0 && forma.wizard) {
@@ -240,161 +317,248 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
     }, [spec.pages, spec.fieldOrder, forma.wizard]);
 
     // Render a single field (memoized)
-    const renderField = useCallback((fieldPath: string) => {
-      const fieldDef = spec.fields[fieldPath];
-      if (!fieldDef) return null;
-
-      const isVisible = forma.visibility[fieldPath] !== false;
-      if (!isVisible) return null;
+    const renderField = useCallback(
+      (fieldPath: string) => {
+        const fieldDef = spec.fields[fieldPath];
+        if (!fieldDef) return null;
+
+        const isVisible = formaVisibility[fieldPath] !== false;
+        if (!isVisible) {
+          return <div key={fieldPath} data-field-path={fieldPath} hidden />;
+        }
 
-      // Infer field type
-      const fieldType = fieldDef.type || (fieldDef.itemFields ? "array" : "text");
-      const componentKey = fieldType as keyof ComponentMap;
-      const Component = components[componentKey] || components.fallback;
+        // Get field type (type is required on all field definitions)
+        const fieldType = fieldDef.type;
+        const componentKey = fieldType as keyof ComponentMap;
+        const Component = components[componentKey] || components.fallback;
 
-      if (!Component) {
-        console.warn(`No component found for field type: ${fieldType}`);
-        return null;
-      }
+        if (!Component) {
+          console.warn(`No component found for field type: ${fieldType}`);
+          return null;
+        }
 
-      const errors = forma.errors.filter((e) => e.field === fieldPath);
-      const touched = forma.touched[fieldPath] ?? false;
-      const required = forma.required[fieldPath] ?? false;
-      const disabled = forma.enabled[fieldPath] === false;
-
-      // Get schema property for additional constraints
-      const schemaProperty = spec.schema.properties[fieldPath];
-
-      // Boolean fields: hide asterisk unless they have validation rules (consent pattern)
-      // - Binary question ("Do you smoke?"): no validation → false is valid → hide asterisk
-      // - Consent checkbox ("I accept terms"): has validation rule → show asterisk
-      const isBooleanField = schemaProperty?.type === "boolean" || fieldDef?.type === "boolean";
-      const hasValidationRules = (fieldDef?.validations?.length ?? 0) > 0;
-      const showRequiredIndicator = required && (!isBooleanField || hasValidationRules);
-
-      // Base field props
-      const baseProps: BaseFieldProps = {
-        name: fieldPath,
-        field: fieldDef,
-        value: forma.data[fieldPath],
-        touched,
-        required,
-        disabled,
-        errors,
-        onChange: (value: unknown) => forma.setFieldValue(fieldPath, value),
-        onBlur: () => forma.setFieldTouched(fieldPath),
-        // Convenience properties
-        visible: true, // Always true since we already filtered for visibility
-        enabled: !disabled,
-        label: fieldDef.label ?? fieldPath,
-        description: fieldDef.description,
-        placeholder: fieldDef.placeholder,
-      };
-
-      // Build type-specific props
-      let fieldProps: BaseFieldProps | TextFieldProps | NumberFieldProps | SelectFieldProps | ArrayFieldProps = baseProps;
-
-      if (fieldType === "number" || fieldType === "integer") {
-        const constraints = getNumberConstraints(schemaProperty);
-        fieldProps = {
-          ...baseProps,
-          fieldType,
-          value: baseProps.value as number | null,
-          onChange: baseProps.onChange as (value: number | null) => void,
-          ...constraints,
-        } as NumberFieldProps;
-      } else if (fieldType === "select" || fieldType === "multiselect") {
-        fieldProps = {
-          ...baseProps,
-          fieldType,
-          value: baseProps.value as string | string[] | null,
-          onChange: baseProps.onChange as (value: string | string[] | null) => void,
-          options: forma.optionsVisibility[fieldPath] ?? fieldDef.options ?? [],
-        } as SelectFieldProps;
-      } else if (fieldType === "array" && fieldDef.itemFields) {
-        const arrayValue = Array.isArray(baseProps.value) ? baseProps.value : [];
-        const minItems = fieldDef.minItems ?? 0;
-        const maxItems = fieldDef.maxItems ?? Infinity;
-        const itemFieldDefs = fieldDef.itemFields;
-
-        // Get helpers from useForma - these are fresh on each render, avoiding stale closures
-        const baseHelpers = forma.getArrayHelpers(fieldPath);
-
-        // Wrap push to add default item creation when called without arguments
-        const pushWithDefault = (item?: unknown): void => {
-          const newItem = item ?? createDefaultItem(itemFieldDefs);
-          baseHelpers.push(newItem);
+        const errors = formaErrors.filter((e) => e.field === fieldPath);
+        const touched = formaTouched[fieldPath] ?? false;
+        const required = formaRequired[fieldPath] ?? false;
+        const disabled = formaEnabled[fieldPath] === false;
+
+        // Get schema property for additional constraints
+        const schemaProperty = spec.schema.properties[fieldPath];
+
+        // Boolean fields: hide asterisk unless they have validation rules (consent pattern)
+        // - Binary question ("Do you smoke?"): no validation → false is valid → hide asterisk
+        // - Consent checkbox ("I accept terms"): has validation rule → show asterisk
+        const isBooleanField =
+          schemaProperty?.type === "boolean" || fieldDef?.type === "boolean";
+        const hasValidationRules = (fieldDef?.validations?.length ?? 0) > 0;
+        const showRequiredIndicator =
+          required && (!isBooleanField || hasValidationRules);
+
+        // Base field props
+        const isReadonly = formaReadonly[fieldPath] ?? false;
+        const baseProps: BaseFieldProps = {
+          name: fieldPath,
+          field: fieldDef,
+          value: formaData[fieldPath],
+          touched,
+          required,
+          disabled,
+          errors,
+          onChange: (value: unknown) => setFieldValue(fieldPath, value),
+          onBlur: () => setFieldTouched(fieldPath),
+          // Convenience properties
+          visible: true, // Always true since we already filtered for visibility
+          enabled: !disabled,
+          readonly: isReadonly,
+          label: fieldDef.label ?? fieldPath,
+          description: fieldDef.description,
+          placeholder: fieldDef.placeholder,
+          // Adorner properties (only for adornable field types)
+          ...(isAdornableField(fieldDef) && {
+            prefix: fieldDef.prefix,
+            suffix: fieldDef.suffix,
+          }),
+          // Presentation variant
+          variant: fieldDef.variant,
+          variantConfig: fieldDef.variantConfig,
         };
 
-        // Extend getItemFieldProps to include additional metadata (itemIndex, fieldName, options)
-        const getItemFieldPropsExtended = (index: number, fieldName: string) => {
-          const baseProps = baseHelpers.getItemFieldProps(index, fieldName);
-          const itemFieldDef = itemFieldDefs[fieldName];
-          const itemPath = `${fieldPath}[${index}].${fieldName}`;
-          return {
+        // Build type-specific props
+        let fieldProps:
+          | BaseFieldProps
+          | TextFieldProps
+          | NumberFieldProps
+          | SelectFieldProps
+          | ArrayFieldProps
+          | DisplayFieldProps = baseProps;
+
+        if (fieldType === "number" || fieldType === "integer") {
+          const constraints = getNumberConstraints(schemaProperty);
+          fieldProps = {
             ...baseProps,
-            itemIndex: index,
-            fieldName,
-            options: (forma.optionsVisibility[itemPath] as SelectOption[] | undefined) ?? itemFieldDef?.options,
+            fieldType,
+            value: baseProps.value as number | null,
+            onChange: baseProps.onChange as (value: number | null) => void,
+            ...constraints,
+          } as NumberFieldProps;
+        } else if (fieldType === "select" || fieldType === "multiselect") {
+          const selectOptions = isSelectionField(fieldDef)
+            ? fieldDef.options
+            : [];
+          fieldProps = {
+            ...baseProps,
+            fieldType,
+            value: baseProps.value as string | string[] | null,
+            onChange: baseProps.onChange as (
+              value: string | string[] | null,
+            ) => void,
+            options: formaOptionsVisibility[fieldPath] ?? selectOptions ?? [],
+          } as SelectFieldProps;
+        } else if (
+          fieldType === "array" &&
+          fieldDef.type === "array" &&
+          fieldDef.itemFields
+        ) {
+          const arrayValue = Array.isArray(baseProps.value)
+            ? baseProps.value
+            : [];
+          const minItems = fieldDef.minItems ?? 0;
+          const maxItems = fieldDef.maxItems ?? Infinity;
+          const itemFieldDefs = fieldDef.itemFields;
+
+          // Get helpers from useForma - these are fresh on each render, avoiding stale closures
+          const baseHelpers = getArrayHelpers(fieldPath);
+
+          // Wrap push to add default item creation when called without arguments
+          const pushWithDefault = (item?: unknown): void => {
+            const newItem = item ?? createDefaultItem(itemFieldDefs);
+            baseHelpers.push(newItem);
           };
-        };
 
-        const helpers: ArrayHelpers = {
-          items: arrayValue,
-          push: pushWithDefault,
-          insert: baseHelpers.insert,
-          remove: baseHelpers.remove,
-          move: baseHelpers.move,
-          swap: baseHelpers.swap,
-          getItemFieldProps: getItemFieldPropsExtended,
-          minItems,
-          maxItems,
-          canAdd: arrayValue.length < maxItems,
-          canRemove: arrayValue.length > minItems,
-        };
-        fieldProps = {
-          ...baseProps,
-          fieldType: "array",
-          value: arrayValue,
-          onChange: baseProps.onChange as (value: unknown[]) => void,
-          helpers,
-          itemFields: itemFieldDefs,
-          minItems,
-          maxItems,
-        } as ArrayFieldProps;
-      } else {
-        // Text-based fields
-        fieldProps = {
-          ...baseProps,
-          fieldType: fieldType as "text" | "email" | "password" | "url" | "textarea",
-          value: (baseProps.value as string) ?? "",
-          onChange: baseProps.onChange as (value: string) => void,
-        };
-      }
+          // Extend getItemFieldProps to include additional metadata (itemIndex, fieldName, options)
+          const getItemFieldPropsExtended = (
+            index: number,
+            fieldName: string,
+          ) => {
+            const baseProps = baseHelpers.getItemFieldProps(index, fieldName);
+            const itemFieldDef = itemFieldDefs[fieldName];
+            const itemPath = `${fieldPath}[${index}].${fieldName}`;
+            return {
+              ...baseProps,
+              itemIndex: index,
+              fieldName,
+              options:
+                (formaOptionsVisibility[itemPath] as
+                  | SelectOption[]
+                  | undefined) ??
+                (itemFieldDef && isSelectionField(itemFieldDef)
+                  ? itemFieldDef.options
+                  : undefined),
+            };
+          };
 
-      // Wrap props in { field, spec } structure for components
-      const componentProps = { field: fieldProps, spec };
-
-      return (
-        <FieldWrapper
-          key={fieldPath}
-          fieldPath={fieldPath}
-          field={fieldDef}
-          errors={errors}
-          touched={touched}
-          required={required}
-          showRequiredIndicator={showRequiredIndicator}
-          visible={isVisible}
-        >
-          {React.createElement(Component as React.ComponentType<typeof componentProps>, componentProps)}
-        </FieldWrapper>
-      );
-    }, [spec, forma, components, FieldWrapper]);
+          const helpers: ArrayHelpers = {
+            items: arrayValue,
+            push: pushWithDefault,
+            insert: baseHelpers.insert,
+            remove: baseHelpers.remove,
+            move: baseHelpers.move,
+            swap: baseHelpers.swap,
+            getItemFieldProps: getItemFieldPropsExtended,
+            minItems,
+            maxItems,
+            canAdd: arrayValue.length < maxItems,
+            canRemove: arrayValue.length > minItems,
+          };
+          fieldProps = {
+            ...baseProps,
+            fieldType: "array",
+            value: arrayValue,
+            onChange: baseProps.onChange as (value: unknown[]) => void,
+            helpers,
+            itemFields: itemFieldDefs,
+            minItems,
+            maxItems,
+          } as ArrayFieldProps;
+        } else if (fieldType === "display" && fieldDef.type === "display") {
+          // Display fields (read-only presentation content)
+          // Resolve source value if the display field has a source property
+          const sourceValue = fieldDef.source
+            ? (formaData[fieldDef.source] ?? formaComputed[fieldDef.source])
+            : undefined;
+          // eslint-disable-next-line @typescript-eslint/no-unused-vars
+          const {
+            onChange: _onChange,
+            value: _value,
+            ...displayBaseProps
+          } = baseProps;
+          fieldProps = {
+            ...displayBaseProps,
+            fieldType: "display",
+            content: fieldDef.content,
+            sourceValue,
+            format: fieldDef.format,
+          } as DisplayFieldProps;
+        } else {
+          // Text-based fields
+          fieldProps = {
+            ...baseProps,
+            fieldType: fieldType as
+              | "text"
+              | "email"
+              | "password"
+              | "url"
+              | "textarea",
+            value: (baseProps.value as string) ?? "",
+            onChange: baseProps.onChange as (value: string) => void,
+          };
+        }
+
+        // Wrap props in { field, spec } structure for components
+        const componentProps = { field: fieldProps, spec };
+
+        return (
+          <div key={fieldPath} data-field-path={fieldPath}>
+            <FieldWrapper
+              fieldPath={fieldPath}
+              field={fieldDef}
+              errors={errors}
+              touched={touched}
+              required={required}
+              showRequiredIndicator={showRequiredIndicator}
+              visible={isVisible}
+            >
+              {React.createElement(
+                Component as React.ComponentType<typeof componentProps>,
+                componentProps,
+              )}
+            </FieldWrapper>
+          </div>
+        );
+      },
+      [
+        spec,
+        components,
+        FieldWrapper,
+        formaData,
+        formaComputed,
+        formaVisibility,
+        formaRequired,
+        formaEnabled,
+        formaReadonly,
+        formaOptionsVisibility,
+        formaTouched,
+        formaErrors,
+        setFieldValue,
+        setFieldTouched,
+        getArrayHelpers,
+      ],
+    );
 
     // Render fields (memoized)
     const renderedFields = useMemo(
       () => fieldsToRender.map(renderField),
-      [fieldsToRender, renderField]
+      [fieldsToRender, renderField],
     );
 
     // Render with page wrapper if using pages
@@ -429,5 +593,5 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
         </Layout>
       </FormaContext.Provider>
     );
-  }
+  },
 );