Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
39.8 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

'use client';

/**
 * @file Popover.tsx
 * @input Uses React layout measurement, the usePopover hook and the touch
 *   presentation's surface motion
 * @output Exports Popover with conditional overflow and content-first focus above the layer runtime's viewport fit
 * @position Layer component; declarative wrapper around usePopover hook
 *
 * Under a finger, the popover grows out of its anchor and shrinks back into
 * it, as a UIKit popover does. The shared touch resolver's coarse primary
 * pointer decides it, with one touch model on every touch device. The motion
 * plays the theme's duration and easing tokens (popoverSurfaceMotion.ts). A
 * fine primary pointer keeps the layer's own entrance.
 *
 * For hover-triggered overlays, use HoverCard instead.
 *
 * `presentation` chooses the surface, with the vocabulary DropdownMenu and
 * Selector use: the anchored popover (the default), a BottomSheet, or
 * `adaptive` — a BottomSheet on a compact touch screen and the popover
 * elsewhere (the shared adaptive presentation policy), which is what iOS does
 * with a popover unless the app keeps it. The surface is chosen when the
 * popover opens; whichever is open stays until it closes. The BottomSheet
 * loads on demand (lazyPopoverBottomSheet.ts).
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Popover/Popover.test.tsx
 * - /packages/core/src/Popover/PopoverTouch.ts (its touch layer)
 * - /packages/core/src/Popover/usePopoverSurfaceMotion.ts
 * - /packages/core/src/Popover/index.ts
 * - /packages/core/src/Popover/PopoverPresentation.test.tsx
 * - /apps/storybook/stories/Popover.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/Popover/ (showcase blocks)
 */

import React, {
  useCallback,
  useEffect,
  useMemo,
  useRef,
  useState,
  useSyncExternalStore,
  type ReactElement,
  type ReactNode,
} from 'react';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import type {
  AdaptivePresentation,
  ResolvedAdaptivePresentation,
} from '../hooks/useAdaptivePresentation';
import {
  compactDefinition,
  DEFAULT_COMPACT_DEFINITION,
} from '../theme/themeAdaptations';
import {useThemeDefinition} from '../theme/useTheme';
import * as stylex from '@stylexjs/stylex';
import {devWarn} from '../utils/devWarning';
import {matchesMediaQuery, watchMediaQuery} from '../utils/coarsePointer';
import type {BaseProps} from '../BaseProps';
import {FALLBACK_CLOSE_SELECTOR, usePopoverInternal} from './usePopover';
import {usePresentationHold} from '../Layer/presentationHold';
import {usePopoverSurfaceMotion} from './PopoverTouch';
import {
  FOCUSABLE_SELECTOR,
  isDisabledWithin,
  preferTabStops,
} from '../hooks/focusableSelector';
import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
import {clampInlineSize, isIntrinsicInlineSize} from '../Layer/clampInlineSize';
import {spacingVars} from '../theme/tokens.stylex';
import {InteractiveRoleContext} from '../InteractiveRoleContext/InteractiveRoleContext';
import type {SpacingStep} from '../utils/types';
import {BottomSheetEscapeContext} from '../BottomSheet/bottomSheetEscape';
import {
  PopoverBottomSheet,
  preloadPopoverBottomSheet,
} from './lazyPopoverBottomSheet';
import {Button} from '../Button';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Popover/Popover.generated';

registerEnglishFallback(english);

// =============================================================================
// Helpers
// =============================================================================

const BUTTON_SELECTOR = 'button, [role="button"]';

const subscribeToNothing = () => () => {};
const notCompactTouch = () => false;

/**
 * The surface `presentation` resolves to now. `adaptive` takes the sheet on a
 * compact screen with a coarse pointer, compact as the active theme defines
 * it (spec:AST-012 FR9: narrower than its `md` point or shorter than 500).
 * Only an adaptive popover reads the theme and subscribes to that query, so a
 * default popover holds no viewport or document listener. The theme is the
 * nearest Theme provider's; without one, the registered root theme's, as
 * AppShell reads it (architecture:theme-application).
 */
function usePresentationSurface(
  presentation: AdaptivePresentation,
): ResolvedAdaptivePresentation {
  const isAdaptive = presentation === 'adaptive';
  const points =
    useThemeDefinition(isAdaptive)?.__adaptations?.widthBreakpoints;
  const query = useMemo(
    () =>
      (points == null ? DEFAULT_COMPACT_DEFINITION : compactDefinition(points))
        .coarsePointerQuery,
    [points],
  );
  const subscribe = useCallback(
    (onStoreChange: () => void) =>
      watchMediaQuery(window, query, onStoreChange),
    [query],
  );
  const getSnapshot = useCallback(
    () => matchesMediaQuery(window, query),
    [query],
  );
  const isCompactTouch = useSyncExternalStore(
    isAdaptive ? subscribe : subscribeToNothing,
    isAdaptive ? getSnapshot : notCompactTouch,
    notCompactTouch,
  );
  if (!isAdaptive) {
    return presentation;
  }
  return isCompactTouch ? 'bottom-sheet' : 'popover';
}
/**
 * Find the trigger button inside a container element.
 * Looks for `<button>` or `[role="button"]` — either the element itself
 * or the first matching descendant.
 */
