Skip to content

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

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

'use client';

/**
 * @file Dialog.tsx
 * @input Uses React, DialogHTMLAttributes, ReactNode, container (Layout), DialogContext, layerTextReset,
 *   layerStructureReset, modalOutlet, interactionModality, chainEventHandlers, holdEntranceInput
 * @output Exports Dialog component, DialogProps, DialogVariant, DialogPurpose types
 * @position Core implementation; consumed by index.ts, tested by Dialog.test.tsx
 *
 * The standard variant treats `width` as the preferred surface width, then
 * clamps it to the dynamic viewport with spacing-token gutters so narrow
 * viewports keep content and controls on screen without changing the public API.
 * Fullscreen dialogs add safe-area protection to the default padding fallback
 * while preserving explicit prop/theme padding overrides, and fade in without
 * the centered-dialog translate/scale motion.
 * Initial focus is applied after showModal; an explicit descendant request
 * takes priority over a header's default title request.
 *
 * Under reduced motion the entrance never travels or scales
 * (docs/design/reduced-motion.md): on a touch screen the dialog fades in
 * where it lands, in 200 ms or less; with a mouse it appears at once.
 *
 * Initial focus and the focus returned on close follow the last input
 * (docs/architecture/interaction-modality.md INV1): the shared focus indicator
 * is hidden after a pointer press and shown after a key press.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/Dialog/Dialog.doc.mjs (props table, features, implementation notes)
 * - /packages/core/src/Dialog/Dialog.test.tsx (tests for new/changed behavior)
 * - /packages/core/src/Dialog/__tests__/DialogTouchEntrance.interaction.browser.spec.ts (the touch entrance hold)
 * - /packages/core/src/Dialog/index.ts (exports if types change)
 * - /apps/storybook/stories/Dialog.stories.tsx (storybook stories)
 * - /packages/cli/assets/templates/blocks/components/Dialog/ (showcase blocks)
 */

import {
  useCallback,
  useEffect,
  useId,
  useLayoutEffect,
  useMemo,
  useRef,
  useState,
  type ReactNode,
} from 'react';
import {useIsHydrating} from '../hooks/useIsHydrating';
import {useSettledOpen} from '../hooks/useSettledOpen';
import type {BaseProps} from '../BaseProps';
import * as stylex from '@stylexjs/stylex';
import {useScrollLock} from '../hooks/useScrollLock';
import {layerTextReset} from '../Layer/layerTextReset.stylex';
import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
import {LayerContentBoundary} from '../Layer/layerScopedContext';
import {layerClickBoundary} from '../Layer/layerClickBoundary';
import {LayerDepthProvider} from '../Layer/LayerDepthContext';
import {holdEntranceInput} from '../Layer/holdEntranceInput';
import {useLayerDismissal} from '../Layer/useLayerDismissal';
import {useBackdropPress} from '../Layer/useBackdropPress';
import {useFocusRegionContainment} from '../hooks/useFocusTrap';
import {useModalOutlet} from '../Layer/modalOutlet';
import {
  colorVars,
  radiusVars,
  durationVars,
  easeVars,
  shadowVars,
  spacingVars,
} from '../theme/tokens.stylex';
import {container} from '../Layout/container.stylex';
import {containerCornerStyles} from '../Layout/containerCorners.stylex';
import type {SpacingToken} from '../Layout/container.stylex';
import {
  paddingStyles,
  containerPaddingInlineVarStyles,
  containerPaddingBlockStartVarStyles,
  containerPaddingBlockEndVarStyles,
  spacingStepToToken,
  overlayPaddingReset,
} from '../Layout/padding.stylex';
import type {SpacingStep} from '../utils/types';
import {mergeProps} from '../utils/mergeProps';
import {chainEventHandlers} from '../utils/chainEventHandlers';
import {createDevWarnings} from '../utils/devWarning';
import {DialogContext} from './DialogContext';
import {themeProps} from '../utils/themeProps';
import type {DialogVariantMap} from './index';
import {focusOutlineProps} from '../utils/focusOutline.stylex';
import {useInteractionModalityTracking} from '../utils/interactionModality';
import {
  focusForLastInput,
  prepareFocusReturnOnRemoval,
  returnFocusForLastInput,
} from '../utils/focusReturn';
import {ModalAnnounceProvider} from '../hooks/ModalAnnounceProvider';

import {useMergedRefs} from '../hooks/useMergedRefs';

type PointerHandler = (event: React.PointerEvent<HTMLDialogElement>) => void;
/**
 * Calculate a directional translate offset for dialog entry animation.
 * Returns a normalized vector from the trigger element toward the viewport
 * center, scaled to the given distance.
 */
