@fogpipe/forma-react 0.11.1 → 0.12.0-alpha.1

package/src/FormRenderer.tsx

@@ -6,10 +6,11 @@
  */
 
 import React, { forwardRef, useImperativeHandle, useRef, useMemo, useCallback } from "react";
-import type { Forma, FieldDefinition, ValidationResult, JSONSchemaProperty } from "@fogpipe/forma-core";
+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
@@ -247,8 +248,8 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
       const isVisible = forma.visibility[fieldPath] !== false;
       if (!isVisible) return null;
 
-      // Infer field type
-      const fieldType = fieldDef.type || (fieldDef.itemFields ? "array" : "text");
+      // 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;
 
@@ -273,6 +274,7 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
       const showRequiredIndicator = required && (!isBooleanField || hasValidationRules);
 
       // Base field props
+      const isReadonly = forma.readonly[fieldPath] ?? false;
       const baseProps: BaseFieldProps = {
         name: fieldPath,
         field: fieldDef,
@@ -286,13 +288,22 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
         // 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,
       };
 
       // Build type-specific props
-      let fieldProps: BaseFieldProps | TextFieldProps | NumberFieldProps | SelectFieldProps | ArrayFieldProps = baseProps;
+      let fieldProps: BaseFieldProps | TextFieldProps | NumberFieldProps | SelectFieldProps | ArrayFieldProps | DisplayFieldProps = baseProps;
 
       if (fieldType === "number" || fieldType === "integer") {
         const constraints = getNumberConstraints(schemaProperty);
@@ -304,14 +315,15 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
           ...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: fieldDef.options ?? [],
+          options: forma.optionsVisibility[fieldPath] ?? selectOptions ?? [],
         } as SelectFieldProps;
-      } else if (fieldType === "array" && fieldDef.itemFields) {
+      } 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;
@@ -330,11 +342,12 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
         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: itemFieldDef?.options,
+            options: (forma.optionsVisibility[itemPath] as SelectOption[] | undefined) ?? (itemFieldDef && isSelectionField(itemFieldDef) ? itemFieldDef.options : undefined),
           };
         };
 
