@fogpipe/forma-react 0.17.1 → 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/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;

package/src/defaults/components/ArrayField.tsx

@@ -0,0 +1,183 @@
+import React, { useRef } from "react";
+import type { ArrayComponentProps } from "../../types.js";
+
+export function ArrayField({ field }: ArrayComponentProps) {
+  const hasErrors = field.visibleErrors.length > 0;
+
+  // Stable keys via ref-based sequential counter
+  const itemKeysRef = useRef<string[]>([]);
+  const nextKeyRef = useRef(0);
+
+  const currentLength = field.helpers.items.length;
+  const keysLength = itemKeysRef.current.length;
+
+  if (currentLength > keysLength) {
+    for (let i = keysLength; i < currentLength; i++) {
+      itemKeysRef.current.push(`item-${nextKeyRef.current++}`);
+    }
+  } else if (currentLength < keysLength) {
+    itemKeysRef.current.length = currentLength;
+  }
+
+  const fieldOrder =
+    field.itemFieldOrder ?? Object.keys(field.itemFields);
+
+  return (
+    <div
+      className="forma-array"
+      aria-invalid={hasErrors || undefined}
+    >
+      {field.helpers.items.length === 0 && (
+        <p className="forma-array__empty">No items</p>
+      )}
+      {field.helpers.items.map((_, index) => (
+        <div
+          key={itemKeysRef.current[index]}
+          className="forma-array__item"
+        >
+          <div className="forma-array__item-fields">
+            {fieldOrder.map((fieldName) => {
+              const itemProps = field.helpers.getItemFieldProps(
+                index,
+                fieldName,
+              );
+              return (
+                <div key={fieldName} className="forma-field">
+                  <label
+                    htmlFor={itemProps.name}
+                    className="forma-label"
+                  >
+                    {itemProps.label}
+                  </label>
+                  {renderItemField(itemProps)}
+                  {itemProps.errors.length > 0 && itemProps.touched && (
+                    <div className="forma-field__errors" role="alert">
+                      {itemProps.errors.map((err, i) => (
+                        <span key={i} className="forma-field__error">
+                          {err.message}
+                        </span>
+                      ))}
+                    </div>
+                  )}
+                </div>
+              );
+            })}
+          </div>
+          <button
+            type="button"
+            className="forma-button forma-button--danger forma-array__remove"
+            onClick={() => field.helpers.remove(index)}
+            disabled={!field.helpers.canRemove || field.disabled}
+          >
+            Remove
+          </button>
+        </div>
+      ))}
+      <button
+        type="button"
+        className="forma-button forma-button--secondary forma-array__add"
+        onClick={() => field.helpers.push()}
+        disabled={!field.helpers.canAdd || field.disabled}
+      >
+        + Add Item
+      </button>
+    </div>
+  );
+}
+
+function renderItemField(
+  itemProps: ReturnType<
+    ArrayComponentProps["field"]["helpers"]["getItemFieldProps"]
+  >,
+) {
+  const type = itemProps.type;
+
+  if (type === "select" && itemProps.options) {
+    return (
+      <select
+        id={itemProps.name}
+        className="forma-select"
+        value={String(itemProps.value ?? "")}
+        onChange={(e) => {
+          const value = e.target.value;
+          if (!value) {
+            itemProps.onChange(null);
+          } else {
+            const option = itemProps.options?.find(
+              (opt) => String(opt.value) === value,
+            );
+            itemProps.onChange(option ? option.value : value);
+          }
+        }}
+        onBlur={itemProps.onBlur}
+        disabled={!itemProps.enabled}
+      >
+        <option value="">Select...</option>
+        {itemProps.options.map((opt) => (
+          <option key={String(opt.value)} value={String(opt.value)}>
+            {opt.label}
+          </option>
+        ))}
+      </select>
+    );
+  }
+
+  if (type === "number" || type === "integer") {
+    return (
+      <input
+        id={itemProps.name}
+        type="number"
+        className="forma-input"
+        value={itemProps.value != null ? String(itemProps.value) : ""}
+        onChange={(e) => {
+          const val = e.target.value;
+          if (val === "") {
+            itemProps.onChange(null);
+          } else {
+            const num =
+              type === "integer"
+                ? parseInt(val, 10)
+                : parseFloat(val);
+            itemProps.onChange(isNaN(num) ? null : num);
+          }
+        }}
+        onBlur={itemProps.onBlur}
+        disabled={!itemProps.enabled}
+        step={type === "integer" ? 1 : "any"}
+      />
+    );
+  }
+
+  if (type === "boolean") {
+    return (
+      <div className="forma-checkbox">
+        <input
+          id={itemProps.name}
+          type="checkbox"
+          className="forma-checkbox__input"
+          checked={Boolean(itemProps.value)}
+          onChange={(e) => itemProps.onChange(e.target.checked)}
+          onBlur={itemProps.onBlur}
+          disabled={!itemProps.enabled}
+        />
+        <label htmlFor={itemProps.name} className="forma-checkbox__label">
+          {itemProps.label}
+        </label>
+      </div>
+    );
+  }
+
+  // Default: text input
+  return (
+    <input
+      id={itemProps.name}
+      type="text"
+      className="forma-input"
+      value={String(itemProps.value ?? "")}
+      onChange={(e) => itemProps.onChange(e.target.value)}
+      onBlur={itemProps.onBlur}
+      disabled={!itemProps.enabled}
+      placeholder={itemProps.placeholder}
+    />
+  );
+}

