@multiplatform.one/forms 6.1.0 → 6.4.0

package/src/Form/index.tsx

@@ -1,4 +1,5 @@
 import { useUrlState } from "@multiplatform.one/router";
+import { useResolvedKnobs } from "@multiplatform.one/theme";
 import { type FormApi, type FormOptions, useForm } from "@tanstack/react-form";
 import {
   type FormEvent,
@@ -9,7 +10,17 @@ import {
   useMemo,
   useRef,
 } from "react";
-import { Form as TamaguiForm, type FormProps as TamaguiFormProps } from "tamagui";
+import { Form as TamaguiForm, type FormProps as TamaguiFormProps, isWeb } from "tamagui";
+import { ErrorSummary, collectFormFieldErrors, type ErrorSummaryItem } from "../ErrorSummary";
+import { RequiredMarkingContext, mapHouseRequiredMarking } from "../requiredMarking";
+import { type FormValidateOn, resolveEffectiveValidateOn } from "./validateOn";
+
+export type { FormValidateOn } from "./validateOn";
+export {
+  resolveEffectiveValidateOn,
+  remapValidatorsForTiming,
+  type EffectiveValidateOn,
+} from "./validateOn";
 
 export const FormContext = createContext<
   FormApi<any, any, any, any, any, any, any, any, any, any, any, any> | undefined
@@ -32,6 +43,23 @@ export function useFormContext<TParentData, _TFormValidator = any>() {
   >;
 }
 
+export interface FormValidateContextValue {
+  validateOn: FormValidateOn;
+  /** True after ≥1 submit attempt (upgrades `"submit"` → blur-then-change). */
+  hasSubmitted: boolean;
+}
+
+const defaultValidateContext: FormValidateContextValue = {
+  validateOn: "submit",
+  hasSubmitted: false,
+};
+
+export const FormValidateContext = createContext<FormValidateContextValue>(defaultValidateContext);
+
+export function useFormValidate(): FormValidateContextValue {
+  return useContext(FormValidateContext);
+}
+
 export interface FormProps<TFormData, _TFormValidator = any> extends Omit<
   TamaguiFormProps,
   "onSubmit"
@@ -43,6 +71,96 @@ export interface FormProps<TFormData, _TFormValidator = any> extends Omit<
   syncWithUrl?: boolean;
   urlDebounceMs?: number;
   submitText?: string;
+  /**
+   * When true (default), render {@link ErrorSummary} above fields after a
+   * failed submit that produced field errors. Set false to opt out
+   * (embedded/inline forms).
+   */
+  showErrorSummary?: boolean;
+  /** Heading for the auto ErrorSummary. */
+  errorSummaryTitle?: string;
+  /**
+   * Preferred validation timing (DG-VAL-01). Default `"submit"`.
+   * After the first submit attempt, `"submit"` remaps field `onSubmit`
+   * validators onto blur + change so errors clear live (blur-then-change).
+   * Explicit `"blur"` / `"change"` always attach those listeners.
+   */
+  validateOn?: FormValidateOn;
+}
+
+function AutoErrorSummary({
+  form,
+  title,
+  formElement,
+}: {
+  form: FormApi<any, any, any, any, any, any, any, any, any, any, any, any>;
+  title?: string;
+  formElement: HTMLElement | null;
+}) {
+  const Subscribe = (
+    form as unknown as {
+      Subscribe: (props: {
+        selector: (state: any) => any;
+        children: (value: any) => ReactNode;
+      }) => ReactNode;
+    }
+  ).Subscribe;
+
+  return (
+    <Subscribe
+      selector={(state: any) => ({
+        fieldMeta: state.fieldMeta,
+        submissionAttempts: state.submissionAttempts ?? 0,
+      })}
+    >
+      {({
+        fieldMeta,
+        submissionAttempts,
+      }: {
+        fieldMeta: Record<string, { errors?: unknown[] } | undefined>;
+        submissionAttempts: number;
+      }) => {
+        if (submissionAttempts < 1) return null;
+        const errors: ErrorSummaryItem[] = collectFormFieldErrors(fieldMeta);
+        if (errors.length === 0) return null;
+        return <ErrorSummary errors={errors} title={title} formElement={formElement} />;
+      }}
+    </Subscribe>
+  );
+}
+
+function FormValidateProvider({
+  form,
+  validateOn,
+  children,
+}: {
+  form: FormApi<any, any, any, any, any, any, any, any, any, any, any, any>;
+  validateOn: FormValidateOn;
+  children: ReactNode;
+}) {
+  const Subscribe = (
+    form as unknown as {
+      Subscribe: (props: {
+        selector: (state: any) => any;
+        children: (value: any) => ReactNode;
+      }) => ReactNode;
+    }
+  ).Subscribe;
+
+  return (
+    <Subscribe selector={(state: any) => state.submissionAttempts ?? 0}>
+      {(submissionAttempts: number) => (
+        <FormValidateContext.Provider
+          value={{
+            validateOn,
+            hasSubmitted: submissionAttempts >= 1,
+          }}
+        >
+          {children}
+        </FormValidateContext.Provider>
+      )}
+    </Subscribe>
+  );
 }
 
 export function Form<TFormData extends Record<string, any>, TFormValidator = any>({
@@ -53,8 +171,15 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
   syncWithUrl = false,
   urlDebounceMs = 500,
   submitText: _submitText,
+  showErrorSummary = true,
+  errorSummaryTitle,
+  validateOn = "submit",
   ...tamaguiFormProps
 }: FormProps<TFormData, TFormValidator>) {
+  const { knobProps } = useResolvedKnobs();
+  const requiredMarkMode = mapHouseRequiredMarking(knobProps.requiredMarking);
+  const formAutofocusOn = knobProps.formAutofocus === "on";
+
   // Get URL state — always call the hook, only use its values when syncWithUrl is true
   const [urlState, setUrlState] = useUrlState<TFormData>(
     formOptions?.defaultValues || ({} as TFormData),
@@ -67,6 +192,9 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
     onSubmitRef.current = onSubmit;
   }, [onSubmit]);
 
