APG Patterns
日本語
日本語

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

Open demo only →

Accessibility Features

WAI-ARIA Roles

RoleTarget ElementDescription
buttonTrigger (<button>)The trigger that opens the menu (implicit via <button> element)
menuContainer (<ul>)A widget offering a list of choices to the user
menuitemEach 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)

KeyAction
Enter / SpaceOpen menu and focus first item
Down ArrowOpen menu and focus first item
Up ArrowOpen menu and focus last item
KeyAction
Down ArrowMove focus to next item (wraps to first)
Up ArrowMove focus to previous item (wraps to last)
HomeMove focus to first item
EndMove focus to last item
EscapeClose menu and return focus to button
TabClose menu and move focus to next focusable element
Enter / SpaceActivate focused item and close menu
Type characterType-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

EventBehavior
Focused menu itemtabIndex="0"
Other menu itemstabIndex="-1"
Arrow key navigationWraps from last to first and vice versa
Disabled itemsSkipped during navigation
Menu closesFocus returns to button

References

Source Code

MenuButton.astro
---
/**
 * 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

Example
---
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).

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

E2E tests: e2e/menu-button.spec.ts (opens in new tab)
See testing-strategy.md (opens in new tab) for full documentation.

MenuButton.test.astro.ts
/**
 * 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