package/src/defaults/components/BooleanInput.tsx

@@ -0,0 +1,32 @@
+import React from "react";
+import type { BooleanComponentProps } from "../../types.js";
+
+export function BooleanInput({ field }: BooleanComponentProps) {
+  const hasErrors = field.visibleErrors.length > 0;
+  const describedBy = [
+    field.description ? `${field.name}-description` : null,
+    hasErrors ? `${field.name}-errors` : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <div className="forma-checkbox">
+      <input
+        id={field.name}
+        name={field.name}
+        type="checkbox"
+        className="forma-checkbox__input"
+        checked={field.value ?? false}
+        onChange={(e) => field.onChange(e.target.checked)}
+        onBlur={field.onBlur}
+        disabled={field.disabled}
+        aria-invalid={hasErrors || undefined}
+        aria-describedby={describedBy || undefined}
+      />
+      <label htmlFor={field.name} className="forma-checkbox__label">
+        {field.label}
+      </label>
+    </div>
+  );
+}

package/src/defaults/components/ComputedDisplay.tsx

@@ -0,0 +1,26 @@
+import React from "react";
+import type { ComputedComponentProps } from "../../types.js";
+
+export function ComputedDisplay({ field }: ComputedComponentProps) {
+  let displayValue: string;
+  if (field.value === null || field.value === undefined) {
+    displayValue = "\u2014";
+  } else if (typeof field.value === "object") {
+    try {
+      displayValue = JSON.stringify(field.value);
+    } catch {
+      displayValue = String(field.value);
+    }
+  } else {
+    displayValue = String(field.value);
+  }
+
+  return (
+    <output
+      id={field.name}
+      className="forma-computed"
+    >
+      {displayValue}
+    </output>
+  );
+}

package/src/defaults/components/DateInput.tsx

@@ -0,0 +1,59 @@
+import React from "react";
+import type { DateComponentProps, DateTimeComponentProps } from "../../types.js";
+
+export function DateInput({ field }: DateComponentProps) {
+  const hasErrors = field.visibleErrors.length > 0;
+  const describedBy = [
+    field.description ? `${field.name}-description` : null,
+    hasErrors ? `${field.name}-errors` : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <input
+      id={field.name}
+      name={field.name}
+      type="date"
+      className="forma-input forma-input--date"
+      value={field.value ?? ""}
+      onChange={(e) => field.onChange(e.target.value || null)}
+      onBlur={field.onBlur}
+      disabled={field.disabled}
+      readOnly={field.readonly}
+      aria-invalid={hasErrors || undefined}
+      aria-required={field.required || undefined}
+      aria-describedby={describedBy || undefined}
+    />
+  );
+}
+
+export function DateTimeInput({ field }: DateTimeComponentProps) {
+  const hasErrors = field.visibleErrors.length > 0;
+  const describedBy = [
+    field.description ? `${field.name}-description` : null,
+    hasErrors ? `${field.name}-errors` : null,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  // datetime-local expects "YYYY-MM-DDTHH:mm" format
+  const inputValue = field.value ?? "";
+
+  return (
+    <input
+      id={field.name}
+      name={field.name}
+      type="datetime-local"
+      className="forma-input forma-input--datetime"
+      value={inputValue}
+      onChange={(e) => field.onChange(e.target.value || null)}
+      onBlur={field.onBlur}
+      disabled={field.disabled}
+      readOnly={field.readonly}
+      aria-invalid={hasErrors || undefined}
+      aria-required={field.required || undefined}
+      aria-describedby={describedBy || undefined}
+    />
+  );
+}