Skip to content

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

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

'use client';

/**
 * @file useMobileKeyboard.ts
 * @input A target element and its scroll area, the keyboard module's reports
 *   and focus claim, and the layout guide
 * @output useMobileKeyboard, which keeps a focused field in the target above
 *   the on-screen keyboard and returns the inset and a dismiss
 * @position Keyboard module, internal to core. BottomSheet passes its panel.
 *
 * SYNC: When modified, update /packages/core/src/keyboard/README.md
 */

import {useCallback, useEffect, useRef, useState, type RefObject} from 'react';
import {flushSync} from 'react-dom';
import {useAttachment} from '../hooks/useAttachment';
import {useMediaQuery} from '../hooks/useMediaQuery';
import {
  animatorFor,
  type Animator,
  type MotionHandle,
} from '../motion/animator';
import {KEYBOARD_SPRING} from '../motion/uikit/springs';
import {deepActiveElement} from '../utils/flatTree';
import {subscribeInput} from '../utils/inputStream';
import {layoutViewportHeight} from '../utils/layoutViewport';
import {isDocument, isNode} from '../utils/nodeType';
import {observeResize} from '../utils/sharedResizeObserver';
import {TOUCH_QUERY} from '../utils/touchPresentation';
import {
  KEYBOARD_EPSILON,
  findTextEntryControl,
  getKeyboardHeight,
  isKeyboardMeasurable,
  isTextEntryControl,
  refuseFocusReveal,
  subscribeKeyboardHeight,
  watchRevealPan,
} from './keyboardHeight';
import {
  bringsUpKeyboard,
  getKeyboardLayoutGuide,
  hidesField,
  keyboardProfileOf,
} from './keyboardLayoutGuide';
import type {KeyboardTransition} from './keyboardModel';
import {
  FIELD_OFFSET,
  drawnOffsetOf,
  followKeyboard,
  keepFieldAboveKeyboard,
  registerKeyboardTarget,
  type KeyboardMove,
} from './keyboardTarget';
import {distanceIntoBand} from './revealBand';
import {rideKeyboard} from './rideKeyboard';

// Chrome on Android pans the page itself if the keyboard still covers the
// focused field about 100 to 170 ms after the report. A field a fraction of a
// pixel under the keyboard's top still counts as covered. So the reveal sets
// the field 4 px above that top in the report's own commit, and only the rest
// rides.
const FIELD_CLEARANCE_AT_REPORT = 4;

/** How a target keeps a focused field above the on-screen keyboard. */
export interface MobileKeyboardOptions {
  /**
   * How the target moves the field. `'ride'` moves the target with the
   * keyboard; with `inset`, it reveals the field with the scroller and rides
   * the scroller's content instead. `'reveal'` scrolls the field into place
   * in the target, a scroller. Without `move`, the target is a field itself,
   * which decides where it is when it gains focus.
   */
  move?: KeyboardMove;
  /**
   * Reserves the keyboard's inset at the end of the target's scroll area,
   * the first element inside it that `useScrollableArea` marks with
   * `data-scroll-axis`.
   */
  inset?: boolean;
  /** The gap kept between the focused field and the keyboard, CSS px. */
  offset?: number;
  /** Whether the target follows the keyboard at all. */
  isEnabled?: boolean;
  /** Whether the target is at its full height, where it reveals fields. */
  isExpanded?: boolean;
  /** Whether the target is open. Focus that leaves for nothing parks on it. */
  isOpen?: boolean;
  /** Whether the page's own scroll is locked under the target. */
  isPageScrollLocked?: boolean;
}

/** What useMobileKeyboard returns. */
export interface MobileKeyboard {
  /** The inset the target lays out at its scroller's content end, CSS px. */
  readonly inset: number;
  /**
   * Dismisses the keyboard, keeping the inset while the keyboard goes. The
   * focused field blurs, or `focusTarget` takes focus.
   */
  readonly dismiss: (focusTarget?: HTMLElement) => void;
}

interface KeyboardGeometry {
  bodyBottom: number;
}

function getObstructionTop(): number {
  return layoutViewportHeight(window) - getKeyboardHeight(window);
}

// Windows whose browser revealed a focused field itself right after the
// keyboard's report, by panning the visual viewport to it. Firefox for
// Android does so 54 to 143 ms after the report while the field is under the
// keyboard. The module learns this from the behavior, never from the user
// agent.
// From then on, a sheet there reveals its field at once, in the report's own
// frame.
let revealsAtReport = new WeakSet<Window>();

/** Forgets every window's recorded reveal, for tests. */
export function __resetRevealsAtReportForTest(): void {
  revealsAtReport = new WeakSet<Window>();
}

