Skip to content

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

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

'use client';

/**
 * @file useLayerKeyboardClearance.ts
 * @input Whether an anchor-mode layer is open, its element, and the keyboard
 *   module: its one height, and its layout guide for timing.
 * @output Exports `useLayerKeyboardClearance` and its result type,
 *   `keyboardLiftStyle`, `keyboardClearanceCap`, `LAYER_ANCHORED_ATTRIBUTE`,
 *   `LAYER_KEYBOARD_CAP_PROPERTY`, `LAYER_KEYBOARD_OVERFLOW_PROPERTY`,
 *   `LAYER_KEYBOARD_INSET_PROPERTY` and `LAYER_KEYBOARD_CLEARANCE_PX`
 * @position Layer runtime, through the layer's touch module: the software
 *   keyboard's part of the viewport caps
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Layer/layerKeyboardClearance.ts
 * - /packages/core/src/Layer/settledBox.ts
 * - /packages/core/src/Layer/useLayerKeyboardClearance.test.tsx
 * - /packages/core/src/Layer/layerViewportInset.stylex.ts
 * - /packages/core/src/Selector/hooks.ts
 * - /docs/specs/AST-059-layer-viewport-inset/spec.md
 */

import {
  useCallback,
  useRef,
  useState,
  type CSSProperties,
  type RefObject,
} from 'react';
import {flushSync} from 'react-dom';
import {useIsomorphicLayoutEffect} from '../hooks/useIsomorphicLayoutEffect';
// The keyboard module's own files, not its index. The index also re-exports
// BottomSheet's keyboard hook. An import through it would put that hook's
// on-demand code in every layered component.
import {getKeyboardLayoutGuide} from '../keyboard/keyboardLayoutGuide';
import {getKeyboardHeight} from '../keyboard/keyboardHeight';
import {timing} from '../motion/uikit/timing';
import {
  keyboardClearanceCap,
  LAYER_ANCHORED_ATTRIBUTE,
  LAYER_KEYBOARD_CLEARANCE_PX,
} from './layerKeyboardClearance';
import {settledBox} from './settledBox';
import {awaitBrowserClick} from '../utils/browserClickWait';
import {subscribeInput} from '../utils/inputStream';
import {layoutViewportHeight} from '../utils/layoutViewport';

export {
  keyboardClearanceCap,
  LAYER_ANCHORED_ATTRIBUTE,
  LAYER_KEYBOARD_CLEARANCE_PX,
} from './layerKeyboardClearance';

/**
 * The custom property each layer's style sets (useLayer.tsx's `keyboardCap`
 * style). It holds the largest block size that keeps the layer clear of the
 * keyboard while it caps the layer. Otherwise it sets no limit.
 */
export const LAYER_KEYBOARD_CAP_PROPERTY = '--_layer-keyboard-max-block-size';

/**
 * The custom property each layer's style sets beside the cap. It holds `auto`
 * while the keyboard caps the layer, and `visible` otherwise. A surface whose
 * own overflow measure makes it a scroll container reads it as its overflow.
 * So it scrolls from the commit that caps it.
 */
export const LAYER_KEYBOARD_OVERFLOW_PROPERTY = '--_layer-keyboard-overflow';

/**
 * The custom property each layer's style sets beside the cap. Once a software
 * keyboard is up, it holds how far above the layout viewport's bottom an
 * anchored layer must end: the keyboard and `LAYER_KEYBOARD_CLEARANCE_PX`. It
 * keeps its largest value until the layer closes. Otherwise it holds no value.
 * A layer that places itself, such as Selector's overlay, slides above the
 * keyboard with it before the cap measures, and stays there.
 */
export const LAYER_KEYBOARD_INSET_PROPERTY =
  '--_layer-keyboard-inset-block-end';

/**
 * Scrolls the nearest scroll container between `target` and `layer` the
 * least amount that shows `target` inside it.
 */
function keepInView(layer: HTMLElement, target: Element) {
  const view = layer.ownerDocument.defaultView;
  for (
    let box: HTMLElement | null = target.parentElement;
    box != null;
    box = box === layer ? null : box.parentElement
  ) {
    const overflowY = view?.getComputedStyle(box).overflowY;
    if (
      box.scrollHeight > box.clientHeight + 1 &&
      (overflowY === 'auto' || overflowY === 'scroll')
    ) {
      const outer = box.getBoundingClientRect();
      const inner = target.getBoundingClientRect();
      if (inner.bottom > outer.bottom) {
        box.scrollTop += inner.bottom - outer.bottom;
      } else if (inner.top < outer.top) {
        box.scrollTop -= outer.top - inner.top;
      }
      return;
    }
  }
}