function findTriggerButton(el: HTMLElement): HTMLElement | null {
  if (el.matches(BUTTON_SELECTOR)) {
    return el;
  }
  return el.querySelector<HTMLElement>(BUTTON_SELECTOR);
}

/** The trigger's own name: its `aria-label`, else its text. */
function readTriggerText(trigger: HTMLElement): string {
  return (
    trigger.getAttribute('aria-label')?.trim() ||
    trigger.textContent?.trim() ||
    ''
  );
}

// =============================================================================
// Types
// =============================================================================

/**
 * The surface a Popover presents its content on: anchored to the trigger, in
 * a BottomSheet, or adaptive (a BottomSheet on a compact touch screen, the
 * popover elsewhere).
 */
export type PopoverPresentation = AdaptivePresentation;

/**
 * Props passed to render-prop children for explicit trigger wiring.
 */
export interface PopoverTriggerRenderProps {
  /** Ref callback — attach to the trigger element for anchor positioning. */
  ref: (el: HTMLElement | null) => void;
  /** Toggle the popover open/closed. Pass the click event through so pointer and keyboard focus behavior can differ. */
  onClick: (event?: {detail: number}) => void;
  /** ARIA attribute: indicates the trigger opens a dialog-style popover. */
  'aria-haspopup': 'dialog';
  /** ARIA attribute: whether the popover is currently open. */
  'aria-expanded': boolean;
  /** ARIA attribute: ID of the controlled popover element. */
  'aria-controls': string;
}

export interface PopoverProps extends Pick<
  BaseProps,
  'xstyle' | 'className' | 'style'