// How far the body runs under the keyboard's top, CSS px. The keyboard's top
// comes from `innerHeight`, a whole number of CSS px, but the visual viewport
// and element rects are fractional. On the Android emulator, Chrome's visual
// viewport is 754.3 px over a 754 px layout viewport. A sheet sized to it
// then ends 0.3 px below `innerHeight` with no keyboard up. So an overlap
// under one CSS px is `innerHeight`'s precision, not an obstruction.
function overlapOf(bodyBottom: number, obstructionTop: number): number {
  const overlap = bodyBottom - obstructionTop;
  return overlap > KEYBOARD_EPSILON ? overlap : 0;
}

// Under half a pixel is rounding, not a keyboard.
function isVisualViewportRecovered(): boolean {
  return getKeyboardHeight(window) <= 0.5;
}

// Whether the focused control may keep the keyboard up, read inside open
// shadow roots. A frame or a custom element can hold a field the page cannot
// see. An open shadow host that has focus itself also counts.
function mayKeepKeyboard(): boolean {
  const target = deepActiveElement(document);
  return target != null && (bringsUpKeyboard(target) || hidesField(target));
}

/**
 * Keeps a focused field in `targetRef`'s element above the on-screen
 * keyboard (see README.md). A sheet passes its panel, and the hook reserves
 * the inset in the panel's scroll area. Returns the inset the keyboard takes
 * at the end of that area's content, CSS px, or 0 without a keyboard, and a
 * dismiss.
 *
 * @example
 * ```
 * const keyboard = useMobileKeyboard(panelRef, {move: 'ride', inset: true, offset: 48, isEnabled, isExpanded, isOpen, isPageScrollLocked});
 * ```
 */
