Menu Button
A button that opens a menu of actions or options.
Demo
Basic Menu Button
Click the button or use keyboard to open the menu.
Last action: None
With Disabled Items
Disabled items are skipped during keyboard navigation.
Last action: None
Note: "Export" is disabled and will be skipped during keyboard navigation
Accessibility Features
WAI-ARIA Roles
| Role | Target Element | Description |
|---|---|---|
button | Trigger (<button>) | The trigger that opens the menu (implicit via <button> element) |
menu | Container (<ul>) | A widget offering a list of choices to the user |
menuitem | Each item (<li>) | An option in a menu |
WAI-ARIA Properties
aria-haspopup
Indicates the button opens a menu
- Values
menu- Required
- Yes
aria-controls
References the menu element
- Values
- ID reference
- Required
- No
aria-labelledby
References the button that opens the menu
- Values
- ID reference
- Required
- Yes (or aria-label)
aria-label
Provides an accessible name for the menu
- Values
- String
- Required
- Yes (or aria-labelledby)
aria-disabled
Indicates the menu item is disabled
- Values
- true
- Required
- No
WAI-ARIA States
aria-expanded
- Target Element
- button
- Values
- true | false
- Required
- Yes
- Change Trigger
- Open/close menu
Keyboard Support
Button (Closed Menu)
| Key | Action |
|---|---|
| Enter / Space | Open menu and focus first item |
| Down Arrow | Open menu and focus first item |
| Up Arrow | Open menu and focus last item |
Menu (Open)
| Key | Action |
|---|---|
| Down Arrow | Move focus to next item (wraps to first) |
| Up Arrow | Move focus to previous item (wraps to last) |
| Home | Move focus to first item |
| End | Move focus to last item |
| Escape | Close menu and return focus to button |
| Tab | Close menu and move focus to next focusable element |
| Enter / Space | Activate focused item and close menu |
| Type character | Type-ahead: focus item starting with typed character(s) |
- When closed, the menu uses both hidden and inert attributes to hide the menu from visual display, remove it from the accessibility tree, and prevent keyboard and mouse interaction with hidden items.
Focus Management
| Event | Behavior |
|---|---|
| Focused menu item | tabIndex="0" |
| Other menu items | tabIndex="-1" |
| Arrow key navigation | Wraps from last to first and vice versa |
| Disabled items | Skipped during navigation |
| Menu closes | Focus returns to button |
References
Source Code
---
/**
* APG Menu Button Pattern - Astro Implementation
*
* A button that opens a menu of actions or functions.
* Uses Web Components for enhanced control and proper focus management.
*
* @see https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
*/
export interface MenuItem {
id: string;
label: string;
disabled?: boolean;
}
export interface Props {
/** Array of menu items */
items: MenuItem[];
/** Button label */
label: string;
/** Whether menu is initially open */
defaultOpen?: boolean;
/** Additional CSS class */
class?: string;
}
const { items = [], label, defaultOpen = false, class: className = '' } = Astro.props;
// Generate unique ID for this instance
const instanceId = `menu-button-${Math.random().toString(36).slice(2, 11)}`;
const buttonId = `${instanceId}-button`;
const menuId = `${instanceId}-menu`;
// Calculate available items and initial focus
const availableItems = items.filter((item) => !item.disabled);
const initialFocusIndex = defaultOpen && availableItems.length > 0 ? 0 : -1;
---
<apg-menu-button
data-default-open={defaultOpen ? 'true' : undefined}
data-initial-focus-index={initialFocusIndex}
>
<div class={`apg-menu-button ${className}`.trim()}>
<button
id={buttonId}
type="button"
class="apg-menu-button-trigger"
aria-haspopup="menu"
aria-expanded={defaultOpen}
aria-controls={menuId}
data-menu-trigger
>
{label}
</button>
<ul
id={menuId}
role="menu"
aria-labelledby={buttonId}
class="apg-menu-button-menu"
hidden={!defaultOpen || undefined}
inert={!defaultOpen || undefined}
data-menu-list
>
{
items.map((item) => {
const availableIndex = availableItems.findIndex((i) => i.id === item.id);
const isFocusTarget = availableIndex === initialFocusIndex;
const tabIndex = item.disabled ? -1 : isFocusTarget ? 0 : -1;
return (
<li
role="menuitem"
data-item-id={item.id}
tabindex={tabIndex}
aria-disabled={item.disabled || undefined}
class="apg-menu-button-item"
>
{item.label}
</li>
);
})
}
</ul>
</div>
</apg-menu-button>
<script>
class ApgMenuButton extends HTMLElement {
private container: HTMLDivElement | null = null;
private button: HTMLButtonElement | null = null;
private menu: HTMLUListElement | null = null;
private rafId: number | null = null;
private isOpen = false;
private focusedIndex = -1;
private typeAheadBuffer = '';
private typeAheadTimeoutId: number | null = null;
private typeAheadTimeout = 500;
connectedCallback() {
this.rafId = requestAnimationFrame(() => this.initialize());
}
private initialize() {
this.rafId = null;
this.container = this.querySelector('.apg-menu-button');
this.button = this.querySelector('[data-menu-trigger]');
this.menu = this.querySelector('[data-menu-list]');
if (!this.button || !this.menu) {
console.warn('apg-menu-button: required elements not found');
return;
}
// Initialize state from data attributes
this.isOpen = this.dataset.defaultOpen === 'true';
this.focusedIndex = parseInt(this.dataset.initialFocusIndex || '-1', 10);
// Attach event listeners
this.button.addEventListener('click', this.handleButtonClick);
this.button.addEventListener('keydown', this.handleButtonKeyDown);
this.menu.addEventListener('keydown', this.handleMenuKeyDown);
this.menu.addEventListener('click', this.handleMenuClick);
this.menu.addEventListener('focusin', this.handleMenuFocusIn);
// Click outside listener (only when open)
if (this.isOpen) {
document.addEventListener('pointerdown', this.handleClickOutside);
// Initialize roving tabindex and focus first item for APG compliance
this.updateTabIndices();
const availableItems = this.getAvailableItems();
if (this.focusedIndex >= 0 && availableItems[this.focusedIndex]) {
availableItems[this.focusedIndex].focus();
}
}
}
disconnectedCallback() {
if (this.rafId !== null) {
cancelAnimationFrame(this.rafId);
this.rafId = null;
}
if (this.typeAheadTimeoutId !== null) {
clearTimeout(this.typeAheadTimeoutId);
this.typeAheadTimeoutId = null;
}
document.removeEventListener('pointerdown', this.handleClickOutside);
this.button?.removeEventListener('click', this.handleButtonClick);
this.button?.removeEventListener('keydown', this.handleButtonKeyDown);
this.menu?.removeEventListener('keydown', this.handleMenuKeyDown);
this.menu?.removeEventListener('click', this.handleMenuClick);
this.menu?.removeEventListener('focusin', this.handleMenuFocusIn);
}
private getItems(): HTMLLIElement[] {
if (!this.menu) return [];
return Array.from(this.menu.querySelectorAll<HTMLLIElement>('[role="menuitem"]'));
}
private getAvailableItems(): HTMLLIElement[] {
return this.getItems().filter((item) => item.getAttribute('aria-disabled') !== 'true');
}
private openMenu(focusPosition: 'first' | 'last') {
if (!this.button || !this.menu) return;
const availableItems = this.getAvailableItems();
this.isOpen = true;
this.button.setAttribute('aria-expanded', 'true');
this.menu.removeAttribute('hidden');
this.menu.removeAttribute('inert');
document.addEventListener('pointerdown', this.handleClickOutside);
if (availableItems.length === 0) {
this.focusedIndex = -1;
return;
}
const targetIndex = focusPosition === 'first' ? 0 : availableItems.length - 1;
this.focusedIndex = targetIndex;
this.updateTabIndices();
availableItems[targetIndex]?.focus();
}
private closeMenu() {
if (!this.button || !this.menu) return;
this.isOpen = false;
this.focusedIndex = -1;
this.button.setAttribute('aria-expanded', 'false');
this.menu.setAttribute('hidden', '');
this.menu.setAttribute('inert', '');
// Clear type-ahead state
this.typeAheadBuffer = '';
if (this.typeAheadTimeoutId !== null) {
clearTimeout(this.typeAheadTimeoutId);
this.typeAheadTimeoutId = null;
}
document.removeEventListener('pointerdown', this.handleClickOutside);
// Reset tabindex
this.updateTabIndices();
}
private toggleMenu() {
if (this.isOpen) {
this.closeMenu();
} else {
this.openMenu('first');
}
}
private updateTabIndices() {
const items = this.getItems();
const availableItems = this.getAvailableItems();
items.forEach((item) => {
if (item.getAttribute('aria-disabled') === 'true') {
item.tabIndex = -1;
return;
}
const availableIndex = availableItems.indexOf(item);
item.tabIndex = availableIndex === this.focusedIndex ? 0 : -1;
});
}
private focusItem(index: number) {
const availableItems = this.getAvailableItems();
if (index >= 0 && index < availableItems.length) {
this.focusedIndex = index;
this.updateTabIndices();
availableItems[index]?.focus();
}
}
private handleTypeAhead(char: string) {
const availableItems = this.getAvailableItems();
if (availableItems.length === 0) return;
if (this.typeAheadTimeoutId !== null) {
clearTimeout(this.typeAheadTimeoutId);
}
this.typeAheadBuffer += char.toLowerCase();
const buffer = this.typeAheadBuffer;
const isSameChar = buffer.length > 1 && buffer.split('').every((c) => c === buffer[0]);
let startIndex: number;
let searchStr: string;
if (isSameChar) {
this.typeAheadBuffer = buffer[0];
searchStr = buffer[0];
startIndex = this.focusedIndex >= 0 ? (this.focusedIndex + 1) % availableItems.length : 0;
} else if (buffer.length === 1) {
searchStr = buffer;
startIndex = this.focusedIndex >= 0 ? (this.focusedIndex + 1) % availableItems.length : 0;
} else {
searchStr = buffer;
startIndex = this.focusedIndex >= 0 ? this.focusedIndex : 0;
}
for (let i = 0; i < availableItems.length; i++) {
const index = (startIndex + i) % availableItems.length;
const item = availableItems[index];
const label = item.textContent?.trim().toLowerCase() || '';
if (label.startsWith(searchStr)) {
this.focusItem(index);
break;
}
}
this.typeAheadTimeoutId = window.setTimeout(() => {
this.typeAheadBuffer = '';
this.typeAheadTimeoutId = null;
}, this.typeAheadTimeout);
}
private handleButtonClick = () => {
this.toggleMenu();
};
private handleButtonKeyDown = (event: KeyboardEvent) => {
switch (event.key) {
case 'Enter':
case ' ':
event.preventDefault();
this.openMenu('first');
break;
case 'ArrowDown':
event.preventDefault();
this.openMenu('first');
break;
case 'ArrowUp':
event.preventDefault();
this.openMenu('last');
break;
}
};
private handleMenuClick = (event: MouseEvent) => {
const target = event.target as HTMLElement;
const item = target.closest('[role="menuitem"]') as HTMLLIElement | null;
if (!item || item.getAttribute('aria-disabled') === 'true') return;
const itemId = item.dataset.itemId;
if (itemId) {
this.dispatchEvent(
new CustomEvent('itemselect', {
detail: { itemId },
bubbles: true,
})
);
}
this.closeMenu();
this.button?.focus();
};
private handleMenuFocusIn = (event: FocusEvent) => {
const target = event.target as HTMLElement;
const item = target.closest('[role="menuitem"]') as HTMLLIElement | null;
if (!item || item.getAttribute('aria-disabled') === 'true') return;
const availableItems = this.getAvailableItems();
const index = availableItems.indexOf(item);
if (index >= 0 && index !== this.focusedIndex) {
this.focusedIndex = index;
this.updateTabIndices();
}
};
private handleMenuKeyDown = (event: KeyboardEvent) => {
const availableItems = this.getAvailableItems();
// Handle Escape even with no available items
if (event.key === 'Escape') {
event.preventDefault();
this.closeMenu();
this.button?.focus();
return;
}
if (availableItems.length === 0) return;
const target = event.target as HTMLElement;
const currentItem = target.closest('[role="menuitem"]') as HTMLLIElement | null;
const currentIndex = currentItem ? availableItems.indexOf(currentItem) : -1;
// If focus is on disabled item, only handle Escape (already handled above)
if (currentIndex < 0) return;
switch (event.key) {
case 'ArrowDown': {
event.preventDefault();
const nextIndex = (currentIndex + 1) % availableItems.length;
this.focusItem(nextIndex);
break;
}
case 'ArrowUp': {
event.preventDefault();
const prevIndex = currentIndex === 0 ? availableItems.length - 1 : currentIndex - 1;
this.focusItem(prevIndex);
break;
}
case 'Home': {
event.preventDefault();
this.focusItem(0);
break;
}
case 'End': {
event.preventDefault();
this.focusItem(availableItems.length - 1);
break;
}
case 'Tab': {
this.closeMenu();
break;
}
case 'Enter':
case ' ': {
event.preventDefault();
const item = availableItems[currentIndex];
const itemId = item?.dataset.itemId;
if (itemId) {
this.dispatchEvent(
new CustomEvent('itemselect', {
detail: { itemId },
bubbles: true,
})
);
}
this.closeMenu();
this.button?.focus();
break;
}
default: {
// Type-ahead: single printable character
if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
event.preventDefault();
this.handleTypeAhead(event.key);
}
}
}
};
private handleClickOutside = (event: PointerEvent) => {
if (this.container && !this.container.contains(event.target as Node)) {
this.closeMenu();
}
};
}
if (!customElements.get('apg-menu-button')) {
customElements.define('apg-menu-button', ApgMenuButton);
}
</script> Usage
---
import MenuButton from './MenuButton.astro';
const items = [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'paste', label: 'Paste' },
{ id: 'delete', label: 'Delete', disabled: true },
];
---
<!-- Basic usage -->
<MenuButton items={items} label="Actions" />
<script>
// Handle selection via custom event
document.querySelectorAll('apg-menu-button').forEach((menuButton) => {
menuButton.addEventListener('itemselect', (e) => {
const event = e as CustomEvent<{ itemId: string }>;
console.log('Selected:', event.detail.itemId);
});
});
</script> API
| Prop | Type | Default | Description |
|---|---|---|---|
items | MenuItem[] | required | Array of menu items |
label | string | required | Button label text |
defaultOpen | boolean | false | Whether menu is initially open |
class | string | '' | Additional CSS class for the container |
Custom Events
| Event | Detail | Description |
|---|---|---|
itemselect | { itemId: string } | Dispatched when a menu item is selected |
Testing
Tests verify APG compliance across keyboard interaction, ARIA attributes, and accessibility requirements.
Test Categories
High Priority : APG Mouse Interaction
| Test | Description |
|---|---|
Button click | Opens menu on button click |
Toggle | Clicking button again closes menu |
Item click | Clicking menu item activates and closes menu |
Disabled item click | Clicking disabled item does nothing |
Click outside | Clicking outside menu closes it |
High Priority : APG Keyboard Interaction (Button)
| Test | Description |
|---|---|
Enter | Opens menu, focuses first enabled item |
Space | Opens menu, focuses first enabled item |
ArrowDown | Opens menu, focuses first enabled item |
ArrowUp | Opens menu, focuses last enabled item |
High Priority : APG Keyboard Interaction (Menu)
| Test | Description |
|---|---|
ArrowDown | Moves focus to next enabled item (wraps) |
ArrowUp | Moves focus to previous enabled item (wraps) |
Home | Moves focus to first enabled item |
End | Moves focus to last enabled item |
Escape | Closes menu, returns focus to button |
Tab | Closes menu, moves focus out |
Enter/Space | Activates item and closes menu |
Disabled skip | Skips disabled items during navigation |
High Priority : Type-Ahead Search
| Test | Description |
|---|---|
Single character | Focuses first item starting with typed character |
Multiple characters | Typed within 500ms form prefix search string |
Wrap around | Search wraps from end to beginning |
Buffer reset | Buffer resets after 500ms of inactivity |
High Priority : APG ARIA Attributes
| Test | Description |
|---|---|
aria-haspopup | Button has aria-haspopup="menu" |
aria-expanded | Button reflects open state (true/false) |
aria-controls | Button references menu ID |
role="menu" | Menu container has menu role |
role="menuitem" | Each item has menuitem role |
aria-labelledby | Menu references button for accessible name |
aria-disabled | Disabled items have aria-disabled="true" |
High Priority : Focus Management (Roving Tabindex)
| Test | Description |
|---|---|
tabIndex=0 | Focused item has tabIndex=0 |
tabIndex=-1 | Non-focused items have tabIndex=-1 |
Initial focus | First enabled item receives focus when menu opens |
Focus return | Focus returns to button when menu closes |
Medium Priority : Accessibility
| Test | Description |
|---|---|
axe violations | No WCAG 2.1 AA violations (via jest-axe) |
Example Test Code
The following is the actual E2E test file (e2e/menu-button.spec.ts).
import { test, expect } from '@playwright/test';
import AxeBuilder from '@axe-core/playwright';
/**
* E2E Tests for Menu Button Pattern
*
* A button that opens a menu containing menu items. The button has
* aria-haspopup="menu" and controls a dropdown menu.
*
* APG Reference: https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/
*/
const frameworks = ['react', 'vue', 'svelte', 'astro'] as const;
// ============================================
// Helper Functions
// ============================================
const getMenuButton = (page: import('@playwright/test').Page) => {
return page.getByRole('button', { name: /actions|file/i }).first();
};
const getMenu = (page: import('@playwright/test').Page) => {
return page.getByRole('menu');
};
const getMenuItems = (page: import('@playwright/test').Page) => {
return page.getByRole('menuitem');
};
const openMenu = async (page: import('@playwright/test').Page) => {
const button = getMenuButton(page);
await button.click();
await getMenu(page).waitFor({ state: 'visible' });
return button;
};
// Wait for hydration to complete
// This is necessary for frameworks like Svelte where event handlers are attached after hydration
const waitForHydration = async (page: import('@playwright/test').Page) => {
const button = getMenuButton(page);
// Wait for aria-controls to be set (basic check)
await expect(button).toHaveAttribute('aria-controls', /.+/);
// Poll until a click actually opens the menu (ensures handlers are attached)
await expect
.poll(async () => {
await button.click();
const isOpen = await getMenu(page).isVisible();
if (isOpen) {
await page.keyboard.press('Escape');
}
return isOpen;
})
.toBe(true);
};
// ============================================
// Framework-specific Tests
// ============================================
for (const framework of frameworks) {
test.describe(`Menu Button (${framework})`, () => {
test.beforeEach(async ({ page }) => {
await page.goto(`patterns/menu-button/${framework}/demo/`);
await getMenuButton(page).waitFor();
// Wait for hydration in frameworks that need it (Svelte)
// This ensures event handlers are attached before tests run
if (framework === 'svelte') {
await waitForHydration(page);
}
});
// ------------------------------------------
// 🔴 High Priority: APG ARIA Structure
// ------------------------------------------
test.describe('APG: ARIA Structure', () => {
test('button has aria-haspopup="menu"', async ({ page }) => {
const button = getMenuButton(page);
await expect(button).toHaveAttribute('aria-haspopup', 'menu');
});
test('button has aria-expanded (false when closed)', async ({ page }) => {
const button = getMenuButton(page);
await expect(button).toHaveAttribute('aria-expanded', 'false');
});
test('button has aria-expanded (true when open)', async ({ page }) => {
const button = await openMenu(page);
await expect(button).toHaveAttribute('aria-expanded', 'true');
});
test('button has aria-controls referencing menu id', async ({ page }) => {
const button = getMenuButton(page);
// Wait for hydration - aria-controls may not be set immediately in Svelte
await expect
.poll(async () => {
const id = await button.getAttribute('aria-controls');
return id && id.length > 1 && !id.startsWith('-');
})
.toBe(true);
const menuId = await button.getAttribute('aria-controls');
expect(menuId).toBeTruthy();
await openMenu(page);
const menu = getMenu(page);
await expect(menu).toHaveAttribute('id', menuId!);
});
test('menu has role="menu"', async ({ page }) => {
await openMenu(page);
const menu = getMenu(page);
await expect(menu).toBeVisible();
await expect(menu).toHaveRole('menu');
});
test('menu has accessible name via aria-labelledby', async ({ page }) => {
await openMenu(page);
const menu = getMenu(page);
const labelledby = await menu.getAttribute('aria-labelledby');
expect(labelledby).toBeTruthy();
// Verify it references the button
const button = getMenuButton(page);
const buttonId = await button.getAttribute('id');
expect(labelledby).toBe(buttonId);
});
test('menu items have role="menuitem"', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const count = await items.count();
expect(count).toBeGreaterThan(0);
for (let i = 0; i < count; i++) {
await expect(items.nth(i)).toHaveRole('menuitem');
}
});
test('disabled items have aria-disabled="true"', async ({ page }) => {
// Use the File menu demo which must have disabled item (Export)
const fileButton = page.getByRole('button', { name: /file/i });
await expect(fileButton).toBeVisible();
await fileButton.click();
await getMenu(page).waitFor({ state: 'visible' });
const disabledItem = page.getByRole('menuitem', { name: /export/i });
await expect(disabledItem).toBeVisible();
await expect(disabledItem).toHaveAttribute('aria-disabled', 'true');
});
});
// ------------------------------------------
// 🔴 High Priority: Keyboard Interaction (Button)
// ------------------------------------------
test.describe('APG: Keyboard Interaction (Button)', () => {
test('Enter opens menu and focuses first item', async ({ page }) => {
const button = getMenuButton(page);
await button.focus();
await expect(button).toBeFocused();
await button.press('Enter');
await expect(getMenu(page)).toBeVisible();
await expect(button).toHaveAttribute('aria-expanded', 'true');
// First item should be focused
const firstItem = getMenuItems(page).first();
await expect(firstItem).toBeFocused();
});
test('Space opens menu and focuses first item', async ({ page }) => {
const button = getMenuButton(page);
await button.focus();
await expect(button).toBeFocused();
await button.press('Space');
await expect(getMenu(page)).toBeVisible();
const firstItem = getMenuItems(page).first();
await expect(firstItem).toBeFocused();
});
test('ArrowDown opens menu and focuses first item', async ({ page }) => {
const button = getMenuButton(page);
await button.focus();
await expect(button).toBeFocused();
await button.press('ArrowDown');
await expect(getMenu(page)).toBeVisible();
const firstItem = getMenuItems(page).first();
await expect(firstItem).toBeFocused();
});
test('ArrowUp opens menu and focuses last enabled item', async ({ page }) => {
const button = getMenuButton(page);
await button.focus();
await expect(button).toBeFocused();
await button.press('ArrowUp');
await expect(getMenu(page)).toBeVisible();
// Find the last enabled item by checking focus
const focusedItem = page.locator(':focus');
await expect(focusedItem).toHaveRole('menuitem');
});
});
// ------------------------------------------
// 🔴 High Priority: Keyboard Interaction (Menu)
// ------------------------------------------
test.describe('APG: Keyboard Interaction (Menu)', () => {
test('ArrowDown moves to next item', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('ArrowDown');
const secondItem = items.nth(1);
await expect(secondItem).toBeFocused();
});
test('ArrowDown wraps from last to first', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
// Focus the first item, then use End to go to last
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('End');
// Get the last item and verify it's focused
const lastItem = items.last();
await expect(lastItem).toBeFocused();
const focusedBefore = await page.evaluate(() => document.activeElement?.textContent);
await lastItem.press('ArrowDown');
const focusedAfter = await page.evaluate(() => document.activeElement?.textContent);
// Should have wrapped to a different item (first)
expect(focusedAfter).not.toBe(focusedBefore);
});
test('ArrowUp moves to previous item', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
const secondItem = items.nth(1);
// Navigate to second item using keyboard
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('ArrowDown');
await expect(secondItem).toBeFocused();
await secondItem.press('ArrowUp');
await expect(firstItem).toBeFocused();
});
test('ArrowUp wraps from first to last', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.focus();
await expect(firstItem).toBeFocused();
const focusedBefore = await page.evaluate(() => document.activeElement?.textContent);
await firstItem.press('ArrowUp');
const focusedAfter = await page.evaluate(() => document.activeElement?.textContent);
// Should have wrapped to last item
expect(focusedAfter).not.toBe(focusedBefore);
});
test('Home moves to first enabled item', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
const secondItem = items.nth(1);
// Navigate to second item using keyboard
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('ArrowDown');
await expect(secondItem).toBeFocused();
await secondItem.press('Home');
await expect(firstItem).toBeFocused();
});
test('End moves to last enabled item', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('End');
// Focus should be on last item (or last enabled item)
const focusedItem = page.locator(':focus');
await expect(focusedItem).toHaveRole('menuitem');
// Should not be the first item anymore
const focusedText = await focusedItem.textContent();
const firstText = await firstItem.textContent();
expect(focusedText).not.toBe(firstText);
});
test('Escape closes menu and returns focus to button', async ({ page }) => {
const button = await openMenu(page);
await page.keyboard.press('Escape');
await expect(getMenu(page)).not.toBeVisible();
await expect(button).toHaveAttribute('aria-expanded', 'false');
await expect(button).toBeFocused();
});
test('Enter activates item and closes menu', async ({ page }) => {
const button = await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('Enter');
await expect(getMenu(page)).not.toBeVisible();
await expect(button).toBeFocused();
});
test('Space activates item and closes menu', async ({ page }) => {
const button = await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('Space');
await expect(getMenu(page)).not.toBeVisible();
await expect(button).toBeFocused();
});
test('Tab closes menu', async ({ page }) => {
await openMenu(page);
await page.keyboard.press('Tab');
await expect(getMenu(page)).not.toBeVisible();
});
});
// ------------------------------------------
// 🔴 High Priority: Focus Management (Roving Tabindex)
// ------------------------------------------
test.describe('APG: Focus Management', () => {
test('focused item has tabindex="0"', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.focus();
await expect(firstItem).toHaveAttribute('tabindex', '0');
});
test('non-focused items have tabindex="-1"', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const count = await items.count();
if (count > 1) {
const firstItem = items.first();
await firstItem.focus();
// Check second item has tabindex="-1"
const secondItem = items.nth(1);
await expect(secondItem).toHaveAttribute('tabindex', '-1');
}
});
test('disabled items are skipped during navigation', async ({ page }) => {
// Use the File menu demo which must have disabled items
const fileButton = page.getByRole('button', { name: /file/i });
await expect(fileButton).toBeVisible();
await fileButton.click();
await getMenu(page).waitFor({ state: 'visible' });
// Navigate through all items
const focusedTexts: string[] = [];
// Get first focused item
const firstItem = getMenuItems(page).first();
await expect(firstItem).toBeFocused();
for (let i = 0; i < 10; i++) {
const focusedElement = page.locator(':focus');
const text = await focusedElement.textContent();
if (text && !focusedTexts.includes(text)) {
focusedTexts.push(text);
}
await focusedElement.press('ArrowDown');
}
// "Export" (disabled) should not be in the focused list
expect(focusedTexts).not.toContain('Export');
});
});
// ------------------------------------------
// 🔴 High Priority: Click Interaction
// ------------------------------------------
test.describe('APG: Click Interaction', () => {
test('click button opens menu', async ({ page }) => {
const button = getMenuButton(page);
await button.click();
await expect(getMenu(page)).toBeVisible();
await expect(button).toHaveAttribute('aria-expanded', 'true');
});
test('click button again closes menu (toggle)', async ({ page }) => {
const button = getMenuButton(page);
await button.click();
await expect(getMenu(page)).toBeVisible();
await button.click();
await expect(getMenu(page)).not.toBeVisible();
await expect(button).toHaveAttribute('aria-expanded', 'false');
});
test('click menu item activates and closes menu', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
await firstItem.click();
await expect(getMenu(page)).not.toBeVisible();
});
test('click outside menu closes it', async ({ page }) => {
await openMenu(page);
const menu = getMenu(page);
const menuBox = await menu.boundingBox();
expect(menuBox).not.toBeNull();
const viewportSize = page.viewportSize();
expect(viewportSize).not.toBeNull();
// Find a safe position outside menu, handling edge cases
const candidates = [
// Above menu (if there's space)
{ x: menuBox!.x + menuBox!.width / 2, y: Math.max(1, menuBox!.y - 20) },
// Left of menu (if there's space)
{ x: Math.max(1, menuBox!.x - 20), y: menuBox!.y + menuBox!.height / 2 },
// Right of menu (if there's space)
{
x: Math.min(viewportSize!.width - 1, menuBox!.x + menuBox!.width + 20),
y: menuBox!.y + menuBox!.height / 2,
},
// Below menu (if there's space)
{
x: menuBox!.x + menuBox!.width / 2,
y: Math.min(viewportSize!.height - 1, menuBox!.y + menuBox!.height + 20),
},
];
// Find first candidate that's outside menu bounds
const isOutsideMenu = (x: number, y: number) =>
x < menuBox!.x ||
x > menuBox!.x + menuBox!.width ||
y < menuBox!.y ||
y > menuBox!.y + menuBox!.height;
const safePosition = candidates.find((pos) => isOutsideMenu(pos.x, pos.y));
if (safePosition) {
await page.mouse.click(safePosition.x, safePosition.y);
} else {
// Fallback: click at viewport corner (1,1)
await page.mouse.click(1, 1);
}
await expect(getMenu(page)).not.toBeVisible();
});
});
// ------------------------------------------
// 🟡 Medium Priority: Type-Ahead
// ------------------------------------------
test.describe('Type-Ahead', () => {
test('single character focuses matching item', async ({ page }) => {
await openMenu(page);
// Wait for first item to be focused (menu opens with focus on first item)
const firstItem = getMenuItems(page).first();
await expect(firstItem).toBeFocused();
// Type 'p' to find "Paste" - use element.press() for single key
await firstItem.press('p');
// Wait for focus to move to item starting with 'p'
// Use trim() because some frameworks may include whitespace in textContent
await expect
.poll(async () => {
const text = await page.evaluate(
() => document.activeElement?.textContent?.trim().toLowerCase() || ''
);
return text.startsWith('p');
})
.toBe(true);
});
test('type-ahead wraps around', async ({ page }) => {
await openMenu(page);
const items = getMenuItems(page);
const firstItem = items.first();
// Navigate to last item using keyboard
await firstItem.focus();
await expect(firstItem).toBeFocused();
await firstItem.press('End');
const lastItem = items.last();
await expect(lastItem).toBeFocused();
// Type character that matches earlier item - use element.press() for single key
await lastItem.press('c');
// Wait for focus to wrap and find item starting with 'c'
// Use trim() because some frameworks may include whitespace in textContent
await expect
.poll(async () => {
const text = await page.evaluate(
() => document.activeElement?.textContent?.trim().toLowerCase() || ''
);
return text.startsWith('c');
})
.toBe(true);
});
});
// ------------------------------------------
// 🟢 Low Priority: Accessibility
// ------------------------------------------
test.describe('Accessibility', () => {
test('has no axe-core violations (closed)', async ({ page }) => {
const results = await new AxeBuilder({ page })
.include('.apg-menu-button')
.disableRules(['color-contrast'])
.analyze();
expect(results.violations).toEqual([]);
});
test('has no axe-core violations (open)', async ({ page }) => {
await openMenu(page);
const results = await new AxeBuilder({ page })
.include('.apg-menu-button')
.disableRules(['color-contrast'])
.analyze();
expect(results.violations).toEqual([]);
});
});
});
}
// ============================================
// Cross-framework Consistency Tests
// ============================================
test.describe('Menu Button - Cross-framework Consistency', () => {
test('all frameworks have menu button with aria-haspopup="menu"', async ({ page }) => {
for (const framework of frameworks) {
await page.goto(`patterns/menu-button/${framework}/demo/`);
await getMenuButton(page).waitFor();
const button = getMenuButton(page);
await expect(button).toHaveAttribute('aria-haspopup', 'menu');
}
});
test('all frameworks open menu on click', async ({ page }) => {
for (const framework of frameworks) {
await page.goto(`patterns/menu-button/${framework}/demo/`);
await getMenuButton(page).waitFor();
const button = getMenuButton(page);
await button.click();
const menu = getMenu(page);
await expect(menu).toBeVisible();
// Close for next iteration
await page.keyboard.press('Escape');
}
});
test('all frameworks close menu on Escape', async ({ page }) => {
for (const framework of frameworks) {
await page.goto(`patterns/menu-button/${framework}/demo/`);
await getMenuButton(page).waitFor();
await openMenu(page);
await expect(getMenu(page)).toBeVisible();
await page.keyboard.press('Escape');
await expect(getMenu(page)).not.toBeVisible();
}
});
test('all frameworks have consistent keyboard navigation', async ({ page }) => {
for (const framework of frameworks) {
await page.goto(`patterns/menu-button/${framework}/demo/`);
await getMenuButton(page).waitFor();
// Wait for hydration (especially needed for Svelte)
if (framework === 'svelte') {
await waitForHydration(page);
}
const button = getMenuButton(page);
await button.focus();
await expect(button).toBeFocused();
await button.press('Enter');
const menu = getMenu(page);
await expect(menu).toBeVisible();
// First item should be focused
const firstItem = getMenuItems(page).first();
await expect(firstItem).toBeFocused();
// Arrow navigation
await firstItem.press('ArrowDown');
const secondItem = getMenuItems(page).nth(1);
await expect(secondItem).toBeFocused();
await page.keyboard.press('Escape');
}
});
}); Testing Tools
- Vitest (opens in new tab) - Test runner for unit tests
- Testing Library (opens in new tab) - Framework-specific testing utilities (React, Vue, Svelte)
- Playwright (opens in new tab) - E2E testing (136 cross-framework tests)
- @axe-core/playwright (opens in new tab) - Automated accessibility testing
E2E tests: e2e/menu-button.spec.ts (opens in new tab)
See
testing-strategy.md
(opens in new tab) for full documentation.
/**
* MenuButton Web Component Tests
*
* Note: These are limited unit tests for the Web Component class.
* Full keyboard navigation and focus management tests require E2E testing
* with Playwright due to jsdom limitations with focus events.
*/
import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
// Mock the MenuButton Web Component for testing
// In a real E2E test, this would use the actual compiled Astro component
describe('MenuButton (Web Component)', () => {
let container: HTMLElement;
// Web Component class extracted for testing
class TestApgMenuButton extends HTMLElement {
private container: HTMLDivElement | null = null;
private button: HTMLButtonElement | null = null;
private menu: HTMLUListElement | null = null;
private rafId: number | null = null;
private isOpen = false;
private focusedIndex = -1;
private typeAheadBuffer = '';
private typeAheadTimeoutId: number | null = null;
private typeAheadTimeout = 500;
connectedCallback() {
this.rafId = requestAnimationFrame(() => this.initialize());
}
private initialize() {
this.rafId = null;
this.container = this.querySelector('.apg-menu-button');
this.button = this.querySelector('[data-menu-trigger]');
this.menu = this.querySelector('[data-menu-list]');
if (!this.button || !this.menu) {
return;
}
this.isOpen = this.dataset.defaultOpen === 'true';
this.focusedIndex = parseInt(this.dataset.initialFocusIndex || '-1', 10);
this.button.addEventListener('click', this.handleButtonClick);
this.button.addEventListener('keydown', this.handleButtonKeyDown);
this.menu.addEventListener('keydown', this.handleMenuKeyDown);
this.menu.addEventListener('click', this.handleMenuClick);
this.menu.addEventListener('focusin', this.handleMenuFocusIn);
if (this.isOpen) {
document.addEventListener('pointerdown', this.handleClickOutside);
}
}
disconnectedCallback() {
if (this.rafId !== null) {
cancelAnimationFrame(this.rafId);
this.rafId = null;
}
if (this.typeAheadTimeoutId !== null) {
clearTimeout(this.typeAheadTimeoutId);
this.typeAheadTimeoutId = null;
}
document.removeEventListener('pointerdown', this.handleClickOutside);
this.button?.removeEventListener('click', this.handleButtonClick);
this.button?.removeEventListener('keydown', this.handleButtonKeyDown);
this.menu?.removeEventListener('keydown', this.handleMenuKeyDown);
this.menu?.removeEventListener('click', this.handleMenuClick);
this.menu?.removeEventListener('focusin', this.handleMenuFocusIn);
}
private getItems(): HTMLLIElement[] {
if (!this.menu) return [];
return Array.from(this.menu.querySelectorAll<HTMLLIElement>('[role="menuitem"]'));
}
private getAvailableItems(): HTMLLIElement[] {
return this.getItems().filter((item) => item.getAttribute('aria-disabled') !== 'true');
}
private openMenu(focusPosition: 'first' | 'last') {
if (!this.button || !this.menu) return;
const availableItems = this.getAvailableItems();
this.isOpen = true;
this.button.setAttribute('aria-expanded', 'true');
this.menu.removeAttribute('hidden');
this.menu.removeAttribute('inert');
document.addEventListener('pointerdown', this.handleClickOutside);
if (availableItems.length === 0) {
this.focusedIndex = -1;
return;
}
const targetIndex = focusPosition === 'first' ? 0 : availableItems.length - 1;
this.focusedIndex = targetIndex;
this.updateTabIndices();
availableItems[targetIndex]?.focus();
}
private closeMenu() {
if (!this.button || !this.menu) return;
this.isOpen = false;
this.focusedIndex = -1;
this.button.setAttribute('aria-expanded', 'false');
this.menu.setAttribute('hidden', '');
this.menu.setAttribute('inert', '');
this.typeAheadBuffer = '';
if (this.typeAheadTimeoutId !== null) {
clearTimeout(this.typeAheadTimeoutId);
this.typeAheadTimeoutId = null;
}
document.removeEventListener('pointerdown', this.handleClickOutside);
this.updateTabIndices();
}
private toggleMenu() {
if (this.isOpen) {
this.closeMenu();
} else {
this.openMenu('first');
}
}
private updateTabIndices() {
const items = this.getItems();
const availableItems = this.getAvailableItems();
items.forEach((item) => {
if (item.getAttribute('aria-disabled') === 'true') {
item.tabIndex = -1;
return;
}
const availableIndex = availableItems.indexOf(item);
item.tabIndex = availableIndex === this.focusedIndex ? 0 : -1;
});
}
private focusItem(index: number) {
const availableItems = this.getAvailableItems();
if (index >= 0 && index < availableItems.length) {
this.focusedIndex = index;
this.updateTabIndices();
availableItems[index]?.focus();
}
}
private handleTypeAhead(char: string) {
const availableItems = this.getAvailableItems();
if (availableItems.length === 0) return;
if (this.typeAheadTimeoutId !== null) {
clearTimeout(this.typeAheadTimeoutId);
}
this.typeAheadBuffer += char.toLowerCase();
const buffer = this.typeAheadBuffer;
const isSameChar = buffer.length > 1 && buffer.split('').every((c) => c === buffer[0]);
let startIndex: number;
let searchStr: string;
if (isSameChar) {
this.typeAheadBuffer = buffer[0];
searchStr = buffer[0];
startIndex = this.focusedIndex >= 0 ? (this.focusedIndex + 1) % availableItems.length : 0;
} else if (buffer.length === 1) {
searchStr = buffer;
startIndex = this.focusedIndex >= 0 ? (this.focusedIndex + 1) % availableItems.length : 0;
} else {
searchStr = buffer;
startIndex = this.focusedIndex >= 0 ? this.focusedIndex : 0;
}
for (let i = 0; i < availableItems.length; i++) {
const index = (startIndex + i) % availableItems.length;
const item = availableItems[index];
const label = item.textContent?.trim().toLowerCase() || '';
if (label.startsWith(searchStr)) {
this.focusItem(index);
break;
}
}
this.typeAheadTimeoutId = window.setTimeout(() => {
this.typeAheadBuffer = '';
this.typeAheadTimeoutId = null;
}, this.typeAheadTimeout);
}
private handleButtonClick = () => {
this.toggleMenu();
};
private handleButtonKeyDown = (event: KeyboardEvent) => {
switch (event.key) {
case 'Enter':
case ' ':
event.preventDefault();
this.openMenu('first');
break;
case 'ArrowDown':
event.preventDefault();
this.openMenu('first');
break;
case 'ArrowUp':
event.preventDefault();
this.openMenu('last');
break;
}
};
private handleMenuClick = (event: MouseEvent) => {
const target = event.target as HTMLElement;
const item = target.closest('[role="menuitem"]') as HTMLLIElement | null;
if (!item || item.getAttribute('aria-disabled') === 'true') return;
const itemId = item.dataset.itemId;
if (itemId) {
this.dispatchEvent(
new CustomEvent('itemselect', {
detail: { itemId },
bubbles: true,
})
);
}
this.closeMenu();
this.button?.focus();
};
private handleMenuFocusIn = (event: FocusEvent) => {
const target = event.target as HTMLElement;
const item = target.closest('[role="menuitem"]') as HTMLLIElement | null;
if (!item || item.getAttribute('aria-disabled') === 'true') return;
const availableItems = this.getAvailableItems();
const index = availableItems.indexOf(item);
if (index >= 0 && index !== this.focusedIndex) {
this.focusedIndex = index;
this.updateTabIndices();
}
};
private handleMenuKeyDown = (event: KeyboardEvent) => {
const availableItems = this.getAvailableItems();
if (event.key === 'Escape') {
event.preventDefault();
this.closeMenu();
this.button?.focus();
return;
}
if (availableItems.length === 0) return;
const target = event.target as HTMLElement;
const currentItem = target.closest('[role="menuitem"]') as HTMLLIElement | null;
const currentIndex = currentItem ? availableItems.indexOf(currentItem) : -1;
if (currentIndex < 0) return;
switch (event.key) {
case 'ArrowDown': {
event.preventDefault();
const nextIndex = (currentIndex + 1) % availableItems.length;
this.focusItem(nextIndex);
break;
}
case 'ArrowUp': {
event.preventDefault();
const prevIndex = currentIndex === 0 ? availableItems.length - 1 : currentIndex - 1;
this.focusItem(prevIndex);
break;
}
case 'Home': {
event.preventDefault();
this.focusItem(0);
break;
}
case 'End': {
event.preventDefault();
this.focusItem(availableItems.length - 1);
break;
}
case 'Tab': {
this.closeMenu();
break;
}
case 'Enter':
case ' ': {
event.preventDefault();
const item = availableItems[currentIndex];
const itemId = item?.dataset.itemId;
if (itemId) {
this.dispatchEvent(
new CustomEvent('itemselect', {
detail: { itemId },
bubbles: true,
})
);
}
this.closeMenu();
this.button?.focus();
break;
}
default: {
if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
event.preventDefault();
this.handleTypeAhead(event.key);
}
}
}
};
private handleClickOutside = (event: PointerEvent) => {
if (this.container && !this.container.contains(event.target as Node)) {
this.closeMenu();
}
};
// Expose for testing
get _isOpen() {
return this.isOpen;
}
get _focusedIndex() {
return this.focusedIndex;
}
}
function createMenuButtonHTML(
options: {
items?: { id: string; label: string; disabled?: boolean }[];
defaultOpen?: boolean;
} = {}
) {
const { items = [{ id: 'item1', label: 'Item 1' }], defaultOpen = false } = options;
const availableItems = items.filter((i) => !i.disabled);
const initialFocusIndex = defaultOpen && availableItems.length > 0 ? 0 : -1;
const itemsHTML = items
.map((item) => {
const availableIndex = availableItems.findIndex((i) => i.id === item.id);
const isFocusTarget = availableIndex === initialFocusIndex;
const tabIndex = item.disabled ? -1 : isFocusTarget ? 0 : -1;
return `<li role="menuitem" data-item-id="${item.id}" tabindex="${tabIndex}" ${item.disabled ? 'aria-disabled="true"' : ''} class="apg-menu-button-item">${item.label}</li>`;
})
.join('');
return `
<apg-menu-button ${defaultOpen ? 'data-default-open="true"' : ''} data-initial-focus-index="${initialFocusIndex}">
<div class="apg-menu-button">
<button type="button" class="apg-menu-button-trigger" aria-haspopup="menu" aria-expanded="${defaultOpen}" aria-controls="menu-1" data-menu-trigger>
Actions
</button>
<ul id="menu-1" role="menu" aria-labelledby="button-1" class="apg-menu-button-menu" ${!defaultOpen ? 'hidden inert' : ''} data-menu-list>
${itemsHTML}
</ul>
</div>
</apg-menu-button>
`;
}
beforeEach(() => {
container = document.createElement('div');
document.body.appendChild(container);
// Register custom element if not already registered
if (!customElements.get('apg-menu-button')) {
customElements.define('apg-menu-button', TestApgMenuButton);
}
});
afterEach(() => {
container.remove();
vi.restoreAllMocks();
});
describe('Initial Rendering', () => {
it('renders with closed menu by default', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'paste', label: 'Paste' },
],
});
// Wait for custom element to initialize
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
expect(button).toBeTruthy();
expect(button.getAttribute('aria-expanded')).toBe('false');
expect(button.getAttribute('aria-haspopup')).toBe('menu');
expect(menu.hasAttribute('hidden')).toBe(true);
});
it('renders with open menu when defaultOpen is true', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
});
it('renders menu items with role="menuitem"', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'paste', label: 'Paste' },
],
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
expect(items.length).toBe(3);
expect(items[0].textContent?.trim()).toBe('Cut');
expect(items[1].textContent?.trim()).toBe('Copy');
expect(items[2].textContent?.trim()).toBe('Paste');
});
it('renders disabled items with aria-disabled', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy', disabled: true },
{ id: 'paste', label: 'Paste' },
],
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
expect(items[0].getAttribute('aria-disabled')).toBeNull();
expect(items[1].getAttribute('aria-disabled')).toBe('true');
expect(items[2].getAttribute('aria-disabled')).toBeNull();
});
});
describe('Button Click', () => {
it('opens menu on button click', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
button.click();
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
});
it('closes menu on second button click', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
button.click(); // Open
button.click(); // Close
expect(button.getAttribute('aria-expanded')).toBe('false');
expect(menu.hasAttribute('hidden')).toBe(true);
});
});
describe('Button Keyboard Navigation', () => {
it('opens menu on Enter key', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
button.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
});
it('opens menu on Space key', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
button.dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
});
it('opens menu and focuses first item on ArrowDown', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
const items = container.querySelectorAll('[role="menuitem"]');
button.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
expect(items[0].getAttribute('tabindex')).toBe('0');
});
it('opens menu and focuses last item on ArrowUp', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const items = container.querySelectorAll('[role="menuitem"]');
button.dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }));
expect(items[1].getAttribute('tabindex')).toBe('0');
});
});
describe('Menu Item Selection', () => {
it('dispatches itemselect event on item click', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const element = container.querySelector('apg-menu-button') as HTMLElement;
const items = container.querySelectorAll('[role="menuitem"]');
const selectHandler = vi.fn();
element.addEventListener('itemselect', selectHandler);
(items[1] as HTMLLIElement).click();
expect(selectHandler).toHaveBeenCalledTimes(1);
expect(selectHandler.mock.calls[0][0].detail.itemId).toBe('copy');
});
it('closes menu after item selection', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
const items = container.querySelectorAll('[role="menuitem"]');
(items[0] as HTMLLIElement).click();
expect(button.getAttribute('aria-expanded')).toBe('false');
expect(menu.hasAttribute('hidden')).toBe(true);
});
it('does not dispatch event for disabled item click', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut', disabled: true },
{ id: 'copy', label: 'Copy' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const element = container.querySelector('apg-menu-button') as HTMLElement;
const items = container.querySelectorAll('[role="menuitem"]');
const selectHandler = vi.fn();
element.addEventListener('itemselect', selectHandler);
(items[0] as HTMLLIElement).click();
expect(selectHandler).not.toHaveBeenCalled();
});
});
describe('Menu Keyboard Navigation', () => {
it('closes menu and focuses button on Escape', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
const items = container.querySelectorAll('[role="menuitem"]');
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('false');
expect(menu.hasAttribute('hidden')).toBe(true);
});
it('selects item on Enter key', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const element = container.querySelector('apg-menu-button') as HTMLElement;
const items = container.querySelectorAll('[role="menuitem"]');
const selectHandler = vi.fn();
element.addEventListener('itemselect', selectHandler);
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', bubbles: true }));
expect(selectHandler).toHaveBeenCalledTimes(1);
expect(selectHandler.mock.calls[0][0].detail.itemId).toBe('cut');
});
it('selects item on Space key', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const element = container.querySelector('apg-menu-button') as HTMLElement;
const items = container.querySelectorAll('[role="menuitem"]');
const selectHandler = vi.fn();
element.addEventListener('itemselect', selectHandler);
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: ' ', bubbles: true }));
expect(selectHandler).toHaveBeenCalledTimes(1);
});
it('moves focus to next item on ArrowDown with wrapping', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
// First item should have tabindex 0 initially
expect(items[0].getAttribute('tabindex')).toBe('0');
// ArrowDown from first item
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
expect(items[0].getAttribute('tabindex')).toBe('-1');
expect(items[1].getAttribute('tabindex')).toBe('0');
// ArrowDown from last item wraps to first
items[1].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
expect(items[0].getAttribute('tabindex')).toBe('0');
expect(items[1].getAttribute('tabindex')).toBe('-1');
});
it('moves focus to previous item on ArrowUp with wrapping', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
// ArrowUp from first item wraps to last
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowUp', bubbles: true }));
expect(items[0].getAttribute('tabindex')).toBe('-1');
expect(items[1].getAttribute('tabindex')).toBe('0');
});
it('moves focus to first item on Home', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'paste', label: 'Paste' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
// Move to last item first
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
expect(items[2].getAttribute('tabindex')).toBe('0');
// Press Home
items[2].dispatchEvent(new KeyboardEvent('keydown', { key: 'Home', bubbles: true }));
expect(items[0].getAttribute('tabindex')).toBe('0');
});
it('moves focus to last item on End', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'paste', label: 'Paste' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'End', bubbles: true }));
expect(items[2].getAttribute('tabindex')).toBe('0');
});
it('closes menu on Tab key', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
const items = container.querySelectorAll('[role="menuitem"]');
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('false');
expect(menu.hasAttribute('hidden')).toBe(true);
});
});
describe('Disabled Items', () => {
it('skips disabled items in navigation', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy', disabled: true },
{ id: 'paste', label: 'Paste' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
// First available item has tabindex 0
expect(items[0].getAttribute('tabindex')).toBe('0');
// ArrowDown should skip disabled item
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'ArrowDown', bubbles: true }));
// Paste (index 2) should have tabindex 0, disabled Copy should have -1
expect(items[1].getAttribute('tabindex')).toBe('-1');
expect(items[2].getAttribute('tabindex')).toBe('0');
});
it('disabled items have tabindex -1', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy', disabled: true },
],
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
expect(items[1].getAttribute('tabindex')).toBe('-1');
});
});
describe('Click Outside', () => {
it('closes menu when clicking outside', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
// Simulate click outside
document.body.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('false');
expect(menu.hasAttribute('hidden')).toBe(true);
});
it('does not close menu when clicking inside', async () => {
container.innerHTML = createMenuButtonHTML({
items: [{ id: 'cut', label: 'Cut' }],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
// Click inside menu container
const menuContainer = container.querySelector('.apg-menu-button') as HTMLDivElement;
menuContainer.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true }));
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
});
});
describe('Type-ahead', () => {
it('focuses matching item on character input', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'paste', label: 'Paste' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
// Type 'p' to focus Paste
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'p', bubbles: true }));
expect(items[2].getAttribute('tabindex')).toBe('0');
});
it('cycles through items starting with same character', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut' },
{ id: 'copy', label: 'Copy' },
{ id: 'clear', label: 'Clear' },
],
defaultOpen: true,
});
await new Promise((r) => requestAnimationFrame(r));
const items = container.querySelectorAll('[role="menuitem"]');
// Type 'c' - should go to Copy (next after Cut which starts with C)
items[0].dispatchEvent(new KeyboardEvent('keydown', { key: 'c', bubbles: true }));
expect(items[1].getAttribute('tabindex')).toBe('0');
// Type 'c' again - should go to Clear
items[1].dispatchEvent(new KeyboardEvent('keydown', { key: 'c', bubbles: true }));
expect(items[2].getAttribute('tabindex')).toBe('0');
// Type 'c' again - should wrap to Cut
items[2].dispatchEvent(new KeyboardEvent('keydown', { key: 'c', bubbles: true }));
expect(items[0].getAttribute('tabindex')).toBe('0');
});
});
describe('Empty Items', () => {
it('opens empty menu without focusing any item', async () => {
container.innerHTML = createMenuButtonHTML({
items: [],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const menu = container.querySelector('[data-menu-list]') as HTMLUListElement;
button.click();
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(menu.hasAttribute('hidden')).toBe(false);
});
});
describe('All Items Disabled', () => {
it('opens menu but does not focus any item when all disabled', async () => {
container.innerHTML = createMenuButtonHTML({
items: [
{ id: 'cut', label: 'Cut', disabled: true },
{ id: 'copy', label: 'Copy', disabled: true },
],
});
await new Promise((r) => requestAnimationFrame(r));
const button = container.querySelector('[data-menu-trigger]') as HTMLButtonElement;
const items = container.querySelectorAll('[role="menuitem"]');
button.click();
expect(button.getAttribute('aria-expanded')).toBe('true');
expect(items[0].getAttribute('tabindex')).toBe('-1');
expect(items[1].getAttribute('tabindex')).toBe('-1');
});
});
}); Resources
- WAI-ARIA APG: Menu Button Pattern (opens in new tab)
- AI Implementation Guide (llm.md) (opens in new tab) - ARIA specs, keyboard support, test checklist