Skip to content

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

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

'use client';

/**
 * @file DropdownMenu.tsx
 * @input Uses React, StyleX, usePopover, MenuBottomSheet (lazy), Button, List,
 *   useListFocus, the shared viewport-safe menu-width resolver, and the
 *   layer runtime's entrance hold
 * @output Exports DropdownMenu with caller-selected popover or bottom-sheet
 *   presentation
 * @position Core implementation; consumed by index.ts
 *
 * Supports two modes with a single keyboard/focus path:
 * - **Data-driven**: pass `items` array (converted to components internally)
 * - **Compound-component**: pass JSX children directly
 *
 * Both modes use useListFocus for DOM-based keyboard navigation.
 *
 * The trigger is the design system's Button (`button`) or any control the
 * caller renders (`renderTrigger`).
 *
 * A sub-menu drills in on a phone through the view stack useMenuDrillIn
 * keeps; the root shows the drilled view in place of its rows.
 *
 * Initial focus on open follows the input modality: a keyboard open
 * (Enter / Space / ArrowDown on the trigger) focuses the first enabled item
 * (APG menu-button); a pointer open focuses the menu container itself so no
 * item reads as pre-selected, and the first ArrowDown then moves to item 1.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/DropdownMenu/DropdownMenu.doc.mjs
 * - /packages/core/src/DropdownMenu/DropdownMenu.test.tsx
 * - /packages/core/src/DropdownMenu/index.ts
 * - /apps/storybook/stories/DropdownMenu.stories.tsx
 * - /packages/cli/assets/templates/blocks/components/DropdownMenu/ (showcase blocks)
 */

import React, {
  useCallback,
  useEffect,
  useId,
  useMemo,
  useRef,
  useState,
  type ReactNode,
} from 'react';
import {readAccessibleName} from '../utils/accessibleName';
import * as stylex from '@stylexjs/stylex';
import {usePopover} from '../Popover/usePopover';
import {holdEntranceInput} from '../Layer/holdEntranceInput';
import {
  claimPress,
  currentGesture,
  isPressInFlight,
} from '../Layer/gestureCounter';
import {Button, type ButtonProps} from '../Button';
import {Heading} from '../Heading';
import {Icon} from '../Icon';

import {renderDropdownItems} from './renderDropdownItems';
import type {DropdownMenuItemProps} from './DropdownMenuItem';
import {
  MENU_ITEM_ROLES,
  MENU_ITEM_SELECTOR,
  MENU_ROW_SELECTOR,
  MENU_BOUNDARY_SELECTOR,
  activateMenuItem,
} from './menuItemRoles';
import {
  DropdownMenuContext,
  DropdownMenuRootOpenContext,
  DropdownMenuSurfaceContext,
  type DropdownMenuContextValue,
  type DropdownMenuSurfaceHost,
  type DropdownMenuSurfaceValue,
} from './DropdownMenuContext';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
import {useMergedRefs} from '../hooks/useMergedRefs';
import {useInternalListFocus} from '../hooks/useListFocus';
import {useDropdownMenuPress} from '../hooks/useMenuPress';
import type {MenuPressPointerType} from '../hooks/menuPressGesture';
import {useTypeahead} from '../hooks/useTypeahead';
import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility';
import {focusForLastInput, returnFocusForLastInput} from '../utils/focusReturn';
import {PressGroupContext} from '../hooks/pressGroupContext';
import {useMenuOverflow} from './useMenuOverflow';
import {moveRegionsTab} from './menuRegionStops';
import {useDevWarning} from '../hooks/useDevWarning';
import {useMenuDrillIn} from './useMenuDrillIn';
import {resolveMenuWidth} from './menuWidth';
import {menuTouchActionStyles} from './menuTouchAction.stylex';
import {layerViewportInset} from '../Layer/layerViewportInset.stylex';
import {
  useAdaptivePresentation,
  type AdaptivePresentation,
} from '../hooks/useAdaptivePresentation';
// Loaded on demand: only the bottom-sheet presentation renders the sheet.
import {
  MenuBottomSheet,
  MenuBottomSheetActionList,
  preloadMenuBottomSheetActionList,
} from './lazyMenuBottomSheet';
import {menuBottomSheetStyles} from './menuBottomSheet.stylex';
import {layerAnimations} from '../Layer/layerAnimations.stylex';
import type {LayerAlignment, LayerPlacement} from '../Layer/useLayer';
import {
  spacingVars,
  colorVars,
  radiusVars,
  durationVars,
  easeVars,
} from '../theme/tokens.stylex';
import {isRenderable, mergeProps, rtlStyles} from '../utils';
import type {BaseProps} from '../BaseProps';
import {themeProps} from '../utils/themeProps';
import {
  getInteractionModality,
  useInteractionModalityTracking,
} from '../utils/interactionModality';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/DropdownMenu/DropdownMenu.generated';

registerEnglishFallback(english);

// The menu's own lower cap on the placement axis; the viewport cap underneath
// it is the layer runtime's (spec:AST-059 FR3).
const MENU_BLOCK_CAP = '300px';
const MENU_MAX_BLOCK_SIZE = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBlockSize})`;
const MENU_MAX_BLOCK_SIZE_FALLBACK = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBlockSizeFallback})`;
const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;

// A sub-menu's drilled-in view with a header or footer renders in the surface
// host that follows the menu (marked `data-astryx-submenu-host`), as the frame
// marked `data-astryx-submenu-regions="view"` (hidden while a deeper view
// shows). While one shows, the menu and its header and footer step aside. The
// rule reads that from the DOM, so no state mirrors which view shows; it names
// the host by its marker rather than a universal selector.
const STEPS_ASIDE_FOR_VIEW =
  ':has(~ [data-astryx-submenu-host] > [data-astryx-submenu-regions="view"]:not([hidden]))';

const styles = stylex.create({
  triggerOpen: {
    backgroundImage: MENU_TRIGGER_OPEN_BACKGROUND,
  },
  // A finger held on the trigger opens the menu; the browser's own held-press
  // affordances — the link preview callout, text selection — must not compete
  // with it.
  triggerPressable: {
    WebkitTouchCallout: 'none',
    userSelect: 'none',
  },
  dropdown: {
    boxSizing: 'border-box',
    display: {
      default: 'flex',
      // A sub-menu's drilled-in view with a header or footer shows in its
      // place (see `stepsAsideForView`).
      [STEPS_ASIDE_FOR_VIEW]: 'none',
    },
    flexDirection: 'column',
    gap: spacingVars['--spacing-0-5'],
    // Pointer opens focus this container so subsequent arrow keys and Escape
    // stay owned by the menu. It is an internal focus target, not a control,
    // so suppress the browser ring; keyboard focus moves to an item instead.
    outline: 'none',
    // Menu rows never offer the browser's held-press link preview or text
    // selection: a held finger is driving the highlight.
    WebkitTouchCallout: 'none',
    userSelect: 'none',
    maxInlineSize: stylex.firstThatWorks(
      `calc(${layerViewportInset.maxInlineSize})`,
      `calc(${layerViewportInset.maxInlineSizeFallback})`,
    ),
    maxHeight: stylex.firstThatWorks(
      MENU_MAX_BLOCK_SIZE,
      MENU_MAX_BLOCK_SIZE_FALLBACK,
    ),
    '--_dropdown-menu-radius': radiusVars['--radius-container'],
    '--_dropdown-menu-padding': spacingVars['--spacing-1'],
    padding: spacingVars['--spacing-1'],
    borderRadius: 'var(--_dropdown-menu-radius)',
    opacity: 1,
    transitionProperty: 'opacity',
    transitionDuration: durationVars['--duration-fast'],
    transitionTimingFunction: easeVars['--ease-standard'],
  },
  scrollable: {
    overflowY: 'auto',
    overflowX: 'hidden',
    overscrollBehavior: 'contain',
  },
  // With a header or footer, the regions and the menu share one column under
  // the menu's block cap: the regions keep their height and the menu shrinks
  // and scrolls between them.
  regionsFrame: {
    boxSizing: 'border-box',
    display: 'flex',
    flexDirection: 'column',
    maxHeight: stylex.firstThatWorks(
      MENU_MAX_BLOCK_SIZE,
      MENU_MAX_BLOCK_SIZE_FALLBACK,
    ),
  },
  menuInFrame: {
    flexGrow: 1,
    flexShrink: 1,
    minBlockSize: 0,
  },
  // Where a sub-menu with a header or footer renders its surface: beside the
  // menu, never inside it. It owns no box, so the popover's layout is
  // unchanged.
  surfaceHost: {
    display: 'contents',
  },
  // While a sub-menu's drilled-in view with its own header or footer shows
  // in the surface host, the header and footer step aside for it, as the menu
  // does (see `dropdown`). Derived from the DOM by the rule itself: the view
  // is the frame in the host that is not hidden.
  stepsAsideForView: {
    display: {
      default: null,
      [STEPS_ASIDE_FOR_VIEW]: 'none',
    },
  },
  region: {
    flexShrink: 0,
    padding: spacingVars['--spacing-1'],
  },
  // The menu's lower block cap rides on the layer box too, so the layer's
  // flip decision sees the same height the menu paints.
  popoverViewport: {
    boxSizing: 'border-box',
    maxBlockSize: stylex.firstThatWorks(
      MENU_MAX_BLOCK_SIZE,
      MENU_MAX_BLOCK_SIZE_FALLBACK,
    ),
  },
  // Without a width the menu prefers the trigger's minimum width, clamped by
  // the runtime's cap because a CSS minimum beats a maximum (spec:AST-059 FR7).
  popoverMatchTrigger: {
    minWidth: stylex.firstThatWorks(
      `min(anchor-size(width), ${layerViewportInset.maxInlineSize})`,
      `min(anchor-size(width), ${layerViewportInset.maxInlineSizeFallback})`,
      'anchor-size(width)',
    ),
  },
  popoverCustomWidth: (width: string) => ({
    minWidth: width,
  }),
  popoverCustomIntrinsicWidth: (width: string) => ({
    inlineSize: width,
  }),
});

