Skip to content

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

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

'use client';

/**
 * @file usePopover.tsx
 * @input Uses useLayer, useFocusTrap, React hooks
 * @output Exports the public usePopover hook with derived focus and guarded opening.
 *   For Popover.tsx (internal), exports usePopoverInternal and
 *   FALLBACK_CLOSE_SELECTOR.
 * @position Higher-level layer utility; used by DatePicker, Combobox, etc.
 *
 * Combines popover layer behavior with focus trap for dialog-like popovers.
 * Use this for interactive popover content that should trap focus.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Popover/index.ts
 */

import React, {useCallback, useEffect, useRef, type ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import {useLayerInternal, type ContextRenderProps} from '../Layer/useLayer';
import {useFocusTrapInternal} from '../hooks/useFocusTrap';
import {LayerDepthProvider} from '../Layer/LayerDepthContext';
import type {StyleXStyles} from '@stylexjs/stylex';
import {
  colorVars,
  spacingVars,
  radiusVars,
  shadowVars,
} from '../theme/tokens.stylex';
import {Button} from '../Button';
import {
  FOCUSABLE_SELECTOR,
  isDisabledWithin,
  preferTabStops,
} from '../hooks/focusableSelector';
import {rtlStyles} from '../utils';
import {useDevWarning} from '../hooks/useDevWarning';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {mergeProps} from '../utils/mergeProps';
import {isFocusDetached} from '../utils/isFocusDetached';
import {themeProps} from '../utils/themeProps';
import {paddingStyles} from '../Layout/paddingStyles.stylex';
import type {SpacingStep} from '../utils/types';
import {stableClassName} from '../naming';
import {
  registerEnglishFallback,
  useComponentTranslator,
} from '../i18n/useComponentTranslator';
import english from '../i18n/generated-english/Popover/usePopover.generated';

registerEnglishFallback(english);

/**
 * The fallback close button's wrapper (anchored layer) or button (sheet,
 * Popover.tsx); initial focus skips it.
 */
export const FALLBACK_CLOSE_SELECTOR = '[data-astryx-popover-fallback-close]';

function attemptFocus(element: HTMLElement): boolean {
  try {
    element.focus();
  } catch {
    // Ignore non-focusable elements; the caller will try the next target.
  }
  // The element's own document: a popover rendered into a second document
  // (an iframe, a Picture-in-Picture window) never moves this one's focus.
  return element.ownerDocument.activeElement === element;
}

function focusFirstContentControl(container: HTMLElement): boolean {
  const focusable = preferTabStops(
    Array.from(
      container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR),
    ).filter(
      element =>
        element.closest(FALLBACK_CLOSE_SELECTOR) == null &&
        !isDisabledWithin(element, container),
    ),
  );
  for (const element of focusable) {
    if (attemptFocus(element)) {
      return true;
    }
  }
  return false;
}

const styles = stylex.create({
  // Default popover surface — background, radius, shadow.
  // Applied automatically unless hasSurface is false.
  // Consumers that need a raw positioned layer should use useLayer instead.
  surface: {
    backgroundColor: colorVars['--color-background-popover'],
    '--_popover-radius': radiusVars['--radius-container'],
    borderRadius: 'var(--_popover-radius)',
    boxShadow: shadowVars['--shadow-low'],
  },
  // Focus trap container. Shared :focus-visible styling keeps semantic focus
  // placement independent of pointer/keyboard indication.
  contentWrapper: {
    position: 'relative',
  },
  // Hidden close button wrapper - sr-only until focused, then positioned below
  // popover. Inline-axis centering (+ the translateY(100%) that drops it below
  // the surface) comes from rtlStyles.centerInline('100%') at the call site —
  // it centers correctly in both LTR and RTL.
  closeButtonWrapper: {
    position: 'absolute',
    bottom: 0,
    zIndex: 1,
    // sr-only by default
    width: {
      default: 1,
      ':focus-within': 'auto',
    },
    height: {
      default: 1,
      ':focus-within': 'auto',
    },
    overflow: {
      default: 'hidden',
      ':focus-within': 'visible',
    },
    clipPath: {
      default: 'inset(50%)',
      ':focus-within': 'none',
    },
    pointerEvents: {
      default: 'none',
      ':focus-within': 'auto',
    },
    paddingBlockStart: {
      default: 0,
      ':focus-within': spacingVars['--spacing-1'],
    },
  },
});

