@fogpipe/forma-react 0.17.0 → 0.18.0

package/src/__tests__/defaults/layout.test.tsx

@@ -0,0 +1,298 @@
+/// <reference types="@testing-library/jest-dom" />
+/**
+ * Tests for default layout components
+ */
+import React from "react";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import type { FieldError } from "@fogpipe/forma-core";
+import type { FieldWrapperProps, PageWrapperProps } from "../../types.js";
+import { FieldWrapper } from "../../defaults/layout/FieldWrapper.js";
+import { FormLayout } from "../../defaults/layout/FormLayout.js";
+import { PageWrapper } from "../../defaults/layout/PageWrapper.js";
+import { FormaContext } from "../../context.js";
+import type { UseFormaReturn } from "../../useForma.js";
+
+function mockFormaContext(
+  overrides: Partial<UseFormaReturn> = {},
+): UseFormaReturn {
+  return {
+    data: {},
+    computed: {},
+    visibility: {},
+    required: {},
+    enabled: {},
+    readonly: {},
+    optionsVisibility: {},
+    touched: {},
+    errors: [],
+    isValid: true,
+    isSubmitting: false,
+    isSubmitted: false,
+    isDirty: false,
+    spec: {} as UseFormaReturn["spec"],
+    wizard: null,
+    setFieldValue: vi.fn(),
+    setFieldTouched: vi.fn(),
+    setValues: vi.fn(),
+    validateField: vi.fn(),
+    validateForm: vi.fn(),
+    submitForm: vi.fn(),
+    resetForm: vi.fn(),
+    getFieldProps: vi.fn(),
+    getSelectFieldProps: vi.fn(),
+    getArrayHelpers: vi.fn(),
+    on: vi.fn(),
+    ...overrides,
+  } as unknown as UseFormaReturn;
+}
+
+function renderWithContext(
+  ui: React.ReactElement,
+  contextOverrides: Partial<UseFormaReturn> = {},
+) {
+  const ctx = mockFormaContext(contextOverrides);
+  return render(
+    <FormaContext.Provider value={ctx}>{ui}</FormaContext.Provider>,
+  );
+}
+
+// ============================================================================
+// FieldWrapper
+// ============================================================================
+describe("FieldWrapper", () => {
+  function makeProps(
+    overrides: Partial<FieldWrapperProps> = {},
+  ): FieldWrapperProps {
+    return {
+      fieldPath: "testField",
+      field: {
+        type: "text",
+        label: "Test Field",
+      } as FieldWrapperProps["field"],
+      children: <input type="text" />,
+      errors: [],
+      touched: false,
+      required: false,
+      showRequiredIndicator: false,
+      visible: true,
+      ...overrides,
+    };
+  }
+
+  it("renders label with field name", () => {
+    renderWithContext(<FieldWrapper {...makeProps()} />);
+    expect(screen.getByText("Test Field")).toBeInTheDocument();
+  });
+
+  it("shows required indicator when showRequiredIndicator is true", () => {
+    renderWithContext(
+      <FieldWrapper {...makeProps({ showRequiredIndicator: true })} />,
+    );
+    expect(screen.getByText("*")).toBeInTheDocument();
+  });
+
+  it("hides required indicator when showRequiredIndicator is false", () => {
+    renderWithContext(
+      <FieldWrapper {...makeProps({ showRequiredIndicator: false })} />,
+    );
+    expect(screen.queryByText("*")).not.toBeInTheDocument();
+  });
+
+  it("renders description when provided", () => {
+    renderWithContext(
+      <FieldWrapper
+        {...makeProps({
+          field: {
+            type: "text",
+            label: "Test Field",
+            description: "Help text here",
+          } as FieldWrapperProps["field"],
+        })}
+      />,
+    );
+    expect(screen.getByText("Help text here")).toBeInTheDocument();
+  });
+
+  it("renders children", () => {
+    renderWithContext(
+      <FieldWrapper
+        {...makeProps({ children: <span>Child content</span> })}
+      />,
+    );
+    expect(screen.getByText("Child content")).toBeInTheDocument();
+  });
+
+  it("does NOT render errors when touched is false and not submitted", () => {
+    const errors: FieldError[] = [
+      { field: "testField", message: "Required", severity: "error" },
+    ];
+    renderWithContext(
+      <FieldWrapper {...makeProps({ errors, touched: false })} />,
+    );
+    expect(screen.queryByText("Required")).not.toBeInTheDocument();
+  });
+
+  it("renders errors when touched is true and errors exist", () => {
+    const errors: FieldError[] = [
+      { field: "testField", message: "Required", severity: "error" },
+    ];
+    renderWithContext(
+      <FieldWrapper {...makeProps({ errors, touched: true })} />,
+    );
+    expect(screen.getByText("Required")).toBeInTheDocument();
+  });
+
+  it("renders errors when isSubmitted is true even if not touched", () => {
+    const errors: FieldError[] = [
+      { field: "testField", message: "Required", severity: "error" },
+    ];
+    renderWithContext(
+      <FieldWrapper {...makeProps({ errors, touched: false })} />,
+      { isSubmitted: true },
+    );
+    expect(screen.getByText("Required")).toBeInTheDocument();
+  });
+
+  it("error container has role=alert", () => {
+    const errors: FieldError[] = [
+      { field: "testField", message: "Required", severity: "error" },
+    ];
+    renderWithContext(
+      <FieldWrapper {...makeProps({ errors, touched: true })} />,
+    );
+    expect(screen.getByRole("alert")).toBeInTheDocument();
+  });
+
+  it("returns null when visible is false", () => {
+    const { container } = renderWithContext(
+      <FieldWrapper {...makeProps({ visible: false })} />,
+    );
+    expect(container.firstChild).toBeNull();
+  });
+
+  it("applies forma-field--error class when has visible errors", () => {
+    const errors: FieldError[] = [
+      { field: "testField", message: "Required", severity: "error" },
+    ];
+    const { container } = renderWithContext(
+      <FieldWrapper {...makeProps({ errors, touched: true })} />,
+    );
+    expect(container.firstChild).toHaveClass("forma-field--error");
+  });
+
+  it("applies forma-field--required class when showRequiredIndicator", () => {
+    const { container } = renderWithContext(
+      <FieldWrapper {...makeProps({ showRequiredIndicator: true })} />,
+    );
+    expect(container.firstChild).toHaveClass("forma-field--required");
+  });
+});
+
+// ============================================================================
+// FormLayout
+// ============================================================================
+describe("FormLayout", () => {
+  it("renders as form element", () => {
+    const { container } = render(
+      <FormLayout onSubmit={vi.fn()} isSubmitting={false} isValid={true}>
+        <div>Content</div>
+      </FormLayout>,
+    );
+    expect(container.querySelector("form")).toBeInTheDocument();
+  });
+
+  it("calls onSubmit on form submit", () => {
+    const onSubmit = vi.fn();
+    const { container } = render(
+      <FormLayout onSubmit={onSubmit} isSubmitting={false} isValid={true}>
+        <div>Content</div>
+      </FormLayout>,
+    );
+    fireEvent.submit(container.querySelector("form")!);
+    expect(onSubmit).toHaveBeenCalled();
+  });
+
+  it("renders submit button with Submit text", () => {
+    render(
+      <FormLayout onSubmit={vi.fn()} isSubmitting={false} isValid={true}>
+        <div>Content</div>
+      </FormLayout>,
+    );
+    expect(screen.getByRole("button")).toHaveTextContent("Submit");
+  });
+
+  it("shows Submitting... and disables button when isSubmitting", () => {
+    render(
+      <FormLayout onSubmit={vi.fn()} isSubmitting={true} isValid={true}>
+        <div>Content</div>
+      </FormLayout>,
+    );
+    const button = screen.getByRole("button");
+    expect(button).toHaveTextContent("Submitting...");
+    expect(button).toBeDisabled();
+  });
+
+  it("sets aria-busy on button when submitting", () => {
+    render(
+      <FormLayout onSubmit={vi.fn()} isSubmitting={true} isValid={true}>
+        <div>Content</div>
+      </FormLayout>,
+    );
+    expect(screen.getByRole("button")).toHaveAttribute("aria-busy", "true");
+  });
+
+  it("renders children inside form", () => {
+    render(
+      <FormLayout onSubmit={vi.fn()} isSubmitting={false} isValid={true}>
+        <div>Form content</div>
+      </FormLayout>,
+    );
+    expect(screen.getByText("Form content")).toBeInTheDocument();
+  });
+});
+
+// ============================================================================
+// PageWrapper
+// ============================================================================
+describe("PageWrapper", () => {
+  function makePageProps(
+    overrides: Partial<PageWrapperProps> = {},
+  ): PageWrapperProps {
+    return {
+      title: "Page Title",
+      children: <div>Page content</div>,
+      pageIndex: 0,
+      totalPages: 3,
+      ...overrides,
+    };
+  }
+
+  it("renders title as h2", () => {
+    render(<PageWrapper {...makePageProps()} />);
+    expect(screen.getByRole("heading", { level: 2 })).toHaveTextContent(
+      "Page Title",
+    );
+  });
+
+  it("renders description when provided", () => {
+    render(
+      <PageWrapper
+        {...makePageProps({ description: "Some description" })}
+      />,
+    );
+    expect(screen.getByText("Some description")).toBeInTheDocument();
+  });
+
+  it("omits description element when not provided", () => {
+    const { container } = render(<PageWrapper {...makePageProps()} />);
+    expect(
+      container.querySelector(".forma-page__description"),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders children", () => {
+    render(<PageWrapper {...makePageProps()} />);
+    expect(screen.getByText("Page content")).toBeInTheDocument();
+  });
+});

package/src/__tests__/events.test.ts

@@ -37,9 +37,15 @@ describe("FormaEventEmitter", () => {
 
   it("should fire multiple listeners in registration order", () => {
     const calls: number[] = [];
-    emitter.on("fieldChanged", () => { calls.push(1); });
-    emitter.on("fieldChanged", () => { calls.push(2); });
-    emitter.on("fieldChanged", () => { calls.push(3); });
+    emitter.on("fieldChanged", () => {
+      calls.push(1);
+    });
+    emitter.on("fieldChanged", () => {
+      calls.push(2);
+    });
+    emitter.on("fieldChanged", () => {
+      calls.push(3);
+    });
 
     emitter.fire("fieldChanged", {
       path: "x",
@@ -582,8 +588,12 @@ describe("formReset event", () => {
         spec,
         initialData: { name: "initial" },
         on: {
-          fieldChanged: () => { events.push("fieldChanged"); },
-          formReset: () => { events.push("formReset"); },
+          fieldChanged: () => {
+            events.push("fieldChanged");
+          },
+          formReset: () => {
+            events.push("formReset");
+          },
         },
       }),
     );

package/src/__tests__/useForma.test.ts

@@ -612,10 +612,14 @@ describe("useForma", () => {
 
       const { result } = renderHook(() => useForma({ spec }));
 
-      // Initially no errors shown (not touched)
-      expect(result.current.getFieldProps("name").errors).toEqual([]);
+      // errors always contains all validation errors (eager validation)
+      expect(
+        result.current.getFieldProps("name").errors.length,
+      ).toBeGreaterThan(0);
+      // visibleErrors should be empty (not touched, default validateOn=blur)
+      expect(result.current.getFieldProps("name").visibleErrors).toEqual([]);
 
-      // After submit, errors should show
+      // After submit, visibleErrors should show
       act(() => {
         result.current.submitForm();
       });
@@ -636,9 +640,12 @@ describe("useForma", () => {
         useForma({ spec, validateOn: "blur" }),
       );
 
-      // Errors exist but not shown
+      // Errors exist (eager validation) but visibleErrors is empty (not touched)
       expect(result.current.isValid).toBe(false);
-      expect(result.current.getFieldProps("name").errors).toEqual([]);
+      expect(
+        result.current.getFieldProps("name").errors.length,
+      ).toBeGreaterThan(0);
+      expect(result.current.getFieldProps("name").visibleErrors).toEqual([]);
     });
 
     it("should show errors immediately when validateOn: change", () => {
@@ -1854,4 +1861,100 @@ describe("useForma", () => {
       ).toBe("Item Name");
     });
   });
+
+  // ============================================================================
+  // visibleErrors
+  // ============================================================================
+
+  describe("visibleErrors", () => {
+    it("visibleErrors is empty for untouched required fields (validateOn=blur)", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+          email: { type: "email", label: "Email", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      const nameProps = result.current.getFieldProps("name");
+
+      // errors should contain the required error (validation runs eagerly)
+      expect(nameProps.errors.length).toBeGreaterThan(0);
+      // visibleErrors should be empty (field not touched)
+      expect(nameProps.visibleErrors).toHaveLength(0);
+    });
+
+    it("visibleErrors populates after field is touched", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      // Before touch
+      expect(result.current.getFieldProps("name").visibleErrors).toHaveLength(
+        0,
+      );
+
+      // Touch the field
+      act(() => {
+        result.current.setFieldTouched("name");
+      });
+
+      // After touch — errors should be visible
+      const props = result.current.getFieldProps("name");
+      expect(props.visibleErrors.length).toBeGreaterThan(0);
+      expect(props.visibleErrors[0].message).toBeDefined();
+    });
+
+    it("visibleErrors populates after form submission", async () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "blur" }),
+      );
+
+      // Before submit — visibleErrors empty
+      expect(result.current.getFieldProps("name").visibleErrors).toHaveLength(
+        0,
+      );
+
+      // Submit the form (validation will fail)
+      await act(async () => {
+        await result.current.submitForm();
+      });
+
+      // After submit — errors should be visible even without touching
+      expect(
+        result.current.getFieldProps("name").visibleErrors.length,
+      ).toBeGreaterThan(0);
+    });
+
+    it("visibleErrors is always populated when validateOn=change", () => {
+      const spec = createTestSpec({
+        fields: {
+          name: { type: "text", label: "Name", required: true },
+        },
+      });
+
+      const { result } = renderHook(() =>
+        useForma({ spec, validateOn: "change" }),
+      );
+
+      // With validateOn="change", errors should be visible immediately
+      const props = result.current.getFieldProps("name");
+      expect(props.visibleErrors.length).toBeGreaterThan(0);
+    });
+  });
 });