/**
 * The insets that move a capped layer's anchor area `lift` px toward the
 * block-start, or null without a lift. They hold the layer's block-start edge
 * where it was when the cap landed (`LayerKeyboardClearance.lift`).
 */
export function keyboardLiftStyle(lift: number | null): CSSProperties | null {
  return lift == null ? null : {insetBlockStart: -lift, insetBlockEnd: lift};
}

/** What `useLayerKeyboardClearance` gives the layer runtime. */
export interface LayerKeyboardClearance {
  /** The block size that keeps the layer clear of the keyboard, or null. */
  readonly cap: number | null;
  /**
   * While the cap holds the layer, how far its block-start edge sits above
   * the place the fallback order picks for the shorter box, in px. The
   * runtime applies it with `keyboardLiftStyle`. Otherwise null.
   */
  readonly lift: number | null;
  /**
   * Once a software keyboard is up, the layout px between the layout
   * viewport's bottom and the line an anchored layer ends above. It keeps its
   * largest value until the layer closes. Otherwise null.
   */
  readonly inset: number | null;
  /**
   * Follows a layer element the runtime swaps in while the layer is open.
   * The runtime calls it from its layer ref callback.
   */
  readonly followLayerElement: () => void;
}

/**
 * Keeps an open anchor-mode layer clear of the software keyboard. While a
 * software keyboard covers the bottom of the viewport, an anchored layer that
 * would run under it keeps its block-start edge. Its block size is capped so
 * that it ends `LAYER_KEYBOARD_CLEARANCE_PX` above the keyboard. The caller
 * applies the cap to the layer's own element (useLayer.tsx's `keyboardCap`).
 * Only a layer whose committed element carries `LAYER_ANCHORED_ATTRIBUTE`
 * (anchor positioning) is capped; other positionings own their geometry.
 */
