Skip to content

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

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

/**
 * @file menu.fixtures.ts
 * @input Plain HTML menus opened from a button, conforming and deliberately violating
 * @output MENU_FIXTURES, their subject and relation selectors, and the expectation → violating-fixture map
 * @position Contract self-test data for menu.jsdom.test.ts and menu.chromium.spec.ts
 */

import type {MenuStateFacts} from './menu';

export const SUBJECT_SELECTOR = '#menu';
export const OPENER_SELECTOR = '#opener';

/**
 * How the fixture menu behaves. One script reads these from the menu's data
 * attributes, so a violating fixture changes exactly one behavior.
 */
interface Behavior {
  /** Items ArrowDown advances by. */
  readonly downStep?: 1 | 2;
  readonly up?: boolean;
  readonly wrap?: boolean;
  readonly homeEnd?: boolean;
  readonly typeahead?: boolean;
  /** Enter: close and return focus, stay open, or close and drop focus. */
  readonly enter?: 'return' | 'stay' | 'drop';
  /** Whether Enter runs the item's action (counted on `window.__menuActivations`). */
  readonly activate?: boolean;
  /** Escape: close and return focus, do nothing, or close and drop focus. */
  readonly escape?: 'return' | 'ignore' | 'drop';
  /** Tab: close (focus moves on from the opener) or leave the menu open. */
  readonly tab?: 'close' | 'keep';
}

/**
 * The smallest menu behavior: roving focus over enabled items, optional wrap,
 * Home/End and typeahead, Enter running the item's action (counted on
 * `window.__menuActivations`) and closing back to the opener, Escape closing
 * back to the opener, Tab closing and letting the browser move focus on from
 * the opener. jsdom does not run it; the jsdom lane reads DOM attributes only.
 */
const SCRIPT = `<script>(() => {
  const menu = document.getElementById('menu');
  const opener = document.getElementById('opener');
  const d = menu.dataset;
  const enabled = () => [...menu.querySelectorAll('[data-item]')].filter(
    item => item.getAttribute('aria-disabled') !== 'true' && !item.hasAttribute('data-disabled'));
  const close = returnFocus => {
    if (!returnFocus && menu.contains(document.activeElement)) document.activeElement.blur();
    menu.hidden = true;
    opener.setAttribute('aria-expanded', 'false');
    if (returnFocus) opener.focus();
  };
  menu.addEventListener('keydown', event => {
    const list = enabled();
    const n = list.length;
    const i = list.indexOf(document.activeElement);
    const go = k => { event.preventDefault(); list[k].focus(); };
    switch (event.key) {
      case 'ArrowDown': {
        const k = i + Number(d.downStep);
        return go(k < n ? k : d.wrap === 'true' ? 0 : n - 1);
      }
      case 'ArrowUp':
        if (d.up !== 'true') return;
        return go(i > 0 ? i - 1 : d.wrap === 'true' ? n - 1 : 0);
      case 'Home':
        if (d.homeEnd === 'true') go(0);
        return;
      case 'End':
        if (d.homeEnd === 'true') go(n - 1);
        return;
      case 'Enter':
        event.preventDefault();
        if (d.activate === 'true') window.__menuActivations = (window.__menuActivations || 0) + 1;
        if (d.enter !== 'stay') close(d.enter === 'return');
        return;
      case 'Escape':
        if (d.escape === 'ignore') return;
        event.preventDefault();
        close(d.escape === 'return');
        return;
      case 'Tab':
        if (d.tab === 'close') { opener.focus(); menu.hidden = true; opener.setAttribute('aria-expanded', 'false'); }
        return;
    }
    if (d.typeahead === 'true' && event.key.length === 1) {
      const c = event.key.toLowerCase();
      for (let j = 1; j <= n; j++) {
        const item = list[(i + j + n) % n];
        if (item.textContent.trim().toLowerCase().startsWith(c)) { go((i + j + n) % n); return; }
      }
    }
  });
})();</script>`;

interface Item {
  readonly id: string;
  readonly label: string;
  readonly role?: string | null;
  readonly checked?: boolean | null;
  /** Disabled and exposed as aria-disabled. */
  readonly disabled?: boolean;
  /** Disabled for the keyboard script but not exposed. */
  readonly hiddenDisabled?: boolean;
}

function itemHtml(item: Item): string {
  const role = item.role === undefined ? 'menuitem' : item.role;
  return `<div id="${item.id}" data-item tabindex="-1"${role == null ? '' : ` role="${role}"`}${item.checked == null ? '' : ` aria-checked="${item.checked}"`}${item.disabled ? ' aria-disabled="true"' : ''}${item.hiddenDisabled ? ' data-disabled' : ''}>${item.label}</div>`;
}