+  const formElementRef = useRef<HTMLElement | null>(null);
+  const didAutofocusRef = useRef(false);
+
   // Create form with URL state as default values.
   // Pass a minimal empty config when providedForm is given so the inner form is a no-op.
   const defaultForm = useForm<TFormData, any, any, any, any, any, any, any, any, any, any, any>(
@@ -106,17 +234,63 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
     () => (e?: FormEvent) => {
       e?.preventDefault();
       e?.stopPropagation();
+      // Guard against double-fire while a submission is already in flight
+      if (form.state.isSubmitting) return;
       // Trigger Tanstack Form's handleSubmit which calls our onSubmit callback
       void form.handleSubmit();
     },
     [form],
   );
 
+  // Capture the native form element for ErrorSummary focus targeting (web).
+  const setFormRef = (node: any) => {
+    if (!isWeb) {
+      formElementRef.current = null;
+      return;
+    }
+    const el =
+      (node as HTMLElement | null)?.tagName === "FORM"
+        ? (node as HTMLElement)
+        : (((node as HTMLElement | null)?.querySelector?.("form") as HTMLElement | null) ??
+          (node as HTMLElement | null));
+    formElementRef.current = el;
+  };
+
+  // House `formAutofocus`: default off (a11y). Only focus first control when knob is on.
+  useEffect(() => {
+    if (!formAutofocusOn || !isWeb || didAutofocusRef.current) return;
+    const formEl = formElementRef.current;
+    if (!formEl || typeof formEl.querySelector !== "function") return;
+    const first = formEl.querySelector(
+      'input:not([disabled]):not([type="hidden"]), textarea:not([disabled]), select:not([disabled])',
+    ) as HTMLElement | null;
+    if (!first || typeof first.focus !== "function") return;
+    first.focus();
+    didAutofocusRef.current = true;
+  }, [formAutofocusOn, children]);
+
   return (
     <FormContext.Provider value={form}>
-      <TamaguiForm onSubmit={handleSubmit} {...tamaguiFormProps}>
-        {children}
-      </TamaguiForm>
+      <RequiredMarkingContext.Provider value={{ mode: requiredMarkMode }}>
+        <FormValidateProvider form={form} validateOn={validateOn}>
+          <TamaguiForm ref={setFormRef} onSubmit={handleSubmit} {...tamaguiFormProps}>
+            {showErrorSummary ? (
+              <AutoErrorSummary
+                form={form}
+                title={errorSummaryTitle}
+                formElement={formElementRef.current}
+              />
+            ) : null}
+            {children}
+          </TamaguiForm>
+        </FormValidateProvider>
+      </RequiredMarkingContext.Provider>
     </FormContext.Provider>
   );
 }
