Skip to content

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

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

/**
 * @file scrollKeyboardDelegation.test.ts
 * @input Private delegation behavior, explicit visibility, and focus event sequences
 * @output Eligibility, keyboard intent, observer cost, and cleanup regressions
 * @position DOM-level policy proof; browser tests own native Tab and scroll evidence
 */

import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
import {attachScrollKeyboardDelegation} from './scrollKeyboardDelegation';
import {FOCUSABLE_SELECTOR} from './focusableSelector';

let detach: (() => void) | undefined;
let before: HTMLButtonElement;
let viewport: HTMLDivElement;
let content: HTMLDivElement;

beforeEach(() => {
  vi.spyOn(HTMLElement.prototype, 'getClientRects').mockReturnValue([
    new DOMRect(0, 0, 20, 20),
  ] as unknown as DOMRectList);
  before = document.createElement('button');
  viewport = document.createElement('div');
  viewport.tabIndex = 0;
  content = document.createElement('div');
  viewport.append(content);
  // The pinned jsdom selector engine orders this comma-separated selector by
  // selector group. Browsers return document order; normalize only the emulator.
  const query = content.querySelectorAll.bind(content);
  vi.spyOn(content, 'querySelectorAll').mockImplementation(selector => {
    const result = query(selector);
    return selector === FOCUSABLE_SELECTOR
      ? ([...result].sort((a, b) =>
          a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
            ? -1
            : 1,
        ) as unknown as NodeListOf<Element>)
      : result;
  });
  document.body.append(before, viewport);
  detach = attachScrollKeyboardDelegation(viewport, content);
});

afterEach(() => {
  detach?.();
  before.remove();
  viewport.remove();
  vi.restoreAllMocks();
});

// jsdom supplies no Tab default action. Complete dispatch before focusing to
// model the browser's event boundary; real traversal is tested in both engines.
function enter() {
  before.focus();
  before.dispatchEvent(
    new KeyboardEvent('keydown', {key: 'Tab', bubbles: true}),
  );
  viewport.focus();
}

describe('scroll keyboard delegation', () => {
  it('inspects content only on keyboard entry and leaves mutation observation untouched', () => {
    content.innerHTML = '<button>Action</button>';
    const scan = vi.spyOn(content, 'querySelectorAll');
    const observe = vi.spyOn(MutationObserver.prototype, 'observe');
    viewport.focus();
    content.firstElementChild?.setAttribute('data-state', 'changed');
    viewport.dispatchEvent(new Event('scroll'));
    expect(scan).not.toHaveBeenCalled();
    expect(observe).not.toHaveBeenCalled();
    enter();
    expect(scan).toHaveBeenCalledTimes(1);
    expect(document.activeElement).toBe(content.firstElementChild);
    expect(viewport.tabIndex).toBe(0);
  });

  it.each([
    '<input aria-label="Input"><button>Later action</button>',
    '<button role="radio">Radio</button><button>Later action</button>',
    '<div role="toolbar"><button>Toolbar action</button></div>',
    '<div contenteditable="true"><button>Editor action</button></div>',
    '<button aria-haspopup="menu">Open menu</button>',
    '<button aria-disabled="true">Unavailable</button>',
    '<button aria-hidden="true">Hidden from AT</button><button>Later action</button>',
    '<button>Zero</button><button tabindex="1">Earlier positive stop</button>',
    '<div tabindex="0">Custom target</div><button>Later action</button>',
  ])('does not skip an excluded first target: %s', markup => {
    content.innerHTML = markup;
    enter();
    expect(document.activeElement).toBe(viewport);
  });

  it.each(['disabled', 'hidden', 'tabindex="-2"', 'style="visibility:hidden"'])(
    'skips a nonsequential target (%s)',
    attributes => {
      content.innerHTML = `<button ${attributes}>Skipped</button><button>Action</button>`;
      enter();
      expect(document.activeElement).toBe(content.lastElementChild);
    },
  );

  it('rechecks ancestor eligibility on the next entry', () => {
    content.innerHTML = '<div><button>Action</button></div>';
    enter();
    expect(document.activeElement).toBe(content.querySelector('button'));
    content.firstElementChild?.setAttribute('role', 'menu');
    enter();
    expect(document.activeElement).toBe(viewport);
  });

  it('retains programmatic focus during a Tab handler even without preventDefault', () => {
    content.innerHTML = '<button>Action</button>';
    before.addEventListener('keydown', () => viewport.focus(), {once: true});
    before.focus();
    before.dispatchEvent(
      new KeyboardEvent('keydown', {key: 'Tab', bubbles: true}),
    );
    expect(document.activeElement).toBe(viewport);
  });

  it('does not retain canceled keyboard intent', () => {
    content.innerHTML = '<button>Action</button>';
    before.addEventListener('keydown', event => event.preventDefault(), {
      once: true,
    });
    before.focus();
    before.dispatchEvent(
      new KeyboardEvent('keydown', {
        key: 'Tab',
        bubbles: true,
        cancelable: true,
      }),
    );
    viewport.focus();
    expect(document.activeElement).toBe(viewport);
  });

  it('restores the skipped viewport on cancellation and cleans up pending work', () => {
    content.innerHTML = '<button>Action</button><button>Last</button>';
    enter();
    const first = content.firstElementChild as HTMLElement;
    (content.lastElementChild as HTMLElement).focus();
    first.focus();
    first.dispatchEvent(
      new KeyboardEvent('keydown', {key: 'Tab', shiftKey: true, bubbles: true}),
    );
    expect(viewport.tabIndex).toBe(-1);
    detach?.();
    detach = undefined;
    expect(viewport.tabIndex).toBe(0);
    enter();
    expect(document.activeElement).toBe(viewport);
  });
});

describe('a viewport that is its own content box', () => {
  function attachToItself(markup: string) {
    detach?.();
    viewport.innerHTML = markup;
    const query = viewport.querySelectorAll.bind(viewport);
    vi.spyOn(viewport, 'querySelectorAll').mockImplementation(selector => {
      const result = query(selector);
      return selector === FOCUSABLE_SELECTOR
        ? ([...result].sort((a, b) =>
            a.compareDocumentPosition(b) & Node.DOCUMENT_POSITION_FOLLOWING
              ? -1
              : 1,
          ) as unknown as NodeListOf<Element>)
        : result;
    });
    detach = attachScrollKeyboardDelegation(viewport, viewport);
  }

  it('delegates Tab entry to its first link or button, never to itself', () => {
    attachToItself(
      '<p>Text</p><a href="#first">First link</a><button>Later</button>',
    );
    enter();
    expect(document.activeElement).toBe(viewport.querySelector('a'));
  });

  it('keeps the stop on itself when nothing inside is focusable', () => {
    attachToItself('<p>Only text</p>');
    enter();
    expect(document.activeElement).toBe(viewport);
  });
});