@multiplatform.one/forms 7.45.0 → 7.46.0

package/src/FloatingPanel/index.tsx

@@ -1,6 +1,8 @@
 import { transitionProps } from "@multiplatform.one/theme";
 import type { ReactNode, RefObject, UIEvent } from "react";
 import {
+  cloneElement,
+  isValidElement,
   useCallback,
   useEffect,
   useLayoutEffect,
@@ -16,6 +18,7 @@ import {
   useResolvedKnobs,
   wasKeyboardFocus,
   ensureKeyboardModalityTracking,
+  motionDurationMs,
 } from "@multiplatform.one/theme";
 import { isWeb, Sheet, View, YStack } from "tamagui";
 import { useClick, useDismiss, useInteractions } from "@floating-ui/react";
@@ -66,6 +69,9 @@ export interface FloatingPanelProps {
   /** Suppress delayed trigger focus when a consumer handles close focus itself. Web only. */
   skipReturnFocusRef?: RefObject<boolean>;
   trigger: ReactNode;
+  anchorMode?: "cover-trigger" | "attach";
+  triggerRow?: ReactNode;
+  anchorRect?: { x: number; y: number; width: number; height: number };
   triggerEcho?: boolean;
   /**
    * Optional control rendered beside the trigger but OUTSIDE the native press
@@ -168,7 +174,7 @@ export interface FloatingPanelProps {
    * COVER-TRIGGER (LC-105): the panel's top edge sits on the trigger's TOP
    * edge instead of attaching below it, so the trigger becomes the panel's
    * first row by default. Set triggerEcho=false for a custom first row. The panel scales from
-   * the trigger's top start corner. Dropping up, the bottom edges coincide.
+   * the trigger's top start corner. Viewport collisions use the bottom sheet.
    * Enabled by default. Web float only; the native and narrow-web sheet is unchanged.
    */
   cover?: boolean;
@@ -201,7 +207,7 @@ function useKeyboardFocusIntoPanel(
       if (!wasKeyboardFocus() && !keyboardOpenRef?.current) return;
       const active = document.activeElement;
       if (active instanceof HTMLElement && frame.contains(active) && active !== frame) return;
-      // The trigger echo row is presentation only (inert): skip its controls.
+      // Initial keyboard focus belongs to an action, not the repeated close row.
       const first = Array.from(frame.querySelectorAll<HTMLElement>(PANEL_FOCUSABLE)).find(
         (el) => !el.closest("[data-fp-trigger-row]"),
       );
@@ -254,12 +260,12 @@ function fixedContainingBlockOrigin(element: HTMLElement): { top: number; left:
   return { top: 0, left: 0 };
 }
 
-function isRtl(): boolean {
-  return (
-    isWeb &&
-    typeof document !== "undefined" &&
-    document.documentElement.getAttribute("dir") === "rtl"
-  );
+function isRtl(element?: HTMLElement | null): boolean {
+  if (!isWeb || typeof document === "undefined") return false;
+  const direction = element ? getComputedStyle(element).direction : "";
+  return direction
+    ? direction === "rtl"
+    : (element?.closest("[dir]") ?? document.documentElement).getAttribute("dir") === "rtl";
 }
 
 function panelTransformOrigin(placement: string): string {
@@ -297,41 +303,94 @@ const ECHO_STRIPPED_ATTRIBUTES = [
 function TriggerEchoRow({
   sourceRef,
   onPress,
+  children,
+  anchorRect,
+  source,
 }: {
   sourceRef: RefObject<HTMLElement | null>;
   onPress: () => void;
+  children?: ReactNode;
+  anchorRect?: FloatingPanelProps["anchorRect"];
+  source: ReactNode;
 }) {
   const rowRef = useRef<HTMLElement | null>(null);
+  const visualRef = useRef<HTMLElement | null>(null);
   useLayoutEffect(() => {
     const row = rowRef.current;
     const source = sourceRef.current;
     if (!row || !source || typeof source.cloneNode !== "function") return;
-    const snapshot = source.cloneNode(true) as HTMLElement;
-    const sourceFields = source.querySelectorAll<HTMLInputElement>("input, textarea");
-    const snapshotFields = snapshot.querySelectorAll<HTMLInputElement>("input, textarea");
-    sourceFields.forEach((field, index) => {
-      const copy = snapshotFields[index];
-      if (copy) copy.value = field.value;
-    });
-    for (const node of [snapshot, ...Array.from(snapshot.querySelectorAll<HTMLElement>("*"))]) {
-      for (const name of ECHO_STRIPPED_ATTRIBUTES) node.removeAttribute(name);
-      if (node.hasAttribute("tabindex") || node.matches("input, textarea, button, a, select")) {
-        node.setAttribute("tabindex", "-1");
+    const sync = () => {
+      const control = source.matches(PANEL_FOCUSABLE)
+        ? source
+        : source.querySelector<HTMLElement>(PANEL_FOCUSABLE);
+      const labelledBy = control?.getAttribute("aria-labelledby");
+      const label =
+        control?.getAttribute("aria-label") ||
+        labelledBy
+          ?.split(/\s+/)
+          .map((id) => document.getElementById(id)?.textContent || "")
+          .join(" ") ||
+        control?.textContent ||
+        source.textContent ||
+        "";
+      row.setAttribute("aria-label", label);
+      const rect = anchorRect ?? source.getBoundingClientRect();
+      row.style.width = `${rect.width}px`;
+      row.style.height = `${rect.height}px`;
+      const rtl = isRtl(source);
+      row.style.alignSelf = "flex-start";
+      const frameStyle = row.parentElement ? getComputedStyle(row.parentElement) : null;
+      row.style.marginTop = `${-(parseFloat(frameStyle?.borderTopWidth || "0") || 0)}px`;
+      row.style.position = "sticky";
+      row.style.top = row.style.marginTop;
+      row.style.zIndex = "1";
+      row.style.marginLeft = rtl
+        ? ""
+        : `${-(parseFloat(frameStyle?.borderLeftWidth || "0") || 0)}px`;
+      row.style.marginRight = rtl
+        ? `${-(parseFloat(frameStyle?.borderRightWidth || "0") || 0)}px`
+        : "";
+      const snapshot =
+        children == null ? (source.cloneNode(true) as HTMLElement) : visualRef.current;
+      if (!snapshot) return;
+      const sourceFields = source.querySelectorAll<HTMLInputElement>("input, textarea");
+      const snapshotFields = snapshot.querySelectorAll<HTMLInputElement>("input, textarea");
+      sourceFields.forEach((field, index) => {
+        const copy = snapshotFields[index];
+        if (copy) copy.value = field.value;
+      });
+      for (const node of [snapshot, ...Array.from(snapshot.querySelectorAll<HTMLElement>("*"))]) {
+        for (const name of ECHO_STRIPPED_ATTRIBUTES) node.removeAttribute(name);
+        if (node.hasAttribute("tabindex") || node.matches("input, textarea, button, a, select")) {
+          node.setAttribute("tabindex", "-1");
+        }
       }
-    }
-    snapshot.setAttribute("inert", "");
-    row.replaceChildren(snapshot);
-  });
+      snapshot.setAttribute("inert", "");
+      snapshot.setAttribute("aria-hidden", "true");
+      if (children == null) visualRef.current?.replaceChildren(snapshot);
+    };
+    sync();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(sync);
+    observer.observe(source);
+    return () => observer.disconnect();
+  }, [sourceRef, source, children, anchorRect]);
   return (
     <View
       ref={rowRef as any}
       data-fp-trigger-row=""
-      aria-hidden
+      role="button"
+      aria-expanded={true}
+      tabIndex={-1}
       cursor="pointer"
       onPress={onPress}
       flexShrink={0}
       pointerEvents="auto"
-    />
+    >
+      <View ref={visualRef as any} pointerEvents="none" aria-hidden>
+        {isValidElement(children) ? cloneElement(children, { ref: null } as any) : children}
+      </View>
+    </View>
   );
 }
 
@@ -373,7 +432,11 @@ export function FloatingPanel(props: FloatingPanelProps) {
   const shouldUseSheet = props.sheet ?? (!isWeb || !viewportGtSm);
   // The panel floats over the page: its content never sits on a painted
   // ancestor, so a Card inside it paints as top-level.
-  const panelProps = { ...props, children: <Surface painted={false}>{props.children}</Surface> };
+  const panelProps = {
+    ...props,
+    cover: props.anchorMode ? props.anchorMode === "cover-trigger" : props.cover,
+    children: <Surface painted={false}>{props.children}</Surface>,
+  };
 
   if (shouldUseSheet) return <FloatingPanelSheet {...panelProps} />;
   return <FloatingPanelWeb {...panelProps} />;
@@ -416,7 +479,8 @@ function FloatingPanelSheet({
   header,
   scrollViewProps,
   openOn = "press",
-}: FloatingPanelProps) {
+  escapeTarget = "window",
+}: FloatingPanelProps & { escapeTarget?: "window" | "document" }) {
   const { knobProps } = useResolvedKnobs({ painted: false });
   // LC-24 / A-ENTEREXIT: honor animation=none (undefined) — do not hardcode "medium".
   const slideMotion = {
@@ -438,7 +502,7 @@ function FloatingPanelSheet({
   };
   // Tamagui Sheet has no key handling (unlike the web floating mode, which
   // dismisses on Escape) — wire the dismissal intent here too.
-  useSheetEscapeDismiss(open, () => handleOpenChange(false));
+  useSheetEscapeDismiss(open, () => handleOpenChange(false), escapeTarget);
   // DG-A11Y-04 / Axiom 7: Sheet has no focus scope — move focus into the
   // frame on open, trap Tab while open, return focus to the trigger on close.
   const sheetFrameRef = useRef<HTMLElement | null>(null);
@@ -484,23 +548,25 @@ function FloatingPanelSheet({
 
   return (
     <>
-      <View
-        flexDirection="row"
-        alignItems="center"
-        width={triggerSizing === "content" ? "auto" : "100%"}
-      >
+      {trigger != null && (
         <View
-          flex={triggerSizing === "content" ? undefined : 1}
-          minWidth={0}
-          {...(isContextMenu ? undefined : { onPress: openFromTrigger })}
-          cursor={disabled ? "not-allowed" : "pointer"}
-          opacity={disabled ? 0.5 : 1}
-          {...triggerActivation}
+          flexDirection="row"
+          alignItems="center"
+          width={triggerSizing === "content" ? "auto" : "100%"}
         >
-          {trigger}
+          <View
+            flex={triggerSizing === "content" ? undefined : 1}
+            minWidth={0}
+            {...(isContextMenu ? undefined : { onPress: openFromTrigger })}
+            cursor={disabled ? "not-allowed" : "pointer"}
+            opacity={disabled ? 0.5 : 1}
+            {...triggerActivation}
+          >
+            {trigger}
+          </View>
+          {triggerEnd}
         </View>
-        {triggerEnd}
-      </View>
+      )}
       <Sheet
         modal
         open={open}
@@ -521,6 +587,7 @@ function FloatingPanelSheet({
         />
         <Sheet.Handle />
         <Sheet.Frame
+          data-testid="floating-panel-sheet"
           // Sheet.Frame forwards its ref at runtime; the styled prop type
           // just omits `ref`, hence the cast. tabIndex -1 makes the frame a
           // programmatic focus target without joining the tab order.
@@ -562,7 +629,11 @@ function FloatingPanelWeb({
   openOn = "press",
   cover = true,
   triggerEcho = true,
+  triggerRow,
+  anchorRect,
+  ...sheetProps
 }: FloatingPanelProps) {
+  const [collisionSheet, setCollisionSheet] = useState(false);
   const isFill = sizing === "fill";
   const isContextMenu = openOn === "contextmenu";
   const overlayStyleRef = useRef<{ top: number; left?: number; maxHeight: number } | null>(null);
@@ -591,7 +662,7 @@ function FloatingPanelWeb({
   };
 
   const panel = useFloatingPanel({
-    open,
+    open: open && !collisionSheet,
     onOpenChange,
     disabled,
     repositionRef: repositionFnRef,
@@ -607,14 +678,27 @@ function FloatingPanelWeb({
   // Escape (or outside click on empty space) closes the panel while focus is
   // inside it, focus falls to <body>. Return it to the pre-open element
   // (the trigger's focusable). Deliberate focus moves elsewhere are kept.
-  useReturnFocusOnClose(open, skipReturnFocusRef);
-  useKeyboardFocusIntoPanel(open && panel.mounted, panel.refs.floating, keyboardOpenRef);
+  useReturnFocusOnClose(open, skipReturnFocusRef, panel.refs.floating);
+  useKeyboardFocusIntoPanel(
+    open && panel.mounted && !collisionSheet,
+    panel.refs.floating,
+    keyboardOpenRef,
+  );
   useEffect(() => {
     if (open) return;
     keyboardOpenRef.current = false;
     anchorPointRef.current = null;
   }, [open]);
 
+  useEffect(() => {
+    if (open || !collisionSheet) return;
+    const timer = setTimeout(
+      () => setCollisionSheet(false),
+      motionDurationMs(panel.knobProps.motion.slide.transition),
+    );
+    return () => clearTimeout(timer);
+  }, [open, collisionSheet, panel.knobProps.motion.slide.transition]);
+
   const repositionOverlay = useCallback(() => {
     const dropdownElement = panel.refs.floating.current;
     const trig = panel.triggerRef.current;
@@ -630,7 +714,16 @@ function FloatingPanelWeb({
     const point = isContextMenu
       ? (anchorPointRef.current ?? referenceCornerPoint(trig, isRtl()))
       : null;
-    const triggerBounds = point ? { top: point.y, bottom: point.y } : trig.getBoundingClientRect();
+    const measured = anchorRect
+      ? {
+          ...anchorRect,
+          top: anchorRect.y,
+          left: anchorRect.x,
+          right: anchorRect.x + anchorRect.width,
+          bottom: anchorRect.y + anchorRect.height,
+        }
+      : trig.getBoundingClientRect();
+    const triggerBounds = point ? { top: point.y, bottom: point.y } : measured;
     const viewportHeight = window.innerHeight;
     const cs = getComputedStyle(dropdownElement);
     const borderTopWidth = parseFloat(cs.borderTopWidth) || 0;
@@ -641,6 +734,70 @@ function FloatingPanelWeb({
     const liveTransition = panel.panelTransition;
     const containingBlock = fixedContainingBlockOrigin(dropdownElement);
 
+    if (cover && !point) {
+      const rtl = isRtl(trig);
+      const viewport = window.visualViewport;
+      const viewportLeft = viewport?.offsetLeft ?? 0;
+      const viewportTop = viewport?.offsetTop ?? 0;
+      const viewportRight =
+        viewportLeft +
+        (viewport?.width ?? (document.documentElement.clientWidth || window.innerWidth));
+      const viewportBottom = viewportTop + (viewport?.height ?? window.innerHeight);
+      dropdownElement.style.left = `${viewportLeft - containingBlock.left}px`;
+      const layoutStyle = getComputedStyle(dropdownElement);
+      const scale =
+        layoutStyle.transform &&
+        layoutStyle.transform !== "none" &&
+        typeof DOMMatrixReadOnly !== "undefined"
+          ? Math.abs(new DOMMatrixReadOnly(layoutStyle.transform).a)
+          : 1;
+      const layoutWidth = dropdownElement.getBoundingClientRect().width / (scale || 1);
+      const width = Math.max(layoutWidth || dropdownElement.offsetWidth, measured.width);
+      const left = rtl ? measured.right - width : measured.left;
+      const firstActionHeight =
+        contentRef.current?.querySelector<HTMLElement>(PANEL_FOCUSABLE)?.getBoundingClientRect()
+          .height ||
+        Number(panel.knobProps.menuRow.minHeight) ||
+        totalContentHeight;
+      const bodyStyle = contentRef.current ? getComputedStyle(contentRef.current) : null;
+      const bodyPadding =
+        (parseFloat(bodyStyle?.paddingTop || "0") || 0) +
+        (parseFloat(bodyStyle?.paddingBottom || "0") || 0);
+      const neededHeight = sheetProps.scrollable
+        ? Math.min(
+            totalContentHeight,
+            measured.height + firstActionHeight + bodyPadding + totalBorderWidth,
+          )
+        : totalContentHeight;
+      if (
+        measured.width > 0 &&
+        measured.height > 0 &&
+        (left < viewportLeft ||
+          left + width > Math.max(measured.right, viewportRight - panelViewportPadding) ||
+          measured.right > viewportRight ||
+          measured.top < viewportTop ||
+          measured.top + Math.max(neededHeight, measured.height) >
+            viewportBottom - panelViewportPadding)
+      ) {
+        dropdownElement.style.visibility = "hidden";
+        setCollisionSheet(true);
+        return;
+      }
+      const top = measured.top - containingBlock.top;
+      const cssLeft = left - containingBlock.left;
+      const maxHeight = Math.max(0, viewportBottom - panelViewportPadding - measured.top);
+      dropdownElement.style.top = `${top}px`;
+      dropdownElement.style.left = `${cssLeft}px`;
+      dropdownElement.style.maxHeight = `${maxHeight}px`;
+      dropdownElement.dir = rtl ? "rtl" : "ltr";
+      dropdownElement.style.transformOrigin = rtl ? "top right" : "top left";
+      dropdownElement.style.visibility = "visible";
+      overlayStyleRef.current = { top, left: cssLeft, maxHeight };
+      panel.initializingRef.current = false;
+      if (isInitial) dropdownElement.style.transition = liveTransition;
+      return;
+    }
+
     let isDropup = panel.placement.startsWith("top");
     let cssLeft: number | undefined;
     if (point) {
@@ -794,6 +951,8 @@ function FloatingPanelWeb({
     isFill,
     isContextMenu,
     cover,
+    anchorRect,
+    sheetProps.scrollable,
     panel.placement,
     panel.refs,
     panel.triggerRef,
@@ -805,9 +964,10 @@ function FloatingPanelWeb({
 
   const click = useClick(panel.context, {
     event: "mousedown",
-    enabled: !isContextMenu,
+    enabled: !isContextMenu && !collisionSheet,
   });
   const dismiss = useDismiss(panel.context, {
+    enabled: !collisionSheet,
     // Use 'click' instead of default 'pointerdown' so scrolling to the bottom
     // (e.g. via wheel/trackpad or scroll arrow hover) doesn't trigger outside-press.
     outsidePressEvent: "click",
@@ -820,11 +980,17 @@ function FloatingPanelWeb({
   useLayoutEffect(() => {
     if (!open || !panel.mounted) return;
     repositionOverlay();
-  }, [open, panel.mounted, repositionOverlay, panel.y]);
+  }, [open, panel.mounted, repositionOverlay, panel.y, panel.x]);
 
   useLayoutEffect(() => {
     const content = contentRef.current;
-    if (!open || !panel.mounted || !isFill || !content || typeof ResizeObserver === "undefined") {
+    if (
+      !open ||
+      !panel.mounted ||
+      (!isFill && !cover) ||
+      !content ||
+      typeof ResizeObserver === "undefined"
+    ) {
       return;
     }
     // Matching the trigger width can rewrap content after the panel's first
@@ -839,17 +1005,18 @@ function FloatingPanelWeb({
       });
     });
     observer.observe(content);
+    if (panel.triggerRef.current) observer.observe(panel.triggerRef.current);
     return () => {
       observer.disconnect();
       if (frame) cancelAnimationFrame(frame);
     };
-  }, [open, panel.mounted, isFill, repositionOverlay]);
+  }, [open, panel.mounted, isFill, cover, repositionOverlay, panel.triggerRef]);
 
   const handleScroll = useCallback(
     (event: UIEvent) => {
       const el = event.target as HTMLElement;
       panel.updateArrows(el);
-      if (isFill) return;
+      if (isFill || (cover && !isContextMenu)) return;
       if (panel.initializingRef.current) {
         lastScrollTopRef.current = el.scrollTop;
         return;
@@ -873,7 +1040,7 @@ function FloatingPanelWeb({
         repositionFnRef.current?.();
       }
     },
-    [isFill, panel.updateArrows],
+    [isFill, cover, isContextMenu, panel.updateArrows],
   );
 
   const webTransition = panel.panelTransition;
@@ -976,6 +1143,7 @@ function FloatingPanelWeb({
     <>
       <View
         {...referenceProps}
+        alignSelf={sheetProps.triggerSizing === "content" ? "flex-start" : undefined}
         cursor={disabled ? "not-allowed" : "pointer"}
         opacity={disabled ? 0.5 : 1}
         // The cover contract is stated as a relation between the panel's top
@@ -989,7 +1157,22 @@ function FloatingPanelWeb({
         {trigger}
       </View>
 
-      {panel.mounted && (
+      {collisionSheet && (
+        <FloatingPanelSheet
+          {...sheetProps}
+          open={open}
+          onOpenChange={onOpenChange}
+          trigger={null}
+          // The trigger's Tooltip stops Escape at document. The float's
+          // useDismiss listens there too, so the fallback must as well.
+          escapeTarget="document"
+          skipReturnFocusRef={skipReturnFocusRef}
+          contentPadding={contentPadding}
+        >
+          {children}
+        </FloatingPanelSheet>
+      )}
+      {panel.mounted && !collisionSheet && (
         <PanelPortal anchor={panel.triggerRef.current}>
           <YStack
             {...getFloatingProps({
@@ -1002,6 +1185,7 @@ function FloatingPanelWeb({
                 scrollbarWidth: "none" as any,
                 zIndex: zIndex.dropdown,
                 overflow: "auto",
+                ...(cover && !isContextMenu ? { overflowX: "hidden" as const } : {}),
                 ...panel.floatingStyleRef.current,
                 ...(overlayStyleRef.current
                   ? { maxHeight: overlayStyleRef.current.maxHeight }
@@ -1012,11 +1196,16 @@ function FloatingPanelWeb({
                 // then positions against this box and is clipped by its scroll.
                 transform: panel.visible ? "none" : "scale(0.96)",
                 transition: webTransition,
-                transformOrigin: panelTransformOrigin(
-                  pointPlacementRef.current
-                    ? `${pointPlacementRef.current.dropup ? "top" : "bottom"}-${pointPlacementRef.current.alignEnd ? "end" : "start"}`
-                    : panel.placement,
-                ),
+                transformOrigin:
+                  cover && !isContextMenu
+                    ? isRtl(panel.triggerRef.current)
+                      ? "top right"
+                      : "top left"
+                    : panelTransformOrigin(
+                        pointPlacementRef.current
+                          ? `${pointPlacementRef.current.dropup ? "top" : "bottom"}-${pointPlacementRef.current.alignEnd ? "end" : "start"}`
+                          : panel.placement,
+                      ),
               },
               onScroll: handleScroll,
               onTransitionEnd: (event) => {
@@ -1042,7 +1231,14 @@ function FloatingPanelWeb({
             paddingVertical={0}
           >
             {isContextMenu || !cover || !triggerEcho ? null : (
-              <TriggerEchoRow sourceRef={panel.triggerRef} onPress={() => onOpenChange(false)} />
+              <TriggerEchoRow
+                sourceRef={panel.triggerRef}
+                source={trigger}
+                anchorRect={anchorRect}
+                onPress={() => onOpenChange(false)}
+              >
+                {triggerRow}
+              </TriggerEchoRow>
             )}
             <ScrollArrow
               direction="up"

package/src/FloatingPanel/useFloatingPanel.spec.tsx

@@ -158,12 +158,14 @@ describe("FloatingPanel and DropdownMenu open over their trigger (MPO-38 cover r
     expect(viewport.style.transformOrigin.startsWith("top")).toBe(true);
   });
 
-  it("the trigger's own label is the panel's first row, presentation only", async () => {
+  it("the trigger's own label is the panel's first close row", async () => {
     const viewport = await openPanel({});
     const echo = viewport.querySelector("[data-fp-trigger-row]") as HTMLElement;
     expect(echo).toBeTruthy();
     expect(echo.textContent).toContain("Actions");
-    expect(echo.getAttribute("aria-hidden")).toBe("true");
+    expect(echo.getAttribute("aria-hidden")).toBeNull();
+    expect(echo.getAttribute("role")).toBe("button");
+    expect(echo.getAttribute("aria-label")).toBe("Actions");
     const firstRow = Array.from(viewport.children).find((el) =>
       (el as HTMLElement).textContent?.trim(),
     );

package/src/shared/focusManagement.spec.tsx

@@ -33,7 +33,7 @@ for (const mode of ["floating", "sheet"] as const) {
       const hook = renderHook(
         ({ open }) => {
           if (mode === "sheet") useSheetModalFocus(open, frameRef, skipReturnFocusRef);
-          else useReturnFocusOnClose(open, skipReturnFocusRef);
+          else useReturnFocusOnClose(open, skipReturnFocusRef, frameRef);
         },
         { initialProps: { open: true }, wrapper: Wrapper },
       );
@@ -76,6 +76,16 @@ for (const mode of ["floating", "sheet"] as const) {
       expect(document.activeElement).toBe(h.trigger);
     });
 
+    it("returns focus left inside the closing frame before the frame unmounts", async () => {
+      const h = setup();
+      h.setAnimation("none");
+      h.rerender({ open: true });
+      h.item.focus();
+      h.rerender({ open: false });
+      await act(() => vi.advanceTimersByTimeAsync(50));
+      expect(document.activeElement).toBe(h.trigger);
+    });
+
     it("honors suppression set after close, before the delayed restore", async () => {
       const h = setup();
       h.trigger.blur();

package/src/shared/focusManagement.ts

@@ -6,9 +6,9 @@
  * only remembers a `Dialog.Trigger` mounted inside the Dialog. These hooks
  * close that gap:
  *
- * - `useReturnFocusOnClose(open)` — capture the focused element when `open`
- *   flips true; when it flips false, return focus to it IF focus was dropped
- *   (on body, or stranded inside a hidden/removed overlay). Never steals
+ * - `useReturnFocusOnClose(open, skip?, insideRef?)` — capture the focused
+ *   element when `open` flips true; when it flips false, return focus to it
+ *   IF focus was dropped (on body, or stranded inside the closing overlay). Never steals
  *   focus the user deliberately moved elsewhere (outside-click onto another
  *   control).
  * - `useSheetModalFocus(open, frameRef)` — sheet-mode complement: also moves
@@ -96,8 +96,17 @@ function restoreLater(
   setTimeout(restore, delayMs);
 }
 
-/** Restore focus to the element focused at open time, on close (web only). */
-export function useReturnFocusOnClose(open: boolean, skipReturnFocusRef?: RefObject<boolean>) {
+/**
+ * Restore focus to the element focused at open time, on close (web only).
+ * `insideRef` is the closing overlay's frame: focus still inside it counts as
+ * dropped, because it falls to <body> when the frame unmounts after the exit
+ * and no retry runs that late.
+ */
+export function useReturnFocusOnClose(
+  open: boolean,
+  skipReturnFocusRef?: RefObject<boolean>,
+  insideRef?: RefObject<HTMLElement | null>,
+) {
   const { prevRef, generationRef } = useCaptureOnOpen(open);
   const { knobProps } = useResolvedKnobs();
   const restoreDelayMsRef = useRef(0);
@@ -109,10 +118,10 @@ export function useReturnFocusOnClose(open: boolean, skipReturnFocusRef?: RefObj
         prevRef,
         generationRef,
         restoreDelayMsRef.current,
-        undefined,
+        insideRef,
         skipReturnFocusRef,
       );
-  }, [open, prevRef, generationRef, skipReturnFocusRef]);
+  }, [open, prevRef, generationRef, skipReturnFocusRef, insideRef]);
 }
 
 /**

package/src/shared/interactionHooks.spec.tsx

@@ -61,6 +61,19 @@ describe("useSheetEscapeDismiss", () => {
     expect(second).toHaveBeenCalledTimes(1);
   });
 
+  it("listens on document when asked, so a document-level stopPropagation cannot block it", () => {
+    const onDismiss = vi.fn();
+    const stop = (event: Event) => event.stopPropagation();
+    document.addEventListener("keydown", stop);
+    try {
+      renderHook(() => useSheetEscapeDismiss(true, onDismiss, "document"));
+      document.dispatchEvent(new KeyboardEvent("keydown", { key: "Escape", bubbles: true }));
+      expect(onDismiss).toHaveBeenCalledTimes(1);
+    } finally {
+      document.removeEventListener("keydown", stop);
+    }
+  });
+
   it("detaches the listener on unmount", () => {
     const onDismiss = vi.fn();
     const { unmount } = renderHook(() => useSheetEscapeDismiss(true, onDismiss));

package/src/shared/useSheetEscapeDismiss.ts

@@ -11,7 +11,11 @@ import { isWeb } from "tamagui";
  * comboboxes) that own Escape call stopPropagation()/preventDefault() and
  * keep the sheet open.
  */
-export function useSheetEscapeDismiss(enabled: boolean, onDismiss: () => void) {
+export function useSheetEscapeDismiss(
+  enabled: boolean,
+  onDismiss: () => void,
+  target: "window" | "document" = "window",
+) {
   const onDismissRef = useRef(onDismiss);
   onDismissRef.current = onDismiss;
   useEffect(() => {
@@ -20,7 +24,8 @@ export function useSheetEscapeDismiss(enabled: boolean, onDismiss: () => void) {
       if (event.key !== "Escape" || event.defaultPrevented) return;
       onDismissRef.current();
     };
-    window.addEventListener("keydown", onKeyDown);
-    return () => window.removeEventListener("keydown", onKeyDown);
-  }, [enabled]);
+    const node = target === "document" ? document : window;
+    node.addEventListener("keydown", onKeyDown as EventListener);
+    return () => node.removeEventListener("keydown", onKeyDown as EventListener);
+  }, [enabled, target]);
 }