Skip to content

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

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

'use client';

/**
 * @file useListFocus.ts
 * @input Uses React useCallback, useRef, useIsomorphicLayoutEffect,
 *   isRtlElement
 * @output Exports useListFocus hook for linear list keyboard navigation
 * @position Core hook; used by TabMenu for dropdown menu navigation, Toolbar
 *   for roving tabindex, ButtonGroup, ContextMenu, NavHeadingMenu, and more.
 *   Auto-detects RTL from the container's computed direction so horizontal
 *   arrow keys follow visual direction (WCAG 1.3.2).
 *
 * SYNC: When modified, update:
 * - /packages/core/src/hooks/index.ts
 * - /packages/core/src/hooks/useListFocus.doc.mjs
 * - /packages/core/src/hooks/useListFocus.test.tsx
 */

import {useCallback, useRef} from 'react';
import {isRtlElement} from './isRtlElement';
import {useIsomorphicLayoutEffect} from './useIsomorphicLayoutEffect';
import {focusForLastInput} from '../utils/focusReturn';

/**
 * Navigation orientation for a linear list.
 * - `'horizontal'`: ArrowLeft/ArrowRight move between items.
 * - `'vertical'`: ArrowUp/ArrowDown move between items.
 * - `'both'`: all four arrows move between items (in linear DOM order).
 */
export type ListFocusOrientation = 'horizontal' | 'vertical' | 'both';

/**
 * Configuration for list focus behavior
 */
export interface UseListFocusOptions {
  /**
   * Selector for focusable items within the list.
   * @default '[role="menuitem"]'
   */
  itemSelector?: string;

  /**
   * Selector identifying a list boundary — used to scope a list that contains
   * *nested* lists of the same kind (e.g. a menu with submenu flyouts).
   *
   * Overlays like submenu flyouts render inline (native popover, not a
   * portal), so a nested list's items are DOM descendants of the parent list.
   * Without scoping, the parent's `querySelectorAll` sweeps the nested items
   * into its roving order (leaving hidden items `.focus()` can't land on), and
   * key events from the nested list bubble into the parent's handler (moving
   * focus twice). When set, `useListFocus`:
   *   - counts an item as its own only when the item's nearest
   *     `boundarySelector` ancestor is this list's container, and
   *   - ignores key events whose nearest `boundarySelector` ancestor is not
   *     this list's container (i.e. they originated in a nested list).
   *
   * Typically `'[role="menu"]'` for menus. Omit for flat lists.
   */
  boundarySelector?: string;

  /**
   * Whether arrow navigation wraps around at the ends.
   * @default true
   */
  wrap?: boolean;

  /**
   * Callback when Escape key is pressed. Supplying it also makes the list
   * consume the key (`preventDefault`); without it Escape passes through to
   * the surrounding layer.
   */
  onEscape?: () => void;

  /**
   * Navigation orientation. `'horizontal'` uses ArrowLeft/ArrowRight,
   * `'vertical'` uses ArrowUp/ArrowDown, `'both'` accepts all four arrows.
   * @default 'vertical'
   */
  orientation?: ListFocusOrientation;

  /**
   * Whether Home/End jump to the first/last enabled item.
   * @default true
   */
  hasHomeEnd?: boolean;

  /**
   * Whether PageDown/PageUp page through a list that scrolls: PageDown moves
   * to the last enabled item fully visible in the container, and pressed
   * there again one viewport further; PageUp is the mirror. Neither wraps.
   * In a list that does not scroll they act as End/Home.
   * @default false
   */
  hasPaging?: boolean;

  /**
   * Roving-tabindex ownership. When true, the hook manages a single tab stop
   * across the items: exactly one enabled item carries `tabindex="0"` and the
   * rest `tabindex="-1"`. The tab stop is stamped on mount and repaired
   * whenever items mount/unmount or toggle disabled, and moves with arrow
   * navigation. Attach the returned {@link UseListFocusReturn.handleFocus} to
   * the container's `onFocus` to keep the stop in sync after clicks or
   * programmatic focus.
   *
   * When false (the default), the hook only *moves* focus (`.focus()`) and
   * never touches `tabindex` — the caller owns tab-stop management.
   * @default false
   */
  hasRovingTabIndex?: boolean;

