@multiplatform.one/forms 7.10.0 → 7.15.0

package/src/FloatingPanel/FloatingPanel.detentLayout.spec.tsx

@@ -0,0 +1,148 @@
+/**
+ * MPO-68: what the native FloatingPanel sheet lays out at a settled detent.
+ *
+ * The iOS simulator run on 965825866 dragged the Combobox sheet to its lower
+ * detent and scrolled the list to its end: the last six rows sat below the
+ * screen edge, because the sheet kept its full height and slid it down. With
+ * the keyboard up the same drag left the body under the keyboard.
+ */
+import { renderWithProviders } from "@multiplatform.one/test-utils";
+import { act, cleanup } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { Animated, PanResponder, type PanResponderCallbacks } from "react-native";
+import { Text } from "tamagui";
+import type { FloatingPanelProps } from "./index";
+import { FloatingPanel } from "./index.native";
+
+const keyboard = vi.hoisted(() => ({ inset: 0 }));
+
+vi.mock("react-native-web", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("react-native")>()),
+  ActionSheetIOS: undefined,
+  Modal: ({ children }: { children: import("react").ReactNode }) => children,
+  useWindowDimensions: () => ({ width: 390, height: 844, scale: 3, fontScale: 1 }),
+}));
+vi.mock("../shared/useKeyboardInset", () => ({ useKeyboardInset: () => keyboard.inset }));
+
+let pan: PanResponderCallbacks;
+let springs: Array<{ toValue: number; done?: (result: { finished: boolean }) => void }>;
+
+beforeEach(() => {
+  keyboard.inset = 0;
+  springs = [];
+  vi.spyOn(PanResponder, "create").mockImplementation((config) => {
+    pan = config;
+    return { panHandlers: {} } as never;
+  });
+  vi.spyOn(Animated, "spring").mockImplementation((_value, config) => ({
+    start: (done) => {
+      springs.push({ toValue: config.toValue as number, done });
+    },
+    stop: vi.fn(),
+    reset: vi.fn(),
+  }));
+  vi.spyOn(Animated, "timing").mockImplementation(() => ({
+    start: (done) => done?.({ finished: true }),
+    stop: vi.fn(),
+    reset: vi.fn(),
+  }));
+});
+afterEach(() => {
+  cleanup();
+  vi.restoreAllMocks();
+});
+
+function px(value: string) {
+  return Number.parseFloat(value);
+}
+
+function open(props: Partial<FloatingPanelProps> = {}) {
+  const view = renderWithProviders(
+    <FloatingPanel open onOpenChange={() => {}} trigger={<Text>Author</Text>} scrollable {...props}>
+      <Text>row</Text>
+    </FloatingPanel>,
+  );
+  const sheet = view.getByTestId("floating-panel-sheet");
+  const full = px(sheet.style.maxHeight);
+  return { view, sheet, full, lower: Math.round(full * 0.55) };
+}
+
+/** react-native-web keeps the onLayout handler on the node; call it the way a device layout would. */
+function layout(element: HTMLElement, height: number) {
+  const handler = (element as unknown as Record<string, (event: unknown) => void>)
+    .__reactLayoutHandler;
+  act(() => handler({ nativeEvent: { layout: { x: 0, y: 0, width: 390, height } } }));
+}
+
+function drag(dy: number) {
+  act(() => {
+    pan.onPanResponderGrant?.({} as never, {} as never);
+    pan.onPanResponderMove?.({} as never, { dy } as never);
+    pan.onPanResponderRelease?.({} as never, { dy, vy: 0 } as never);
+  });
+}
+
+function settle() {
+  const last = springs[springs.length - 1];
+  act(() => last.done?.({ finished: true }));
+  return last;
+}
+
+describe("a native FloatingPanel sheet at rest on a lower detent", () => {
+  it("is laid out at the detent height, so the end of its list is on screen", () => {
+    const { sheet, full, lower } = open();
+    drag(full - lower);
+    expect(settle().toValue).toBe(full - lower);
+    expect(px(sheet.style.maxHeight)).toBe(lower);
+    expect(sheet.style.transform).toContain("translateY(0px)");
+  });
+
+  it("ends above the keyboard when the keyboard is up", () => {
+    keyboard.inset = 300;
+    const { sheet, full, lower } = open({ sheetFill: true });
+    expect(sheet.parentElement?.style.paddingBottom).toBe("300px");
+    drag(full - lower);
+    settle();
+    expect(px(sheet.style.maxHeight)).toBe(lower);
+    expect(sheet.style.transform).toContain("translateY(0px)");
+  });
+
+  it("grows back to full height under a still top edge when a drag picks it up", () => {
+    const { sheet, full, lower } = open();
+    drag(full - lower);
+    settle();
+    act(() => pan.onPanResponderGrant?.({} as never, {} as never));
+    expect(px(sheet.style.maxHeight)).toBe(full);
+    expect(sheet.style.transform).toContain(`translateY(${full - lower}px)`);
+  });
+
+  it("keeps its top edge when the keyboard moved the max height under it", () => {
+    const { view, sheet, full, lower } = open();
+    layout(sheet, full);
+    drag(full - lower);
+    settle();
+    keyboard.inset = 300;
+    view.rerender(
+      <FloatingPanel open onOpenChange={() => {}} trigger={<Text>Author</Text>} scrollable>
+        <Text>row</Text>
+      </FloatingPanel>,
+    );
+    const lifted = 844 - 300 - 48;
+    expect(px(sheet.style.maxHeight)).toBe(Math.min(lifted, lower));
+    act(() => pan.onPanResponderGrant?.({} as never, {} as never));
+    expect(px(sheet.style.maxHeight)).toBe(lifted);
+    expect(sheet.style.transform).toContain(`translateY(${lifted - lower}px)`);
+  });
+
+  it("keeps the drag when a scroll inside the sheet asks for the touch", () => {
+    open();
+    expect(pan.onPanResponderTerminationRequest?.({} as never, {} as never)).toBe(false);
+  });
+
+  it("keeps a content-sized picker at its one height", () => {
+    const { sheet, full } = open({ scrollable: false });
+    drag(40);
+    expect(settle().toValue).toBe(0);
+    expect(px(sheet.style.maxHeight)).toBe(full);
+  });
+});