function menuHtml({
  items,
  behavior = {},
  role = 'menu',
  label = 'Actions',
}: {
  items: readonly (Item | {group: string; items: readonly Item[]})[];
  behavior?: Behavior;
  role?: string;
  label?: string | null;
}): string {
  const b: Required<Behavior> = {
    downStep: 1,
    up: true,
    wrap: true,
    homeEnd: true,
    typeahead: true,
    enter: 'return',
    activate: true,
    escape: 'return',
    tab: 'close',
    ...behavior,
  };
  const data = `data-down-step="${b.downStep}" data-up="${b.up}" data-wrap="${b.wrap}" data-home-end="${b.homeEnd}" data-typeahead="${b.typeahead}" data-enter="${b.enter}" data-activate="${b.activate}" data-escape="${b.escape}" data-tab="${b.tab}"`;
  const body = items
    .map(entry =>
      'group' in entry
        ? `<div role="group" aria-label="${entry.group}">${entry.items.map(itemHtml).join('')}</div>`
        : itemHtml(entry),
    )
    .join('');
  const opener = `<button type="button" id="opener" aria-haspopup="menu" aria-expanded="true" aria-controls="menu">Actions</button>`;
  return `${opener}<div id="menu" role="${role}"${label == null ? '' : ` aria-label="${label}"`} tabindex="-1" ${data}>${body}</div>${SCRIPT}`;
}

export interface MenuFixture {
  readonly id: string;
  readonly summary: string;
  readonly facts: MenuStateFacts;
  /** Relation name → selector inside the fixture. */
  readonly relations: Readonly<Record<string, string>>;
  readonly html: string;
}

const ACTIONS: readonly Item[] = [
  {id: 'rename', label: 'Rename'},
  {id: 'duplicate', label: 'Duplicate'},
  {id: 'archive', label: 'Archive', disabled: true},
  {id: 'delete', label: 'Delete'},
];

const ACTION_RELATIONS = {
  opener: OPENER_SELECTOR,
  'first-item': '#rename',
  'second-item': '#duplicate',
  'last-item': '#delete',
  'disabled-item': '#archive',
  'typeahead-target': '#duplicate',
} as const;

const actionFacts = (
  overrides: Partial<MenuStateFacts> = {},
): MenuStateFacts => ({
  enterTarget: 'first-item',
  wraps: true,
  homeEnd: true,
  disabledItem: true,
  checked: {},
  typeaheadCharacter: 'd',
  ...overrides,
});

function actions(
  id: string,
  summary: string,
  {
    items = ACTIONS,
    behavior,
    facts = actionFacts(),
    role,
    label,
  }: {
    items?: readonly Item[];
    behavior?: Behavior;
    facts?: MenuStateFacts;
    role?: string;
    label?: string | null;
  } = {},
): MenuFixture {
  return {
    id,
    summary,
    facts,
    relations: ACTION_RELATIONS,
    html: menuHtml({items, behavior, role, label}),
  };
}

function withItem(id: string, change: Partial<Item>): readonly Item[] {
  return ACTIONS.map(item => (item.id === id ? {...item, ...change} : item));
}

const SELECTABLE = menuHtml({
  label: 'View',
  items: [
    {id: 'edit', label: 'Edit'},
    {
      id: 'archived',
      label: 'Show archived',
      role: 'menuitemcheckbox',
      checked: true,
    },
    {
      group: 'Sort by',
      items: [
        {id: 'newest', label: 'Newest', role: 'menuitemradio', checked: true},
        {id: 'oldest', label: 'Oldest', role: 'menuitemradio', checked: false},
      ],
    },
  ],
});

const SELECTABLE_RELATIONS = {
  opener: OPENER_SELECTOR,
  'first-item': '#edit',
  'second-item': '#archived',
  'last-item': '#oldest',
  'checkbox-item': '#archived',
  'radio-item': '#newest',
  'unchecked-radio-item': '#oldest',
  'typeahead-target': '#oldest',
} as const;

const selectableFacts: MenuStateFacts = {
  enterTarget: 'first-item',
  wraps: true,
  homeEnd: true,
  disabledItem: false,
  checked: {
    'checkbox-item': true,
    'radio-item': true,
    'unchecked-radio-item': false,
  },
  typeaheadCharacter: 'o',
};

