feat(a11y): give the context menu a keyboard, and the app a voice

The context menu was the only route to Play, Add to Queue, Play Next, Add to Playlist, Favourite and Track Details, and it opened on right-click alone: the panel had no role=menu, so its six menuitems were orphaned, nothing moved focus into it, and nothing handled arrows or Escape (a11y.3). Phase 1 deferred this deliberately so it would land with the dialogs, as one focus-management implementation. MenuKeyboard is that model. It is standalone rather than part of ContextMenuController because playlist-view renders a menu without the controller, and the only thing worse than a menu with no keyboard model is two menus with two of them. Shift+F10 and the ContextMenu key open it from a focused row, anchored to that row, and focus returns there. Three lists had no focused row to open it from, so they gained a roving tab stop (utils/roving-rows.ts, written once rather than three times). track-list keeps its own: it predates this, carries selection semantics the other three do not have, and is pinned by its own tests. Also the ARIA tail this is one story with: aria-sort on the column headers (role=columnheader arrived in Phase 1 without it), listbox and option on the four selectable grids — aria-selected on role=button is invalid and was being dropped, so the state the whole ctrl/shift interaction exists to produce was invisible — and live regions on the four async surfaces that changed in silence. Two things a reproduction taught that reading could not: the wa-dropdown-items have not set their role when the host's updateComplete resolves, so querying by role then finds nothing and the menu opens without taking focus; and focus() on a popup that has not positioned itself is a silent no-op.
2026-08-12 11:07:34 -04:00
parent 7912cdf23f
commit 1ed4167634
16 changed files with 1160 additions and 35 deletions
@@ -0,0 +1,193 @@
+/**
+ * The ARIA tail of `a11y.md`, pinned.
+ *
+ * Every assertion here is a finding that was reproduced in the running
+ * app first. Three of them are the kind that no other tier can see: a
+ * grid that sorts and never says so, a list whose loading/empty/failed
+ * states are text nobody is watching, and `aria-selected` on
+ * `role="button"`, which is not merely useless but *invalid* — the
+ * attribute is dropped, so the state the whole ctrl/shift interaction
+ * exists to produce was invisible.
+ */
+import { describe, expect, it, beforeEach } from 'vitest';
+import type { LitElement } from 'lit';
+
+import '@components/track-list/track-list';
+import '@components/artists-view/artists-view';
+import '@components/genres-view/genres-view';
+import { emit, stub, flush, resetHarness } from '@test/support/harness';
+import { Events } from '../../src/events';
+import { fixture, shadow, shadowAll } from '@test/support/render';
+import { searchStore } from '@store/search-store';
+
+/**
+ * The searchable columns' accessors read these fields and call
+ * `.toLowerCase()` on the result, so a sparse fixture throws inside the
+ * ranker rather than failing an assertion. Real tracks always carry
+ * them; a fixture has to as well.
+ */
+const TRACKS = [
+  {
+    FilePath: '/m/a.mp3',
+    TrackName: 'Departure',
+    ArtistName: 'Aurora Fields',
+    Album: 'Glass Harbour',
+    AlbumArtist: 'Aurora Fields',
+    Composer: '',
+    Genre: ['Ambient'],
+    TrackLength: 4000,
+  },
+  {
+    FilePath: '/m/b.mp3',
+    TrackName: 'Tideline',
+    ArtistName: 'Aurora Fields',
+    Album: 'Glass Harbour',
+    AlbumArtist: 'Aurora Fields',
+    Composer: '',
+    Genre: ['Ambient'],
+    TrackLength: 6000,
+  },
+];
+
+const ARTISTS = [
+  { ID: 1, Name: 'Alpha', AlbumCount: 2, TrackCount: 9 },
+  { ID: 2, Name: 'Beta', AlbumCount: 1, TrackCount: 4 },
+];
+
+const GENRES = [
+  { name: 'Ambient', count: 12 },
+  { name: 'Doom', count: 3 },
+];
+
+function sized(el: HTMLElement): void {
+  el.style.display = 'block';
+  el.style.height = '600px';
+  el.style.width = '900px';
+}
+
+async function settle(el: LitElement): Promise<void> {
+  await flush();
+  await el.updateComplete;
+  await new Promise((r) => setTimeout(r, 80));
+}
+
+describe('the track list says how it is sorted', () => {
+  beforeEach(async () => {
+    resetHarness();
+    searchStore.setTerm('');
+    stub('library.Library.GetAllTracks', TRACKS);
+    stub('library.Library.GetAllAlbums', []);
+    emit(Events.LibraryScanComplete);
+  });
+
+  it('gives every column an aria-sort, defaulting to none', async () => {
+    const el = await fixture<LitElement>('track-list');
+
+    sized(el);
+    await settle(el);
+
+    const sorts = shadowAll(el, '.header-cell[role="columnheader"]').map((h) =>
+      h.getAttribute('aria-sort'),
+    );
+
+    expect(sorts.length, 'no sortable column headers').toBeGreaterThan(0);
+    // The list opens in file order — `sortField` is null — so no column
+    // claims to be the sort until one is chosen.
+    expect(sorts.every((s) => s === 'none')).toBe(true);
+  });
+
+  it('changes aria-sort when a column is activated from the keyboard', async () => {
+    const el = await fixture<LitElement>('track-list');
+
+    sized(el);
+    await settle(el);
+
+    const title = shadowAll(el, '.header-cell[role="columnheader"]').find((h) =>
+      /track name/i.test(h.textContent ?? ''),
+    );
+
+    expect(title, 'no Track Name column header').toBeTruthy();
+
+    // Reading the DOM synchronously after this would report the state
+    // *before* Lit rendered, which is how a fix for nothing gets shipped.
+    title!.dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Enter', bubbles: true, composed: true }),
+    );
+    await settle(el);
+
+    const after = shadowAll(el, '.header-cell[role="columnheader"]').find((h) =>
+      /track name/i.test(h.textContent ?? ''),
+    );
+
+    expect(after?.getAttribute('aria-sort')).toBe('ascending');
+  });
+});
+
+describe('the track list has a voice for its own state', () => {
+  beforeEach(() => {
+    resetHarness();
+    searchStore.setTerm('');
+    stub('library.Library.GetAllAlbums', []);
+  });
+
+  it('announces the result of a search that matches nothing', async () => {
+    stub('library.Library.GetAllTracks', TRACKS);
+    emit(Events.LibraryScanComplete);
+
+    const el = await fixture<LitElement>('track-list');
+
+    sized(el);
+    await settle(el);
+
+    const live = shadow(el, '[role="status"][aria-live="polite"]');
+
+    // The region exists *before* it has anything to say — a region that
+    // appears with its text already in it is not announced by most
+    // screen readers.
+    expect(live, 'no live region on the track list').toBeTruthy();
+
+    searchStore.setCurrentView('tracks');
+    searchStore.setTerm('nothing matches this');
+    await settle(el);
+
+    expect(shadow(el, '[role="status"]')?.textContent?.trim()).toMatch(
+      /No tracks match/i,
+    );
+  });
+});
+
+describe('a selectable grid is a listbox, not a row of buttons', () => {
+  beforeEach(() => {
+    resetHarness();
+    searchStore.setTerm('');
+    stub('library.Library.GetAllArtists', ARTISTS);
+    stub('library.Library.GetAllGenresWithCounts', GENRES);
+    stub('library.Library.GetAllTracks', []);
+    stub('library.Library.GetAllAlbums', []);
+    emit(Events.LibraryScanComplete);
+  });
+
+  it.each([
+    ['artists-view', '.artist-card'],
+    ['genres-view', '.genre-card'],
+  ])('%s cards are options carrying aria-selected', async (tag, cardSelector) => {
+    const el = await fixture<LitElement>(tag);
+
+    sized(el);
+    await settle(el);
+
+    const card = shadowAll(el, cardSelector)[0];
+
+    expect(card, `no cards rendered in ${tag}`).toBeTruthy();
+
+    // role=button + aria-selected is invalid: the attribute is dropped,
+    // and the selection is invisible to anything but a sighted user.
+    expect(card!.getAttribute('role')).toBe('option');
+    expect(card!.hasAttribute('aria-selected')).toBe(true);
+
+    const list = shadow(el, '[role="listbox"]');
+
+    expect(list, `${tag} has options with no listbox`).toBeTruthy();
+    expect(list!.getAttribute('aria-multiselectable')).toBe('true');
+  });
+});
@@ -0,0 +1,176 @@
+/**
+ * The context menu has a keyboard model, and it is one model.
+ *
+ * `a11y.3`: the panel is a bare `wa-popup` holding `wa-dropdown-item`s.
+ * Web Awesome gives each item `role="menuitem"`, but nothing gave the
+ * container `role="menu"`, nothing moved focus into it, nothing handled
+ * Arrow/Escape, and nothing restored focus. Play, Add to Queue, Play
+ * Next, Add to Playlist, Favourite and Track Details — most of which
+ * have no other route — were mouse-only.
+ *
+ * `MenuKeyboard` is that model, standalone rather than part of
+ * `ContextMenuController`, because `playlist-view` renders a menu
+ * without the controller and two menus with two keyboard models is the
+ * thing this is meant to prevent.
+ *
+ * The two non-obvious parts are pinned below, both of which cost a cycle
+ * when they were wrong:
+ *
+ * - The items are not items yet when the host's `updateComplete`
+ *   resolves. `wa-dropdown-item` sets its `role` in its *own* first
+ *   update, so a `[role^="menuitem"]` query at that moment finds
+ *   nothing and the menu opens without taking focus.
+ * - Focus is only taken back on close if the menu had it. A click
+ *   elsewhere closes the menu too, and pulling focus to the row the
+ *   user right-clicked a moment ago would be worse than leaving it.
+ */
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+
+import { MenuKeyboard, isContextMenuKey } from '@utils/context-menu-controller';
+
+/** A panel of plain elements carrying the roles Web Awesome would set. */
+function panelWith(labels: string[]): HTMLElement {
+  const panel = document.createElement('div');
+
+  panel.className = 'context-menu-panel';
+  panel.setAttribute('role', 'menu');
+
+  for (const label of labels) {
+    const item = document.createElement('div');
+
+    item.setAttribute('role', 'menuitem');
+    item.textContent = label;
+    panel.append(item);
+  }
+
+  document.body.append(panel);
+
+  return panel;
+}
+
+function press(target: EventTarget, key: string): void {
+  target.dispatchEvent(
+    new KeyboardEvent('keydown', { key, bubbles: true, composed: true }),
+  );
+}
+
+/** The focused element, resolved the way the app resolves it. */
+function active(): Element | null {
+  let el = document.activeElement;
+
+  while (el?.shadowRoot?.activeElement) el = el.shadowRoot.activeElement;
+
+  return el;
+}
+
+describe('the context menu key', () => {
+  it('is Shift+F10 and the ContextMenu key, and nothing else', () => {
+    expect(isContextMenuKey(new KeyboardEvent('keydown', { key: 'ContextMenu' }))).toBe(
+      true,
+    );
+    expect(
+      isContextMenuKey(new KeyboardEvent('keydown', { key: 'F10', shiftKey: true })),
+    ).toBe(true);
+    // F10 alone is a menu-bar convention we do not own.
+    expect(isContextMenuKey(new KeyboardEvent('keydown', { key: 'F10' }))).toBe(false);
+    expect(isContextMenuKey(new KeyboardEvent('keydown', { key: 'Enter' }))).toBe(false);
+  });
+});
+
+describe('MenuKeyboard', () => {
+  let panel: HTMLElement;
+  let opener: HTMLButtonElement;
+  let closed: number;
+  let keyboard: MenuKeyboard;
+
+  beforeEach(async () => {
+    closed = 0;
+    opener = document.createElement('button');
+    opener.textContent = 'The row';
+    document.body.append(opener);
+    opener.focus();
+
+    panel = panelWith(['Play', 'Add to Queue', 'Track Details']);
+    keyboard = new MenuKeyboard(() => {
+      closed++;
+      keyboard.close();
+    });
+    keyboard.open(panel, opener);
+
+    // Focus is taken across at least one frame, because a popup that has
+    // not positioned itself yet cannot be focused.
+    await new Promise((r) => requestAnimationFrame(r));
+  });
+
+  afterEach(() => {
+    keyboard.close();
+    panel.remove();
+    opener.remove();
+  });
+
+  it('focuses the first item on open', () => {
+    expect(active()?.textContent).toBe('Play');
+  });
+
+  it('moves with the arrows and wraps', () => {
+    press(active()!, 'ArrowDown');
+    expect(active()?.textContent).toBe('Add to Queue');
+
+    press(active()!, 'ArrowUp');
+    expect(active()?.textContent).toBe('Play');
+
+    // Up from the first item wraps to the last, which is what a menu
+    // does and what a listbox does not.
+    press(active()!, 'ArrowUp');
+    expect(active()?.textContent).toBe('Track Details');
+  });
+
+  it('goes to the ends with Home and End', () => {
+    press(active()!, 'End');
+    expect(active()?.textContent).toBe('Track Details');
+
+    press(active()!, 'Home');
+    expect(active()?.textContent).toBe('Play');
+  });
+
+  it('activates the focused item with Enter', () => {
+    let clicked = '';
+
+    for (const item of panel.querySelectorAll('[role="menuitem"]')) {
+      item.addEventListener('click', () => {
+        clicked = item.textContent ?? '';
+      });
+    }
+
+    press(active()!, 'ArrowDown');
+    press(active()!, 'Enter');
+
+    expect(clicked).toBe('Add to Queue');
+  });
+
+  it('closes on Escape and gives focus back to the opener', () => {
+    press(active()!, 'Escape');
+
+    expect(closed).toBe(1);
+    expect(active()).toBe(opener);
+  });
+
+  it('closes on Tab rather than letting focus escape the panel', () => {
+    press(active()!, 'Tab');
+
+    expect(closed).toBe(1);
+    expect(active()).toBe(opener);
+  });
+
+  it('leaves focus alone when the menu did not have it', () => {
+    const elsewhere = document.createElement('button');
+
+    document.body.append(elsewhere);
+    elsewhere.focus();
+
+    keyboard.close();
+
+    expect(active()).toBe(elsewhere);
+    elsewhere.remove();
+  });
+});