  /**
   * When true, arrow keys are not stolen from a nested text input/textarea
   * whose caret is not at the boundary in the direction of travel (or that has
   * a non-collapsed selection), and are never stolen from a nested
   * `contenteditable` (rich-text editor / chat composer). This preserves
   * normal caret movement while the user is editing inline within the list
   * (e.g. a toolbar search field or composer).
   * @default false
   */
  hasCaretGuard?: boolean;
}

/**
 * Options only Core components pass; this module's internal export, not
 * re-exported from `hooks/index.ts`, so not public API.
 */
export interface InternalListFocusOptions extends UseListFocusOptions {
  /**
   * With `hasRovingTabIndex`, the owner places the one tab stop: returns the
   * elements that share it, the stop first, enabled or not. After every
   * commit and every keyboard move the hook gives the first `tabindex="0"`
   * and the rest `tabindex="-1"`. For a group whose stop follows its own
   * state, such as a radio group whose checked item keeps the stop even when
   * that item, or the whole group, is disabled.
   * Unset (the default): the first enabled item holds the stop, kept across
   * renders, and no item holds it while every item is disabled.
   */
  tabStopOrder?: (list: HTMLElement) => ReadonlyArray<HTMLElement>;
  /**
   * Moves focus with the modality of the last input: after a pointer press a
   * focused item shows no keyboard ring, and after a key press it does. Use it
   * for a list whose items draw the ring and that opens from a pointer, such as
   * a context menu. Unset (the default): a plain `focus()`.
   */
  focusFollowsLastInput?: boolean;
  /**
   * The arrow keys, Home, End and the Page keys visit a disabled item as they
   * visit any other item. The item must take focus (`tabindex="-1"`). Use it in
   * a menu, where a disabled row stays discoverable and inert. `focusFirst` and
   * `focusLast` still land on an enabled item, so an open from the keyboard
   * lands on a row that acts. Unset (the default): navigation skips disabled
   * items.
   */
  reachesDisabledItems?: boolean;
}

/**
 * Return type for useListFocus hook
 */
export interface UseListFocusReturn<T extends HTMLElement = HTMLElement> {
  /**
   * Ref to attach to the list container element.
   */
  listRef: React.RefObject<T | null>;

  /**
   * Key down handler to attach to the list container.
   */
  handleKeyDown: (e: React.KeyboardEvent) => void;

  /**
   * Focus handler to attach to the container's `onFocus`. Keeps the roving tab
   * stop in sync when `hasRovingTabIndex` is enabled; a no-op otherwise, so it is
   * always safe to attach.
   */
  handleFocus: (e: React.FocusEvent) => void;

  /**
   * Focus a specific item by index.
   */
  focusItem: (index: number) => void;

  /**
   * Focus the first enabled item. Returns true when an item was focused.
   */
  focusFirst: () => boolean;

  /**
   * Focus the last enabled item. Returns true when an item was focused.
   */
  focusLast: () => boolean;

  /**
   * Whether a key event belongs to this list level (vs. a nested list that
   * shares the same `boundarySelector`). Useful when a consumer wraps
   * `handleKeyDown` with extra behavior (Enter/Space activation, typeahead)
   * and must apply it only to events this level owns. Always true when no
   * `boundarySelector` is configured.
   */
  ownsEvent: (e: React.KeyboardEvent) => boolean;

  /**
   * The current, in-DOM-order list of this level's focusable items (already
   * scoped by `boundarySelector`). Exposed so consumers can build typeahead
   * targets from the same source of truth as roving focus, rather than
   * re-querying and re-filtering.
   */
  getItems: () => HTMLElement[];
}

// Text-editing inputs whose caret must not be hijacked by arrow navigation.
const TEXT_INPUT_TYPES = new Set([
  'text',
  'search',
  'url',
  'tel',
  'email',
  'password',
  'number',
]);

/**
 * Whether `el` sits under a `hidden` or `inert` ancestor that is itself inside
 * `listEl` (the list's own state is not consulted). Such a row cannot take
 * focus — a drilled-in menu hides the rows a view replaced — so it
 * leaves the roving order and the typeahead.
 */
function isHiddenWithin(el: HTMLElement, listEl: HTMLElement): boolean {
  const hidden = el.parentElement?.closest<HTMLElement>('[hidden],[inert]');
  return hidden != null && hidden !== listEl && listEl.contains(hidden);
}