// `menuMaxHeight` lifts the 300px cap for a menu that must fit its rows; the
// viewport still bounds it.
const dynamicStyles = stylex.create({
  menuMaxHeight: (maxHeight: string) => ({
    maxHeight: `min(${maxHeight}, ${layerViewportInset.maxBlockSize})`,
  }),
  popoverViewportMaxBlockSize: (maxHeight: string) => ({
    maxBlockSize: `min(${maxHeight}, ${layerViewportInset.maxBlockSize})`,
  }),
});

const bottomSheetStyles = stylex.create({
  content: {
    width: '100%',
  },
  header: {
    display: 'flex',
    flexDirection: 'row',
    alignItems: 'center',
    gap: spacingVars['--spacing-1'],
    marginBottom: spacingVars['--spacing-2'],
  },
  rootHeading: {
    // Match the content edge of a spacious ListItem. Icon-bearing rows place
    // their icon here; rows without an icon place their label here.
    marginInlineStart: spacingVars['--spacing-3'],
  },
  viewHeading: {
    outline: 'none',
  },
  // Caller content above or below the action list, inset to the list's
  // content edge.
  region: {
    paddingInline: spacingVars['--spacing-3'],
    paddingBlock: spacingVars['--spacing-2'],
  },
});

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

/**
 * Data-mode shape for one menu row.
 *
 * The item fields are sourced from `DropdownMenuItemProps` — data mode renders
 * through `DropdownMenuItem`, so the two APIs describe the same thing and must
 * not drift. Only the fields listed here are part of the data API; add a key to
 * the `Pick` to expose more of the item's props to `items`.
 */
export interface DropdownMenuItemData extends Pick<
  DropdownMenuItemProps,
  | 'icon'
  | 'onClick'
  | 'isDisabled'
  | 'variant'
  | 'description'
  | 'endContent'
  | 'hasCloseOnSelect'
  | 'href'
  | 'target'
  | 'rel'
> {
  /**
   * Stable identity for the row, used as its React key (as on
   * `TreeListItemData`). Omit it and the row is keyed by position, which is
   * correct for a fixed menu; set it when `items` can reorder, filter, or grow,
   * so a row keeps its DOM node — and therefore keyboard focus — as the array
   * changes around it.
   */
  id?: string;
  /** Primary label content. */
  label: ReactNode;
  /**
   * Nested submenu entries. When present, this row becomes a submenu (a
   * flyout revealing `items`) instead of a leaf action — no separate item
   * "type" is needed. Data-mode parity for the compound DropdownMenuSubMenu API.
   */
  items?: DropdownMenuOption[];
}

/**
 * Data-mode shape for a divider row. The compound-mode peer is the
 * `DropdownMenuDivider` component, which both modes render.
 */
export interface DropdownMenuDividerData {
  type: 'divider';
}

export interface DropdownMenuSection {
  type: 'section';
  /** Stable identity for the group; see {@link DropdownMenuItemData.id}. */
  id?: string;
  title?: string;
  items: DropdownMenuItemData[];
}

export type DropdownMenuOption =
  DropdownMenuItemData | DropdownMenuDividerData | DropdownMenuSection;

// =============================================================================
// Props
// =============================================================================

export type DropdownMenuButtonProps = Omit<ButtonProps, 'onClick'>;

export type DropdownMenuPresentation = AdaptivePresentation;

/**
 * The props `renderTrigger` spreads onto the control that opens the menu.
 * They carry the press model — a mouse opens on press-down, a held finger
 * opens with the finger down — the keyboard opens (Enter, Space, ArrowDown,
 * ArrowUp), the toggle click, and the ARIA wiring that names the menu after
 * the control. Spread them all; add your own handlers beside them.
 */
export interface DropdownMenuTriggerProps {
  /** Attaches the control as the menu's anchor and focus-return target. */
  ref: (element: HTMLElement | null) => void;
  /** The menu points at this id with `aria-labelledby`. */
  id: string;
  onClick: (event: React.MouseEvent<HTMLElement>) => void;
  onClickCapture: (event: React.MouseEvent<HTMLElement>) => void;
  onPointerDown: (event: React.PointerEvent<HTMLElement>) => void;
  onContextMenu: (event: React.MouseEvent<HTMLElement>) => void;
  onKeyDown: (event: React.KeyboardEvent<HTMLElement>) => void;
  onFocus: (event: React.FocusEvent<HTMLElement>) => void;
  'aria-haspopup': 'menu' | 'dialog';
  'aria-expanded': boolean;
  'aria-controls': string;
}

interface DropdownMenuBaseProps extends BaseProps {
  /**
   * The design system's own button as the trigger. Mutually exclusive with
   * `renderTrigger`.
   */
  button?: DropdownMenuButtonProps;
  /**
   * Render the control the menu hangs off — an icon button, a chip, an
   * avatar, a list row. Spread the given props onto it; the menu is then
   * named by that control. Mutually exclusive with `button`.
   *
   * Hover and pressed paint stay yours. The open state reaches your control
   * as `aria-expanded` on the given props, so style it from the rendered
   * attribute. A pressed look keyed to `:active` is not a substitute:
   * `:active` does not behave the same under a coarse pointer, which is why
   * menu rows drop coarse-pointer `:active` paint entirely.
   *
   * @example
   * ```
   * <DropdownMenu renderTrigger={props => <IconButton icon="more" label="More" {...props} />}>
   * ```
   *
   * @example
   * ```
   * // Styling the open state from the rendered attribute:
   * // .my-trigger[aria-expanded='true'] { background: var(--color-overlay-pressed); }
   * ```
   */
  renderTrigger?: (props: DropdownMenuTriggerProps) => ReactNode;
  isMenuOpen?: boolean;
  onOpenChange?: (isOpen: boolean) => void;
  /**
   * Minimum popover width. The menu may grow for its content but is capped to
   * the available viewport space. Ignored by bottom-sheet presentation.
   * Defaults to the trigger width.
   */
  menuWidth?: number | string;
  /**
   * Maximum menu height in pixels, for a menu that must fit its rows. Lifts
   * the default 300px cap; the viewport still bounds it. Ignored by
   * bottom-sheet presentation.
   */
  menuMaxHeight?: number;
  onClick?: () => void;
  hasChevron?: boolean;
  /**
   * Popover position relative to the trigger. Ignored by bottom-sheet
   * presentation.
   * Uses the same placement values as other Astryx layer-based components.
   * @default 'below'
   */
  placement?: LayerPlacement;

  /**
   * Popover alignment along the placement axis. Ignored by bottom-sheet
   * presentation.
   * Uses the same alignment values as other Astryx layer-based components.
   * @default 'start'
   */
  alignment?: LayerAlignment;
  /**
   * Content above the menu's rows and outside the menu itself — a filter
   * field, a toggle. The menu holds only its rows, so a control that is not
   * a row goes here or in `footer`, never among the rows.
   */
  header?: ReactNode;
  /**
   * Content below the menu's rows and outside the menu itself — a "Create"
   * button. See `header`.
   */
  footer?: ReactNode;

