Skip to content

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

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

/**
 * @file hitArea.test.ts
 * @input Vitest, jsdom with stubbed matchMedia, IntersectionObserver,
 *   ResizeObserver, requestAnimationFrame and element rects
 * @output Checks the touch hit area: it grows toward 44 px, stops at half the
 *   gap to each neighbour, resolves a group's touch to the nearest target, and
 *   keeps a live control's insets current only where the pointer is coarse,
 *   only on screen, in one batched read-then-write pass per frame
 * @position Test for utils/hitArea.ts
 */

import fs from 'node:fs';
import path from 'node:path';
import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {
  clampedHitInsets,
  groupGrowth,
  HIT_INSET_PROPERTIES,
  type HitInsets,
  type HitRect,
  NO_HIT_INSETS,
  resetHitAreaForTests,
  resolveHitTarget,
  watchHitArea,
  writeHitInsets,
} from './hitArea';

function rect(left: number, top: number, width: number, height: number) {
  return {left, top, right: left + width, bottom: top + height};
}

describe('groupGrowth', () => {
  it('grows each side of a row as far as the member on that edge would, and a wide group by its narrow end members', () => {
    // Three 32 px toggles in a 104 × 32 row, 4 px apart.
    const row = rect(0, 100, 104, 32);
    const members = [
      rect(0, 100, 32, 32),
      rect(36, 100, 32, 32),
      rect(72, 100, 32, 32),
    ];
    expect(groupGrowth(row, members)).toEqual({
      top: 6,
      right: 6,
      bottom: 6,
      left: 6,
    });
    // A column of wide members grows only at its top and bottom.
    const column = rect(0, 0, 120, 64);
    expect(
      groupGrowth(column, [rect(0, 0, 120, 32), rect(0, 32, 120, 32)]),
    ).toEqual({top: 6, right: 0, bottom: 6, left: 0});
    // A row wider than its members shrinks past its last member, so it
    // covers only their targets: 32 px buttons ending 160 px short.
    expect(groupGrowth(rect(0, 100, 264, 32), members)).toEqual({
      top: 6,
      right: -154,
      bottom: 6,
      left: 6,
    });
    expect(groupGrowth(row, [])).toEqual(NO_HIT_INSETS);
    // The full growth it gives stops at a neighbour, as a control's does.
    expect(
      clampedHitInsets(
        row,
        [rect(-8, 100, 4, 32)],
        44,
        groupGrowth(row, members),
      ).left,
    ).toBe(2);
  });
});