/**
 * The nearest `contenteditable` root for `el`, or null when `el` is not inside
 * an editable region. Prefers the browser's `isContentEditable` property and
 * falls back to the closest `[contenteditable]` ancestor whose value is not
 * `"false"` (so environments without `isContentEditable` still work).
 */
function getContentEditableRoot(el: HTMLElement): HTMLElement | null {
  if (el.isContentEditable) {
    return el;
  }
  const candidate = el.closest<HTMLElement>('[contenteditable]');
  if (candidate && candidate.getAttribute('contenteditable') !== 'false') {
    return candidate;
  }
  return null;
}

/**
 * Whether an arrow/Home/End key should be left to the browser because the
 * event target is a text-editing element whose caret is not yet at the boundary
 * in the direction of travel (or a selection is present). Returns true when the
 * list should NOT steal the key.
 *
 * Covers three editing surfaces:
 * - `<textarea>` and text-type `<input>` — use `selectionStart`/`selectionEnd`
 *   to steal only at the boundary in the travel direction.
 * - `contenteditable` (rich-text editor / chat composer) — precise caret
 *   boundary detection in an arbitrary editable subtree is fragile, so we err
 *   on the side of never hijacking an active editor: defer on every caret key
 *   whenever focus is inside a non-empty contenteditable. (An empty editable
 *   has nothing to caret through, so navigation may proceed.)
 */
function shouldDeferToCaret(target: EventTarget | null, key: string): boolean {
  if (!(target instanceof HTMLElement)) {
    return false;
  }

  // contenteditable (covers an element with contenteditable="" / "true" and
  // descendants that inherit it). `isContentEditable` is the reliable property
  // in the browser; fall back to the nearest `contenteditable` ancestor for
  // environments (e.g. jsdom) that don't implement the property.
  const editableRoot = getContentEditableRoot(target);
  if (editableRoot) {
    const selection =
      typeof window !== 'undefined' ? window.getSelection() : null;
    // A non-collapsed selection means the user is selecting text — never steal.
    if (selection && selection.rangeCount > 0 && !selection.isCollapsed) {
      return true;
    }
    // Collapsed caret (or no selection API): defer whenever the editor has
    // content, so arrow keys stay with the active rich-text editor.
    return (editableRoot.textContent ?? '').length > 0;
  }

  const isTextarea = target.tagName === 'TEXTAREA';
  const isTextInput =
    target.tagName === 'INPUT' &&
    TEXT_INPUT_TYPES.has((target as HTMLInputElement).type);
  if (!isTextarea && !isTextInput) {
    return false;
  }
  const input = target as HTMLInputElement | HTMLTextAreaElement;
  const {selectionStart, selectionEnd, value} = input;
  // A non-collapsed selection means the user is selecting text — never steal.
  if (selectionStart !== selectionEnd) {
    return true;
  }
  // number inputs report null selection; treat as "always defer" for caret keys.
  if (selectionStart == null) {
    return true;
  }
  if (key === 'ArrowLeft' || key === 'ArrowUp' || key === 'Home') {
    // Defer unless the caret is at the very start.
    return selectionStart > 0;
  }
  if (key === 'ArrowRight' || key === 'ArrowDown' || key === 'End') {
    // Defer unless the caret is at the very end.
    return selectionStart < value.length;
  }
  return false;
}

/**
 * Hook for managing keyboard navigation within a linear list.
 *
 * Implements WAI-ARIA menu/listbox/toolbar pattern:
 * - ArrowDown/ArrowRight: Move to next item (wraps to first)
 * - ArrowUp/ArrowLeft: Move to previous item (wraps to last)
 * - Home: Move to first item
 * - End: Move to last item
 * - Escape: runs `onEscape` and consumes the key. With no `onEscape` the key
 *   is left alone, so a surrounding layer can still dismiss on it.
 *
 * By default the hook only *moves* focus and leaves `tabindex` management to
 * the caller. Opt into {@link UseListFocusOptions.hasRovingTabIndex} for a hook
 * that owns a single tab stop (roving tabindex) across the items — stamping and
 * repairing it as items mount/unmount or toggle disabled — for toolbars,
 * segmented controls, tab strips, and similar composite widgets.
 *
 * @example
 * ```
 * const {listRef, handleKeyDown} = useListFocus({
 *   onEscape: () => layer.hide(),
 * });
 *
 * <div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
 *   {items.map(item => <div role="menuitem" tabIndex={0}>{item}</div>)}
 * </div>
 * ```
 *
 * Roving-tabindex composite (e.g. a toolbar):
 *
 * @example
 * ```
 * const {listRef, handleKeyDown, handleFocus} = useListFocus<HTMLDivElement>({
 *   itemSelector: 'button, input, [tabindex]',
 *   orientation: 'horizontal',
 *   hasRovingTabIndex: true,
 *   hasCaretGuard: true,
 * });
 *
 * <div ref={listRef} role="toolbar" onKeyDown={handleKeyDown} onFocus={handleFocus}>
 *   {children}
 * </div>
 * ```
 */
