feat(headless): hold Popover contents while it closes

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});

.changeset/headless-popover-menu.md

@@ -0,0 +1,2 @@
+---
+---

packages/headless/src/primitives/menu/README.md

@@ -139,7 +139,7 @@ Accepts all `FloatingArrow` props. `ref` and `context` are injected automaticall
 - Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
 - Only one sibling submenu can be open at a time.
 - Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
-- `Escape` closes the innermost menu first, bubbling up through the tree.
+- `Escape` closes one level: the innermost open menu, leaving its parent — a parent menu, or a `Popover` the menu is rendered inside — open. Pressing it again closes the next level up. An outside press is the opposite: it dismisses the whole stack at once.
 
 ## Important Notes
 

packages/headless/src/primitives/menu/menu-root.tsx

@@ -114,7 +114,9 @@ function MenuInner(props: MenuProps) {
  delete reference.role;
  return { ...baseRole, reference };
  }, [baseRole, isNested]);
- const dismiss = useDismiss(floatingContext, { bubbles: true });
+ // Escape must not bubble: it closes this menu and leaves whatever it sits inside — a parent menu,
+ // or a popover — open. An outside press is the opposite, and dismisses the whole stack.
+ const dismiss = useDismiss(floatingContext, { bubbles: { escapeKey: false, outsidePress: true } });
  const listNavigation = useListNavigation(floatingContext, {
  listRef: elementsRef,
  activeIndex,

packages/headless/src/primitives/menu/menu.test.tsx

@@ -682,6 +682,89 @@ describe('Menu', () => {
 
  expect(onClick).toHaveBeenCalledTimes(1);
  });
+
+ it('Escape closes only the submenu', async () => {
+ const user = userEvent.setup();
+ render(
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Email'>Email</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>,
+ );
+
+ await user.click(screen.getByText('Actions'));
+ await new Promise(r => requestAnimationFrame(r));
+ await user.keyboard('{ArrowDown}');
+ await user.keyboard('{ArrowRight}');
+ expect(screen.getByText('Share')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Share')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+ });
+ });
+
+ describe('inside a popover', () => {
+ function renderMenuInPopover() {
+ return render(
+ <Popover.Root defaultOpen>
+ <Popover.Trigger>Open popover</Popover.Trigger>
+ <Popover.Positioner>
+ <Popover.Popup>
+ <Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Cut'>Cut</Menu.Item>
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Popover.Popup>
+ </Popover.Positioner>
+ </Popover.Root>,
+ );
+ }
+
+ it('Escape closes only the menu', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ expect(screen.getByText('Actions')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+ });
+
+ it('Escape closes the popover once the menu is closed', async () => {
+ const user = userEvent.setup();
+ renderMenuInPopover();
+
+ await user.click(screen.getByText('Actions'));
+ await user.keyboard('{Escape}');
+ // The whole point of the two-step: the first Escape must spend itself on the menu and leave
+ // the popover up, or the second one is closing something that was already closed.
+ expect(screen.getByText('Actions')).toHaveAttribute('data-closed', '');
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-open', '');
+
+ await user.keyboard('{Escape}');
+
+ expect(screen.getByText('Open popover')).toHaveAttribute('data-closed', '');
+ });
  });
 
  describe('positioner', () => {

packages/headless/src/primitives/popover/README.md

@@ -63,14 +63,15 @@ const [open, setOpen] = useState(false);
 
 ### `Popover.Root`
 
-| Prop | Type | Default | Description |
-| -------------- | ------------------------- | ---------- | ---------------------------------- |
-| `open` | `boolean` | — | Controlled open state |
-| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
-| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
-| `placement` | `Placement` | `"bottom"` | Floating UI placement |
-| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
-| `modal` | `boolean` | `false` | Traps focus within the popover |
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ---------- | ----------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+| `alignOffset` | `number` | `0` | Nudge along the alignment axis (px) |
+| `modal` | `boolean` | `false` | Traps focus within the popover |
 
 ### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
 
@@ -104,6 +105,7 @@ Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popu
 - **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
 - **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
 - **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+- **Popup contents freeze while closing.** The popup outlives `open` by its exit animation, so its children are wrapped in `Freeze` (`@clerk/headless/utils`) and hold their last frame instead of re-rendering under the animation. The popup element itself keeps updating, so `data-closed` / `data-ending-style` still land. Freezing wraps the children in a `display: contents` element and detaches refs inside them until the popup reopens.
 
 ## ARIA
 

packages/headless/src/primitives/popover/popover-popup.tsx

@@ -2,17 +2,22 @@
 
 import React from 'react';
 
-import { type ComponentProps, mergeProps, useRender } from '../../utils';
+import { type ComponentProps, Freeze, mergeProps, useRender } from '../../utils';
 import { usePopoverContext } from './popover-context';
 
 export type PopoverPopupProps = ComponentProps<'div'>;
 
 export const PopoverPopup = React.forwardRef<HTMLDivElement, PopoverPopupProps>(function PopoverPopup(props, ref) {
- const { render, ...otherProps } = props;
- const { popupRef, transitionProps } = usePopoverContext();
+ const { render, children, ...otherProps } = props;
+ const { open, popupRef, transitionProps } = usePopoverContext();
 
  const defaultProps = {
  ...transitionProps,
+ // The popup outlives `open` by the length of its exit animation. Whatever closed it has
+ // usually changed the data behind it (switching account, picking an item), so the contents
+ // hold their last frame on the way out instead of swapping under the animation. The popup
+ // element itself stays live, so `data-closed` / `data-ending-style` still land.
+ children: <Freeze frozen={!open}>{children}</Freeze>,
  };
 
  return useRender({

packages/headless/src/primitives/popover/popover-root.tsx

@@ -31,6 +31,7 @@ export interface PopoverProps {
  onOpenChange?: (open: boolean) => void;
  placement?: Placement;
  sideOffset?: number;
+ alignOffset?: number;
  modal?: boolean;
  /**
  * Where focus lands when the popup opens.
@@ -47,7 +48,14 @@ export interface PopoverProps {
 
 function PopoverInner(props: PopoverProps) {
  const nodeId = useFloatingNodeId();
- const { placement: placementProp = 'bottom', sideOffset = 4, modal = false, initialFocus = 'auto', children } = props;
+ const {
+ placement: placementProp = 'bottom',
+ sideOffset = 4,
+ alignOffset = 0,
+ modal = false,
+ initialFocus = 'auto',
+ children,
+ } = props;
 
  const [open, setOpen] = useControllableState(props.open, props.defaultOpen ?? false, props.onOpenChange);
 
@@ -71,7 +79,7 @@ function PopoverInner(props: PopoverProps) {
  onOpenChange: setOpen,
  placement: placementProp,
  middleware: [
- offset(sideOffset),
+ offset({ mainAxis: sideOffset, alignmentAxis: alignOffset }),
  flip({
  crossAxis: placementProp.includes('-'),
  fallbackAxisSideDirection: 'end',

packages/headless/src/primitives/popover/popover.test.tsx

@@ -6,7 +6,10 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { axe } from '../../test-utils/axe';
 import { Popover } from './index';
 
-afterEach(() => cleanup());
+afterEach(() => {
+ cleanup();
+ vi.restoreAllMocks();
+});
 
 function renderPopover(props: Partial<React.ComponentProps<typeof Popover.Root>> = {}) {
  return render(
@@ -243,6 +246,31 @@ describe('Popover', () => {
  const positioner = document.querySelector('[data-testid="popover-positioner"]');
  expect(positioner).toHaveAttribute('data-side', 'bottom');
  });
+
+ // jsdom reports a zero-sized viewport, which leaves `shift` no room and pins the alignment
+ // axis to its padding whatever the offset asked for. Giving it a viewport is what lets the
+ // offset show up in the transform at all.
+ async function transformWithViewport(props: Partial<React.ComponentProps<typeof Popover.Root>>) {
+ vi.spyOn(document.documentElement, 'clientWidth', 'get').mockReturnValue(1024);
+ vi.spyOn(document.documentElement, 'clientHeight', 'get').mockReturnValue(768);
+
+ renderPopover({ defaultOpen: true, ...props });
+ const positioner = document.querySelector('[data-testid="popover-positioner"]');
+ await waitFor(() => expect(positioner).toHaveStyle({ position: 'absolute' }));
+ return positioner instanceof HTMLElement ? positioner.style.transform : null;
+ }
+
+ it('nudges along the alignment axis by alignOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24 });
+
+ expect(transform).toBe('translate(24px, 4px)');
+ });
+
+ it('keeps alignOffset off the side axis, which stays sideOffset', async () => {
+ const transform = await transformWithViewport({ placement: 'bottom-start', alignOffset: 24, sideOffset: 10 });
+
+ expect(transform).toBe('translate(24px, 10px)');
+ });
  });
 
  describe('focus management', () => {

packages/headless/src/utils/freeze.test.tsx

@@ -0,0 +1,119 @@
+import { act, cleanup, render, screen } from '@testing-library/react';
+import * as React from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { Freeze } from './freeze';
+
+afterEach(() => {
+ cleanup();
+});
+
+describe('Freeze', () => {
+ it('renders children while not frozen', () => {
+ render(<Freeze frozen={false}>Acme</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ });
+
+ it('holds the committed DOM when children change while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+ expect(screen.queryByText('Globex')).toBeNull();
+ });
+
+ it('keeps the held DOM visible', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('keeps the held DOM visible across further updates while frozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen>Initech</Freeze>);
+
+ expect(screen.getByText('Acme')).toBeVisible();
+ });
+
+ it('commits the pending children once unfrozen', () => {
+ const { rerender } = render(<Freeze frozen={false}>Acme</Freeze>);
+
+ rerender(<Freeze frozen>Globex</Freeze>);
+ rerender(<Freeze frozen={false}>Globex</Freeze>);
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ expect(screen.queryByText('Acme')).toBeNull();
+ });
+
+ it('holds a state update raised by the subtree itself', () => {
+ let bump = () => {};
+ function Counter() {
+ const [count, setCount] = React.useState(0);
+ bump = () => setCount(n => n + 1);
+ return <span>count: {count}</span>;
+ }
+
+ const { rerender } = render(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+ rerender(
+ <Freeze frozen>
+ <Counter />
+ </Freeze>,
+ );
+
+ act(() => bump());
+
+ expect(screen.getByText('count: 0')).toBeInTheDocument();
+
+ rerender(
+ <Freeze frozen={false}>
+ <Counter />
+ </Freeze>,
+ );
+
+ expect(screen.getByText('count: 1')).toBeInTheDocument();
+ });
+
+ it('holds a context change read from inside the frozen subtree', () => {
+ const NameContext = React.createContext('Acme');
+ function Reader() {
+ return <span>{React.useContext(NameContext)}</span>;
+ }
+
+ const { rerender } = render(
+ <NameContext.Provider value='Acme'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Acme')).toBeInTheDocument();
+
+ rerender(
+ <NameContext.Provider value='Globex'>
+ <Freeze frozen={false}>
+ <Reader />
+ </Freeze>
+ </NameContext.Provider>,
+ );
+
+ expect(screen.getByText('Globex')).toBeInTheDocument();
+ });
+});