Skip to content

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

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

'use client';

/**
 * @file BottomSheetPanel.tsx
 * @input Uses React, StyleX, theme tokens, text/provider boundaries, container padding, sheet gestures, shared scroll behavior, and the host label
 * @output Internal BottomSheetPanel with a keyboard-reachable scrolling body and motion-state types
 * @position Shared presentation layer for standalone and switcher
 *   BottomSheets. It owns the sheet surface and the body's keyboard access.
 *   The host owns dialog focus, inert state and switcher registration.
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/BottomSheet/BottomSheet.tsx
 * - /packages/core/src/BottomSheet/BottomSheetPanel.test.tsx
 * - /packages/core/src/BottomSheet/snapOffsets.ts
 * - /packages/core/src/keyboard/useMobileKeyboard.ts
 * - /packages/core/src/BottomSheet/useSheetGestures.ts
 * - /packages/core/src/Layout/container.stylex.ts (bottom-sheet padding chain)
 */

import {
  useCallback,
  useEffect,
  useImperativeHandle,
  useLayoutEffect,
  useMemo,
  useRef,
  useSyncExternalStore,
  type ReactNode,
  type Ref,
} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {useDevWarning} from '../hooks/useDevWarning';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {useScrollableArea} from '../hooks/useScrollableArea';
import {
  borderVars,
  colorVars,
  durationVars,
  easeVars,
  focusVars,
  radiusVars,
  shadowVars,
  sizeVars,
  spacingVars,
} from '../theme/tokens.stylex';
import {mergeProps} from '../utils/mergeProps';
import {themeProps} from '../utils/themeProps';
import {focusOutlineStyles} from '../utils/focusOutline.stylex';
import {layerTextReset} from '../Layer/layerTextReset.stylex';
import {layerStructureReset} from '../Layer/layerStructureReset.stylex';
import {LayerContentBoundary} from '../Layer/layerScopedContext';
import {container} from '../Layout/container.stylex';
import type {SpacingToken} from '../Layout/container.stylex';
import {
  containerPaddingBlockEndVarStyles,
  containerPaddingInlineVarStyles,
  overlayPaddingReset,
  paddingStyles,
  spacingStepToToken,
} from '../Layout/padding.stylex';
import {subscribeInput} from '../utils/inputStream';
import type {SpacingStep} from '../utils/types';
import {
  isValidSnapPoint,
  resolveSnapPoints,
  type BottomSheetSnapPoint,
} from './snapOffsets';
import {animatorFor, SETTLE_THRESHOLD} from '../motion/animator';
import {resolveSettleMs} from '../motion/resolveMotion';
import {springs} from '../motion/uikit/springs';
import {useMobileKeyboard} from '../keyboard/useMobileKeyboard';
import {
  scrollPreservationPadding,
  sheetLayoutHeight,
  useSheetGestures,
  type SheetDragExit,
} from './useSheetGestures';

const HEIGHT_BUDGETS = {
  hug: '92dvh',
  capped: '62dvh',
  tall: '92dvh',
} as const;

export type BottomSheetHeight = keyof typeof HEIGHT_BUDGETS;
export type {BottomSheetSnapPoint};

// The reserve: how far the sheet's surface reaches below the screen, so a
// pull past the top never shows the page under it.
// SYNC: OVERSCROLL_MAX in useSheetGestures.ts must not exceed MIN_RESERVE.
const MIN_RESERVE = 48;
// A finger can pull past the top by at most the viewport's height. The rubber
// band over a sheet as tall as the viewport then shows 35.5% of it.
const RESERVE_VIEWPORT_SHARE = 0.4;

function sheetReserve(viewportHeight: number): number {
  return Math.max(
    MIN_RESERVE,
    Math.ceil(viewportHeight * RESERVE_VIEWPORT_SHARE),
  );
}
const MOBILE_KEYBOARD_BOTTOM_CLEARANCE = 48;
// How many more frames a drag's close looks for its scrim's fade to adopt.
const MAX_SCRIM_FADE_ADOPT_FRAMES = 3;
const TRANSITION_BACKSTOP_BUFFER_MS = 50;
// The floating handle bar's height. The bar is out of flow; at rest the
// content box keeps a band this tall under it (`clearsGrabBar`), so the pill
// (4px, centered, 10-14px from the sheet's top edge) never sits on the first
// row, and scrolled content rides up beneath it.
const HANDLE_BAR_HEIGHT = spacingVars['--spacing-6'];

const BLOCK_SIZE_PROPERTIES = [
  'height',
  'minHeight',
  'maxHeight',
  'blockSize',
  'minBlockSize',
  'maxBlockSize',
] as const;

/** Whether StyleX styles hold any style: they can nest in arrays. */
function hasStyles(xstyle: unknown): boolean {
  return Array.isArray(xstyle)
    ? xstyle.some(hasStyles)
    : xstyle != null && typeof xstyle === 'object';
}

function supportsWebAnimations(): boolean {
  return (
    typeof Element !== 'undefined' &&
    typeof Element.prototype.animate === 'function'
  );
}

/**
 * How long a drag's close plays, in ms. It is the close spring's move from
 * where the finger left the sheet, timed as the shared animator times it.
 */
function dragExitMs(element: Element, exit: SheetDragExit): number {
  return resolveSettleMs(element, springs.sheetDismissSwipe, {
    from: 0,
    to: exit.distance,
    velocity: exit.velocity,
    epsilon: SETTLE_THRESHOLD.y,
  });
}