@@ -361,6 +374,19 @@ export const FormRenderer = forwardRef<FormRendererHandle, FormRendererProps>(
           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 ? forma.data[fieldDef.source] ?? forma.computed[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 = {

package/src/__tests__/FormRenderer.test.tsx

@@ -735,6 +735,192 @@ describe("FormRenderer", () => {
     });
   });
 
+  // ============================================================================
+  // Option Visibility (visibleWhen on select options)
+  // ============================================================================
+
+  describe("option visibility in FormRenderer", () => {
+    it("should filter select options based on visibleWhen expressions", async () => {
+      const user = userEvent.setup();
+      const spec = createTestSpec({
+        fields: {
+          department: {
+            type: "select",
+            label: "Department",
+            options: [
+              { value: "engineering", label: "Engineering" },
+              { value: "sales", label: "Sales" },
+            ],
+          },
+          position: {
+            type: "select",
+            label: "Position",
+            options: [
+              { value: "dev", label: "Developer", visibleWhen: 'department = "engineering"' },
+              { value: "qa", label: "QA Engineer", visibleWhen: 'department = "engineering"' },
+              { value: "rep", label: "Sales Rep", visibleWhen: 'department = "sales"' },
+              { value: "mgr", label: "Sales Manager", visibleWhen: 'department = "sales"' },
+            ],
+          },
+        },
+      });
+
+      render(
+        <FormRenderer
+          spec={spec}
+          components={createTestComponentMap()}
+        />
+      );
+
+      // Initially no department selected - no position options should show
+      const positionSelect = screen.getByTestId("field-position").querySelector("select")!;
+      // Only the placeholder "Select..." option should be present
+      expect(positionSelect.querySelectorAll("option")).toHaveLength(1);
+
+      // Select Engineering department
+      const departmentSelect = screen.getByTestId("field-department").querySelector("select")!;
+      await user.selectOptions(departmentSelect, "engineering");
+
+      // Now only engineering positions should show
+      await waitFor(() => {
+        const options = positionSelect.querySelectorAll("option");
+        // placeholder + 2 engineering options
+        expect(options).toHaveLength(3);
+        expect(screen.getByText("Developer")).toBeInTheDocument();
+        expect(screen.getByText("QA Engineer")).toBeInTheDocument();
+        expect(screen.queryByText("Sales Rep")).not.toBeInTheDocument();
+        expect(screen.queryByText("Sales Manager")).not.toBeInTheDocument();
+      });
+
+      // Switch to Sales department
+      await user.selectOptions(departmentSelect, "sales");
+
+      // Now only sales positions should show
+      await waitFor(() => {
+        const options = positionSelect.querySelectorAll("option");
+        // placeholder + 2 sales options
+        expect(options).toHaveLength(3);
+        expect(screen.getByText("Sales Rep")).toBeInTheDocument();
+        expect(screen.getByText("Sales Manager")).toBeInTheDocument();
+        expect(screen.queryByText("Developer")).not.toBeInTheDocument();
+        expect(screen.queryByText("QA Engineer")).not.toBeInTheDocument();
+      });
+    });
+
+    it("should show all options when none have visibleWhen", () => {
+      const spec = createTestSpec({
+        fields: {
+          color: {
+            type: "select",
+            label: "Color",
+            options: [
+              { value: "red", label: "Red" },
+              { value: "blue", label: "Blue" },
+              { value: "green", label: "Green" },
+            ],
+          },
+        },
+      });
+
+      render(
+        <FormRenderer
+          spec={spec}
+          components={createTestComponentMap()}
+        />
+      );
+
+      expect(screen.getByText("Red")).toBeInTheDocument();
+      expect(screen.getByText("Blue")).toBeInTheDocument();
+      expect(screen.getByText("Green")).toBeInTheDocument();
+    });
+
+    it("should filter multiselect options based on visibleWhen expressions", async () => {
+      const user = userEvent.setup();
+      const spec = createTestSpec({
+        fields: {
+          tier: {
+            type: "select",
+            label: "Tier",
+            options: [
+              { value: "basic", label: "Basic" },
+              { value: "premium", label: "Premium" },
+            ],
+          },
+          features: {
+            type: "multiselect",
+            label: "Features",
+            options: [
+              { value: "email", label: "Email Support" },
+              { value: "phone", label: "Phone Support", visibleWhen: 'tier = "premium"' },
+              { value: "priority", label: "Priority Queue", visibleWhen: 'tier = "premium"' },
+            ],
+          },
+        },
+      });
+
+      render(
+        <FormRenderer
+          spec={spec}
+          components={createTestComponentMap()}
+        />
+      );
+
+      // Initially no tier selected - only non-conditional option visible
+      const featuresSelect = screen.getByTestId("field-features").querySelector("select")!;
+      await waitFor(() => {
+        // placeholder + 1 option without visibleWhen
+        expect(featuresSelect.querySelectorAll("option")).toHaveLength(2);
+        expect(screen.getByText("Email Support")).toBeInTheDocument();
+        expect(screen.queryByText("Phone Support")).not.toBeInTheDocument();
+      });
+
+      // Select Premium tier
+      const tierSelect = screen.getByTestId("field-tier").querySelector("select")!;
+      await user.selectOptions(tierSelect, "premium");
+
+      // All options should now show
+      await waitFor(() => {
+        // placeholder + 3 options
+        expect(featuresSelect.querySelectorAll("option")).toHaveLength(4);
+        expect(screen.getByText("Email Support")).toBeInTheDocument();
+        expect(screen.getByText("Phone Support")).toBeInTheDocument();
+        expect(screen.getByText("Priority Queue")).toBeInTheDocument();
+      });
+    });
+
+    it("should return empty options when all are filtered out", async () => {
+      const spec = createTestSpec({
+        fields: {
+          category: {
+            type: "select",
+            label: "Category",
+            options: [
+              { value: "a", label: "Option A", visibleWhen: 'toggle = true' },
+              { value: "b", label: "Option B", visibleWhen: 'toggle = true' },
+            ],
+          },
+          toggle: {
+            type: "boolean",
+            label: "Toggle",
+          },
+        },
+      });
+
+      render(
+        <FormRenderer
+          spec={spec}
+          initialData={{ toggle: false }}
+          components={createTestComponentMap()}
+        />
+      );
+
+      // All options have visibleWhen that evaluates to false
+      const categorySelect = screen.getByTestId("field-category").querySelector("select")!;
+      // Only placeholder
+      expect(categorySelect.querySelectorAll("option")).toHaveLength(1);
+    });
+  });
+
   // ============================================================================
   // Array Field Interactions
   // ============================================================================

package/src/index.ts

@@ -79,6 +79,8 @@ export type {
   ArrayComponentProps,
   ObjectComponentProps,
   ComputedComponentProps,
+  DisplayFieldProps,
+  DisplayComponentProps,
   ComponentMap,
 
   // Form state

package/src/types.ts

@@ -31,12 +31,22 @@ export interface BaseFieldProps {
   visible: boolean;
   /** Whether field is enabled (inverse of disabled) */
   enabled: boolean;
+  /** Whether field is readonly (visible, not editable, value still submitted) */
+  readonly: boolean;
   /** Display label from field definition */
   label: string;
   /** Help text or description from field definition */
   description?: string;
   /** Placeholder text from field definition */
   placeholder?: string;
+  /** Prefix adorner text (e.g., "$") - only for adornable field types */
+  prefix?: string;
+  /** Suffix adorner text (e.g., "kg") - only for adornable field types */
+  suffix?: string;
+  /** Presentation variant hint (e.g., "slider", "radio", "nps") */
+  variant?: string;
+  /** Variant-specific configuration */
+  variantConfig?: Record<string, unknown>;
 }
 
 /**
@@ -239,6 +249,22 @@ export interface ArrayItemFieldProps extends Omit<BaseFieldProps, "value" | "onC
   fieldName: string;
 }
 
+/**
+ * Props for display fields (read-only presentation content)
+ */
+export interface DisplayFieldProps extends Omit<BaseFieldProps, "value" | "onChange"> {
+  fieldType: "display";
+  /** Static content (markdown/text) */
+  content?: string;
+  /** Computed source value (resolved by useForma from display field's source property) */
+  sourceValue?: unknown;
+  /** Display format string */
+  format?: string;
+  /** No onChange - display fields are read-only */
+  onChange?: never;
+  value?: never;
+}
+
 /**
  * Union of all field prop types
  */
@@ -253,7 +279,8 @@ export type FieldProps =
   | MultiSelectFieldProps
   | ArrayFieldProps
   | ObjectFieldProps
-  | ComputedFieldProps;
+  | ComputedFieldProps
+  | DisplayFieldProps;
 
 /**
  * Map of field types to React components
@@ -275,6 +302,7 @@ export interface ComponentMap {
   array?: React.ComponentType<ArrayComponentProps>;
   object?: React.ComponentType<ObjectComponentProps>;
   computed?: React.ComponentType<ComputedComponentProps>;
+  display?: React.ComponentType<DisplayComponentProps>;
   fallback?: React.ComponentType<FieldComponentProps>;
 }
 
@@ -382,6 +410,11 @@ export interface ComputedComponentProps {
   spec: Forma;
 }
 
+export interface DisplayComponentProps {
+  field: DisplayFieldProps;
+  spec: Forma;
+}
+
 /**
  * Generic field component props (for fallback/dynamic components)
  */
@@ -427,6 +460,8 @@ export interface GetFieldPropsResult {
   visible: boolean;
   /** Whether field is enabled (not disabled) */
   enabled: boolean;
+  /** Whether field is readonly (visible, not editable, value still submitted) */
+  readonly: boolean;
   /** Whether field is required (for validation) */
   required: boolean;
   /**
@@ -451,6 +486,14 @@ export interface GetFieldPropsResult {
   "aria-required"?: boolean;
   /** Options for select/multiselect fields (filtered by visibleWhen) */
   options?: SelectOption[];
+  /** Prefix adorner text (e.g., "$") */
+  prefix?: string;
+  /** Suffix adorner text (e.g., "kg") */
+  suffix?: string;
+  /** Presentation variant hint */
+  variant?: string;
+  /** Variant-specific configuration */
+  variantConfig?: Record<string, unknown>;
 }
 
 /**

package/src/useForma.ts

@@ -7,11 +7,13 @@
 
 import { useCallback, useEffect, useMemo, useReducer, useRef, useState } from "react";
 import type { Forma, FieldError, ValidationResult, SelectOption } from "@fogpipe/forma-core";
+import { isAdornableField } from "@fogpipe/forma-core";
 import type { GetFieldPropsResult, GetSelectFieldPropsResult, GetArrayHelpersResult } from "./types.js";
 import {
   getVisibility,
   getRequired,
   getEnabled,
+  getReadonly,
   validate,
   calculate,
   getPageVisibility,
@@ -110,6 +112,8 @@ export interface UseFormaReturn {
   required: Record<string, boolean>;
   /** Field enabled state map */
   enabled: Record<string, boolean>;
+  /** Field readonly state map */
+  readonly: Record<string, boolean>;
   /** Visible options for select/multiselect fields, keyed by field path */
   optionsVisibility: OptionsVisibilityResult;
   /** Field touched state map */
@@ -272,6 +276,12 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
     [state.data, spec, computed]
   );
 
+  // Calculate readonly state
+  const readonly = useMemo(
+    () => getReadonly(state.data, spec, { computed }),
+    [state.data, spec, computed]
+  );
+
   // Calculate visible options for all select/multiselect fields (memoized)
   const optionsVisibility = useMemo(
     () => getOptionsVisibility(state.data, spec, { computed }),
@@ -543,7 +553,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
     // Also include array item field patterns
     for (const fieldId of spec.fieldOrder) {
       const fieldDef = spec.fields[fieldId];
-      if (fieldDef?.itemFields) {
+      if (fieldDef?.type === "array" && fieldDef.itemFields) {
         for (const key of fieldHandlers.current.keys()) {
           if (key.startsWith(`${fieldId}[`)) {
             validFields.add(key);
@@ -610,6 +620,11 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
     const hasValidationRules = (fieldDef?.validations?.length ?? 0) > 0;
     const showRequiredIndicator = isRequired && (!isBooleanField || hasValidationRules);
 
+    // Pass through adorner props for adornable field types
+    const adornerProps = fieldDef && isAdornableField(fieldDef)
+      ? { prefix: fieldDef.prefix, suffix: fieldDef.suffix }
+      : {};
+
     return {
       name: path,
       value: getValueAtPath(path),
@@ -619,6 +634,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
       placeholder: fieldDef?.placeholder,
       visible: visibility[path] !== false,
       enabled: enabled[path] !== false,
+      readonly: readonly[path] ?? false,
       required: isRequired,
       showRequiredIndicator,
       touched: isTouched,
@@ -629,8 +645,13 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
       "aria-invalid": hasErrors || undefined,
       "aria-describedby": hasErrors ? `${path}-error` : undefined,
       "aria-required": isRequired || undefined,
+      // Adorner props (only for adornable field types)
+      ...adornerProps,
+      // Presentation variant
+      variant: fieldDef?.variant,
+      variantConfig: fieldDef?.variantConfig,
     };
-  }, [spec, state.touched, state.isSubmitted, visibility, enabled, required, validation.errors, validateOn, getValueAtPath, getFieldHandlers]);
+  }, [spec, state.touched, state.isSubmitted, visibility, enabled, readonly, required, validation.errors, validateOn, getValueAtPath, getFieldHandlers]);
 
   // Get select field props - uses pre-computed optionsVisibility map
   const getSelectFieldProps = useCallback((path: string): GetSelectFieldPropsResult => {
@@ -649,15 +670,16 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
   const getArrayHelpers = useCallback((path: string): GetArrayHelpersResult => {
     const fieldDef = spec.fields[path];
     const currentValue = (getValueAtPath(path) as unknown[]) ?? [];
-    const minItems = fieldDef?.minItems ?? 0;
-    const maxItems = fieldDef?.maxItems ?? Infinity;
+    const arrayDef = fieldDef?.type === "array" ? fieldDef : undefined;
+    const minItems = arrayDef?.minItems ?? 0;
+    const maxItems = arrayDef?.maxItems ?? Infinity;
 
     const canAdd = currentValue.length < maxItems;
     const canRemove = currentValue.length > minItems;
 
     const getItemFieldProps = (index: number, fieldName: string): GetFieldPropsResult => {
       const itemPath = `${path}[${index}].${fieldName}`;
-      const itemFieldDef = fieldDef?.itemFields?.[fieldName];
+      const itemFieldDef = arrayDef?.itemFields?.[fieldName];
       const handlers = getFieldHandlers(itemPath);
 
       // Get item value
@@ -680,6 +702,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
         placeholder: itemFieldDef?.placeholder,
         visible: true,
         enabled: enabled[path] !== false,
+        readonly: readonly[itemPath] ?? false,
         required: false, // TODO: Evaluate item field required
         showRequiredIndicator: false, // Item fields don't show required indicator
         touched: isTouched,
@@ -728,7 +751,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
       canAdd,
       canRemove,
     };
-  }, [spec.fields, getValueAtPath, setValueAtPath, getFieldHandlers, enabled, state.touched, state.isSubmitted, validation.errors, validateOn, optionsVisibility]);
+  }, [spec.fields, getValueAtPath, setValueAtPath, getFieldHandlers, enabled, readonly, state.touched, state.isSubmitted, validation.errors, validateOn, optionsVisibility]);
 
   return {
     data: state.data,
@@ -736,6 +759,7 @@ export function useForma(options: UseFormaOptions): UseFormaReturn {
     visibility,
     required,
     enabled,
+    readonly,
     optionsVisibility,
     touched: state.touched,
     errors: validation.errors,