  'data-testid'?: string;
}

interface DropdownMenuDataProps extends DropdownMenuBaseProps {
  /**
   * Surface used to present the actions. Pass a value selected by product
   * policy (for example, a compact-touch media query) when the presentation
   * should adapt. Bottom-sheet presentation is intended for short action sets.
   * Omitted, the menu is the anchored popover. Under a finger, on every
   * device, the finger that opened it picks as UIMenu's does, once it has
   * moved. `'popover'` pins the anchored popover with the pointer behavior on
   * every device (the opening press follows the settle rule).
   */
  presentation?: DropdownMenuPresentation;
  items: DropdownMenuOption[];
  children?: undefined;
}

interface DropdownMenuCompoundProps extends DropdownMenuBaseProps {
  /**
   * `'popover'` pins the pointer behavior on every device (the opening press
   * follows the settle rule). Omitted, on every device, the finger
   * that opened the menu picks as UIMenu's does, once it has moved.
   */
  presentation?: 'popover';
  items?: undefined;
  children: ReactNode;
}

export type DropdownMenuProps =
  DropdownMenuDataProps | DropdownMenuCompoundProps;

// =============================================================================
// DropdownMenu
// =============================================================================

/**
 * A dropdown menu component that displays a list of actionable items.
 *
 * Supports two modes:
 * - **Data-driven**: pass `items` and choose either the default anchored
 *   popover or the modal bottom-sheet presentation.
 * - **Compound-component**: pass JSX children for dynamic, stateful, or
 *   lazy-loaded anchored popover menus.
 *
 * @example
 * ```
 * <DropdownMenu
 *   button={{ label: 'Actions' }}
 *   presentation={useBottomSheet ? 'bottom-sheet' : 'popover'}
 *   items={[
 *     { label: 'Edit', onClick: () => handleEdit() },
 *     { label: 'Delete', onClick: () => handleDelete() },
 *   ]}
 * />
 * ```
 */
// When the consumer doesn't pass `button`, the default label is looked up
// at render time so it respects the active InternationalizationProvider
// locale.
const DEFAULT_BUTTON_I18N_KEY = '@astryx.dropdownMenu.label' as const;

/**
 * Keep `control` the invoker of popover `popoverId` for the rest of the press
 * in flight, so the native light dismiss of a `popover="auto"` does not read
 * the release over the trigger as a dismissal. The attribute is dropped a
 * task after the release, once light dismiss has run.
 */
function holdInvokerThroughPress(
  control: HTMLElement | null,
  popoverId: string,
): void {
  if (control == null) {
    return;
  }
  const doc = control.ownerDocument;
  control.setAttribute('popovertarget', popoverId);
  const onPressEnd = () => {
    doc.removeEventListener('pointerup', onPressEnd, true);
    doc.removeEventListener('pointercancel', onPressEnd, true);
    // Light dismiss runs as the pointerup default action after listeners.
    doc.defaultView?.setTimeout(() => {
      control.removeAttribute('popovertarget');
    }, 0);
  };
  doc.addEventListener('pointerup', onPressEnd, true);
  doc.addEventListener('pointercancel', onPressEnd, true);
}

/**
 * The name of a menu opened from a custom trigger: the caller's `aria-label`
 * when it is a non-empty string, else the trigger's own accessible name. The
 * popover and the bottom sheet both name the menu through this.
 */
function resolveCustomTriggerMenuName(
  callerLabel: unknown,
  triggerName: string | undefined,
): string | undefined {
  return typeof callerLabel === 'string' && callerLabel.trim() !== ''
    ? callerLabel
    : triggerName;
}

