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.
This commit is contained in:
2026-08-12 11:07:34 -04:00
parent 7912cdf23f
commit 1ed4167634
16 changed files with 1160 additions and 35 deletions
@@ -25,8 +25,10 @@ import type { SelectionHost } from '@utils/selection-controller';
import {
ContextMenuController,
contextMenuStyles,
isContextMenuKey,
} from '@utils/context-menu-controller.js';
import type { ContextMenuHost } from '@utils/context-menu-controller.js';
import { focusRovingRow, nextRovingIndex } from '@utils/roving-rows';
import { FavoritesController } from '@store/controllers/favorites-controller';
import {
hasTrackPayload,
@@ -157,6 +159,9 @@ export class QueuePanel
}
};
/** The row holding the roving tab stop. */
@state() private focusedIndex = 0;
private panelWidth = DEFAULT_WIDTH;
private scrollbarDragging = false;
@@ -569,6 +574,7 @@ export class QueuePanel
virtEl.addEventListener('contextmenu', this.onDelegatedContextMenu);
virtEl.addEventListener('dragstart', this.onDelegatedDragStart);
virtEl.addEventListener('dragend', this.onTrackDragEnd);
virtEl.addEventListener('keydown', this.onDelegatedKeydown);
this.delegationAttached = true;
}
@@ -651,6 +657,7 @@ export class QueuePanel
virtEl.removeEventListener('contextmenu', this.onDelegatedContextMenu);
virtEl.removeEventListener('dragstart', this.onDelegatedDragStart);
virtEl.removeEventListener('dragend', this.onTrackDragEnd);
virtEl.removeEventListener('keydown', this.onDelegatedKeydown);
}
this.delegationAttached = false;
}
@@ -871,6 +878,55 @@ export class QueuePanel
this.ctxMenu.openAt(e.clientX, e.clientY);
}
/**
* The queue's rows had no keyboard path at all: not focusable, so
* neither Enter nor Shift+F10 had anywhere to fire from, and the
* menu — which is the only way to reach most of what a queue row can
* do — was right-click only (a11y.3).
*/
private onDelegatedKeydown = (e: KeyboardEvent): void => {
const count = this.queue.tracks.length;
if (count === 0) return;
const row = (e.target as HTMLElement | null)?.closest<HTMLElement>(
'.track-item',
);
if (isContextMenuKey(e) && row) {
e.preventDefault();
e.stopPropagation();
this.selection.handleContextMenu(String(this.focusedIndex));
this.ctxMenu.openFrom(row);
return;
}
if (e.key === 'Enter') {
e.preventDefault();
e.stopPropagation();
this.selection.clear();
this.queue.playAtIndex(this.focusedIndex);
return;
}
const next = nextRovingIndex(e.key, this.focusedIndex, count);
if (next === null) return;
e.preventDefault();
e.stopPropagation();
this.focusedIndex = next;
this.selection.handleContextMenu(String(next));
void focusRovingRow(
this,
this.virtualizer,
next,
(i) => `.track-item[data-index="${i}"]`,
);
};
private onContextMenuAction(action: string) {
const indices =
this.selection.getSelectedIndices();
@@ -1473,6 +1529,10 @@ export class QueuePanel
data-testid="queue-row"
data-file-path=${track.filePath}
draggable="true"
role="option"
aria-selected=${selected}
aria-current=${active ? 'true' : 'false'}
tabindex=${index === this.focusedIndex ? 0 : -1}
>
<span class="track-position">
${index + 1}
@@ -1584,6 +1644,9 @@ export class QueuePanel
: html`
<lit-virtualizer
scroller
role="listbox"
aria-label="Queue"
aria-multiselectable="true"
.items=${tracks}
.renderItem=${this.renderTrackItem}
.keyFunction=${(track: QueueTrack) => track.id}
@@ -1602,7 +1665,7 @@ export class QueuePanel
>
${this.ctxMenu.contextMenuOpen
? html`
<div class="context-menu-panel">
<div class="context-menu-panel" role="menu" aria-label="Queue track actions">
<wa-dropdown-item
@click=${() =>
this.onContextMenuAction(