export function useListFocus<T extends HTMLElement = HTMLElement>(
  options: UseListFocusOptions = {},
): UseListFocusReturn<T> {
  return useInternalListFocus<T>(options);
}

function isDisabledItem(el: HTMLElement): boolean {
  return (
    el.getAttribute('aria-disabled') === 'true' ||
    (el as HTMLButtonElement).disabled === true ||
    el.hasAttribute('disabled')
  );
}

/**
 * A `tabStopOrder` for a group whose disabled items stay focusable, such as a
 * row of disabled Buttons. The group keeps one Tab stop while every item is
 * disabled: the item that holds the stop, else the first enabled item, else
 * the first item. With an enabled item it places the stop as the default does.
 */
export function oneTabStopAmong(
  itemSelector: string,
  boundarySelector: string,
): (list: HTMLElement) => HTMLElement[] {
  return list => {
    const items = Array.from(
      list.querySelectorAll<HTMLElement>(itemSelector),
    ).filter(
      el => !isHiddenWithin(el, list) && el.closest(boundarySelector) === list,
    );
    const enabled = items.filter(el => !isDisabledItem(el));
    const candidates = enabled.length > 0 ? enabled : items;
    const stop =
      candidates.find(el => el.getAttribute('tabindex') === '0') ??
      candidates[0];
    return stop == null ? items : [stop, ...items.filter(el => el !== stop)];
  };
}

/**
 * {@link useListFocus} with the Core-only {@link InternalListFocusOptions}.
 * Not re-exported from `hooks/index.ts`.
 */