/**
 * Options for usePopover
 */
export interface UsePopoverOptions {
  /**
   * Callback fired when popover is shown.
   * Wrap in useCallback for stable identity.
   */
  onShow?: () => void;

  /**
   * Callback fired when popover is hidden.
   * Use this to return focus to the trigger element.
   * Wrap in useCallback for stable identity.
   */
  onHide?: () => void;

  /**
   * StyleX styles applied to the popover's content wrapper.
   * Merges after the surface styles (when hasSurface is true), so these
   * can override background, radius, etc.
   *
   * For styles on the layer's positioned element (e.g., animations using
   * `:popover-open`), pass `xstyle` via the `render()` call's props instead.
   */
  xstyle?: StyleXStyles;

  /**
   * Additional class name applied to the painted popover surface.
   */
  className?: string;

  /**
   * Inline styles applied to the painted popover surface.
   */
  style?: React.CSSProperties;

  /**
   * Whether clicking outside should dismiss the popover.
   * @default true
   */
  hasLightDismiss?: boolean;

  /**
   * Whether pressing Escape dismisses the popover.
   *
   * Takes effect together with `hasLightDismiss: false`: with light dismiss
   * on, the native popover uses `popover="auto"`, whose browser-level light
   * dismiss also closes on Escape, so Escape handling stays registered to
   * keep topmost-only dismissal intact. Set both to `false` for
   * explicit-dismiss-only surfaces like onboarding coachmarks.
   *
   * @default true
   */
  hasEscapeDismiss?: boolean;

  /**
   * Whether to automatically focus the first focusable element when opened.
   * @default true
   */
  hasAutoFocus?: 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;

  /**
   * Accessible label for the dialog.
   * Required for screen readers to announce the dialog purpose
   * (only applies when `role` is `'dialog'`).
   */
  dialogLabel?: string;

  /**
   * ARIA role stamped on the popover content wrapper.
   *
   * - `'dialog'` (default): the wrapper is a `role="dialog"` and, when
   *   `isModal` is true, carries `aria-modal`. Use for genuine dialog content.
   * - `'none'`: the wrapper carries no role or `aria-modal`, so the popup's own
   *   content role (e.g. a child `role="listbox"` or `role="menu"`) is the
   *   exposed semantics. Use for comboboxes, listboxes, and menus — their
   *   trigger keeps DOM focus, so announcing an unnamed modal dialog around
   *   them is incorrect.
   *
   * @default 'dialog'
   */
  role?: 'dialog' | 'none';

  /**
   * Whether the dialog is modal (`aria-modal`). Only applies when `role` is
   * `'dialog'`. Set to `false` for non-modal dialogs that do not inert the rest
   * of the page.
   *
   * @default true
   */
  isModal?: boolean;

  /**
   * Whether to apply the default popover surface (background, border-radius,
   * box-shadow) to the content wrapper.
   *
   * Set to false when the popover content provides its own surface styling
   * (e.g., mega menus with custom layouts). If you find yourself opting out,
   * consider whether useLayer is a better fit.
   *
   * @default true
   */
  hasSurface?: boolean;

  /**
   * Inner padding of the painted surface, using the spacing scale.
   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
   * `0` paints a flush surface for content that owns its own edges (a list of
   * rows, a header with a rule). Matches the `padding` prop on `Card`,
   * `Stack` and `Popover`.
   *
   * Applied to the surface itself — the box that paints background, radius
   * and elevation — so a theme's `padding` on the `popover` target replaces
   * it instead of nesting inside it. `xstyle` merges after it.
   *
   * Omit it and the surface paints no padding of its own (the hook's
   * historical behavior; `Popover` passes its own default).
   */
  padding?: SpacingStep;

  /**
   * Theme-target name stamped on the popup SURFACE — the element that paints
   * the background, radius and elevation — without the `astryx-` prefix
   * (e.g. `'complex-selector-popup'`).
   *
   * The surface is created here, not by the calling component, so a component
   * that wants its popup themeable cannot reach it on its own: a target it
   * renders itself lands on its content INSIDE the surface, where a background
   * or radius rule paints the wrong box. Name the surface through this option
   * and document the class in the component's `theming.targets`.
   *
   * The canonical `astryx-popover` target is always present alongside any
   * component-owned refinement target.
   */
  surfaceTarget?: string;
}

