Skip to content

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

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

/**
 * @file keyboardHeight.test.ts
 * @input keyboardHeight.ts, the keyboard layout guide, a stand-in visual
 *   viewport
 * @output Tests for the on-screen keyboard module: the height, where it
 *   measures, a hide reported in steps, its one set of listeners and the
 *   focus refusal
 * @position Keyboard module tests
 */

import fs from 'node:fs';
import path from 'node:path';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {act} from '@testing-library/react';
import {bringsUpKeyboard, getKeyboardLayoutGuide} from './keyboardLayoutGuide';
import {
  __resetClickGuardForTest,
  CLICK_GUARD_WINDOW_MS,
} from '../utils/clickGuard';
import {
  __resetLayoutViewportForTest,
  layoutViewportHeight,
} from '../utils/layoutViewport';
import {
  claimTapFocus,
  findTextEntryControl,
  focusAtPoint,
  getKeyboardHeight,
  isKeyboardMeasurable,
  isTextEntryControl,
  measureKeyboardHeight,
  refuseFocusReveal,
  subscribeKeyboardHeight,
  watchRevealPan,
  type KeyboardHeightEvent,
} from './keyboardHeight';

type FakeViewport = EventTarget & {
  height: number;
  offsetTop: number;
  scale: number;
  width?: number;
};

let viewport: FakeViewport;

function report(changes: Partial<FakeViewport>) {
  Object.assign(viewport, changes);
  act(() => {
    viewport.dispatchEvent(new Event('resize'));
  });
}

beforeEach(() => {
  viewport = Object.assign(new EventTarget(), {
    height: window.innerHeight,
    offsetTop: 0,
    scale: 1,
  });
  Object.defineProperty(window, 'visualViewport', {
    configurable: true,
    value: viewport,
  });
});

afterEach(() => {
  Reflect.deleteProperty(window, 'visualViewport');
  Reflect.deleteProperty(window.navigator, 'virtualKeyboard');
  for (const key of ['clientWidth', 'clientHeight', 'scrollWidth']) {
    Reflect.deleteProperty(document.documentElement, key);
  }
  __resetLayoutViewportForTest();
  __resetClickGuardForTest();
  vi.unstubAllGlobals();
  vi.restoreAllMocks();
  vi.unstubAllGlobals();
});

describe('the keyboard height (spec:AST-099 FR2)', () => {
  it('is the layout viewport minus the visual viewport', () => {
    viewport.height = window.innerHeight - 300;
    expect(measureKeyboardHeight(window)).toBe(300);
  });

  it('is not made smaller by a page pan', () => {
    viewport.height = window.innerHeight - 300;
    viewport.offsetTop = 120;
    expect(measureKeyboardHeight(window)).toBe(300);
  });

  it('is 0 while pinch-zoomed with no keyboard, and the keyboard with one', () => {
    viewport.scale = 2;
    viewport.height = window.innerHeight / 2;
    expect(measureKeyboardHeight(window)).toBe(0);
    viewport.height = (window.innerHeight - 300) / 2;
    expect(measureKeyboardHeight(window)).toBe(300);
  });

  it('is 0 with no keyboard shown', () => {
    expect(measureKeyboardHeight(window)).toBe(0);
  });
});

