@astryxdesign/core 0.7.1-canary.ff40b78 → 0.7.1

package/src/DropdownMenu/DropdownMenu.tsx

@@ -114,6 +114,53 @@ const MENU_TRIGGER_OPEN_BACKGROUND = `linear-gradient(${colorVars['--color-overl
  * 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 [];
@@ -148,8 +195,9 @@ function isInsideHiddenWrapper(
 }
 
 /**
- * Move focus to a region control. Reports whether focus actually arrived, so a
- * caller can close the menu instead of stranding focus on the page.
+ * 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();
@@ -551,6 +599,17 @@ function visibleText(element: Element): string {
   for (const hidden of copy.querySelectorAll('[aria-hidden="true"]')) {
     hidden.remove();
   }
+  // An icon-only control is named by its image's alt, an inner aria-label, or
+  // an svg title rather than by text, so those count as its contents too.
+  for (const named of copy.querySelectorAll('img[alt], [aria-label]')) {
+    const name =
+      named.getAttribute(named.tagName === 'IMG' ? 'alt' : 'aria-label') ?? '';
+    named.replaceWith(copy.ownerDocument.createTextNode(` ${name} `));
+  }
+  for (const svg of copy.querySelectorAll('svg')) {
+    const title = svg.querySelector('title')?.textContent ?? '';
+    svg.replaceWith(copy.ownerDocument.createTextNode(` ${title} `));
+  }
   return (copy.textContent ?? '').replace(/\s+/g, ' ').trim();
 }
 
@@ -580,6 +639,24 @@ function readAccessibleName(element: HTMLElement | null): string | undefined {
   if (label) {
     return label;
   }
+  // A form control is named by its own <label>s; an input button by its value.
+  const labels =
+    'labels' in element
+      ? Array.from((element as HTMLInputElement).labels ?? [])
+      : [];
+  const labelText = labels.map(visibleText).join(' ').trim();
+  if (labelText !== '') {
+    return labelText;
+  }
+  if (
+    element instanceof HTMLInputElement &&
+    ['button', 'submit', 'reset'].includes(element.getAttribute('type') ?? '')
+  ) {
+    const value = element.value.trim();
+    if (value !== '') {
+      return value;
+    }
+  }
   const text = visibleText(element);
   if (text !== '') {
     return text;
@@ -716,7 +793,15 @@ function DropdownMenuBottomSheet({
       openModalityRef.current = 'keyboard';
     }
   };
-  const handleSheetTriggerClick = () => {
+  const handleSheetTriggerClick = (event: React.MouseEvent<HTMLElement>) => {
+    // A caller-rendered trigger that is natively or aria-disabled must not
+    // open the sheet; the default Button already refuses its own click.
+    // The DOM check covers the built-in Button too (it renders aria-disabled
+    // when focusable-disabled); a caller's own enabled control wins over a
+    // `button.isDisabled` left on the props.
+    if (event.currentTarget.matches(':disabled, [aria-disabled="true"]')) {
+      return;
+    }
     onClick?.();
     setOpen(!isOpen);
   };
@@ -954,6 +1039,16 @@ function DropdownMenuPopover({
   // ArrowUp opens with the LAST enabled row highlighted.
   const focusLastOnOpenRef = useRef(false);
 
+  // Synchronizes the dialog's name from the custom trigger's DOM, an external
+  // system React does not own: the rendered control's accessible name is only
+  // readable once it mounts. With a header or footer the dialog is named like
+  // the menu, so that name is needed before the first open, not only at it.
+  useIsomorphicLayoutEffect(() => {
+    if (renderTrigger != null && hasRegions && triggerName == null) {
+      setTriggerName(readAccessibleName(buttonRef.current));
+    }
+  }, [renderTrigger, hasRegions, triggerName]);
+
   const handleLayerShow = useCallback(() => {
     acceptedOpenRef.current = true;
     resetFocusReturn();
@@ -970,15 +1065,38 @@ function DropdownMenuPopover({
     }
   }, [isControlled, onClick, onOpenChange, renderTrigger, resetFocusReturn]);
 
+  // The menu's name: the dialog around it with a header or footer, and the
+  // Back row of a drilled-in view ("Back to <this>"), both read it.
+  // The design system's button names the menu by its label. A custom trigger
+  // names it by reference (or the caller's `aria-label` does), so that name
+  // is read off the control as the menu opens.
+  const callerMenuLabel = rest['aria-label'];
+  const menuLabel =
+    renderTrigger != null
+      ? typeof callerMenuLabel === 'string' && callerMenuLabel.trim() !== ''
+        ? callerMenuLabel
+        : triggerName
+      : typeof button.label === 'string'
+        ? button.label
+        : undefined;
+
   const popover = usePopover({
     onHide: handleLayerHide,
     onShow: handleLayerShow,
     hasLightDismiss: true,
     hasCloseButton: false,
     hasAutoFocus: false,
-    // The popup's own role="menu" is the exposed semantics; wrapping it in a
-    // modal dialog would announce an unnamed dialog around the menu.
-    role: 'none',
+    // Without a header or footer the popup's own role="menu" is the exposed
+    // semantics; a dialog around it would announce an extra container. With
+    // either, the popover holds controls that are not menu items, so it is a
+    // modal dialog named like the menu, with the menu inside it. A custom
+    // trigger's name is read off the control once it mounts; until then, or
+    // when the control exposes no readable name, the dialog takes the default
+    // menu label, so it is never unnamed and never loses its role.
+    role: hasRegions ? 'dialog' : 'none',
+    dialogLabel: hasRegions
+      ? (menuLabel ?? t(DEFAULT_BUTTON_I18N_KEY))
+      : undefined,
   });
 
   const closeMenu = useCallback(() => {
@@ -1077,6 +1195,55 @@ function DropdownMenuPopover({
     });
   }, [popover.isOpen, focusFirst, focusLast, listRef]);
 
+  // With a header or footer the popover is a modal 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. The key is handled here in full, so the
+  // popover's own focus trap, which listens on the document, never reads it a
+  // 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,
+      );
+      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],
+  );
+
   // Extend useListFocus with Enter/Space activation + typeahead
   const listKeyDown = useCallback(
     (e: React.KeyboardEvent) => {
@@ -1087,18 +1254,7 @@ function DropdownMenuPopover({
         // itself as the key bubbled up, and the root moves focus on as Tab
         // from one of its own rows would.
         if (e.key === 'Tab' && hasRegions) {
-          const region = e.shiftKey ? headerRef.current : footerRef.current;
-          const tabbables = tabbablesIn(region);
-          e.stopPropagation();
-          const target = e.shiftKey
-            ? tabbables[tabbables.length - 1]
-            : tabbables[0];
-          if (target != null) {
-            e.preventDefault();
-          }
-          if (target == null || !focusRegionControl(target)) {
-            closeMenu();
-          }
+          moveDialogTab(e, true);
         }
         return;
       }
@@ -1120,30 +1276,15 @@ function DropdownMenuPopover({
         }
         return;
       }
-      // APG menu-button pattern: Tab closes the menu. Menu items are
-      // tabIndex={-1} so the focus trap has nothing trappable and Tab would
-      // otherwise leak into the page while the menu stayed open (menus-5).
-      // Do NOT preventDefault — closing restores focus to the trigger, and the
-      // browser's default Tab then continues from there to the next element.
-      // A header or footer with something Tab can reach in that direction
-      // takes the Tab instead, and the menu stays open.
+      // With a header or footer the popover is a dialog and Tab wraps inside
+      // it. Without either, the APG menu-button pattern: Tab closes the menu.
+      // Menu items are tabIndex={-1} so the focus trap has nothing trappable
+      // and Tab would otherwise leak into the page while the menu stayed open
+      // (menus-5). Do NOT preventDefault — closing restores focus to the
+      // trigger, and the browser's default Tab then continues from there.
       if (e.key === 'Tab') {
-        const region = e.shiftKey ? headerRef.current : footerRef.current;
-        const tabbables = tabbablesIn(region);
-        if (tabbables.length > 0) {
-          // From a row, the browser's Shift+Tab would stop on the menu element
-          // itself — the row's ancestor and a Tab stop — before reaching the
-          // header. The menu is one stop, so go straight to the header.
-          if (e.shiftKey && e.target !== listRef.current) {
-            e.preventDefault();
-            // The popover's focus trap listens on the document and would read
-            // this same Shift+Tab against the field just focused — the trap's
-            // first element — and wrap to the footer. This key is handled.
-            e.stopPropagation();
-            if (!focusRegionControl(tabbables[tabbables.length - 1])) {
-              closeMenu();
-            }
-          }
+        if (hasRegions) {
+          moveDialogTab(e);
           return;
         }
         closeMenu();
@@ -1156,33 +1297,24 @@ function DropdownMenuPopover({
       }
       listNavKeyDown(e);
     },
-    [listNavKeyDown, closeMenu, typeahead, ownsEvent, listRef, hasRegions],
+    [
+      listNavKeyDown,
+      closeMenu,
+      typeahead,
+      ownsEvent,
+      hasRegions,
+      moveDialogTab,
+    ],
   );
 
-  // Tab past the last control of the footer, or Shift+Tab before the first
-  // control of the header, leaves the menu as Tab from its rows does: the
-  // menu closes, focus returns to the trigger, and the browser's own Tab
-  // continues from there. Between the regions, Tab moves through the menu
-  // as one stop.
+  // Tab from a header or footer control moves through the same dialog cycle.
   const handleRegionKeyDown = useCallback(
     (e: React.KeyboardEvent<HTMLDivElement>) => {
-      if (e.key !== 'Tab') {
-        return;
-      }
-      const tabbables = tabbablesIn(e.currentTarget);
-      const isHeader = e.currentTarget === headerRef.current;
-      const exit = isHeader
-        ? e.shiftKey
-          ? tabbables[0]
-          : undefined
-        : e.shiftKey
-          ? undefined
-          : tabbables[tabbables.length - 1];
-      if (exit != null && exit === document.activeElement) {
-        closeMenu();
+      if (e.key === 'Tab') {
+        moveDialogTab(e);
       }
     },
-    [closeMenu],
+    [moveDialogTab],
   );
 
   const openAndFocus = useCallback(
@@ -1190,6 +1322,15 @@ function DropdownMenuPopover({
       modality: 'keyboard' | 'pointer' = 'keyboard',
       notifyClick = false,
     ): boolean => {
+      // An unavailable trigger never opens the menu. Button keeps an
+      // aria-disabled trigger focusable for its tooltip and swallows only
+      // Enter and Space, so the arrow keys, a press and a click would still
+      // arrive here; a custom trigger may be natively disabled instead.
+      if (
+        buttonRef.current?.matches(':disabled, [aria-disabled="true"]') === true
+      ) {
+        return false;
+      }
       acceptedOpenRef.current = false;
       notifyClickOnShowRef.current = notifyClick;
       pendingControlledOpenRef.current = isControlled;
@@ -1328,7 +1469,11 @@ function DropdownMenuPopover({
             return;
           }
           focusLastOnOpenRef.current = e.key === 'ArrowUp';
-          openAndFocus();
+          if (!openAndFocus()) {
+            // A refused open (disabled trigger) must not leave ArrowUp's
+            // "land on the last row" armed for a later open.
+            focusLastOnOpenRef.current = false;
+          }
         }
         return;
       }
@@ -1368,20 +1513,6 @@ function DropdownMenuPopover({
 
   // The drill-in view stack for sub-menus on a phone.
   const {drillIn, wrapContent} = useMenuDrillIn(isOpen);
-  // The name a drilled-in view's Back row returns to: the menu's own name.
-  // The design system's button names the menu by its label. A custom trigger
-  // names it by reference (or the caller's `aria-label` does), so that name
-  // is read off the control as the menu opens.
-  const callerMenuLabel = rest['aria-label'];
-  const menuLabel =
-    renderTrigger != null
-      ? typeof callerMenuLabel === 'string' && callerMenuLabel.trim() !== ''
-        ? callerMenuLabel
-        : triggerName
-      : typeof button.label === 'string'
-        ? button.label
-        : undefined;
-
   const resolvedMaxHeight = menuMaxHeight == null ? null : `${menuMaxHeight}px`;
   // Context for compound items
   const contextValue = useMemo<DropdownMenuContextValue>(
@@ -1442,9 +1573,9 @@ function DropdownMenuPopover({
     // keeps the browser from drawing one after pointer input (see
     // handleLayerHide), so its focus needs no bookkeeping here.
     onFocus: () => {},
-    'aria-haspopup': 'menu',
+    'aria-haspopup': hasRegions ? 'dialog' : 'menu',
     'aria-expanded': isOpen,
-    'aria-controls': menuId,
+    'aria-controls': hasRegions ? popover.id : menuId,
   };
 
   return (
@@ -1492,9 +1623,9 @@ function DropdownMenuPopover({
             button.onFocus?.(event);
             onFocusReturnTargetFocus();
           }}
-          aria-haspopup="menu"
+          aria-haspopup={hasRegions ? 'dialog' : 'menu'}
           aria-expanded={isOpen}
-          aria-controls={menuId}
+          aria-controls={hasRegions ? popover.id : menuId}
           data-testid={testId}
         />
       )}

package/src/DropdownMenu/DropdownMenuCheckboxItem.doc.mjs

@@ -1,5 +1,27 @@
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
+/** @type {import('@astryxdesign/cli/authoring').ComponentAnatomyElement[]} */
+const anatomy = [
+  {
+    name: 'Checkable row',
+    required: true,
+    description:
+      'The menuitemcheckbox root that owns the accessible name, checked state, focus, and activation.',
+  },
+  {
+    name: 'Label/content',
+    required: true,
+    description:
+      'Caller content laid out by Item: the required label plus optional description, icon, and end content.',
+  },
+  {
+    name: 'Checkbox marker',
+    required: true,
+    description:
+      'Decorative shared Indicator chrome that visualizes checked and disabled state without adding a second control.',
+  },
+];
+
 /** @type {import('@astryxdesign/cli/authoring').ComponentDoc} */
 
 export const docs = {
@@ -9,6 +31,11 @@ export const docs = {
   isHiddenFromOverview: true,
   description:
     'A checkable menu item (role="menuitemcheckbox") that toggles an independent boolean. Use for on/off options inside a DropdownMenu; for a one-of-N choice use DropdownMenuRadioGroup.',
+  usage: {
+    anatomy,
+    description:
+      'An independently checkable option inside DropdownMenu. The row owns menuitemcheckbox semantics while the shared Indicator supplies decorative checkbox paint.',
+  },
   props: [
     {
       name: 'label',
@@ -43,7 +70,7 @@ export const docs = {
       type: 'boolean',
       default: 'false',
       description:
-        'Whether the item is disabled. Disabled items stay focusable (via aria-disabled) so they remain discoverable by keyboard and assistive technology, but activation is blocked.',
+        'Whether the item is disabled. Disabled items expose aria-disabled, block activation, and are currently skipped by DropdownMenu arrow-key navigation.',
     },
     {
       name: 'hasCloseOnSelect',
@@ -65,6 +92,14 @@ export const docs = {
         'Content to render after the label and description, such as a keyboard shortcut hint or badge.',
     },
   ],
+  theming: {
+    targets: [
+      {
+        className: 'astryx-dropdown-menu-item',
+        visualProps: ['size'],
+      },
+    ],
+  },
 };
 
 export const docsZh = {
@@ -98,7 +133,8 @@ export const docsDense = {
     icon: 'icon before label',
     value: 'checked state (controlled, w/ onChange)',
     onChange: 'fired w/ next checked state on toggle',
-    isDisabled: 'disabled; stays focusable via aria-disabled',
+    isDisabled:
+      'disabled; aria-disabled, no activation; current menu focus skips the row',
     hasCloseOnSelect: 'close menu on toggle (default false, stays open)',
     ref: 'forwarded to the row root (the role="menuitemcheckbox" element)',
     endContent: 'content after label+description',

package/src/DropdownMenu/DropdownMenuCheckboxItem.tsx

@@ -4,7 +4,7 @@
 
 /**
  * @file DropdownMenuCheckboxItem.tsx
- * @input React, stylex, Item + CheckboxInput + DropdownMenu context + tokens from core
+ * @input React, stylex, Item + Indicator registry + DropdownMenu context + tokens from core
  * @output DropdownMenuCheckboxItem — a standalone checkable menu item.
  * @position Sub-component; used inside DropdownMenu.
  *
@@ -26,7 +26,12 @@
  * mobile.
  */
 
-import {useCallback, type PointerEvent, type ReactNode} from 'react';
+import {
+  useCallback,
+  type MouseEvent,
+  type PointerEvent,
+  type ReactNode,
+} from 'react';
 import * as stylex from '@stylexjs/stylex';
 import {renderIconSlot, type IconType} from '../Icon';
 import {useIndicator} from '../Indicator';
@@ -34,7 +39,7 @@ import {Item} from '../Item';
 import {useDropdownMenuContext} from './DropdownMenuContext';
 import {focusMenuItemOnHover} from './menuItemHover';
 import {colorVars, spacingVars} from '../theme/tokens.stylex';
-import {mergeProps, themeProps} from '../utils';
+import {composeEventHandlers, mergeProps, themeProps} from '../utils';
 import type {BaseProps} from '../BaseProps';
 
 const styles = stylex.create({
@@ -58,8 +63,8 @@ const styles = stylex.create({
   },
   // Rendered in Item's `marker` slot as a raw flex child, so `order` moves it
   // relative to the label within the row. On touch it moves to the inline-end.
-  // `aria-hidden` + `inert` + pointer-events:none keep the composed CheckboxInput
-  // decorative: it adds no accessible name, and clicks fall through to the row,
+  // `aria-hidden` + `inert` + pointer-events:none keep the composed checkbox
+  // indicator decorative: it adds no accessible name, and clicks fall through to the row,
   // which owns the role and activation.
   // Placement of the marker within the row. The indicator draws its own box
   // (size, fill, border) — these are only the rules the MENU owns: where the
@@ -105,9 +110,8 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
    */
   onChange?: (checked: boolean) => void;
   /**
-   * Whether the item is disabled. Disabled items stay focusable (via
-   * `aria-disabled`) so they remain discoverable by keyboard and assistive
-   * technology, but activation is blocked.
+   * Whether the item is disabled. Disabled items expose `aria-disabled`, block
+   * activation, and are currently skipped by DropdownMenu arrow-key navigation.
    * @default false
    */
   isDisabled?: boolean;
@@ -132,6 +136,9 @@ export interface DropdownMenuCheckboxItemProps extends Omit<
  *
  * Must be used inside a DropdownMenu. Toggles an independent boolean; for a
  * one-of-N choice use DropdownMenuRadioGroup + DropdownMenuRadioItem instead.
+ * Consumer click and pointer-move handlers compose after the row's own
+ * activation and hover-focus behavior; disabled activation stops before the
+ * consumer click handler.
  *
  * @example
  * ```