function DropdownMenuBottomSheet({
  button: buttonFromProps,
  renderTrigger,
  isMenuOpen: controlledIsOpen,
  onOpenChange,
  onClick,
  hasChevron = true,
  items,
  presentation: _presentation,
  menuWidth: _menuWidth,
  menuMaxHeight: _menuMaxHeight,
  placement: _placement,
  alignment: _alignment,
  header,
  footer,
  className,
  style,
  xstyle,
  'data-testid': testId,
  ...rest
}: DropdownMenuDataProps & {presentation: 'bottom-sheet'}) {
  const t = useComponentTranslator();
  const button = buttonFromProps ?? {label: t(DEFAULT_BUTTON_I18N_KEY)};
  const backLabel = t('@astryx.dropdownMenu.back');
  const buttonRef = useRef<HTMLElement>(null);
  // The trigger, where focus returns after the sheet closes, carries the
  // modality tracking for its document.
  const modality = useInteractionModalityTracking();
  // The caller's `button.ref` rides along with the sheet's own trigger ref.
  const triggerRef = useMergedRefs<HTMLButtonElement>(
    buttonRef as React.Ref<HTMLButtonElement>,
    modality.ref,
    button.ref,
  );
  const triggerId = useId();
  const sheetId = useId();
  const actionListRef = useRef<HTMLDivElement>(null);
  const openModalityRef = useRef<'keyboard' | 'pointer'>('pointer');
  const {
    isFocusRingSuppressed,
    onFocusReturnTargetFocus,
    prepareFocusReturn,
    resetFocusReturn,
  } = useFocusReturnVisibility(modality);
  const viewHeadingRef = useRef<HTMLHeadingElement>(null);
  const previousSubmenuDepthRef = useRef(0);
  const [internalIsOpen, setInternalIsOpen] = useState(false);
  const [submenuPath, setSubmenuPath] = useState<DropdownMenuItemData[]>([]);
  const isControlled = controlledIsOpen !== undefined;
  const isOpen = isControlled ? controlledIsOpen : internalIsOpen;
  const [previousIsOpen, setPreviousIsOpen] = useState(isOpen);
  if (previousIsOpen !== isOpen) {
    setPreviousIsOpen(isOpen);
    if (!isOpen && submenuPath.length > 0) {
      setSubmenuPath([]);
    }
  }
  // The closed sheet renders nothing, so load its rows at rest: the first
  // open shows the actions at once. The preload's result says whether they
  // loaded; after a failure the first open loads them.
  useEffect(() => {
    void preloadMenuBottomSheetActionList();
  }, []);
  // The control's name is only readable from the DOM once it is rendered.
  const [triggerName, setTriggerName] = useState<string | undefined>(undefined);
  useIsomorphicLayoutEffect(() => {
    if (renderTrigger != null && isOpen) {
      setTriggerName(readAccessibleName(buttonRef.current));
    }
  }, [renderTrigger, isOpen]);
  const rootTitle =
    (renderTrigger != null
      ? resolveCustomTriggerMenuName(rest['aria-label'], triggerName)
      : undefined) ?? button.label;
  const currentSubmenu = submenuPath.at(-1);
  const currentItems = currentSubmenu?.items ?? items;
  const currentTitle = currentSubmenu?.label ?? rootTitle;
  const sheetLabel =
    typeof currentTitle === 'string' ? currentTitle : rootTitle;

  const setOpen = useCallback(
    (nextIsOpen: boolean) => {
      if (!nextIsOpen) {
        setSubmenuPath([]);
        prepareFocusReturn();
      } else {
        resetFocusReturn();
      }
      onOpenChange?.(nextIsOpen);
      if (!isControlled) {
        setInternalIsOpen(nextIsOpen);
      }
    },
    [isControlled, onOpenChange, prepareFocusReturn, resetFocusReturn],
  );

  const handleSelect = useCallback(
    (item: DropdownMenuItemData, event: React.MouseEvent) => {
      if (item.isDisabled) {
        return;
      }
      item.onClick?.(event);
      if (item.hasCloseOnSelect !== false) {
        setOpen(false);
      }
    },
    [setOpen],
  );

  const isIconOnly = button.isIconOnly === true;
  const resolvedEndContent =
    button.endContent ??
    (hasChevron && !isIconOnly ? (
      <Icon icon="chevronDown" size="sm" color="inherit" />
    ) : undefined);

  useEffect(() => {
    if (!isOpen || openModalityRef.current !== 'keyboard') {
      return;
    }
    const findFirstAction = () =>
      actionListRef.current?.querySelector<HTMLElement>(
        'button:not(:disabled), a[href]',
      ) ?? null;
    let observer: MutationObserver | null = null;
    let frame = requestAnimationFrame(() => {
      const action = findFirstAction();
      if (action != null) {
        action.focus({preventScroll: true});
        return;
      }
      // The sheet loads on demand, so a keyboard open can arrive before its
      // rows exist. Wait for them, then focus a frame later so the sheet's
      // own open-focus has already run.
      observer = new MutationObserver(() => {
        const loaded = findFirstAction();
        if (loaded == null) {
          return;
        }
        observer?.disconnect();
        observer = null;
        frame = requestAnimationFrame(() => {
          loaded.focus({preventScroll: true});
        });
      });
      observer.observe(document.body, {childList: true, subtree: true});
    });
    return () => {
      cancelAnimationFrame(frame);
      observer?.disconnect();
    };
  }, [currentItems, isOpen]);

  useEffect(() => {
    if (!isOpen) {
      previousSubmenuDepthRef.current = 0;
      return;
    }
    if (submenuPath.length === previousSubmenuDepthRef.current) {
      return;
    }
    previousSubmenuDepthRef.current = submenuPath.length;
    const frame = requestAnimationFrame(() => {
      viewHeadingRef.current?.focus({preventScroll: true});
    });
    return () => cancelAnimationFrame(frame);
  }, [isOpen, submenuPath.length]);

  const handleSheetTriggerPointerDown = () => {
    openModalityRef.current = 'pointer';
  };
  const handleSheetTriggerKeyDown = (event: React.KeyboardEvent) => {
    if (
      event.key === 'ArrowDown' ||
      event.key === 'Enter' ||
      event.key === ' '
    ) {
      openModalityRef.current = 'keyboard';
    }
  };
  const handleSheetTriggerClick = (event: React.MouseEvent<HTMLElement>) => {
    // A caller-rendered trigger that is natively or aria-disabled must not
    // open the sheet; the default Button already refuses its own click.
    // The DOM check covers the built-in Button too (it renders aria-disabled
    // when focusable-disabled); a caller's own enabled control wins over a
    // `button.isDisabled` left on the props.
    if (event.currentTarget.matches(':disabled, [aria-disabled="true"]')) {
      return;
    }
    onClick?.();
    setOpen(!isOpen);
  };

  // The root view's heading stands alone; a sub-menu's sits in a row with its
  // back button.
  const viewHeading = (
    <Heading
      ref={viewHeadingRef}
      level={3}
      tabIndex={-1}
      xstyle={[
        bottomSheetStyles.viewHeading,
        submenuPath.length === 0 && [
          bottomSheetStyles.rootHeading,
          menuBottomSheetStyles.headingAlone,
        ],
      ]}>
      {currentTitle}
    </Heading>
  );
  // A stable ref: an inline one re-runs on every render (null, then the element).
  const sheetModalityRef = modality.ref;
  const sheetTriggerRef = useCallback(
    (el: HTMLElement | null) => {
      buttonRef.current = el;
      sheetModalityRef(el);
    },
    [sheetModalityRef],
  );
  return (
    <>
      {renderTrigger != null ? (
        renderTrigger({
          ref: sheetTriggerRef,
          id: triggerId,
          onClick: handleSheetTriggerClick,
          onClickCapture: () => {},
          onPointerDown: handleSheetTriggerPointerDown,
          onContextMenu: () => {},
          onKeyDown: handleSheetTriggerKeyDown,
          onFocus: onFocusReturnTargetFocus,
          'aria-haspopup': 'dialog',
          'aria-expanded': isOpen,
          'aria-controls': sheetId,
        })
      ) : (
        <Button
          {...button}
          ref={triggerRef}
          xstyle={[
            isOpen && styles.triggerOpen,
            button.xstyle,
            isFocusRingSuppressed && focusOutlineStyles.suppressed,
          ]}
          tooltip={isOpen ? undefined : button.tooltip}
          endContent={resolvedEndContent}
          onPointerDown={event => {
            button.onPointerDown?.(event);
            handleSheetTriggerPointerDown();
          }}
          onKeyDown={event => {
            button.onKeyDown?.(event);
            handleSheetTriggerKeyDown(event);
          }}
          onFocus={event => {
            button.onFocus?.(event);
            onFocusReturnTargetFocus();
          }}
          onClick={handleSheetTriggerClick}
          aria-haspopup="dialog"
          aria-expanded={isOpen}
          data-testid={testId}
        />
      )}

      <MenuBottomSheet
        isOpen={isOpen}
        onOpenChange={setOpen}
        finalFocusRef={buttonRef}
        label={sheetLabel}>
        <div
          ref={actionListRef}
          id={sheetId}
          {...rest}
          {...mergeProps(
            themeProps('dropdown-menu', {presentation: 'bottom-sheet'}),
            stylex.props(
              bottomSheetStyles.content,
              menuBottomSheetStyles.content,
              xstyle,
            ),
            className,
            style,
          )}>
          {submenuPath.length > 0 ? (
            <div {...stylex.props(bottomSheetStyles.header)}>
              <Button
                label={backLabel}
                variant="ghost"
                size="sm"
                icon={
                  <Icon
                    icon="chevronLeft"
                    size="sm"
                    xstyle={rtlStyles.mirror}
                  />
                }
                isIconOnly
                onClick={() => setSubmenuPath(path => path.slice(0, -1))}
              />
              {viewHeading}
            </div>
          ) : (
            viewHeading
          )}
          {isRenderable(header) && (
            <div {...stylex.props(bottomSheetStyles.region)}>{header}</div>
          )}
          <MenuBottomSheetActionList
            items={currentItems}
            onSelect={handleSelect}
            onOpenSubmenu={item => setSubmenuPath(path => [...path, item])}
          />
          {isRenderable(footer) && (
            <div {...stylex.props(bottomSheetStyles.region)}>{footer}</div>
          )}
        </div>
      </MenuBottomSheet>
    </>
  );
}