describe('the layout viewport WebKit reports under a pinch zoom (FR2)', () => {
  // Measured in Safari on iOS 26.2 on an iPhone 17 Pro, with a 402 × 714
  // layout viewport and a 337 px keyboard. WebKit reports innerWidth and
  // innerHeight in the zoomed visual viewport's px. The visual viewport's
  // height times its scale stays in layout px.
  function safari({
    innerHeight,
    innerWidth,
    height,
    scale,
    offsetTop = 0,
  }: {
    innerHeight: number;
    innerWidth: number;
    height: number;
    scale: number;
    offsetTop?: number;
  }) {
    vi.stubGlobal('innerHeight', innerHeight);
    vi.stubGlobal('innerWidth', innerWidth);
    // The visual viewport is the 402 px layout width over the zoom.
    Object.assign(viewport, {height, scale, offsetTop, width: 402 / scale});
  }

  it('reads the keyboard at scale 1', () => {
    safari({innerHeight: 714, innerWidth: 402, height: 377, scale: 1});
    expect(measureKeyboardHeight(window)).toBe(337);
    expect(layoutViewportHeight(window)).toBe(714);
  });

  it('reads the same keyboard pinch-zoomed to 1.33', () => {
    safari({innerHeight: 536, innerWidth: 302, height: 282.75, scale: 4 / 3});
    expect(Math.abs(measureKeyboardHeight(window) - 337)).toBeLessThan(1);
  });

  it('follows the layout viewport WebKit clamps to the document after a scroll', () => {
    safari({
      innerHeight: 666,
      innerWidth: 402,
      height: 377,
      scale: 1,
      offsetTop: 120,
    });
    expect(measureKeyboardHeight(window)).toBe(289);
  });

  it('reads the same keyboard scrolled and pinch-zoomed', () => {
    safari({
      innerHeight: 536,
      innerWidth: 302,
      height: 282.75,
      scale: 4 / 3,
      offsetTop: 154.5,
    });
    expect(Math.abs(measureKeyboardHeight(window) - 337)).toBeLessThan(1);
  });

  it('keeps the keyboard past a 2x zoom, where innerHeight alone reads none', () => {
    safari({innerHeight: 357, innerWidth: 201, height: 188.5, scale: 2});
    expect(measureKeyboardHeight(window)).toBe(337);
  });

  it('reads no keyboard pinch-zoomed with none, in WebKit and where innerHeight ignores the zoom', () => {
    safari({innerHeight: 536, innerWidth: 302, height: 536, scale: 4 / 3});
    expect(measureKeyboardHeight(window)).toBe(0);
    safari({innerHeight: 714, innerWidth: 402, height: 535.5, scale: 4 / 3});
    expect(measureKeyboardHeight(window)).toBe(0);
  });

  it('reads no keyboard beside a classic scrollbar', () => {
    // A desktop page with a 17 px vertical scrollbar, which innerWidth and
    // not the document's client width or the visual viewport counts.
    vi.stubGlobal('innerHeight', 800);
    vi.stubGlobal('innerWidth', 1280);
    Object.defineProperty(document.documentElement, 'clientWidth', {
      configurable: true,
      value: 1263,
    });
    Object.assign(viewport, {height: 800, scale: 1, width: 1263});
    expect(layoutViewportHeight(window)).toBe(800);
    expect(measureKeyboardHeight(window)).toBe(0);
  });

  /** The document's root: its client box and how wide its content is. */
  function root(box: {
    clientHeight: number;
    clientWidth: number;
    scrollWidth: number;
  }) {
    for (const [key, value] of Object.entries(box)) {
      Object.defineProperty(document.documentElement, key, {
        configurable: true,
        value,
      });
    }
  }

  /**
   * Scrollbars that take `thickness` px of a scrolling box (0: overlaid).
   * `probes` counts the scrolling boxes measured.
   */
  function scrollbars(thickness: number): {probes: number} {
    const counter = {probes: 0};
    const scrolls = (el: Element) =>
      el instanceof HTMLElement && el.style.overflow === 'scroll';
    vi.spyOn(HTMLElement.prototype, 'offsetHeight', 'get').mockImplementation(
      function (this: HTMLElement) {
        if (scrolls(this)) {
          counter.probes += 1;
          return 100;
        }
        return 0;
      },
    );
    vi.spyOn(Element.prototype, 'clientHeight', 'get').mockImplementation(
      function (this: Element) {
        return scrolls(this) ? 100 - thickness : 0;
      },
    );
    return counter;
  }

  it('reads no keyboard from a desktop page\u2019s classic horizontal scrollbar', () => {
    // Chromium with classic scrollbars, on a page wider than the window.
    // innerHeight counts the 15 px scrollbar. The visual viewport and the
    // document's client height do not.
    scrollbars(15);
    vi.stubGlobal('innerHeight', 800);
    vi.stubGlobal('innerWidth', 1280);
    root({clientHeight: 785, clientWidth: 1280, scrollWidth: 1600});
    Object.assign(viewport, {height: 785, scale: 1, width: 1280});
    expect(layoutViewportHeight(window)).toBe(785);
    expect(measureKeyboardHeight(window)).toBe(0);
  });

  it('measures the scrollbar once, however many keyboard changes read the height (INV11)', () => {
    // The probe writes to the document and forces a layout: it runs once,
    // and every later measurement reuses the thickness.
    const counter = scrollbars(15);
    vi.stubGlobal('innerHeight', 800);
    vi.stubGlobal('innerWidth', 1280);
    root({clientHeight: 785, clientWidth: 1280, scrollWidth: 1600});
    Object.assign(viewport, {height: 785, scale: 1, width: 1280});
    for (let i = 0; i < 3; i += 1) {
      expect(measureKeyboardHeight(window)).toBe(0);
    }
    expect(counter.probes).toBe(1);
  });

  it('reads the whole keyboard under a hidden toolbar, which no scrollbar explains', () => {
    // Chrome on Android sizes the document's client height to the viewport
    // with its toolbar shown, 754 px, and overlays its scrollbars. So the
    // 136 px a hidden toolbar adds to innerHeight is no scrollbar, also on a
    // page wider than the window.
    scrollbars(0);
    vi.stubGlobal('innerHeight', 890);
    vi.stubGlobal('innerWidth', 411);
    root({clientHeight: 754, clientWidth: 411, scrollWidth: 1600});
    Object.assign(viewport, {height: 590, scale: 1, width: 411});
    expect(measureKeyboardHeight(window)).toBe(300);
  });
});