export const MENU_FIXTURES: readonly MenuFixture[] = [
  actions(
    'conforming-actions',
    'a named menu of four actions, one disabled, with wrapping arrows, Home/End and typeahead',
  ),
  {
    id: 'conforming-selectable',
    summary:
      'a menu holding an action, a checked checkbox item and a radio group',
    facts: selectableFacts,
    relations: SELECTABLE_RELATIONS,
    html: SELECTABLE,
  },
  actions(
    'conforming-no-wrap-with-home-end',
    'a menu whose arrows stop at either end and which ships Home and End, as the APG then requires',
    {
      behavior: {wrap: false},
      facts: actionFacts({wraps: false}),
    },
  ),
  actions(
    'conforming-no-typeahead',
    'a menu that ships no typeahead and does not claim it',
    {
      behavior: {typeahead: false},
      facts: actionFacts({typeaheadCharacter: null}),
    },
  ),
  actions('violating-menu-unnamed', 'a menu with no accessible name', {
    label: null,
  }),
  actions(
    'violating-menu-as-list',
    'the surface exposed as a list instead of a menu',
    {role: 'list'},
  ),
  actions(
    'violating-item-without-role',
    'the last item rendered as a plain focusable div',
    {items: withItem('delete', {role: null})},
  ),
  actions('violating-item-unnamed', 'the second item has no text', {
    items: withItem('duplicate', {label: ''}),
    facts: actionFacts({typeaheadCharacter: null}),
  }),
  {
    id: 'violating-checkbox-without-checked',
    summary: 'a checked checkbox item that carries no aria-checked',
    facts: selectableFacts,
    relations: SELECTABLE_RELATIONS,
    html: SELECTABLE.replace(
      'role="menuitemcheckbox" aria-checked="true"',
      'role="menuitemcheckbox"',
    ),
  },
  {
    id: 'violating-radio-reports-unchecked',
    summary: 'the chosen radio item reports unchecked',
    facts: selectableFacts,
    relations: SELECTABLE_RELATIONS,
    html: SELECTABLE.replace(
      'role="menuitemradio" aria-checked="true"',
      'role="menuitemradio" aria-checked="false"',
    ),
  },
  actions(
    'violating-disabled-not-exposed',
    'a disabled item the keyboard skips but that does not say it is unavailable',
    {items: withItem('archive', {disabled: false, hiddenDisabled: true})},
  ),
  actions(
    'violating-arrow-down-skips',
    'ArrowDown jumps two items instead of one',
    {behavior: {downStep: 2}},
  ),
  actions('violating-arrow-up-ignored', 'ArrowUp does nothing', {
    behavior: {up: false},
  }),
  actions(
    'violating-claims-wrap',
    'a menu that claims wrapping but stops at either end',
    {behavior: {wrap: false}},
  ),
  actions(
    'violating-home-end-ignored',
    'a menu that claims Home and End but ignores them',
    {behavior: {homeEnd: false}},
  ),
  actions(
    'violating-no-wrap-no-home-end',
    'a menu that neither wraps nor ships Home and End',
    {
      behavior: {wrap: false, homeEnd: false},
      facts: actionFacts({wraps: false, homeEnd: false}),
    },
  ),
  actions(
    'violating-typeahead-ignored',
    'a menu that claims typeahead but ignores typed characters',
    {behavior: {typeahead: false}},
  ),
  actions(
    'violating-enter-keeps-menu-open',
    'Enter on an item leaves the menu displayed',
    {behavior: {enter: 'stay'}},
  ),
  actions(
    'violating-enter-closes-without-activating',
    "Enter closes the menu and returns focus but never runs the item's action",
    {behavior: {activate: false}},
  ),
  actions(
    'violating-enter-drops-focus',
    'Enter closes the menu and leaves focus on the page body',
    {behavior: {enter: 'drop'}},
  ),
  actions('violating-escape-ignored', 'Escape does nothing', {
    behavior: {escape: 'ignore'},
  }),
  actions(
    'violating-escape-drops-focus',
    'Escape closes the menu and leaves focus on the page body',
    {behavior: {escape: 'drop'}},
  ),
  actions(
    'violating-tab-keeps-menu-open',
    'Tab moves focus on but leaves the menu displayed',
    {behavior: {tab: 'keep'}},
  ),
];

export function fixture(id: string): MenuFixture {
  const found = MENU_FIXTURES.find(candidate => candidate.id === id);
  if (found == null) {
    throw new Error(`unknown menu fixture "${id}"`);
  }
  return found;
}

export const CONFORMING_FIXTURES: readonly string[] = MENU_FIXTURES.filter(
  candidate => candidate.id.startsWith('conforming-'),
).map(candidate => candidate.id);

export const MENU_MUTATIONS: Readonly<Record<string, readonly string[]>> = {
  'menu.container.role-and-name': [
    'violating-menu-unnamed',
    'violating-menu-as-list',
  ],
  'menu.items.roles-and-names': [
    'violating-item-without-role',
    'violating-item-unnamed',
  ],
  'menu.items.checked-state': [
    'violating-checkbox-without-checked',
    'violating-radio-reports-unchecked',
  ],
  'menu.items.disabled-state': ['violating-disabled-not-exposed'],
  'menu.keys.arrow-down-moves-to-next-item': ['violating-arrow-down-skips'],
  'menu.keys.arrow-up-moves-to-previous-item': ['violating-arrow-up-ignored'],
  'menu.keys.arrows-wrap': ['violating-claims-wrap'],
  'menu.keys.home-and-end': [
    'violating-home-end-ignored',
    'violating-no-wrap-no-home-end',
  ],
  'menu.keys.typeahead': ['violating-typeahead-ignored'],
  'menu.keys.enter-activates-and-closes': [
    'violating-enter-keeps-menu-open',
    'violating-enter-closes-without-activating',
    'violating-enter-drops-focus',
  ],
  'menu.keys.escape-closes-and-returns-focus': [
    'violating-escape-ignored',
    'violating-escape-drops-focus',
  ],
  'menu.keys.tab-leaves-and-closes': ['violating-tab-keeps-menu-open'],
};