yonlu/yellowjacket
1
1
Fork 0
Code Issues 52 Pull Requests 4 Actions Packages Projects Releases 12 Wiki Activity

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

Browse Source 
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:
logan
2026-08-12 11:07:34 -04:00
parent 7912cdf23f
commit 1ed4167634
16 changed files with 1160 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files
frontend/src/utils/context-menu-controller.ts
+235 -3
View File
@@ -33,6 +33,195 @@ export interface ContextMenuHost
/** Submenu close delay in milliseconds. */
const SUBMENU_CLOSE_DELAY = 150;
/** A menu item, focusable and clickable. Web Awesome sets `role` itself. */
type MenuItem = HTMLElement & { active?: boolean; disabled?: boolean };
/**
* Whether a keypress is the conventional "open the context menu" one.
* Shift+F10 is the long-standing binding; `ContextMenu` is the dedicated
* key on keyboards that have one.
*/
export function isContextMenuKey(e: KeyboardEvent): boolean {
return e.key === 'ContextMenu' || (e.shiftKey && e.key === 'F10');
}
/**
* The keyboard model for an open menu panel: focus the first item,
* Arrow/Home/End to move, Enter/Space to activate, Escape/Tab to close,
* and focus back where it came from.
*
* It is a standalone class rather than part of `ContextMenuController`
* because `playlist-view` renders a menu without using that controller,
* and the one thing worse than a menu with no keyboard model is two
* menus with two different ones.
*/
export class MenuKeyboard {
private panel: HTMLElement | null = null;
private restoreFocusTo: HTMLElement | null = null;
constructor(private readonly onClose: () => void) {}
/** Bind to a freshly-opened panel and focus its first item. */
open(panel: HTMLElement | null, opener?: HTMLElement | null): void {
if (!panel || this.panel === panel) return;
this.detach();
this.panel = panel;
this.restoreFocusTo = opener ?? deepActiveElement();
panel.addEventListener('keydown', this.onKeydown);
void this.focusFirstItem(panel);
}
/**
* Focus the first item, once the items are items.
*
* The host's `updateComplete` resolves before the `wa-dropdown-item`s
* inside the panel have run their own first update — and `role` is
* one of the things they set there. Querying by role at that moment
* finds nothing, which reads exactly like a menu that opened and
* refused to take focus.
*/
private async focusFirstItem(panel: HTMLElement): Promise<void> {
const candidates = [
...panel.querySelectorAll<MenuItem & { updateComplete?: Promise<boolean> }>(
'wa-dropdown-item, [role^="menuitem"]',
),
];
await Promise.all(candidates.map((el) => el.updateComplete ?? null));
// …and once the popup has positioned itself. `wa-popup` places the
// panel on an animation frame, and `focus()` on a not-yet-shown
// element is a silent no-op — which looks identical to a menu
// that opened and refused to take focus.
for (let attempt = 0; attempt < 3; attempt++) {
// Bail if the menu closed while we waited.
if (this.panel !== panel) return;
const first = this.items()[0];
this.focusItem(first);
if (first && panel.contains(deepActiveElement())) return;
await new Promise((resolve) => requestAnimationFrame(resolve));
}
}
/**
* Unbind, and give focus back if the menu had it. A click elsewhere
* closes the menu too, and yanking focus back to the row the user
* right-clicked a moment ago is worse than leaving it alone.
*/
close(): void {
const restoreTo = this.restoreFocusTo;
const hadFocus = this.panel?.contains(deepActiveElement()) ?? false;
this.detach();
if (hadFocus && restoreTo?.isConnected) restoreTo.focus();
}
private detach(): void {
this.panel?.removeEventListener('keydown', this.onKeydown);
this.panel = null;
this.restoreFocusTo = null;
}
/** The enabled items, in DOM order. */
private items(): MenuItem[] {
if (!this.panel) return [];
return [
...this.panel.querySelectorAll<MenuItem>(
'wa-dropdown-item, [role^="menuitem"]',
),
].filter(
(item) =>
!item.disabled && item.getAttribute('aria-disabled') !== 'true',
);
}
private focusItem(item: MenuItem | undefined): void {
if (!item) return;
// `active` is what Web Awesome keys an item's tabindex and its
// highlight off, so moving focus without it leaves the highlight
// on whichever item the mouse last touched.
for (const other of this.items()) other.active = other === item;
item.tabIndex = 0;
item.focus();
}
private onKeydown = (e: KeyboardEvent): void => {
const items = this.items();
if (items.length === 0) return;
const current = items.findIndex(
(item) => item === e.target || item.contains(e.target as Node),
);
const move = (next: number): void => {
e.preventDefault();
e.stopPropagation();
this.focusItem(items[(next + items.length) % items.length]);
};
switch (e.key) {
case 'ArrowDown':
move(current + 1);
break;
case 'ArrowUp':
move(current - 1);
break;
case 'Home':
move(0);
break;
case 'End':
move(items.length - 1);
break;
case 'Escape':
case 'Tab':
// Tab closes rather than moving through the menu: the panel
// is a bare popup in the host's shadow root, so tabbing out
// of it lands in the page behind with the menu still open.
e.preventDefault();
e.stopPropagation();
this.onClose();
break;
case 'Enter':
case ' ':
// These items are in a `wa-popup`, not a `wa-dropdown`, so
// nothing upstream turns a keypress into an activation.
e.preventDefault();
e.stopPropagation();
items[current]?.click();
break;
default:
break;
}
};
}
/** The focused element, resolved through shadow roots. */
function deepActiveElement(): HTMLElement | null {
let el = document.activeElement as HTMLElement | null;
while (el?.shadowRoot?.activeElement) {
el = el.shadowRoot.activeElement as HTMLElement;
}
return el;
}
/**
* Reusable context menu controller that manages the open/close
* state of a wa-popup context menu with an optional playlist
@@ -116,6 +305,7 @@ export class ContextMenuController
hostDisconnected(): void {
this.detach();
this.keyboard.close();
this.clearSubmenuCloseTimer();
}
@@ -162,8 +352,13 @@ export class ContextMenuController
/**
* Open the context menu at the given screen
* coordinates using a virtual anchor.
*
* `opener` is where focus goes back to on close. It defaults to
* whatever was focused when the menu opened, which is right for a
* right-click (usually nothing) and for a keyboard open (the row).
*/
openAt(clientX: number, clientY: number): void {
openAt(clientX: number, clientY: number, opener?: HTMLElement | null): void {
this.pendingOpener = opener ?? deepActiveElement();
this.contextMenuOpen = true;
this.host.requestUpdate();
@@ -184,9 +379,27 @@ export class ContextMenuController
},
};
popup.active = true;
this.bindKeyboard();
});
}
/**
* Open the menu from an element rather than from a pointer — the
* Shift+F10 / ContextMenu-key path. Anchors to the element's own box
* so the menu appears where the thing it acts on is, and restores
* focus there on close.
*/
openFrom(el: HTMLElement): void {
const rect = el.getBoundingClientRect();
this.openAt(rect.left + 16, rect.top + rect.height / 2, el);
}
// =================================================================
// KEYBOARD
// =================================================================
/**
* Close the context menu and playlist submenu.
* Notifies the host via `onContextMenuClose()` so
@@ -195,12 +408,12 @@ export class ContextMenuController
close(): void {
if (!this.contextMenuOpen) return;
this.keyboard.close();
this.closePlaylistSubmenu();
this.contextMenuOpen = false;
this.playlistFilePaths = [];
const popup =
this.host.getContextMenuPopup();
const popup = this.host.getContextMenuPopup();
if (popup) {
popup.active = false;
@@ -210,6 +423,25 @@ export class ContextMenuController
this.host.requestUpdate();
}
/** The menu's keyboard model, shared with the one host that renders
* a context menu without this controller. */
private keyboard = new MenuKeyboard(() => this.close());
/** The element focus returns to, captured at open and handed to the
* keyboard model once the panel exists. */
private pendingOpener: HTMLElement | null = null;
private get panel(): HTMLElement | null {
const popup = this.host.getContextMenuPopup();
return popup?.querySelector('.context-menu-panel') ?? null;
}
private bindKeyboard(): void {
this.keyboard.open(this.panel, this.pendingOpener);
this.pendingOpener = null;
}
// =================================================================
// PLAYLIST SUBMENU
// =================================================================