package/src/FloatingPanel/FloatingPanel.spec.tsx

@@ -4,7 +4,7 @@ import { renderWithProviders } from "@multiplatform.one/test-utils";
 import { useState, type ReactNode } from "react";
 import { Text } from "tamagui";
 import { Button } from "../Button";
-import { FloatingPanel } from "./index";
+import { FloatingPanel, panelViewportPadding } from "./index";
 
 /**
  * The trigger contract, and why every case fires a REAL press rather than
@@ -336,6 +336,45 @@ describe("FloatingPanel trigger — floating mode", () => {
     });
   });
 
+  it("a pointer open focuses the pressed trigger, so Escape leaves focus there (LC-48)", async () => {
+    const result = renderWithProviders(<Harness trigger={<Button>Open Panel</Button>} />);
+    const trigger = result.container.querySelector("[role='button']") as HTMLElement;
+    pointerPress(trigger);
+    await waitFor(() => {
+      expect(floatingViewport()).not.toBeNull();
+    });
+    expect(document.activeElement).toBe(trigger);
+    fireEvent.keyDown(document, { key: "Escape" });
+    await waitFor(() => {
+      expect(floatingViewport()).toBeNull();
+    });
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    expect(document.activeElement).toBe(trigger);
+  });
+
+  it("Escape after a pointer open returns to that trigger, not the one focused before (LC-48)", async () => {
+    const result = renderWithProviders(
+      <>
+        <Harness trigger={<Button>First</Button>} />
+        <Harness trigger={<Button>Second</Button>} />
+      </>,
+    );
+    const [first, second] = Array.from(
+      result.container.querySelectorAll<HTMLElement>("[role='button']"),
+    );
+    first.focus();
+    pointerPress(second);
+    await waitFor(() => {
+      expect(floatingViewport()).not.toBeNull();
+    });
+    fireEvent.keyDown(document, { key: "Escape" });
+    await waitFor(() => {
+      expect(floatingViewport()).toBeNull();
+    });
+    await new Promise((resolve) => setTimeout(resolve, 400));
+    expect(document.activeElement).toBe(second);
+  });
+
   it("disconnects fill content observation on close and unmount", async () => {
     const observers: { target: Element; disconnected: boolean }[] = [];
     class TrackingResizeObserver {
@@ -370,3 +409,103 @@ describe("FloatingPanel trigger — floating mode", () => {
     }
   });
 });
+
+describe("FloatingPanel nesting (MPO-221)", () => {
+  it("a visible panel carries no transform, so a nested panel's position: fixed stays on the viewport", async () => {
+    const result = renderWithProviders(<Harness trigger={<Button>Open Panel</Button>} />);
+    pointerPress(result.container.querySelector("[role='button']") as Element);
+    await waitFor(() => expect(floatingViewport()).not.toBeNull());
+    const viewport = floatingViewport() as HTMLElement;
+    await waitFor(() => expect(viewport.style.opacity).toBe("1"));
+    expect(viewport.style.transform).toBe("none");
+    expect(viewport.style.position).toBe("fixed");
+  });
+
+  it("escapes a transformed, scrolled ancestor instead of positioning against it (MPO-335)", async () => {
+    const result = renderWithProviders(
+      <div
+        data-testid="scroller"
+        style={{ transform: "translateZ(0)", overflowY: "auto", height: 100 }}
+      >
+        <Harness trigger={<Button>Open Panel</Button>} />
+      </div>,
+    );
+    const scroller = result.getByTestId("scroller");
+    scroller.scrollTop = 40;
+    pointerPress(result.container.querySelector("[role='button']") as Element);
+    await waitFor(() => expect(floatingViewport()).not.toBeNull());
+    const viewport = floatingViewport() as HTMLElement;
+    expect(scroller.contains(viewport)).toBe(false);
+    // jsdom puts everything at viewport y 0, so the panel pins to the
+    // viewport padding, now in viewport coordinates with no scroller offset.
+    await waitFor(() => expect(viewport.style.top).toBe(`${panelViewportPadding}px`));
+  });
+
+  it("offsets its top by a transformed dialog it stays inside", async () => {
+    const result = renderWithProviders(
+      <div
+        role="dialog"
+        data-testid="dialog"
+        style={{ transform: "translateZ(0)", overflowY: "auto", height: 100 }}
+      >
+        <Harness trigger={<Button>Open Panel</Button>} />
+      </div>,
+    );
+    const dialog = result.getByTestId("dialog");
+    dialog.scrollTop = 40;
+    pointerPress(result.container.querySelector("[role='button']") as Element);
+    await waitFor(() => expect(floatingViewport()).not.toBeNull());
+    const viewport = floatingViewport() as HTMLElement;
+    expect(dialog.contains(viewport)).toBe(true);
+    // Laid out against the dialog, whose content is scrolled 40px, its css
+    // top must be 40px lower to land at the same viewport y.
+    await waitFor(() => expect(viewport.style.top).toBe(`${panelViewportPadding + 40}px`));
+  });
+});
+
+describe("FloatingPanel sheet — closed frame leaves the accessibility tree (MPO-359)", () => {
+  function SheetWithOutsideClose() {
+    const [open, setOpen] = useState(false);
+    return (
+      <>
+        <button type="button" onClick={() => setOpen(true)}>
+          Open sheet
+        </button>
+        <button type="button" onClick={() => setOpen(false)}>
+          Shut sheet
+        </button>
+        <FloatingPanel open={open} onOpenChange={setOpen} sheet trigger={<Text>anchor</Text>}>
+          <Button>Apply</Button>
+          <input aria-label="Draft" defaultValue="" />
+        </FloatingPanel>
+      </>
+    );
+  }
+
+  const frameOf = (el: Element) => el.closest("[tabindex='-1']") as HTMLElement;
+
+  it("marks a parked frame inert and aria-hidden, and lifts both when it reopens", async () => {
+    const result = renderWithProviders(<SheetWithOutsideClose />);
+    fireEvent.click(result.getByRole("button", { name: "Open sheet" }));
+    const apply = await result.findByRole("button", { name: "Apply" });
+    const frame = frameOf(apply);
+    expect(frame).not.toBeNull();
+    fireEvent.change(result.getByRole("textbox", { name: "Draft" }), {
+      target: { value: "acme" },
+    });
+
+    fireEvent.click(result.getByRole("button", { name: "Shut sheet" }));
+    await waitFor(() => {
+      expect(result.queryByRole("button", { name: "Apply" })).toBeNull();
+    });
+    expect(frame.isConnected).toBe(true);
+    expect(frame.hasAttribute("inert")).toBe(true);
+    expect(frame.getAttribute("aria-hidden")).toBe("true");
+
+    fireEvent.click(result.getByRole("button", { name: "Open sheet" }));
+    await result.findByRole("button", { name: "Apply" });
+    expect(frame.hasAttribute("inert")).toBe(false);
+    expect(frame.hasAttribute("aria-hidden")).toBe(false);
+    expect((result.getByRole("textbox", { name: "Draft" }) as HTMLInputElement).value).toBe("acme");
+  });
+});

package/src/FloatingPanel/FloatingPanel.stories.tsx

@@ -1,8 +1,10 @@
 import { useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
-import { H4, Paragraph, Separator, Text, View, YStack } from "tamagui";
+import { Preset } from "@multiplatform.one/theme";
+import { H4, Paragraph, ScrollView, Separator, Text, View, XStack, YStack } from "tamagui";
 import { FloatingPanel } from "./index";
 import { Button } from "../Button";
+import { Select } from "../fields/Select";
 import { formCommonColors } from "../shared/colorRamps";
 
 const meta: Meta<typeof FloatingPanel> = {
@@ -166,3 +168,86 @@ export const ForceSheet: Story = {
     );
   },
 };
+
+const scrollClipOptions = [
+  "Apple",
+  "Banana",
+  "Cherry",
+  "Date",
+  "Elderberry",
+  "Fig",
+  "Grape",
+  "Honeydew",
+].map((label) => ({ label, value: label.toLowerCase() }));
+
+function ScrollClipPair({ where }: { where: string }) {
+  const [open, setOpen] = useState(false);
+  const [value, setValue] = useState<string | undefined>(undefined);
+  return (
+    <YStack gap="$3" data-testid={`scroll-clip-pair-${where}`}>
+      <Select
+        label={`Select (${where})`}
+        placeholder="Pick a fruit"
+        options={scrollClipOptions}
+        value={value}
+        onValueChange={(next) => setValue(Array.isArray(next) ? next[0] : next)}
+      />
+      <FloatingPanel
+        open={open}
+        onOpenChange={setOpen}
+        trigger={<Button>{`FloatingPanel (${where})`}</Button>}
+      >
+        <YStack gap="$3" data-testid={`scroll-clip-panel-${where}`}>
+          <H4>Panel {where}</H4>
+          <Paragraph>
+            This body is taller than the space left in the scroll view, so a clipped panel loses its
+            lower half.
+          </Paragraph>
+          <Separator />
+          <Button onPress={() => setOpen(false)}>Close</Button>
+        </YStack>
+      </FloatingPanel>
+    </YStack>
+  );
+}
+
+/**
+ * MPO-335: react-native-web's ScrollView sets `transform: translateZ(0)`,
+ * which makes it the containing block of a `position: fixed` panel. Both
+ * controls sit at the bottom of a 260px ScrollView; opened, their panels
+ * must render in full past the scroller's edge, flush on the trigger, with
+ * the same theme and radius as the pair outside the scroller.
+ */
+export const InsideScrollView: Story = {
+  render: () => (
+    <Preset theme="blue" overrides={{ borderRadius: "large" }}>
+      <XStack padding="$4" gap="$6" alignItems="flex-start" flexWrap="wrap">
+        <YStack width={320} gap="$2">
+          <Paragraph color={formCommonColors.muted}>Inside a ScrollView</Paragraph>
+          <ScrollView
+            testID="scroll-clip-scroller"
+            height={260}
+            borderWidth={1}
+            borderColor="$borderColor"
+            borderRadius="$4"
+          >
+            <YStack padding="$3" gap="$3">
+              {Array.from({ length: 2 }, (_, i) => (
+                <Paragraph key={i} color={formCommonColors.muted}>
+                  Filler row {i + 1}
+                </Paragraph>
+              ))}
+              <ScrollClipPair where="inside" />
+            </YStack>
+          </ScrollView>
+        </YStack>
+        <YStack width={320} gap="$2">
+          <Paragraph color={formCommonColors.muted}>Outside, for comparison</Paragraph>
+          <YStack padding="$3" gap="$3">
+            <ScrollClipPair where="outside" />
+          </YStack>
+        </YStack>
+      </XStack>
+    </Preset>
+  ),
+};