@@ -157,6 +164,8 @@ export function DropdownMenuCheckboxItem({
   xstyle,
   className,
   style,
+  onClick,
+  onPointerMove,
   ...rest
 }: DropdownMenuCheckboxItemProps) {
   const ctx = useDropdownMenuContext();
@@ -164,15 +173,20 @@ export function DropdownMenuCheckboxItem({
   const controlSize = menuSize === 'sm' ? 'sm' : 'md';
   const CheckboxControl = useIndicator('checkbox');
 
-  const handleClick = useCallback(() => {
-    if (isDisabled) {
-      return;
-    }
-    onChange?.(!value);
-    if (hasCloseOnSelect) {
-      ctx?.closeMenu();
-    }
-  }, [isDisabled, onChange, value, hasCloseOnSelect, ctx]);
+  const handleClick = useCallback(
+    (event: MouseEvent) => {
+      if (isDisabled) {
+        event.preventDefault();
+        return;
+      }
+      onChange?.(!value);
+      if (hasCloseOnSelect) {
+        ctx?.closeMenu();
+      }
+      onClick?.(event as MouseEvent<HTMLElement>);
+    },
+    [isDisabled, onChange, value, hasCloseOnSelect, ctx, onClick],
+  );
 
   const handlePointerMove = useCallback(
     (e: PointerEvent<HTMLElement>) => focusMenuItemOnHover(e, isDisabled),
@@ -185,7 +199,7 @@ export function DropdownMenuCheckboxItem({
       role="menuitemcheckbox"
       aria-checked={value}
       tabIndex={isDisabled ? undefined : -1}
-      onPointerMove={handlePointerMove}
+      onPointerMove={composeEventHandlers(handlePointerMove, onPointerMove)}
       marker={
         // No wrapper, and no menu-specific theme target: the shared
         // `astryx-checkbox-indicator` target is already on this element (main