> {
  /**
   * The trigger element. Accepts either:
   *
   * **ReactNode (automatic mode):** Must contain a `<button>` or
   * `[role="button"]` element — the popover locates it and applies
   * click/keydown handlers and ARIA attributes automatically.
   * Components that consume `InteractiveRoleContext` (e.g., Token)
   * will render as a button automatically when placed here.
   *
   * **Render function (explicit mode):** Receives `PopoverTriggerRenderProps`
   * with ref, onClick, and ARIA attributes. The consumer is responsible
   * for attaching these to their trigger element. Use this for custom
   * triggers or third-party components.
   *
   * The trigger is rendered inside an anchor wrapper used for CSS anchor
   * positioning. The wrapper is stable (no pressed-state transforms),
   * preventing popover position jitter.
   *
   * When `anchorRef` is provided, children can be omitted and the popover
   * attaches to the external ref element as a sibling.
   *
   * @example
   * ```
   * <Popover content={...}><Button label="Open" /></Popover>
   * <Popover content={...}><Token label="Filter" /></Popover>
   * <Popover content={...}>
   *   {(triggerProps) => <MyCustomTrigger {...triggerProps} />}
   * </Popover>
   * ```
   */
  children?: ReactNode | ((props: PopoverTriggerRenderProps) => ReactNode);

  /**
   * External ref to use as the popover anchor.
   * When provided (and no children), the popover attaches to this element
   * instead of wrapping children. The referenced element must be a
   * `<button>` or `[role="button"]` — the popover applies click/keydown
   * handlers and ARIA attributes to it directly.
   */
  anchorRef?: React.RefObject<HTMLElement>;

  /**
   * Content to display inside the popover.
   */
  content: ReactNode;

  /**
   * Position placement relative to the trigger.
   * Uses CSS anchor positioning via useLayer.
   * @default 'below'
   */
  placement?: LayerPlacement;

  /**
   * Alignment along the placement axis.
   * @default 'start'
   */
  alignment?: LayerAlignment;

  /**
   * Whether the popover is open (controlled mode).
   * Omit for uncontrolled behavior.
   */
  isOpen?: boolean;

  /**
   * Callback fired when the popover visibility changes.
   */
  onOpenChange?: (isOpen: boolean) => void;

  /**
   * Whether the popover is enabled.
   * When false, trigger interactions are ignored.
   * @default true
   */
  isEnabled?: boolean;

  /**
   * Width of the popover container.
   * Numbers are px, strings are CSS widths. The popover renders at this width
   * up to the viewport minus its gutters — it is never shrunk to the room
   * beside the trigger; when it does not fit there it flips or slides.
   * @default 'auto'
   */
  width?: number | string;

  /**
   * Inner padding of the popover surface, using the spacing scale.
   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
   * Matches the `padding` prop on `Card` and `Stack`.
   *
   * Pass `0` for a flush surface when the content owns its own edges — a
   * list of rows whose hover paint reaches the edge, or a header row with a
   * bottom rule — and pad the content itself.
   *
   * The padding sits on the painted surface (the `popover` theme target), so
   * a theme's `padding` on that target replaces it rather than nesting.
   * @default 3
   */
  padding?: SpacingStep;

  /**
   * Accessible label for the popover dialog.
   * Recommended for accessibility when `role` is `'dialog'`. A sheet
   * (`presentation`) without one is named by the trigger's text, so it is
   * never an unnamed dialog.
   */
  label?: string;

  /**
   * ARIA role stamped on the popover content wrapper.
   *
   * Use `'dialog'` for dialog-style popovers. Use `'none'` when the popup
   * content owns its own role, such as a child `role="menu"` or
   * `role="listbox"`.
   *
   * @default 'dialog'
   */
  role?: 'dialog' | 'none';

  /**
   * Whether a dialog-style popover is modal (`aria-modal`). Only applies when
   * `role` is `'dialog'`.
   *
   * @default true
   */
  isModal?: boolean;

  /**
   * Whether to include a hidden close button for accessibility.
   * The button appears when keyboard users tab past the last element.
   * @default true
   */
  hasCloseButton?: boolean;

  /**
   * Label for the hidden close button.
   * @default "Close popover"
   */
  closeButtonLabel?: string;

  /**
   * Whether to move focus into the popover when it opens. Focus enters the
   * first genuine caller content control; dialogs with none fall back to the
   * labeled surface. The generated fallback close control is excluded from
   * initial focus and reveals only when reached through keyboard navigation.
   * Set to `false` for input-owned focus, inline showcases, or documentation
   * previews.
   * @default true
   */
  hasAutoFocus?: boolean;

  /**
   * Whether clicking outside dismisses the popover.
   * Set to `false` for surfaces that should stay open until explicitly
   * dismissed, like onboarding coachmarks or multi-step flows.
   * @default true
   */
  hasLightDismiss?: boolean;

  /**
   * Whether pressing Escape dismisses the popover.
   *
   * Only takes full effect together with `hasLightDismiss={false}`: with
   * light dismiss on, the browser's native light dismiss also closes on
   * Escape. Set both to `false` for explicit-dismiss-only surfaces.
   * @default true
   */
  hasEscapeDismiss?: boolean;

  /**
   * The surface that holds the content. `'popover'` anchors it to the
   * trigger. `'bottom-sheet'` presents it in a modal BottomSheet, labeled
   * by `label`. `'adaptive'` presents the BottomSheet on a compact touch
   * screen (a coarse pointer on a screen the theme counts as compact:
   * narrower than its `md` width point or shorter than 500px, so a phone in
   * either orientation) and the anchored popover elsewhere, which is what iOS
   * does with a popover by default.
   *
   * In a sheet, `placement`, `alignment`, `width`, `role`, `isModal` and
   * `hasAutoFocus` do not apply (the sheet is a modal dialog with its own
   * focus handling); `xstyle`, `className` and `style` style the sheet's
   * panel, as they style the anchored surface; `padding` insets the
   * sheet's content. The sheet always light-dismisses (a tap outside it or a
   * swipe down closes it, whatever `hasLightDismiss` says), Escape follows
   * `hasEscapeDismiss`, and the fallback close stays hidden as on the
   * anchored surface. The surface is
   * chosen when the popover opens and kept until it closes.
   * @default 'popover'
   */
  presentation?: PopoverPresentation;

  /**
   * Test ID for the popover container.
   */
  'data-testid'?: string;
}

// =============================================================================
// Styles
// =============================================================================

