Skip to content

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

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

/**
 * @file keyboardTarget.ts
 * @input The keyboard module's reports and focus claim, the layout guide,
 *   rideKeyboard and the shared animator
 * @output The keyboard targets: their registry, followKeyboard for a docked
 *   or scrolling target, and keepFieldAboveKeyboard, a covered field's path.
 *   Also followsKeyboard, the touch gate, and deliverTap, a tap's delivery
 * @position Keyboard module, internal to core. useMobileKeyboard calls it.
 *
 * SYNC: When modified, update /packages/core/src/keyboard/README.md
 */

import {animatorFor, type Animator} from '../motion/animator';
import {isCoarsePointer} from '../utils/coarsePointer';
import {subscribeInput} from '../utils/inputStream';
import {layoutViewportHeight} from '../utils/layoutViewport';
import {nearestScroller, scrollingAncestor} from '../utils/scrollingAncestor';
import {
  KEYBOARD_EPSILON,
  claimTapFocus,
  findTextEntryControl,
  focusAtPoint,
  getKeyboardHeight,
  isKeyboardMeasurable,
  isTextEntryControl,
  refuseFocusReveal,
  subscribeKeyboardHeight,
  watchRevealPan,
} from './keyboardHeight';
import {getKeyboardLayoutGuide, keyboardProfileOf} from './keyboardLayoutGuide';
import type {KeyboardTransition} from './keyboardModel';
import {distanceIntoBand} from './revealBand';
import {rideKeyboard} from './rideKeyboard';

/**
 * How a target keeps a focused field above the keyboard: `'reveal'` scrolls
 * the field into place, and `'ride'` moves the target with the keyboard.
 */
export type KeyboardMove = 'reveal' | 'ride';

/**
 * The gap a field keeps above the keyboard's top edge, CSS px: the same
 * clearance a layer keeps above the keyboard.
 */
export const FIELD_OFFSET = 10;

// Targets that keep their own fields above the keyboard. A field inside one
// moves nothing itself, so nothing moves twice.
const targets = new WeakSet<Element>();

/** Registers `element` as a keyboard target until the returned call. */
export function registerKeyboardTarget(element: Element): () => void {
  targets.add(element);
  return () => {
    targets.delete(element);
  };
}

export {nearestScroller};

/** Whether a registered target holds `element`. */
export function isInsideKeyboardTarget(element: Element): boolean {
  for (
    let node = element.parentElement;
    node != null;
    node = node.parentElement
  ) {
    if (targets.has(node)) {
      return true;
    }
  }
  return false;
}

// The element's bottom edge where layout puts it, without the ride's move.
function restingBottom(element: Element, animator: Animator): number {
  return element.getBoundingClientRect().bottom - animator.get('y');
}

/**
 * How far a ride has moved `element` from where its layout puts it, as the
 * page draws it now, CSS px. Reading the style creates no animator.
 */
export function drawnOffsetOf(element: Element): number {
  const view = element.ownerDocument.defaultView;
  const translate = view?.getComputedStyle(element).translate ?? '';
  return parseFloat(translate.split(' ')[1] ?? '') || 0;
}

/** Where an element sits among fixed containers (see fixedContainerOf). */
export type FixedContainer =
  {docked: HTMLElement} | 'fills-viewport' | 'floating' | null;

/**
 * How the nearest fixed-position ancestor of `element` meets the keyboard. It
 * is docked when its layout puts its bottom at the layout viewport's bottom
 * edge. It can also fill the viewport, as a dialog does, or float above the
 * bottom edge. Null with no fixed ancestor, as in page content.
 */
export function fixedContainerOf(element: Element): FixedContainer {
  const view = element.ownerDocument.defaultView;
  const node = nearestFixedAncestor(element);
  if (view == null || node == null) {
    return null;
  }
  const dock = dockOf(node, view);
  return dock === 'docked' ? {docked: node} : dock;
}

function nearestFixedAncestor(element: Element): HTMLElement | null {
  const view = element.ownerDocument.defaultView;
  if (view == null) {
    return null;
  }
  for (
    let node = element.parentElement;
    node != null;
    node = node.parentElement
  ) {
    if (view.getComputedStyle(node).position === 'fixed') {
      return node;
    }
  }
  return null;
}