package/src/FloatingPanel/PanelPortal.native.tsx

@@ -0,0 +1,15 @@
+import type { ReactNode } from "react";
+
+export interface PanelPortalProps {
+  anchor: unknown;
+  children: ReactNode;
+}
+
+export function panelPortalHost(): null {
+  return null;
+}
+
+/** Native panels are sheets and modals, never clipped by a scroll view. */
+export function PanelPortal({ children }: PanelPortalProps) {
+  return <>{children}</>;
+}

package/src/FloatingPanel/PanelPortal.tsx

@@ -0,0 +1,149 @@
+import type { CSSProperties, FocusEvent, ReactNode } from "react";
+import { useLayoutEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { TamaguiRoot, useThemeName } from "@tamagui/web";
+import { panelPortalAttribute, registerPanelPortal } from "../shared/panelPortal";
+
+export interface PanelPortalProps {
+  /** The element the panel opened from: the trigger it attaches to. */
+  anchor: HTMLElement | null;
+  children: ReactNode;
+}
+
+const layerRootSelector = '[role="dialog"], [aria-modal="true"]';
+
+const tabbableSelector =
+  'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+const focusGuardAttribute = "data-fp-focus-guard";
+
+const focusGuardStyle: CSSProperties = {
+  position: "fixed",
+  top: 0,
+  left: 0,
+  width: 1,
+  height: 1,
+  margin: -1,
+  padding: 0,
+  overflow: "hidden",
+  clipPath: "inset(50%)",
+  whiteSpace: "nowrap",
+  border: 0,
+};
+
+/**
+ * Where a web panel mounts: the nearest modal layer around its trigger, else
+ * the body. Staying inside a dialog keeps that dialog's focus trap and
+ * outside-press test treating the panel as its own content; every scroll
+ * view between the trigger and that layer is escaped either way.
+ */
+export function panelPortalHost(anchor: Element | null): HTMLElement | null {
+  if (typeof document === "undefined") return null;
+  return anchor?.closest<HTMLElement>(layerRootSelector) ?? document.body;
+}
+
+function isTabbable(element: HTMLElement): boolean {
+  if (element.hasAttribute(focusGuardAttribute) || element.tabIndex < 0) return false;
+  if (element.closest("[inert]")) return false;
+  return element.getClientRects().length > 0;
+}
+
+function tabbablesIn(root: Element | null): HTMLElement[] {
+  if (!root) return [];
+  return Array.from(root.querySelectorAll<HTMLElement>(tabbableSelector)).filter(isTabbable);
+}
+
+/** Tab order resumes beside the trigger, not at the end of the portal host. */
+function focusBesideAnchor(anchor: HTMLElement | null, side: "before" | "after") {
+  if (!anchor) return;
+  const inAnchor = tabbablesIn(anchor);
+  if (side === "before" && isTabbable(anchor)) inAnchor.unshift(anchor);
+  const own = side === "before" ? inAnchor[inAnchor.length - 1] : undefined;
+  if (own) {
+    own.focus();
+    return;
+  }
+  const edge =
+    side === "before" ? Node.DOCUMENT_POSITION_PRECEDING : Node.DOCUMENT_POSITION_FOLLOWING;
+  const page = tabbablesIn(document.body).filter((element) => {
+    if (anchor.contains(element) || !(anchor.compareDocumentPosition(element) & edge)) {
+      return false;
+    }
+    const portal = element.closest(`[${panelPortalAttribute}]`);
+    return !portal || portal.contains(anchor);
+  });
+  (side === "before" ? page[page.length - 1] : page[0])?.focus();
+}
+
+/**
+ * Web: renders a floating panel outside every scroll view between its trigger
+ * and the page (MPO-335, LC-90). react-native-web's ScrollView sets
+ * `transform: translateZ(0)`, which makes it the containing block of a
+ * `position: fixed` descendant, so a panel left in place is clipped by the
+ * scroller. The portal carries the trigger's theme across (knobs are React
+ * context and follow on their own). Hidden focus guards keep the panel in Tab
+ * order right after the trigger, where it sat before it moved.
+ */
+export function PanelPortal({ anchor, children }: PanelPortalProps) {
+  const themeName = useThemeName();
+  const portalRef = useRef<HTMLSpanElement | null>(null);
+  const host = panelPortalHost(anchor);
+  const direction = anchor?.closest("[dir]")?.getAttribute("dir") ?? undefined;
+
+  useLayoutEffect(() => {
+    const portal = portalRef.current;
+    if (!portal || !anchor) return;
+    return registerPanelPortal(portal, anchor);
+  }, [anchor, host]);
+
+  if (!host) return null;
+  // Stands where the panel used to be in tab order: right after the trigger.
+  const enterPanel = (event: FocusEvent<HTMLSpanElement>) => {
+    const guard = event.currentTarget;
+    const from = event.relatedTarget;
+    const forward =
+      !(from instanceof Node) ||
+      Boolean(guard.compareDocumentPosition(from) & Node.DOCUMENT_POSITION_PRECEDING);
+    const inside = tabbablesIn(portalRef.current);
+    const target = forward ? inside[0] : inside[inside.length - 1];
+    if (target) target.focus();
+    else focusBesideAnchor(anchor, forward ? "after" : "before");
+  };
+  const portal = createPortal(
+    <span
+      ref={portalRef}
+      {...{ [panelPortalAttribute]: "" }}
+      dir={direction}
+      style={{ display: "contents" }}
+    >
+      <span
+        {...{ [focusGuardAttribute]: "" }}
+        aria-hidden
+        tabIndex={0}
+        style={focusGuardStyle}
+        onFocus={() => focusBesideAnchor(anchor, "before")}
+      />
+      <TamaguiRoot theme={themeName}>{children}</TamaguiRoot>
+      <span
+        {...{ [focusGuardAttribute]: "" }}
+        aria-hidden
+        tabIndex={0}
+        style={focusGuardStyle}
+        onFocus={() => focusBesideAnchor(anchor, "after")}
+      />
+    </span>,
+    host,
+  );
+  return (
+    <>
+      <span
+        {...{ [focusGuardAttribute]: "" }}
+        aria-hidden
+        tabIndex={0}
+        style={focusGuardStyle}
+        onFocus={enterPanel}
+      />
+      {portal}
+    </>
+  );
+}