package/src/defaults/DefaultFormRenderer.tsx

@@ -0,0 +1,43 @@
+import React, { forwardRef } from "react";
+import { FormRenderer } from "../FormRenderer.js";
+import type { FormRendererProps, FormRendererHandle } from "../FormRenderer.js";
+import {
+  defaultComponentMap,
+  defaultFieldWrapper,
+  defaultLayout,
+  defaultWizardLayout,
+  defaultPageWrapper,
+} from "./componentMap.js";
+
+export interface DefaultFormRendererProps
+  extends Omit<FormRendererProps, "components"> {
+  /** Component map (defaults to defaultComponentMap if not provided) */
+  components?: FormRendererProps["components"];
+  /** Use wizard layout for multi-page forms */
+  wizardLayout?: boolean;
+}
+
+export const DefaultFormRenderer = forwardRef<
+  FormRendererHandle,
+  DefaultFormRendererProps
+>(function DefaultFormRenderer(props, ref) {
+  const {
+    components,
+    wizardLayout,
+    layout,
+    fieldWrapper,
+    pageWrapper,
+    ...rest
+  } = props;
+
+  return (
+    <FormRenderer
+      ref={ref}
+      components={components ?? defaultComponentMap}
+      fieldWrapper={fieldWrapper ?? defaultFieldWrapper}
+      layout={layout ?? (wizardLayout ? defaultWizardLayout : defaultLayout)}
+      pageWrapper={pageWrapper ?? defaultPageWrapper}
+      {...rest}
+    />
+  );
+});