export function useMobileKeyboard(
  targetRef: RefObject<HTMLElement | null>,
  {
    move,
    inset: reservesInset = false,
    offset = FIELD_OFFSET,
    isEnabled = true,
    isExpanded = true,
    isOpen = true,
    isPageScrollLocked = false,
  }: MobileKeyboardOptions = {},
): MobileKeyboard {
  // The inset the keyboard takes at the end of the body's content, CSS px.
  // The target lays it out after its content box's children, through a
  // functional style.
  const [keyboardInset, setKeyboardInset] = useState(0);
  const hasKeyboardLayoutRef = useRef(false);
  const retainKeyboardLayoutRef = useRef(false);
  const isEnabledRef = useRef(isEnabled);
  const isExpandedRef = useRef(isExpanded);
  const isOpenRef = useRef(isOpen);
  isEnabledRef.current = isEnabled;
  isExpandedRef.current = isExpanded;
  isOpenRef.current = isOpen;
  // Touch-only work, the ride and the reveal-pan watch, attaches only under a
  // coarse primary pointer (the touch query). Under a fine one, the hook
  // registers no touch listener.
  const isTouch = useMediaQuery(TOUCH_QUERY, false);

  const dismiss = useCallback(
    (focusTarget?: HTMLElement) => {
      const target = targetRef.current;
      const activeElement = document.activeElement;
      if (
        !isEnabledRef.current ||
        target == null ||
        !(activeElement instanceof HTMLElement) ||
        activeElement === target ||
        !target.contains(activeElement)
      ) {
        return;
      }
      // Keep the current keyboard scroll range while the keyboard goes.
      // Viewport resize events unwind that layout as the visual viewport
      // recovers, avoiding a content jump on the first drag frame.
      retainKeyboardLayoutRef.current = hasKeyboardLayoutRef.current;
      if (focusTarget == null) {
        activeElement.blur();
      } else {
        focusTarget.focus({preventScroll: true});
      }
    },
    [targetRef],
  );

  // Syncs the on-screen keyboard with closing: a target that closes blurs its
  // focused field, which dismisses the keyboard.
  useEffect(() => {
    if (isEnabled && !isOpen) {
      dismiss();
    }
  }, [dismiss, isEnabled, isOpen]);

  // A docked target, a scroller or a field, which moves no inset.
  useAttachment(
    targetRef,
    target => {
      if (!isEnabled || reservesInset || !isTouch) {
        return () => {};
      }
      return move == null
        ? keepFieldAboveKeyboard(target, {offset})
        : followKeyboard(target, {move, offset});
    },
    `${isEnabled}|${move}|${reservesInset}|${offset}|${isTouch}`,
  );

  useAttachment(
    targetRef,
    sheet => {
      const body = sheet.querySelector<HTMLElement>('[data-scroll-axis]');
      if (!isEnabled || !reservesInset || body == null) {
        return () => {};
      }
      // A field inside the sheet moves nothing itself.
      const unregister = registerKeyboardTarget(sheet);

      let keyboardGeometry: KeyboardGeometry | null = null;
      // Where a smooth reveal under way is taking the body's scrollTop.
      let smoothTarget: number | null = null;
      // The inset laid out at the end of the body's content, CSS px, and the
      // scroll range it adds there. The inset's drop takes that range back. The
      // two can differ: Chrome 124 added 344 px of range for a 360 px inset.
      let laidOutInset = 0;
      let insetRange = 0;
      // Where the keyboard layout guide publishes the keyboard's own slide, as
      // Gboard's in Chrome on Android, the sheet's content rides it. This needs
      // a coarse primary pointer and Chrome's schedule. Under a fine pointer
      // nothing of the ride attaches. In a browser without the VirtualKeyboard
      // API, such as iOS Safari or Firefox for Android, the guide never starts.
      // There the inset follows the reports. The hook subscribes to the guide
      // before the keyboard module below, so the guide publishes a report's
      // transition before the reveal reads it.
      const guide =
        isTouch && keyboardProfileOf(window) === 'chromium'
          ? getKeyboardLayoutGuide(window)
          : null;
      const contentAnimator = (): Animator | null => {
        const content = body.firstElementChild;
        return guide != null && content instanceof HTMLElement
          ? animatorFor(content)
          : null;
      };
      // How far a ride has moved the content from where its layout puts it, as
      // the page draws it now. The reveal reads a control's rect in the same
      // frame.
      const rideOffset = () => {
        const content = body.firstElementChild;
        return content instanceof HTMLElement ? drawnOffsetOf(content) : 0;
      };
      // The keyboard's show the guide plays on its slide right now, if any. At
      // a report, a show whose slide has ended counts too. A busy page can read
      // the report that late, and the ride then lands at once.
      const showOnSlide = (atReport: boolean): KeyboardTransition | null => {
        const transition = guide?.transition;
        return transition != null &&
          transition.kind === 'show' &&
          transition.animated &&
          transition.curve != null &&
          (atReport ||
            performance.now() < transition.start + transition.curve.durationMs)
          ? transition
          : null;
      };
      // A hide the hook holds the inset through (see holdInsetThrough and
      // holdThroughUnguidedHide). `onReveal` answers whether a reveal during
      // the hold goes on.
      let heldHide: {
        readonly release: () => void;
        readonly onReveal?: () => boolean;
      } | null = null;
      let documentScrollAtKeyboard: {x: number; y: number} | null = null;
      // The keyboard's top and the body's scroll when the keyboard came up. A
      // keyboard that closes puts the body back at that scroll.
      let keyboardObstructionTop: number | null = null;
      let bodyScrollTopAtKeyboard: number | null = null;
      // The hook takes focus moves over where this window measures the
      // keyboard, never by user agent, and only under a coarse primary pointer.
      // Under a fine one, it registers no touch-only listener.
      // Desktop Safari and Firefox measure too, but show no on-screen keyboard
      // and keep the browser's own focus. The effect runs again when the
      // pointer changes, so a tablet that docks a mouse drops the claim.
      const ownsFocusTransitions = isTouch && isKeyboardMeasurable(window);

      // Lays the inset out before anything measures or scrolls the body: the
      // reveal scrolls into the inset it adds in the same frame.
      const writeInset = (inset: number) => {
        const changes = inset !== laidOutInset;
        const rangeBefore = changes ? body.scrollHeight : 0;
        laidOutInset = inset;
        // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the reveal scrolls into this inset in the same frame, so it must be laid out before the reveal measures
        flushSync(() => setKeyboardInset(inset));
        if (changes) {
          insetRange =
            inset === 0
              ? 0
              : Math.max(0, insetRange + body.scrollHeight - rangeBefore);
        }
      };

      const clearKeyboardLayout = () => {
        writeInset(0);
        if (bodyScrollTopAtKeyboard != null) {
          smoothTarget = null;
          body.scrollTop = bodyScrollTopAtKeyboard;
        }
        keyboardGeometry = null;
        keyboardObstructionTop = null;
        bodyScrollTopAtKeyboard = null;
        documentScrollAtKeyboard = null;
        hasKeyboardLayoutRef.current = false;
        retainKeyboardLayoutRef.current = false;
      };

      // `within` is how far below its resting place the control can sit and
      // still clear the keyboard.
      const scrollBodyBy = (
        distance: number,
        smoothly: boolean,
        ride: KeyboardTransition | null = null,
        within: number | null = null,
      ) => {
        smoothTarget = null;
        const animator = ride == null ? null : contentAnimator();
        if (ride != null && animator != null) {
          // The body lands at once, and its content rides the keyboard's slide
          // up from the slide's start. The content starts no lower than
          // `within`, so the control clears the keyboard in this commit. Content
          // that joins the slide late is where the keyboard is (rideKeyboard). A
          // further scroll during the slide adds to the same ride.
          const before = body.scrollTop;
          body.scrollTop = before + distance;
          const moved = body.scrollTop - before;
          // Only what the body actually scrolled rides. A remainder under the
          // scroll position's precision moves nothing, so the ride under way
          // stays on its curve.
          if (moved !== 0) {
            const from = animator.get('y', ride.start) + moved;
            animator.set({y: within == null ? from : Math.min(from, within)});
            rideKeyboard(animator, {y: 0}, ride, {entrance: within != null});
          }
          return;
        }
        if (typeof body.scrollBy !== 'function') {
          body.scrollTop += distance;
          return;
        }
        // Reduce Motion applies on any pointer.
        const reduceMotion =
          typeof window.matchMedia === 'function' &&
          window.matchMedia('(prefers-reduced-motion: reduce)').matches;
        const behavior = smoothly && !reduceMotion ? 'smooth' : 'instant';
        if (behavior === 'smooth') {
          smoothTarget = body.scrollTop + distance;
        }
        body.scrollBy({
          top: distance,
          // Not 'auto', which defers to the element's computed
          // `scroll-behavior`. A consumer's `scroll-behavior: smooth` would then
          // animate a scroll this hook needs to land in the same frame.
          behavior,
        });
      };

      // The distance a smooth reveal under way has still to scroll, as far as
      // the body can scroll. It is 0 once it has landed, or with none under way.
      const smoothDistanceLeft = () => {
        if (smoothTarget == null) {
          return 0;
        }
        const maxScroll = Math.max(
          body.scrollTop,
          body.scrollHeight - body.clientHeight,
        );
        const target = Math.min(smoothTarget, maxScroll);
        const left = target - body.scrollTop;
        return Math.abs(left) < 1 ? 0 : left;
      };

      // Scroll `control` into the part of the body the keyboard leaves visible,
      // reading live geometry each time.
      const scrollControlIntoSafeArea = (
        control: HTMLElement,
        smoothly: boolean,
        ride: KeyboardTransition | null = null,
      ) => {
        const measuredBodyRect = body.getBoundingClientRect();
        const measuredControlRect = control.getBoundingClientRect();
        const obstructionTop = getObstructionTop();
        // Under a pixel of overhang is `innerHeight`'s precision, not a
        // keyboard: no suggestion clearance then (overlapOf).
        const overlap = overlapOf(measuredBodyRect.bottom, obstructionTop);
        const clearance = overlap > 0 ? offset : 0;
        const safeTop = measuredBodyRect.top;
        const safeBottom = Math.min(
          measuredBodyRect.bottom,
          obstructionTop - clearance,
        );

        // Where the control will be once a smooth reveal under way lands. If
        // that lands the control, a second scroll would overshoot in Firefox.
        // Firefox keeps adding a smooth scrollBy's distance after another
        // scroll. A ride's translate is not where the layout puts the control
        // either.
        const pending = smoothDistanceLeft() + rideOffset();
        const controlBottom = measuredControlRect.bottom - pending;
        const controlTop = measuredControlRect.top - pending;
        const distance = distanceIntoBand(
          controlTop,
          controlBottom,
          safeTop,
          safeBottom,
        );
        if (distance > 0) {
          scrollBodyBy(
            distance,
            smoothly,
            ride,
            Math.max(
              0,
              obstructionTop - safeBottom - FIELD_CLEARANCE_AT_REPORT,
            ),
          );
        } else if (distance < 0) {
          scrollBodyBy(distance, smoothly, ride);
        }
      };

      const applyKeyboardGeometry = (geometry: KeyboardGeometry) => {
        const obstructionTop = getObstructionTop();
        // A collapsed detent can extend the body below the layout viewport even
        // after the keyboard closes, so body overlap alone cannot identify
        // recovery. Once the visual viewport is full height again, release the
        // retained keyboard layout unconditionally.
        if (isVisualViewportRecovered()) {
          clearKeyboardLayout();
          return;
        }
        const overlap = overlapOf(geometry.bodyBottom, obstructionTop);
        if (overlap === 0) {
          clearKeyboardLayout();
          return;
        }

        const inset = Math.max(
          0,
          geometry.bodyBottom - (obstructionTop - offset),
        );
        writeInset(inset);
      };

      // Take every focus move into a field over before the browser performs it
      // (refuseFocusReveal). That handler does not reveal the field. Focusing
      // it raises focusin, and the viewport report that follows the keyboard
      // raises another. Both schedule the reveal below, which knows the safe
      // area and scrolls only the sheet's own body.
      //
      // The keyboard's Done button parks focus on the body. The handler parks
      // focus that leaves for nothing on the sheet instead. Then a second tap on
      // the same field is still a move the handler sees. Left on the body, the field
      // is already `document.activeElement` on the next tap. Then no blur fires,
      // and the browser reveals the field its own way. This applies only while
      // the sheet is open. Closing blurs the field too, and no next tap needs a
      // claim. The host restores focus to whatever opened the sheet.
      const claimFocusTransitions = () =>
        refuseFocusReveal(document, {
          isActive: () => isExpandedRef.current,
          claim: destination => findTextEntryControl(destination, body),
          park: origin => {
            if (isOpenRef.current && findTextEntryControl(origin, body)) {
              sheet.focus({preventScroll: true});
            }
          },
        });

      const revealFocusedControl = (atReport = false) => {
        // Through a hide the sheet rides, its layout holds until the end.
        if (heldHide != null && heldHide.onReveal?.() !== true) {
          return;
        }
        const obstructionTop = getObstructionTop();
        const activeElement = document.activeElement;
        const focusedControl =
          activeElement instanceof HTMLElement &&
          body.contains(activeElement) &&
          isTextEntryControl(activeElement)
            ? activeElement
            : null;
        // The keyboard can close while its field keeps focus, as a downward
        // dismissal does on iOS. The full clear puts back the inset and the
        // body's scroll. The hook then reveals the field still focused in the
        // restored body, because it may not be the field that opened the
        // keyboard.
        if (hasKeyboardLayoutRef.current && isVisualViewportRecovered()) {
          const settle = keepDrawnPlace();
          clearKeyboardLayout();
          if (isExpandedRef.current && focusedControl != null) {
            scrollControlIntoSafeArea(focusedControl, false);
          }
          settle();
          return;
        }
        if (!isExpandedRef.current || focusedControl == null) {
          if (retainKeyboardLayoutRef.current && keyboardGeometry) {
            const settle = keepDrawnPlace();
            applyKeyboardGeometry(keyboardGeometry);
            settle();
            // Focus left for a control that brings up no keyboard, inside an
            // open shadow root too, so the keyboard goes down now. A select's
            // picker takes the keyboard's place instead. A frame or a custom
            // element can hold a field the page cannot see, which keeps it up.
            if (
              isExpandedRef.current &&
              hasKeyboardLayoutRef.current &&
              !mayKeepKeyboard()
            ) {
              holdThroughUnguidedHide();
            }
            return;
          }
          clearKeyboardLayout();
          return;
        }

        // An iOS keyboard dismissed by a drag can leave its accessory bar, so
        // the visual viewport grows short of full height. The body goes back
        // to its scroll from before the keyboard as soon as that starts. The
        // reveal below still clears what covers a low field. The new top is
        // kept, so a later content change does not repeat this.
        if (
          hasKeyboardLayoutRef.current &&
          keyboardObstructionTop != null &&
          obstructionTop > keyboardObstructionTop + 0.5 &&
          bodyScrollTopAtKeyboard != null
        ) {
          smoothTarget = null;
          body.scrollTop = bodyScrollTopAtKeyboard;
          keyboardObstructionTop = obstructionTop;
        }

        retainKeyboardLayoutRef.current = false;

        const measuredBodyRect = body.getBoundingClientRect();
        const overlap = overlapOf(measuredBodyRect.bottom, obstructionTop);
        // The extra clearance leaves space for mobile suggestion UI, but only
        // while the visual viewport actually overlaps the sheet. With no
        // obstruction, ordinary desktop and hardware-keyboard focus must not
        // shift an already visible control.
        const clearance = overlap > 0 ? offset : 0;
        keyboardGeometry =
          overlap > 0
            ? {
                bodyBottom: measuredBodyRect.bottom,
              }
            : null;
        // Where the document sits with the keyboard up and nothing yet shifted:
        // the position handleDocumentScroll returns to. Captured on the
        // transition only — a reveal that runs after the browser has already
        // scrolled would otherwise record the shifted position as correct.
        if (overlap > 0 && !hasKeyboardLayoutRef.current) {
          keyboardObstructionTop = obstructionTop;
          bodyScrollTopAtKeyboard = body.scrollTop;
          if (isPageScrollLocked) {
            documentScrollAtKeyboard = {x: window.scrollX, y: window.scrollY};
          }
        }
        hasKeyboardLayoutRef.current = overlap > 0;

        const inset =
          overlap > 0
            ? Math.max(
                0,
                measuredBodyRect.bottom - (obstructionTop - clearance),
              )
            : 0;
        writeInset(inset);

        scrollControlIntoSafeArea(
          focusedControl,
          overlap > 0 && !revealsAtReport.has(window),
          overlap > 0 ? showOnSlide(atReport) : null,
        );
      };

      // Where the body's scroll rests once the keyboard is gone, as
      // revealFocusedControl leaves it. The clear puts back the scroll from
      // before the keyboard, within the range left once the inset drops. The
      // reveal then brings a field that keeps focus into the body's view.
      const restingScrollTop = (): number => {
        const scrollTop = body.scrollTop;
        const maxAtRest = Math.max(
          0,
          body.scrollHeight - insetRange - body.clientHeight,
        );
        let resting = Math.min(maxAtRest, bodyScrollTopAtKeyboard ?? scrollTop);
        const active = document.activeElement;
        if (
          isExpandedRef.current &&
          active instanceof HTMLElement &&
          body.contains(active) &&
          isTextEntryControl(active)
        ) {
          const bodyRect = body.getBoundingClientRect();
          const rect = active.getBoundingClientRect();
          // Where the layout puts the control at the resting scroll.
          const shift = scrollTop - resting - rideOffset();
          if (rect.bottom + shift > bodyRect.bottom) {
            resting += rect.bottom + shift - bodyRect.bottom;
          } else if (rect.top + shift < bodyRect.top) {
            resting += rect.top + shift - bodyRect.top;
          }
          resting = Math.min(maxAtRest, Math.max(0, resting));
        }
        return resting;
      };

      // Without the guide, as in iOS Safari and Firefox for Android, nothing
      // publishes the keyboard's slide down. iOS Safari sends one report once
      // the keyboard is gone, about half a second after a blur. Under a coarse
      // primary pointer, the content then moves on UIKit's keyboard spring,
      // never at once.
      const unguidedAnimator = (): Animator | null => {
        const content = body.firstElementChild;
        return ownsFocusTransitions &&
          guide == null &&
          content instanceof HTMLElement
          ? animatorFor(content)
          : null;
      };
      const rideKeyboardSpring = (
        animator: Animator,
        y: number,
      ): MotionHandle => {
        return animator.animate({y}, {spring: KEYBOARD_SPRING});
      };
      // Keeps the content drawn where it is across a change of the body's
      // scroll, then rides it to its new place on the keyboard's spring. A
      // report of the keyboard gone, with no ride under way, moves the content
      // this way.
      const keepDrawnPlace = (): (() => void) => {
        const animator = unguidedAnimator();
        if (animator == null) {
          return () => {};
        }
        const drawnBefore = animator.get('y') - body.scrollTop;
        return () => {
          const y = drawnBefore + body.scrollTop;
          if (Math.abs(y - animator.get('y')) < 0.5) {
            return;
          }
          animator.set({y});
          void rideKeyboardSpring(animator, 0);
        };
      };

      // A field that loses focus to nothing takes the keyboard down. Without
      // the guide, the content rides down to its resting scroll from the blur.
      // It rides on the keyboard's spring, as the keyboard does. The inset and
      // the scroll stay meanwhile. Once the keyboard is gone (its report), the
      // inset drops and the scroll goes back with the translate in one commit.
      // So nothing moves then. A ride not yet landed goes on from there at the
      // same speed. A control that takes focus first and brings up a keyboard
      // or a picker keeps that space covered, so the content rides back up. A
      // field inside an open shadow root does too, and so can a frame or a
      // custom element, whose field the page cannot see.
      const holdThroughUnguidedHide = () => {
        const animator = unguidedAnimator();
        if (animator == null || heldHide != null) {
          return;
        }
        const drop = body.scrollTop - restingScrollTop();
        if (drop === 0) {
          return;
        }
        const hold = {
          release: () => {
            if (heldHide === hold) {
              heldHide = null;
            }
          },
          onReveal: () => {
            const active = document.activeElement;
            if (
              active instanceof HTMLElement &&
              body.contains(active) &&
              mayKeepKeyboard()
            ) {
              hold.release();
              void rideKeyboardSpring(animator, 0);
              return true;
            }
            if (isVisualViewportRecovered()) {
              hold.release();
              const y = animator.get('y');
              const velocity = animator.getVelocity('y');
              const scrollBefore = body.scrollTop;
              clearKeyboardLayout();
              // The scroll's drop moved the layout down by `shift`.
              const shift = scrollBefore - body.scrollTop;
              if (Math.abs(y - shift) < 0.5) {
                animator.set({y: 0});
              } else {
                animator.set({y: y - shift});
                void animator.animate(
                  {y: 0},
                  {spring: KEYBOARD_SPRING, velocity: {y: velocity}},
                );
              }
            }
            return false;
          },
        };
        heldHide = hold;
        void rideKeyboardSpring(animator, drop);
      };

      // Through a hide on the keyboard's slide, the inset stays, so nothing
      // drops while the keyboard still covers the sheet's bottom. The content
      // rides down on the hide's curve by the scroll the body drops at rest. At
      // rest, the inset drops, the scroll goes back, and the translate clears in
      // one commit. A busy page reads Chrome's report of the keyboard gone
      // after the slide. Until then the content stays where the slide leaves
      // it, and the report commits.
      const holdInsetThrough = (transition: KeyboardTransition) => {
        heldHide?.release();
        const animator = contentAnimator();
        const drop = body.scrollTop - restingScrollTop();
        const handle =
          animator != null && drop !== 0
            ? rideKeyboard(animator, {y: drop}, transition)
            : null;
        let timer: ReturnType<typeof setTimeout> | undefined;
        let landed = false;
        const commit = () => {
          revealFocusedControl();
          animator?.set({y: 0});
        };
        const hold = {
          release: () => {
            clearTimeout(timer);
            if (heldHide === hold) {
              heldHide = null;
            }
          },
          onReveal: () => {
            if (landed && isVisualViewportRecovered()) {
              hold.release();
              commit();
            }
            return false;
          },
        };
        heldHide = hold;
        const land = () => {
          if (heldHide !== hold) {
            return;
          }
          landed = true;
          if (hasKeyboardLayoutRef.current && !isVisualViewportRecovered()) {
            return;
          }
          hold.release();
          commit();
        };
        if (handle == null) {
          const end = transition.start + (transition.curve?.durationMs ?? 0);
          timer = setTimeout(land, Math.max(0, end - performance.now()));
        } else {
          void handle.finished.then(land);
        }
      };
      const unsubscribeGuide = guide?.subscribe(transition => {
        // A jump lands with the reports: only a slide rides.
        if (transition.curve == null) {
          return;
        }
        if (transition.kind === 'hide') {
          if (hasKeyboardLayoutRef.current && transition.animated) {
            holdInsetThrough(transition);
          }
          return;
        }
        if (heldHide != null) {
          // The keyboard comes back before it is down (focus returns): the
          // inset never left, so the content rides back to its place with it.
          heldHide.release();
          const animator = contentAnimator();
          if (animator != null) {
            rideKeyboard(animator, {y: 0}, transition);
          }
        }
      });

      let animationFrame = 0;
      const scheduleReveal = () => {
        cancelAnimationFrame(animationFrame);
        animationFrame = requestAnimationFrame(() => revealFocusedControl());
      };

      // Resuming the app re-reveals the focused field with no focus event to
      // claim. The reveal above never runs, and the document scrolls with the
      // fixed sheet. Put that scroll back on the event that reports it, and
      // reveal again inside the sheet.
      //
      // This applies only while the page is locked. Only then can a document
      // scroll not be the user's own. Behind a non-modal sheet the page stays
      // scrollable, and a revert there would fight the user.
      const handleDocumentScroll = () => {
        const expected = documentScrollAtKeyboard;
        if (
          expected == null ||
          (window.scrollX === expected.x && window.scrollY === expected.y)
        ) {
          return;
        }
        window.scrollTo(expected.x, expected.y);
        const activeElement = document.activeElement;
        if (
          activeElement instanceof HTMLElement &&
          body.contains(activeElement) &&
          isTextEntryControl(activeElement)
        ) {
          scrollControlIntoSafeArea(activeElement, false);
        }
      };

      let stopObserving: (() => void)[] = [];
      const refreshObservedLayout = () => {
        if (typeof ResizeObserver === 'undefined') {
          return;
        }
        for (const stop of stopObserving) {
          stop();
        }
        stopObserving = [];

        // Body and sheet box changes include public height and xstyle updates.
        // The inset pseudo-element is the content box's last box. Where the
        // content grows with it, the observation runs the reveal again. The
        // reveal computes the same inset from the body's unchanged box, so
        // nothing feeds back into the sheet's geometry.
        const targets = new Set<Element>([body, sheet]);
        for (const child of body.children) {
          targets.add(child);
        }
        const activeElement = document.activeElement;
        if (
          activeElement instanceof HTMLElement &&
          body.contains(activeElement)
        ) {
          for (
            let element: HTMLElement | null = activeElement;
            element && element !== body;
            element = element.parentElement
          ) {
            targets.add(element);
          }
        }
        for (const target of targets) {
          stopObserving.push(observeResize(target, scheduleReveal));
        }
      };
      const mutationObserver =
        typeof MutationObserver === 'undefined'
          ? null
          : new MutationObserver(records => {
              // Skip the sheet's own attribute writes on the body. Consumer
              // DOM, text, class, style, or visibility changes can all move the
              // focused control without a viewport event. The inset's write on
              // the content box schedules one more reveal, which finds the same
              // inset and settles.
              if (
                records.every(
                  record =>
                    record.type === 'attributes' && record.target === body,
                )
              ) {
                return;
              }
              refreshObservedLayout();
              scheduleReveal();
            });
      const handleFocusIn = () => {
        refreshObservedLayout();
        scheduleReveal();
      };
      const handleFocusOut = () => {
        // Keep the added scroll range while the keyboard animates away. A focus
        // transition to another text-entry control cancels this in focusin.
        retainKeyboardLayoutRef.current = hasKeyboardLayoutRef.current;
        scheduleReveal();
      };
      const handleSheetTransitionEnd = (event: TransitionEvent) => {
        if (event.target === sheet && event.propertyName === 'transform') {
          scheduleReveal();
        }
      };

      const stopClaiming = ownsFocusTransitions
        ? claimFocusTransitions()
        : null;
      // The hook reveals a keyboard report in its own frame, not the next. A browser
      // that reveals a focused field itself pans the visual viewport to it a few
      // frames after the report. It does so if the keyboard still covers the
      // field. Such a pan moves the visual viewport down within the layout
      // viewport, with no touch, document scroll or zoom since the report. Once
      // the sheet lands the field itself, the hook puts the pan back: it scrolls
      // the full-viewport dialog's top into view. On every later report, the field
      // lands at once.
      let lastHeight = getKeyboardHeight(window);
      // Under a coarse primary pointer only: the watch reads touches, and an
      // on-screen keyboard's pan comes with a touch screen.
      const revealPan = isTouch
        ? watchRevealPan(window, {
            owns: focused =>
              hasKeyboardLayoutRef.current && body.contains(focused),
            // The reader's own scroll may stop a smooth reveal short: forget
            // where it was going.
            onTouch: () => {
              smoothTarget = null;
            },
          })
        : null;
      // Every keyboard report reaches the reveal through the keyboard module's
      // one set of listeners.
      const unsubscribe = subscribeKeyboardHeight(window, event => {
        if (event.type !== 'viewport') {
          return;
        }
        if (event.height !== lastHeight) {
          lastHeight = event.height;
          revealPan?.report();
          cancelAnimationFrame(animationFrame);
          revealFocusedControl(true);
          return;
        }
        if (revealPan?.isRevealPan(event.height) === true) {
          revealsAtReport.add(window);
          cancelAnimationFrame(animationFrame);
          // A smooth reveal still under way lands the field where it is going.
          // Another scroll on top of it would overshoot in Firefox, which keeps
          // adding a smooth scrollBy's distance after an instant scroll. The
          // field ended 244 px too high there. With none under way, the field
          // lands at once.
          const distanceLeft = smoothDistanceLeft();
          if (distanceLeft === 0) {
            revealFocusedControl();
          }
          // The hook puts the pan back only if the sheet holds the field above
          // the keyboard with its own scroller. Rects are in layout-viewport
          // coordinates, which the pan does not move. A ride still draws the
          // field lower than its layout, so its offset does not count. A field
          // the sheet cannot bring up keeps the browser's reveal.
          const activeElement = document.activeElement;
          const dialog = sheet.closest('dialog');
          if (
            dialog != null &&
            activeElement instanceof HTMLElement &&
            activeElement.getBoundingClientRect().bottom -
              rideOffset() -
              distanceLeft <=
              getObstructionTop()
          ) {
            // The full-viewport dialog is fixed at the layout viewport's top.
            revealPan?.putBack(dialog);
          }
          return;
        }
        scheduleReveal();
      });
      body.addEventListener('focusin', handleFocusIn);
      body.addEventListener('focusout', handleFocusOut);
      sheet.addEventListener('transitionend', handleSheetTransitionEnd);
      // The window's capture phase hears every element's scroll too, and only
      // the page's own scroll moves the document.
      const stopDocumentScroll = subscribeInput(window, 'scroll', event => {
        const target = event.target;
        if (!isNode(target) || isDocument(target)) {
          handleDocumentScroll();
        }
      });
      mutationObserver?.observe(body, {
        attributes: true,
        characterData: true,
        childList: true,
        subtree: true,
      });
      refreshObservedLayout();
      // The dialog enters the top layer in a later effect. Wait until the next
      // frame so flex geometry is final before measuring the body.
      scheduleReveal();

      return () => {
        unregister();
        cancelAnimationFrame(animationFrame);
        stopClaiming?.();
        unsubscribe();
        unsubscribeGuide?.();
        heldHide?.release();
        (contentAnimator() ?? unguidedAnimator())?.set({y: 0});
        revealPan?.stop();
        body.removeEventListener('focusin', handleFocusIn);
        body.removeEventListener('focusout', handleFocusOut);
        sheet.removeEventListener('transitionend', handleSheetTransitionEnd);
        stopDocumentScroll();
        for (const stop of stopObserving) {
          stop();
        }
        mutationObserver?.disconnect();
        setKeyboardInset(0);
        hasKeyboardLayoutRef.current = false;
        retainKeyboardLayoutRef.current = false;
      };
    },
    `${isEnabled}|${reservesInset}|${isPageScrollLocked}|${isTouch}|${offset}`,
  );
  return {inset: keyboardInset, dismiss};
}