function DropdownMenuPopover({
  button: buttonFromProps,
  renderTrigger,
  isMenuOpen: controlledIsOpen,
  onOpenChange,
  menuWidth,
  menuMaxHeight,
  onClick,
  hasChevron = true,
  placement = 'below',
  alignment = 'start',
  presentation: _presentation,
  pressTouchModel = 'uikit',
  header,
  footer,
  className,
  style,
  xstyle,
  'data-testid': testId,
  ...props
}: DropdownMenuProps & {
  /**
   * How a finger's press runs, on every device: UIMenu's, unless the caller
   * pins `presentation="popover"`.
   */
  pressTouchModel?: 'pointer' | 'uikit';
}) {
  const t = useComponentTranslator();
  const button = buttonFromProps ?? {label: t(DEFAULT_BUTTON_I18N_KEY)};

  const items = ('items' in props ? props.items : undefined) ?? [];
  const children = props.children;

  // Extract BaseProps pass-throughs (aria-*, id, event handlers) from the
  // discriminated-union rest bag so they can be forwarded to the menu element.
  const {
    items: _items,
    children: _children,
    ...rest
  } = props as Record<string, unknown>;

  const menuId = useId();
  const triggerId = useId();
  const menuSize = button.size ?? 'md';
  const buttonRef = useRef<HTMLElement>(null);

  // The name a custom trigger gives the menu, read off it as the menu opens.
  const [triggerName, setTriggerName] = useState<string | undefined>(undefined);

  // Open state
  const [internalIsOpen, setInternalIsOpen] = useState(false);
  const isControlled = controlledIsOpen !== undefined;
  const isOpen = isControlled ? controlledIsOpen : internalIsOpen;
  const acceptedOpenRef = useRef(false);
  const notifyClickOnShowRef = useRef(false);
  const pendingControlledOpenRef = useRef(false);
  const suppressControlledRollbackHideRef = useRef(false);

  const contentRef = useRef<HTMLDivElement | null>(null);
  const modality = useInteractionModalityTracking();
  const {
    isFocusRingSuppressed,
    onFocusReturnTargetFocus,
    prepareFocusReturn,
    resetFocusReturn,
  } = useFocusReturnVisibility(modality);
  const headerRef = useRef<HTMLDivElement | null>(null);
  const footerRef = useRef<HTMLDivElement | null>(null);
  const hasRegions = useMemo(
    () => isRenderable(header) || isRenderable(footer),
    [header, footer],
  );
  // Whether the menu element itself took focus from the keyboard. A pointer
  // open focuses it programmatically, and pointer history must not paint the
  // keyboard ring (architecture:interaction-modality INV1).
  const [isMenuKeyboardFocused, setIsMenuKeyboardFocused] = useState(false);
  // The press model is mounted below (it needs the popover); the hide path
  // above it ends the gesture in flight through this ref.
  const cancelMenuPressRef = useRef<() => void>(() => {});
  // The entrance hold starts as the layer shows. Its start is set below, once
  // the list ref exists, and its release is kept for the close.
  const holdEntranceRef = useRef<() => void>(() => {});
  const releaseEntranceRef = useRef<(() => void) | null>(null);
  // The trigger press that asks the menu to open. The show holds the trigger
  // as the invoker through that press; that hold is set below, once the
  // popover exists.
  const openingPressRef = useRef<{gesture: number} | null>(null);
  const holdOpeningPressRef = useRef<() => void>(() => {});

  // Submenu flyouts are `popover="manual"` elements nested inside the menu's
  // `popover="auto"` element, so the browser's light dismiss of the menu never
  // reaches them: without a sweep they keep their open state and their
  // top-layer entry while the menu is hidden, and re-anchor to the viewport
  // corner when the menu reopens (#6893). Closing them through the popover
  // API lets useLayer's toggle handling reset their state. Only flyouts that
  // are actually open are touched: `:popover-open` ships wherever
  // `hidePopover` does (they are one API), and the display fallback keeps its
  // own open signal (`display: block`) so it is guarded the same way.
  const hideOpenFlyouts = useCallback(() => {
    const menuPopover = contentRef.current;
    if (!menuPopover) {
      return;
    }
    // Innermost first: hiding a flyout may unmount the flyouts nested inside
    // it, and a detached element no longer has the toggle listener that
    // resets its open state.
    const flyouts = [
      ...menuPopover.querySelectorAll<HTMLElement>('[popover]'),
    ].reverse();
    for (const flyout of flyouts) {
      if (typeof flyout.hidePopover === 'function') {
        if (flyout.matches(':popover-open')) {
          flyout.hidePopover();
        }
      } else if (flyout.style.display === 'block') {
        flyout.style.display = 'none';
        const toggle = new Event('toggle', {bubbles: false});
        Object.defineProperty(toggle, 'newState', {
          value: 'closed',
          configurable: true,
        });
        flyout.dispatchEvent(toggle);
      }
    }
  }, []);

  // Focus lands somewhere stated when the menu closes. A press outside that
  // landed on a focusable control has already moved focus there; leave it.
  // Otherwise — a row acted, Escape, a press on nothing — focus returns to
  // the trigger, with a visible ring only when the menu was driven by
  // keyboard (the modality tracker decides; the suppressed style hides the
  // pointer case, which Safari would otherwise paint after a touch pick).
  const handleLayerHide = useCallback(() => {
    releaseEntranceRef.current?.();
    releaseEntranceRef.current = null;
    // Whatever closed the menu — light dismiss, the dismissal stack, Escape
    // or a controlled close — its flyouts close with it.
    hideOpenFlyouts();
    if (suppressControlledRollbackHideRef.current) {
      suppressControlledRollbackHideRef.current = false;
      return;
    }
    cancelMenuPressRef.current();
    pendingControlledOpenRef.current = false;
    onOpenChange?.(false);
    if (!isControlled) {
      setInternalIsOpen(false);
    }
    const trigger = buttonRef.current;
    if (!trigger) {
      return;
    }
    const active = document.activeElement;
    const focusLandedElsewhere =
      active instanceof HTMLElement &&
      active !== document.body &&
      active !== trigger &&
      !contentRef.current?.contains(active);
    if (focusLandedElsewhere) {
      return;
    }
    prepareFocusReturn();
    // After pointer input the trigger takes focus without the focus-visible
    // ring (`component:DropdownMenu/DEC-1`). The style the helper above adds
    // reaches only the design system's own Button; the browser's focus option
    // also reaches a control the caller renders, which the browser would
    // otherwise ring (Chromium after a mouse pick, WebKit after a touch).
    returnFocusForLastInput(trigger);
  }, [hideOpenFlyouts, isControlled, onOpenChange, prepareFocusReturn]);

  // Defer item focus until the layer has committed open, so focus restore
  // captures the trigger instead of the first menu item.
  const shouldFocusOnOpenRef = useRef(false);

  // How the next open was initiated. Keyboard (and programmatic) opens focus
  // the first enabled item per the APG menu-button pattern; pointer opens
  // focus the menu container instead, so no item is visually highlighted as
  // if pre-selected (#4477). Reset to 'keyboard' after every open so
  // programmatic controlled opens keep the item-focus behavior.
  const openModalityRef = useRef<'keyboard' | 'pointer'>('keyboard');
  // ArrowUp opens with the LAST enabled row highlighted.
  const focusLastOnOpenRef = useRef(false);

  // Synchronizes the dialog's name from the custom trigger's DOM, an external
  // system React does not own: the rendered control's accessible name is only
  // readable once it mounts. With a header or footer the dialog is named like
  // the menu, so that name is needed before the first open, not only at it.
  useIsomorphicLayoutEffect(() => {
    if (renderTrigger != null && hasRegions && triggerName == null) {
      setTriggerName(readAccessibleName(buttonRef.current));
    }
  }, [renderTrigger, hasRegions, triggerName]);

  const handleLayerShow = useCallback(() => {
    acceptedOpenRef.current = true;
    holdOpeningPressRef.current();
    holdEntranceRef.current();
    resetFocusReturn();
    if (renderTrigger != null) {
      setTriggerName(readAccessibleName(buttonRef.current));
    }
    if (notifyClickOnShowRef.current) {
      notifyClickOnShowRef.current = false;
      onClick?.();
    }
    onOpenChange?.(true);
    if (!isControlled) {
      setInternalIsOpen(true);
    }
  }, [isControlled, onClick, onOpenChange, renderTrigger, resetFocusReturn]);

  // The menu's name: the dialog around it with a header or footer, and the
  // Back row of a drilled-in view ("Back to <this>"), both read it.
  // The design system's button names the menu by its label. A custom trigger
  // names it by reference (or the caller's `aria-label` does), so that name
  // is read off the control as the menu opens.
  const menuLabel =
    renderTrigger != null
      ? resolveCustomTriggerMenuName(rest['aria-label'], triggerName)
      : typeof button.label === 'string'
        ? button.label
        : undefined;

  const popover = usePopover({
    onHide: handleLayerHide,
    onShow: handleLayerShow,
    hasLightDismiss: true,
    hasCloseButton: false,
    hasAutoFocus: false,
    // Without a header or footer the popup's own role="menu" is the exposed
    // semantics; a dialog around it would announce an extra container. With
    // either, the popover holds controls that are not menu items, so it is a
    // modal dialog named like the menu, with the menu inside it. A custom
    // trigger's name is read off the control once it mounts; until then, or
    // when the control exposes no readable name, the dialog takes the default
    // menu label, so it is never unnamed and never loses its role.
    role: hasRegions ? 'dialog' : 'none',
    dialogLabel: hasRegions
      ? (menuLabel ?? t(DEFAULT_BUTTON_I18N_KEY))
      : undefined,
    // The entrance runs on the surface: an anchored layer lays out again on
    // each frame its own style animates.
    xstyle: layerAnimations[placement],
  });

  const closeMenu = useCallback(() => {
    popover.hide();
  }, [popover]);

  // Single keyboard navigation path for both modes.
  // The selector matches plain items plus selectable items
  // (menuitemradio/menuitemcheckbox) so lab checkbox/radio rows are reachable
  // and roved to alongside plain items — not just role="menuitem".
  const {
    listRef,
    handleKeyDown: listNavKeyDown,
    focusFirst,
    focusLast,
    focusItem,
    ownsEvent,
    getItems: getMenuItems,
  } = useInternalListFocus<HTMLDivElement>({
    itemSelector: MENU_ROW_SELECTOR,
    reachesDisabledItems: true,
    boundarySelector: MENU_BOUNDARY_SELECTOR,
    // Menus wrap from the last row to the first and back, as macOS menus do;
    // a picker's list clamps instead.
    wrap: true,
    hasPaging: true,
    onEscape: closeMenu,
  });

  // Typeahead over the menu items, disabled ones included — jump to the next item whose
  // LABEL starts with the typed text, never its description, shortcut or
  // badge. Reuses the hook's scoped item collection so an inline submenu
  // flyout's items aren't swept in.
  const typeahead = useTypeahead({
    getItemLabels: () => getMenuItems().map(el => el.textContent),
    onMatch: focusItem,
    getCurrentIndex: () =>
      getMenuItems().findIndex(
        el =>
          el === document.activeElement || el.contains(document.activeElement),
      ),
  });

  // Mounting already open (`isMenuOpen` true on the first render) is not an
  // open anyone asked for, so it must not move focus into the menu — that
  // drops keyboard users mid-page (#5976). The flag is decided once at mount
  // rather than per effect run, because the layer may defer the first show
  // until its popover element mounts; it clears once the consumer closes the
  // menu, so every later open follows the modality rules above.
  const isMountedOpenRef = useRef(isControlled && controlledIsOpen === true);

  // Sync controlled open state → popover. A trigger open is committed first so
  // Popover can reject the dismissing gesture before notifying the controller.
  // If the controller has not accepted by the next layout pass, roll the DOM
  // state back before paint without emitting a second change request.
  useIsomorphicLayoutEffect(() => {
    if (!isControlled) {
      return;
    }
    if (controlledIsOpen) {
      pendingControlledOpenRef.current = false;
      if (!popover.isOpen) {
        shouldFocusOnOpenRef.current = !isMountedOpenRef.current;
        popover.show();
      }
    } else {
      isMountedOpenRef.current = false;
      if (popover.isOpen) {
        suppressControlledRollbackHideRef.current =
          pendingControlledOpenRef.current;
        pendingControlledOpenRef.current = false;
        popover.hide();
      }
    }
  }, [controlledIsOpen, isControlled, popover]);

  // Move focus into the menu only after the layer has committed open,
  // honoring the input modality: keyboard (and programmatic) opens land on
  // the first enabled item per the APG menu-button pattern; pointer opens
  // focus the menu container itself (tabIndex={-1}) so no item is
  // highlighted as if pre-selected (#4477). Container focus keeps arrows,
  // typeahead, Escape and Tab in the menu's onKeyDown, and is also the
  // fallback when no item is focusable (e.g. all disabled), mirroring the
  // submenu flyout fallback.
  useEffect(() => {
    if (!popover.isOpen || !shouldFocusOnOpenRef.current) {
      return;
    }
    shouldFocusOnOpenRef.current = false;
    requestAnimationFrame(() => {
      const focusEnd = focusLastOnOpenRef.current ? focusLast : focusFirst;
      focusLastOnOpenRef.current = false;
      const isPointerOpen = openModalityRef.current === 'pointer';
      // A pointer that lit a row before this frame keeps that row's
      // highlight: the row under the pointer stays the focused row.
      const list = listRef.current;
      const active = list?.ownerDocument.activeElement;
      const isRowLit =
        isPointerOpen &&
        active != null &&
        active !== list &&
        list?.contains(active) === true;
      if (!isRowLit && (isPointerOpen || !focusEnd())) {
        list?.focus();
      }
      openModalityRef.current = 'keyboard';
    });
  }, [popover.isOpen, focusFirst, focusLast, listRef]);

  // Under a finger, where the primary pointer is coarse, a tap or a drag during
  // the entrance reaches nothing, as in UIMenu. Keys and assistive technology
  // stay live.
  const holdEntrance = useCallback(() => {
    releaseEntranceRef.current?.();
    const layer =
      pressTouchModel === 'uikit'
        ? listRef.current?.closest('[popover]')
        : null;
    // The entrance plays on the popover's surface, inside the layer.
    releaseEntranceRef.current =
      layer == null
        ? null
        : holdEntranceInput(layer, {
            entrance: popover.contentRef.current ?? layer,
          });
  }, [listRef, pressTouchModel, popover.contentRef]);
  holdEntranceRef.current = holdEntrance;
  // The layer runtime's input hold: an unmount during the entrance releases it.
  useEffect(
    () => () => {
      releaseEntranceRef.current?.();
      releaseEntranceRef.current = null;
    },
    [],
  );

  // With a header or footer the popover is a modal dialog: Tab and Shift+Tab
  // walk the header's controls, the menu as one stop, then the footer's
  // controls, and wrap at either end. The key is handled here in full, so the
  // popover's own focus trap, which listens on the document, never reads it a
  // second time.
  const moveDialogTab = useCallback(
    (e: React.KeyboardEvent, isFromFlyout = false) => {
      moveRegionsTab(
        e,
        listRef.current,
        headerRef.current,
        footerRef.current,
        isFromFlyout,
      );
    },
    [listRef],
  );

  // Extend useListFocus with Enter/Space activation + typeahead
  const listKeyDown = useCallback(
    (e: React.KeyboardEvent) => {
      // A submenu flyout renders inline inside this menu; its key events bubble
      // up here. Let that level own them — only handle events from this level.
      if (!ownsEvent(e)) {
        // Except Tab: each open flyout has closed itself as the key bubbled
        // up, and the root moves on as Tab from one of its own rows would.
        // With a header or footer that walks the regions; otherwise the menu
        // closes and focus moves on from the trigger (APG menu button).
        if (e.key === 'Tab') {
          if (hasRegions) {
            moveDialogTab(e, true);
          } else {
            closeMenu();
          }
        }
        return;
      }
      if (e.key === 'Enter' || e.key === ' ') {
        e.preventDefault();
        // The key that opened the menu, held down, auto-repeats into the menu
        // once focus has moved there; a repeat is never an activation.
        if (e.repeat) {
          return;
        }
        const focused = document.activeElement as HTMLElement | null;
        if (
          focused &&
          MENU_ITEM_ROLES.has(focused.getAttribute('role') ?? '')
        ) {
          // The synthesized click keeps the key's modifiers, so a modified
          // Enter on a link row opens the way a modified click would.
          activateMenuItem(focused, e);
        }
        return;
      }
      // With a header or footer the popover is a dialog and Tab wraps inside
      // it. Without either, the APG menu-button pattern: Tab closes the menu.
      // Menu items are tabIndex={-1} so the focus trap has nothing trappable
      // and Tab would otherwise leak into the page while the menu stayed open
      // (menus-5). Do NOT preventDefault — closing restores focus to the
      // trigger, and the browser's default Tab then continues from there.
      if (e.key === 'Tab') {
        if (hasRegions) {
          moveDialogTab(e);
          return;
        }
        closeMenu();
        return;
      }
      // Type-to-focus next; if it consumed a printable key, stop here.
      if (typeahead.onKeyDown(e)) {
        e.preventDefault();
        return;
      }
      listNavKeyDown(e);
    },
    [
      listNavKeyDown,
      closeMenu,
      typeahead,
      ownsEvent,
      hasRegions,
      moveDialogTab,
    ],
  );

  // Tab from a header or footer control moves through the same dialog cycle.
  const handleRegionKeyDown = useCallback(
    (e: React.KeyboardEvent<HTMLDivElement>) => {
      if (e.key === 'Tab') {
        moveDialogTab(e);
      }
    },
    [moveDialogTab],
  );

  const openAndFocus = useCallback(
    (
      modality: 'keyboard' | 'pointer' = 'keyboard',
      notifyClick = false,
    ): boolean => {
      // An unavailable trigger never opens the menu. Button keeps an
      // aria-disabled trigger focusable for its tooltip and swallows only
      // Enter and Space, so the arrow keys, a press and a click would still
      // arrive here; a custom trigger may be natively disabled instead.
      if (
        buttonRef.current?.matches(':disabled, [aria-disabled="true"]') === true
      ) {
        return false;
      }
      acceptedOpenRef.current = false;
      notifyClickOnShowRef.current = notifyClick;
      pendingControlledOpenRef.current = isControlled;
      openModalityRef.current = modality;
      shouldFocusOnOpenRef.current = true;
      popover.show();
      if (!acceptedOpenRef.current) {
        notifyClickOnShowRef.current = false;
        pendingControlledOpenRef.current = false;
        openModalityRef.current = 'keyboard';
        shouldFocusOnOpenRef.current = false;
        return false;
      }
      return true;
    },
    [isControlled, popover],
  );

  const isMenuOpenNow = isControlled
    ? controlledIsOpen === true
    : popover.isOpen;

  // The menu is `popover="auto"`. The browser's light dismiss reads a release
  // outside the popover as a dismissal, also the release of the press that
  // opened it. This holds for a mouse and for a finger after the long-press
  // delay, and also when the show waited for another popover operation. So
  // the trigger stays the popover's invoker through that press, as
  // useKeepLayerOpenProps does for controls beside an open layer.
  const holdOpeningPress = useCallback(() => {
    const press = openingPressRef.current;
    openingPressRef.current = null;
    if (
      press != null &&
      press.gesture === currentGesture() &&
      isPressInFlight()
    ) {
      holdInvokerThroughPress(buttonRef.current, popover.id);
    }
  }, [popover.id]);
  holdOpeningPressRef.current = holdOpeningPress;

  // A mouse opens on press-down; a finger held on the trigger opens after
  // the long-press delay. Pressing the trigger of an open menu closes it, and
  // the click of that same gesture — reported by `isTriggerClickFromPress` —
  // neither toggles nor reopens.
  const handleTriggerPress = useCallback(
    (pointerType: MenuPressPointerType): boolean => {
      if (isMenuOpenNow) {
        if (pointerType !== 'mouse') {
          // A finger's tap toggles through its click, as it always did.
          return false;
        }
        onClick?.();
        if (isControlled) {
          onOpenChange?.(false);
        } else {
          popover.hide();
        }
        return false;
      }
      // The press opens the menu before the browser's own mousedown has
      // focused the trigger (a held finger never does), so the popover would
      // remember whatever was focused BEFORE the press as the element to hand
      // focus back to when it closes. Focusing the trigger first gives the
      // popover the state a click-open already has: the trigger is where
      // Escape or a pick returns focus (the APG menu-button pattern). A
      // finger's press shows no ring here.
      if (buttonRef.current != null) {
        focusForLastInput(buttonRef.current, {preventScroll: true});
      }
      openingPressRef.current = {gesture: currentGesture()};
      const didOpen = openAndFocus('pointer', true);
      // A mouse can release away from the trigger, or the trigger can move
      // away under it. So the layer claims a mouse's press, and that release
      // lands on the layer; over the trigger, the trigger keeps it. Only a
      // show accepted here claims it. After a show that waited, the press
      // model no longer tracks the press, and a settled release outside must
      // still close the menu.
      const layer = listRef.current?.closest('[popover]');
      if (didOpen && pointerType === 'mouse' && layer instanceof HTMLElement) {
        claimPress(layer, {releaseTarget: buttonRef.current});
      }
      return didOpen;
    },
    [
      isMenuOpenNow,
      isControlled,
      listRef,
      onClick,
      onOpenChange,
      openAndFocus,
      popover,
    ],
  );

  // The press model: the row under a release acts, the highlight follows a
  // held pointer. A mouse released outside the menu dismisses it; a finger
  // released outside leaves it open, so the hook never calls onDismiss then.
  const menuPress = useDropdownMenuPress({
    menuRef: listRef,
    triggerRef: buttonRef,
    itemSelector: MENU_ITEM_SELECTOR,
    onTriggerPress: handleTriggerPress,
    onDismiss: closeMenu,
    // Under a finger, on every device, the opening finger picks as UIMenu's
    // does. `presentation="popover"` pins the pointer model.
    touchModel: pressTouchModel,
  });
  cancelMenuPressRef.current = menuPress.cancel;

  const handleButtonClick = useCallback(
    (e: React.MouseEvent<HTMLElement>) => {
      // The press already opened or closed the menu; its click is spent.
      if (menuPress.isTriggerClickFromPress()) {
        return;
      }
      // detail === 0 marks a synthesized click (screen reader / AT
      // activation): treat it as keyboard so those users still land on the
      // first item. Real pointer clicks report detail >= 1.
      const modality = e.detail === 0 ? 'keyboard' : 'pointer';
      if (isControlled) {
        if (controlledIsOpen) {
          onClick?.();
          onOpenChange?.(false);
        } else {
          openAndFocus(modality, true);
        }
      } else if (popover.isOpen) {
        onClick?.();
        popover.hide();
      } else {
        openAndFocus(modality, true);
      }
    },
    [
      menuPress,
      onClick,
      isControlled,
      onOpenChange,
      controlledIsOpen,
      popover,
      openAndFocus,
    ],
  );

  const handleTriggerClickCapture = useCallback(
    (e: React.MouseEvent<HTMLElement>) => {
      const control = e.currentTarget;
      if (control.hasAttribute('popovertarget')) {
        // Still the invoker from a press-open: the browser would toggle the
        // menu shut on this click.
        e.preventDefault();
        control.removeAttribute('popovertarget');
      }
    },
    [],
  );

  const handleButtonKeyDown = useCallback(
    (e: React.KeyboardEvent) => {
      if (!popover.isOpen) {
        if (
          e.key === 'ArrowDown' ||
          e.key === 'ArrowUp' ||
          e.key === 'Enter' ||
          e.key === ' '
        ) {
          e.preventDefault();
          if (e.repeat) {
            return;
          }
          focusLastOnOpenRef.current = e.key === 'ArrowUp';
          if (!openAndFocus()) {
            // A refused open (disabled trigger) must not leave ArrowUp's
            // "land on the last row" armed for a later open.
            focusLastOnOpenRef.current = false;
          }
        }
        return;
      }
      // Open with focus still on the trigger — a menu that mounted open, or
      // a pointer open followed by Shift+Tab — has nothing in the tab order
      // to reach its items, so ArrowDown walks in the way a keyboard open
      // would land (#5976). Enter/Space keep toggling the menu closed, and
      // once focus is inside, key events go to the menu container instead.
      if (e.key === 'ArrowDown') {
        e.preventDefault();
        if (!focusFirst()) {
          listRef.current?.focus();
        }
      }
    },
    [popover.isOpen, openAndFocus, focusFirst, listRef],
  );

  // Icon-only
  const isIconOnly = button.isIconOnly === true;
  const resolvedEndContent =
    button.endContent ??
    (hasChevron && !isIconOnly ? (
      <Icon icon="chevronDown" size="sm" color="inherit" />
    ) : undefined);

  // An explicit menuWidth is clamped to the viewport, never to the room
  // beside the trigger (spec:AST-059 FR2, FR7).
  const resolvedMenuWidth = menuWidth
    ? resolveMenuWidth(menuWidth, layerViewportInset.maxInlineSizeFallback)
    : null;
  const popoverXstyle = resolvedMenuWidth
    ? resolvedMenuWidth.property === 'inlineSize'
      ? styles.popoverCustomIntrinsicWidth(resolvedMenuWidth.value)
      : styles.popoverCustomWidth(resolvedMenuWidth.value)
    : styles.popoverMatchTrigger;

  // The drill-in view stack for sub-menus on a phone.
  const {drillIn, wrapContent} = useMenuDrillIn(isOpen);
  // The surface host is owned through a ref. State keeps only a key that
  // changes whenever a host element attaches, the host included when it
  // moves (a header or footer coming or going), so sub-menus re-render into
  // the element that is mounted.
  const surfaceHostRef = useRef<HTMLDivElement | null>(null);
  const [surfaceHostKey, setSurfaceHostKey] = useState(0);
  const attachSurfaceHost = useCallback((node: HTMLDivElement | null) => {
    surfaceHostRef.current = node;
    if (node != null) {
      setSurfaceHostKey(key => key + 1);
    }
  }, []);
  const surfaceHost = useMemo<DropdownMenuSurfaceHost>(
    () => ({
      getElement: () => (surfaceHostKey > 0 ? surfaceHostRef.current : null),
    }),
    [surfaceHostKey],
  );
  const resolvedMaxHeight = menuMaxHeight == null ? null : `${menuMaxHeight}px`;
  // Context for compound items
  const contextValue = useMemo<DropdownMenuContextValue>(
    () => ({closeMenu, menuSize, drillIn, menuLabel}),
    [closeMenu, menuSize, drillIn, menuLabel],
  );
  // What a sub-menu with a header or footer needs, on an internal context.
  const surfaceValue = useMemo<DropdownMenuSurfaceValue>(
    () => ({
      host: surfaceHost,
      ownerId: menuId,
      menuMaxHeight: resolvedMaxHeight ?? undefined,
    }),
    [surfaceHost, menuId, resolvedMaxHeight],
  );

  // Resolve menu content: data-driven items become components
  const menuContent = wrapContent(
    props.items !== undefined ? renderDropdownItems(items) : children,
  );
  const hasOverflow = useMenuOverflow(listRef, menuContent, popover.isOpen);

  // The header and footer sit beside the menu inside the popover, never inside
  // the role="menu" element: a menu holds only its rows. The surface host
  // follows the menu, so a sub-menu with a header or footer renders beside the
  // menu too; while such a sub-menu's drilled-in view shows there, the menu and
  // the regions step aside (STEPS_ASIDE_FOR_VIEW).
  const surfaceHostElement = (
    <div
      ref={attachSurfaceHost}
      data-astryx-submenu-host=""
      {...stylex.props(styles.surfaceHost)}
    />
  );
  const renderWithRegions = (menu: ReactNode): ReactNode =>
    hasRegions ? (
      <div
        {...stylex.props(
          styles.regionsFrame,
          resolvedMaxHeight != null &&
            dynamicStyles.menuMaxHeight(resolvedMaxHeight),
        )}>
        {isRenderable(header) && (
          <div
            ref={headerRef}
            onKeyDown={handleRegionKeyDown}
            {...stylex.props(styles.region, styles.stepsAsideForView)}>
            {header}
          </div>
        )}
        {menu}
        {isRenderable(footer) && (
          <div
            ref={footerRef}
            onKeyDown={handleRegionKeyDown}
            {...stylex.props(styles.region, styles.stepsAsideForView)}>
            {footer}
          </div>
        )}
        {surfaceHostElement}
      </div>
    ) : (
      <>
        {menu}
        {surfaceHostElement}
      </>
    );

  // Stable trigger refs. An inline ref is a new function every render, so React
  // re-runs it on every commit (null, then the element), and each run moved the
  // popover's anchor off the trigger and back: two inline-style writes on the
  // trigger per render of the menu.
  const popoverTriggerRef = popover.triggerRef;
  // The trigger, where focus returns, also carries the modality tracking for
  // its document.
  const modalityRef = modality.ref;
  const triggerRef = useCallback(
    (el: HTMLElement | null) => {
      buttonRef.current = el;
      popoverTriggerRef(el);
      // Called with each node and with `null`, so its cleanup isn't returned
      // (a returned cleanup would stop React's `null` call to the others).
      modalityRef(el);
    },
    [popoverTriggerRef, modalityRef],
  );
  const consumerButtonRef = button.ref;
  const buttonTriggerRef = useCallback(
    (el: HTMLButtonElement | null) => {
      triggerRef(el);
      if (typeof consumerButtonRef === 'function') {
        consumerButtonRef(el);
      } else if (consumerButtonRef) {
        /* eslint-disable react-compiler/react-compiler -- ref callback: forwarding consumer ref object */
        consumerButtonRef.current = el;
        /* eslint-enable react-compiler/react-compiler */
      }
    },
    [triggerRef, consumerButtonRef],
  );

  const triggerProps: DropdownMenuTriggerProps = {
    ref: triggerRef,
    id: triggerId,
    onClick: handleButtonClick,
    onClickCapture: handleTriggerClickCapture,
    onPointerDown: menuPress.triggerProps.onPointerDown,
    onContextMenu: menuPress.triggerProps.onContextMenu,
    onKeyDown: handleButtonKeyDown,
    // The caller's control paints its own ring, and the menu's focus return
    // keeps the browser from drawing one after pointer input (see
    // handleLayerHide), so its focus needs no bookkeeping here.
    onFocus: () => {},
    'aria-haspopup': hasRegions ? 'dialog' : 'menu',
    'aria-expanded': isOpen,
    'aria-controls': hasRegions ? popover.id : menuId,
  };

  return (
    <>
      {renderTrigger != null ? (
        renderTrigger(triggerProps)
      ) : (
        <Button
          {...button}
          ref={buttonTriggerRef}
          xstyle={[
            styles.triggerPressable,
            isOpen && styles.triggerOpen,
            button.xstyle,
            isFocusRingSuppressed && focusOutlineStyles.suppressed,
          ]}
          tooltip={isOpen ? undefined : button.tooltip}
          endContent={resolvedEndContent}
          onClick={handleButtonClick}
          onClickCapture={event => {
            button.onClickCapture?.(event);
            handleTriggerClickCapture(event);
          }}
          onKeyDown={handleButtonKeyDown}
          onPointerDown={event => {
            button.onPointerDown?.(event);
            menuPress.triggerProps.onPointerDown(event);
          }}
          onContextMenu={event => {
            button.onContextMenu?.(event);
            menuPress.triggerProps.onContextMenu(event);
          }}
          onFocus={event => {
            button.onFocus?.(event);
            onFocusReturnTargetFocus();
          }}
          aria-haspopup={hasRegions ? 'dialog' : 'menu'}
          aria-expanded={isOpen}
          aria-controls={hasRegions ? popover.id : menuId}
          data-testid={testId}
        />
      )}
      {popover.render(
        renderWithRegions(
          <div
            {...rest}
            ref={el => {
              listRef.current = el;
              contentRef.current =
                el?.closest<HTMLDivElement>('[popover]') ?? null;
            }}
            id={menuId}
            role="menu"
            // Pointer opens focus the container so arrows, typeahead, Escape and
            // Tab remain owned by the menu without pre-highlighting an item.
            // An overflowing menu joins the Tab order so its scrollable region is
            // keyboard-accessible; Tab still dismisses through listKeyDown. With
            // a header or footer the menu is one Tab stop between them.
            tabIndex={hasOverflow || hasRegions ? 0 : -1}
            // Give the menu an accessible name from its trigger's label, so
            // screen readers announce e.g. "Actions menu" rather than an unnamed
            // menu (menus-13). A custom trigger names it by reference.
            aria-label={
              renderTrigger != null
                ? (rest['aria-label'] as string | undefined)
                : button.label
            }
            aria-labelledby={
              renderTrigger != null && rest['aria-label'] == null
                ? triggerId
                : (rest['aria-labelledby'] as string | undefined)
            }
            onKeyDown={listKeyDown}
            onFocus={event => {
              (
                rest.onFocus as
                  React.FocusEventHandler<HTMLDivElement> | undefined
              )?.(event);
              if (event.target === event.currentTarget) {
                setIsMenuKeyboardFocused(
                  getInteractionModality(event.currentTarget) === 'keyboard',
                );
              }
            }}
            {...menuPress.menuProps}
            {...mergeProps(
              themeProps('dropdown-menu', {presentation: 'popover'}),
              stylex.props(
                styles.dropdown,
                resolvedMaxHeight != null &&
                  dynamicStyles.menuMaxHeight(resolvedMaxHeight),
                hasOverflow
                  ? menuTouchActionStyles.scrolls
                  : menuTouchActionStyles.fits,
                hasOverflow && styles.scrollable,
                hasRegions && styles.menuInFrame,
                // Between a header and a footer the menu is a Tab stop, so
                // keyboard focus on it must be visible (the base style removes
                // the ring for the pointer-open focus target).
                hasRegions &&
                  isMenuKeyboardFocused &&
                  focusOutlineStyles.focusVisible,
                xstyle,
              ),
              className,
              style,
            )}>
            <DropdownMenuContext value={contextValue}>
              <DropdownMenuSurfaceContext value={surfaceValue}>
                <DropdownMenuRootOpenContext value={isOpen}>
                  {menuContent}
                </DropdownMenuRootOpenContext>
              </DropdownMenuSurfaceContext>
            </DropdownMenuContext>
          </div>,
        ),
        {
          placement,
          alignment,
          offset: spacingVars['--spacing-1'],
          xstyle: [
            styles.popoverViewport,
            resolvedMaxHeight != null &&
              dynamicStyles.popoverViewportMaxBlockSize(resolvedMaxHeight),
            popoverXstyle,
          ],
        },
      )}
    </>
  );
}