describe('where the keyboard is measured (FR6, FR7)', () => {
  it('measures with a visual viewport and no keyboard geometry API', () => {
    expect(isKeyboardMeasurable(window)).toBe(true);
  });

  it('measures Chrome on Android from its visual viewport, which has its own keyboard geometry API (DEC-4)', () => {
    // Gboard shrinks Chrome's visual viewport while the layout viewport keeps
    // its height, as everywhere else; the VirtualKeyboard API is not read.
    Object.defineProperty(window.navigator, 'virtualKeyboard', {
      configurable: true,
      value: {overlaysContent: false},
    });
    vi.stubGlobal(
      'matchMedia',
      (query: string) =>
        ({matches: false, media: query}) as unknown as MediaQueryList,
    );
    viewport.height = window.innerHeight - 300;
    expect(isKeyboardMeasurable(window)).toBe(true);
    expect(measureKeyboardHeight(window)).toBe(300);
  });

  it('reads no keyboard where a desktop browser with the API shows none', () => {
    Object.defineProperty(window.navigator, 'virtualKeyboard', {
      configurable: true,
      value: {overlaysContent: false},
    });
    expect(measureKeyboardHeight(window)).toBe(0);
  });

  it('reads no keyboard under interactive-widget=resizes-content, where Chrome shrinks the layout viewport with it (FR8)', () => {
    Object.defineProperty(window.navigator, 'virtualKeyboard', {
      configurable: true,
      value: {overlaysContent: false},
    });
    const full = window.innerHeight;
    Object.defineProperty(window, 'innerHeight', {
      configurable: true,
      value: full - 300,
    });
    try {
      viewport.height = full - 300;
      expect(measureKeyboardHeight(window)).toBe(0);
    } finally {
      Object.defineProperty(window, 'innerHeight', {
        configurable: true,
        value: full,
      });
    }
  });

  it('measures nothing without a visual viewport', () => {
    Reflect.deleteProperty(window, 'visualViewport');
    expect(measureKeyboardHeight(window)).toBe(0);
  });

  it('measures nothing inside an iframe', () => {
    const frame = document.createElement('iframe');
    document.body.append(frame);
    const inner = frame.contentWindow as Window;
    Object.defineProperty(inner, 'visualViewport', {
      configurable: true,
      value: Object.assign(new EventTarget(), {
        height: inner.innerHeight - 300,
        offsetTop: 0,
        scale: 1,
      }),
    });
    expect(isKeyboardMeasurable(inner)).toBe(false);
    expect(measureKeyboardHeight(inner)).toBe(0);
    frame.remove();
  });
});

describe('a hide Chrome reports in steps under Remove animations (FR8)', () => {
  // Each test's subscriptions end after it, also when an expectation fails.
  const stops: (() => void)[] = [];
  afterEach(() => {
    for (const stop of stops.splice(0)) {
      stop();
    }
    vi.useRealTimers();
  });
  // Android's Remove animations setting reads as prefers-reduced-motion.
  const reduceMotion = (reduce: boolean) =>
    vi.stubGlobal(
      'matchMedia',
      (query: string) =>
        ({
          matches: reduce && query === '(prefers-reduced-motion: reduce)',
          media: query,
        }) as unknown as MediaQueryList,
    );
  const withVirtualKeyboard = () =>
    Object.defineProperty(window.navigator, 'virtualKeyboard', {
      configurable: true,
      value: {overlaysContent: false},
    });
  const heightsOf = (listener: ReturnType<typeof vi.fn>) =>
    listener.mock.calls.map(([event]) => (event as KeyboardHeightEvent).height);
  const keyboard = (height: number) =>
    report({height: window.innerHeight - height});

  it('reports the hide once, with the report of none, and keeps the shown height until then', () => {
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(300);
    for (const step of [200, 120, 60]) {
      keyboard(step);
      expect(getKeyboardHeight(window)).toBe(300);
    }
    keyboard(0);
    expect(heightsOf(listener)).toEqual([300, 0]);
    expect(getKeyboardHeight(window)).toBe(0);
  });

  it('gives the keyboard layout guide one hide for the steps, and no change', () => {
    withVirtualKeyboard();
    reduceMotion(true);
    const kinds: string[] = [];
    stops.push(
      getKeyboardLayoutGuide(window).subscribe(transition => {
        kinds.push(transition.kind);
      }),
    );
    keyboard(300);
    for (const step of [200, 120, 60]) {
      keyboard(step);
    }
    keyboard(0);
    expect(kinds).toEqual(['show', 'hide']);
  });

  it('reports a lower keyboard that stays up after a quiet spell', () => {
    vi.useFakeTimers();
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(300);
    keyboard(250);
    act(() => {
      vi.advanceTimersByTime(299);
    });
    expect(heightsOf(listener)).toEqual([300]);
    act(() => {
      vi.advanceTimersByTime(1);
    });
    expect(heightsOf(listener)).toEqual([300, 250]);
  });

  it('keeps a step waiting through a pan, which reports the same height', () => {
    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout', 'performance']});
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(300);
    keyboard(250);
    for (const offsetTop of [20, 40, 60]) {
      act(() => {
        vi.advanceTimersByTime(90);
      });
      Object.assign(viewport, {offsetTop});
      act(() => {
        viewport.dispatchEvent(new Event('scroll'));
      });
    }
    act(() => {
      vi.advanceTimersByTime(30);
    });
    expect(heightsOf(listener)).toEqual([300, 250]);
  });

  it('waits 1 s at most in all, however long the steps go on', () => {
    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout', 'performance']});
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(300);
    for (const step of [280, 260, 240, 220]) {
      keyboard(step);
      act(() => {
        vi.advanceTimersByTime(250);
      });
    }
    expect(heightsOf(listener)).toEqual([300, 220]);
  });

  it('reports a keyboard that comes back up at once', () => {
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(300);
    keyboard(200);
    keyboard(300);
    expect(heightsOf(listener)).toEqual([300, 300]);
  });

  it('reports every report of a show at once', () => {
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(44);
    keyboard(300);
    expect(heightsOf(listener)).toEqual([44, 300]);
  });

  it.each([
    ['without Remove animations', true, false],
    ['without the VirtualKeyboard API', false, true],
  ])('reports every step %s', (_, hasApi, reduce) => {
    if (hasApi) {
      withVirtualKeyboard();
    }
    reduceMotion(reduce);
    const listener = vi.fn();
    stops.push(subscribeKeyboardHeight(window, listener));
    keyboard(300);
    for (const step of [200, 120, 60]) {
      keyboard(step);
    }
    keyboard(0);
    expect(heightsOf(listener)).toEqual([300, 200, 120, 60, 0]);
  });

  it('stops waiting when the last reader leaves', () => {
    vi.useFakeTimers();
    withVirtualKeyboard();
    reduceMotion(true);
    const listener = vi.fn();
    const stop = subscribeKeyboardHeight(window, listener);
    keyboard(300);
    keyboard(200);
    stop();
    act(() => {
      vi.advanceTimersByTime(1000);
    });
    expect(heightsOf(listener)).toEqual([300]);
  });
});