function getDialogDirection(
  triggerEl: HTMLElement,
  distance = 16,
): {x: number; y: number} {
  const rect = triggerEl.getBoundingClientRect();
  // The trigger's own window: its rect is measured in that window's viewport,
  // which is not the page's when the dialog renders into a second document.
  const view = triggerEl.ownerDocument.defaultView ?? window;
  const dx = rect.left + rect.width / 2 - view.innerWidth / 2;
  const dy = rect.top + rect.height / 2 - view.innerHeight / 2;
  const dist = Math.sqrt(dx * dx + dy * dy) || 1;
  return {
    x: Math.round((dx / dist) * distance),
    y: Math.round((dy / dist) * distance),
  };
}

/**
 * Dialog variant type
 * - standard: Normal dialog with configurable width/height
 * - fullscreen: Takes up the entire viewport
 *
 * Extensible via module augmentation of DialogVariantMap.
 */
export type DialogVariant = keyof DialogVariantMap;

/**
 * Dialog purpose type - controls dismissal behavior
 * - required: Mandatory flows (security, permissions) - disables all exit methods
 * - form: User forms/flows - prevents backdrop click, allows escape
 * - info: Informational flows - allows all exit methods
 */
export type DialogPurpose = 'required' | 'form' | 'info';

/** Block-axis offsets — always allowed, independent of inline direction. */
interface DialogBlockPosition {
  top?: number | string;
  bottom?: number | string;
}

/**
 * Static position for a dialog. The inline axis is logical XOR physical — the
 * type forbids mixing the two, so a single dialog can't be positioned both ways:
 * - Logical `start`/`end` map to `inset-inline-*` and mirror under RTL (preferred).
 * Block-axis `top`/`bottom` may be combined with either.
 */
export interface DialogPosition extends DialogBlockPosition {
  /** Logical inline-start offset (`inset-inline-start`); mirrors under RTL. */
  start?: number | string;
  /** Logical inline-end offset (`inset-inline-end`); mirrors under RTL. */
  end?: number | string;
}

const enterDirectional = stylex.keyframes({
  from: {
    opacity: 0,
    transform:
      'translate(var(--dialog-dir-x, 0px), var(--dialog-dir-y, 16px)) scale(0.95)',
  },
  to: {opacity: 1, transform: 'translate(0, 0) scale(1)'},
});

const enterFullscreen = stylex.keyframes({
  from: {opacity: 0},
  to: {opacity: 1},
});

const dialogFullscreenSafeAreaBlockStartPadding = `var(--astryx-dialog-padding-block-start, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-top, 0px))))`;
const dialogFullscreenSafeAreaBlockEndPadding = `var(--astryx-dialog-padding-block-end, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-bottom, 0px))))`;
const dialogFullscreenSafeAreaInlineStartPaddingLtr = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;
const dialogFullscreenSafeAreaInlineStartPaddingRtl = `var(--astryx-dialog-padding-inline-start, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
const dialogFullscreenSafeAreaInlineEndPaddingLtr = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-right, 0px)))))`;
const dialogFullscreenSafeAreaInlineEndPaddingRtl = `var(--astryx-dialog-padding-inline-end, var(--astryx-dialog-padding-inline, var(--astryx-dialog-padding, max(${spacingVars['--spacing-4']}, env(safe-area-inset-left, 0px)))))`;

/** @internal Verified by Dialog.test.tsx; not re-exported from the package entry point. */
export const dialogFullscreenSafeAreaPaddingContract = {
  blockStart: dialogFullscreenSafeAreaBlockStartPadding,
  blockEnd: dialogFullscreenSafeAreaBlockEndPadding,
  inlineStart: {
    ltr: dialogFullscreenSafeAreaInlineStartPaddingLtr,
    rtl: dialogFullscreenSafeAreaInlineStartPaddingRtl,
  },
  inlineEnd: {
    ltr: dialogFullscreenSafeAreaInlineEndPaddingLtr,
    rtl: dialogFullscreenSafeAreaInlineEndPaddingRtl,
  },
} as const;

/**
 * Dialog styles using native <dialog> element
 * Uses ::backdrop pseudo-element for overlay
 */