/**
 * Return type for usePopover
 */
export interface UsePopoverReturn {
  /**
   * Ref callback to attach to the trigger element.
   * Sets up CSS anchor positioning.
   */
  triggerRef: (el: HTMLElement | null) => void;

  /**
   * Ref for the popover content container (used internally for focus trapping).
   * You typically don't need to use this directly - the render function
   * automatically wraps content in a focus trap container.
   */
  contentRef: React.RefObject<HTMLDivElement | null>;

  /**
   * The CSS anchor name to use for positioning.
   * Use when you need to set anchorName manually (e.g., display:contents wrapper).
   * Set it only while the layer is shown or its exit animation runs.
   */
  anchorId: string;

  /**
   * Show the popover.
   * @param options.skipAutoFocus - If true, don't auto-focus the first element.
   *   Useful when triggered by mouse click on an input that should retain focus.
   */
  show: (options?: {skipAutoFocus?: boolean}) => void;

  /**
   * Hide the popover
   */
  hide: () => void;

  /**
   * Toggle the popover open/closed
   */
  toggle: () => void;

  /**
   * Whether the popover is currently open
   */
  isOpen: boolean;

  /**
   * Unique ID for aria-describedby or aria-controls
   */
  id: string;

  /**
   * Render function for popover content.
   * Automatically wraps content in a focus trap container with a hidden close button.
   *
   * @example
   * ```
   * {popover.render(
   *   <Calendar />,
   *   { placement: 'below', alignment: 'start' }
   * )}
   * ```
   */
  render: (children: ReactNode, props?: ContextRenderProps) => ReactNode;

  /**
   * ARIA attributes to spread on the trigger element
   */
  triggerProps: {
    'aria-haspopup': 'dialog' | 'true';
    'aria-expanded': boolean;
    'aria-controls': string;
  };
}

/**
 * Options a core component may pass through `usePopoverInternal`; not part
 * of the public `usePopover` options.
 */
interface InternalPopoverOptions extends UsePopoverOptions {
  /**
   * Runs as the popover starts to close, while the browser still shows it.
   * A close that plays out after the popover is hidden starts here.
   */
  onCloseStart?: () => void;
}

/**
 * Hook for creating popover dialogs with focus trapping.
 *
 * Combines:
 * - `useLayer` for popover positioning using CSS anchor positioning
 * - `useFocusTrap` for trapping focus within the popover content
 * - Auto-focus first element on open
 * - Escape key to close (configurable via hasEscapeDismiss)
 * - Hidden close button that reveals on focus for accessibility
 *
 * The render function automatically wraps your content in a focus trap container
 * and appends a hidden close button. The button appears at the end of the popover,
 * is visually hidden until focused, then shows a tooltip-like message (default: "Close popover").
 *
 * @example
 * ```
 * function DatePickerExample() {
 *   const inputRef = useRef<HTMLInputElement>(null);
 *   const popover = usePopover({
 *     onHide: () => inputRef.current?.focus(),
 *     closeButtonLabel: 'Close calendar',
 *   });
 *   return (
 *     <>
 *       <input ref={inputRef} />
 *       <button
 *         ref={popover.triggerRef}
 *         onClick={popover.toggle}
 *         {...popover.triggerProps}>
 *         Open Calendar
 *       </button>
 *       {popover.render(
 *         <Calendar />,
 *         { placement: 'below', alignment: 'start' }
 *       )}
 *     </>
 *   );
 * }
 * ```
 */
