@bearmenu/ui 0.8.42 → 0.8.43

package/dist/components/responsive-overlay.d.ts

@@ -64,6 +64,22 @@ type ResponsiveOverlayProps = {
      * keeps today's default in every mode (dialog, sheet, drawer).
      */
     initialFocusRef?: React.RefObject<HTMLElement | null>;
+    /**
+     * Whether closing the overlay returns focus to whatever had it before the
+     * overlay opened. Two things do that today: Radix's `onCloseAutoFocus` —
+     * the FocusScope's own auto-focus-on-unmount, refocusing the element that
+     * was active before the overlay trapped focus — and this component's own
+     * `useFocusReturn`, which refocuses that same element a frame later so it
+     * survives the overlay's own unmount. `true` (the default) keeps today's
+     * behaviour in every mode (dialog, sheet, drawer): the opener gets focus
+     * back.
+     *
+     * Pass `false` when closing hands focus to another surface that takes it
+     * itself — a pick-mode bar docking over the header, say. Both paths are
+     * disabled and focus stays wherever the consumer puts it (typically inside
+     * the same `onOpenChange(false)` handler that closes the overlay).
+     */
+    returnFocus?: boolean;
     /**
      * A fixed height for the phone drawer instead of sizing to its content —
      * `DrawerContent`'s `snapHeight` (the frames' ~640px table sheet). Applies

package/dist/components/responsive-overlay.js

@@ -15,7 +15,7 @@ var CONTAINER_DESCRIPTION = {
   dialog: DialogDescription,
   sheet: SheetDescription
 };
-function useFocusReturn(open) {
+function useFocusReturn(open, returnFocus) {
   const openerRef = React.useRef(null);
   const wasOpen = React.useRef(false);
   React.useEffect(() => {
@@ -26,7 +26,7 @@ function useFocusReturn(open) {
     if (wasOpen.current) {
       wasOpen.current = false;
       const opener = openerRef.current;
-      if (opener && opener.isConnected) {
+      if (returnFocus && opener && opener.isConnected) {
         requestAnimationFrame(() => opener.focus());
       }
     }
@@ -39,7 +39,7 @@ function useFocusReturn(open) {
     }
     document.addEventListener("focusin", track);
     return () => document.removeEventListener("focusin", track);
-  }, [open]);
+  }, [open, returnFocus]);
 }
 var ResponsiveOverlay = React.forwardRef(
   ({
@@ -57,11 +57,12 @@ var ResponsiveOverlay = React.forwardRef(
     className,
     bodyClassName,
     initialFocusRef,
+    returnFocus = true,
     drawerHeight
   }, ref) => {
     const isWide = useMediaQuery(wideFrom === "lg" ? DESKTOP_MEDIA_QUERY : MD_MEDIA_QUERY);
     const container = isWide ? desktop : "drawer";
-    useFocusReturn(open);
+    useFocusReturn(open, returnFocus);
     const handleOpenAutoFocus = React.useCallback(
       (event) => {
         if (!(initialFocusRef == null ? void 0 : initialFocusRef.current)) return;
@@ -70,6 +71,12 @@ var ResponsiveOverlay = React.forwardRef(
       },
       [initialFocusRef]
     );
+    const handleCloseAutoFocus = React.useCallback(
+      (event) => {
+        if (!returnFocus) event.preventDefault();
+      },
+      [returnFocus]
+    );
     const describedBy = subtitle ? {} : { "aria-describedby": void 0 };
     const Title = CONTAINER_TITLE[container];
     const Description = CONTAINER_DESCRIPTION[container];
@@ -129,7 +136,8 @@ var ResponsiveOverlay = React.forwardRef(
           attachment: "inset",
           hideClose: true,
           overlayClassName: "bg-scrim-overlay backdrop-blur-none",
-          onOpenAutoFocus: handleOpenAutoFocus
+          onOpenAutoFocus: handleOpenAutoFocus,
+          onCloseAutoFocus: handleCloseAutoFocus
         }, describedBy), {
           "data-slot": "responsive-overlay-sheet",
           "data-modal": modal ? "true" : "false"
@@ -154,7 +162,8 @@ var ResponsiveOverlay = React.forwardRef(
           size,
           showCloseButton: false,
           overlayClassName: "bg-scrim-overlay backdrop-blur-none",
-          onOpenAutoFocus: handleOpenAutoFocus
+          onOpenAutoFocus: handleOpenAutoFocus,
+          onCloseAutoFocus: handleCloseAutoFocus
         }, describedBy), {
           className: cn(
             // The dialog's own `grid gap-4 p-6` would put air between the
@@ -175,7 +184,8 @@ var ResponsiveOverlay = React.forwardRef(
       __spreadProps(__spreadValues(__spreadValues({
         ref,
         overlayClassName: "bg-scrim-overlay",
-        onOpenAutoFocus: handleOpenAutoFocus
+        onOpenAutoFocus: handleOpenAutoFocus,
+        onCloseAutoFocus: handleCloseAutoFocus
       }, drawerHeight !== void 0 ? { snapHeight: drawerHeight } : {}), describedBy), {
         className: cn("flex max-h-[85vh] flex-col p-0", className),
         children: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bearmenu/ui",
-  "version": "0.8.42",
+  "version": "0.8.43",
   "description": "BearMenu design system — shared UI tokens, primitives, and components",
   "license": "UNLICENSED",
   "repository": {

package/src/components/responsive-overlay.stories.tsx

@@ -122,6 +122,65 @@ export const FormRail: Story = {
   },
 };
 
+/**
+ * `returnFocus={false}` — closing hands off to a surface that takes focus
+ * itself, rather than returning it to the opener. Here that surface is a
+ * pick-mode bar docking over the header: click "Add item", then "Pick a
+ * table" inside it — focus lands on the bar's own button, not back on
+ * "Add item".
+ */
+export const HandsOffFocusOnClose: Story = {
+  render: () => {
+    const [open, setOpen] = React.useState(false);
+    const [pickMode, setPickMode] = React.useState(false);
+    const pickButtonRef = React.useRef<HTMLButtonElement>(null);
+
+    return (
+      <div className="relative">
+        {pickMode ? (
+          <div className="mb-3 flex items-center justify-between rounded-lg border border-border bg-surface-2 p-3">
+            <span className="text-[14px] font-medium">Pick a table on the floor</span>
+            <Button ref={pickButtonRef} variant="outline" onClick={() => setPickMode(false)}>
+              Cancel
+            </Button>
+          </div>
+        ) : null}
+        <Button variant="cta" onClick={() => setOpen(true)}>
+          Add item
+        </Button>
+        <ResponsiveOverlay
+          open={open}
+          onOpenChange={(next) => {
+            if (!next) {
+              // The overlay hands off to the pick-mode bar itself — it moves
+              // focus into its own "Cancel" button before the overlay even
+              // starts unmounting, so the overlay must not fight it back.
+              setPickMode(true);
+              requestAnimationFrame(() => pickButtonRef.current?.focus());
+            }
+            setOpen(next);
+          }}
+          title="Add an item"
+          subtitle="Table 18 · from the menu"
+          closeLabel="Close"
+          returnFocus={false}
+          footer={
+            <ActionBar
+              secondary={<Button variant="outline">Pick a table</Button>}
+              primary={<Button variant="cta">Add 1 item</Button>}
+            />
+          }
+        >
+          <p className="text-[14px] text-muted-foreground">
+            Closing this does not return focus to "Add item" — the pick-mode bar above takes it
+            instead.
+          </p>
+        </ResponsiveOverlay>
+      </div>
+    );
+  },
+};
+
 /** T1 — an overlay with no footer note: the two actions divide the band. */
 export const JoinTheTable: Story = {
   render: () => {

package/src/components/responsive-overlay.test.tsx

@@ -191,6 +191,92 @@ describe("ResponsiveOverlay", () => {
     await waitFor(() => expect(opener).toHaveFocus());
   });
 
+  describe("returnFocus", () => {
+    /**
+     * Mirrors a pick-mode bar docking over the header: the consumer decides,
+     * from inside the same `onOpenChange(false)` handler that closes the
+     * overlay, to move focus itself — scheduled a frame out, same as a bar
+     * that focuses itself once it mounts. The overlay is still trapping
+     * focus synchronously at the moment `onOpenChange` fires (it hasn't
+     * unmounted yet), so an immediate `.focus()` call here would just be
+     * bounced back inside by that trap; that is Radix's ordinary modal
+     * behaviour, unrelated to `returnFocus`, which is what a caller works
+     * around by deferring.
+     */
+    function Harness({
+      returnFocus,
+      ...props
+    }: Partial<React.ComponentProps<typeof ResponsiveOverlay>>) {
+      const [isOpen, setIsOpen] = React.useState(false);
+      const elsewhereRef = React.useRef<HTMLButtonElement>(null);
+      return (
+        <>
+          <button type="button" onClick={() => setIsOpen(true)}>
+            Add item
+          </button>
+          <button type="button" ref={elsewhereRef}>
+            Elsewhere
+          </button>
+          <ResponsiveOverlay
+            open={isOpen}
+            onOpenChange={(next) => {
+              if (!next && returnFocus === false) {
+                requestAnimationFrame(() => elsewhereRef.current?.focus());
+              }
+              setIsOpen(next);
+            }}
+            title="Add an item"
+            closeLabel="Close"
+            returnFocus={returnFocus}
+            {...props}
+          >
+            <p>body</p>
+          </ResponsiveOverlay>
+        </>
+      );
+    }
+
+    /** Two rAF ticks — where `useFocusReturn`'s own refocus would land. */
+    async function nextFrames(count: number) {
+      for (let i = 0; i < count; i++) {
+        await new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+      }
+    }
+
+    const MODES: Array<{
+      name: string;
+      wide: boolean;
+      props: Partial<React.ComponentProps<typeof ResponsiveOverlay>>;
+    }> = [
+      { name: "drawer", wide: false, props: {} },
+      { name: "dialog", wide: true, props: {} },
+      { name: "sheet", wide: true, props: { desktop: "sheet" } },
+    ];
+
+    for (const mode of MODES) {
+      it(`${mode.name}: default (true) returns focus to the opener`, async () => {
+        setWidth(mode.wide);
+        render(<Harness {...mode.props} />);
+        const opener = screen.getByRole("button", { name: "Add item" });
+        await userEvent.click(opener);
+        await userEvent.click(screen.getByRole("button", { name: "Close" }));
+        await waitFor(() => expect(opener).toHaveFocus());
+      });
+
+      it(`${mode.name}: returnFocus={false} leaves focus where the consumer puts it`, async () => {
+        setWidth(mode.wide);
+        render(<Harness {...mode.props} returnFocus={false} />);
+        const opener = screen.getByRole("button", { name: "Add item" });
+        const elsewhere = screen.getByRole("button", { name: "Elsewhere" });
+        await userEvent.click(opener);
+        await userEvent.click(screen.getByRole("button", { name: "Close" }));
+        await nextFrames(2);
+        expect(elsewhere).toHaveFocus();
+        expect(opener).not.toHaveFocus();
+      });
+    }
+  });
+
   describe('desktop="sheet"', () => {
     /** A width-aware matchMedia, for the md / lg split. */
     function setViewport(px: number) {

package/src/components/responsive-overlay.tsx

@@ -32,8 +32,12 @@ const CONTAINER_DESCRIPTION = {
  * The opener is tracked while the overlay is CLOSED rather than captured when
  * it opens: by the time an effect could run on the opening render, the dialog
  * has already mounted and pulled focus into itself.
+ *
+ * `returnFocus={false}` disables the `requestAnimationFrame` refocus below,
+ * but tracking keeps running regardless — cheap, and it means flipping the
+ * prop back on mid-lifecycle has an opener ready immediately.
  */
-function useFocusReturn(open: boolean) {
+function useFocusReturn(open: boolean, returnFocus: boolean) {
   const openerRef = React.useRef<HTMLElement | null>(null);
   const wasOpen = React.useRef(false);
 
@@ -48,7 +52,7 @@ function useFocusReturn(open: boolean) {
       const opener = openerRef.current;
       // The overlay is still unmounting on this tick, and it takes focus with
       // it; restoring on the next frame lands after that.
-      if (opener && opener.isConnected) {
+      if (returnFocus && opener && opener.isConnected) {
         requestAnimationFrame(() => opener.focus());
       }
     }
@@ -62,7 +66,7 @@ function useFocusReturn(open: boolean) {
     }
     document.addEventListener("focusin", track);
     return () => document.removeEventListener("focusin", track);
-  }, [open]);
+  }, [open, returnFocus]);
 }
 
 export type ResponsiveOverlayProps = {
@@ -124,6 +128,22 @@ export type ResponsiveOverlayProps = {
    * keeps today's default in every mode (dialog, sheet, drawer).
    */
   initialFocusRef?: React.RefObject<HTMLElement | null>;
+  /**
+   * Whether closing the overlay returns focus to whatever had it before the
+   * overlay opened. Two things do that today: Radix's `onCloseAutoFocus` —
+   * the FocusScope's own auto-focus-on-unmount, refocusing the element that
+   * was active before the overlay trapped focus — and this component's own
+   * `useFocusReturn`, which refocuses that same element a frame later so it
+   * survives the overlay's own unmount. `true` (the default) keeps today's
+   * behaviour in every mode (dialog, sheet, drawer): the opener gets focus
+   * back.
+   *
+   * Pass `false` when closing hands focus to another surface that takes it
+   * itself — a pick-mode bar docking over the header, say. Both paths are
+   * disabled and focus stays wherever the consumer puts it (typically inside
+   * the same `onOpenChange(false)` handler that closes the overlay).
+   */
+  returnFocus?: boolean;
   /**
    * A fixed height for the phone drawer instead of sizing to its content —
    * `DrawerContent`'s `snapHeight` (the frames' ~640px table sheet). Applies
@@ -178,13 +198,14 @@ const ResponsiveOverlay = React.forwardRef<HTMLDivElement, ResponsiveOverlayProp
       className,
       bodyClassName,
       initialFocusRef,
+      returnFocus = true,
       drawerHeight,
     },
     ref
   ) => {
     const isWide = useMediaQuery(wideFrom === "lg" ? DESKTOP_MEDIA_QUERY : MD_MEDIA_QUERY);
     const container: "drawer" | "dialog" | "sheet" = isWide ? desktop : "drawer";
-    useFocusReturn(open);
+    useFocusReturn(open, returnFocus);
 
     // Radix (and vaul, underneath the drawer) call this before moving focus
     // themselves; preventing the default there is what stops the first-
@@ -198,6 +219,19 @@ const ResponsiveOverlay = React.forwardRef<HTMLDivElement, ResponsiveOverlayProp
       [initialFocusRef]
     );
 
+    // Radix's FocusScope calls this on unmount before it runs its own default
+    // action — refocusing whatever was active before the scope trapped focus,
+    // i.e. the opener. Vaul forwards it straight through to the same Radix
+    // primitive underneath the drawer, so one handler covers all three modes.
+    // Leaving it a no-op when `returnFocus` is true reproduces today's
+    // behaviour exactly: the prop was never passed before this change.
+    const handleCloseAutoFocus = React.useCallback(
+      (event: Event) => {
+        if (!returnFocus) event.preventDefault();
+      },
+      [returnFocus]
+    );
+
     // The name and the description are Radix's own: its `Title` and
     // `Description` register ids in the dialog context and `Content` points
     // `aria-labelledby` / `aria-describedby` at them. Passing our own ids
@@ -278,6 +312,7 @@ const ResponsiveOverlay = React.forwardRef<HTMLDivElement, ResponsiveOverlayProp
             hideClose
             overlayClassName="bg-scrim-overlay backdrop-blur-none"
             onOpenAutoFocus={handleOpenAutoFocus}
+            onCloseAutoFocus={handleCloseAutoFocus}
             {...describedBy}
             data-slot="responsive-overlay-sheet"
             data-modal={modal ? "true" : "false"}
@@ -310,6 +345,7 @@ const ResponsiveOverlay = React.forwardRef<HTMLDivElement, ResponsiveOverlayProp
             showCloseButton={false}
             overlayClassName="bg-scrim-overlay backdrop-blur-none"
             onOpenAutoFocus={handleOpenAutoFocus}
+            onCloseAutoFocus={handleCloseAutoFocus}
             {...describedBy}
             className={cn(
               // The dialog's own `grid gap-4 p-6` would put air between the
@@ -332,6 +368,7 @@ const ResponsiveOverlay = React.forwardRef<HTMLDivElement, ResponsiveOverlayProp
           ref={ref}
           overlayClassName="bg-scrim-overlay"
           onOpenAutoFocus={handleOpenAutoFocus}
+          onCloseAutoFocus={handleCloseAutoFocus}
           {...(drawerHeight !== undefined ? { snapHeight: drawerHeight } : {})}
           {...describedBy}
           className={cn("flex max-h-[85vh] flex-col p-0", className)}