const styles = stylex.create({
  dialog: {
    position: 'fixed',
    margin: 'auto',
    padding: 0,
    // The backdrop does not blur the page. Forced colors override the
    // backdrop's colour, so a 1px border keeps the modal separate from the
    // page. It is a border, not an outline: the focus ring
    // (focusOutlineProps) owns the outline longhands on this element.
    borderWidth: {
      default: 0,
      '@media (forced-colors: active)': 1,
    },
    borderStyle: {
      default: 'none',
      '@media (forced-colors: active)': 'solid',
    },
    borderColor: {
      default: null,
      '@media (forced-colors: active)': 'CanvasText',
    },
    backgroundColor: colorVars['--color-background-surface'],
    '--_dialog-radius': radiusVars['--radius-container'],
    borderRadius: 'var(--_dialog-radius)',
    boxShadow: shadowVars['--shadow-high'],
    display: 'none',
    flexDirection: 'column',
    height: 'fit-content',
    overscrollBehavior: 'contain',
    opacity: 0,
    // Under reduced motion on a touch screen the entrance is the shared
    // reduced-motion cross-fade, 200 ms on easeInOut whatever the theme's
    // duration (design:reduced-motion DR2, DR4). Moves to
    // reducedMotionFadeConsts once that is on main.
    animationDuration: {
      default: durationVars['--duration-medium-max'],
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)': '200ms',
    },
    animationTimingFunction: {
      default: easeVars['--ease-standard'],
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
        'cubic-bezier(0.42, 0, 0.58, 1)',
    },
    animationFillMode: 'backwards' as const,
  },
  // Applied via isOpen prop — avoids :where([open]) attribute selectors
  // which have zero specificity and can lose to default styles depending
  // on CSS source order in the build output.
  open: {
    display: 'flex',
    opacity: 1,
    // Under `prefers-reduced-motion: reduce` the dialog never travels or
    // scales in (design:reduced-motion DR1): on a touch screen it fades in
    // where it lands (DR2), and with a mouse it appears at once (DR3).
    animationName: {
      default: enterDirectional,
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
        enterFullscreen,
      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
        'none',
    },
  },
  // A dialog present on page load opens where it rests (spec:AST-013 FR13).
  openSettled: {
    animationName: 'none',
  },
  // No backdrop-filter: a full-viewport blur is costly to repaint.
  backdrop: {
    '::backdrop': {
      backgroundColor: colorVars['--color-overlay'],
    },
  },
  fullscreen: {
    width: '100dvw',
    height: '100dvh',
    maxWidth: '100dvw',
    maxHeight: '100dvh',
    '--_dialog-radius': '0px',
    borderRadius: 0,
    // Nothing of the page shows around a full-screen dialog: no edge.
    borderWidth: 0,
    margin: 0,
    inset: 0,
  },
  fullscreenOpen: {
    animationName: {
      default: enterFullscreen,
      '@media (prefers-reduced-motion: reduce) and (pointer: coarse)':
        enterFullscreen,
      '@media (prefers-reduced-motion: reduce) and (not (pointer: coarse))':
        'none',
    },
  },
  fullscreenSafeArea: {
    paddingBlockStart: dialogFullscreenSafeAreaBlockStartPadding,
    paddingBlockEnd: dialogFullscreenSafeAreaBlockEndPadding,
    paddingInlineStart: {
      default: dialogFullscreenSafeAreaInlineStartPaddingLtr,
      ':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineStartPaddingRtl,
    },
    paddingInlineEnd: {
      default: dialogFullscreenSafeAreaInlineEndPaddingLtr,
      ':is([dir="rtl"] *)': dialogFullscreenSafeAreaInlineEndPaddingRtl,
    },
  },
  inner: {
    display: 'flex',
    flexDirection: 'column',
    flex: '1 1 auto',
    minHeight: 0,
    overflow: 'hidden',
    borderRadius: 'inherit',
  },
  innerCorners: {
    '--_container-corner-block-start': 'var(--_dialog-radius)',
    '--_container-corner-block-end': 'var(--_dialog-radius)',
  },
  // Inline wrapper mirrors the dialog's visual styles without <dialog> behavior
  inlineWrapper: {
    padding: 0,
    borderWidth: 0,
    borderStyle: 'none',
    backgroundColor: colorVars['--color-background-surface'],
    '--_dialog-radius': radiusVars['--radius-container'],
    borderRadius: 'var(--_dialog-radius)',
    boxShadow: shadowVars['--shadow-high'],
    display: 'flex',
    flexDirection: 'column',
    height: 'fit-content',
    overscrollBehavior: 'contain',
  },
});

const STANDARD_DIALOG_VIEWPORT_GUTTER = spacingVars['--spacing-4'];
const STANDARD_DIALOG_VIEWPORT_MAX_WIDTH = `calc(100dvw - ${STANDARD_DIALOG_VIEWPORT_GUTTER} - ${STANDARD_DIALOG_VIEWPORT_GUTTER})`;
const STANDARD_DIALOG_MAX_WIDTH = `min(100%, ${STANDARD_DIALOG_VIEWPORT_MAX_WIDTH})`;