+
+/** @internal test helper — effective timing for current FormValidate context. */
+export function useEffectiveValidateOn() {
+  const { validateOn, hasSubmitted } = useFormValidate();
+  return resolveEffectiveValidateOn(validateOn, hasSubmitted);
+}

package/src/Form/validateOn.spec.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from "vitest";
+import { remapValidatorsForTiming, resolveEffectiveValidateOn } from "./validateOn";
+
+describe("resolveEffectiveValidateOn", () => {
+  it("keeps submit before any attempt", () => {
+    expect(resolveEffectiveValidateOn("submit", false)).toBe("submit");
+  });
+
+  it("upgrades submit to blur-then-change after first attempt", () => {
+    expect(resolveEffectiveValidateOn("submit", true)).toBe("blur-then-change");
+  });
+
+  it("passes blur and change through unchanged", () => {
+    expect(resolveEffectiveValidateOn("blur", false)).toBe("blur");
+    expect(resolveEffectiveValidateOn("blur", true)).toBe("blur");
+    expect(resolveEffectiveValidateOn("change", false)).toBe("change");
+    expect(resolveEffectiveValidateOn("change", true)).toBe("change");
+  });
+});
+
+describe("remapValidatorsForTiming", () => {
+  const onSubmit = ({ value }: { value: unknown }) => (value ? undefined : "required");
+
+  it("leaves validators alone for submit-only timing", () => {
+    const validators = { onSubmit };
+    expect(remapValidatorsForTiming(validators, "submit")).toBe(validators);
+  });
+
+  it("copies onSubmit onto onBlur for blur timing", () => {
+    const remapped = remapValidatorsForTiming({ onSubmit }, "blur");
+    expect(remapped?.onBlur).toBeTypeOf("function");
+    expect((remapped?.onBlur as typeof onSubmit)({ value: "" })).toBe("required");
+    expect(remapped?.onChange).toBeUndefined();
+  });
+
+  it("copies onSubmit onto onChange for change timing", () => {
+    const remapped = remapValidatorsForTiming({ onSubmit }, "change");
+    expect(remapped?.onChange).toBeTypeOf("function");
+    expect((remapped?.onChange as typeof onSubmit)({ value: "ok" })).toBeUndefined();
+    expect(remapped?.onBlur).toBeUndefined();
+  });
+
+  it("attaches both listeners for blur-then-change", () => {
+    const remapped = remapValidatorsForTiming({ onSubmit }, "blur-then-change");
+    expect(remapped?.onBlur).toBeTypeOf("function");
+    expect(remapped?.onChange).toBeTypeOf("function");
+  });
+
+  it("composes with existing onBlur without dropping it", () => {
+    const onBlur = ({ value }: { value: unknown }) => (value === "x" ? "bad x" : undefined);
+    const remapped = remapValidatorsForTiming({ onSubmit, onBlur }, "blur");
+    expect((remapped?.onBlur as typeof onBlur)({ value: "x" })).toBe("bad x");
+    expect((remapped?.onBlur as typeof onBlur)({ value: "" })).toBe("required");
+  });
+});

package/src/Form/validateOn.ts