function usePopoverImplementation(
  options: InternalPopoverOptions = {},
): UsePopoverReturn {
  const {
    onShow,
    onHide,
    onCloseStart,
    xstyle,
    className,
    style,
    hasLightDismiss = true,
    hasEscapeDismiss = true,
    hasAutoFocus = true,
    hasSurface = true,
    padding,
    surfaceTarget,
    hasCloseButton = true,
    closeButtonLabel: closeButtonLabelFromProps,
    dialogLabel,
    role = 'dialog',
    isModal = true,
  } = options;

  const t = useComponentTranslator();
  const closeButtonLabel =
    closeButtonLabelFromProps ?? t('@astryx.popover.close');

  // Track the trigger element for returning focus
  const triggerElementRef = useRef<HTMLElement | null>(null);

  // Track whether to skip auto-focus for the current open event
  const skipAutoFocusRef = useRef(false);
  // Whether `show` focused a content control within the opening event.
  const hasFocusedInGestureRef = useRef(false);

  // Set when the layer reports it has shown, so `show` can tell a popover
  // that opened within the call from one whose content mounts later.
  const hasShownRef = useRef(false);
  const handleLayerShow = useCallback(() => {
    hasShownRef.current = true;
    onShow?.();
  }, [onShow]);

  // Core layer for popover positioning
  const layer = useLayerInternal({
    mode: 'context',
    lightDismiss: hasLightDismiss,
    onShow: handleLayerShow,
    onHide,
    onCloseStart,
  });

  // Focus trap for the popover content. Escape stays registered while light
  // dismiss is on (native popover="auto" closes on Escape regardless), so a
  // host Dialog keeps deferring to this trap instead of double-dismissing.
  // The element focused when `show` ran: initial focus may move inside before
  // the trap activates, so the trap restores focus here instead.
  const openerRef = useRef<HTMLElement | null>(null);
  const getRestoreTarget = useCallback(() => openerRef.current, []);
  const {containerRef: contentRef, focusFirst} =
    useFocusTrapInternal<HTMLDivElement>({
      isActive: layer.isOpen,
      onEscape: hasEscapeDismiss || hasLightDismiss ? layer.hide : undefined,
      getRestoreTarget,
    });

  const focusInitialTarget = useCallback(() => {
    const container = contentRef.current;
    if (!container) {
      return;
    }
    // Focus already on a control inside (set in `onShow`, or a press in the
    // content) is where the user or the caller wants it; moving it would
    // undo that.
    const active = container.ownerDocument.activeElement;
    if (active != null && active !== container && container.contains(active)) {
      return;
    }
    if (focusFirstContentControl(container)) {
      return;
    }
    if (role === 'dialog') {
      attemptFocus(container);
      return;
    }
    focusFirst();
  }, [contentRef, focusFirst, role]);

  // Auto-focus first element when popover opens (unless skipped)
  useEffect(() => {
    // Reset the per-open focus preference after the popover closes.
    if (!layer.isOpen) {
      skipAutoFocusRef.current = false;
      hasFocusedInGestureRef.current = false;
      return;
    }
    if (hasAutoFocus && !skipAutoFocusRef.current) {
      // Wait a frame so the content is mounted. A popover that closes or
      // unmounts first cancels it: the frame would otherwise move focus into
      // content that is no longer shown, after the close had left it alone.
      const frame = requestAnimationFrame(() => {
        const doc = contentRef.current?.ownerDocument ?? document;
        if (hasFocusedInGestureRef.current && !isFocusDetached(doc)) {
          return;
        }
        focusInitialTarget();
      });
      return () => cancelAnimationFrame(frame);
    }
  }, [layer.isOpen, hasAutoFocus, focusInitialTarget, contentRef]);

  // Combined ref for trigger element (layer anchor + our ref). It is keyed on
  // the layer's own ref, not the whole layer: the layer object changes with
  // every new onShow or onHide, and a trigger ref that changed with it made
  // React detach and reattach the trigger on every render. It reads nothing
  // else from the layer, and layer.ref (useLayer's contextRef) reads only refs
  // and its anchor name and anchor-clearance option, so nothing in it goes
  // stale.
  const layerRef = layer.ref;
  const triggerRef = useCallback(
    (el: HTMLElement | null) => {
      triggerElementRef.current = el;
      layerRef(el);
    },
    [layerRef],
  );

  // Show function with optional focus preservation
  const show = useCallback(
    (showOptions?: {skipAutoFocus?: boolean}) => {
      skipAutoFocusRef.current = showOptions?.skipAutoFocus ?? false;
      hasShownRef.current = false;
      const activeElement = (
        triggerElementRef.current?.ownerDocument ?? document
      ).activeElement as HTMLElement | null;
      openerRef.current =
        activeElement != null && !contentRef.current?.contains(activeElement)
          ? activeElement
          : null;
      layer.show();
      // When the content is already mounted, the layer shows it within this
      // call, so initial focus lands within the event that opened it: iOS
      // raises its keyboard only for a focus made while the tap is still
      // being handled. The frame in the effect above stays for content that
      // mounts later.
      // Only a content control already rendered takes focus here; content
      // that renders on open (and the dialog-surface fallback) waits for the
      // effect's frame.
      const container = contentRef.current;
      if (
        hasShownRef.current &&
        hasAutoFocus &&
        !skipAutoFocusRef.current &&
        container != null &&
        !container.contains(container.ownerDocument.activeElement) &&
        focusFirstContentControl(container)
      ) {
        // Initial focus is done. The effect's frame stays only as a fallback
        // for focus lost to the page (content swapped in the same handler
        // unmounts the control just focused); it must not move focus the user
        // has since moved elsewhere.
        hasFocusedInGestureRef.current = true;
      }
    },
    [layer, hasAutoFocus, contentRef],
  );

  // Toggle function. Opening delegates to show so every route inherits the
  // same-gesture reopen guard owned by Layer.
  const toggle = useCallback(() => {
    if (layer.isOpen) {
      layer.hide();
    } else {
      show();
    }
  }, [layer, show]);

  // ARIA attributes for the trigger
  const triggerProps = {
    'aria-haspopup':
      role === 'dialog' ? ('dialog' as const) : ('true' as const),
    'aria-expanded': layer.isOpen,
    'aria-controls': layer.id,
  };

  // Dev-time guardrail: a dialog popover should always be labeled.
  useDevWarning(
    'usePopover',
    'role="dialog" without a `dialogLabel` renders an unnamed ' +
      'dialog. Pass `dialogLabel`, or use `role: "none"` for listbox/menu ' +
      'popups whose content already carries its own role.',
    role === 'dialog' && !dialogLabel,
  );

  const isDialogShown = role === 'dialog' && layer.isOpen;
  // Wrapped render function that includes surface styles and optional hidden close button
  const render = useCallback(
    (children: ReactNode, props?: ContextRenderProps): ReactNode => {
      // `mergeProps` is positional — a third OBJECT argument is read as
      // `style`, not as more props — so the surface's classes are composed
      // into one props object before merging with the StyleX result.
      const surfaceProps = themeProps('popover');
      const surfaceClassName =
        surfaceTarget != null && surfaceTarget !== 'popover'
          ? `${surfaceProps.className} ${stableClassName(surfaceTarget)}`
          : surfaceProps.className;

      return layer.render(
        <LayerDepthProvider>
          <div
            ref={contentRef}
            // A closed surface stays mounted but hidden. It carries no dialog
            // role or name, so selectors find no hidden dialog.
            role={isDialogShown ? 'dialog' : undefined}
            aria-modal={isDialogShown && isModal ? true : undefined}
            aria-label={isDialogShown ? dialogLabel : undefined}
            tabIndex={role === 'dialog' ? -1 : undefined}
            {...mergeProps(
              {...surfaceProps, className: surfaceClassName},
              focusOutlineProps.focusVisible(
                styles.contentWrapper,
                hasSurface && styles.surface,
                padding != null && paddingStyles[padding],
                xstyle,
              ),
              className,
              style,
            )}>
            {children}
            {hasCloseButton && (
              <div
                data-astryx-popover-fallback-close=""
                {...stylex.props(
                  styles.closeButtonWrapper,
                  rtlStyles.centerInline('100%'),
                )}>
                <Button
                  variant="secondary"
                  label={closeButtonLabel}
                  onClick={layer.hide}
                />
              </div>
            )}
          </div>
        </LayerDepthProvider>,
        {...props, xstyle: props?.xstyle},
      );
    },
    [
      layer,
      hasCloseButton,
      hasSurface,
      padding,
      surfaceTarget,
      className,
      style,
      closeButtonLabel,
      contentRef,
      dialogLabel,
      isDialogShown,
      role,
      isModal,
      xstyle,
    ],
  );

  return {
    triggerRef,
    contentRef,
    anchorId: layer.anchorId,
    show,
    hide: layer.hide,
    toggle,
    isOpen: layer.isOpen,
    id: layer.id,
    render,
    triggerProps,
  };
}

export function usePopover(options: UsePopoverOptions = {}): UsePopoverReturn {
  return usePopoverImplementation(options);
}

/**
 * @internal For Popover; not exported from the package barrel.
 */
export function usePopoverInternal(
  options: InternalPopoverOptions = {},
): UsePopoverReturn {
  return usePopoverImplementation(options);
}