function formatSizeValue(value: number | string): string {
  return typeof value === 'number' ? `${value}px` : value;
}

function resolveDialogSizing(
  width: number | string,
  maxHeight: number | string,
) {
  return {
    width: formatSizeValue(width),
    maxWidth: STANDARD_DIALOG_MAX_WIDTH,
    maxHeight: formatSizeValue(maxHeight),
  };
}

const dynamicStyles = stylex.create({
  sizing: (width: string, maxWidth: string, maxHeight: string) => ({
    width,
    maxWidth,
    maxHeight,
  }),
  position: (
    top: string,
    insetInlineStart: string,
    insetInlineEnd: string,
    bottom: string,
  ) => ({
    // Assigns pre-resolved offsets from resolveDialogPositionOffsets(). This
    // literal has no logic — StyleX can't analyze a helper, so the values
    // (logical start/end → inset-inline-*, physical left/right, `auto`
    // fallbacks) are computed at the call site and passed in.
    margin: 0,
    top,
    insetInlineStart,
    insetInlineEnd,
    bottom,
  }),
});

/**
 * Format position value - numbers become pixels, strings pass through, undefined becomes null
 */
function formatPosition(value: number | string): string {
  return typeof value === 'number' ? `${value}px` : value;
}

/**
 * Map a {@link DialogPosition} to resolved CSS offsets. Logical `start`/`end`
 * become `inset-inline-*` (mirror under RTL); each unset offset falls back to
 * `auto`.
 *
 * Not re-exported from the package; internal to Dialog. Directly unit-tested
 * so the mapping is verified without StyleX class compilation.
 *
 * @see DialogPosition
 */
export function resolveDialogPositionOffsets(position: DialogPosition) {
  const {top, bottom, start, end} = position;

  return {
    top: top !== undefined ? formatPosition(top) : 'auto',
    bottom: bottom !== undefined ? formatPosition(bottom) : 'auto',
    // Logical offsets mirror under RTL (preferred replacements).
    insetInlineStart: start !== undefined ? formatPosition(start) : 'auto',
    insetInlineEnd: end !== undefined ? formatPosition(end) : 'auto',
  };
}

export interface DialogProps extends BaseProps<HTMLDialogElement> {
  /** Ref forwarded to the root element */
  ref?: React.Ref<HTMLDialogElement>;
  /**
   * Whether the dialog is open.
   */
  isOpen: boolean;

  /**
   * Renders dialog content inline without the <dialog> element, backdrop,
   * modal behavior, or dialog-managed autofocus. Intended for documentation
   * previews and showcases only — not for production UIs. The dialog will not
   * trap focus or respond to Escape.
   * @default false
   */
  isInline?: boolean;

  /**
   * Callback fired when the dialog visibility changes.
   * Called with `false` when the dialog requests to be hidden.
   * Behavior depends on the `purpose` prop:
   * - required: Never called automatically
   * - form: Called on Escape key only
   * - info: Called on Escape key and backdrop click
   */
  onOpenChange: (isOpen: boolean) => unknown;

  /**
   * The width of the dialog.
   * Numbers are treated as pixels, strings are used as-is.
   * Ignored when variant is 'fullscreen'.
   * @default 400
   */
  width?: number | string;

  /**
   * The maximum height of the dialog.
   * The actual height will be the height of its content.
   * Numbers are treated as pixels, strings are used as-is.
   * Ignored when variant is 'fullscreen'.
   * @default '75dvh'
   */
  maxHeight?: number | string;

  /**
   * Static position for the dialog on screen.
   * By default, the dialog will be centered.
   * Ignored when variant is 'fullscreen'.
   */
  position?: Readonly<DialogPosition>;

  /**
   * The variant of the dialog.
   * - standard: Normal dialog with configurable dimensions
   * - fullscreen: Takes up the entire viewport
   * @default 'standard'
   */
  variant?: DialogVariant;

  /**
   * Configures how the dialog enables dismissals.
   * - required: Disables all exit methods (for mandatory flows)
   * - form: Prevents backdrop click, allows Escape key
   * - info: Allows all exit methods (Escape and backdrop click)
   * @default 'info'
   */
  purpose?: DialogPurpose;

  /**
   * Internal padding of the dialog using the spacing scale.
   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
   * When omitted, uses the theme default for dialogs.
   */
  padding?: SpacingStep;

  /**
   * The content of the dialog.
   * Typically an Layout with header, content, and footer slots.
   */
  children: ReactNode;
}

