Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
3.0 KB
Raw Blame
// Copyright (c) Meta Platforms, Inc. and affiliates.

/**
 * @file menuItemRoles.ts
 * @output Shared menu-item role set, row selectors, and keyboard activation.
 * @position Internal; used by DropdownMenu and ContextMenu so their
 *   roving-focus, typeahead, and Enter/Space activation stay in sync.
 *
 * Includes the selectable items (menuitemradio/menuitemcheckbox) alongside
 * plain menuitem so checkbox/radio rows are reachable by arrow keys, typeahead,
 * and Enter/Space — not just role="menuitem".
 */

export const MENU_ITEM_ROLES: ReadonlySet<string> = new Set([
  'menuitem',
  'menuitemradio',
  'menuitemcheckbox',
]);

/** The rows a press can act on: enabled rows only. */
export const MENU_ITEM_SELECTOR: string = [...MENU_ITEM_ROLES]
  .map(role => `[role="${role}"]:not([aria-disabled="true"])`)
  .join(',');

/**
 * Every row, disabled rows included. The arrow keys, Home, End and type-ahead
 * visit a disabled row, so a keyboard user finds it and its reason; the row
 * stays inert.
 */
export const MENU_ROW_SELECTOR: string = [...MENU_ITEM_ROLES]
  .map(role => `[role="${role}"]`)
  .join(',');

/**
 * Boundary selector for a single menu level. A menu and its submenu flyouts
 * both use `role="menu"`, and flyouts render inline (native popover, not a
 * portal), so a nested menu's items and key events would otherwise be picked
 * up by the parent. Pass this as `useListFocus`'s `boundarySelector` so each
 * level scopes item collection and key handling to its own container.
 */
export const MENU_BOUNDARY_SELECTOR = '[role="menu"]';

/**
 * Whether a click carries a modifier or a non-primary button: on a row that
 * is a link the browser gives it a meaning of its own (a new tab, a
 * download), which the row must leave alone.
 */
export function isModifiedClick(event: {
  metaKey: boolean;
  ctrlKey: boolean;
  shiftKey: boolean;
  altKey: boolean;
  button: number;
}): boolean {
  return (
    event.metaKey ||
    event.ctrlKey ||
    event.shiftKey ||
    event.altKey ||
    event.button !== 0
  );
}

/**
 * Activate a menu row from the keyboard (Enter / Space): a synthesized click
 * that carries the key's modifiers, so a ⌘-Enter on a row that is a link opens
 * it the way a ⌘-click would. `detail` stays 0, the mark of a
 * non-pointer activation.
 */
export function activateMenuItem(
  row: HTMLElement,
  key: {metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean},
): void {
  row.dispatchEvent(
    new MouseEvent('click', {
      bubbles: true,
      cancelable: true,
      composed: true,
      metaKey: key.metaKey,
      ctrlKey: key.ctrlKey,
      shiftKey: key.shiftKey,
      altKey: key.altKey,
    }),
  );
}

/**
 * A disabled row's `onMouseDown`. The row takes focus from the keys
 * (`tabindex="-1"`), so a mouse press would otherwise focus it and light it.
 * Cancelling the press's default keeps focus where it is.
 */
export function keepDisabledRowUnfocused(event: {
  preventDefault(): void;
}): void {
  event.preventDefault();
}