@@ -0,0 +1,61 @@
+/**
+ * Validation timing helpers (DG-VAL-01 / W2 residual).
+ *
+ * Default is submit-only. After the first submit attempt, `"submit"` upgrades
+ * to blur-then-change so inline errors clear live as the user edits.
+ */
+
+export type FormValidateOn = "submit" | "blur" | "change";
+
+/** Resolved listener set after applying the post-submit upgrade. */
+export type EffectiveValidateOn = "submit" | "blur" | "change" | "blur-then-change";
+
+export function resolveEffectiveValidateOn(
+  validateOn: FormValidateOn,
+  hasSubmitted: boolean,
+): EffectiveValidateOn {
+  if (validateOn === "submit" && hasSubmitted) {
+    return "blur-then-change";
+  }
+  return validateOn;
+}
+
+function composeValidator(
+  existing: ((args: { value: unknown }) => unknown) | undefined,
+  fallback: (args: { value: unknown }) => unknown,
+): (args: { value: unknown }) => unknown {
+  if (!existing) return fallback;
+  return (args) => existing(args) ?? fallback(args);
+}
+
+/**
+ * Remap `onSubmit` validators onto blur/change listeners per timing policy.
+ * Existing onBlur/onChange validators are preserved and composed (run first).
+ */
+export function remapValidatorsForTiming(
+  validators: Record<string, unknown> | undefined,
+  effective: EffectiveValidateOn,
+): Record<string, unknown> | undefined {
+  if (!validators || effective === "submit") return validators;
+
+  const onSubmit = validators.onSubmit as ((args: { value: unknown }) => unknown) | undefined;
+  if (typeof onSubmit !== "function") return validators;
+
+  const next: Record<string, unknown> = { ...validators };
+  const wantBlur = effective === "blur" || effective === "blur-then-change";
+  const wantChange = effective === "change" || effective === "blur-then-change";
+
+  if (wantBlur) {
+    next.onBlur = composeValidator(
+      validators.onBlur as ((args: { value: unknown }) => unknown) | undefined,
+      onSubmit,
+    );
+  }
+  if (wantChange) {
+    next.onChange = composeValidator(
+      validators.onChange as ((args: { value: unknown }) => unknown) | undefined,
+      onSubmit,
+    );
+  }
+  return next;
+}

package/src/FormGrid.spec.tsx