/** The running fade that clears the scrim behind `panel`, if any. */
function clearingScrimFade(panel: Element): Animation | undefined {
  const dialog = panel.closest('dialog');
  const doc = panel.ownerDocument;
  if (dialog == null || typeof doc.getAnimations !== 'function') {
    return undefined;
  }
  const fades = doc.getAnimations().filter(animation => {
    const effect = animation.effect as KeyframeEffect | null;
    return (
      effect?.target === dialog &&
      (animation as CSSTransition).transitionProperty === 'opacity' &&
      // Skip a fade that the drag started. A style update replaces that fade.
      Number(effect.getKeyframes().at(-1)?.opacity) === 0
    );
  });
  const onBackdrop = fades.filter(
    fade => (fade.effect as KeyframeEffect).pseudoElement === '::backdrop',
  );
  // An engine that reports no backdrop effect (WebKit) puts the backdrop's
  // fade on the dialog itself, which runs no opacity transition of its own.
  return (
    onBackdrop.length > 0
      ? onBackdrop
      : fades.filter(fade => !(fade.effect as KeyframeEffect).pseudoElement)
  ).at(-1);
}

// Measure the viewport that the height budgets use. They are `dvh`, which
// the virtual keyboard does not shrink, so `visualViewport` would differ by
// the keyboard's height. `useMobileKeyboard` handles the keyboard and does
// not change the detents.
function layoutViewportHeight(): number {
  return typeof window === 'undefined' ? 0 : window.innerHeight;
}

// The layout viewport's height, as the `resize` listener last read it. While
// the listener runs, a render reads this value, never `innerHeight`. After a
// commit's DOM writes, a read of `innerHeight` forces a style recalculation
// and a layout. Open sheets share one listener. With no sheet open, the value
// is null, because nothing keeps it current.
let viewportHeight: number | null = null;
const viewportHeightListeners = new Set<() => void>();
let stopViewportResize: (() => void) | null = null;

function handleViewportResize(): void {
  viewportHeight = layoutViewportHeight();
  for (const listener of viewportHeightListeners) {
    listener();
  }
}

function subscribeToViewportHeight(onChange: () => void): () => void {
  viewportHeightListeners.add(onChange);
  if (stopViewportResize == null) {
    stopViewportResize = subscribeInput(window, 'resize', handleViewportResize);
    // A resize between the first render and this listener has no event left
    // to deliver. So read the height now, and let React compare it with the
    // height it rendered.
    viewportHeight = layoutViewportHeight();
    onChange();
  }
  return () => {
    viewportHeightListeners.delete(onChange);
    if (viewportHeightListeners.size === 0) {
      stopViewportResize?.();
      stopViewportResize = null;
      viewportHeight = null;
    }
  };
}

function readViewportHeight(): number {
  // Without a listener, nothing keeps a stored height current.
  if (stopViewportResize == null) {
    return layoutViewportHeight();
  }
  viewportHeight ??= layoutViewportHeight();
  return viewportHeight;
}

function readNoViewportHeight(): number {
  return 0;
}

function subscribeToNothing(): () => void {
  return () => {};
}

/**
 * A stable identity for a set of snap points. Type-tagged, so the fraction
 * `0.5` and the (invalid) string `'0.5'` cannot collide on one key.
 *
 * Recomputed every render — the panel re-renders on every frame of a drag — so
 * it stays a single pass over a handful of values, and everything derived from
 * the points hangs off it instead of being rebuilt per frame.
 */
function snapPointsKeyFor(
  points: ReadonlyArray<BottomSheetSnapPoint> | undefined,
): string {
  let key = '';
  for (const point of points ?? []) {
    key += `${typeof point}:${point}|`;
  }
  return key;
}

// An explicit padding publishes only the part past the grab bar's band, so a
// lone Section that escapes the published padding still starts below the bar.
// `clearsGrabBar` applies the band on top.
const pastGrabBarStyles = stylex.create({
  0: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-0']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  0.5: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-0-5']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  1: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-1']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  1.5: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-1-5']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  2: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-2']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  3: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-3']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  4: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-4']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  5: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-5']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  6: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-6']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  8: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-8']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
  10: {
    '--container-padding-block-start': `max(calc(${spacingVars['--spacing-10']} - ${HANDLE_BAR_HEIGHT}), 0px)`,
  },
});

/**
 * The reduced-motion queries. With a coarse primary pointer the sheet
 * cross-fades, else it changes at once. The cross-fade lasts at most 200 ms.
 */
const REDUCED_MOTION_COARSE =
  '@media (prefers-reduced-motion: reduce) and (pointer: coarse)';
export const REDUCED_MOTION_COARSE_QUERY =
  '(prefers-reduced-motion: reduce) and (pointer: coarse)';
const CROSS_FADE_MS = 200;

