@multiplatform.one/forms 7.11.0 → 7.15.0

package/src/FloatingPanel/panelPortal.spec.tsx

@@ -0,0 +1,142 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { fireEvent, waitFor } from "@testing-library/react";
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { useState } from "react";
+import { ScrollView, Text, Theme } from "tamagui";
+import { Button } from "../Button";
+import { Select } from "../fields/Select";
+import { containsAcrossPanels, panelPortalAnchor } from "../shared/panelPortal";
+import { FloatingPanel } from "./index";
+import { panelPortalHost } from "./PanelPortal";
+
+/**
+ * MPO-335. react-native-web's ScrollView sets `transform: translateZ(0)` on
+ * its scroll node, which makes it the containing block of any
+ * `position: fixed` descendant, so a web panel left in the scroller's DOM is
+ * clipped by it. Every web panel now portals out of the scroller.
+ */
+
+const options = ["Apple", "Banana", "Cherry"].map((label) => ({
+  label,
+  value: label.toLowerCase(),
+}));
+
+const pointerPress = (el: Element) => {
+  fireEvent.pointerDown(el);
+  fireEvent.mouseDown(el, { detail: 1 });
+  fireEvent.mouseUp(el, { detail: 1 });
+  fireEvent.click(el, { detail: 1 });
+};
+
+function PanelHarness() {
+  const [open, setOpen] = useState(false);
+  return (
+    <FloatingPanel open={open} onOpenChange={setOpen} trigger={<Button>Open</Button>}>
+      <Text>panel body</Text>
+    </FloatingPanel>
+  );
+}
+
+let innerWidth = 0;
+beforeEach(() => {
+  innerWidth = window.innerWidth;
+  Object.defineProperty(window, "innerWidth", { configurable: true, writable: true, value: 1200 });
+});
+afterEach(() => {
+  Object.defineProperty(window, "innerWidth", {
+    configurable: true,
+    writable: true,
+    value: innerWidth,
+  });
+});
+
+describe("web panels escape a react-native-web ScrollView (MPO-335)", () => {
+  it("a Select's listbox is not a descendant of the scroll node", async () => {
+    const result = renderWithProviders(
+      <ScrollView testID="scroller" height={120}>
+        <Select options={options} placeholder="Pick" />
+      </ScrollView>,
+    );
+    const scroller = result.getByTestId("scroller");
+    const trigger = result.getByTestId("select-trigger");
+    expect(scroller.contains(trigger)).toBe(true);
+    pointerPress(trigger);
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="select-dropdown"]')).not.toBeNull();
+    });
+    const dropdown = document.querySelector('[data-testid="select-dropdown"]') as HTMLElement;
+    expect(scroller.contains(dropdown)).toBe(false);
+    expect(dropdown.closest("[data-fp-portal]")).not.toBeNull();
+    const anchor = panelPortalAnchor(dropdown);
+    expect(anchor && scroller.contains(anchor)).toBe(true);
+    expect(containsAcrossPanels(scroller, dropdown)).toBe(true);
+  });
+
+  it("a FloatingPanel's viewport is not a descendant of the scroll node", async () => {
+    const result = renderWithProviders(
+      <ScrollView testID="scroller" height={120}>
+        <PanelHarness />
+      </ScrollView>,
+    );
+    const scroller = result.getByTestId("scroller");
+    pointerPress(result.container.querySelector("[role='button']") as Element);
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="floating-panel-viewport"]')).not.toBeNull();
+    });
+    const viewport = document.querySelector(
+      '[data-testid="floating-panel-viewport"]',
+    ) as HTMLElement;
+    expect(scroller.contains(viewport)).toBe(false);
+    expect(viewport.style.position).toBe("fixed");
+    expect(containsAcrossPanels(scroller, viewport)).toBe(true);
+  });
+
+  it("carries the trigger's theme across the portal", async () => {
+    const result = renderWithProviders(
+      <Theme name="dark">
+        <ScrollView testID="scroller" height={120}>
+          <PanelHarness />
+        </ScrollView>
+      </Theme>,
+    );
+    pointerPress(result.container.querySelector("[role='button']") as Element);
+    await waitFor(() => {
+      expect(document.querySelector('[data-testid="floating-panel-viewport"]')).not.toBeNull();
+    });
+    const viewport = document.querySelector(
+      '[data-testid="floating-panel-viewport"]',
+    ) as HTMLElement;
+    const portal = viewport.closest("[data-fp-portal]") as HTMLElement;
+    const themed = Array.from(portal.querySelectorAll<HTMLElement>(".is_Theme")).filter((el) =>
+      el.contains(viewport),
+    );
+    expect(themed.some((el) => /\bt_dark\b/.test(el.className))).toBe(true);
+  });
+});
+
+describe("panelPortalHost", () => {
+  it("mounts inside the nearest modal layer so its focus trap keeps the panel", () => {
+    const dialog = document.createElement("div");
+    dialog.setAttribute("role", "dialog");
+    const scroller = document.createElement("div");
+    const trigger = document.createElement("button");
+    scroller.append(trigger);
+    dialog.append(scroller);
+    document.body.append(dialog);
+    try {
+      expect(panelPortalHost(trigger)).toBe(dialog);
+    } finally {
+      dialog.remove();
+    }
+  });
+
+  it("falls back to the body", () => {
+    const trigger = document.createElement("button");
+    document.body.append(trigger);
+    try {
+      expect(panelPortalHost(trigger)).toBe(document.body);
+    } finally {
+      trigger.remove();
+    }
+  });
+});