/**
 * A dialog component using the native <dialog> element.
 *
 * Designed to be used with Layout as its child for structured content.
 * Uses the browser's built-in modal behavior for optimal accessibility.
 * When a DialogHeader is rendered inside, its title automatically names the
 * dialog via aria-labelledby; pass `aria-label` or `aria-labelledby` to
 * override.
 *
 * @example
 * ```
 * const [isOpen, setIsOpen] = useState(false);
 * <Dialog isOpen={isOpen} onOpenChange={open => setIsOpen(open)}>
 *   <Layout
 *     header={<DialogHeader title="Title" onOpenChange={open => setIsOpen(open)} />}
 *     content={<LayoutContent>Content</LayoutContent>}
 *     footer={<LayoutFooter hasDivider>Actions</LayoutFooter>}
 *   />
 * </Dialog>
 * ```
 */
export function Dialog({
  isOpen: isOpenProp,
  isInline = false,
  onOpenChange,
  width = 400,
  maxHeight = '75dvh',
  position,
  variant = 'standard',
  purpose = 'info',
  padding,
  children,
  xstyle,
  className,
  style,
  ref,
  ...props
}: DialogProps) {
  // A modal dialog open on the server renders closed until hydration, and
  // opens in the render after it, the first one that can call showModal(): a
  // <dialog> painted open with aria-modal before it is modal claims a state it
  // does not have, over a live page (FR8). An inline dialog is not modal and
  // renders as it is.
  const isHydrating = useIsHydrating();
  const isOpen = isOpenProp && (isInline || !isHydrating);
  // A dialog open on the server was present on page load, so it opens settled,
  // with no entry motion; its later opens animate as usual (spec:AST-013 FR13).
  const [settledOpen] = useSettledOpen(isOpenProp && !isInline, isOpen, false);
  const opensSettled = settledOpen && isOpen;
  // When no explicit padding prop, use theme default (--astryx-dialog-padding)
  const useThemeDefault = padding == null;
  const effectivePadding = padding ?? 4;
  const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;

  const isFullscreen = variant === 'fullscreen';
  const standardSizing = isFullscreen
    ? null
    : resolveDialogSizing(width, maxHeight);

  // Default accessible name: publish a title id through DialogContext so a
  // DialogHeader applies it to its heading (mirrors AlertDialog's explicit
  // useId wiring). Whether to emit the default aria-labelledby is decided
  // imperatively in the callback ref below by checking whether the title
  // element actually rendered — so a dialog with no header never points at a
  // missing id, and we avoid the extra render a registration-via-state effect
  // would cost at the dialog level.
  const titleId = useId();

  // Consumer-provided labels always win over the DialogHeader default.
  const hasConsumerName =
    props['aria-label'] != null || props['aria-labelledby'] != null;

  const dialogRef = useRef<HTMLDialogElement>(null);
  // Native showModal() lets Tab leave for the browser's own UI, so the shared
  // module wraps it. An inline preview is not modal and contains nothing.
  useFocusRegionContainment(dialogRef, isOpen && !isInline);

  // Callback ref on the <dialog>: sync the default aria-labelledby from the
  // DialogHeader title (if one rendered) in the same commit, with no second
  // render. Consumer aria-label/aria-labelledby win — when present we leave
  // the attribute to the {...safeProps} spread and never touch it here.
  const attachDialog = useCallback(
    (node: HTMLDialogElement | null) => {
      dialogRef.current = node;
      if (!node || hasConsumerName) {
        return;
      }
      const hasTitle = node.querySelector(`#${CSS.escape(titleId)}`) != null;
      if (hasTitle) {
        node.setAttribute('aria-labelledby', titleId);
      } else {
        node.removeAttribute('aria-labelledby');
      }
    },
    [titleId, hasConsumerName],
  );

  // A composed header whose title renders after the dialog mounted asks the
  // dialog to look for the title again.
  const syncDefaultName = useCallback(() => {
    if (dialogRef.current != null) {
      attachDialog(dialogRef.current);
    }
  }, [attachDialog]);

  const dialogContextValue = useMemo(
    () => ({isInline, titleId, syncDefaultName}),
    [isInline, titleId, syncDefaultName],
  );

  // Input in a second document (a same-origin iframe, a Document
  // Picture-in-Picture window) never reaches the page's listeners, so the
  // dialog's own document keeps its own last input for the focus return while
  // this Dialog is mounted, from before it opens until it unmounts.
  const {ref: modalityRef} = useInteractionModalityTracking();

  const mergedDialogRef = useMergedRefs(ref, attachDialog, modalityRef);

  // Capture the element that was focused when the dialog opened, for
  // directional animation origin and focus restoration on close.
  const triggerElementRef = useRef<HTMLElement | null>(null);

  // This runs in a layout effect so the capture lands before any descendant's
  // passive mount effect: all layout effects run before any passive effect,
  // while a child's passive effect runs before this parent's passive effect.
  // Content that mounts in the open commit — e.g. a DialogHeader focusing its
  // own title on mount — would otherwise move document.activeElement inside
  // the dialog before the capture ran, and closing would then restore focus
  // to a detached node, stranding the user's focus on <body>.
  //
  // Only the closed-to-open edge captures. StrictMode replays this effect
  // after the open commit's passive effects. By then Dialog has focused the
  // title, so a replayed capture would take the title as the opener. The ref
  // survives the replay. It starts false, so a dialog first mounted open still
  // captures.
  const wasOpenRef = useRef(false);
  useLayoutEffect(() => {
    const isOpenNow = !isInline && isOpen;
    if (isOpenNow && !wasOpenRef.current) {
      // The dialog's own document while it holds focus: an app can render a
      // dialog into a second document (a same-origin iframe, a Document
      // Picture-in-Picture window) through a portal, and a control there that
      // opens it is focused in that document, which the page's document reports
      // only as the iframe element, or not at all. A control in the page that
      // opens such a dialog leaves focus in the page.
      const dialogDocument = dialogRef.current?.ownerDocument ?? document;
      const doc = dialogDocument.hasFocus() ? dialogDocument : document;
      triggerElementRef.current = doc.activeElement as HTMLElement | null;
    }
    wasOpenRef.current = isOpenNow;
  }, [isOpen, isInline]);

  // Derive dismissal behavior from purpose
  const allowEscape = purpose !== 'required';
  const allowBackdropClick = purpose === 'info';

  // Syncs the native dialog with `isOpen` through `showModal()` and `close()`.
  // An inline dialog is not in the top layer, so it skips this.
  useEffect(() => {
    if (isInline) {
      return;
    }
    const dialog = dialogRef.current;
    if (!dialog) {
      return;
    }

    if (isOpen) {
      // Set directional CSS custom properties before opening. The trigger was
      // captured by the layout effect above, before any descendant effect
      // could move focus.
      const trigger = triggerElementRef.current;
      if (trigger && trigger !== trigger.ownerDocument.body) {
        const dir = getDialogDirection(trigger);
        dialog.style.setProperty('--dialog-dir-x', `${dir.x}px`);
        dialog.style.setProperty('--dialog-dir-y', `${dir.y}px`);
      } else {
        dialog.style.setProperty('--dialog-dir-x', '0px');
        dialog.style.setProperty('--dialog-dir-y', '16px');
      }

      if (!dialog.open) {
        dialog.showModal();
        // React's autoFocus calls .focus() during commit, before showModal()
        // makes the dialog visible, so the focus silently fails.
        // Explicit descendant intent takes priority over a header's default
        // title. Keep the marker private to the focus-owning components.
        const autofocusTargets = [
          ...dialog.querySelectorAll<HTMLElement>(
            '[data-autofocus]:not([data-autofocus="dialog-title"])',
          ),
          ...dialog.querySelectorAll<HTMLElement>(
            '[data-autofocus="dialog-title"]',
          ),
        ];
        for (const target of autofocusTargets) {
          // Only hiding inside the dialog makes a request ineligible: the
          // modal dialog is not part of an inert region around it.
          const hiddenAncestor = target.closest(
            '[hidden], [inert], [aria-hidden="true"]',
          );
          if (hiddenAncestor != null && dialog.contains(hiddenAncestor)) {
            continue;
          }
          // Disabled and CSS-hidden targets cannot receive focus in the
          // browser. If a request cannot land, try the next eligible request
          // and finally the title; otherwise preserve native initial focus.
          // The dialog's own document reports its focus, also when the dialog
          // renders in an iframe or a Picture-in-Picture window.
          focusForLastInput(target);
          if (target.ownerDocument.activeElement === target) {
            break;
          }
        }
      }
      // Under a coarse primary pointer, a tap or a drag during the entrance
      // reaches nothing. Keys and assistive technology stay live. The hold
      // ends with the entrance, or with this effect's cleanup on a close or
      // unmount.
      return holdEntranceInput(dialog) ?? undefined;
    } else {
      if (dialog.open) {
        dialog.close();
      }
      // Return focus to the element that opened the dialog, with the ring
      // the last input in that element's own document calls for.
      const trigger = triggerElementRef.current;
      if (trigger) {
        returnFocusForLastInput(trigger);
      }
      triggerElementRef.current = null;
    }
  }, [isOpen, isInline]);

  // A dialog that unmounts while open (rendered only while open, or removed
  // with the rest of a view) never runs the close branch above. Focus the
  // removal lost goes back to the opener.
  useEffect(() => {
    const dialog = dialogRef.current;
    if (isInline || dialog == null) {
      return;
    }
    const returnFocusOnRemoval = prepareFocusReturnOnRemoval(dialog);
    return () => returnFocusOnRemoval(triggerElementRef.current);
  }, [isInline]);

  // Host app-global surfaces (toasts) inside this modal while it is open, so
  // they stay visible and operable above it.
  const outletRef = useModalOutlet(dialogRef, isOpen && !isInline);

  // Lock body scroll when dialog is open (iOS Safari workaround)
  // Skip for inline rendering — no modal overlay to compensate for.
  useScrollLock(isOpen && !isInline);

  // Join the shared layer dismissal stack. The stack owns the Escape listener
  // and routes each press to the top-most layer, so this dialog does not listen
  // itself — that is what stops a modal opened from inside another modal (or a
  // popover opened inside this one) from closing two layers on one press.
  //
  // A `required` dialog registers as `block`: it must not be dismissed, and the
  // press must not fall through and dismiss a layer behind it either.
  //
  // Inline mode opts out — it renders dialog content in normal flow, with
  // nothing layered over anything.
  const {shouldDismissOnCloseRequest} = useLayerDismissal({
    isActive: isOpen,
    isEnabled: !isInline,
    escapeBehavior: allowEscape ? 'close' : 'block',
    onDismiss: () => {
      onOpenChange(false);
    },
    // The dialog's document is this layer's: rendered into an iframe or a
    // Picture-in-Picture window, it ranks with the layers opened inside it.
    getContainer: () => dialogRef.current,
  });

  // Dev-time guardrail: an open modal should always have an accessible name.
  // The header-title check reads the DOM, so this stays in an effect.
  const [warn] = useState(createDevWarnings);
  useEffect(() => {
    const hasHeaderTitle =
      dialogRef.current?.querySelector(`#${CSS.escape(titleId)}`) != null;
    if (isOpen && !isInline && !hasConsumerName && !hasHeaderTitle) {
      warn(
        'Dialog',
        'open dialog has no accessible name. Add a DialogHeader ' +
          'with a `title`, or pass `aria-label`/`aria-labelledby`.',
      );
    }
  }, [isOpen, isInline, hasConsumerName, titleId, warn]);

  // A press on the ::backdrop targets the <dialog> itself, so native browser
  // popups (date pickers, selects, color pickers) that render outside the
  // dialog's rect never count. The press must start and end there.
  const handleBackdropPress = useCallback(() => {
    onOpenChange(false);
  }, [onOpenChange]);
  const backdropPress = useBackdropPress(
    handleBackdropPress,
    allowBackdropClick,
  );

  // The native `cancel` event is the browser's own close-watcher firing: an
  // Android back gesture, or a close request the stack never saw a press for.
  // Escape presses the stack owns never arrive here — it preventDefault()s
  // those, which suppresses the close watcher.
  //
  // A `cancel` that bubbles up from inside is not a close request for this
  // dialog: a file input fires one when its picker is dismissed. It is left
  // alone. Otherwise always preventDefault so the browser cannot close a
  // controlled <dialog> behind React's back, then answer the request with the
  // stack's own rules: only the top-most layer dismisses, a `required` dialog
  // swallows it, and nothing dismisses while an IME composition is in progress.
  const handleCancel = (event: React.SyntheticEvent<HTMLDialogElement>) => {
    if (event.target !== event.currentTarget) {
      return;
    }
    event.preventDefault();
    if (!shouldDismissOnCloseRequest()) {
      return;
    }
    if (allowEscape) {
      onOpenChange(false);
    }
  };

  const innerContent = (
    <div
      ref={outletRef}
      {...stylex.props(
        styles.inner,
        ...container(
          useThemeDefault
            ? {
                useThemeDefault: 'dialog',
                maxHeight: standardSizing?.maxHeight,
              }
            : {
                paddingInnerX: paddingToken,
                paddingInnerY: paddingToken,
                paddingOuterX: paddingToken,
                paddingOuterY: paddingToken,
                maxHeight: standardSizing?.maxHeight,
              },
        ),
        !useThemeDefault &&
          effectivePadding !== 4 &&
          paddingStyles[effectivePadding],
        !useThemeDefault &&
          effectivePadding !== 4 &&
          containerPaddingInlineVarStyles[effectivePadding],
        !useThemeDefault &&
          effectivePadding !== 4 &&
          containerPaddingBlockStartVarStyles[effectivePadding],
        !useThemeDefault &&
          effectivePadding !== 4 &&
          containerPaddingBlockEndVarStyles[effectivePadding],
        isFullscreen && useThemeDefault && styles.fullscreenSafeArea,
        styles.innerCorners,
        containerCornerStyles.publish,
      )}>
      <DialogContext value={dialogContextValue}>{children}</DialogContext>
    </div>
  );

  // Filter out native open to prevent InvalidStateError when accidentally passed.
  // Keep the consumer click handler separate so the modal path can compose it
  // with Dialog-owned behavior without changing the inline preview path.
  const hasPosition = position != null && !isFullscreen;
  const {onClick: onClickProp, ...propsWithoutClick} = props;
  const {open: _open, ...safeProps} = propsWithoutClick as Record<
    string,
    unknown
  >;
  const inlineSafeProps: Record<string, unknown> = {
    ...safeProps,
    onClick: onClickProp,
  };

  // --- Inline rendering path (for documentation previews) ---
  if (isInline) {
    if (!isOpen) {
      return null;
    }

    return (
      <div
        {...inlineSafeProps}
        {...mergeProps(
          themeProps('dialog', {variant}),
          stylex.props(
            layerTextReset.reset,
            layerStructureReset.reset,
            styles.inlineWrapper,
            overlayPaddingReset.reset,
            standardSizing &&
              dynamicStyles.sizing(
                standardSizing.width,
                standardSizing.maxWidth,
                standardSizing.maxHeight,
              ),
            isFullscreen && styles.fullscreen,
            xstyle,
          ),
          className,
          style,
        )}
        data-testid={
          (props as Record<string, unknown>)['data-testid'] as
            string | undefined
        }>
        <LayerDepthProvider>
          <LayerContentBoundary>{innerContent}</LayerContentBoundary>
        </LayerDepthProvider>
      </div>
    );
  }

  // --- Standard modal rendering path ---

  return (
    <dialog
      ref={mergedDialogRef}
      {...safeProps}
      {...mergeProps(
        themeProps('dialog', {variant}),
        focusOutlineProps.focusVisible(
          layerTextReset.reset,
          layerStructureReset.reset,
          styles.dialog,
          overlayPaddingReset.reset,
          isOpen && styles.open,
          styles.backdrop,
          standardSizing &&
            dynamicStyles.sizing(
              standardSizing.width,
              standardSizing.maxWidth,
              standardSizing.maxHeight,
            ),
          hasPosition &&
            (() => {
              const o = resolveDialogPositionOffsets(position);
              return dynamicStyles.position(
                o.top,
                o.insetInlineStart,
                o.insetInlineEnd,
                o.bottom,
              );
            })(),
          isFullscreen && styles.fullscreen,
          isFullscreen && isOpen && styles.fullscreenOpen,
          opensSettled && styles.openSettled,
          xstyle,
        ),
        className,
        style,
      )}
      // Presses inside the dialog do not reach handlers around where it is
      // written.
      {...layerClickBoundary({
        ...safeProps,
        onClick: chainEventHandlers(backdropPress.onClick, onClickProp),
      })}
      onPointerDownCapture={chainEventHandlers(
        backdropPress.onPointerDownCapture,
        safeProps.onPointerDownCapture as PointerHandler | undefined,
      )}
      onPointerUpCapture={chainEventHandlers(
        backdropPress.onPointerUpCapture,
        safeProps.onPointerUpCapture as PointerHandler | undefined,
      )}
      onPointerCancelCapture={chainEventHandlers(
        backdropPress.onPointerCancelCapture,
        safeProps.onPointerCancelCapture as PointerHandler | undefined,
      )}
      onCancel={handleCancel}
      aria-modal={isHydrating ? undefined : 'true'}
      // The default aria-labelledby (from a DialogHeader title) is set
      // imperatively in `attachDialog`; a consumer-provided aria-labelledby
      // flows through {...safeProps} above and wins.
      {...(purpose === 'required' ? {role: 'alertdialog'} : undefined)}>
      <ModalAnnounceProvider dialogRef={dialogRef} isOpen={isOpen}>
        <LayerDepthProvider>
          <LayerContentBoundary>{innerContent}</LayerContentBoundary>
        </LayerDepthProvider>
      </ModalAnnounceProvider>
    </dialog>
  );
}

Dialog.displayName = 'Dialog';