const styles = stylex.create({
  // Stable anchor wrapper — uses inline-flex to generate a box for CSS
  // anchor positioning without affecting layout. The trigger element (e.g.
  // Button) renders inside this wrapper. Because the wrapper itself is
  // the anchor, pressed-state transforms on the child (e.g. :active scale)
  // don't shift the anchor position and cause popover jitter.
  anchorWrapper: {
    display: 'inline-flex',
  },
  // The sheet's fallback close control: hidden until it is reached, as the
  // anchored surface's is, on the Button itself rather than a wrapper
  // (architecture:component-style-authoring INV7). Taken out of flow and
  // clipped at rest, it rejoins the flow when focused, set below the content
  // with room for its focus ring.
  sheetFallbackClose: {
    position: {
      default: 'absolute',
      ':focus': 'relative',
    },
    clipPath: {
      default: 'inset(50%)',
      ':focus': 'none',
    },
    marginBlockStart: {
      default: 0,
      ':focus': spacingVars['--spacing-3'],
    },
    // Block-level when revealed, so it starts its own line below inline
    // content rather than sitting on its last line.
    display: {
      default: null,
      ':focus': 'flex',
    },
    width: {
      default: null,
      ':focus': 'fit-content',
    },
  },
  // The painted surface is capped to the viewport with the layer runtime's
  // one definition (spec:AST-059 FR2, FR3): the layer box above it caps the
  // block axis itself and leaves the inline axis to the surface, so a flip is
  // still chosen when the surface does not fit beside the trigger.
  surfaceViewportFit: {
    boxSizing: 'border-box',
    maxInlineSize: stylex.firstThatWorks(
      `calc(${layerViewportInset.maxInlineSize})`,
      `calc(${layerViewportInset.maxInlineSizeFallback})`,
    ),
    maxBlockSize: stylex.firstThatWorks(
      `calc(${layerViewportInset.maxBlockSize})`,
      `calc(${layerViewportInset.maxBlockSizeFallback})`,
    ),
    // A scroll container from the commit in which the software keyboard caps
    // the layer, a frame before the overflow measure sees the shorter box.
    // Otherwise `visible`. The type names the two values the property takes.
    // SYNC: LAYER_KEYBOARD_OVERFLOW_PROPERTY (Layer/useLayerKeyboardClearance.ts).
    overflow: 'var(--_layer-keyboard-overflow, visible)' as 'auto' | 'visible',
  },
  surfaceScrollable: {
    overflow: 'auto',
    overscrollBehavior: 'contain',
  },
  // An explicit width renders at its size up to the viewport cap, never
  // shrunk to the room beside the trigger (spec:AST-059 FR2). Keywords cannot
  // sit inside min(); the surface cap above bounds them.
  customWidth: (width: string) => ({
    width,
  }),
  // Without a width the surface prefers the trigger's minimum width, clamped
  // by the runtime's cap because a CSS minimum beats a maximum (FR7).
  matchTrigger: {
    minWidth: stylex.firstThatWorks(
      `min(anchor-size(width), ${layerViewportInset.maxInlineSize})`,
      `min(anchor-size(width), ${layerViewportInset.maxInlineSizeFallback})`,
      'anchor-size(width)',
    ),
  },
});

/**
 * The window that holds `element`: the page's own, or a second document's (a
 * same-origin iframe, a Document Picture-in-Picture window) when the Popover
 * renders there.
 */
function windowOf(element: Element | null): Window & typeof globalThis {
  return element?.ownerDocument.defaultView ?? window;
}

// =============================================================================
// Component
// =============================================================================

/**
 * A click-triggered popover for displaying interactive content anchored to a trigger.
 *
 * Implements the button + dialog ARIA pattern. The trigger must contain a
 * `<button>` or `[role="button"]` element — the popover finds it and applies
 * click/keydown handlers and ARIA attributes automatically.
 *
 * Uses an inline-flex wrapper as the CSS anchor for stable positioning
 * (immune to pressed-state transforms like `:active { scale(0.98) }`).
 *
 * Focus is trapped inside the popover when open.
 * Supports light dismiss by default (click outside or Escape to close).
 *
 * For hover-triggered overlays, use {@link HoverCard} instead.
 *
 * @example
 * ```
 * <Popover label="Settings" content={<SettingsPanel />} placement="below">
 *   <Button label="Settings" />
 * </Popover>
 * <Popover
 *   isOpen={isOpen}
 *   onOpenChange={setIsOpen}
 *   label="Filter"
 *   content={<FilterForm />}>
 *   <Button label="Filter" />
 * </Popover>
 * <Popover
 *   anchorRef={myButtonRef}
 *   label="Actions"
 *   content={<ActionMenu />}
 *   placement="below"
 * />
 * ```
 */