// How far the element's own `transform` moves it down, CSS px: the
// translation of its computed matrix. An app may lift its bar this way.
function transformOffsetOf(element: Element, view: Window): number {
  const transform = view.getComputedStyle(element).transform;
  const matrix = /^matrix(3d)?\(([^)]*)\)$/.exec(transform);
  if (matrix == null) {
    return 0;
  }
  const values = (matrix[2] ?? '').split(',').map(Number);
  const y = matrix[1] == null ? values[5] : values[13];
  return y != null && Number.isFinite(y) ? y : 0;
}

// How a fixed-position `node` meets the keyboard, by its layout box: without
// the ride's translate or any transform the app sets on it.
function dockOf(
  node: HTMLElement,
  view: Window,
): 'docked' | 'fills-viewport' | 'floating' {
  const viewportBottom = layoutViewportHeight(view);
  const box = node.getBoundingClientRect();
  if (box.height >= viewportBottom - KEYBOARD_EPSILON) {
    return 'fills-viewport';
  }
  const bottom =
    box.bottom - drawnOffsetOf(node) - transformOffsetOf(node, view);
  return Math.abs(viewportBottom - bottom) <= KEYBOARD_EPSILON
    ? 'docked'
    : 'floating';
}

// The animator each ridden target moves with. A translate it draws is the
// ride's, not the app's.
const riddenAnimators = new WeakMap<HTMLElement, Animator>();

// Whether the app positions `node` with its own `translate`, such as `-50% 0`
// to centre it. A translate the ride draws is not the app's.
function hasOwnTranslate(node: HTMLElement, view: Window): boolean {
  const translate = view.getComputedStyle(node).translate;
  if (translate === '' || translate === 'none') {
    return false;
  }
  const ride = riddenAnimators.get(node);
  return ride == null || ride.get('y') === 0;
}

const POSITION_PROPERTIES = new Set([
  'transform',
  'translate',
  'top',
  'bottom',
  'inset',
  'inset-block',
  'inset-block-start',
  'inset-block-end',
]);

const KEYFRAME_FIELDS = new Set([
  'offset',
  'computedOffset',
  'easing',
  'composite',
]);

// The CSS properties a running animation changes, in their CSS names.
function animatedProperties(animation: Animation): string[] {
  if ('transitionProperty' in animation) {
    return [String(animation.transitionProperty)];
  }
  const effect = animation.effect;
  if (effect == null || !('getKeyframes' in effect)) {
    return [];
  }
  const names = new Set<string>();
  for (const frame of (effect as KeyframeEffect).getKeyframes()) {
    for (const key of Object.keys(frame)) {
      if (!KEYFRAME_FIELDS.has(key)) {
        names.add(key.replace(/[A-Z]/g, letter => `-${letter.toLowerCase()}`));
      }
    }
  }
  return [...names];
}

// Whether the app is moving `node` itself right now with a CSS transition or
// animation on its position. A script animation is not seen: an app that moves
// its bar from script keeps it clear with its own `translate`. On a target the
// ride moves, a transition of `translate` alone is the ride's. The target's
// `transition` starts it when the ride writes the property. The app sets no
// `translate` on a target the ride moves.
function isMovedByApp(node: HTMLElement): boolean {
  if (typeof node.getAnimations !== 'function') {
    return false;
  }
  const isRidden = riddenAnimators.has(node);
  return node.getAnimations().some(animation => {
    if (animation.playState !== 'running') {
      return false;
    }
    const isTransition = 'transitionProperty' in animation;
    if (!isTransition && !('animationName' in animation)) {
      return false;
    }
    const properties = animatedProperties(animation);
    if (
      isRidden &&
      isTransition &&
      properties.every(property => property === 'translate')
    ) {
      return false;
    }
    return properties.some(property => POSITION_PROPERTIES.has(property));
  });
}

function isDockedContainer(node: HTMLElement): boolean {
  const view = node.ownerDocument.defaultView;
  return (
    view != null &&
    view.getComputedStyle(node).position === 'fixed' &&
    dockOf(node, view) === 'docked'
  );
}

/**
 * The fixed container docked at the viewport's bottom edge that holds
 * `element`, or null. A container that fills the viewport or floats above
 * the bottom edge is never one.
 */