package/src/defaults/componentMap.ts

@@ -0,0 +1,45 @@
+import type { ComponentMap } from "../types.js";
+import { TextInput } from "./components/TextInput.js";
+import { TextareaInput } from "./components/TextareaInput.js";
+import { NumberInput, IntegerInput } from "./components/NumberInput.js";
+import { BooleanInput } from "./components/BooleanInput.js";
+import { DateInput, DateTimeInput } from "./components/DateInput.js";
+import { SelectInput } from "./components/SelectInput.js";
+import { MultiSelectInput } from "./components/MultiSelectInput.js";
+import { ArrayField } from "./components/ArrayField.js";
+import { ObjectField } from "./components/ObjectField.js";
+import { ComputedDisplay } from "./components/ComputedDisplay.js";
+import { DisplayField } from "./components/DisplayField.js";
+import { MatrixField } from "./components/MatrixField.js";
+import { FallbackField } from "./components/FallbackField.js";
+import { FieldWrapper } from "./layout/FieldWrapper.js";
+import { FormLayout } from "./layout/FormLayout.js";
+import { WizardLayout } from "./layout/WizardLayout.js";
+import { PageWrapper } from "./layout/PageWrapper.js";
+
+export const defaultComponentMap: ComponentMap = {
+  text: TextInput,
+  email: TextInput,
+  phone: TextInput,
+  url: TextInput,
+  password: TextInput,
+  textarea: TextareaInput,
+  number: NumberInput,
+  integer: IntegerInput,
+  boolean: BooleanInput,
+  date: DateInput,
+  datetime: DateTimeInput,
+  select: SelectInput,
+  multiselect: MultiSelectInput,
+  array: ArrayField,
+  object: ObjectField,
+  computed: ComputedDisplay,
+  display: DisplayField,
+  matrix: MatrixField,
+  fallback: FallbackField,
+};
+
+export const defaultFieldWrapper = FieldWrapper;
+export const defaultLayout = FormLayout;
+export const defaultWizardLayout = WizardLayout;
+export const defaultPageWrapper = PageWrapper;