@@ -0,0 +1,253 @@
+import { act } from "@testing-library/react";
+import { Preset } from "@multiplatform.one/theme";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { FieldGroup } from "./FieldGroup";
+import { FORM_GRID_COLLAPSE_WIDTH, FormGrid } from "./FormGrid";
+import { FormSection, FormSectionStack } from "./FormSection";
+import { formFieldGap, formReadableMaxWidth, formSectionGap } from "./formSpacing";
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+function stubContainerWidth(width: number) {
+  vi.spyOn(HTMLElement.prototype, "getBoundingClientRect").mockReturnValue({
+    width,
+    height: 100,
+    top: 0,
+    left: 0,
+    right: width,
+    bottom: 100,
+    x: 0,
+    y: 0,
+    toJSON: () => ({}),
+  } as DOMRect);
+
+  vi.stubGlobal(
+    "ResizeObserver",
+    class {
+      cb: ResizeObserverCallback;
+      constructor(cb: ResizeObserverCallback) {
+        this.cb = cb;
+      }
+      observe(target: Element) {
+        this.cb(
+          [
+            {
+              target,
+              contentRect: { width } as DOMRectReadOnly,
+              borderBoxSize: [],
+              contentBoxSize: [],
+              devicePixelContentBoxSize: [],
+            } as ResizeObserverEntry,
+          ],
+          this as unknown as ResizeObserver,
+        );
+      }
+      unobserve() {}
+      disconnect() {}
+    },
+  );
+}
+
+describe("formSpacing tokens", () => {
+  it("encodes section gap larger than field gap (DG-FORM-06)", () => {
+    expect(formFieldGap).toBe("$4");
+    expect(formSectionGap).toBe("$8");
+    expect(Number(formSectionGap.slice(1))).toBeGreaterThan(Number(formFieldGap.slice(1)));
+  });
+
+  it("exposes a readable max width in the 480–600 band (DG-FORM-08)", () => {
+    expect(formReadableMaxWidth).toBeGreaterThanOrEqual(480);
+    expect(formReadableMaxWidth).toBeLessThanOrEqual(600);
+  });
+});
+
+describe("FormGrid", () => {
+  it("defaults to a single column (DG-FORM-01)", () => {
+    const result = renderWithProviders(
+      <FormGrid>
+        <div>a</div>
+        <div>b</div>
+      </FormGrid>,
+    );
+    const grid = result.container.querySelector("[data-mpo-form-grid]");
+    expect(grid).toBeTruthy();
+    expect(grid?.getAttribute("data-columns")).toBe("1");
+    expect(grid?.getAttribute("data-requested-columns")).toBe("1");
+    expect(grid?.getAttribute("data-max-columns")).toBe("2");
+  });
+
+  it("caps columns at maxColumns", () => {
+    stubContainerWidth(720);
+    const result = renderWithProviders(
+      <FormGrid columns={2} maxColumns={1}>
+        <div>a</div>
+        <div>b</div>
+      </FormGrid>,
+    );
+    const grid = result.container.querySelector("[data-mpo-form-grid]");
+    expect(grid?.getAttribute("data-requested-columns")).toBe("1");
+    expect(grid?.getAttribute("data-columns")).toBe("1");
+  });
+
+  it("uses 2 columns when requested and container is wide", () => {
+    stubContainerWidth(FORM_GRID_COLLAPSE_WIDTH + 40);
+    let result!: ReturnType<typeof renderWithProviders>;
+    act(() => {
+      result = renderWithProviders(
+        <FormGrid columns={2}>
+          <div>a</div>
+          <div>b</div>
+        </FormGrid>,
+      );
+    });
+    const grid = result.container.querySelector("[data-mpo-form-grid]") as HTMLElement;
+    expect(grid.getAttribute("data-requested-columns")).toBe("2");
+    expect(grid.getAttribute("data-columns")).toBe("2");
+    expect(grid.style.gridTemplateColumns).toBe("repeat(2, minmax(0, 1fr))");
+  });
+
+  it("collapses to 1 column when container is narrow (DG-FORM-09)", () => {
+    stubContainerWidth(280);
+    let result!: ReturnType<typeof renderWithProviders>;
+    act(() => {
+      result = renderWithProviders(
+        <FormGrid columns={2}>
+          <div>a</div>
+          <div>b</div>
+        </FormGrid>,
+      );
+    });
+    const grid = result.container.querySelector("[data-mpo-form-grid]") as HTMLElement;
+    expect(grid.getAttribute("data-requested-columns")).toBe("2");
+    expect(grid.getAttribute("data-columns")).toBe("1");
+    expect(grid.style.gridTemplateColumns).toBe("repeat(1, minmax(0, 1fr))");
+  });
+});
+
+describe("FieldGroup", () => {
+  it("renders a fieldset legend on web", () => {
+    const result = renderWithProviders(
+      <FieldGroup legend="Billing">
+        <div>card</div>
+      </FieldGroup>,
+    );
+    const fieldset = result.container.querySelector("fieldset[data-mpo-field-group]");
+    expect(fieldset).toBeTruthy();
+    expect(result.container.querySelector("legend")?.textContent).toBe("Billing");
+  });
+
+  it("uses FormGrid when columns=2", () => {
+    stubContainerWidth(720);
+    const result = renderWithProviders(
+      <FieldGroup legend="Name" columns={2}>
+        <div>first</div>
+        <div>last</div>
+      </FieldGroup>,
+    );
+    expect(result.container.querySelector("[data-mpo-form-grid]")).toBeTruthy();
+    expect(
+      result.container.querySelector("[data-mpo-field-group]")?.getAttribute("data-columns"),
+    ).toBe("2");
+  });
+});
+
+describe("FormSection", () => {
+  it("renders label and section marker", () => {
+    const result = renderWithProviders(
+      <FormSection label="Details">
+        <div>field</div>
+      </FormSection>,
+    );
+    expect(result.container.querySelector("[data-mpo-form-section]")).toBeTruthy();
+    expect(result.findTextElement("Details")).toBeDefined();
+  });
+
+  it("allows fluid max width", () => {
+    const result = renderWithProviders(
+      <FormSection label="Wide" maxWidth="fluid">
+        <div>field</div>
+      </FormSection>,
+    );
+    expect(result.container.querySelector("[data-mpo-form-section]")).toBeTruthy();
+  });
+
+  it("FormSectionStack marks section rhythm container", () => {
+    const result = renderWithProviders(
+      <FormSectionStack>
+        <FormSection label="A">
+          <div>1</div>
+        </FormSection>
+        <FormSection label="B">
+          <div>2</div>
+        </FormSection>
+      </FormSectionStack>,
+    );
+    expect(result.container.querySelector("[data-mpo-form-section-stack]")).toBeTruthy();
+    expect(result.container.querySelectorAll("[data-mpo-form-section]").length).toBe(2);
+  });
+
+  it("renders semantic fieldset + legend on web by default", () => {
+    const result = renderWithProviders(
+      <FormSection label="Billing">
+        <div>field</div>
+      </FormSection>,
+    );
+    expect(result.container.querySelector("fieldset")).toBeTruthy();
+    expect(result.container.querySelector("legend")?.textContent).toContain("Billing");
+    expect(result.container.querySelector("[data-mpo-fieldset]")).toBeTruthy();
+  });
+});
+
+describe("FormSection semantic gaps (DG-FORM-06)", () => {
+  it("defaults field gap to knobProps.gap and section gap to knobProps.gapLg", () => {
+    const result = renderWithProviders(
+      <FormSectionStack>
+        <FormSection label="A">
+          <div>1</div>
+        </FormSection>
+      </FormSectionStack>,
+    );
+    const section = result.container.querySelector("[data-mpo-form-section]");
+    const stack = result.container.querySelector("[data-mpo-form-section-stack]");
+    // knob defaults: gap $4 (within-group), gapLg $5 (between-groups)
+    expect(section?.getAttribute("data-field-gap")).toBe("$4");
+    expect(stack?.getAttribute("data-section-gap")).toBe("$5");
+    const fieldStep = Number(section?.getAttribute("data-field-gap")?.slice(1));
+    const sectionStep = Number(stack?.getAttribute("data-section-gap")?.slice(1));
+    expect(sectionStep).toBeGreaterThan(fieldStep);
+  });
+
+  it("space knob restyles both gaps while keeping section > field", () => {
+    const result = renderWithProviders(
+      <Preset overrides={{ space: "small" }}>
+        <FormSectionStack>
+          <FormSection label="A">
+            <div>1</div>
+          </FormSection>
+        </FormSectionStack>
+      </Preset>,
+    );
+    const section = result.container.querySelector("[data-mpo-form-section]");
+    const stack = result.container.querySelector("[data-mpo-form-section-stack]");
+    expect(section?.getAttribute("data-field-gap")).toBe("$2");
+    expect(stack?.getAttribute("data-section-gap")).toBe("$3");
+  });
+
+  it("explicit gap props eject from the knob defaults", () => {
+    const result = renderWithProviders(
+      <FormSectionStack gap="$10">
+        <FormSection label="A" gap="$1">
+          <div>1</div>
+        </FormSection>
+      </FormSectionStack>,
+    );
+    const section = result.container.querySelector("[data-mpo-form-section]");
+    const stack = result.container.querySelector("[data-mpo-form-section-stack]");
+    expect(section?.getAttribute("data-field-gap")).toBe("$1");
+    expect(stack?.getAttribute("data-section-gap")).toBe("$10");
+  });
+});