export function dockedAncestor(element: Element): HTMLElement | null {
  const container = fixedContainerOf(element);
  return container != null && typeof container === 'object'
    ? container.docked
    : null;
}

/**
 * How far a bottom edge at `bottom` sits under the keyboard's top, plus
 * `offset`, CSS px; 0 when it clears it. An overlap under one CSS px is the
 * viewport's rounding, not an obstruction.
 */
export function coveredBy(
  bottom: number,
  height: number,
  offset: number,
  win: Window,
): number {
  const covered = bottom + offset - (layoutViewportHeight(win) - height);
  return height > 0 && covered > KEYBOARD_EPSILON ? covered : 0;
}

// The lift of a ridden target. A Core host (`isHostOwned`) clears the keyboard
// with a focused field inside, the field `offset` above it. An app's docked
// container moves only by the part of it the keyboard still covers. That part
// is measured after any lift the app gives it. So a bar the app already moves
// with the keyboard is not moved again. It is not moved at all once its layout
// leaves the bottom edge. Nor is it moved while the app runs its own CSS
// transition or animation on its position. When a field outside has focus, the
// target rests under the keyboard, so it never covers that field. When focus
// left for nothing, a lifted target rides down with the keyboard, and one at
// rest stays there.
function liftFor(
  target: HTMLElement,
  animator: Animator,
  height: number,
  offset: number,
  win: Window,
  isHostOwned: boolean,
): number {
  // An app's bar it is moving itself is left to the app, never lifted twice.
  if (!isHostOwned && (!isDockedContainer(target) || isMovedByApp(target))) {
    return 0;
  }
  const targetCovered = coveredBy(
    restingBottom(target, animator),
    height,
    0,
    win,
  );
  const field = focusedFieldIn(target);
  if (field != null) {
    if (!isHostOwned) {
      return targetCovered;
    }
    const fieldCovered = coveredBy(
      restingBottom(field, animator),
      height,
      offset,
      win,
    );
    return Math.max(targetCovered, fieldCovered);
  }
  if (isTextEntryControl(target.ownerDocument.activeElement)) {
    return 0;
  }
  return animator.get('y') < 0 ? targetCovered : 0;
}

// Scrolls `scroller` by `distance` px, up or down, at once. A smooth scroll
// would leave the field covered when Chrome checks it.
function scrollBy(scroller: Element, distance: number, win: Window): void {
  const doc = scroller.ownerDocument;
  if (scroller === (doc.scrollingElement ?? doc.documentElement)) {
    win.scrollBy({top: distance, behavior: 'instant'});
  } else {
    scroller.scrollTop += distance;
  }
}

// How far `field` sits outside the band it must be in. The band is inside its
// scroller's box and the viewport, and `offset` above the keyboard while one
// shows. A move not yet written shifts the field and its scroller by `shift`.
function revealDistance(
  field: Element,
  scroller: Element,
  height: number,
  offset: number,
  win: Window,
  shift = 0,
): number {
  const doc = field.ownerDocument;
  const keyboardTop = layoutViewportHeight(win) - height;
  let safeTop = 0;
  let safeBottom =
    height > KEYBOARD_EPSILON ? keyboardTop - offset : keyboardTop;
  if (scroller !== (doc.scrollingElement ?? doc.documentElement)) {
    const box = scroller.getBoundingClientRect();
    safeTop = Math.max(safeTop, box.top + shift);
    safeBottom = Math.min(safeBottom, box.bottom + shift);
  }
  const box = field.getBoundingClientRect();
  return distanceIntoBand(
    box.top + shift,
    box.bottom + shift,
    safeTop,
    safeBottom,
  );
}

// Scrolls `field` into its band with its nearest scroller, the document
// included. Nothing else moves: a scroller that cannot scroll far enough
// leaves the rest of the field covered.
function reveal(
  field: Element,
  scroller: Element,
  height: number,
  offset: number,
  win: Window,
): void {
  const distance = revealDistance(field, scroller, height, offset, win);
  if (Math.abs(distance) > KEYBOARD_EPSILON) {
    scrollBy(scroller, distance, win);
  }
}

