yonlu/yellowjacket
1
1
Fork 0
Code Issues 55 Pull Requests 6 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/components/artists-view/artists-view.ts
+33 -1
View File
@@ -24,6 +24,7 @@ import { queueStore } from '@store/queue-store';
import {
ContextMenuController,
contextMenuStyles,
isContextMenuKey,
} from '@utils/context-menu-controller.js';
import type { ContextMenuHost } from '@utils/context-menu-controller.js';
import { FavoritesController } from '@store/controllers/favorites-controller';
@@ -948,6 +949,23 @@ export class ArtistsView
);
};
/** Shift+F10 / ContextMenu on a focused card, anchored to the card
* so the menu appears where the artist is and focus goes back
* there when it closes. */
private openArtistMenuFromKey(
e: KeyboardEvent,
artist: library.Artist,
): void {
const card = e.currentTarget as HTMLElement | null;
if (!card) return;
e.preventDefault();
e.stopPropagation();
this.contextMenuArtistId = artist.ID;
this.ctxMenu.openFrom(card);
}
private async onContextMenuAction(
action: string,
) {
@@ -1193,7 +1211,7 @@ export class ArtistsView
data-index=${index}
tabindex=${this.roving.tabIndexFor(index)}
@focus=${() => this.roving.noteFocus(index)}
role="button"
role="option"
aria-label="${artist.Name}"
aria-selected="${isSelected}"
style="
@@ -1212,6 +1230,15 @@ export class ArtistsView
artist,
)}
@keydown=${(e: KeyboardEvent) => {
if (isContextMenuKey(e)) {
this.openArtistMenuFromKey(
e,
artist,
);
return;
}
if (
e.key === 'Enter' ||
e.key === ' '
@@ -1266,6 +1293,8 @@ export class ArtistsView
? html`
<div
class="context-menu-panel"
role="menu"
aria-label="Artist actions"
>
<wa-dropdown-item
@click=${() =>
@@ -1442,6 +1471,9 @@ export class ArtistsView
@keydown=${this.roving.handleKeydown}
>
<lit-virtualizer
role="listbox"
aria-label="Artists"
aria-multiselectable="true"
.items=${entries}
.renderItem=${(entry: ArtistEntry) => this.renderArtistCard(entry)}
.keyFunction=${(entry: ArtistEntry) => entry.artist.ID}
frontend/src/components/cover-grid/cover-grid.ts
+30 -3
View File
@@ -46,7 +46,10 @@ import {
emitDragActive,
} from '@utils/drag-controller';
import type { DragPayload } from '@utils/drag-controller';
import { ContextMenuController } from '@utils/context-menu-controller.js';
import {
ContextMenuController,
isContextMenuKey,
} from '@utils/context-menu-controller.js';
import type { ContextMenuHost } from '@utils/context-menu-controller.js';
import { FavoritesController } from '@store/controllers/favorites-controller';
import { artistLink, exploreLinkStyles } from '../../utils/explore-link';
@@ -1050,6 +1053,26 @@ export class CoverGrid
private onGridAlbumKeydown = (
e: KeyboardEvent,
) => {
if (isContextMenuKey(e)) {
const target = this.resolveAlbumFromEvent(e);
const card =
e.composedPath().find(
(el): el is HTMLElement =>
el instanceof HTMLElement &&
el.classList.contains('album-card'),
);
if (!target || !card) return;
e.preventDefault();
e.stopPropagation();
this.contextMenuAlbumId = target.album.ID;
this.contextMenuTarget = { kind: 'album' };
this.ctxMenu.openFrom(card);
return;
}
if (e.key !== 'Enter' && e.key !== ' ') return;
const hit = this.resolveAlbumFromEvent(e);
@@ -1679,7 +1702,8 @@ export class CoverGrid
class=${classes}
tabindex=${this.roving.tabIndexFor(index)}
@focus=${() => this.roving.noteFocus(index)}
role="button"
role="option"
aria-selected=${this.selectedAlbums.has(album.ID)}
data-index=${index}
aria-label="${album.Name} by ${album.ArtistName}"
draggable="true"
@@ -1780,6 +1804,9 @@ export class CoverGrid
return html`
<lit-virtualizer
id="grid-single"
role="listbox"
aria-label="Albums"
aria-multiselectable="true"
.items=${this.buildGridEntries()}
.renderItem=${this.renderGridEntry}
.keyFunction=${(entry: GridEntry) => entry.album.ID}
@@ -1877,7 +1904,7 @@ export class CoverGrid
>
${ctxMenu.contextMenuOpen
? html`
<div class="context-menu-panel">
<div class="context-menu-panel" role="menu" aria-label="Album actions">
<wa-dropdown-item
@click=${() =>
this.onContextMenuAction(
frontend/src/components/explore-view/explore-view.ts
+25
View File
@@ -2,6 +2,7 @@ import { LitElement, html, css, nothing } from 'lit';
import { customElement, state, query as litQuery } from 'lit/decorators.js';
import '@components/page-header/page-header';
import { designTokens } from '../../styles/tokens.css';
import { srOnly } from '../../styles/sr-only.css';
import { SearchLocal, SearchLyrics, GetThumbnail, GetThumbnails, GetArtistImageURL, RecordSearchClick } from '@go/explore/Service';
import { libraryStore } from '../../store/library-store';
import { exploreCache, ARTIST_IMAGE_CACHE_LIMIT } from '../../store/explore-cache';
@@ -156,6 +157,7 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
static override styles = [
designTokens,
srOnly,
exploreLinkStyles,
css`
:host {
@@ -1319,6 +1321,9 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
override render() {
return html`
<page-header heading="Explore"></page-header>
<div class="sr-only" role="status" aria-live="polite">
${this.liveStatus()}
</div>
${this.renderSearchInput()}
${this.loading
? html`<div class="loading-indicator">Searching\u2026</div>`
@@ -1333,6 +1338,26 @@ export class ExploreView extends ViewLifecycleMixin(LitElement) {
`;
}
/** "Searching…" and the error block were both silent (a11y.12). */
private liveStatus(): string {
if (this.error) return this.error;
if (this.loading) return 'Searching…';
const results = this.results;
if (!results) return '';
const count =
(results.artists?.length ?? 0)
+ (results.releaseGroups?.length ?? 0)
+ (results.recordings?.length ?? 0);
return count === 0
? 'No results.'
: `${count} result${count === 1 ? '' : 's'}.`;
}
private renderSearchInput() {
const placeholder =
this.searchMode === 'lyrics'
frontend/src/components/genres-view/genres-view.ts
+31 -1
View File
@@ -21,6 +21,7 @@ import { queueStore } from '@store/queue-store';
import {
ContextMenuController,
contextMenuStyles,
isContextMenuKey,
} from '@utils/context-menu-controller.js';
import type { ContextMenuHost } from '@utils/context-menu-controller.js';
import { FavoritesController } from '@store/controllers/favorites-controller';
@@ -959,6 +960,21 @@ export class GenresView
);
};
/** Shift+F10 / ContextMenu on a focused card. */
private openGenreMenuFromKey(
e: KeyboardEvent,
genre: Genre,
): void {
const card = e.currentTarget as HTMLElement | null;
if (!card) return;
e.preventDefault();
e.stopPropagation();
this.contextMenuGenreName = genre.name;
this.ctxMenu.openFrom(card);
}
private async onContextMenuAction(
action: string,
) {
@@ -1036,7 +1052,7 @@ export class GenresView
data-index=${index}
tabindex=${this.roving.tabIndexFor(index)}
@focus=${() => this.roving.noteFocus(index)}
role="button"
role="option"
aria-label="${genre.name}"
aria-selected="${isSelected}"
style="
@@ -1055,6 +1071,15 @@ export class GenresView
genre,
)}
@keydown=${(e: KeyboardEvent) => {
if (isContextMenuKey(e)) {
this.openGenreMenuFromKey(
e,
genre,
);
return;
}
if (
e.key === 'Enter' ||
e.key === ' '
@@ -1109,6 +1134,8 @@ export class GenresView
? html`
<div
class="context-menu-panel"
role="menu"
aria-label="Genre actions"
>
<wa-dropdown-item
@click=${() =>
@@ -1295,6 +1322,9 @@ export class GenresView
@keydown=${this.roving.handleKeydown}
>
<lit-virtualizer
role="listbox"
aria-label="Genres"
aria-multiselectable="true"
.items=${entries}
.renderItem=${(entry: GenreEntry) => this.renderGenreCard(entry)}
.keyFunction=${(entry: GenreEntry) => entry.genre.name}
frontend/src/components/jobs/job-indicator.ts
+38 -18
View File
@@ -3,6 +3,7 @@ import { customElement, state } from 'lit/decorators.js';
import '@awesome.me/webawesome/dist/components/icon/icon.js';
import '@awesome.me/webawesome/dist/components/popup/popup.js';
import { designTokens } from '../../styles/tokens.css';
import { srOnly } from '../../styles/sr-only.css';
import { jobStore } from '@store/job-store';
import type { Job } from '@store/job-store';
import { isIndeterminate, progressFraction } from '@store/job-store';
@@ -45,6 +46,7 @@ export class JobIndicator extends LitElement {
static override styles = [
designTokens,
srOnly,
jobStateStyles,
css`
:host {
@@ -337,36 +339,48 @@ export class JobIndicator extends LitElement {
`;
}
private renderTrigger() {
/**
* What the trigger says. Extracted so the live region can announce
* the same sentence — it swung between "Scanning Music", "3
* background jobs" and "Finished" in silence (a11y.12).
*/
private triggerLabel(): string {
const job = this.primaryJob;
const activeCount = jobStore.activeJobs.length;
if (activeCount > 1) return `${activeCount} background jobs`;
if (job && job.state === 'running') return job.title;
// "Scanning Music" would be a lie for a job that is paused or
// queued, so lead with the state instead.
if (job) return `${stateLabel(job)} · ${job.title}`;
return 'Finished';
}
private renderTrigger() {
const job = this.primaryJob;
const hasFailure = jobStore.failedJobs.length > 0;
let label: string;
if (activeCount > 1) {
label = `${activeCount} background jobs`;
} else if (job && job.state === 'running') {
label = job.title;
} else if (job) {
// "Scanning Music" would be a lie for a job that is paused
// or queued, so lead with the state instead.
label = `${stateLabel(job)} · ${job.title}`;
} else {
label = 'Finished';
}
const label = this.triggerLabel();
return html`
<button
class="trigger"
aria-haspopup="dialog"
aria-haspopup="true"
aria-expanded=${this.popoverOpen}
title="Background jobs"
@click=${this.onTriggerClick}
>
${this.renderRing(job)}
<span class="label">${label}</span>
${hasFailure ? html`<span class="alert-dot"></span>` : nothing}
${hasFailure
? html`<span
class="alert-dot"
role="img"
aria-label="A background job failed"
></span>`
: nothing}
</button>
`;
}
@@ -375,7 +389,10 @@ export class JobIndicator extends LitElement {
const finished = jobStore.finishedJobs;
return html`
<div class="panel" role="dialog" aria-label="Background jobs">
<!-- Not role="dialog": nothing moves focus into this, traps
Tab or handles Escape, so announcing a dialog that never
receives focus was a promise it does not keep (a11y.17). -->
<div class="panel" role="group" aria-label="Background jobs">
<div class="panel-header">
<span>Background jobs</span>
${finished.length > 0
@@ -415,6 +432,9 @@ export class JobIndicator extends LitElement {
override render() {
return html`
<div class="sr-only" role="status" aria-live="polite">
${this.triggerLabel()}
</div>
<wa-popup
placement="bottom-end"
distance="8"
frontend/src/components/now-playing/now-playing.ts
+10 -1
View File
@@ -11,6 +11,7 @@ import {
import { PlayerController } from '@store/controllers/player-controller';
import { FavoritesController } from '@store/controllers/favorites-controller';
import { designTokens } from '../../styles/tokens.css';
import { srOnly } from '../../styles/sr-only.css';
// H-17: at 200 px the artist truncated to "The Orchestra Of" while
// ~400 px of empty space sat between it and the transport controls.
@@ -74,7 +75,7 @@ export class NowPlaying extends LitElement {
private lastGeometryKey = '';
private geometryDirty = true;
static override styles = [designTokens, exploreLinkStyles, css`
static override styles = [designTokens, srOnly, exploreLinkStyles, css`
:host {
display: block;
position: relative;
@@ -287,9 +288,16 @@ export class NowPlaying extends LitElement {
override render() {
const track = this.player.currentTrack;
// Auto-advance changes the track with no announcement of any
// kind (a11y.12). The region is in both branches because it has
// to already exist when the *first* track arrives.
const announcement = track
? `Now playing: ${track.title}${track.artist ? ` by ${track.artist}` : ''}`
: '';
if (!track) {
return html`
<div class="sr-only" role="status" aria-live="polite">${announcement}</div>
<div class="now-playing">
<div class="cover-art">
<div class="cover-placeholder"><wa-icon name="music"></wa-icon></div>
@@ -311,6 +319,7 @@ export class NowPlaying extends LitElement {
const artistScrolling = this.shouldScroll('artist');
return html`
<div class="sr-only" role="status" aria-live="polite">${announcement}</div>
<div class="now-playing">
<div class="cover-art-wrapper">
<div
frontend/src/components/playlist-details/playlist-details.ts
+58 -2
View File
@@ -31,8 +31,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 { notificationStore } from '@store/notification-store';
import { describeError } from '@utils/describe-error';
@@ -342,6 +344,51 @@ export class PlaylistDetails
);
}
/** The row holding the roving tab stop. Rows had no keyboard path at
* all before this: not focusable, so Shift+F10 had nowhere to fire
* from and the menu was right-click only (a11y.3). */
@state() private focusedIndex = 0;
private onRowKeydown(e: KeyboardEvent, trackIndex: number): void {
const count = this.tracks.length;
if (count === 0) return;
const row = e.currentTarget as HTMLElement | null;
if (isContextMenuKey(e) && row) {
e.preventDefault();
e.stopPropagation();
this.selection.handleContextMenu(String(trackIndex));
this.ctxMenu.openFrom(row);
return;
}
if (e.key === 'Enter') {
e.preventDefault();
e.stopPropagation();
this.handleTrackDblClick(trackIndex);
return;
}
const next = nextRovingIndex(e.key, this.focusedIndex, count);
if (next === null) return;
e.preventDefault();
e.stopPropagation();
this.focusedIndex = next;
void focusRovingRow(
this,
this.virtualizer,
next,
(i) => `.track-item[data-index="${i}"]`,
);
}
private handleTrackDblClick(trackIndex: number) {
this.selection.clear();
@@ -1364,6 +1411,9 @@ export class PlaylistDetails
</div>
<lit-virtualizer
class="track-scroller"
role="listbox"
aria-label="Playlist tracks"
aria-multiselectable="true"
.items=${visibleTracks}
.renderItem=${this.renderRow}
.keyFunction=${this.rowKey}
@@ -1397,6 +1447,12 @@ export class PlaylistDetails
return html`
<div
class=${classes}
role="option"
aria-selected=${selected}
data-index=${trackIndex}
tabindex=${trackIndex === this.focusedIndex ? 0 : -1}
@keydown=${(e: KeyboardEvent) =>
this.onRowKeydown(e, trackIndex)}
draggable=${isPhantom
? 'false'
: 'true'}
@@ -1526,7 +1582,7 @@ export class PlaylistDetails
${this.ctxMenu.contextMenuOpen
? this.isPhantomSelection()
? html`
<div class="context-menu-panel">
<div class="context-menu-panel" role="menu" aria-label="Track actions">
<wa-dropdown-item
@click=${() =>
this.onContextMenuAction(
@@ -1556,7 +1612,7 @@ export class PlaylistDetails
</div>
`
: html`
<div class="context-menu-panel">
<div class="context-menu-panel" role="menu" aria-label="Track actions">
<wa-dropdown-item
@click=${() =>
this.onContextMenuAction(
frontend/src/components/playlist-view/playlist-view.ts
+51 -1
View File
@@ -25,7 +25,11 @@ import {
getActiveDragSource,
getActiveDragPlaylistId,
} from '@utils/drag-controller';
import { contextMenuStyles } from '@utils/context-menu-controller.js';
import {
MenuKeyboard,
contextMenuStyles,
isContextMenuKey,
} from '@utils/context-menu-controller.js';
import { describeError } from '@utils/describe-error';
import { notificationStore } from '@store/notification-store';
import { confirmAction } from '@components/confirm-dialog/confirm-dialog';
@@ -134,6 +138,13 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
@query('duplicate-tracks-dialog')
private duplicateDialog!: DuplicateTracksDialog;
/** This view renders its own context menu rather than using
* `ContextMenuController`, so it borrows just the keyboard model —
* which is the part that must not exist twice. */
private menuKeyboard = new MenuKeyboard(() =>
this.closePlaylistContextMenu(),
);
private closePlaylistCtxMenuHandler =
() => this.closePlaylistContextMenu();
@@ -1031,6 +1042,7 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
private handlePlaylistContextMenu = (
e: MouseEvent,
index: number,
opener?: HTMLElement,
) => {
e.preventDefault();
e.stopPropagation();
@@ -1061,13 +1073,39 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
},
};
popup.active = true;
this.menuKeyboard.open(
popup.querySelector('.context-menu-panel'),
opener,
);
}
});
};
/** Shift+F10 / ContextMenu on a focused playlist header. */
private handlePlaylistMenuKey(
e: KeyboardEvent,
index: number,
): void {
const header = e.currentTarget as HTMLElement | null;
if (!header) return;
const rect = header.getBoundingClientRect();
this.handlePlaylistContextMenu(
new MouseEvent('contextmenu', {
clientX: rect.left + 16,
clientY: rect.top + rect.height / 2,
}),
index,
header,
);
}
private closePlaylistContextMenu() {
if (!this.playlistContextMenuOpen) return;
this.menuKeyboard.close();
this.playlistContextMenuOpen = false;
this.playlistContextMenuIndex = -1;
@@ -1499,6 +1537,8 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
? html`
<div
class="context-menu-panel"
role="menu"
aria-label="Playlist actions"
>
${this.selectedPlaylists.size <= 1
? html`
@@ -1695,8 +1735,18 @@ export class PlaylistView extends ViewLifecycleMixin(LitElement) {
>
<div
class="playlist-header ${this.selectedPlaylists.has(index) ? 'selected' : ''}"
role="button"
tabindex="0"
aria-label=${`Playlist ${entry.summary.Name}`}
@click=${(e: MouseEvent) =>
this.handlePlaylistHeaderClick(e, index)}
@keydown=${(e: KeyboardEvent) => {
if (isContextMenuKey(e)) {
e.preventDefault();
e.stopPropagation();
this.handlePlaylistMenuKey(e, index);
}
}}
@contextmenu=${(e: MouseEvent) =>
this.handlePlaylistContextMenu(
e,
frontend/src/components/queue-panel/queue-panel.ts
+64 -1
View File
@@ -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(
frontend/src/components/smart-playlist-details/smart-playlist-details.ts
+57 -1
View File
@@ -22,8 +22,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 {
setDragPayload,
@@ -817,6 +819,51 @@ export class SmartPlaylistDetails
);
}
/** The row holding the roving tab stop. Rows had no keyboard path at
* all before this: not focusable, so Shift+F10 had nowhere to fire
* from and the menu was right-click only (a11y.3). */
@state() private focusedIndex = 0;
private onRowKeydown(e: KeyboardEvent, trackIndex: number): void {
const count = this.tracks.length;
if (count === 0) return;
const row = e.currentTarget as HTMLElement | null;
if (isContextMenuKey(e) && row) {
e.preventDefault();
e.stopPropagation();
this.selection.handleContextMenu(String(trackIndex));
this.ctxMenu.openFrom(row);
return;
}
if (e.key === 'Enter') {
e.preventDefault();
e.stopPropagation();
this.handleTrackDblClick(trackIndex);
return;
}
const next = nextRovingIndex(e.key, this.focusedIndex, count);
if (next === null) return;
e.preventDefault();
e.stopPropagation();
this.focusedIndex = next;
void focusRovingRow(
this,
this.virtualizer,
next,
(i) => `.track-item[data-index="${i}"]`,
);
}
private handleTrackDblClick(trackIndex: number) {
this.selection.clear();
@@ -1264,6 +1311,9 @@ export class SmartPlaylistDetails
<div class="header-cell col-duration">Duration</div>
</div>
<lit-virtualizer
role="listbox"
aria-label="Smart playlist tracks"
aria-multiselectable="true"
.items=${visibleTracks}
.renderItem=${this.renderRow}
.keyFunction=${this.rowKey}
@@ -1297,6 +1347,12 @@ export class SmartPlaylistDetails
return html`
<div
class=${classes}
role="option"
aria-selected=${selected}
data-index=${trackIndex}
tabindex=${trackIndex === this.focusedIndex ? 0 : -1}
@keydown=${(e: KeyboardEvent) =>
this.onRowKeydown(e, trackIndex)}
draggable=${isPhantom ? 'false' : 'true'}
@click=${(e: MouseEvent) =>
this.handleTrackClick(
@@ -1372,7 +1428,7 @@ export class SmartPlaylistDetails
>
${this.ctxMenu.contextMenuOpen
? html`
<div class="context-menu-panel">
<div class="context-menu-panel" role="menu" aria-label="Track actions">
<wa-dropdown-item
@click=${() =>
this.onContextMenuAction(
frontend/src/components/track-list/track-list.ts
+60 -3
View File
@@ -1,6 +1,7 @@
import { library } from '@go/models';
import { LitElement, html, svg, css, nothing } from 'lit';
import { designTokens } from '../../styles/tokens.css';
import { srOnly } from '../../styles/sr-only.css';
import {
customElement,
property,
@@ -13,6 +14,7 @@ import { ViewLifecycleMixin } from '@utils/view-lifecycle';
import {
ContextMenuController,
contextMenuStyles,
isContextMenuKey,
} from '@utils/context-menu-controller.js';
import type { ContextMenuHost } from '@utils/context-menu-controller.js';
@@ -231,6 +233,24 @@ export class TrackList
let next = this.focusedIndex;
// The menu is most of what a row can do, and it was reachable
// only by right-click (a11y.3).
if (isContextMenuKey(e)) {
const track = this.cachedSortedTracks[this.focusedIndex];
const row = e.target instanceof HTMLElement
? e.target.closest<HTMLElement>('[role="row"]')
: null;
if (!track || !row) return;
e.preventDefault();
e.stopPropagation();
this.selection.handleContextMenu(track.FilePath);
this.ctxMenu.openFrom(row);
return;
}
switch (e.key) {
case 'ArrowDown':
next = Math.min(this.focusedIndex + 1, last);
@@ -877,7 +897,7 @@ export class TrackList
this.requestUpdate();
};
static override styles = [designTokens, contextMenuStyles, exploreLinkStyles, css`
static override styles = [designTokens, srOnly, contextMenuStyles, exploreLinkStyles, css`
:host {
display: flex;
flex-direction: column;
@@ -1316,6 +1336,28 @@ export class TrackList
}
}
/**
* What a screen reader is told about this list, in a sentence.
*
* Loading, failed, empty and "n results for a search" were all
* silent — the list said them in text nobody was watching (a11y.12).
*/
private liveStatus(visible: number): string {
if (this.loadError) return this.loadError;
if (this.loadingTracks) return 'Loading tracks…';
if (this.tracks.length === 0) return 'No tracks.';
const term = this.searchCtrl.term.trim();
if (term === '') return '';
return visible === 0
? `No tracks match “${term}”.`
: `${visible} track${visible === 1 ? '' : 's'} match “${term}”.`;
}
/** Loading / failed / genuinely empty, said apart. */
private renderPlaceholder() {
if (this.loadError) {
@@ -1858,6 +1900,9 @@ export class TrackList
return html`
${this.renderPageHeader()}
<div class="sr-only" role="status" aria-live="polite">
${this.liveStatus(visibleTracks.length)}
</div>
${this.tracks.length === 0
? this.renderPlaceholder()
: html`
@@ -1866,19 +1911,31 @@ export class TrackList
role="grid"
aria-label="Tracks"
aria-rowcount=${visibleTracks.length}
aria-busy=${this.loadingTracks}
@keydown=${this.onListKeydown}
>
<div class="header-row" role="row">
<div role="columnheader"></div>
<div role="columnheader" aria-label="Favourite"></div>
${cols.map(
(col) => html`
<div
role="columnheader"
tabindex="0"
aria-sort=${this.sortField === col.id
? (this.sortDirection === 'asc' ? 'ascending' : 'descending')
: 'none'}
class="header-cell ${col.align === 'right' ? 'cell-right' : ''}"
@click=${() =>
this.onHeaderCellClick(
col.id,
)}
@keydown=${(e: KeyboardEvent) => {
if (e.key !== 'Enter' && e.key !== ' ') return;
e.preventDefault();
e.stopPropagation();
this.onHeaderCellClick(col.id);
}}
>
<span>${col.label}</span>
${this.sortField === col.id
@@ -1930,7 +1987,7 @@ export class TrackList
>
${this.ctxMenu.contextMenuOpen
? html`
<div class="context-menu-panel">
<div class="context-menu-panel" role="menu" aria-label="Track actions">
<wa-dropdown-item
@click=${() => this.onContextMenuAction('play')}
@mouseenter=${() => this.ctxMenu.closePlaylistSubmenu()}
frontend/src/styles/sr-only.css.ts
+29
View File
@@ -0,0 +1,29 @@
import { css } from 'lit';
/**
* The visually-hidden class, and with it the rule for using one.
*
* A live region has to be **in the DOM before the text it announces
* is**: most screen readers announce a *change* to a region they are
* already watching, and ignore a region that appears with its content
* already in it. So these regions render unconditionally and empty, and
* only their text changes — which is why they are a class rather than a
* component that mounts on demand.
*
* `clip-path` rather than `display: none` or `visibility: hidden`, both
* of which take the element out of the accessibility tree along with the
* layout, which would defeat the point.
*/
export const srOnly = css`
.sr-only {
position: absolute;
width: 1px;
height: 1px;
margin: -1px;
padding: 0;
overflow: hidden;
clip-path: inset(50%);
white-space: nowrap;
border: 0;
}
`;
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
// =================================================================
frontend/src/utils/roving-rows.ts
+70
View File
@@ -0,0 +1,70 @@
/**
* A roving tab stop over a virtualized list of rows.
*
* Three lists needed the same thing at once — the queue panel and both
* playlist detail views — because a context menu opened with Shift+F10
* needs a focused row to open *from*, and none of the three had one:
* their rows were plain `<div>`s with no `tabindex` and no `role`.
*
* `track-list` deliberately does not use this. Its equivalent predates
* it, carries selection semantics (shift-extend, ctrl-toggle) that the
* other three do not have, and is pinned by its own tests; converting it
* would be a rewrite of the one list that already worked.
*
* Two things here are not optional:
*
* - **The virtualizer is told the index changed.** Rows come from the
* `virtualize` directive, which re-renders on the virtualizer's *own*
* properties — a host re-render does not move a `tabindex`.
* - **Focus is taken after the update.** The row for an index that was
* off-screen does not exist until the virtualizer has scrolled to it.
*/
import type { LitVirtualizer } from '@lit-labs/virtualizer';
export interface RovingRowsHost {
requestUpdate(): void;
updateComplete: Promise<boolean>;
}
/** The keys this handles, and what they mean given a row count. */
export function nextRovingIndex(
key: string,
current: number,
count: number,
): number | null {
switch (key) {
case 'ArrowDown':
return Math.min(current + 1, count - 1);
case 'ArrowUp':
return Math.max(current - 1, 0);
case 'Home':
return 0;
case 'End':
return count - 1;
default:
return null;
}
}
/**
* Move the tab stop to `index` and put focus on it.
*
* `rowSelector` receives the index and must return a selector matching
* that row inside the virtualizer's light DOM.
*/
export async function focusRovingRow(
host: RovingRowsHost,
virtualizer: LitVirtualizer | undefined,
index: number,
rowSelector: (index: number) => string,
): Promise<void> {
host.requestUpdate();
virtualizer?.requestUpdate();
virtualizer?.scrollToIndex(index, 'nearest');
await host.updateComplete;
virtualizer
?.querySelector<HTMLElement>(rowSelector(index))
?.focus();
}
frontend/test/components/aria-tail.test.ts
+193
View File
@@ -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');
});
});
frontend/test/components/menu-keyboard.test.ts
+176
View File
@@ -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();
});
});