package/src/FloatingPanel/panelWidthContract.spec.ts

@@ -10,6 +10,8 @@
  * Calendar grids take fit-content (MPO-262): a full-width field wrapper is
  * unrelated to seven day columns and must not create a mostly empty popup.
  * Text listboxes retain at-least-trigger; icon/button launchers may also hug.
+ * The Icon glyph grid pins to its field exactly (match-trigger): fixed 64px
+ * cells wrap into more columns on a wider field instead of stretching.
  */
 import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
@@ -19,7 +21,10 @@ import { describe, expect, it } from "vitest";
 const fieldsDir = resolve(dirname(fileURLToPath(import.meta.url)), "..", "fields");
 
 /** Pickers whose trigger is a form FIELD: the panel may never be narrower. */
-const fieldShapedPickers = ["TimePicker/catalog.tsx", "ColorPicker/parts.tsx", "Icon/index.tsx"];
+const fieldShapedPickers = ["TimePicker/catalog.tsx", "ColorPicker/parts.tsx"];
+
+/** Field-triggered pickers pinned to the field's width exactly. */
+const matchTriggerPickers = ["Icon/index.tsx"];
 
 const intrinsicGridPickers = ["DatePicker/parts.tsx", "DatePicker/DatetimePicker.catalog.tsx"];
 
@@ -40,12 +45,19 @@ describe("FloatingPanel width contract (MPO-38, MPO-262)", () => {
     expect(source).toContain('widthMode="at-least-trigger"');
   });
 