// Focuses the tapped field without the browser's reveal, then raises the
// tap's click. The claimed tap's cancelled `touchend` raises none, and a
// caller's `onClick` still runs once. The click is synthetic: its `isTrusted`
// is false. Like a real tap's click in Chrome and Safari, it is a touch
// `PointerEvent`, or a `MouseEvent` where no `PointerEvent` exists.
export function deliverTap(
  control: HTMLElement,
  x: number,
  y: number,
  touch: {screenX: number; screenY: number; identifier: number},
): void {
  focusAtPoint(control, x, y);
  // The field's own window's constructors, as a click in a frame has.
  const view = control.ownerDocument.defaultView;
  const init: MouseEventInit = {
    bubbles: true,
    cancelable: true,
    composed: true,
    detail: 1,
    clientX: x,
    clientY: y,
    screenX: touch.screenX,
    screenY: touch.screenY,
  };
  const PointerClick = view?.PointerEvent;
  const click =
    typeof PointerClick === 'function'
      ? new PointerClick('click', {
          ...init,
          pointerType: 'touch',
          isPrimary: true,
          pointerId: touch.identifier,
        })
      : new (view?.MouseEvent ?? MouseEvent)('click', init);
  control.dispatchEvent(click);
}

/**
 * Puts back a pan the browser makes on its own after a keyboard report. This
 * happens, for example, after a focus no claim saw: a script's `focus()` while
 * nothing has focus. The field sits in place already, so the pan only displaces
 * the page. Feed `report` each keyboard height the module reports; `owns`
 * says whether a focused element is one this watch keeps in place.
 */
export function watchPans(
  win: Window,
  owns: (focused: Element) => boolean,
): {report(height: number): void; stop(): void} {
  const watch = watchRevealPan(win, {owns});
  let lastHeight = getKeyboardHeight(win);
  return {
    report(height: number): void {
      if (height !== lastHeight) {
        lastHeight = height;
        watch.report();
      } else if (watch.isRevealPan(height)) {
        watch.putBack();
      }
    },
    stop: () => watch.stop(),
  };
}

function focusedFieldIn(target: Element): HTMLElement | null {
  const active = target.ownerDocument.activeElement;
  return active != null &&
    active !== target &&
    target.contains(active) &&
    isTextEntryControl(active)
    ? active
    : null;
}

/**
 * Whether `win` keeps fields above a keyboard at all: a top-level document
 * whose visual viewport shrinks for the keyboard, under a coarse primary
 * pointer.
 */
export function followsKeyboard(win: Window | null): win is Window {
  return win != null && isKeyboardMeasurable(win) && isCoarsePointer(win);
}

/** How followKeyboard moves its target. */
export interface FollowKeyboardOptions {
  move: KeyboardMove;
  /** The gap kept between the focused field and the keyboard, CSS px. */
  offset: number;
}

/**
 * Keeps the focused field inside `target` above the keyboard until the
 * returned call. `'ride'` moves `target` with the keyboard, on its slide
 * where the browser reports one. `'reveal'` scrolls the field into place in
 * `target`, a scroller. The target claims focus moves into its fields, so the
 * browser never pans the page to them, and it registers as a keyboard target.
 *
 * @example
 * ```
 * const stop = followKeyboard(dock, {move: 'ride', offset: FIELD_OFFSET});
 * ```
 */
export function followKeyboard(
  target: HTMLElement,
  {move, offset}: FollowKeyboardOptions,
): () => void {
  const doc = target.ownerDocument;
  const win = doc.defaultView;
  if (!followsKeyboard(win)) {
    return () => {};
  }
  const unregister = registerKeyboardTarget(target);
  const stopClaim = refuseFocusReveal(doc, {
    claim: destination =>
      destination instanceof win.HTMLElement &&
      destination !== target &&
      target.contains(destination) &&
      isTextEntryControl(destination)
        ? destination
        : null,
  });
  // A first tap moves focus from nothing, so no blur claims it. The tap
  // route focuses the field itself, without the browser's reveal.
  const stopTaps = claimTapFocus(target, {
    claim: touched => {
      const control = findTextEntryControl(touched, target);
      return control != null && control !== doc.activeElement ? control : null;
    },
    deliver: deliverTap,
  });
  const stopMoving: (isFinal?: boolean) => void =
    move === 'ride'
      ? rideWithKeyboard(target, offset, win, true)
      : revealWithKeyboard(
          target,
          () => focusedFieldIn(target),
          target,
          offset,
          win,
        );
  return () => {
    stopMoving(true);
    stopTaps();
    stopClaim();
    unregister();
  };
}