export function DropdownMenu(props: DropdownMenuProps) {
  const {onOpenChange} = props;
  // Both presentations hang the menu off ONE control.
  useDevWarning(
    'DropdownMenu',
    '`button` and `renderTrigger` are mutually exclusive: the menu hangs ' +
      'off one control. `renderTrigger` wins; drop `button`.',
    props.button != null && props.renderTrigger != null,
  );
  const requestedPresentation =
    'items' in props ? (props.presentation ?? 'popover') : 'popover';
  const resolvedPresentation = useAdaptivePresentation(requestedPresentation);
  const isControlled = props.isMenuOpen !== undefined;
  const [internalIsOpen, setInternalIsOpen] = useState(false);
  const isOpen = isControlled ? props.isMenuOpen : internalIsOpen;
  const handleOpenChange = useCallback(
    (nextIsOpen: boolean) => {
      onOpenChange?.(nextIsOpen);
      if (!isControlled) {
        setInternalIsOpen(nextIsOpen);
      }
    },
    [isControlled, onOpenChange],
  );
  const sharedProps = {
    ...props,
    isMenuOpen: isOpen,
    onOpenChange: handleOpenChange,
  };

  if (
    resolvedPresentation === 'bottom-sheet' &&
    'items' in props &&
    props.items !== undefined
  ) {
    return (
      <PressGroupContext value={null}>
        <DropdownMenuBottomSheet
          {...(sharedProps as DropdownMenuDataProps)}
          presentation="bottom-sheet"
        />
      </PressGroupContext>
    );
  }

  // In a group that tracks presses, the trigger keeps its own press and
  // opening, whatever its `aria-haspopup`.
  return (
    <PressGroupContext value={null}>
      <DropdownMenuPopover
        {...sharedProps}
        presentation="popover"
        pressTouchModel={props.presentation === 'popover' ? 'pointer' : 'uikit'}
      />
    </PressGroupContext>
  );
}

DropdownMenu.displayName = 'DropdownMenu';