export function useLayerKeyboardClearance(
  isOpen: boolean,
  layerRef: RefObject<HTMLElement | null>,
): LayerKeyboardClearance {
  const [cap, setCap] = useState<number | null>(null);
  const [lift, setLift] = useState<number | null>(null);
  const [keyboardInset, setKeyboardInset] = useState<number | null>(null);
  // The cap the layer renders with, read by the measurement between commits.
  const capRef = useRef<number | null>(null);
  const liftRef = useRef<number | null>(null);
  const keyboardInsetRef = useRef<number | null>(null);
  // Set while the layer is open: follows the runtime when it replaces the
  // layer element without closing it.
  const resyncRef = useRef<(() => void) | null>(null);

  // Syncs the cap with the software keyboard's layout guide and with the
  // open layer's element.
  useIsomorphicLayoutEffect(() => {
    const initial = layerRef.current;
    const win = initial?.ownerDocument.defaultView;
    if (!isOpen || initial == null || win == null) {
      return;
    }
    // The window, for the hoisted press handlers below.
    const view: Window = win;
    let isDisposed = false;
    const guide = getKeyboardLayoutGuide(win);
    // The element the cap and the press tracking are on. The runtime can
    // replace the layer element while it stays open; `sync` moves both to the
    // element the ref holds now.
    let layer: HTMLElement = initial;
    // The field reveal after a cap stands down if a person's input reached
    // the layer since the cap.
    let personInputs = 0;
    const notePersonInput = () => {
      personInputs += 1;
    };
    const sync = (): boolean => {
      const next = layerRef.current;
      if (next == null || next === layer) {
        return false;
      }
      layer.removeEventListener('pointerdown', handlePress, true);
      layer.removeEventListener('touchstart', notePersonInput, {capture: true});
      layer.removeEventListener('wheel', notePersonInput, {capture: true});
      layer = next;
      layer.addEventListener('pointerdown', handlePress, true);
      layer.addEventListener('touchstart', notePersonInput, {
        capture: true,
        passive: true,
      });
      layer.addEventListener('wheel', notePersonInput, {
        capture: true,
        passive: true,
      });
      return true;
    };
    // Renders the layer with `next` and returns once that commit has laid it
    // out, so the measurement after it reads the new box. Runs outside
    // React's own work: keyboard reports, timers, frames and native events.
    const commitCap = (
      next: number | null,
      nextInset = keyboardInsetRef.current,
      nextLift: number | null = null,
    ) => {
      if (
        isDisposed ||
        (capRef.current === next &&
          keyboardInsetRef.current === nextInset &&
          liftRef.current === nextLift)
      ) {
        return;
      }
      capRef.current = next;
      keyboardInsetRef.current = nextInset;
      liftRef.current = nextLift;
      // eslint-disable-next-line @eslint-react/dom-no-flush-sync -- the box is measured at its new size in the same task, before the frame paints
      flushSync(() => {
        setCap(next);
        setKeyboardInset(nextInset);
        setLift(nextLift);
      });
      sync();
    };
    // Measured at the layer's own size, as the fallback order places it:
    // returns whether the layer is capped.
    const capFor = (inset: number): boolean => {
      // The inset goes out in the commit that lifts the cap. So a layer that
      // places itself by the inset has moved before its box is read. While
      // the layer stays open, the inset only grows. A keyboard that goes down
      // then leaves a layer placed by it where it is.
      const reported = inset > 0 ? inset + LAYER_KEYBOARD_CLEARANCE_PX : 0;
      const held = Math.max(reported, keyboardInsetRef.current ?? 0);
      commitCap(null, held > 0 ? held : null);
      if (inset <= 0) {
        return false;
      }
      // In layout px, the box's and the keyboard's units: WebKit reports
      // `innerHeight` in the pinch-zoomed visual viewport's px.
      const viewport = layoutViewportHeight(win);
      const box = settledBox(layer);
      const height = keyboardClearanceCap(box, viewport, inset);
      if (height == null) {
        return false;
      }
      commitCap(height);
      // A layer too tall for the room on both sides of its trigger sits over
      // the trigger, where the viewport fit shifted it. Shorter, it fits below
      // the trigger, and the fallback order moves it down. Lift it back, so it
      // keeps the block-start edge it had when the cap landed. A layer that
      // holds its block-end edge (placed above its trigger) moves only its
      // top, and is not lifted.
      const placed = settledBox(layer);
      if (
        placed.top > box.top + 1 &&
        Math.abs(placed.bottom - box.bottom) > 1
      ) {
        commitCap(height, keyboardInsetRef.current, placed.top - box.top);
        // An engine that does not move the layer by the lift leaves it below
        // the trigger: cap it from where it starts there.
        const lifted = settledBox(layer);
        if (Math.abs(lifted.top - box.top) > 1) {
          commitCap(height);
          const again = keyboardClearanceCap(placed, viewport, inset);
          if (again != null) {
            commitCap(again);
          }
        }
      }
      // The cap holds the block-start edge: below its trigger the top stays
      // and the bottom comes up. Placed above its trigger the layer holds its
      // bottom instead, which a shorter box cannot lift: leave it as it is.
      const limit = viewport - inset - LAYER_KEYBOARD_CLEARANCE_PX;
      if (settledBox(layer).bottom > limit + 1) {
        commitCap(null);
        return false;
      }
      return true;
    };

    const avoid = (inset: number) => {
      sync();
      if (!layer.hasAttribute(LAYER_ANCHORED_ATTRIBUTE)) {
        commitCap(null, null);
        return;
      }
      if (!capFor(inset)) {
        return;
      }
      // The composing component makes its surface a scroll container once it
      // overflows. That comes a frame later, as its observer reports the
      // smaller box. Keep the field being typed into in view after that. A
      // person who presses, touches or turns a wheel in the layer by then has
      // placed its content, so the reveal stands down. A component's own
      // scroll, such as a list keeping its active option in view, does not
      // stop it. The next cap reveals the field again.
      const focused = layer.ownerDocument.activeElement;
      if (focused != null && focused !== layer && layer.contains(focused)) {
        const inputsAtCap = personInputs;
        win.requestAnimationFrame(() =>
          win.requestAnimationFrame(() => {
            if (!isDisposed && personInputs === inputsAtCap) {
              keepInView(layer, focused);
            }
          }),
        );
      }
    };

    let pending: number | null = null;
    const cancelPending = () => {
      if (pending != null) {
        win.clearTimeout(pending);
        pending = null;
      }
    };
    // A tap in the capped layer can blur the field it leaves (a button takes
    // focus on Android and in Chromium). The keyboard then starts down. The
    // full height must not come back between the tap's press and its click.
    // Otherwise the click lands on whatever moved under the finger. Such a
    // change waits for the browser's click after the lift (`awaitBrowserClick`).
    // The window's release subscriptions are held only while a press in the
    // layer is live.
    const pressed = new Set<number>();
    let deferred: (() => void) | null = null;
    let stopWaiting: (() => void) | null = null;
    let stopFollowing: (() => void) | null = null;
    const follow = () => {
      const stops = [
        subscribeInput(view, 'pointerup', handleRelease),
        subscribeInput(view, 'pointercancel', handleRelease),
      ];
      stopFollowing = () => {
        for (const stop of stops) {
          stop();
        }
      };
    };
    const unfollow = () => {
      stopFollowing?.();
      stopFollowing = null;
    };
    const runDeferred = () => {
      stopWaiting?.();
      stopWaiting = null;
      pressed.clear();
      unfollow();
      const run = deferred;
      deferred = null;
      run?.();
    };
    function handlePress(event: PointerEvent) {
      notePersonInput();
      if (pressed.size === 0) {
        follow();
      }
      pressed.add(event.pointerId);
    }
    function handleRelease(event: PointerEvent) {
      if (!pressed.has(event.pointerId)) {
        return;
      }
      if (event.type === 'pointercancel') {
        runDeferred();
        return;
      }
      stopWaiting ??= awaitBrowserClick(layer, {
        onClicked: runDeferred,
        onNoClick: runDeferred,
      });
    }
    layer.addEventListener('pointerdown', handlePress, true);
    layer.addEventListener('touchstart', notePersonInput, {
      capture: true,
      passive: true,
    });
    layer.addEventListener('wheel', notePersonInput, {
      capture: true,
      passive: true,
    });
    const unsubscribe = guide.subscribe(transition => {
      cancelPending();
      if (transition.animated && transition.to > transition.from) {
        // Rising: the keyboard covers the difference on its way up. A box's
        // height cannot change on the compositor, so the cap changes once,
        // when the keyboard arrives. Chrome draws Gboard's slide; Safari's
        // keyboard takes UIKit's notification duration.
        const arrival =
          transition.start +
          (guide.profile === 'chromium' && transition.curve != null
            ? transition.curve.durationMs
            : timing.keyboardNotificationMs);
        pending = win.setTimeout(
          () => {
            pending = null;
            avoid(transition.to);
          },
          Math.max(0, arrival - win.performance.now()),
        );
        return;
      }
      // Falling (it uncovers the full height as it goes) or at once; after
      // the click of a press in progress inside the layer.
      if (pressed.size > 0) {
        deferred = () => avoid(transition.to);
        return;
      }
      avoid(transition.to);
    });
    // Opened while a keyboard is up: capped in the task that opens it. So no
    // frame callback reads the layer uncapped, and no frame paints it so. The
    // runtime has shown the layer before this commit. A read here places it,
    // as the fallback order's read in the same task does. `flushSync` cannot
    // run inside a commit, so the cap runs in a microtask right after it.
    if (getKeyboardHeight(win) > 0) {
      win.queueMicrotask(() => {
        if (!isDisposed) {
          avoid(getKeyboardHeight(win));
        }
      });
    }
    // A layer element the runtime swaps in while the layer is open. The press
    // tracking moves to it in the commit that brings it. Its own box is read
    // in the next frame, before that frame paints: the runtime shows the new
    // element only after this call. Like a keyboard change, it waits for a
    // press in the layer to make its click. A rising keyboard's arrival reads
    // it instead.
    let swapped: number | null = null;
    resyncRef.current = () => {
      if (!sync() || swapped != null || getKeyboardHeight(win) <= 0) {
        return;
      }
      swapped = win.requestAnimationFrame(() => {
        swapped = null;
        if (isDisposed || pending != null) {
          return;
        }
        if (pressed.size > 0) {
          deferred = () => avoid(getKeyboardHeight(win));
          return;
        }
        avoid(getKeyboardHeight(win));
      });
    };
    return () => {
      isDisposed = true;
      resyncRef.current = null;
      if (swapped != null) {
        win.cancelAnimationFrame(swapped);
      }
      unsubscribe();
      cancelPending();
      stopWaiting?.();
      layer.removeEventListener('pointerdown', handlePress, true);
      layer.removeEventListener('touchstart', notePersonInput, {capture: true});
      layer.removeEventListener('wheel', notePersonInput, {capture: true});
      unfollow();
      // A closed layer reopens at its own size.
      if (capRef.current != null) {
        capRef.current = null;
        setCap(null);
      }
      if (liftRef.current != null) {
        liftRef.current = null;
        setLift(null);
      }
      if (keyboardInsetRef.current != null) {
        keyboardInsetRef.current = null;
        setKeyboardInset(null);
      }
    };
  }, [isOpen, layerRef]);

  const followLayerElement = useCallback(() => {
    resyncRef.current?.();
  }, []);
  return {
    cap: isOpen ? cap : null,
    lift: isOpen ? lift : null,
    inset: isOpen ? keyboardInset : null,
    followLayerElement,
  };
}