// Reveals the focused field `field()` returns through `scroller` when the
// keyboard's height changes, now, and when focus moves into `region` with the
// keyboard already up. Returns the call that stops it.
function revealWithKeyboard(
  region: Element,
  field: () => Element | null,
  scroller: Element,
  offset: number,
  win: Window,
): () => void {
  const revealNow = (height: number) => {
    const focused = field();
    if (focused != null) {
      reveal(focused, scroller, height, offset, win);
    }
  };
  const pans = watchPans(win, focused => focused === field());
  // A report within a pixel of the last height comes from a pan, a scroll or
  // a zoom's rounding. The field stays where the person put it.
  let lastHeight = getKeyboardHeight(win);
  const stopReports = subscribeKeyboardHeight(win, event => {
    if (event.type === 'viewport') {
      if (Math.abs(event.height - lastHeight) > KEYBOARD_EPSILON) {
        lastHeight = event.height;
        revealNow(event.height);
      }
      pans.report(event.height);
    }
  });
  const onFocusIn = () => revealNow(getKeyboardHeight(win));
  region.addEventListener('focusin', onFocusIn);
  revealNow(getKeyboardHeight(win));
  return () => {
    stopReports();
    pans.stop();
    region.removeEventListener('focusin', onFocusIn);
  };
}

// Whether `container`'s drawn box is taller than the room above a keyboard
// `height` px tall. A move to the keyboard's top would then push it off the
// top.
function exceedsRoom(
  container: HTMLElement,
  height: number,
  win: Window,
): boolean {
  return (
    height > KEYBOARD_EPSILON &&
    container.getBoundingClientRect().height >
      layoutViewportHeight(win) - height + KEYBOARD_EPSILON
  );
}

// The focused text field in `container` and its scroller there, or null
// when no field inside has focus or no scroller sits between them.
function focusedScrollerIn(
  container: HTMLElement,
): {field: Element; scroller: Element} | null {
  const field = focusedFieldIn(container);
  const scroller = field == null ? null : scrollingAncestor(field, container);
  return field == null || scroller == null ? null : {field, scroller};
}

// The lift of a container taller than the room above the keyboard with no
// scroller around its focused field. It lifts only as far as that field needs
// to sit `offset` above the keyboard. It never lifts past the container's own
// overlap, so a field near its top stays on screen. It keeps liftFor's guards:
// a container that left the bottom edge or that the app is moving gets none.
// When focus left for nothing it never rises and rides down as the keyboard
// goes.
function fieldLift(
  target: HTMLElement,
  animator: Animator,
  height: number,
  offset: number,
  win: Window,
): number {
  if (!isDockedContainer(target) || isMovedByApp(target)) {
    return 0;
  }
  const overlap = coveredBy(restingBottom(target, animator), height, 0, win);
  const field = focusedFieldIn(target);
  if (field == null) {
    // A text field outside has focus: the container rests under the keyboard.
    return isTextEntryControl(target.ownerDocument.activeElement)
      ? 0
      : Math.min(Math.max(0, -animator.get('y')), overlap);
  }
  const need = coveredBy(restingBottom(field, animator), height, offset, win);
  return Math.min(need, overlap);
}

// The ride that moves each target. A new ride on the same target takes over,
// whether the old one still rides or waits for the keyboard to go. So two never
// move one target, and the one taken over never moves it again.
const currentRides = new WeakMap<HTMLElement, () => void>();