const styles = stylex.create({
  sheet: {
    pointerEvents: 'auto',
    boxSizing: 'border-box',
    // Containing block for the floating handle bar, which is lifted out of
    // flow so the scrolling body reaches the sheet's top edge.
    position: 'relative',
    display: 'flex',
    flexDirection: 'column',
    minHeight: 0,
    width: '100%',
    maxWidth: 640,
    backgroundColor: colorVars['--color-background-surface'],
    // A hairline on the three edges that face the scrim. In dark mode the
    // surface and the scrim are only a few RGB steps apart, and the shadow is
    // black on near-black, so the side edges disappear. The block-end edge
    // stays bare, below the viewport.
    borderBlockStartWidth: borderVars['--border-width'],
    borderBlockStartStyle: 'solid',
    borderBlockStartColor: colorVars['--color-border'],
    borderInlineStartWidth: borderVars['--border-width'],
    borderInlineStartStyle: 'solid',
    borderInlineStartColor: colorVars['--color-border'],
    borderInlineEndWidth: borderVars['--border-width'],
    borderInlineEndStyle: 'solid',
    borderInlineEndColor: colorVars['--color-border'],
    borderStartStartRadius: radiusVars['--radius-container'],
    borderStartEndRadius: radiusVars['--radius-container'],
    boxShadow: shadowVars['--shadow-high'],
    outline: 'none',
    overflow: 'hidden',
    paddingBlockEnd: `calc(env(safe-area-inset-bottom, 0px) + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
    marginBlockEnd: `calc(-1 * var(--_sheet-reserve, ${MIN_RESERVE}px))`,
    // Under reduced motion no transform runs. On a coarse primary pointer the
    // entrance is an opacity cross-fade of at most 200 ms. A fine pointer gets
    // the change at once (the 0.01s collapse).
    transform: {
      default: 'translateY(0)',
      '@starting-style': {
        default: 'translateY(100%)',
        '@media (prefers-reduced-motion: reduce)': 'translateY(0)',
      },
    },
    opacity: {
      default: 1,
      '@starting-style': {
        default: 1,
        [REDUCED_MOTION_COARSE]: 0,
      },
    },
    transitionProperty: 'transform, opacity',
    transitionDuration: {
      default: durationVars['--duration-medium'],
      '@media (prefers-reduced-motion: reduce)': {
        default: '0.01s',
        '@media (pointer: coarse)': `0.01s, ${CROSS_FADE_MS}ms`,
      },
    },
    transitionTimingFunction: easeVars['--ease-standard'],
    willChange: 'transform, opacity',
  },
  // A sheet present on page load opens where it rests (spec:AST-013 FR13):
  // the collapse reduced motion uses, so the transition still ends.
  sheetSettled: {
    transitionDuration: '0.01s',
  },
  /**
   * The exit is its own motion, not the entrance played backwards. The
   * decelerate `--ease-standard` put the sheet half off-screen in 59ms of a
   * 410ms close, so the travel ended before the eye followed it. An exit
   * accelerates instead (`--ease-exit`). The curve is gentle, so the sheet
   * moves within ~50ms and the close reads as one departure. The duration is
   * the entrance's band, because a shorter band leaves too little travel when
   * a theme scales motion down.
   */
  sheetClosing: {
    // Under reduced motion the exit does not travel. On a coarse pointer it
    // fades out where it is, and on a fine one it ends at once.
    transform: {
      default: 'translateY(100%)',
      '@media (prefers-reduced-motion: reduce)': 'translateY(0)',
    },
    opacity: {
      default: null,
      [REDUCED_MOTION_COARSE]: 0,
    },
    // A pointer presentation closes on the theme's exit curve. A touch
    // presentation keeps its own curve.
    transitionTimingFunction: {
      default: easeVars['--ease-exit'],
      '@media (pointer: coarse)': 'cubic-bezier(0.3, 0, 0.6, 0.6)',
    },
  },
  /**
   * An exit that cross-fades on a pointer that the media query does not
   * cover: a touch swipe dismissal under reduced motion fades out in place on
   * every pointer. It uses the opacity and ceiling of the coarse-pointer rule.
   */
  sheetClosingCrossFade: {
    transform: 'translateY(0)',
    opacity: 0,
    transitionDuration: `0.01s, ${CROSS_FADE_MS}ms`,
  },
  sheetFading: {
    opacity: 0,
  },
  sheetInactive: {
    pointerEvents: 'none',
  },
  handleBar: {
    // Floats over the body rather than taking a row in the flex column. The
    // content starts at the sheet's top edge and rides up under the pill --
    // both moving it closer to the top and letting scrolled content pass
    // beneath instead of stopping at a hard edge.
    position: 'absolute',
    insetBlockStart: 0,
    insetInlineStart: 0,
    insetInlineEnd: 0,
    zIndex: 1,
    display: 'flex',
    alignItems: 'center',
    justifyContent: 'center',
    height: HANDLE_BAR_HEIGHT,
    // Keeps the pill legible over whatever sits or scrolls under it: opaque
    // surface behind the pill itself, fading out across the lower half so the
    // content emerging below has no visible cut line.
    backgroundImage: `linear-gradient(to bottom, ${colorVars['--color-background-surface']} 60%, transparent)`,
    // WebKit can draw this bar under the scrolling body's own layer while the
    // sheet's transform animates, so the pill vanishes until the sheet rests.
    // A layer of its own keeps it above the body.
    willChange: 'transform',
    // Drags are the handle's; a pinch still zooms the page (WCAG 1.4.4).
    touchAction: 'pinch-zoom',
    cursor: {
      default: 'grab',
      ':is(:disabled,[aria-disabled="true"])': 'default',
    },
    // The pill is drawn on the grab bar itself, as decoration with no role.
    '::before': {
      content: '""',
      width: sizeVars['--size-element-lg'],
      height: spacingVars['--spacing-1'],
      borderRadius: radiusVars['--radius-full'],
      backgroundColor: colorVars['--color-border'],
    },
  },
  body: {
    flexGrow: 1,
    minHeight: 0,
    boxSizing: 'border-box',
    touchAction: 'pan-y pinch-zoom',
    outlineOffset: {
      default: 0,
      ':focus-visible': `calc(-1 * ${focusVars['--focus-outline-width']})`,
    },
    // The scrolling area paints the surface itself, covering the sheet's whole
    // inner box. Without it the sheet's edge is not uniform: a theme that packs
    // an inset ring into --shadow-high (the bundled themes all add one in dark
    // mode) draws that ring just inside the sheet, where an opaque content
    // wrapper such as Section paints over it -- so the ring shows only in the
    // gap below where the content ends, and the sheet's side edges appear to
    // change width partway down. Painting the surface here hides the ring
    // evenly, leaving the border below as the sheet's one edge.
    backgroundColor: colorVars['--color-background-surface'],
    // No reserve for the handle bar here: it floats over the scrolling area,
    // so scrolled content rides up under the pill. The content box keeps the
    // resting content clear of the bar instead (`clearsGrabBar`).
    paddingBlockEnd: 0,
  },
  clearsGrabBar: {
    paddingBlockStart: `calc(var(--container-padding-block-start, 0px) + ${HANDLE_BAR_HEIGHT})`,
  },
  content: {
    // Preserve the body's block formatting (including margin/float isolation)
    // and its definite percentage-height basis. fit-content lets this real
    // observed box grow with async content beyond a fixed-height viewport.
    // This box is also the sheet's container: it carries the padding and
    // publishes it, so a lone Section child escapes it exactly as in Dialog.
    // At the block start it publishes only the padding past the grab bar's
    // band, so a child escapes the padding but never the band.
    display: 'flow-root',
    boxSizing: 'border-box',
    height: '100%',
    // fit-content, not min-content: they are one size in the block axis, but
    // WebKit ignores min-content on a block's min-height. There the box keeps
    // its body's height on a budget-height sheet. Content placed directly in
    // it then overflows the box, and its block-end padding leaves the scroll
    // range.
    minHeight: 'fit-content',
  },
  tallKeyboardBody: {
    scrollPaddingBlockEnd: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
  },
  // The inset the keyboard takes at the end of a Tall sheet's content
  // (useMobileKeyboard), so its last control can scroll above the keyboard.
  // It is the content box's last in-flow box, after the content's own
  // children, not a box after the content. Firefox resolves the content's
  // `min-height: min-content` as `auto` in the block axis. The content box
  // then keeps the body's height while its children overflow it. An inset
  // after that box sat inside the overflow and added no scroll range. In
  // Firefox for Android, the body's scrollHeight was 1491 with and without a
  // 357 px inset.
  tallKeyboardContent: {
    '::after': {
      content: '""',
      display: 'block',
      blockSize: 0,
      pointerEvents: 'none',
    },
  },
  keyboardInset: (inset: number) => ({
    '::after': {
      blockSize: inset,
    },
  }),
  budget: {
    height: `calc(var(--_sheet-budget) + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
  },
  hugHeight: {
    height: 'fit-content',
    maxHeight: `calc(${HEIGHT_BUDGETS.hug} + var(--_sheet-reserve, ${MIN_RESERVE}px))`,
  },
});

export type BottomSheetPanelMotion =
  'entering' | 'aligning' | 'fading' | 'exiting';

export type BottomSheetPanelState =
  | {kind: 'hidden'}
  | {kind: 'open'; entering: boolean}
  | {
      kind: 'retained';
      motion: 'covered' | 'aligning' | 'fading';
      alignmentOffset: number;
    }
  | {kind: 'exiting'};

interface BottomSheetPanelProps extends BaseProps<HTMLDivElement> {
  /** Ref forwarded to the visual sheet panel. */
  ref?: React.Ref<HTMLDivElement>;
  state: BottomSheetPanelState;
  /**
   * Whether the sheet was open on page load: it then opens where it rests,
   * with no entry motion.
   */
  isEntrySettled?: boolean;
  /**
   * Called when the settled entry's transition ends, so the host can release
   * it and later motion in the same open (a drag's settle) animates as usual.
   */
  onEntrySettled?: () => void;
  /**
   * The host's controlled open state — false as soon as the host has taken
   * a close, true while it is open or has refused one — distinct from
   * `state`, which stays `open` until the close settles. Decides whether a
   * swipe release's dismissal was honored (the reduced-motion cross-fade).
   */
  isOpenRequested?: boolean;
  height: BottomSheetHeight | number | string;
  /** Existing host name, reused for the keyboard scrolling group. */
  label: string;
  children: ReactNode;
  /**
   * Content padding on the spacing scale. Omitted, the content box reads the
   * theme's bottom-sheet padding, then --spacing-4 (Dialog's default).
   */
  padding?: SpacingStep;
  snapPoints?: ReadonlyArray<BottomSheetSnapPoint>;
  isSwipeDismissAllowed?: boolean;
  /** Whether the host has locked page scrolling (a modal, scrim-backed sheet). */
  isPageScrollLocked?: boolean;
  onDismiss: () => void;
  onScrimOpacity: (opacity: number) => void;
  /**
   * The scrim's fade under a touch drag's close, in milliseconds, or null
   * once that close ends or a reopen takes the sheet back. `panel` is the
   * sheet's element: the commit that starts the close can detach the host's
   * dialog ref while this runs.
   */
  onScrimFadeDuration?: (panel: HTMLElement, ms: number | null) => void;
  onElementChange?: (element: HTMLDivElement | null) => void;
  /**
   * A ref for the grab handle's element. The handle stays mounted with the
   * panel and carries no other ref.
   */
  handleRef?: Ref<HTMLDivElement>;
  onMotionStart?: (motion: BottomSheetPanelMotion) => void;
  onMotionComplete?: (motion: BottomSheetPanelMotion) => void;
}

/**
 * A hidden sheet observes nothing. The scroll area's measuring ref attaches
 * as the sheet presents and detaches when it is hidden, so a closed sheet
 * that stays mounted holds no resize, mutation or viewport observers.
 */
function whilePresented<P extends {ref?: unknown}>(
  isPresented: boolean,
  props: P,
): P {
  return isPresented ? props : {...props, ref: undefined};
}

function motionForState(
  state: BottomSheetPanelState,
): BottomSheetPanelMotion | null {
  if (state.kind === 'open') {
    return state.entering ? 'entering' : null;
  }
  if (state.kind === 'retained') {
    return state.motion === 'covered' ? null : state.motion;
  }
  return state.kind === 'exiting' ? 'exiting' : null;
}

function waitForTransition(
  element: HTMLElement | null,
  propertyName: 'transform' | 'opacity',
  complete: () => void,
): () => void {
  if (element == null) {
    complete();
    return () => {};
  }

  let done = false;
  let timer: ReturnType<typeof setTimeout> | null = null;
  let backstopMs = 0;
  const finish = () => {
    if (done) {
      return;
    }
    done = true;
    if (timer != null) {
      clearTimeout(timer);
    }
    element.removeEventListener('transitionend', handleTransitionEnd);
    element.removeEventListener('transitioncancel', handleTransitionEnd);
    complete();
  };
  const handleTransitionEnd = (event: TransitionEvent) => {
    if (event.target !== element || event.propertyName !== propertyName) {
      return;
    }
    // The engine cancels a transition whose end value changes mid-flight. A
    // percentage transform does when the closing frame moves the height by a
    // fraction of a pixel. A replacement runs on from where it was. That one
    // ends the motion, not the cancel.
    if (
      event.type === 'transitioncancel' &&
      hasRunningTransition(element, propertyName)
    ) {
      if (timer != null) {
        clearTimeout(timer);
        timer = setTimeout(finish, backstopMs);
      }
      return;
    }
    finish();
  };
  element.addEventListener('transitionend', handleTransitionEnd);
  element.addEventListener('transitioncancel', handleTransitionEnd);

  const computedStyle = getComputedStyle(element);
  if (
    element.style.transition.trim() === 'none' ||
    computedStyle.transition.trim() === 'none'
  ) {
    finish();
    return () => {};
  }
  const properties = computedStyle.transitionProperty
    .split(',')
    .map(value => value.trim());
  const durations = computedStyle.transitionDuration
    .split(',')
    .map(parseTransitionTime);
  const delays = computedStyle.transitionDelay
    .split(',')
    .map(parseTransitionTime);
  let hasUnresolvedTiming = false;
  const transitionMs = properties.reduce((longest, property, index) => {
    if (property !== propertyName && property !== 'all') {
      return longest;
    }
    const duration = durations[index % durations.length];
    const delay = delays[index % delays.length];
    if (duration == null || delay == null) {
      hasUnresolvedTiming = true;
      return longest;
    }
    return Math.max(longest, duration + delay);
  }, 0);

  if (hasUnresolvedTiming) {
    // JSDOM can leave CSS variables unresolved. In that case the native event
    // remains authoritative; choosing a fixed timeout here would make an
    // assumption about the consumer's theme.
    return () => {
      element.removeEventListener('transitionend', handleTransitionEnd);
      element.removeEventListener('transitioncancel', handleTransitionEnd);
    };
  }

  if (transitionMs <= 0) {
    finish();
    return () => {};
  }

  backstopMs = transitionMs + TRANSITION_BACKSTOP_BUFFER_MS;
  timer = setTimeout(finish, backstopMs);
  return () => {
    if (timer != null) {
      clearTimeout(timer);
    }
    element.removeEventListener('transitionend', handleTransitionEnd);
    element.removeEventListener('transitioncancel', handleTransitionEnd);
  };
}

// Whether a CSS transition of `propertyName` still runs on `element`.
function hasRunningTransition(
  element: HTMLElement,
  propertyName: string,
): boolean {
  return (element.getAnimations?.() ?? []).some(
    animation =>
      (animation as Animation & {transitionProperty?: string})
        .transitionProperty === propertyName &&
      (animation.playState === 'running' || animation.playState === 'paused'),
  );
}

function parseTransitionTime(value: string): number | null {
  const normalizedValue = value.trim();
  if (!/^-?(?:\d+|\d*\.\d+)(?:ms|s)$/.test(normalizedValue)) {
    return null;
  }
  const time = Number.parseFloat(value);
  return normalizedValue.endsWith('ms') ? time : time * 1000;
}

/** Internal visual and gesture surface shared by every BottomSheet host. */
export function BottomSheetPanel({
  ref,
  state,
  isOpenRequested,
  height,
  label,
  children,
  padding,
  snapPoints,
  className,
  style,
  tabIndex,
  xstyle,
  isEntrySettled = false,
  onEntrySettled,
  onTransitionEnd,
  isSwipeDismissAllowed = true,
  isPageScrollLocked = false,
  onDismiss,
  onScrimOpacity,
  onScrimFadeDuration,
  onElementChange,
  handleRef,
  onMotionStart,
  onMotionComplete,
  ...props
}: BottomSheetPanelProps) {
  const elementRef = useRef<HTMLDivElement | null>(null);
  const dismissKeyboardRef = useRef<
    ((focusTarget?: HTMLElement) => void) | null
  >(null);
  const previousStateRef = useRef(state);
  const reactivatedEntranceRef = useRef(false);
  const onMotionStartRef = useRef(onMotionStart);
  const onMotionCompleteRef = useRef(onMotionComplete);
  const onScrimFadeDurationRef = useRef(onScrimFadeDuration);
  const startedMotionRef = useRef<BottomSheetPanelMotion | null>(null);
  const pendingMotionCompleteRef = useRef<BottomSheetPanelMotion | null>(null);

  const isEntering = state.kind === 'open' && state.entering;
  const previousState = previousStateRef.current;
  const wasEntering = previousState.kind === 'open' && previousState.entering;
  if (isEntering && !wasEntering) {
    reactivatedEntranceRef.current = previousState.kind === 'retained';
  } else if (!isEntering) {
    reactivatedEntranceRef.current = false;
  }

  useLayoutEffect(() => {
    previousStateRef.current = state;
    onMotionStartRef.current = onMotionStart;
    onMotionCompleteRef.current = onMotionComplete;
    onScrimFadeDurationRef.current = onScrimFadeDuration;
  }, [onMotionComplete, onMotionStart, onScrimFadeDuration, state]);

  const isInteractive = state.kind === 'open';
  const isPresented = state.kind !== 'hidden';
  const isRetained = state.kind === 'retained';
  const isInactive = isRetained || state.kind === 'exiting';
  const isClosing = state.kind === 'exiting';
  const isFading = isRetained && state.motion === 'fading';
  // Under reduced motion a retained sheet does not align down to a shorter
  // entering sheet, because that is travel. It fades where it is.
  const isReducedMotion = useMediaQuery('(prefers-reduced-motion: reduce)');
  const alignmentOffset =
    isRetained && !isReducedMotion ? state.alignmentOffset : 0;

  // Everything derived from the snap points keys off their identity, not the
  // array's: the resolver's identity is the hook's signal that the stops
  // changed, so it must not churn on a re-render the drag caused. The memo
  // reads the points through a ref, so the resolver resolves them at call time
  // — against whatever the viewport is then, not what it was at memo time.
  const snapPointsKey = snapPointsKeyFor(snapPoints);
  const snapPointsRef = useRef(snapPoints);
  snapPointsRef.current = snapPoints;
  const {snapHeights, ignoredSnapPointsMessage} = useMemo(() => {
    if (snapPointsKey === '') {
      return {snapHeights: undefined, ignoredSnapPointsMessage: ''};
    }
    const ignored = (snapPointsRef.current ?? []).filter(
      point => !isValidSnapPoint(point),
    );
    return {
      snapHeights: () =>
        resolveSnapPoints(snapPointsRef.current ?? [], layoutViewportHeight()),
      ignoredSnapPointsMessage:
        ignored.length === 0
          ? ''
          : `snapPoints ignored ${JSON.stringify(ignored)}. A snap point is a viewport fraction above 0 and up to 1 (0.5 is half the screen), a px length ('320px'), or a percentage ('50%').`,
    };
  }, [snapPointsKey]);
  useDevWarning(
    'BottomSheet',
    ignoredSnapPointsMessage,
    ignoredSnapPointsMessage !== '',
  );

  // A caller's height owns the element's height: the drag never writes it.
  const consumerHeight = style?.height;
  // StyleX styles and a class name can size the sheet too. Their rules are
  // only class names here, so any of them counts as a size.
  const isSizedByCaller =
    BLOCK_SIZE_PROPERTIES.some(property => style?.[property] != null) ||
    hasStyles(xstyle) ||
    (className != null && className !== '');
  // Only a finger stretches the sheet past MIN_RESERVE, so a device with no
  // touch pointer keeps the smallest reserve. So does a sheet the caller
  // sizes, which nothing extends by the reserve; the stretch stops at it.
  const hasTouchPointer = useMediaQuery('(any-pointer: coarse)');
  const tracksViewport = isPresented && hasTouchPointer && !isSizedByCaller;
  // Each argument is a module function, so React keeps one snapshot function
  // across renders and does not re-read it in the commit.
  const trackedViewportHeight = useSyncExternalStore(
    tracksViewport ? subscribeToViewportHeight : subscribeToNothing,
    tracksViewport ? readViewportHeight : readNoViewportHeight,
    readNoViewportHeight,
  );
  const reserve =
    trackedViewportHeight > 0
      ? sheetReserve(trackedViewportHeight)
      : MIN_RESERVE;
  const {
    contentProps,
    handleProps,
    bodyProps,
    bodyElementRef,
    sheetRef,
    dragOffset,
    settledOffset,
    isDragging,
    isDismissedByTouchDrag,
    dragExit,
    sheetHeight,
    scrollPreservationInset,
    settlingLayoutOffset,
    settledLayoutOffset,
    completeScrollAreaSettle,
  } = useSheetGestures({
    isOpen: isInteractive,
    isOpenRequested: isOpenRequested ?? isInteractive,
    canDismiss: isSwipeDismissAllowed,
    offscreenBlockEndInset: reserve,
    onDismiss,
    snapHeights,
    onTravelStart: () => {
      // Focusing the sheet dismisses the keyboard as the sheet starts to move.
      dismissKeyboardRef.current?.(elementRef.current ?? undefined);
    },
    onScrimOpacity,
    hasFixedHeight: consumerHeight != null,
  });

  const {getViewportProps, getContentProps} = useScrollableArea({
    // The previous overflow-y:auto also computed overflow-x:auto. Keep wide
    // content reachable instead of clipping that existing inline scroll path.
    axis: 'both',
    keyboardAccess: {owner: 'contentOrViewport', label},
    overscroll: 'contain',
    // The sheet body deliberately remains the boundary for sheet-local sticky
    // content while fitting, as it was before shared scroll adoption.
    stickyContainment: 'always',
  });

  // The sheet measures its own height only while it is presented; a hidden
  // sheet that stays mounted observes nothing.
  const isPresentedRef = useRef(isPresented);
  const setElement = useCallback(
    (element: HTMLDivElement | null) => {
      sheetRef(isPresentedRef.current ? element : null);
      elementRef.current = element;
      onElementChange?.(element);
    },
    [onElementChange, sheetRef],
  );
  // The element a drag's exit moved, until the sheet is hidden.
  const dragExitElementRef = useRef<HTMLElement | null>(null);
  useLayoutEffect(() => {
    if (isPresentedRef.current === isPresented) {
      return;
    }
    isPresentedRef.current = isPresented;
    sheetRef(isPresented ? elementRef.current : null);
    // A hidden sheet can stay mounted, so the exit's offset goes back to 0.
    const exited = dragExitElementRef.current;
    if (!isPresented && exited != null) {
      dragExitElementRef.current = null;
      animatorFor(exited).set({y: 0});
    }
  }, [isPresented, sheetRef]);
  const keyboard = useMobileKeyboard(elementRef, {
    move: 'ride',
    inset: true,
    offset: MOBILE_KEYBOARD_BOTTOM_CLEARANCE,
    isEnabled: height === 'tall' && isPresented,
    isExpanded: settledOffset === 0,
    isOpen: isInteractive,
    isPageScrollLocked,
  });
  const keyboardInset = keyboard.inset;
  // The drag's own callback dismisses the keyboard as the sheet starts to
  // move. It runs in the gesture, so it reads the newest dismiss.
  dismissKeyboardRef.current = keyboard.dismiss;
  // Keep controller registration attached to one stable host ref. React
  // detaches an old callback ref when a consumer supplies a new identity; if
  // that public ref were merged with setElement, an ordinary parent rerender
  // could be mistaken for the panel unmounting and cancel a sheet handoff.
  useImperativeHandle(ref, () => elementRef.current as HTMLDivElement, []);

  const motion = motionForState(state);
  // The cross-fade applies on a coarse pointer, and to a transition that a
  // touch drag's release started: a finger's swipe dismissal fades in place on
  // every pointer. A mouse or pen drag is not a touch drag.
  const isCoarseCrossFade = useMediaQuery(REDUCED_MOTION_COARSE_QUERY);
  const isCrossFade =
    isCoarseCrossFade || (isReducedMotion && isDismissedByTouchDrag);
  // Without Web Animations the animator jumps the sheet to its end, so the
  // stylesheet's exit runs.
  const playedDragExit =
    dragExit != null &&
    !isCrossFade &&
    !isReducedMotion &&
    supportsWebAnimations()
      ? dragExit
      : null;
  // Syncs the scrim's fade with a drag's close. It runs as the host takes the
  // close, before the host clears the scrim, so the fade starts on the
  // close's own clock.
  useLayoutEffect(() => {
    const element = elementRef.current;
    if (playedDragExit == null || element == null) {
      return;
    }
    onScrimFadeDurationRef.current?.(
      element,
      dragExitMs(element, playedDragExit),
    );
    return () => {
      onScrimFadeDurationRef.current?.(element, null);
    };
  }, [playedDragExit]);
  // Syncs the motion with the panel's CSS transition, or a drag's exit with
  // the shared animator. The motion completes when that one ends.
  useLayoutEffect(() => {
    if (motion == null) {
      return;
    }
    // React can run this effect again for the same motion, for example when
    // a Suspense boundary shows this content again. The passive effect below
    // does not run again then, so the motion it started stays started, and a
    // completion completes at once instead of waiting for that effect.
    if (startedMotionRef.current !== motion) {
      startedMotionRef.current = null;
    }
    pendingMotionCompleteRef.current = null;
    const complete = () => {
      if (startedMotionRef.current === motion) {
        onMotionCompleteRef.current?.(motion);
      } else {
        pendingMotionCompleteRef.current = motion;
      }
    };
    if (motion === 'entering' && reactivatedEntranceRef.current) {
      complete();
      return;
    }
    const element = elementRef.current;
    if (motion === 'exiting' && playedDragExit != null && element != null) {
      dragExitElementRef.current = element;
      const exit = animatorFor(element).animate(
        {y: playedDragExit.distance},
        {
          spring: springs.sheetDismissSwipe,
          velocity: {y: playedDragExit.velocity},
        },
      );
      let isCurrent = true;
      let isFinished = false;
      let frame: number | null = null;
      // The scrim's fade follows the close. Once the close starts, the fade
      // takes its start time, so the two end together. If the fade has no
      // style yet, look for it again on each of the next few frames.
      void exit.started.then(start => {
        const adopt = (framesLeft: number) => {
          frame = null;
          if (!isCurrent) {
            return;
          }
          const fade = clearingScrimFade(element);
          if (fade != null) {
            fade.startTime = start;
          } else if (framesLeft > 0) {
            frame = requestAnimationFrame(() => adopt(framesLeft - 1));
          }
        };
        adopt(MAX_SCRIM_FADE_ADOPT_FRAMES);
      });
      void exit.finished.then(() => {
        isFinished = true;
        onScrimFadeDurationRef.current?.(element, null);
        if (isCurrent) {
          complete();
        }
      });
      return () => {
        isCurrent = false;
        if (frame != null) {
          cancelAnimationFrame(frame);
        }
        // A reopen during the exit takes the sheet back from where it is.
        if (!isFinished) {
          exit.retarget({y: 0});
        }
      };
    }
    // What ends a motion: the fade is opacity, and the entrance, alignment and
    // exit are transforms. Under the reduced-motion cross-fade an exit fades
    // where it is, and its dialog closes only after the fade, so it waits on
    // opacity. The entrance still waits on its instant transform, so the
    // retained sheet's fade starts at once and the two fades cross.
    const crossFadeMotion = isCrossFade && motion === 'exiting';
    return waitForTransition(
      elementRef.current,
      motion === 'fading' || crossFadeMotion ? 'opacity' : 'transform',
      complete,
    );
  }, [motion, isCrossFade, playedDragExit]);
  // The snap is transform-only; the layout height reconciles when it lands.
  // waitForTransition — the same helper the motion states use — resolves that
  // even when no `transitionend` is coming: inline or computed
  // `transition: none`, a zero duration, and a timer backstop otherwise.
  useLayoutEffect(() => {
    if (settlingLayoutOffset == null) {
      return;
    }
    return waitForTransition(
      elementRef.current,
      'transform',
      completeScrollAreaSettle,
    );
  }, [completeScrollAreaSettle, settlingLayoutOffset]);
  useEffect(() => {
    if (motion == null) {
      return;
    }
    onMotionStartRef.current?.(motion);
    startedMotionRef.current = motion;
    if (pendingMotionCompleteRef.current === motion) {
      pendingMotionCompleteRef.current = null;
      onMotionCompleteRef.current?.(motion);
    }
    return () => {
      if (startedMotionRef.current === motion) {
        startedMotionRef.current = null;
      }
      if (pendingMotionCompleteRef.current === motion) {
        pendingMotionCompleteRef.current = null;
      }
    };
  }, [motion]);

  // Same lowering as Dialog: with no padding prop the content box reads the
  // theme's --astryx-bottom-sheet-padding chain (--spacing-4 when unset), else
  // the explicit step.
  const usesThemePadding = padding == null;
  const effectivePadding = padding ?? 4;
  const paddingToken = spacingStepToToken[effectivePadding] as SpacingToken;

  const isNamedHeight = typeof height === 'string' && height in HEIGHT_BUDGETS;
  const budget = isNamedHeight
    ? HEIGHT_BUDGETS[height as BottomSheetHeight]
    : typeof height === 'number'
      ? `${height}px`
      : height;
  const hasMeasuredSheet = sheetHeight > 0;
  let gestureTransform = contentProps.style.transform;
  let resizedHeight: string | undefined;
  if (hasMeasuredSheet) {
    // The sheet's travel is split across two properties: `layoutOffset` is the
    // part the scrolling area gives up as layout height, and the remainder is
    // a compositor transform. Live gestures and snaps only ever move the
    // transform — the layout height changes at rest, in one reconciling render
    // whose visible geometry is identical (see useSheetGestures).
    //   - dragging above the base restores the full height below the viewport
    //     (the move that crosses writes that height to the element itself,
    //     so this render only catches up to it)
    //   - a peek settles with layout 0, so it slides rather than reflowing
    const layoutOffset = isDragging
      ? dragOffset < settledOffset
        ? 0
        : settledLayoutOffset
      : (settlingLayoutOffset ?? settledLayoutOffset);
    const activeOffset = isDragging ? dragOffset : settledOffset;
    const translation = activeOffset - layoutOffset;

    // At layout 0 the sheet is its natural height, so leave that to CSS —
    // `hug` sheets must stay fit-content. While the sheet is in motion it is
    // pinned in px instead: content reflowing mid-gesture would move the
    // surface out from under the finger, or under the snap.
    const isTraveling = isDragging || settlingLayoutOffset != null;
    resizedHeight =
      layoutOffset > 0 || isTraveling
        ? sheetLayoutHeight(sheetHeight, layoutOffset)
        : undefined;
    gestureTransform =
      translation !== 0 ? `translateY(${translation}px)` : undefined;
  }
  const retainedTransform =
    alignmentOffset > 0
      ? [gestureTransform, `translateY(${alignmentOffset}px)`]
          .filter(Boolean)
          .join(' ')
      : gestureTransform;
  const sheetTransform = isInteractive
    ? gestureTransform
    : isRetained
      ? retainedTransform
      : undefined;
  const consumerTransform = style?.transform;
  const hostHeight =
    isInteractive || isRetained || isClosing ? resizedHeight : undefined;
  const bodyEndPadding = scrollPreservationPadding(scrollPreservationInset);
  // The transform is written to the element here, not through the style
  // prop. A drag writes it straight to the element and renders nothing, so
  // React never sees those writes. Through the prop, React would skip the
  // resting value as unchanged, and the sheet would stay where the finger
  // left it. Written after each commit outside a drag, the resting value
  // lands with the restored transition, so a settle animates from the live
  // position.
  //
  // A drag that crosses its base detent also writes the height and the end
  // inset. If the release runs before that move's render commits, React sees
  // no change and writes nothing, so these are written here too. A caller's
  // height stays in the style prop, because the drag does not write it.
  useLayoutEffect(() => {
    if (isDragging) {
      return;
    }
    const element = elementRef.current;
    if (element != null) {
      // A drag's close holds the sheet where the finger left it, so the exit
      // starts from there. A step back to rest first would turn the sheet
      // the wrong way.
      const holdsDragClose =
        dragExit != null && (!isClosing || playedDragExit != null);
      if (consumerTransform == null && !holdsDragClose) {
        element.style.transform = sheetTransform ?? '';
      }
      if (consumerHeight == null) {
        element.style.height = hostHeight ?? '';
      }
    }
    const body = bodyElementRef.current;
    if (body != null) {
      body.style.paddingBlockEnd = bodyEndPadding ?? '';
    }
  });
  const gestureStyle = {
    transition: contentProps.style.transition,
    touchAction: contentProps.style.touchAction,
    overscrollBehavior: contentProps.style.overscrollBehavior,
    height: hostHeight,
  };
  return (
    <div
      {...props}
      ref={setElement}
      tabIndex={tabIndex ?? -1}
      onTransitionEnd={event => {
        onTransitionEnd?.(event);
        if (isEntrySettled && event.target === event.currentTarget) {
          onEntrySettled?.();
        }
      }}
      {...mergeProps(
        themeProps('bottom-sheet'),
        stylex.props(
          layerTextReset.reset,
          layerStructureReset.reset,
          styles.sheet,
          overlayPaddingReset.reset,
          height === 'hug' ? styles.hugHeight : styles.budget,
          isClosing && styles.sheetClosing,
          isClosing && isCrossFade && styles.sheetClosingCrossFade,
          isFading && styles.sheetFading,
          isInactive && styles.sheetInactive,
          isEntrySettled && styles.sheetSettled,
          xstyle,
        ),
        className,
        {
          ['--_sheet-budget' as string]: budget,
          ['--_sheet-reserve' as string]: `${reserve}px`,
          ...(isInteractive
            ? gestureStyle
            : isRetained || isClosing
              ? {height: hostHeight}
              : {}),
          ...style,
        },
      )}>
      <div
        ref={handleRef}
        {...stylex.props(styles.handleBar)}
        {...handleProps}
        aria-hidden="true"
      />
      <div
        {...whilePresented(
          isPresented,
          getViewportProps<HTMLDivElement>({
            ...bodyProps,
            ...mergeProps(
              stylex.props(
                focusOutlineStyles.focusVisible,
                styles.body,
                height === 'tall' && styles.tallKeyboardBody,
              ),
              bodyEndPadding != null
                ? {style: {paddingBlockEnd: bodyEndPadding}}
                : {},
            ),
          }),
        )}>
        <div
          {...whilePresented(
            isPresented,
            getContentProps<HTMLDivElement>(
              stylex.props(
                styles.content,
                height === 'tall' && styles.tallKeyboardContent,
                height === 'tall' &&
                  keyboardInset > 0 &&
                  styles.keyboardInset(keyboardInset),
                ...container(
                  usesThemePadding
                    ? {useThemeDefault: 'bottom-sheet'}
                    : {
                        paddingInnerX: paddingToken,
                        paddingInnerY: paddingToken,
                        paddingOuterX: paddingToken,
                        paddingOuterY: paddingToken,
                      },
                ),
                !usesThemePadding &&
                  effectivePadding !== 4 &&
                  paddingStyles[effectivePadding],
                !usesThemePadding &&
                  effectivePadding !== 4 &&
                  containerPaddingInlineVarStyles[effectivePadding],
                // An explicit padding publishes what reaches past the grab
                // bar's band, like the theme default (Layout/container.stylex.ts).
                !usesThemePadding && pastGrabBarStyles[effectivePadding],
                !usesThemePadding &&
                  effectivePadding !== 4 &&
                  containerPaddingBlockEndVarStyles[effectivePadding],
                // The band under the grab bar, on top of the published
                // padding past it: max(padding, the bar) in all.
                styles.clearsGrabBar,
              ),
            ),
          )}>
          <LayerContentBoundary>{children}</LayerContentBoundary>
        </div>
      </div>
    </div>
  );
}

BottomSheetPanel.displayName = 'BottomSheetPanel';