-  it.each(fieldShapedPickers)("%s no longer passes the fitContent boolean", (relative) => {
-    const source = read(relative);
-    expect(source).not.toMatch(/^\s*fitContent\s*$/m);
-    expect(source).not.toMatch(/fitContent=\{?true/);
+  it.each(matchTriggerPickers)("%s declares match-trigger", (relative) => {
+    expect(read(relative)).toContain('widthMode="match-trigger"');
   });
 
+  it.each([...fieldShapedPickers, ...matchTriggerPickers])(
+    "%s no longer passes the fitContent boolean",
+    (relative) => {
+      const source = read(relative);
+      expect(source).not.toMatch(/^\s*fitContent\s*$/m);
+      expect(source).not.toMatch(/fitContent=\{?true/);
+    },
+  );
+
   it.each(buttonShapedPickers)("%s keeps fit-content deliberately", (relative) => {
     const source = read(relative);
     // Asserted, not merely tolerated: if this stops being true the exemption

package/src/FloatingPanel/touchRecipeHydration.spec.tsx

@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { act } from "react";
+import { renderToString } from "react-dom/server";
+import { hydrateRoot } from "react-dom/client";
+import { TestProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it, vi } from "vitest";
+import { TextArea } from "../fields/TextArea";
+import { Input as InputParts } from "../InputParts";
+import { Input } from "../fields/Input";
+import { SearchInput } from "../fields/SearchInput";
+import { Select } from "../fields/Select";
+import { Combobox } from "../fields/Combobox";
+const modality = vi.hoisted(() => ({ touch: true }));
+vi.mock("@multiplatform.one/platform", async (original) => ({
+  ...(await original<object>()),
+  get isWebTouchable() {
+    return modality.touch && typeof window !== "undefined";
+  },
+}));
+const options = ["Alpha", "Beta", "Gamma", "Delta"].map((label) => ({ label, value: label }));
+function Fixture() {
+  return (
+    <TestProviders>
+      <Input aria-label="Input" />
+      <TextArea aria-label="Area" />
+      <InputParts>
+        <InputParts.Box>
+          <InputParts.Area aria-label="Compound" />
+          <InputParts.Icon>
+            <span>Icon</span>
+          </InputParts.Icon>
+          <InputParts.Button aria-label="End">End</InputParts.Button>
+        </InputParts.Box>
+      </InputParts>
+      <SearchInput aria-label="Search" />
+      <Select aria-label="Select" options={options} defaultValue="Alpha" />
+      <Combobox aria-label="Combobox" options={options} defaultValue="Alpha" />
+    </TestProviders>
+  );
+}
+describe("touch recipe hydration", () => {
+  it.each([true, false, true])(
+    "hydrates actual controls on repeated coarse mount %s",
+    async (touch) => {
+      modality.touch = touch;
+      const browserWindow = window;
+      let html: string;
+      vi.stubGlobal("window", undefined);
+      try {
+        html = renderToString(<Fixture />);
+      } finally {
+        vi.stubGlobal("window", browserWindow);
+      }
+      const container = document.createElement("div");
+      container.innerHTML = html;
+      document.body.append(container);
+      const errors: unknown[] = [];
+      const spy = vi.spyOn(console, "error").mockImplementation((...args) => errors.push(args));
+      let root: ReturnType<typeof hydrateRoot> | undefined;
+      try {
+        await act(async () => {
+          root = hydrateRoot(container, <Fixture />, {
+            onRecoverableError: (error) => errors.push(error),
+          });
+        });
+        expect(
+          errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error))),
+        ).toEqual([]);
+        const heights = [...container.querySelectorAll("[data-visual-height]")].map((el) =>
+          Number(el.getAttribute("data-visual-height")),
+        );
+        expect(container.querySelector("[touch]")).toBeNull();
+        expect(heights.length).toBeGreaterThanOrEqual(2);
+        expect(heights.every((height) => height >= 44)).toBe(true);
+      } finally {
+        await act(async () => root?.unmount());
+        spy.mockRestore();
+        container.remove();
+      }
+    },
+  );
+});

package/src/FloatingPanel/useFloatingPanel.ts

@@ -12,6 +12,7 @@ import {
   useState,
 } from "react";
 import { clampDropdownRadius, scrollArrowThreshold } from "../shared/floatingList";
+import { containsAcrossPanels } from "../shared/panelPortal";
 
 // React Native defines a `window` global without DOM event methods, so a bare
 // `typeof window` check is not enough — the floating cores mount this hook on
@@ -399,16 +400,18 @@ export function useFloatingPanel({
         if (atTop || atBottom) e.preventDefault();
         return;
       }
+      // A nested panel is portaled outside this one; its own lock decides.
+      if (containsAcrossPanels(floatingEl, e.target)) return;
       e.preventDefault();
     };
     const preventKeyScroll = (e: KeyboardEvent) => {
-      if (floatingEl.contains(e.target as Node)) return;
+      if (containsAcrossPanels(floatingEl, e.target)) return;
       if (["ArrowDown", "ArrowUp", "Space", "PageDown", "PageUp", "Home", "End"].includes(e.code)) {
         e.preventDefault();
       }
     };
     const preventTouchScroll = (e: TouchEvent) => {
-      if (floatingEl.contains(e.target as Node)) return;
+      if (containsAcrossPanels(floatingEl, e.target)) return;
       e.preventDefault();
     };
 

package/src/FloatingPanel/viewportHydration.spec.tsx

@@ -0,0 +1,118 @@
+// @vitest-environment jsdom
+import { act, useState } from "react";
+import { renderToString } from "react-dom/server";
+import { hydrateRoot } from "react-dom/client";
+import { fireEvent, waitFor } from "@testing-library/react";
+import { TestProviders } from "@multiplatform.one/test-utils";
+import { describe, expect, it, vi } from "vitest";
+import { Select } from "../fields/Select";
+import { Combobox } from "../fields/Combobox";
+import { FloatingPanel, useViewportGtSm } from "./index";
+
+const options = ["Alpha", "Beta", "Gamma", "Delta"].map((label) => ({ label, value: label }));
+function Fixture({ kind }: { kind: string }) {
+  const [open, setOpen] = useState(false);
+  const wide = useViewportGtSm();
+  const [value, setValue] = useState("Alpha");
+  return (
+    <TestProviders>
+      <span data-wide={String(wide)} />
+      <output>{value}</output>
+      {kind === "Select" ? (
+        <Select
+          aria-label="Choice"
+          options={options}
+          value={value}
+          onValueChange={(next) => setValue(String(next))}
+        />
+      ) : kind === "Combobox" ? (
+        <Combobox
+          aria-label="Choice"
+          options={options}
+          value={value}
+          onValueChange={(next) => setValue(String(next))}
+        />
+      ) : (
+        <FloatingPanel
+          open={open}
+          onOpenChange={setOpen}
+          trigger={<button type="button">Open</button>}
+        >
+          <span>Panel contents</span>
+        </FloatingPanel>
+      )}
+    </TestProviders>
+  );
+}
+
+describe("viewport hydration", () => {
+  it.each(
+    ["Select", "Combobox", "FloatingPanel"].flatMap((kind) =>
+      [390, 640, 641, 1200].map((width) => ({ kind, width })),
+    ),
+  )("hydrates $kind at $width pixels before adapting", async ({ kind, width }) => {
+    const browserWindow = window;
+    const scrollTo = vi.spyOn(browserWindow, "scrollTo").mockImplementation(() => {});
+    Object.defineProperty(browserWindow, "innerWidth", {
+      configurable: true,
+      value: width,
+      writable: true,
+    });
+    let html: string;
+    vi.stubGlobal("window", undefined);
+    try {
+      html = renderToString(<Fixture kind={kind} />);
+    } finally {
+      vi.stubGlobal("window", browserWindow);
+    }
+    const container = document.createElement("div");
+    container.innerHTML = html;
+    document.body.append(container);
+    const errors: unknown[] = [];
+    const spy = vi.spyOn(console, "error").mockImplementation((...args) => errors.push(args));
+    let root: ReturnType<typeof hydrateRoot> | undefined;
+    try {
+      await act(async () => {
+        root = hydrateRoot(container, <Fixture kind={kind} />, {
+          onRecoverableError: (error) => errors.push(error),
+        });
+      });
+      expect(
+        errors.filter((error) => /hydration|hydrated|didn't match/i.test(String(error))),
+      ).toEqual([]);
+      expect(container.querySelector("[data-wide]")?.getAttribute("data-wide")).toBe(
+        String(width > 640),
+      );
+      if (width === 1200 && kind !== "FloatingPanel") {
+        const trigger = container.querySelector('[role="combobox"]')!;
+        await act(async () => {
+          fireEvent.mouseDown(trigger, { detail: 1 });
+          fireEvent.mouseUp(trigger, { detail: 1 });
+          fireEvent.click(trigger, { detail: 1 });
+        });
+        await waitFor(() =>
+          expect(document.querySelectorAll('[role="option"]').length).toBeGreaterThan(0),
+        );
+        const beta = [...document.querySelectorAll('[role="option"]')].find((option) =>
+          option.textContent?.includes("Beta"),
+        )!;
+        await act(async () => {
+          fireEvent.mouseDown(beta, { detail: 1 });
+          fireEvent.mouseUp(beta, { detail: 1 });
+          fireEvent.click(beta, { detail: 1 });
+        });
+        await waitFor(() => expect(container.querySelector("output")?.textContent).toBe("Beta"));
+      }
+      await act(async () => {
+        window.innerWidth = 390;
+        fireEvent(window, new Event("resize"));
+      });
+      expect(container.querySelector("[data-wide]")?.getAttribute("data-wide")).toBe("false");
+    } finally {
+      await act(async () => root?.unmount());
+      spy.mockRestore();
+      scrollTo.mockRestore();
+      container.remove();
+    }
+  });
+});

package/src/Form/index.tsx

@@ -20,6 +20,7 @@ import {
 import { ContextualSaveBar, type ContextualSaveBarProps } from "../ContextualSaveBar";
 import { ErrorSummary, collectFormFieldErrors, type ErrorSummaryItem } from "../ErrorSummary";
 import { RequiredMarkingContext, mapHouseRequiredMarking } from "../requiredMarking";
+import { getFormSubmission } from "./submissionController";
 import { type FormValidateOn, resolveEffectiveValidateOn } from "./validateOn";
 
 export type { FormValidateOn } from "./validateOn";
@@ -276,7 +277,7 @@ export function Form<TFormData extends Record<string, any>, TFormValidator = any
       // 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();
+      void getFormSubmission(form).submit();
     },
     [form],
   );

package/src/Form/submission.spec.tsx

@@ -0,0 +1,148 @@
+// @vitest-environment jsdom
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { useForm } from "@tanstack/react-form";
+import { act, fireEvent, waitFor, within } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import { Button } from "../Button";
+import { Input } from "../fields/Input";
+import { Form, useFormContext } from "./index";
+
+const refusal = "The record changed. Refresh and retry.";
+
+describe("shared form submission outcome", () => {
+  it.each(["html", "action", "save", "shortcut"] as const)(
+    "%s submission exposes failure, retains edits and can retry without changing its success policy",
+    async (route) => {
+      const submit = vi.fn().mockRejectedValueOnce(new Error(refusal)).mockResolvedValue(undefined);
+      const saved = vi.fn();
+      let isDirty = () => false;
+      function DirtyProbe() {
+        const form = useFormContext();
+        isDirty = () => form.state.isDirty;
+        return null;
+      }
+      const view = renderWithProviders(
+        <Form
+          formOptions={{ defaultValues: { name: "Original" } }}
+          onSubmit={submit}
+          saveBar={{ forceVisible: true, onSaved: saved }}
+        >
+          <DirtyProbe />
+          <Input name="name" label="Name" />
+          <button type="submit">Submit HTML</button>
+          <Button action="submit">Submit action</Button>
+        </Form>,
+      );
+      fireEvent.change(view.getByLabelText("Name"), { target: { value: "Edited" } });
+      const activate = () => {
+        if (route === "shortcut") fireEvent.keyDown(document, { key: "s", ctrlKey: true });
+        else
+          fireEvent.click(
+            view.getByRole("button", {
+              name:
+                route === "html" ? "Submit HTML" : route === "action" ? "Submit action" : "Save",
+            }),
+          );
+      };
+      await act(async () => activate());
+      await waitFor(() => expect(view.getByText(/Couldn't save/).textContent).toContain(refusal));
+      expect((view.getByLabelText("Name") as HTMLInputElement).value).toBe("Edited");
+      expect(submit).toHaveBeenCalledTimes(1);
+      expect(saved).not.toHaveBeenCalled();
+      await act(async () => activate());
+      await waitFor(() => expect(submit).toHaveBeenCalledTimes(2));
+      await waitFor(() => expect(view.queryByText(/Couldn't save/)).toBeNull());
+      expect((view.getByLabelText("Name") as HTMLInputElement).value).toBe("Edited");
+      expect(saved).toHaveBeenCalledTimes(route === "save" || route === "shortcut" ? 1 : 0);
+      expect(isDirty()).toBe(route === "html" || route === "action");
+    },
+  );
+
+  it("allows only one transport call when HTML, action and Save activate together", async () => {
+    let finish!: () => void;
+    const submit = vi.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          finish = resolve;
+        }),
+    );
+    const saved = vi.fn();
+    const view = renderWithProviders(
+      <Form onSubmit={submit} saveBar={{ forceVisible: true, onSaved: saved }}>
+        <button type="submit">Submit HTML</button>
+        <Button action="submit">Submit action</Button>
+      </Form>,
+    );
+    await act(async () => {
+      fireEvent.click(view.getByRole("button", { name: "Submit HTML" }));
+      fireEvent.click(view.getByRole("button", { name: "Submit action" }));
+      fireEvent.click(view.getByRole("button", { name: "Save" }));
+      fireEvent.keyDown(document, { key: "s", ctrlKey: true });
+    });
+    await waitFor(() => expect(submit).toHaveBeenCalledTimes(1));
+    await act(async () => finish());
+    expect(submit).toHaveBeenCalledTimes(1);
+    expect(saved).not.toHaveBeenCalled();
+  });
+
+  it("routes explicit form targets and standalone actions to the matching form only", async () => {
+    const firstSubmit = vi.fn();
+    const secondSubmit = vi.fn().mockRejectedValue(new Error(refusal));
+    function Harness() {
+      const first = useForm({
+        defaultValues: { name: "First" } as Record<string, unknown>,
+        onSubmit: firstSubmit,
+      });
+      const second = useForm({
+        defaultValues: { name: "Second" } as Record<string, unknown>,
+        onSubmit: secondSubmit,
+      });
+      return (
+        <>
+          <Form form={first} saveBar={{ forceVisible: true }} testID="first">
+            <Button action="submit" form={second}>
+              Target second
+            </Button>
+          </Form>
+          <Form form={second} saveBar={{ forceVisible: true }} testID="second">
+            <Input name="name" label="Second name" />
+          </Form>
+          <Button action="submit" form={second}>
+            Standalone submit
+          </Button>
+        </>
+      );
+    }
+    const view = renderWithProviders(<Harness />);
+    await act(async () => fireEvent.click(view.getByRole("button", { name: "Target second" })));
+    await waitFor(() =>
+      expect(within(view.getByTestId("second")).getByText(/Couldn't save/)).toBeTruthy(),
+    );
+    expect(within(view.getByTestId("first")).queryByText(/Couldn't save/)).toBeNull();
+    await act(async () => fireEvent.click(view.getByRole("button", { name: "Standalone submit" })));
+    await waitFor(() => expect(secondSubmit).toHaveBeenCalledTimes(2));
+    expect(firstSubmit).not.toHaveBeenCalled();
+  });
+
+  it("does not mark a form-level validation refusal saved", async () => {
+    const submit = vi.fn();
+    const saved = vi.fn();
+    const view = renderWithProviders(
+      <Form
+        formOptions={{
+          defaultValues: { name: "Original" },
+          validators: { onSubmit: () => "Review the form" },
+        }}
+        onSubmit={submit}
+        saveBar={{ forceVisible: true, onSaved: saved }}
+      >
+        <Input name="name" label="Name" />
+      </Form>,
+    );
+    fireEvent.change(view.getByLabelText("Name"), { target: { value: "Edited" } });
+    await act(async () => fireEvent.click(view.getByRole("button", { name: "Save" })));
+    expect(submit).not.toHaveBeenCalled();
+    expect(saved).not.toHaveBeenCalled();
+    expect((view.getByLabelText("Name") as HTMLInputElement).value).toBe("Edited");
+  });
+});

package/src/Form/submissionController.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it, vi } from "vitest";
+import { getFormSubmission } from "./submissionController";
+
+describe("submission controller", () => {
+  it("shares one guarded attempt per form and keeps other forms independent", async () => {
+    let finish!: () => void;
+    const form = {
+      state: { isSubmitting: false, isSubmitSuccessful: false },
+      handleSubmit: vi.fn(async () => {
+        await new Promise<void>((resolve) => {
+          finish = resolve;
+        });
+        form.state.isSubmitSuccessful = true;
+      }),
+    };
+    const other = {
+      state: { isSubmitting: false, isSubmitSuccessful: false },
+      handleSubmit: vi.fn(async () => {}),
+    };
+    const controller = getFormSubmission(form);
+    expect(getFormSubmission(form)).toBe(controller);
+    expect(getFormSubmission(other)).not.toBe(controller);
+    const first = controller.submit();
+    const duplicate = controller.submit();
+    await Promise.resolve();
+    expect(form.handleSubmit).toHaveBeenCalledTimes(1);
+    expect(await duplicate).toBe("busy");
+    finish();
+    expect(await first).toBe("success");
+    expect(other.handleSubmit).not.toHaveBeenCalled();
+  });
+
+  it("captures sync throws, exposes stable reactive snapshots and unsubscribes", async () => {
+    const form = {
+      state: { isSubmitting: false, isSubmitSuccessful: false },
+      handleSubmit: vi.fn(() => {
+        throw new Error("Service unavailable");
+      }),
+    };
+    const controller = getFormSubmission(form);
+    const initial = controller.getSnapshot();
+    expect(controller.getSnapshot()).toBe(initial);
+    const listener = vi.fn();
+    const unsubscribe = controller.subscribe(listener);
+    expect(await controller.submit()).toBe("failed");
+    expect(controller.getSnapshot().error).toBe("Service unavailable");
+    expect(controller.getSnapshot()).toBe(controller.getSnapshot());
+    expect(listener).toHaveBeenCalled();
+    unsubscribe();
+    listener.mockClear();
+    controller.clearError();
+    expect(controller.getSnapshot().error).toBeNull();
+    expect(listener).not.toHaveBeenCalled();
+    expect(await controller.submit()).toBe("failed");
+    expect(form.handleSubmit).toHaveBeenCalledTimes(2);
+  });
+
+  it("clears a prior refusal when retry starts and does not treat validation as success", async () => {
+    const form = {
+      state: { isSubmitting: false, isSubmitSuccessful: false },
+      handleSubmit: vi
+        .fn<() => Promise<void>>()
+        .mockRejectedValueOnce(new Error("Try again"))
+        .mockResolvedValue(undefined),
+    };
+    const controller = getFormSubmission(form);
+    expect(await controller.submit()).toBe("failed");
+    const retry = controller.submit();
+    expect(controller.getSnapshot().error).toBeNull();
+    expect(await retry).toBe("invalid");
+    expect(form.handleSubmit).toHaveBeenCalledTimes(2);
+  });
+});