// Rides `target` with the keyboard until the returned call (see liftFor).
// `isHostOwned` is true for a Core host's own element, and false for an app's
// docked container. Where the guide publishes the keyboard's slide, the
// target moves on it; elsewhere it takes each report's place. A blur's stop
// waits for the keyboard to go, so the target never drops under a keyboard
// still showing. A final stop, on detach, returns it at once.
function rideWithKeyboard(
  target: HTMLElement,
  offset: number,
  win: Window,
  isHostOwned: boolean,
): (isFinal?: boolean) => void {
  currentRides.get(target)?.();
  const animator = animatorFor(target);
  riddenAnimators.set(target, animator);
  const guide =
    keyboardProfileOf(win) === 'chromium' ? getKeyboardLayoutGuide(win) : null;
  // A ride moves the target while it rides or waits for the keyboard to go.
  // Once it ends, by itself or by a takeover, it never moves the target.
  let state: 'riding' | 'waiting' | 'ended' = 'riding';
  let stopReports: (() => void) | null = null;
  let stopGuide: (() => void) | null = null;
  const pans = watchPans(win, focused => target.contains(focused));
  let frame = 0;
  let pendingSlide: KeyboardTransition | null = null;
  const end = () => {
    state = 'ended';
    stopReports?.();
    stopGuide?.();
    stopReports = null;
    stopGuide = null;
    pans.stop();
    stopFocusIns();
    if (frame !== 0) {
      win.cancelAnimationFrame(frame);
      frame = 0;
    }
    if (currentRides.get(target) === end) {
      currentRides.delete(target);
    }
  };
  currentRides.set(target, end);
  const place = (height: number, transition: KeyboardTransition | null) => {
    if (state === 'ended') {
      return;
    }
    // An app's container taller than the room above the keyboard never rides
    // the whole overlap. A scroller in it reveals the focused field instead.
    // With none, it rides only as far as that field needs.
    const isTooTall = !isHostOwned && exceedsRoom(target, height, win);
    const inside = isTooTall ? focusedScrollerIn(target) : null;
    const lift = !isTooTall
      ? liftFor(target, animator, height, offset, win, isHostOwned)
      : inside == null
        ? fieldLift(target, animator, height, offset, win)
        : 0;
    // Rest is y 0, never -0, so the animator releases its translate there.
    const y = lift > 0 ? -lift : 0;
    // Every box is read before anything is written. The scroller moves with
    // the container, so the reveal measures the field where the move leaves
    // it.
    const revealBy =
      inside == null
        ? 0
        : revealDistance(
            inside.field,
            inside.scroller,
            height,
            offset,
            win,
            y - animator.get('y'),
          );
    if (inside != null && Math.abs(revealBy) > KEYBOARD_EPSILON) {
      scrollBy(inside.scroller, revealBy, win);
    }
    if (y !== 0 || animator.get('y') !== 0) {
      if (transition == null) {
        animator.set({y});
      } else {
        rideKeyboard(animator, {y}, transition);
      }
    }
    // The target is now at rest, or rides there on the keyboard's slide, so
    // a stopped ride only stops listening. A set here would cut the slide.
    if (state === 'waiting' && height <= KEYBOARD_EPSILON) {
      end();
    }
  };
  // A report, a slide or a focus move places the target on the next frame, once
  // every listener of that event has run. An app that moves its own bar in its
  // listener has moved it by then. So the lift measures only what the keyboard
  // still covers, and never stacks on the app's.
  const placeOnNextFrame = (slide: KeyboardTransition | null) => {
    if (slide != null) {
      pendingSlide = slide;
    }
    if (frame !== 0) {
      return;
    }
    frame = win.requestAnimationFrame(() => {
      frame = 0;
      const next = pendingSlide;
      pendingSlide = null;
      place(next?.to ?? guide?.inset ?? getKeyboardHeight(win), next);
    });
  };
  if (guide != null) {
    stopGuide = guide.subscribe(placeOnNextFrame);
  } else {
    stopReports = subscribeKeyboardHeight(win, event => {
      if (event.type === 'viewport') {
        placeOnNextFrame(null);
        pans.report(event.height);
      }
    });
  }
  // A field gaining focus with the keyboard up places the target. A blur to
  // nothing waits for the keyboard's own report or slide, so the target rides
  // down from where it is.
  const stopFocusIns = subscribeInput(win, 'focusin', () =>
    placeOnNextFrame(null),
  );
  placeOnNextFrame(null);
  return (isFinal = false) => {
    if (state === 'ended') {
      return;
    }
    if (isFinal || getKeyboardHeight(win) <= KEYBOARD_EPSILON) {
      end();
      if (animator.get('y') !== 0) {
        animator.set({y: 0});
      }
    } else {
      state = 'waiting';
    }
  };
}

/** How keepFieldAboveKeyboard keeps its field clear. */
export interface KeepFieldAboveKeyboardOptions {
  /** The gap kept between the field and the keyboard, CSS px. */
  offset?: number;
}

