Skip to content

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

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

/**
 * @file keyboardLayoutGuide.ts
 * @input The keyboard module's reports (subscribeKeyboardHeight) and
 *   createKeyboardModel
 * @output getKeyboardLayoutGuide (a window's one guide), bringsUpKeyboard and
 *   the KeyboardLayoutGuide type
 * @position The web's UIKeyboardLayoutGuide: where the software keyboard
 *   covers the layout viewport and how it moves. Touch presentations read it
 *   to keep content above the keyboard. It is internal to core.
 *
 * SYNC: When modified, update /packages/core/src/keyboard/README.md
 */

import {
  getKeyboardHeight,
  hasVirtualKeyboard,
  isTextEntryControl,
  subscribeKeyboardHeight,
  type KeyboardHeightEvent,
} from './keyboardHeight';
import {
  createKeyboardModel,
  type KeyboardModel,
  type KeyboardProfile,
  type KeyboardTransition,
} from './keyboardModel';

/**
 * Whose keyboard schedule the guide reads: `chromium` where the browser has
 * the VirtualKeyboard API, else null. Without the profile, no surface rides
 * the guide. Chrome reports the keyboard as each slide starts. The profile is
 * a capability, never the user agent. motion/android/keyboard.ts holds the
 * measured timing.
 */
export function keyboardProfileOf(win: Window): KeyboardProfile | null {
  return hasVirtualKeyboard(win) ? 'chromium' : null;
}

/** A window's keyboard layout guide. */
export interface KeyboardLayoutGuide {
  /** The inset the keyboard rests at (or is heading to), CSS px. */
  readonly inset: number;
  /** The latest transition. */
  readonly transition: KeyboardTransition;
  /** The inset presented at `time` (default now), CSS px. */
  presentation(time?: number): number;
  /**
   * Calls `listener` with every transition, inside the event that revealed
   * it, until the caller runs the returned function.
   */
  subscribe(listener: (transition: KeyboardTransition) => void): () => void;
  /** Whose keyboard schedule the guide reads (keyboardProfileOf). */
  readonly profile: KeyboardProfile | null;
}

// Extra time after a predicted transition's end before checking it.
const VERIFY_SLACK_MS = 150;
// How long after a field gains focus Chrome may still report the keyboard
// gone for a moment (measured: back within 50 ms of the move).
const FOCUS_HANDOFF_MS = 150;

// Controls whose picker Chrome on Android opens over the page while the
// keyboard goes away; on iOS the picker takes the keyboard's place.
const PICKER_INPUT_TYPES = new Set([
  'date',
  'datetime-local',
  'month',
  'time',
  'week',
]);

/**
 * Whether focusing `target` brings up a software keyboard (or another input
 * view in its place, as a select's picker does).
 */
export function bringsUpKeyboard(target: EventTarget | null): boolean {
  const element = target instanceof Element ? target : null;
  return (
    isTextEntryControl(element) ||
    (element instanceof HTMLSelectElement && !element.disabled)
  );
}

// Whether `target` is a select, or a date or time field, which Chrome on
// Android edits in a picker over the page.
function opensPickerOverPage(target: EventTarget | null): boolean {
  const element = target as HTMLElement | null;
  if (element == null || element.nodeType !== 1) {
    return false;
  }
  return (
    element.tagName === 'SELECT' ||
    (element.tagName === 'INPUT' &&
      PICKER_INPUT_TYPES.has((element as HTMLInputElement).type))
  );
}

/**
 * Whether `target` can hold a field the page cannot see: a frame, an open
 * shadow host or a custom element. Focus on a field inside one leaves
 * `document.activeElement` on it.
 */
export function hidesField(target: Element): boolean {
  return (
    target.tagName === 'IFRAME' ||
    target.tagName === 'FRAME' ||
    target.tagName === 'OBJECT' ||
    target.tagName === 'EMBED' ||
    target.shadowRoot != null ||
    target.tagName.includes('-')
  );
}

const guides = new WeakMap<Window, KeyboardLayoutGuide>();

/**
 * The window's keyboard layout guide, created on first use.
 *
 * One guide serves each window. It subscribes to the keyboard module only
 * while something subscribes to it. It owns no listener and measures nothing.
 * It feeds the model the module's reports, the keyboard height and the focus
 * changes that start a hide. It hands each transition to its subscribers.
 * What it adds is timing: when a show started, a hide predicted from the
 * blur, and the motion in between. Layout follows the keyboard height
 * itself, and the guide's transitions only time the optional ride on top.
 *
 * The model reads Chrome's measured schedule: Chrome reports each slide just
 * after it starts. A surface rides the guide only where the VirtualKeyboard
 * API reports the keyboard. Focus can move from one field to another through
 * something that brings no keyboard, such as a popover's container. Chrome
 * then reports the keyboard gone for a moment and then back. So a hide
 * reported while a field that just got focus still has it waits until the
 * move settles.
 *
 * A busy page reads Chrome's reports late, after Gboard's slide. So once a
 * hide predicted from a blur is under way, a report of the keyboard partway
 * down, or still up, starts nothing. Only the report of the keyboard gone
 * confirms the hide. Focus that comes back still turns it around. Focus in a
 * frame, an open shadow host or a custom element can keep up a keyboard the
 * guide cannot see. There the viewport decides, as before. A closed shadow
 * root on a built-in element reads as nothing focused.
 *
 * @example
 * ```
 * const guide = getKeyboardLayoutGuide(window);
 * const unsubscribe = guide.subscribe(t => {
 *   rideKeyboard(animator, {y: -t.to}, t);
 * });
 * ```
 */