export function useInternalListFocus<T extends HTMLElement = HTMLElement>(
  options: InternalListFocusOptions = {},
): UseListFocusReturn<T> {
  const {
    itemSelector = '[role="menuitem"]',
    boundarySelector,
    wrap = true,
    onEscape,
    orientation = 'vertical',
    hasHomeEnd = true,
    hasPaging = false,
    hasRovingTabIndex = false,
    tabStopOrder,
    hasCaretGuard = false,
    focusFollowsLastInput = false,
    reachesDisabledItems = false,
  } = options;

  const listRef = useRef<T>(null);

  /**
   * Whether an item is disabled and therefore cannot receive DOM focus.
   * A `.focus()` call on such an element silently no-ops, so navigation must
   * skip these to avoid freezing on a disabled item (menus-4, navigation-5).
   */
  const isItemDisabled = isDisabledItem;

  /**
   * Get all focusable items in the list.
   */
  const getItems = useCallback((): HTMLElement[] => {
    const listEl = listRef.current;
    if (!listEl) {
      return [];
    }
    const matched = Array.from(
      listEl.querySelectorAll<HTMLElement>(itemSelector),
    ).filter(el => !isHiddenWithin(el, listEl));
    // When a boundary is set, keep only items that belong to THIS list level —
    // i.e. whose nearest boundary ancestor is our own container. This excludes
    // items inside nested lists (e.g. inline submenu flyouts) that would
    // otherwise be swept in by querySelectorAll.
    if (!boundarySelector) {
      return matched;
    }
    return matched.filter(el => el.closest(boundarySelector) === listEl);
  }, [itemSelector, boundarySelector]);

  /**
   * Whether a key event belongs to this list level rather than a nested list.
   * With a boundary set, an event that originated inside a nested boundary
   * (e.g. a submenu flyout) has bubbled up to us and must be ignored so we
   * don't double-handle navigation. Without a boundary, every event is ours.
   */
  const ownsEvent = useCallback(
    (e: React.KeyboardEvent): boolean => {
      const listEl = listRef.current;
      if (!listEl || !boundarySelector) {
        return true;
      }
      const target = e.target as HTMLElement | null;
      if (!target) {
        return true;
      }
      return target.closest(boundarySelector) === listEl;
    },
    [boundarySelector],
  );

  /**
   * Find the next item index from `start` that `isSkipped` does not pass over
   * (by default, the next enabled item), moving by `step`, optionally
   * wrapping. Returns -1 when no such item exists in range. Skipping
   * disabled items here (rather than relying on the selector) keeps navigation
   * from stalling on an item whose `.focus()` silently no-ops.
   */
  const findItemIndex = useCallback(
    (
      items: HTMLElement[],
      start: number,
      step: 1 | -1,
      shouldWrap: boolean,
      isSkipped: (el: HTMLElement) => boolean = isItemDisabled,
    ): number => {
      const count = items.length;
      if (count === 0) {
        return -1;
      }
      let index = start;
      for (let i = 0; i < count; i++) {
        if (index < 0 || index >= count) {
          if (!shouldWrap) {
            return -1;
          }
          index = (index + count) % count;
        }
        const item = items[index];
        if (item && !isSkipped(item)) {
          return index;
        }
        index += step;
      }
      return -1;
    },
    [isItemDisabled],
  );

  const isSkippedByKeys = useCallback(
    (el: HTMLElement): boolean => !reachesDisabledItems && isItemDisabled(el),
    [reachesDisabledItems, isItemDisabled],
  );

  /**
   * Get the currently focused item index.
   */
  const getCurrentIndex = useCallback((): number => {
    const items = getItems();
    const active = document.activeElement;
    return items.findIndex(item => item === active || item.contains(active));
  }, [getItems]);

  // --- Roving tabindex ownership (opt-in via `hasRovingTabIndex`) -------------

  /**
   * Set `tabindex` on an item, but only when it differs (avoids redundant DOM
   * writes). Uses setAttribute so the value reflects even for elements (like
   * `<button>`) whose default tabIndex is already 0.
   */
  const setTabIndex = useCallback((el: HTMLElement, value: 0 | -1) => {
    if (el.getAttribute('tabindex') !== String(value)) {
      el.setAttribute('tabindex', String(value));
    }
  }, []);

  /**
   * Stamp the roving tab stop: exactly one enabled item is tabbable (0), the
   * rest are -1. Prefer keeping the currently-tabbable item if it is still
   * enabled; otherwise promote the first enabled item (tab-stop repair).
   */
  const syncTabStops = useCallback(() => {
    const listEl = listRef.current;
    if (listEl != null && tabStopOrder != null) {
      const [stop, ...others] = tabStopOrder(listEl);
      if (stop != null) {
        setTabIndex(stop, 0);
      }
      for (const el of others) {
        setTabIndex(el, -1);
      }
      return;
    }
    const items = getItems();
    const enabled = items.filter(el => !isItemDisabled(el));
    if (enabled.length === 0) {
      return;
    }
    const current = enabled.find(el => el.getAttribute('tabindex') === '0');
    const tabbable = current ?? enabled[0];
    for (const el of items) {
      setTabIndex(el, el === tabbable ? 0 : -1);
    }
  }, [getItems, isItemDisabled, setTabIndex, tabStopOrder]);

  // Keep the tab stop valid across renders (items added/removed, disabled
  // toggled). Runs after every commit but only when roving tabindex is on.
  useIsomorphicLayoutEffect(() => {
    if (hasRovingTabIndex) {
      syncTabStops();
    }
  });

  /**
   * Move focus to `items[index]`. When roving tabindex is enabled, also move
   * the tab stop so `index` becomes the sole tabbable item.
   */
  const focusIndex = useCallback(
    (items: HTMLElement[], index: number) => {
      const target = items[index];
      if (!target) {
        return;
      }
      if (hasRovingTabIndex) {
        // An owner-placed stop may sit on an element outside `items`, such as
        // a disabled checked radio; it gives way to the target too.
        const listEl = listRef.current;
        const sharing =
          listEl != null && tabStopOrder != null
            ? [...items, ...tabStopOrder(listEl)]
            : items;
        for (const el of sharing) {
          setTabIndex(el, el === target ? 0 : -1);
        }
      }
      if (focusFollowsLastInput) {
        focusForLastInput(target);
      } else {
        target.focus();
      }
    },
    [hasRovingTabIndex, setTabIndex, focusFollowsLastInput, tabStopOrder],
  );

  /**
   * Focus an item by index, clamping to valid range.
   */
  const focusItem = useCallback(
    (index: number) => {
      const items = getItems();
      if (items.length === 0) {
        return;
      }
      const clampedIndex = Math.max(0, Math.min(index, items.length - 1));
      focusIndex(items, clampedIndex);
    },
    [getItems, focusIndex],
  );

  /**
   * Focus the first enabled item. Returns true when an item was focused.
   */
  const focusFirst = useCallback((): boolean => {
    const items = getItems();
    const index = findItemIndex(items, 0, 1, false);
    if (index !== -1) {
      focusIndex(items, index);
      return true;
    }
    return false;
  }, [getItems, findItemIndex, focusIndex]);

  /**
   * Focus the last enabled item. Returns true when an item was focused.
   */
  const focusLast = useCallback((): boolean => {
    const items = getItems();
    const index = findItemIndex(items, items.length - 1, -1, false);
    if (index !== -1) {
      focusIndex(items, index);
      return true;
    }
    return false;
  }, [getItems, findItemIndex, focusIndex]);

  /**
   * PageDown / PageUp: move to the last / first enabled item fully
   * visible in the scrolling container. Pressed there again, scroll one
   * viewport further and land on the last / first item then visible. Never
   * wraps; at the end of the list it stays on the last enabled item.
   */
  const focusPage = useCallback(
    (direction: 1 | -1) => {
      const container = listRef.current;
      const items = getItems();
      if (!container || items.length === 0) {
        return;
      }
      const currentIndex = getCurrentIndex();
      const enabledIndices = items
        .map((item, index) => (isSkippedByKeys(item) ? -1 : index))
        .filter(index => index !== -1);
      if (enabledIndices.length === 0) {
        return;
      }
      const edgeVisible = (): number => {
        const bounds = container.getBoundingClientRect();
        const visible = enabledIndices.filter(index => {
          const rect = items[index].getBoundingClientRect();
          return rect.top >= bounds.top - 1 && rect.bottom <= bounds.bottom + 1;
        });
        if (visible.length === 0) {
          return -1;
        }
        return direction === 1 ? visible[visible.length - 1] : visible[0];
      };
      const isAhead = (index: number): boolean =>
        currentIndex === -1 ||
        (direction === 1 ? index > currentIndex : index < currentIndex);
      if (currentIndex === -1 && direction === -1) {
        focusFirst();
        return;
      }
      let target = edgeVisible();
      if (target === -1 || !isAhead(target)) {
        // Already at the visible edge: one viewport further.
        const before = container.scrollTop;
        container.scrollTop = before + direction * container.clientHeight;
        target = edgeVisible();
        if (target === -1 || !isAhead(target)) {
          // No usable geometry (or nothing moved): step by the number of rows
          // a viewport shows, never wrapping.
          const pageSize = Math.max(
            1,
            enabledIndices.filter(index => {
              const bounds = container.getBoundingClientRect();
              const rect = items[index].getBoundingClientRect();
              return (
                rect.height > 0 &&
                rect.top >= bounds.top - 1 &&
                rect.bottom <= bounds.bottom + 1
              );
            }).length,
          );
          const position = enabledIndices.indexOf(currentIndex);
          const from =
            position === -1
              ? direction === 1
                ? -1
                : enabledIndices.length
              : position;
          const next = Math.max(
            0,
            Math.min(enabledIndices.length - 1, from + direction * pageSize),
          );
          target = enabledIndices[next];
        }
      }
      if (target !== -1 && target !== currentIndex) {
        focusIndex(items, target);
      }
    },
    [getItems, getCurrentIndex, isSkippedByKeys, focusIndex, focusFirst],
  );

  /**
   * Keep the roving stop pointing at whatever ended up focused (e.g. a click
   * or programmatic focus) so the next Tab behaves correctly. No-op unless
   * roving tabindex is enabled.
   */
  const handleFocus = useCallback(() => {
    if (hasRovingTabIndex) {
      syncTabStops();
    }
  }, [hasRovingTabIndex, syncTabStops]);

  /**
   * Handle keyboard navigation.
   */
  const handleKeyDown = useCallback(
    (e: React.KeyboardEvent) => {
      // Let browser/OS shortcut chords (Ctrl/Cmd/Alt + key) through untouched.
      if (e.ctrlKey || e.metaKey || e.altKey) {
        return;
      }

      // Ignore events that bubbled up from a nested list (e.g. a submenu
      // flyout, which renders inline inside this container). That level owns
      // and already handled them; re-handling here would move focus twice.
      if (!ownsEvent(e)) {
        return;
      }

      // Escape is handled regardless of orientation, but only *consumed* when
      // a handler asked for it: a list with no dismissal to perform must leave
      // the key to whatever host layer does have one, and those defer to
      // `defaultPrevented` (see `useFocusTrap`) or to the native popover.
      if (e.key === 'Escape') {
        if (onEscape) {
          e.preventDefault();
          onEscape();
        }
        return;
      }

      const horizontal = orientation === 'horizontal' || orientation === 'both';
      const vertical = orientation === 'vertical' || orientation === 'both';

      // Resolve which keys advance vs retreat, honoring RTL for horizontal.
      // Direction is resolved lazily — getComputedStyle runs only when a
      // horizontal arrow key is actually pressed (SSR-safe, no layout thrash
      // on unrelated keys).
      const nextKeys: string[] = [];
      const prevKeys: string[] = [];
      if (horizontal) {
        const rtl =
          e.key === 'ArrowLeft' || e.key === 'ArrowRight'
            ? isRtlElement(listRef.current)
            : false;
        nextKeys.push(rtl ? 'ArrowLeft' : 'ArrowRight');
        prevKeys.push(rtl ? 'ArrowRight' : 'ArrowLeft');
      }
      if (vertical) {
        nextKeys.push('ArrowDown');
        prevKeys.push('ArrowUp');
      }

      const isNext = nextKeys.includes(e.key);
      const isPrev = prevKeys.includes(e.key);
      const isHome = hasHomeEnd && e.key === 'Home';
      const isEnd = hasHomeEnd && e.key === 'End';
      const isPageDown = hasPaging && e.key === 'PageDown';
      const isPageUp = hasPaging && e.key === 'PageUp';

      if (!isNext && !isPrev && !isHome && !isEnd && !isPageDown && !isPageUp) {
        return;
      }

      // Never hijack a caret key from a nested text input mid-line. Check both
      // the React event target and the actual focused element (events may
      // bubble up to the container).
      if (
        hasCaretGuard &&
        (shouldDeferToCaret(e.target, e.key) ||
          shouldDeferToCaret(document.activeElement, e.key))
      ) {
        return;
      }

      const currentIndex = getCurrentIndex();
      const items = getItems();
      let nextFrom = currentIndex === -1 ? 0 : currentIndex + 1;
      let prevFrom = currentIndex === -1 ? items.length - 1 : currentIndex - 1;
      // Focus on an owner-placed stop outside `items`, such as a disabled
      // checked radio, moves to the enabled item beside it in document order.
      const active = document.activeElement;
      if (
        currentIndex === -1 &&
        tabStopOrder != null &&
        active != null &&
        listRef.current?.contains(active)
      ) {
        const after = items.findIndex(
          item =>
            (active.compareDocumentPosition(item) &
              Node.DOCUMENT_POSITION_FOLLOWING) !==
            0,
        );
        nextFrom = after === -1 ? items.length : after;
        prevFrom = nextFrom - 1;
      }

      if (isPageDown) {
        focusPage(1);
      } else if (isPageUp) {
        focusPage(-1);
      } else {
        let target: number;
        if (isNext) {
          target = findItemIndex(items, nextFrom, 1, wrap, isSkippedByKeys);
        } else if (isPrev) {
          target = findItemIndex(items, prevFrom, -1, wrap, isSkippedByKeys);
        } else if (isHome) {
          target = findItemIndex(items, 0, 1, false, isSkippedByKeys);
        } else {
          target = findItemIndex(
            items,
            items.length - 1,
            -1,
            false,
            isSkippedByKeys,
          );
        }
        if (target !== -1) {
          focusIndex(items, target);
        }
      }

      e.preventDefault();
    },
    [
      getCurrentIndex,
      getItems,
      wrap,
      orientation,
      hasHomeEnd,
      hasPaging,
      hasCaretGuard,
      findItemIndex,
      isSkippedByKeys,
      focusIndex,
      focusPage,
      onEscape,
      ownsEvent,
      tabStopOrder,
    ],
  );

  return {
    listRef,
    handleKeyDown,
    handleFocus,
    focusItem,
    focusFirst,
    focusLast,
    ownsEvent,
    getItems,
  };
}