// The placement of `field` when it gains focus. A docked container rides.
// Page content, or a fixed container the app positions, reveals the field
// through a scroller. Null keeps the browser's reveal: inside a keyboard
// target, or with no such scroller.
function placementOf(
  field: HTMLElement,
): {ride: HTMLElement} | {reveal: Element} | null {
  if (isInsideKeyboardTarget(field)) {
    return null;
  }
  const container = fixedContainerOf(field);
  if (container === 'floating' || container === 'fills-viewport') {
    return revealWithin(field, nearestFixedAncestor(field));
  }
  if (container == null) {
    // A page with nothing to scroll keeps the browser's own reveal: a claim
    // there would leave the field under the keyboard.
    const scroller = nearestScroller(field);
    return scroller.scrollHeight > scroller.clientHeight
      ? {reveal: scroller}
      : null;
  }
  // A bar the app positions with its own `translate` does not ride: the ride
  // would replace that translate.
  const view = field.ownerDocument.defaultView;
  return view != null && hasOwnTranslate(container.docked, view)
    ? revealWithin(field, container.docked)
    : {ride: container.docked};
}

// A reveal by the scroller between `field` and the fixed `container` the app
// positions, or null when no scroller sits between them.
function revealWithin(
  field: HTMLElement,
  container: HTMLElement | null,
): {reveal: Element} | null {
  const scroller =
    container == null ? null : scrollingAncestor(field, container);
  return scroller == null ? null : {reveal: scroller};
}

/**
 * A field's own path until the returned call. When the field gains focus, it
 * decides where it is. Docked at the viewport's bottom, its fixed container
 * moves up by the part of it the keyboard still covers. In scrolling content,
 * its nearest scroller, the document included, brings it into view, above the
 * keyboard while one shows. A docked container taller than the room above the
 * keyboard never rides its whole overlap. Its scroller there brings the field
 * up instead, and with none it rides only as far as the field needs. A fixed
 * container the app positions fills the viewport, floats above the bottom edge,
 * or sets its own `translate`. In one, a scroller between the field and the
 * container brings it up. A focus move or a tap into the field arrives without
 * the browser's reveal there, so the page never pans for it. Inside a keyboard
 * target, or in such a container with no scroller around the field, the path
 * does nothing and the browser's own reveal stays.
 *
 * @example
 * ```
 * const stop = keepFieldAboveKeyboard(input);
 * ```
 */
export function keepFieldAboveKeyboard(
  field: HTMLElement,
  {offset = FIELD_OFFSET}: KeepFieldAboveKeyboardOptions = {},
): () => void {
  const doc = field.ownerDocument;
  const win = doc.defaultView;
  if (!followsKeyboard(win)) {
    return () => {};
  }
  const stopClaim = refuseFocusReveal(doc, {
    claim: destination =>
      destination === field && placementOf(field) != null ? field : null,
  });
  // A first tap moves focus from nothing, so no blur claims it.
  const stopTaps = claimTapFocus(field, {
    claim: () =>
      doc.activeElement !== field && placementOf(field) != null ? field : null,
    deliver: deliverTap,
  });
  let stopSession: ((isFinal?: boolean) => void) | null = null;
  // A ride a blur stopped can still wait for the keyboard to go; a detach
  // ends it at once.
  let stoppedSession: ((isFinal?: boolean) => void) | null = null;
  const onFocus = () => {
    // A claimed focus move raises a second focus event; the session stands.
    if (stopSession != null) {
      return;
    }
    const placement = placementOf(field);
    if (placement == null) {
      return;
    }
    stopSession =
      'ride' in placement
        ? rideWithKeyboard(placement.ride, offset, win, false)
        : revealWithKeyboard(
            field,
            () => (doc.activeElement === field ? field : null),
            placement.reveal,
            offset,
            win,
          );
  };
  const onBlur = () => {
    stopSession?.();
    stoppedSession = stopSession ?? stoppedSession;
    stopSession = null;
  };
  field.addEventListener('focus', onFocus);
  field.addEventListener('blur', onBlur);
  return () => {
    field.removeEventListener('focus', onFocus);
    field.removeEventListener('blur', onBlur);
    stopSession?.(true);
    stoppedSession?.(true);
    stopSession = null;
    stoppedSession = null;
    stopTaps();
    stopClaim();
  };
}