export function getKeyboardLayoutGuide(win: Window): KeyboardLayoutGuide {
  let guide = guides.get(win);
  if (guide == null) {
    guide = createGuide(win);
    guides.set(win, guide);
  }
  return guide;
}

function createGuide(win: Window): KeyboardLayoutGuide {
  const listeners = new Set<(transition: KeyboardTransition) => void>();
  let profile = keyboardProfileOf(win);
  let model: KeyboardModel = createKeyboardModel(getKeyboardHeight(win));
  let verifyTimer: ReturnType<typeof setTimeout> | null = null;
  let detach: (() => void) | null = null;
  // Whether focusing `target` keeps an input view where the keyboard is. On
  // iOS, a select's picker or a date or time field's picker takes the
  // keyboard's place. Chrome on Android opens it over the page, and the
  // keyboard goes away.
  const keepsInputView = (target: EventTarget | null): boolean =>
    bringsUpKeyboard(target) &&
    !(profile === 'chromium' && opensPickerOverPage(target));
  // Whether a hide predicted from a blur is under way with nothing focused
  // that can keep a keyboard up. Then only Chrome's report of the keyboard
  // gone counts.
  const awaitsHide = (): boolean => {
    const active = win.document.activeElement;
    return (
      model.transition.kind === 'hide' &&
      model.transition.predicted &&
      !keepsInputView(active) &&
      !(active != null && hidesField(active))
    );
  };

  const publish = (transition: KeyboardTransition | null) => {
    if (transition == null) {
      return;
    }
    if (transition.predicted) {
      scheduleVerify(transition);
    }
    for (const listener of [...listeners]) {
      listener(transition);
    }
  };
  const scheduleVerify = (transition: KeyboardTransition) => {
    if (verifyTimer != null) {
      clearTimeout(verifyTimer);
    }
    const due =
      transition.start + (transition.curve?.durationMs ?? 0) + VERIFY_SLACK_MS;
    verifyTimer = setTimeout(
      () => {
        verifyTimer = null;
        const inset = getKeyboardHeight(win);
        if (inset != null && inset > 0.5 && awaitsHide()) {
          return;
        }
        publish(model.verify(inset, win.performance.now()));
      },
      Math.max(0, due - win.performance.now()),
    );
  };

  const attach = () => {
    profile = keyboardProfileOf(win);
    model = createKeyboardModel(getKeyboardHeight(win));
    // When a field that brings up a keyboard last gained focus.
    let keyboardFocusAt = -Infinity;
    let handoffTimer: ReturnType<typeof setTimeout> | null = null;
    const report = (
      height: number,
      time: number,
    ): KeyboardTransition | null => {
      if (handoffTimer != null) {
        clearTimeout(handoffTimer);
        handoffTimer = null;
      }
      const settled = keyboardFocusAt + FOCUS_HANDOFF_MS;
      if (
        profile === 'chromium' &&
        height < 0.5 &&
        model.inset >= 0.5 &&
        time < settled &&
        keepsInputView(win.document.activeElement)
      ) {
        // Focus just moved to another field: Chrome reports the keyboard
        // gone before it reports it back. Hold the hide until the move
        // settles, then believe whatever the keyboard is doing.
        handoffTimer = setTimeout(() => {
          handoffTimer = null;
          publish(model.report(getKeyboardHeight(win), settled));
        }, settled - time);
        return null;
      }
      if (height > 0.5 && awaitsHide()) {
        return null;
      }
      return model.report(height, time);
    };
    const onReport = (event: KeyboardHeightEvent) => {
      if (event.type === 'viewport') {
        publish(report(event.height, event.timeStamp));
      } else if (event.type === 'focusin') {
        if (keepsInputView(event.target)) {
          keyboardFocusAt = event.timeStamp;
          publish(model.focused(event.timeStamp));
        }
      } else if (
        keepsInputView(event.target) &&
        !keepsInputView(event.relatedTarget)
      ) {
        publish(model.blurred(event.timeStamp));
      }
    };
    const unsubscribe = subscribeKeyboardHeight(win, onReport, {focus: true});
    return () => {
      unsubscribe();
      if (handoffTimer != null) {
        clearTimeout(handoffTimer);
        handoffTimer = null;
      }
      if (verifyTimer != null) {
        clearTimeout(verifyTimer);
        verifyTimer = null;
      }
    };
  };

  return {
    get profile() {
      return profile;
    },
    get inset() {
      return model.inset;
    },
    get transition() {
      return model.transition;
    },
    presentation(time = win.performance.now()) {
      return model.presentation(time);
    },
    subscribe(listener) {
      listeners.add(listener);
      if (detach == null) {
        detach = attach();
      }
      return () => {
        listeners.delete(listener);
        if (listeners.size === 0 && detach != null) {
          detach();
          detach = null;
        }
      };
    },
  };
}