Skip to content

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

TypeScript

refactor(DropdownMenu): the header and footer Tab walk moves to a module of its own (#7737)

Christopher Chedeau684ca57bdc04
diff --git a/.changeset/dropdown-menu-region-stops.md b/.changeset/dropdown-menu-region-stops.md
new file mode 100644
index 0000000000..d201b42dcd
--- /dev/null
+++ b/.changeset/dropdown-menu-region-stops.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/core': patch
+---
+
+[chore] Internal groundwork for a sub-menu's header and footer: `DropdownMenu`'s Tab walk through its header, menu and footer moves, unchanged, into a module of its own, so another menu level with regions can share it. `DropdownMenu`'s behavior does not change.
+
+@vjeux
diff --git a/packages/core/src/DropdownMenu/DropdownMenu.tsx b/packages/core/src/DropdownMenu/DropdownMenu.tsx
index afb803deb4..1a474d1167 100644
--- a/packages/core/src/DropdownMenu/DropdownMenu.tsx
+++ b/packages/core/src/DropdownMenu/DropdownMenu.tsx
@@ -72,7 +72,7 @@ import {useFocusReturnVisibility} from '../hooks/useFocusReturnVisibility';
import {focusForLastInput} from '../utils/focusReturn';
import {useMenuOverflow} from './useMenuOverflow';
import {MenuRegionsContext} from './menuRegionsContext';
-import {getFocusableElements} from '../hooks/useFocusTrap';
+import {moveRegionsTab} from './menuRegionStops';
import {useDevWarning} from '../hooks/useDevWarning';
import {useMenuDrillIn} from './useMenuDrillIn';
import {resolveMenuWidth} from './menuWidth';
@@ -112,102 +112,6 @@ const MENU_MAX_BLOCK_SIZE = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBloc
const MENU_MAX_BLOCK_SIZE_FALLBACK = `min(${MENU_BLOCK_CAP}, ${layerViewportInset.maxBlockSizeFallback})`;
const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overlay-pressed']}, ${colorVars['--color-overlay-pressed']})`;
-/**
- * The elements Tab reaches inside a header or footer region, in order. Hidden
- * controls (`hidden`, `display: none`, `visibility: hidden`, inert or
- * aria-hidden subtrees) are not reachable, judged by the popover focus trap's
- * own test so the two never disagree about where Tab can go.
- */
-/**
- * Collapse each named radio group to the one Tab stop a browser gives it: the
- * focused radio, else the checked one, else the first radio moving forward or
- * the last moving backward. The stop takes the group's first position.
- */
-function collapseRadioGroups(
- elements: HTMLElement[],
- active: Element | null,
- isBackward: boolean,
-): HTMLElement[] {
- const groups = new Map<string, HTMLInputElement[]>();
- const groupKey = (el: HTMLElement): string | null =>
- el instanceof HTMLInputElement &&
- el.getAttribute('type') === 'radio' &&
- el.name !== ''
- ? `${el.form?.id ?? ''}\u0000${el.name}`
- : null;
- for (const el of elements) {
- const key = groupKey(el);
- if (key != null) {
- const members = groups.get(key) ?? [];
- members.push(el as HTMLInputElement);
- groups.set(key, members);
- }
- }
- const placed = new Set<string>();
- const result: HTMLElement[] = [];
- for (const el of elements) {
- const key = groupKey(el);
- if (key == null) {
- result.push(el);
- continue;
- }
- if (placed.has(key)) {
- continue;
- }
- placed.add(key);
- const members = groups.get(key) ?? [];
- const stop =
- members.find(radio => radio === active) ??
- members.find(radio => radio.checked) ??
- (isBackward ? members[members.length - 1] : members[0]);
- result.push(stop);
- }
- return result;
-}
-
-function tabbablesIn(region: HTMLElement | null): HTMLElement[] {
- if (region == null) {
- return [];
- }
- return getFocusableElements(region).filter(
- element => element.tabIndex >= 0 && !isInsideHiddenWrapper(element, region),
- );
-}
-
-/**
- * Whether a `display: none` ancestor between the element and its region hides
- * it — a control in a wrapper hidden at some widths, say. The trap's test reads
- * only the element's own display.
- */
-function isInsideHiddenWrapper(
- element: HTMLElement,
- region: HTMLElement,
-): boolean {
- if (typeof window === 'undefined' || !window.getComputedStyle) {
- return false;
- }
- for (
- let node = element.parentElement;
- node != null && node !== region.parentElement;
- node = node.parentElement
- ) {
- if (window.getComputedStyle(node).display === 'none') {
- return true;
- }
- }
- return false;
-}
-
-/**
- * Move focus to a Tab stop in the dialog. Reports whether focus actually
- * arrived, so a caller can fall back to the menu instead of stranding focus on
- * the page.
- */
-function focusRegionControl(element: HTMLElement): boolean {
- element.focus();
- return element.ownerDocument.activeElement === element;
-}
-
const styles = stylex.create({
triggerOpen: {
backgroundImage: MENU_TRIGGER_OPEN_BACKGROUND,
@@ -1271,44 +1175,13 @@ function DropdownMenuPopover({
// second time.
const moveDialogTab = useCallback(
(e: React.KeyboardEvent, isFromFlyout = false) => {
- const menu = listRef.current;
- if (menu == null) {
- return;
- }
- e.preventDefault();
- e.stopPropagation();
- // A named radio group is one stop, as the browser's own Tab order has it.
- const cycle = collapseRadioGroups(
- [
- ...tabbablesIn(headerRef.current),
- menu,
- ...tabbablesIn(footerRef.current),
- ],
- document.activeElement,
- e.shiftKey,
+ moveRegionsTab(
+ e,
+ listRef.current,
+ headerRef.current,
+ footerRef.current,
+ isFromFlyout,
);
- if (cycle.length === 1) {
- // Nothing else to reach: focus stays in the menu. From a flyout that
- // has just closed itself, that is the menu's own stop.
- if (isFromFlyout) {
- menu.focus();
- }
- return;
- }
- const active = document.activeElement;
- const menuIndex = cycle.indexOf(menu);
- // A row, or a row of an open flyout, counts as the menu's stop.
- let index = menu.contains(active)
- ? menuIndex
- : cycle.findIndex(el => el === active || el.contains(active));
- if (index < 0) {
- index = menuIndex;
- }
- const step = e.shiftKey ? -1 : 1;
- const next = cycle[(index + step + cycle.length) % cycle.length];
- if (!focusRegionControl(next)) {
- menu.focus();
- }
},
[listRef],
);
diff --git a/packages/core/src/DropdownMenu/menuRegionStops.ts b/packages/core/src/DropdownMenu/menuRegionStops.ts
new file mode 100644
index 0000000000..5dd7d2ace5
--- /dev/null
+++ b/packages/core/src/DropdownMenu/menuRegionStops.ts
@@ -0,0 +1,167 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file menuRegionStops.ts
+ * @input The focus trap's own reachability test (getFocusableElements)
+ * @output `tabbablesIn`, `focusRegionControl`, `moveRegionsTab`: the Tab stops
+ * of a header or footer region and the walk through a menu with regions,
+ * with a named radio group as one stop
+ * @position Internal; DropdownMenu's walk through its header and footer, in a
+ * module of its own so another menu level with regions can share it.
+ *
+ * A menu with a header or footer is a dialog: Tab and Shift+Tab walk the
+ * header's controls, the menu as one stop, then the footer's controls, and
+ * wrap at either end.
+ */
+import type React from 'react';
+import {getFocusableElements} from '../hooks/useFocusTrap';
+
+/**
+ * The elements Tab reaches inside a header or footer region, in order. Hidden
+ * controls (`hidden`, `display: none`, `visibility: hidden`, inert or
+ * aria-hidden subtrees) are not reachable, judged by the popover focus trap's
+ * own test so the two never disagree about where Tab can go.
+ */
+export function tabbablesIn(region: HTMLElement | null): HTMLElement[] {
+ if (region == null) {
+ return [];
+ }
+ return getFocusableElements(region).filter(
+ element => element.tabIndex >= 0 && !isInsideHiddenWrapper(element, region),
+ );
+}
+
+/**
+ * Whether a `display: none` ancestor between the element and its region hides
+ * it — a control in a wrapper hidden at some widths, say. The trap's test reads
+ * only the element's own display.
+ */
+function isInsideHiddenWrapper(
+ element: HTMLElement,
+ region: HTMLElement,
+): boolean {
+ if (typeof window === 'undefined' || !window.getComputedStyle) {
+ return false;
+ }
+ for (
+ let node = element.parentElement;
+ node != null && node !== region.parentElement;
+ node = node.parentElement
+ ) {
+ if (window.getComputedStyle(node).display === 'none') {
+ return true;
+ }
+ }
+ return false;
+}
+
+/**
+ * Collapse each named radio group to the one Tab stop a browser gives it: the
+ * focused radio, else the checked one, else the first radio moving forward or
+ * the last moving backward. The stop takes the group's first position.
+ */
+function collapseRadioGroups(
+ elements: HTMLElement[],
+ active: Element | null,
+ isBackward: boolean,
+): HTMLElement[] {
+ const groups = new Map<string, HTMLInputElement[]>();
+ const groupKey = (el: HTMLElement): string | null =>
+ el instanceof HTMLInputElement &&
+ el.getAttribute('type') === 'radio' &&
+ el.name !== ''
+ ? `${el.form?.id ?? ''}\u0000${el.name}`
+ : null;
+ for (const el of elements) {
+ const key = groupKey(el);
+ if (key != null) {
+ const members = groups.get(key) ?? [];
+ members.push(el as HTMLInputElement);
+ groups.set(key, members);
+ }
+ }
+ const placed = new Set<string>();
+ const result: HTMLElement[] = [];
+ for (const el of elements) {
+ const key = groupKey(el);
+ if (key == null) {
+ result.push(el);
+ continue;
+ }
+ if (placed.has(key)) {
+ continue;
+ }
+ placed.add(key);
+ const members = groups.get(key) ?? [];
+ const stop =
+ members.find(radio => radio === active) ??
+ members.find(radio => radio.checked) ??
+ (isBackward ? members[members.length - 1] : members[0]);
+ result.push(stop);
+ }
+ return result;
+}
+
+/**
+ * Move focus to a Tab stop in the dialog. Reports whether focus actually
+ * arrived, so a caller can fall back to the menu instead of stranding focus on
+ * the page.
+ */
+export function focusRegionControl(element: HTMLElement): boolean {
+ element.focus();
+ return element.ownerDocument.activeElement === element;
+}
+
+/**
+ * Handle Tab in a menu with a header or footer: move to the next stop of the
+ * header's controls, the menu as one stop, then the footer's controls,
+ * wrapping at either end. The key is handled in full, so a document-level
+ * focus trap never reads it a second time. A row, or a row of an open
+ * flyout below this menu, counts as the menu's stop; with no other stop,
+ * focus stays in the menu (`isFromFlyout`: a flyout that has just closed
+ * itself hands the focus back to the menu's own stop).
+ */
+export function moveRegionsTab(
+ event: React.KeyboardEvent,
+ menu: HTMLElement | null,
+ header: HTMLElement | null,
+ footer: HTMLElement | null,
+ isFromFlyout = false,
+): void {
+ if (menu == null) {
+ return;
+ }
+ event.preventDefault();
+ event.stopPropagation();
+ const active = document.activeElement;
+ // A named radio group is one stop, as the browser's own Tab order has it.
+ const cycle = collapseRadioGroups(
+ [...tabbablesIn(header), menu, ...tabbablesIn(footer)],
+ active,
+ event.shiftKey,
+ );
+ if (cycle.length === 1) {
+ // Nothing else to reach: focus stays in the menu. From a flyout that has
+ // just closed itself, that is the menu's own stop.
+ if (isFromFlyout) {
+ menu.focus();
+ }
+ return;
+ }
+ const menuIndex = cycle.indexOf(menu);
+ let index = menu.contains(active)
+ ? menuIndex
+ : cycle.findIndex(
+ element => element === active || element.contains(active),
+ );
+ if (index < 0) {
+ index = menuIndex;
+ }
+ const step = event.shiftKey ? -1 : 1;
+ const next = cycle[(index + step + cycle.length) % cycle.length];
+ if (!focusRegionControl(next)) {
+ menu.focus();
+ }
+}