describe('clampedHitInsets', () => {
  it('grows a lone 24 px target to 44 px, centered', () => {
    expect(clampedHitInsets(rect(100, 100, 24, 24), [])).toEqual({
      top: 10,
      right: 10,
      bottom: 10,
      left: 10,
    });
  });

  it('does not grow a target already 44 px or larger on an axis', () => {
    expect(clampedHitInsets(rect(0, 0, 44, 44), [])).toEqual(NO_HIT_INSETS);
    expect(clampedHitInsets(rect(0, 0, 120, 24), [])).toEqual({
      top: 10,
      right: 0,
      bottom: 10,
      left: 0,
    });
  });

  it('stops at half the gap to a neighbour on that side, and only that side', () => {
    // A link 8 px to the right.
    expect(
      clampedHitInsets(rect(100, 100, 24, 24), [rect(132, 100, 60, 24)]),
    ).toEqual({top: 10, right: 4, bottom: 10, left: 10});
  });

  it('stops at half the gap to a neighbour that does not grow itself (a long link)', () => {
    // A 32 × 20 switch 8 px from a link wider and taller than 44 px.
    expect(
      clampedHitInsets(rect(100, 100, 32, 20), [rect(140, 88, 120, 44)]).right,
    ).toBe(4);
  });

  it('does not grow toward a neighbour it touches', () => {
    expect(
      clampedHitInsets(rect(100, 100, 24, 24), [rect(124, 100, 24, 24)]).right,
    ).toBe(0);
  });

  it('stops at half the gap even where it would not reach the neighbour itself, so a tap nearer the neighbour is never its', () => {
    // 16 px apart: growing 10 px would take taps 2 px from the neighbour.
    expect(
      clampedHitInsets(rect(100, 100, 24, 24), [rect(140, 100, 24, 24)]).right,
    ).toBe(8);
  });

  it('ignores a neighbour at least twice its growth away', () => {
    expect(
      clampedHitInsets(rect(100, 100, 24, 24), [rect(144, 100, 24, 24)]),
    ).toEqual({top: 10, right: 10, bottom: 10, left: 10});
  });

  it('stops a diagonal neighbour on the side with the larger gap, so neither area reaches the other', () => {
    const a = rect(100, 100, 24, 24);
    // Down and to the right: 4 px across, 6 px down.
    const b = rect(128, 130, 24, 24);
    const insetsA = clampedHitInsets(a, [b]);
    const insetsB = clampedHitInsets(b, [a]);
    expect(insetsA).toEqual({top: 10, right: 10, bottom: 3, left: 10});
    expect(insetsB).toEqual({top: 3, right: 10, bottom: 10, left: 10});
    expect(a.bottom + insetsA.bottom).toBeLessThanOrEqual(b.top - insetsB.top);
  });

  it('cuts the same side as a diagonal neighbour of another size, so the two areas never overlap', () => {
    const small = rect(100, 100, 16, 16);
    // 12 px across and 14 px down.
    const wide = rect(128, 130, 32, 20);
    const a = clampedHitInsets(small, [wide]);
    const b = clampedHitInsets(wide, [small]);
    expect(small.bottom + a.bottom).toBeLessThanOrEqual(wide.top - b.top);
    expect(a.bottom).toBe(7);
    expect(b.top).toBe(7);
  });

  it('cuts a wide and a tall diagonal pair whose full areas would meet', () => {
    const square = rect(100, 100, 32, 32);
    // 4 px across and 12 px down.
    const wide = rect(136, 144, 40, 24);
    const a = clampedHitInsets(square, [wide]);
    const b = clampedHitInsets(wide, [square]);
    expect(square.bottom + a.bottom).toBeLessThanOrEqual(wide.top - b.top);
  });

  it('ignores a neighbour that overlaps the target (an ancestor or an overlay)', () => {
    expect(
      clampedHitInsets(rect(100, 100, 24, 24), [rect(90, 90, 200, 60)]),
    ).toEqual({top: 10, right: 10, bottom: 10, left: 10});
  });
});

describe('resolveHitTarget', () => {
  // Two 28 px buttons 4 px apart, as in a dense toolbar.
  const toolbar: HitRect[] = [rect(0, 0, 28, 28), rect(32, 0, 28, 28)];

  it('gives a touch in the gap to the nearer button', () => {
    expect(resolveHitTarget(29, 14, toolbar)).toBe(0);
    expect(resolveHitTarget(31, 14, toolbar)).toBe(1);
  });

  it('extends each button toward 44 px where nothing is near', () => {
    expect(resolveHitTarget(-7, 14, toolbar)).toBe(0);
    expect(resolveHitTarget(14, 35, toolbar)).toBe(0);
  });

  it('gives a corner touch to the nearer of two diagonal targets', () => {
    const pair: HitRect[] = [rect(100, 100, 24, 24), rect(128, 130, 24, 24)];
    // 9.2 px from the first, 4 px from the second.
    expect(resolveHitTarget(133, 126, pair)).toBe(1);
  });

  it('answers -1 beyond every hit area', () => {
    expect(resolveHitTarget(14, 60, toolbar)).toBe(-1);
  });

  it('picks the nearer target, not the earlier one, where targets overlap', () => {
    const overlapping: HitRect[] = [rect(0, 0, 40, 28), rect(30, 0, 40, 28)];
    expect(resolveHitTarget(36, 14, overlapping)).toBe(1);
  });
});

describe('writeHitInsets', () => {
  it('sets the four custom properties in px', () => {
    const element = document.createElement('div');
    writeHitInsets(element, {top: 1, right: 2, bottom: 3, left: 4});
    expect(element.style.getPropertyValue(HIT_INSET_PROPERTIES.top)).toBe(
      '1px',
    );
    expect(element.style.getPropertyValue(HIT_INSET_PROPERTIES.left)).toBe(
      '4px',
    );
  });
});