export function Popover({
  children,
  anchorRef,
  content,
  placement = 'below',
  alignment = 'start',
  isOpen,
  onOpenChange,
  isEnabled = true,
  width,
  padding = 3,
  label,
  role = 'dialog',
  isModal,
  hasCloseButton,
  closeButtonLabel,
  hasAutoFocus,
  hasLightDismiss = true,
  hasEscapeDismiss = true,
  presentation = 'popover',
  xstyle,
  className,
  style,
  'data-testid': testId,
}: PopoverProps): ReactElement {
  const t = useComponentTranslator();
  const wrapperRef = useRef<HTMLDivElement>(null);
  const measurementFrameRef = useRef<{id: number; view: Window} | null>(null);
  const [hasOverflow, setHasOverflow] = useState(false);
  const isControlled = isOpen !== undefined;
  // The element the popover is anchored to, whichever way it was attached:
  // the touch presentation grows the popover out of it.
  const anchorElementRef = useRef<HTMLElement | null>(null);
  const surfaceMotion = usePopoverSurfaceMotion();
  // Runs as the popover opens, before it paints; set once `usePopover` has
  // returned the surface it presents.
  const presentSurfaceRef = useRef<() => void>(() => {});
  // The bottom-sheet presentation: the surface it resolves to now, and
  // whether the sheet is the surface that is open.
  const resolvedPresentation = usePresentationSurface(presentation);
  const [isSheetOpenState, setIsSheetOpenState] = useState(false);

  const handlePopoverShow = useCallback(() => {
    presentSurfaceRef.current();
    onOpenChange?.(true);
  }, [onOpenChange]);

  const handlePopoverHide = useCallback(() => {
    onOpenChange?.(false);
  }, [onOpenChange]);

  const popover = usePopoverInternal({
    dialogLabel: label,
    role,
    isModal,
    hasLightDismiss,
    hasEscapeDismiss,
    hasCloseButton,
    closeButtonLabel,
    hasAutoFocus,
    // The surface is the box that paints background, radius and elevation, so
    // it is the element the `popover` theme target has to sit on — a target on
    // the content div inside it styles a box that paints nothing.
    surfaceTarget: 'popover',
    // Surface padding is a usePopover option so it lands on that same box,
    // where a theme's `padding` replaces it instead of nesting inside it.
    padding,
    xstyle: [
      styles.surfaceViewportFit,
      hasOverflow && styles.surfaceScrollable,
      // The entrance runs on the surface: an anchored layer lays out again on
      // each frame its own style animates.
      layerAnimations[placement],
      xstyle,
    ],
    className,
    style,
    onShow: handlePopoverShow,
    onHide: handlePopoverHide,
    onCloseStart: surfaceMotion.closeStart,
  });

  const {contentRef: surfaceRef} = popover;
  // The layer's show handler calls this as the popover opens. It reads the
  // surface and the anchor when it runs, so a render-time store is safe.
  presentSurfaceRef.current = () => {
    surfaceMotion.present(
      surfaceRef.current?.closest<HTMLElement>('[popover]') ?? null,
      anchorElementRef.current,
      surfaceRef.current,
    );
  };
  // A controlled popover opens on the surface its presentation resolves to
  // as it opens, and keeps that surface until it closes: a phone rotated past
  // the compact width while the sheet is open keeps its sheet.
  // The layer runtime's presentation hold (Layer/presentationHold), taken
  // during render as the controlled `isOpen` turns on, so the open surface is
  // known in the same render that opens it, and let go as it turns off.
  const surfaceHold = usePresentationHold<'popover' | 'bottom-sheet'>({
    isOpen: isControlled && isOpen === true,
    presentation: popover.isOpen ? 'popover' : resolvedPresentation,
  });
  if (isControlled && isOpen !== true && surfaceHold.isHeld) {
    surfaceHold.release();
  }
  const controlledSurface = surfaceHold.presentation;
  const isSheetOpen = isControlled
    ? isOpen === true && controlledSurface === 'bottom-sheet'
    : isSheetOpenState;
  // One presentation at a time (architecture:component-style-authoring
  // INV7): the sheet is mounted, in place of the anchored layer, while it is
  // the surface an opening would choose (a compact touch screen, or
  // `'bottom-sheet'`) and the anchored popover is not the open one, while it
  // is open, and through its exit after it was. Closed, it holds the content
  // as the anchored layer does, so state kept in the content (a ticked box,
  // typed text) survives a reopen. After a sheet closes on a screen that has
  // stopped being compact, it stays through its exit, so the exit plays out
  // and its dialog hands focus back to the trigger (component:Popover AR4),
  // and gives way to the anchored layer once its dialog has closed.
  // The sheet's presentation hold: from the render that opens it until its
  // dialog has closed.
  const sheetHold = usePresentationHold({
    isOpen: isSheetOpen,
    presentation: true,
  });
  const hasSheetBeenOpen = sheetHold.isHeld;
  const releaseSheet = sheetHold.release;
  // The trigger's text, which names a sheet that has no `label` (DEC-8).
  const [triggerText, setTriggerText] = useState('');
  const isSheetMounted =
    isSheetOpen ||
    hasSheetBeenOpen ||
    (resolvedPresentation === 'bottom-sheet' && !popover.isOpen);
  const sheetPanelRef = useRef<HTMLDivElement | null>(null);
  const [isSheetPanelAttached, setSheetPanelAttached] = useState(false);
  const attachSheetPanel = useCallback((panel: HTMLDivElement | null) => {
    sheetPanelRef.current = panel;
    setSheetPanelAttached(panel != null);
  }, []);
  // Focus enters the sheet at each opening, as in the anchored popover (FR2).
  // A caller's `[data-autofocus]` wins. Else the first enabled tab stop in the
  // content takes focus: never the injected fallback close or BottomSheet's
  // own scroll area. Else the scroll area does: it is the sheet's labelled
  // surface and shows the keyboard focus ring. This runs a frame after
  // BottomSheet presents the dialog.
  useEffect(() => {
    if (!isSheetOpen || !isSheetPanelAttached) {
      return;
    }
    const frame = requestAnimationFrame(() => {
      const sheetPanel = sheetPanelRef.current;
      if (sheetPanel == null) {
        return;
      }
      const dialog = sheetPanel.closest('dialog');
      if (dialog == null || !dialog.open) {
        return;
      }
      const active = sheetPanel.ownerDocument.activeElement;
      if (
        active != null &&
        active !== sheetPanel &&
        active !== dialog &&
        sheetPanel.contains(active)
      ) {
        return;
      }
      const target =
        sheetPanel.querySelector<HTMLElement>('[data-autofocus]') ??
        preferTabStops(
          Array.from(
            sheetPanel.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
          ).filter(
            element =>
              // BottomSheet's scroll area is the panel's own child; content
              // sits inside it.
              element.parentElement !== sheetPanel &&
              element.closest(FALLBACK_CLOSE_SELECTOR) == null &&
              !isDisabledWithin(element, sheetPanel),
          ),
        )[0];
      if (target != null) {
        target.focus({preventScroll: true});
        return;
      }
      // The scroll area is a tab stop only while its content overflows; it is
      // focusable from script either way.
      const surface = Array.from(sheetPanel.children).find(
        (child): child is HTMLElement =>
          child instanceof HTMLElement &&
          child.getAttribute('role') === 'group',
      );
      if (surface == null) {
        return;
      }
      if (!surface.hasAttribute('tabindex')) {
        surface.tabIndex = -1;
      }
      surface.focus({preventScroll: true});
    });
    return () => cancelAnimationFrame(frame);
  }, [isSheetOpen, isSheetPanelAttached]);
  useEffect(() => {
    if (isSheetOpen || !hasSheetBeenOpen) {
      return;
    }
    const dialog = sheetPanelRef.current?.closest('dialog');
    if (dialog == null || !dialog.open) {
      // The sheet's <dialog> is already closed, so its close event has fired
      // and its exit is over: unmount it.
      releaseSheet();
      return;
    }
    dialog.addEventListener('close', releaseSheet);
    return () => dialog.removeEventListener('close', releaseSheet);
  }, [hasSheetBeenOpen, isSheetOpen, releaseSheet]);
  // An open on a compact touch screen shows the sheet at once: its module
  // loads as soon as the sheet can be the surface, with nothing rendered.
  useEffect(() => {
    if (resolvedPresentation === 'bottom-sheet') {
      preloadPopoverBottomSheet();
    }
  }, [resolvedPresentation]);
  const isAnySurfaceOpen = popover.isOpen || isSheetOpen;
  const sheetId = `${popover.id}-sheet`;

  const setSheetOpen = useCallback(
    (next: boolean) => {
      if (!isControlled) {
        setIsSheetOpenState(next);
      }
      onOpenChange?.(next);
    },
    [isControlled, onOpenChange],
  );

  const measureOverflow = useCallback(() => {
    const surface = popover.contentRef.current;
    if (!surface) {
      return;
    }
    const nextHasOverflow =
      surface.scrollHeight > surface.clientHeight + 1 ||
      surface.scrollWidth > surface.clientWidth + 1;
    // eslint-disable-next-line @eslint-react/set-state-in-effect -- DOM overflow measurement controls whether this surface becomes a scroll container
    setHasOverflow(current =>
      current === nextHasOverflow ? current : nextHasOverflow,
    );
  }, [popover.contentRef]);

  const scheduleOverflowMeasurement = useCallback(() => {
    if (measurementFrameRef.current != null) {
      return;
    }
    // The surface's own window paints it, so its frame runs the measurement.
    const view = windowOf(popover.contentRef.current);
    measurementFrameRef.current = {
      view,
      id: view.requestAnimationFrame(() => {
        measurementFrameRef.current = null;
        measureOverflow();
      }),
    };
  }, [measureOverflow, popover.contentRef]);

  // Syncs the overflow measurement with the open surface. It measures, then
  // observes resize and DOM changes until the surface closes.
  useIsomorphicLayoutEffect(() => {
    if (!popover.isOpen) {
      return;
    }
    const surface = popover.contentRef.current;
    if (!surface) {
      return;
    }
    // Observe from the surface's own window. A Popover rendered into a second
    // document resizes with that document's window, and a ResizeObserver the
    // page created checks a box in a Picture-in-Picture window only while the
    // page itself renders frames.
    const view = windowOf(surface);
    measureOverflow();
    const resizeObserver =
      typeof view.ResizeObserver === 'undefined'
        ? null
        : new view.ResizeObserver(scheduleOverflowMeasurement);
    const mutationObserver =
      typeof MutationObserver === 'undefined'
        ? null
        : new MutationObserver(scheduleOverflowMeasurement);
    resizeObserver?.observe(surface);
    mutationObserver?.observe(surface, {
      childList: true,
      characterData: true,
      subtree: true,
    });
    surface.addEventListener('load', scheduleOverflowMeasurement, true);
    view.addEventListener('resize', scheduleOverflowMeasurement);
    view.visualViewport?.addEventListener(
      'resize',
      scheduleOverflowMeasurement,
    );
    return () => {
      resizeObserver?.disconnect();
      mutationObserver?.disconnect();
      surface.removeEventListener('load', scheduleOverflowMeasurement, true);
      view.removeEventListener('resize', scheduleOverflowMeasurement);
      view.visualViewport?.removeEventListener(
        'resize',
        scheduleOverflowMeasurement,
      );
      const frame = measurementFrameRef.current;
      if (frame != null) {
        frame.view.cancelAnimationFrame(frame.id);
        measurementFrameRef.current = null;
      }
    };
  }, [measureOverflow, popover.isOpen, scheduleOverflowMeasurement]);

  // Measures overflow again after the content changes while the surface is
  // open.
  useIsomorphicLayoutEffect(() => {
    if (!popover.isOpen) {
      return;
    }
    scheduleOverflowMeasurement();
  }, [content, popover.isOpen, scheduleOverflowMeasurement]);

  // Shared handler for click events on the trigger button.
  // A render-prop trigger is the caller's element, reached through the ref
  // the render prop hands it; its text names a sheet that has no `label`.
  const renderTriggerRef = useRef<HTMLElement | null>(null);
  const setRenderTrigger = useCallback(
    (element: HTMLElement | null) => {
      renderTriggerRef.current = element;
      anchorElementRef.current = element;
      popover.triggerRef(element);
    },
    [popover],
  );
  const handleTriggerClick = useCallback(
    (event?: {currentTarget: EventTarget | null}) => {
      // An aria-disabled trigger stays focusable but opens nothing
      // (spec:AST-085 FR2), even for a click dispatched straight on it.
      const trigger = event?.currentTarget;
      if (
        !isEnabled ||
        (trigger instanceof Element &&
          trigger.getAttribute('aria-disabled') === 'true')
      ) {
        return;
      }
      // Opening chooses the surface; an open popover closes as a popover.
      if (
        isSheetOpen ||
        (!popover.isOpen && resolvedPresentation === 'bottom-sheet')
      ) {
        const opener =
          trigger instanceof HTMLElement ? trigger : renderTriggerRef.current;
        if (opener != null) {
          setTriggerText(readTriggerText(opener));
        }
        setSheetOpen(!isSheetOpen);
        return;
      }
      popover.toggle();
    },
    [isEnabled, isSheetOpen, popover, resolvedPresentation, setSheetOpen],
  );

  // Shared handler for keydown events on role="button" elements.
  // Native <button> synthesizes click on Enter/Space, but role="button"
  // does not — we need to handle it explicitly.
  const handleTriggerKeyDown = useCallback(
    (e: KeyboardEvent) => {
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault();
        handleTriggerClick(e);
      }
    },
    [handleTriggerClick],
  );

  /**
   * Attach click/keydown handlers and ARIA attributes to a trigger button.
   * Used by both sibling mode and children mode.
   */
  const attachTrigger = useCallback(
    (button: HTMLElement) => {
      // ARIA attributes
      // The sheet's surface is a dialog whatever the popover's role.
      button.setAttribute(
        'aria-haspopup',
        isSheetMounted ? 'dialog' : popover.triggerProps['aria-haspopup'],
      );
      button.setAttribute('aria-expanded', String(isAnySurfaceOpen));
      button.setAttribute(
        'aria-controls',
        isSheetMounted ? sheetId : popover.triggerProps['aria-controls'],
      );
      // The trigger's text is in the DOM the caller rendered, read as the
      // trigger attaches; it names a sheet that has no `label` (DEC-8).
      // eslint-disable-next-line @eslint-react/set-state-in-effect -- reads the caller-rendered trigger's text, which only the DOM holds
      setTriggerText(readTriggerText(button));

      // Event handlers
      button.addEventListener('click', handleTriggerClick);
      // Only add keydown for role="button" — native <button> already
      // synthesizes click events for Enter/Space.
      const needsKeyDown =
        button.tagName !== 'BUTTON' && button.getAttribute('role') === 'button';
      if (needsKeyDown) {
        button.addEventListener('keydown', handleTriggerKeyDown);
      }

      return () => {
        button.removeAttribute('aria-haspopup');
        button.removeAttribute('aria-expanded');
        button.removeAttribute('aria-controls');
        button.removeEventListener('click', handleTriggerClick);
        if (needsKeyDown) {
          button.removeEventListener('keydown', handleTriggerKeyDown);
        }
      };
    },
    [
      popover,
      isAnySurfaceOpen,
      isSheetMounted,
      sheetId,
      handleTriggerClick,
      handleTriggerKeyDown,
    ],
  );

  // Sibling mode: attach to external anchorRef
  useIsomorphicLayoutEffect(() => {
    if (!anchorRef) {
      return;
    }

    const el = anchorRef.current;
    if (!el) {
      return;
    }

    const button = findTriggerButton(el);
    if (!button) {
      devWarn(
        'Popover',
        'anchorRef must reference a <button> or [role="button"] element. ' +
          'The popover trigger implements the button + dialog ARIA pattern.',
      );
    }
    if (!button) {
      return;
    }

    // Set up anchor positioning on the anchorRef element itself
    anchorElementRef.current = el;
    popover.triggerRef(el);

    // Attach handlers + ARIA to the button
    const detach = attachTrigger(button);

    return () => {
      anchorElementRef.current = null;
      popover.triggerRef(null);
      detach();
    };
  }, [anchorRef, popover, attachTrigger]);

  // Children mode: use wrapper as CSS anchor, find button inside for
  // ARIA + event handlers.
  useIsomorphicLayoutEffect(() => {
    if (anchorRef) {
      return;
    } // Skip if using anchorRef mode
    if (typeof children === 'function') {
      return;
    } // Skip if using render prop mode

    const wrapper = wrapperRef.current;
    if (!wrapper) {
      return;
    }

    // Use the wrapper as the CSS anchor — it doesn't receive pressed-state
    // transforms, so the anchor position stays stable.
    anchorElementRef.current = wrapper;
    popover.triggerRef(wrapper);

    // Find the button inside the wrapper
    const button = findTriggerButton(wrapper);
    if (!button) {
      devWarn(
        'Popover',
        'children must contain a <button> or [role="button"] element. ' +
          'The popover trigger implements the button + dialog ARIA pattern.',
      );
    }
    if (!button) {
      return;
    }

    const detach = attachTrigger(button);

    return () => {
      anchorElementRef.current = null;
      popover.triggerRef(null);
      detach();
    };
  }, [anchorRef, popover, attachTrigger]);

  // Sync controlled state: show or hide the anchored popover, the one surface
  // with an imperative API, to follow the latch. The sheet follows the latch
  // in render (`isSheetOpen`).
  useIsomorphicLayoutEffect(() => {
    if (!isControlled) {
      return;
    }
    if (!isOpen) {
      if (popover.isOpen) {
        popover.hide();
      }
      return;
    }
    if (controlledSurface === 'popover' && !popover.isOpen) {
      popover.show();
    }
  }, [isOpen, isControlled, popover, controlledSurface]);

  // Popover's one sizing fact: an explicit width wins over trigger matching.
  // Fit against the viewport is the layer runtime's (spec:AST-059).
  const popoverSizeXstyle = !width
    ? styles.matchTrigger
    : styles.customWidth(
        typeof width === 'string' && isIntrinsicInlineSize(width)
          ? width.trim()
          : clampInlineSize(width, layerViewportInset.maxInlineSizeFallback),
      );

  // One instance of the content at a time: the sheet holds it while it is
  // mounted, the anchored layer otherwise.
  const isContentInSheet = isSheetMounted;
  const anchoredContent = (
    <div data-testid={isContentInSheet ? undefined : testId}>
      {isContentInSheet ? null : content}
    </div>
  );
  // The sheet renders while it is the open surface and through its exit. It
  // always light-dismisses: a tap outside it or a swipe down closes it,
  // whatever `hasLightDismiss` says, so a finger always has a way out
  // (DEC-8). Escape follows `hasEscapeDismiss`, and the fallback close stays
  // hidden until it is reached, as on the anchored surface.
  const sheet = isSheetMounted ? (
    <BottomSheetEscapeContext value={hasEscapeDismiss}>
      <PopoverBottomSheet
        ref={attachSheetPanel}
        id={sheetId}
        isOpen={isSheetOpen}
        onOpenChange={setSheetOpen}
        label={label ?? triggerText}
        height="tall"
        padding={padding}
        xstyle={xstyle}
        className={className}
        style={style}
        data-testid={isContentInSheet ? testId : undefined}>
        {isContentInSheet ? content : null}
        {isContentInSheet && hasCloseButton !== false ? (
          <Button
            data-astryx-popover-fallback-close=""
            variant="secondary"
            label={closeButtonLabel ?? t('@astryx.popover.close')}
            onClick={() => setSheetOpen(false)}
            xstyle={styles.sheetFallbackClose}
          />
        ) : null}
      </PopoverBottomSheet>
    </BottomSheetEscapeContext>
  ) : null;

  // The anchored layer, unless the sheet is the presentation that is mounted.
  const anchoredLayer = isSheetMounted
    ? null
    : popover.render(anchoredContent, {
        placement,
        alignment,
        offset: spacingVars['--spacing-1'],
        xstyle: popoverSizeXstyle,
      });

  // Sibling mode: render only the popover (no wrapper needed)
  if (anchorRef && children == null) {
    return (
      <>
        {anchoredLayer}
        {sheet}
      </>
    );
  }

  // Render prop mode: children is a function — pass trigger props directly
  const isRenderProp = typeof children === 'function';

  if (isRenderProp) {
    const triggerProps: PopoverTriggerRenderProps = {
      ref: setRenderTrigger,
      // The caller renders and owns this trigger element.
      onClick: () => handleTriggerClick(),
      'aria-haspopup': 'dialog',
      'aria-expanded': isAnySurfaceOpen,
      'aria-controls': isSheetMounted ? sheetId : popover.id,
    };

    return (
      <>
        {children(triggerProps)}
        {anchoredLayer}
        {sheet}
      </>
    );
  }

  // Automatic mode: wrap children in context + anchor wrapper
  return (
    <>
      <InteractiveRoleContext value="button">
        <div ref={wrapperRef} {...stylex.props(styles.anchorWrapper)}>
          {children}
        </div>
      </InteractiveRoleContext>
      {anchoredLayer}
      {sheet}
    </>
  );
}

Popover.displayName = 'Popover';