describe('one set of listeners per window (FR1, INV11)', () => {
  it('shares the listeners among subscribers and removes them with the last', () => {
    const add = vi.spyOn(viewport, 'addEventListener');
    const remove = vi.spyOn(viewport, 'removeEventListener');
    const first = vi.fn();
    const second = vi.fn();
    const stopFirst = subscribeKeyboardHeight(window, first);
    const stopSecond = subscribeKeyboardHeight(window, second);
    expect(add.mock.calls.map(([type]) => type)).toEqual(['resize', 'scroll']);

    report({height: window.innerHeight - 300});
    expect(first).toHaveBeenLastCalledWith(
      expect.objectContaining({type: 'viewport', height: 300}),
    );
    expect(second).toHaveBeenLastCalledWith(
      expect.objectContaining({type: 'viewport', height: 300}),
    );

    stopFirst();
    expect(remove).not.toHaveBeenCalled();
    stopSecond();
    expect(remove.mock.calls.map(([type]) => type)).toEqual([
      'resize',
      'scroll',
    ]);
  });

  it('feeds the keyboard layout guide, which adds no listener of its own', () => {
    const add = vi.spyOn(viewport, 'addEventListener');
    const windowAdd = vi.spyOn(window, 'addEventListener');
    const stopHook = subscribeKeyboardHeight(window, () => {});
    const guide = getKeyboardLayoutGuide(window);
    const transitions: number[] = [];
    const stopGuide = guide.subscribe(transition => {
      transitions.push(transition.to);
    });
    expect(add).toHaveBeenCalledTimes(2);
    expect(
      windowAdd.mock.calls.filter(([type]) => type === 'resize'),
    ).toHaveLength(1);

    report({height: window.innerHeight - 300});
    expect(transitions.at(-1)).toBe(300);
    expect(guide.inset).toBe(300);
    stopGuide();
    stopHook();
  });

  it('reads the layout once per keyboard change, however many read the height (INV11)', () => {
    // Count every read of the visual viewport's height: one per measurement.
    let height = viewport.height;
    let reads = 0;
    Object.defineProperty(viewport, 'height', {
      configurable: true,
      get: () => {
        reads += 1;
        return height;
      },
      set: (value: number) => {
        height = value;
      },
    });
    const seen: number[] = [];
    // Three readers, each reading the height again as it lays out.
    const reader = () => (event: KeyboardHeightEvent) => {
      if (event.type === 'viewport') {
        seen.push(getKeyboardHeight(window), event.height);
      }
    };
    // And the keyboard layout guide, whose rider reads the height again as
    // it commits its layout.
    const stopGuide = getKeyboardLayoutGuide(window).subscribe(transition => {
      seen.push(getKeyboardHeight(window), transition.to);
    });
    const stops = [reader(), reader(), reader()].map(listener =>
      subscribeKeyboardHeight(window, listener),
    );
    try {
      reads = 0;
      report({height: window.innerHeight - 300});
      expect(seen).toHaveLength(8);
      expect(seen.every(value => value === 300)).toBe(true);
      expect(reads).toBe(1);
    } finally {
      for (const stop of stops) {
        stop();
      }
      stopGuide();
    }
  });
  it('listens to focus moves only while a subscriber asks for them, through one pair of shared input listeners (spec:AST-094 FR24)', () => {
    const documentAdd = vi.spyOn(window, 'addEventListener');
    const documentRemove = vi.spyOn(window, 'removeEventListener');
    const focusCalls = (spy: typeof documentAdd) =>
      spy.mock.calls
        .filter(([type]) => type.startsWith('focus'))
        .map(([type]) => type);
    const viewportTypes: string[] = [];
    const guideTypes: string[] = [];
    const input = document.createElement('input');
    document.body.append(input);
    // A viewport reader (a Tall BottomSheet's hook) adds no focus listener.
    const stopViewport = subscribeKeyboardHeight(window, event => {
      viewportTypes.push(event.type);
    });
    try {
      expect(focusCalls(documentAdd)).toEqual([]);
      // Readers of focus moves (the keyboard layout guide) share one pair.
      const stopA = subscribeKeyboardHeight(
        window,
        event => {
          guideTypes.push(event.type);
        },
        {focus: true},
      );
      const stopB = subscribeKeyboardHeight(window, () => {}, {focus: true});
      expect(focusCalls(documentAdd)).toEqual(['focusin', 'focusout']);
      input.focus();
      input.blur();
      expect(guideTypes).toEqual(['focusin', 'focusout']);
      expect(viewportTypes).toEqual([]);
      stopA();
      expect(focusCalls(documentRemove)).toEqual([]);
      stopB();
      expect(focusCalls(documentRemove)).toEqual(['focusin', 'focusout']);
    } finally {
      input.remove();
      stopViewport();
      documentAdd.mockRestore();
      documentRemove.mockRestore();
    }
  });

  it('reports the window\u2019s own resize, not a resize event an element sends through the window', () => {
    const heights: number[] = [];
    const stop = subscribeKeyboardHeight(window, event => {
      heights.push(event.height);
    });
    try {
      document.body.dispatchEvent(new Event('resize'));
      expect(heights).toEqual([]);
      window.dispatchEvent(new Event('resize'));
      expect(heights).toHaveLength(1);
    } finally {
      stop();
    }
  });

  it('reads a keyboard that is already up when the first subscriber attaches', () => {
    // Nothing listens yet: the keyboard came up before any keyboard-aware
    // component mounted (a sheet opened from a focused field).
    viewport.height = window.innerHeight - 300;
    expect(getKeyboardHeight(window)).toBe(300);
    const heights: number[] = [];
    const stop = subscribeKeyboardHeight(window, event => {
      if (event.type === 'viewport') {
        heights.push(event.height);
      }
    });
    expect(getKeyboardHeight(window)).toBe(300);
    // The guide reads it too.
    const guide = getKeyboardLayoutGuide(window);
    const stopGuide = guide.subscribe(() => {});
    expect(guide.inset).toBe(300);
    report({height: window.innerHeight});
    expect(heights).toEqual([0]);
    stopGuide();
    stop();
  });
  it('is the only visual viewport listener for the keyboard in core', () => {
    // Visible-viewport readers that place layers and scroll areas, not the
    // keyboard; the layer cap's keyboard is architecture:layer-runtime's.
    const visibleViewportReaders = new Set([
      'AppShell/observeMainOverflow.ts',
      'DropdownMenu/useMenuOverflow.ts',
      'Popover/Popover.tsx',
      'hooks/useScrollableArea.ts',
    ]);
    const root = path.resolve(__dirname, '..');
    const offenders: string[] = [];
    const walk = (dir: string) => {
      for (const entry of fs.readdirSync(dir, {withFileTypes: true})) {
        const file = path.join(dir, entry.name);
        if (entry.isDirectory()) {
          walk(file);
          continue;
        }
        if (
          !/\.tsx?$/.test(entry.name) ||
          /\.(test|spec|stories)\./.test(entry.name)
        ) {
          continue;
        }
        const relative = path.relative(root, file).split(path.sep).join('/');
        const source = fs.readFileSync(file, 'utf8');
        if (
          /visualViewport\??\.addEventListener|viewport\??\.addEventListener\(\s*'(resize|scroll)'/.test(
            source,
          ) &&
          relative !== 'keyboard/keyboardHeight.ts' &&
          !visibleViewportReaders.has(relative)
        ) {
          offenders.push(relative);
        }
      }
    };
    walk(root);
    expect(offenders).toEqual([]);
  });
});

describe('the focus refusal (FR4)', () => {
  it('delivers a claimed focus move with preventScroll and parks focus that leaves for nothing', () => {
    const first = document.createElement('input');
    const second = document.createElement('input');
    const park = vi.fn();
    document.body.append(first, second);
    const stop = refuseFocusReveal(document, {
      claim: target => (target === second ? second : null),
      park,
    });
    const focus = vi.spyOn(second, 'focus');
    first.focus();
    second.focus();
    expect(focus).toHaveBeenCalledWith({preventScroll: true});
    second.blur();
    expect(park).toHaveBeenCalledWith(second);
    stop();
    first.remove();
    second.remove();
  });

  it('leaves the window\u2019s own blur alone: it moves no focus in the document', () => {
    const parked: unknown[] = [];
    const stop = refuseFocusReveal(document, {
      claim: () => null,
      park: origin => parked.push(origin),
    });
    try {
      window.dispatchEvent(new FocusEvent('blur'));
      expect(parked).toEqual([]);
    } finally {
      stop();
    }
  });

  it('shares one blur subscription among its callers, each still hearing every blur (spec:AST-094 FR24)', () => {
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    const field = document.createElement('input');
    const other = document.createElement('input');
    document.body.append(field, other);
    const heard: string[] = [];
    const stopFirst = refuseFocusReveal(document, {
      claim: () => {
        heard.push('first');
        return null;
      },
    });
    const stopSecond = refuseFocusReveal(document, {
      claim: () => {
        heard.push('second');
        return null;
      },
    });
    expect(add.mock.calls.filter(([type]) => type === 'blur')).toHaveLength(1);
    field.focus();
    other.focus();
    expect(heard).toEqual(['first', 'second']);
    stopFirst();
    expect(remove).not.toHaveBeenCalled();
    field.focus();
    expect(heard).toEqual(['first', 'second', 'second']);
    stopSecond();
    expect(remove.mock.calls.map(([type]) => type)).toEqual(['blur']);
    field.remove();
    other.remove();
  });
});

describe('the browser\u2019s own reveal pan (FR4)', () => {
  function setup() {
    const region = document.createElement('div');
    const field = document.createElement('textarea');
    const outside = document.createElement('textarea');
    region.append(field);
    document.body.append(region, outside);
    const watch = watchRevealPan(window, {
      owns: focused => region.contains(focused),
    });
    field.focus();
    viewport.height = window.innerHeight - 300;
    watch.report();
    return {region, field, outside, watch};
  }

  afterEach(() => {
    document.body.replaceChildren();
  });

  it('sees the visual viewport moving down after the report as a reveal pan of an owned field', () => {
    const {watch} = setup();
    expect(watch.isRevealPan(300)).toBe(false);
    viewport.offsetTop = 300;
    expect(watch.isRevealPan(300)).toBe(true);
    expect(watch.isRevealPan(0)).toBe(false);
    watch.stop();
  });

  it('leaves alone a reader\u2019s own pan, a document scroll, a zoom, and a field it does not own', () => {
    const touched = setup();
    document.dispatchEvent(new Event('touchstart'));
    viewport.offsetTop = 300;
    expect(touched.watch.isRevealPan(300)).toBe(false);
    touched.watch.stop();
    document.body.replaceChildren();
    viewport.offsetTop = 0;

    const scrolled = setup();
    vi.stubGlobal('scrollY', 120);
    viewport.offsetTop = 300;
    expect(scrolled.watch.isRevealPan(300)).toBe(false);
    scrolled.watch.stop();
    vi.unstubAllGlobals();
    document.body.replaceChildren();
    viewport.offsetTop = 0;

    const zoomed = setup();
    Object.assign(viewport, {offsetTop: 300, scale: 1.5});
    expect(zoomed.watch.isRevealPan(300)).toBe(false);
    zoomed.watch.stop();
    document.body.replaceChildren();
    Object.assign(viewport, {offsetTop: 0, scale: 1});

    const elsewhere = setup();
    elsewhere.outside.focus();
    viewport.offsetTop = 300;
    expect(elsewhere.watch.isRevealPan(300)).toBe(false);
    elsewhere.watch.stop();
  });

  it('puts the pan back by scrolling a fixed probe at the report\u2019s offset into view, or a given anchor', () => {
    const {watch} = setup();
    const scrolled: {element: HTMLElement; position: string; top: string}[] =
      [];
    // jsdom has no scrollIntoView.
    Object.defineProperty(Element.prototype, 'scrollIntoView', {
      configurable: true,
      value(this: HTMLElement) {
        scrolled.push({
          element: this,
          position: this.style.position,
          top: this.style.top,
        });
      },
    });
    viewport.offsetTop = 300;
    watch.putBack();
    expect(scrolled).toHaveLength(1);
    expect(scrolled[0].position).toBe('fixed');
    expect(scrolled[0].top).toBe('0px');
    // The probe is gone once the sheet puts the pan back.
    expect(scrolled[0].element.isConnected).toBe(false);

    const anchor = document.createElement('dialog');
    document.body.append(anchor);
    watch.putBack(anchor);
    expect(scrolled.at(-1)?.element).toBe(anchor);
    watch.stop();
    Reflect.deleteProperty(Element.prototype, 'scrollIntoView');
  });

  it('listens for touches only while it watches', () => {
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    const watch = watchRevealPan(window, {owns: () => true});
    expect(add.mock.calls.map(([type]) => type)).toEqual(['touchstart']);
    watch.stop();
    expect(remove.mock.calls.map(([type]) => type)).toEqual(['touchstart']);
  });

  it('shares one touch subscription among its watches (architecture INV13, spec:AST-094 FR24)', () => {
    const add = vi.spyOn(window, 'addEventListener');
    const remove = vi.spyOn(window, 'removeEventListener');
    const touched: string[] = [];
    const first = watchRevealPan(window, {
      owns: () => true,
      onTouch: () => touched.push('first'),
    });
    const second = watchRevealPan(window, {
      owns: () => true,
      onTouch: () => touched.push('second'),
    });
    expect(add.mock.calls.map(([type]) => type)).toEqual(['touchstart']);
    document.dispatchEvent(new Event('touchstart'));
    expect(touched).toEqual(['first', 'second']);
    first.stop();
    expect(remove).not.toHaveBeenCalled();
    document.dispatchEvent(new Event('touchstart'));
    expect(touched).toEqual(['first', 'second', 'second']);
    second.stop();
    expect(remove.mock.calls.map(([type]) => type)).toEqual(['touchstart']);
  });
});

describe('the text-entry predicate', () => {
  it('reads an inputmode="none" field as no text entry, as the keyboard layout guide does', () => {
    const input = document.createElement('input');
    input.setAttribute('inputmode', 'none');
    document.body.append(input);
    try {
      expect(isTextEntryControl(input)).toBe(false);
      expect(findTextEntryControl(input, document.body)).toBeNull();
      expect(bringsUpKeyboard(input)).toBe(false);
    } finally {
      input.remove();
    }
  });

  it('gives the keyboard layout guide only a select beyond the text-entry controls', () => {
    const select = document.createElement('select');
    const text = document.createElement('input');
    const box = document.createElement('input');
    box.type = 'checkbox';
    const area = document.createElement('textarea');
    area.readOnly = true;
    const editable = document.createElement('div');
    editable.setAttribute('contenteditable', '');
    document.body.append(select, text, box, area, editable);
    try {
      expect(isTextEntryControl(select)).toBe(false);
      expect(bringsUpKeyboard(select)).toBe(true);
      for (const element of [text, box, area, editable]) {
        expect(bringsUpKeyboard(element)).toBe(isTextEntryControl(element));
      }
    } finally {
      for (const element of [select, text, box, area, editable]) {
        element.remove();
      }
    }
  });
});

describe('the tap route (FR4)', () => {
  // A touch event as the browser raises it: its fingers, and cancelable.
  const touchEvent = (
    type: string,
    points: {x: number; y: number}[],
    changed = points,
  ) => {
    const event = new Event(type, {bubbles: true, cancelable: true});
    const list = (ps: {x: number; y: number}[]) =>
      ps.map((p, identifier) => ({identifier, clientX: p.x, clientY: p.y}));
    Object.assign(event, {
      touches: list(points),
      changedTouches: list(changed),
    });
    return event;
  };

  function setup() {
    const region = document.createElement('div');
    const field = document.createElement('div');
    region.append(field);
    document.body.append(region);
    const deliver = vi.fn();
    const stop = claimTapFocus(region, {
      claim: target => (target === field ? field : null),
      deliver,
    });
    return {region, field, deliver, stop};
  }

  it('delivers a tap on a claimed field itself, and cancels the browser\u2019s', () => {
    const {region, field, deliver, stop} = setup();
    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    const end = touchEvent('touchend', [], [{x: 12, y: 11}]);
    field.dispatchEvent(end);
    expect(end.defaultPrevented).toBe(true);
    expect(deliver).toHaveBeenCalledWith(field, 12, 11, expect.anything());
    stop();
    region.remove();
  });

  it('leaves a touch that moves past the scroll slop, or a second finger, to the browser', () => {
    const {region, field, deliver, stop} = setup();
    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    field.dispatchEvent(touchEvent('touchmove', [{x: 10, y: 30}]));
    const moved = touchEvent('touchend', [], [{x: 10, y: 30}]);
    field.dispatchEvent(moved);
    expect(moved.defaultPrevented).toBe(false);

    field.dispatchEvent(
      touchEvent('touchstart', [
        {x: 10, y: 10},
        {x: 40, y: 10},
      ]),
    );
    const pinch = touchEvent('touchend', [], [{x: 10, y: 10}]);
    field.dispatchEvent(pinch);
    expect(pinch.defaultPrevented).toBe(false);
    expect(deliver).not.toHaveBeenCalled();
    stop();
    region.remove();
  });

  it('listens on the region only, and follows a touch only while it is down', () => {
    const {region, field, stop} = setup();
    const add = vi.spyOn(region, 'addEventListener');
    const remove = vi.spyOn(region, 'removeEventListener');
    const documentAdd = vi.spyOn(document, 'addEventListener');
    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    expect(add.mock.calls.map(([type]) => type)).toEqual([
      'touchmove',
      'touchend',
      'touchcancel',
    ]);
    field.dispatchEvent(touchEvent('touchend', [], [{x: 10, y: 10}]));
    expect(remove.mock.calls.map(([type]) => type)).toEqual([
      'touchmove',
      'touchend',
      'touchcancel',
    ]);
    // No document listener: the swallower of the mouse events Safari may
    // still send rides the window's one shared input stream.
    expect(documentAdd).not.toHaveBeenCalled();
    stop();
    region.remove();
  });

  it('swallows the mouse events Safari still sends for a delivered tap, wherever they land, until its click', () => {
    const {region, field, deliver, stop} = setup();
    const elsewhere = document.createElement('button');
    document.body.append(elsewhere);
    const pressed = vi.fn();
    elsewhere.addEventListener('mousedown', pressed);
    elsewhere.addEventListener('click', pressed);
    // Safari's events for a tap carry its click count.
    const mouse = (type: string) => {
      const event = new MouseEvent(type, {
        bubbles: true,
        cancelable: true,
        detail: 1,
      });
      elsewhere.dispatchEvent(event);
      return event;
    };
    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    field.dispatchEvent(touchEvent('touchend', [], [{x: 12, y: 11}]));
    expect(deliver).toHaveBeenCalledTimes(1);
    // Aimed at what is under the finger now.
    expect(mouse('mousedown').defaultPrevented).toBe(true);
    expect(mouse('click').defaultPrevented).toBe(true);
    expect(pressed).not.toHaveBeenCalled();
    // The tap's click ends it.
    expect(mouse('click').defaultPrevented).toBe(false);
    expect(pressed).toHaveBeenCalledTimes(1);
    stop();
    elsewhere.remove();
    region.remove();
  });

  it('lets go when no click comes and a new press starts, or after the click guard’s window', () => {
    const {region, field, stop} = setup();
    const mousedown = () => {
      const event = new MouseEvent('mousedown', {
        bubbles: true,
        cancelable: true,
        detail: 1,
      });
      document.body.dispatchEvent(event);
      return event.defaultPrevented;
    };
    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    field.dispatchEvent(touchEvent('touchend', [], [{x: 10, y: 10}]));
    // A new press anywhere: a touch's or a mouse's, which starts with its
    // pointerdown.
    document.body.dispatchEvent(new Event('pointerdown', {bubbles: true}));
    expect(mousedown()).toBe(false);

    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    field.dispatchEvent(touchEvent('touchend', [], [{x: 10, y: 10}]));
    // A key's own click (detail 0) goes through.
    const keyClick = new MouseEvent('click', {bubbles: true, cancelable: true});
    document.body.dispatchEvent(keyClick);
    expect(keyClick.defaultPrevented).toBe(false);

    // The guard ends after its window, also when the route goes first.
    vi.useFakeTimers();
    field.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    field.dispatchEvent(touchEvent('touchend', [], [{x: 10, y: 10}]));
    stop();
    expect(mousedown()).toBe(true);
    vi.advanceTimersByTime(CLICK_GUARD_WINDOW_MS);
    expect(mousedown()).toBe(false);
    vi.useRealTimers();
    region.remove();
  });

  it('leaves a touch outside what the caller claims to the browser', () => {
    const {region, deliver, stop} = setup();
    region.dispatchEvent(touchEvent('touchstart', [{x: 10, y: 10}]));
    const end = touchEvent('touchend', [], [{x: 10, y: 10}]);
    region.dispatchEvent(end);
    expect(end.defaultPrevented).toBe(false);
    expect(deliver).not.toHaveBeenCalled();
    stop();
    region.remove();
  });
});

describe('the caret a claimed tap places', () => {
  // Installs (or, with undefined, removes) one caret-from-point API on the
  // document, as each engine has its own.
  function stubCaretApi(
    name: 'caretPositionFromPoint' | 'caretRangeFromPoint',
    value: unknown,
  ) {
    Object.defineProperty(document, name, {configurable: true, value});
  }

  function editable(): {element: HTMLElement; text: Text} {
    const element = document.createElement('div');
    element.setAttribute('contenteditable', 'true');
    // jsdom does not compute isContentEditable.
    Object.defineProperty(element, 'isContentEditable', {value: true});
    const text = document.createTextNode('Hello there');
    element.append(text);
    document.body.append(element);
    return {element, text};
  }

  afterEach(() => {
    Reflect.deleteProperty(document, 'caretPositionFromPoint');
    Reflect.deleteProperty(document, 'caretRangeFromPoint');
    document.body.replaceChildren();
  });

  it('reads the standard caretPositionFromPoint, the only one Firefox has', () => {
    const {element, text} = editable();
    stubCaretApi(
      'caretPositionFromPoint',
      vi.fn(() => ({offsetNode: text, offset: 3})),
    );

    focusAtPoint(element, 20, 10);

    expect(document.activeElement).toBe(element);
    const selection = document.getSelection();
    expect(selection?.anchorNode).toBe(text);
    expect(selection?.anchorOffset).toBe(3);
    expect(selection?.isCollapsed).toBe(true);
  });

  it('puts a text control\u2019s caret where the browser maps the point into it, or after its text', () => {
    const textarea = document.createElement('textarea');
    textarea.value = 'A long draft';
    document.body.append(textarea);
    const focus = vi.spyOn(textarea, 'focus');
    stubCaretApi(
      'caretPositionFromPoint',
      vi.fn(() => ({offsetNode: textarea, offset: 3})),
    );
    focusAtPoint(textarea, 20, 10);
    expect(focus).toHaveBeenCalledWith({preventScroll: true});
    expect(document.activeElement).toBe(textarea);
    expect([textarea.selectionStart, textarea.selectionEnd]).toEqual([3, 3]);

    textarea.blur();
    stubCaretApi(
      'caretPositionFromPoint',
      vi.fn(() => null),
    );
    focusAtPoint(textarea, 20, 10);
    expect([textarea.selectionStart, textarea.selectionEnd]).toEqual([12, 12]);
  });

  it('falls back to caretRangeFromPoint where only WebKit\u2019s exists', () => {
    const {element, text} = editable();
    stubCaretApi(
      'caretRangeFromPoint',
      vi.fn(() => {
        const range = document.createRange();
        range.setStart(text, 5);
        range.collapse(true);
        return range;
      }),
    );

    focusAtPoint(element, 20, 10);

    expect(document.getSelection()?.anchorOffset).toBe(5);
  });
});