describe('watchHitArea', () => {
  let coarse = true;
  let pointerListeners: Set<() => void>;
  let frames: (() => void)[];
  let intersection: ((entries: IntersectionObserverEntry[]) => void) | null;
  const rects = new Map<Element, HitRect>();
  const log: string[] = [];

  function place(element: Element, at: HitRect): void {
    rects.set(element, at);
    element.getBoundingClientRect = () => {
      log.push(`read ${element.id}`);
      const r = rects.get(element) ?? rect(0, 0, 0, 0);
      return {
        ...r,
        x: r.left,
        y: r.top,
        width: r.right - r.left,
        height: r.bottom - r.top,
        toJSON: () => r,
      };
    };
  }

  /** Give `element` the whole-pixel layout size that jsdom leaves at 0. */
  function layOut(element: HTMLElement, width: number, height: number): void {
    Object.defineProperty(element, 'offsetWidth', {
      configurable: true,
      value: width,
    });
    Object.defineProperty(element, 'offsetHeight', {
      configurable: true,
      value: height,
    });
  }

  function show(...elements: Element[]): void {
    intersection?.(
      elements.map(
        target => ({target, isIntersecting: true}) as IntersectionObserverEntry,
      ),
    );
  }

  function flush(): void {
    const due = frames;
    frames = [];
    due.forEach(run => run());
  }

  beforeEach(() => {
    coarse = true;
    pointerListeners = new Set();
    frames = [];
    intersection = null;
    rects.clear();
    log.length = 0;
    vi.stubGlobal('matchMedia', (media: string) => ({
      media,
      get matches() {
        return media === '(pointer: coarse)' && coarse;
      },
      addEventListener: (_type: string, listener: () => void) =>
        pointerListeners.add(listener),
      removeEventListener: (_type: string, listener: () => void) =>
        pointerListeners.delete(listener),
    }));
    vi.stubGlobal(
      'IntersectionObserver',
      class {
        constructor(callback: (entries: IntersectionObserverEntry[]) => void) {
          intersection = callback;
        }
        observe() {}
        unobserve() {}
        disconnect() {}
      },
    );
    vi.stubGlobal('requestAnimationFrame', (run: () => void) => {
      frames.push(run);
      return frames.length;
    });
    vi.stubGlobal('cancelAnimationFrame', () => {});
    document.body.innerHTML =
      '<label><span id="switch" role="switch" tabindex="0"></span> Wi-Fi</label>' +
      '<a id="link" href="#details">Details</a>' +
      '<span id="other" role="switch" tabindex="0"></span>';
  });

  afterEach(() => {
    resetHitAreaForTests();
    vi.restoreAllMocks();
    vi.unstubAllGlobals();
    document.body.innerHTML = '';
  });

  const byId = (id: string) => document.getElementById(id) as HTMLElement;

  it('measures an on-screen control in the next frame and stops at half the gap to a neighbouring link', () => {
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    place(byId('link'), rect(132, 100, 60, 24));
    place(byId('other'), rect(400, 400, 24, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    expect(heard).toEqual([]);
    flush();
    expect(heard).toEqual([{top: 10, right: 4, bottom: 10, left: 10}]);
    stop();
  });

  it('measures a control in an opening layer by its layout box, so its insets hold once the layer settles', () => {
    // The layer opens from half size about the page origin, so every rect on
    // screen is half its layout box during the first pass.
    const half = ({left, top, right, bottom}: HitRect) => ({
      left: left / 2,
      top: top / 2,
      right: right / 2,
      bottom: bottom / 2,
    });
    const control = byId('switch');
    Object.assign(control.style, {
      width: '24px',
      height: '24px',
      boxSizing: 'border-box',
    });
    layOut(control, 24, 24);
    place(control, half(rect(100, 100, 24, 24)));
    place(byId('link'), half(rect(132, 100, 60, 24)));
    place(byId('other'), half(rect(400, 400, 24, 24)));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    // The same insets as the page at full size gives.
    expect(heard).toEqual([{top: 10, right: 4, bottom: 10, left: 10}]);
    stop();
  });

  it('reads no computed style for a control at its layout size', () => {
    const control = byId('switch');
    const other = byId('other');
    layOut(control, 24, 24);
    place(control, rect(100, 100, 24, 24));
    place(other, rect(400, 400, 24, 24));
    place(byId('link'), rect(132, 100, 60, 24));
    const getComputedStyle = vi.spyOn(window, 'getComputedStyle');
    const stops = [control, other].map(element =>
      watchHitArea(element, () => {}),
    );
    show(control, other);
    flush();
    // One control is at its layout size and the other has none, so neither
    // resolves style in the measuring pass.
    expect(getComputedStyle).not.toHaveBeenCalled();
    stops.forEach(stop => stop());
  });

  it("reads a group's growth from its members in its layout px, so a group in an opening layer keeps its insets", () => {
    // As above, the layer opens from half size about the page origin.
    const half = ({left, top, right, bottom}: HitRect) => ({
      left: left / 2,
      top: top / 2,
      right: right / 2,
      bottom: bottom / 2,
    });
    const group = byId('other');
    Object.assign(group.style, {
      width: '68px',
      height: '32px',
      boxSizing: 'border-box',
    });
    layOut(group, 68, 32);
    place(group, half(rect(200, 300, 68, 32)));
    place(byId('switch'), half(rect(100, 100, 24, 24)));
    place(byId('link'), half(rect(132, 100, 60, 24)));
    // Two 32 px members, each 6 px short of 44 on each axis.
    const members = [
      half(rect(200, 300, 32, 32)),
      half(rect(236, 300, 32, 32)),
    ];
    const heard: HitInsets[] = [];
    const stop = watchHitArea(group, insets => heard.push(insets), {
      growth: (box, toLayout) => groupGrowth(box, members.map(toLayout)),
    });
    show(group);
    flush();
    // At half size the members would read 16 px and grow 14 px.
    expect(heard).toEqual([{top: 6, right: 6, bottom: 6, left: 6}]);
    stop();
  });

  it('matches the page against its selector once, and again only after a mutation can change what it matches', () => {
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    place(byId('link'), rect(132, 100, 60, 24));
    place(byId('other'), rect(400, 400, 24, 24));
    const queries = vi.spyOn(document, 'querySelectorAll');
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    expect(queries).toHaveBeenCalledTimes(1);
    expect(heard).toEqual([{top: 10, right: 4, bottom: 10, left: 10}]);

    // A later pass reads every rect again, but finds the elements kept.
    place(byId('link'), rect(140, 100, 60, 24));
    log.length = 0;
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(queries).toHaveBeenCalledTimes(1);
    expect(log).toContain('read link');
    expect(heard.at(-1)).toEqual({top: 10, right: 8, bottom: 10, left: 10});

    // A neighbour added in the same task as the pass counts in it.
    const above = document.createElement('button');
    above.id = 'above';
    document.body.append(above);
    place(above, rect(100, 80, 24, 12));
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(queries).toHaveBeenCalledTimes(2);
    expect(heard.at(-1)).toEqual({top: 4, right: 8, bottom: 10, left: 10});

    // An attribute the selector reads makes an element a neighbour.
    const below = document.createElement('span');
    below.id = 'below';
    document.body.append(below);
    place(below, rect(100, 130, 24, 12));
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(heard.at(-1)).toEqual({top: 4, right: 8, bottom: 10, left: 10});
    below.setAttribute('role', 'button');
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(heard.at(-1)).toEqual({top: 4, right: 8, bottom: 3, left: 10});

    // A neighbour removed stops counting.
    above.remove();
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(heard.at(-1)).toEqual({top: 10, right: 8, bottom: 3, left: 10});
    stop();
  });

  it('counts a control watched after the last pass by its own box, not by a part inside it', () => {
    // A group whose box reaches nearer the control than the input inside it.
    const group = document.createElement('div');
    const input = document.createElement('input');
    group.append(input);
    document.body.append(group);
    place(group, rect(100, 60, 24, 30));
    place(input, rect(100, 20, 24, 10));
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    place(byId('link'), rect(132, 100, 60, 24));
    place(byId('other'), rect(400, 400, 24, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    // The input is too far away to stop the control's growth.
    expect(heard.at(-1)).toEqual({top: 10, right: 4, bottom: 10, left: 10});
    // The group starts a watch. No element changes, but its box, not its
    // input, is now the neighbour.
    const stopGroup = watchHitArea(group, () => {});
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(heard.at(-1)).toEqual({top: 5, right: 4, bottom: 10, left: 10});
    // The group stops its watch: its input, too far away, is the neighbour
    // again.
    stopGroup();
    window.dispatchEvent(new Event('resize'));
    flush();
    expect(heard.at(-1)).toEqual({top: 10, right: 4, bottom: 10, left: 10});
    stop();
  });

  it('measures nothing off screen', () => {
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    flush();
    expect(heard).toEqual([]);
    expect(log).toEqual([]);
    stop();
  });

  it('batches every pending control into one frame: all reads, then all writes', () => {
    // The clock holds still, so a slow machine cannot spend the frame budget
    // and split the batch. The budget has its own case below.
    vi.spyOn(performance, 'now').mockReturnValue(0);
    const first = byId('switch');
    const second = byId('other');
    place(first, rect(100, 100, 24, 24));
    place(second, rect(400, 400, 24, 24));
    place(byId('link'), rect(132, 100, 60, 24));
    const stops = [first, second].map(element =>
      watchHitArea(element, () => log.push(`write ${element.id}`)),
    );
    show(first, second);
    expect(frames).toHaveLength(1);
    flush();
    const firstWrite = log.findIndex(entry => entry.startsWith('write'));
    expect(firstWrite).toBeGreaterThan(0);
    expect(
      log.slice(firstWrite).every(entry => entry.startsWith('write')),
    ).toBe(true);
    expect(log.filter(entry => entry.startsWith('write'))).toEqual([
      'write switch',
      'write other',
    ]);
    stops.forEach(stop => stop());
  });

  it('counts a neighbour up to 44 px away for a small target, so two 8 px dots 24 px apart meet in the middle', () => {
    const control = byId('switch');
    const other = byId('other');
    place(control, rect(100, 100, 8, 8));
    place(other, rect(132, 100, 8, 8));
    place(byId('link'), rect(400, 400, 60, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    expect(heard.at(-1)?.right).toBe(12);
    stop();
  });

  it('gives a second watch of the same element its insets', () => {
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    const first = watchHitArea(control, () => {});
    show(control);
    flush();
    const heard: HitInsets[] = [];
    const second = watchHitArea(control, insets => heard.push(insets));
    flush();
    expect(heard).toEqual([{top: 10, right: 10, bottom: 10, left: 10}]);
    first();
    second();
  });

  it('carries controls past the frame budget to the next frame, measuring at least one a frame', () => {
    const controls = ['switch', 'other'].map(byId);
    place(controls[0], rect(100, 100, 24, 24));
    place(controls[1], rect(400, 400, 24, 24));
    // Every clock read is 5 ms later: each frame's budget is spent after one
    // control.
    let clock = 0;
    vi.spyOn(performance, 'now').mockImplementation(() => (clock += 5));
    const heard: string[] = [];
    const stops = controls.map(element =>
      watchHitArea(element, () => heard.push(element.id)),
    );
    show(...controls);
    flush();
    expect(heard).toEqual(['switch']);
    expect(frames).toHaveLength(1);
    flush();
    expect(heard).toEqual(['switch', 'other']);
    expect(frames).toHaveLength(0);
    stops.forEach(stop => stop());
  });

  it('measures nothing where the primary pointer is fine, and returns to 0 when it turns fine', () => {
    coarse = false;
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    expect(heard).toEqual([]);
    expect(log).toEqual([]);
    // The pointer turns coarse (the observers start, and the visibility
    // observer's first notice comes), then fine again.
    coarse = true;
    pointerListeners.forEach(listener => listener());
    show(control);
    flush();
    expect(heard).toEqual([{top: 10, right: 10, bottom: 10, left: 10}]);
    coarse = false;
    pointerListeners.forEach(listener => listener());
    expect(heard.at(-1)).toEqual(NO_HIT_INSETS);
    stop();
  });

  it('re-measures once its parent’s text settles after a change that moves a neighbour without resizing the control', async () => {
    vi.useFakeTimers({toFake: ['setTimeout', 'clearTimeout']});
    const control = byId('switch');
    const link = byId('link');
    place(control, rect(100, 100, 24, 24));
    place(link, rect(400, 100, 60, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    expect(heard.at(-1)?.right).toBe(10);
    // The label beside the switch shortens, and the link moves to 8 px away.
    place(link, rect(132, 100, 60, 24));
    (control.parentElement as HTMLElement).lastChild!.textContent = ' Wi';
    await Promise.resolve();
    vi.advanceTimersByTime(100);
    flush();
    expect(heard.at(-1)?.right).toBe(4);
    stop();
    vi.useRealTimers();
  });

  it('swallows the click of a touch that a fresh measurement puts nearer a neighbour, and only that one', () => {
    const control = byId('switch');
    const link = byId('link');
    place(control, rect(100, 100, 24, 24));
    place(link, rect(400, 100, 60, 24));
    const stop = watchHitArea(control, () => {});
    show(control);
    flush();
    // The link moved to 8 px away with nothing re-measuring yet.
    place(link, rect(132, 100, 60, 24));
    const touch = (x: number) => {
      const press = new Event('pointerdown', {bubbles: true});
      Object.assign(press, {pointerType: 'touch', clientX: x, clientY: 112});
      control.dispatchEvent(press);
    };
    const click = () => {
      const event = new MouseEvent('click', {
        bubbles: true,
        cancelable: true,
        detail: 1,
      });
      control.dispatchEvent(event);
      return event.defaultPrevented;
    };
    // 6 px right of the switch: inside the old area, 2 px from the link.
    touch(130);
    expect(click()).toBe(true);
    // One-shot: the next click is the control's.
    expect(click()).toBe(false);
    // A touch with no click leaves nothing behind for the next touch.
    touch(130);
    touch(110);
    expect(click()).toBe(false);
    // A keyboard activation (detail 0) after a touch with no click goes
    // through, and so does a click after the browser cancelled the touch.
    touch(130);
    const key = new MouseEvent('click', {bubbles: true, cancelable: true});
    control.dispatchEvent(key);
    expect(key.defaultPrevented).toBe(false);
    touch(130);
    control.dispatchEvent(new Event('pointercancel', {bubbles: true}));
    expect(click()).toBe(false);
    // A press elsewhere (the control's label) ends it before its click.
    touch(130);
    link.dispatchEvent(new Event('pointerdown', {bubbles: true}));
    expect(click()).toBe(false);
    stop();
  });

  it('reads nothing on the page at a finger’s press, and swallows no click, for a watch whose owner reads its own targets (checkAtPress off)', () => {
    const control = byId('switch');
    const link = byId('link');
    place(control, rect(100, 100, 24, 24));
    place(link, rect(400, 100, 60, 24));
    const stop = watchHitArea(control, () => {}, {checkAtPress: false});
    show(control);
    flush();
    // The link moved to 8 px away with nothing re-measuring yet.
    place(link, rect(132, 100, 60, 24));
    const read = vi.spyOn(link, 'getBoundingClientRect');
    const press = new Event('pointerdown', {bubbles: true});
    Object.assign(press, {pointerType: 'touch', clientX: 130, clientY: 112});
    control.dispatchEvent(press);
    expect(read).not.toHaveBeenCalled();
    const click = new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      detail: 1,
    });
    control.dispatchEvent(click);
    expect(click.defaultPrevented).toBe(false);
    stop();
  });

  it('runs no observer or window listener for hit areas while the primary pointer is fine', () => {
    coarse = false;
    const constructed = vi.fn();
    vi.stubGlobal(
      'IntersectionObserver',
      class {
        constructor() {
          constructed();
        }
        observe() {}
        unobserve() {}
        disconnect() {}
      },
    );
    const onWindow = vi.spyOn(window, 'addEventListener');
    const onElement = vi.spyOn(byId('switch'), 'addEventListener');
    const stop = watchHitArea(byId('switch'), () => {});
    expect(constructed).not.toHaveBeenCalled();
    expect(onWindow).not.toHaveBeenCalled();
    expect(onElement).not.toHaveBeenCalled();
    stop();
  });

  it('leaves a touch on content that the element paints past its own box to that content, however near a neighbour is', () => {
    // A row moved aside, its panel's entry painted beside it, and the next
    // row 2 px below the touch.
    document.body.insertAdjacentHTML(
      'beforeend',
      '<div id="row"><button id="entry">Read</button></div>' +
        '<a id="next" href="#next">Next</a>',
    );
    const row = byId('row');
    const entry = byId('entry');
    place(row, rect(88, 16, 388, 60));
    place(entry, rect(16, 16, 72, 60));
    place(byId('next'), rect(16, 78, 388, 60));
    const stop = watchHitArea(row, () => {}, {ownsDescendantTouches: true});
    show(row);
    flush();
    // On the entry: 36 px from the row's box, 32 px from the next row.
    const press = new Event('pointerdown', {bubbles: true});
    Object.assign(press, {pointerType: 'touch', clientX: 52, clientY: 46});
    entry.dispatchEvent(press);
    const click = new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      detail: 1,
    });
    entry.dispatchEvent(click);
    expect(click.defaultPrevented).toBe(false);
    // The same touch on the row itself, in its band, is still checked.
    const bandPress = new Event('pointerdown', {bubbles: true});
    Object.assign(bandPress, {
      pointerType: 'touch',
      clientX: 52,
      clientY: 46,
    });
    row.dispatchEvent(bandPress);
    const bandClick = new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      detail: 1,
    });
    row.dispatchEvent(bandClick);
    expect(bandClick.defaultPrevented).toBe(true);
    stop();
  });

  it('still swallows a touch on a control’s own grown input that a neighbour is nearer, unless the watch owns its descendants’ touches', () => {
    // A switch whose invisible input grows past its track, as its coarse hit
    // area. A link moved to 2 px past the switch.
    const control = byId('switch');
    control.insertAdjacentHTML('beforeend', '<input id="input" />');
    const input = byId('input');
    place(control, rect(100, 100, 24, 24));
    place(input, rect(100, 100, 28, 24));
    place(byId('link'), rect(126, 100, 60, 24));
    const stop = watchHitArea(control, () => {});
    show(control);
    flush();
    // On the input, 2.5 px past the switch and 0.5 px from the link.
    const press = new Event('pointerdown', {bubbles: true});
    Object.assign(press, {pointerType: 'touch', clientX: 126.5, clientY: 112});
    input.dispatchEvent(press);
    const click = new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      detail: 1,
    });
    input.dispatchEvent(click);
    expect(click.defaultPrevented).toBe(true);
    stop();
  });

  it('swallows a touch inside the fresh area that an offset neighbour is nearer (a corner)', () => {
    const control = byId('switch');
    // A tall link beside it, 8 px to the right, reaching far below.
    place(control, rect(100, 100, 24, 24));
    place(byId('link'), rect(132, 100, 60, 80));
    const stop = watchHitArea(control, () => {});
    show(control);
    flush();
    // Inside the area (right inset 4, bottom 10), below the switch: 5 px from
    // the link, 9.5 px from the switch.
    const press = new Event('pointerdown', {bubbles: true});
    Object.assign(press, {pointerType: 'touch', clientX: 127, clientY: 133});
    control.dispatchEvent(press);
    const click = new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      detail: 1,
    });
    control.dispatchEvent(click);
    expect(click.defaultPrevented).toBe(true);
    stop();
  });

  it('counts tree items, menu checkbox and radio items as neighbours', () => {
    document.body.innerHTML =
      '<span id="switch" role="switch" tabindex="0"></span>' +
      '<div id="item" role="treeitem"></div>';
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    place(byId('item'), rect(132, 100, 60, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    flush();
    expect(heard.at(-1)?.right).toBe(4);
    stop();
  });

  it('leaves a touch the browser hands a lone control a few px past its area to it: only a nearer neighbour swallows', () => {
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    place(byId('link'), rect(400, 400, 60, 24));
    const stop = watchHitArea(control, () => {});
    show(control);
    flush();
    // 3 px right of the 44 px area (10 px of growth), nothing near.
    const press = new Event('pointerdown', {bubbles: true});
    Object.assign(press, {pointerType: 'touch', clientX: 137, clientY: 112});
    control.dispatchEvent(press);
    const click = new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      detail: 1,
    });
    control.dispatchEvent(click);
    expect(click.defaultPrevented).toBe(false);
    stop();
  });

  it('measures a watched neighbour by its own box, not by its grown input', () => {
    document.body.innerHTML =
      '<div id="a"><input id="ia" role="switch"></div>' +
      '<div id="b"><input id="ib" role="switch"></div>';
    const a = byId('a');
    const b = byId('b');
    place(a, rect(100, 100, 32, 20));
    place(b, rect(100, 128, 32, 20));
    // Each input is grown to its hit area: 44 px tall.
    place(byId('ia'), rect(94, 88, 44, 44));
    place(byId('ib'), rect(94, 116, 44, 44));
    const heard: HitInsets[] = [];
    const stopA = watchHitArea(a, insets => heard.push(insets));
    const stopB = watchHitArea(b, () => {});
    show(a, b);
    flush();
    // Half the 8 px gap to b's box, not a quarter (b's input reaches a).
    expect(heard.at(-1)?.bottom).toBe(4);
    stopA();
    stopB();
  });

  it('listens for presses once, on the document: a watched control, row or handle gets no listener of its own (spec:AST-103 FR5)', () => {
    const elements = ['switch', 'other'].map(byId);
    const onElements = elements.map(element =>
      vi.spyOn(element, 'addEventListener'),
    );
    const onDocument = vi.spyOn(document, 'addEventListener');
    const stops = elements.map(element => watchHitArea(element, () => {}));
    for (const spy of onElements) {
      expect(spy).not.toHaveBeenCalled();
    }
    expect(
      onDocument.mock.calls.filter(([type]) => type === 'pointerdown'),
    ).toHaveLength(1);
    stops.forEach(stop => stop());
  });

  it('observes the page for its interactive elements only while the pointer is coarse and a watch is live (spec:AST-094 FR24)', () => {
    const Native = globalThis.MutationObserver;
    let pageObservers = 0;
    vi.stubGlobal(
      'MutationObserver',
      class extends Native {
        private isOnPage = false;
        override observe(target: Node, options?: MutationObserverInit) {
          if (target === document && !this.isOnPage) {
            this.isOnPage = true;
            pageObservers += 1;
          }
          super.observe(target, options);
        }
        override disconnect() {
          if (this.isOnPage) {
            this.isOnPage = false;
            pageObservers -= 1;
          }
          super.disconnect();
        }
      },
    );
    const control = byId('switch');
    const other = byId('other');
    place(control, rect(100, 100, 24, 24));
    place(other, rect(400, 400, 24, 24));
    place(byId('link'), rect(132, 100, 60, 24));
    // Under a fine pointer: none.
    coarse = false;
    const stops = [control, other].map(element =>
      watchHitArea(element, () => {}),
    );
    show(control, other);
    flush();
    expect(pageObservers).toBe(0);
    // Coarse, with two watches: one.
    coarse = true;
    pointerListeners.forEach(listener => listener());
    show(control, other);
    flush();
    expect(pageObservers).toBe(1);
    // The pointer turns fine: released.
    coarse = false;
    pointerListeners.forEach(listener => listener());
    expect(pageObservers).toBe(0);
    // Coarse again, then the last watch stops: released.
    coarse = true;
    pointerListeners.forEach(listener => listener());
    show(control, other);
    flush();
    expect(pageObservers).toBe(1);
    stops[0]();
    expect(pageObservers).toBe(1);
    stops[1]();
    expect(pageObservers).toBe(0);
  });

  it('removes its document listener when the last watch stops (spec:AST-094 FR24)', () => {
    const offDocument = vi.spyOn(document, 'removeEventListener');
    const stops = ['switch', 'other'].map(id =>
      watchHitArea(byId(id), () => {}),
    );
    stops[0]();
    expect(
      offDocument.mock.calls.filter(([type]) => type === 'pointerdown'),
    ).toHaveLength(0);
    stops[1]();
    expect(
      offDocument.mock.calls.filter(([type]) => type === 'pointerdown'),
    ).toHaveLength(1);
  });

  it('leaves nothing behind after resetHitAreaForTests, even from a watch never stopped', () => {
    watchHitArea(byId('switch'), () => {});
    const offDocument = vi.spyOn(document, 'removeEventListener');
    resetHitAreaForTests();
    expect(
      offDocument.mock.calls.filter(([type]) => type === 'pointerdown'),
    ).toHaveLength(1);
    coarse = false;
    const onDocument = vi.spyOn(document, 'addEventListener');
    const stop = watchHitArea(byId('other'), () => {});
    expect(onDocument).not.toHaveBeenCalled();
    stop();
  });

  it('reads the pointer query at each watch, so a watch never left behind keeps a stale coarse answer', () => {
    const left = watchHitArea(byId('switch'), () => {});
    // The environment's pointer turns fine through a new query object (a
    // test's stub), and the earlier watch never stopped.
    coarse = false;
    const other = byId('other');
    const onElement = vi.spyOn(other, 'addEventListener');
    const stop = watchHitArea(other, () => {});
    expect(onElement).not.toHaveBeenCalled();
    stop();
    left();
  });

  it('stops hearing a control after its function runs', () => {
    const control = byId('switch');
    place(control, rect(100, 100, 24, 24));
    const heard: HitInsets[] = [];
    const stop = watchHitArea(control, insets => heard.push(insets));
    show(control);
    stop();
    flush();
    expect(heard).toEqual([]);
  });

  it('stops a watch whose window closed before it, as a removed iframe’s', () => {
    const iframe = document.body.appendChild(document.createElement('iframe'));
    const frameDocument = iframe.contentDocument as Document;
    const control = frameDocument.body.appendChild(
      frameDocument.createElement('button'),
    );
    const stop = watchHitArea(control, () => {});
    iframe.remove();
    expect(() => stop()).not.toThrow();
  });
});

describe('the package surface', () => {
  it('keeps hitArea out of the public utils entry', () => {
    const entry = fs.readFileSync(
      path.join(path.dirname(new URL(import.meta.url).pathname), 'index.ts'),
      'utf8',
    );
    expect(entry).not.toMatch(/hitArea/);
  });
});