♿️(frontend) fix menu semantics and trigger ARIA for screen readers

Dropdown menu exposes proper ARIA, Popover no longer announces as dialog

Author: Ovgodd

CHANGELOG.md

@@ -67,6 +67,12 @@
 
 ## 0.20.2
 
+### Patch changes
+
+- ♿️(frontend) fix menu semantics and trigger ARIA for screen readers #210
+
+## 0.20.1
+
 ### Patch Changes
 
 - 🐛(dropdown) fix to hide icon when no icon prop is passed

src/components/dropdown-menu/DropdownMenu.tsx

@@ -6,21 +6,68 @@ import {
   Separator,
   SubmenuTrigger,
 } from "react-aria-components";
-import { MenuItemAction, MenuItemSeparator } from "../menu/types";
-import { MenuItemBody } from "../menu/MenuItemBody";
-import { DropdownMenuItem } from "./types";
-import { Fragment, PropsWithChildren, ReactNode, useId, useRef } from "react";
+import { DropdownMenuItem, DropdownMenuOption } from "./types";
+import {
+  Children,
+  cloneElement,
+  Fragment,
+  isValidElement,
+  PropsWithChildren,
+  ReactElement,
+  ReactNode,
+  useEffect,
+  useId,
+  useRef,
+} from "react";
+import { MenuItemSeparator } from "../menu/types";
 import clsx from "clsx";
 import { useCunningham } from "@gouvfr-lasuite/cunningham-react";
+import { MenuItemBody } from "../menu/MenuItemBody";
 
 const isSeparator = (item: DropdownMenuItem): item is MenuItemSeparator => {
   return "type" in item && item.type === "separator";
 };
 
-const hasChildren = (item: MenuItemAction): boolean => {
+const hasChildren = (item: DropdownMenuOption): boolean => {
   return Array.isArray(item.children) && item.children.length > 0;
 };
 
+/**
+ * Walk the React tree to find the first interactive element (button, link,
+ * or anything with onClick/onPress) and inject ARIA trigger attributes on it.
+ * This way consumers can wrap their trigger in layout divs without breaking
+ * the screen reader announcement.
+ */
+const injectAriaAttrs = (
+  node: ReactNode,
+  attrs: Record<string, unknown>,
+  state: { done: boolean },
+): ReactNode => {
+  if (state.done || !isValidElement(node)) return node;
+  const element = node as ReactElement<Record<string, unknown>>;
+
+  const isInteractive =
+    element.type === "button" ||
+    element.type === "a" ||
+    "onClick" in element.props ||
+    "onPress" in element.props;
+
+  if (isInteractive) {
+    state.done = true;
+    return cloneElement(element, attrs);
+  }
+
+  if (element.props.children) {
+    const newChildren = Children.map(
+      element.props.children as ReactNode,
+      (child) => injectAriaAttrs(child, attrs, state),
+    );
+    return cloneElement(element, {}, newChildren);
+  }
+
+  return node;
+};
+
 export type DropdownMenuProps = {
   options: DropdownMenuItem[];
   onOpenChange?: (isOpen: boolean) => void;
@@ -44,22 +91,58 @@ export const DropdownMenu = ({
   variant = "default",
 }: PropsWithChildren<DropdownMenuProps>) => {
   const id = useId();
-  const triggerRef = useRef(null);
+  const triggerRef = useRef<HTMLDivElement>(null);
+  const popoverRef = useRef<HTMLDivElement>(null);
   const { t } = useCunningham();
-  const menuClassName = `c__dropdown-menu${
-    variant === "tiny" ? " c__dropdown-menu--tiny" : ""
-  }`;
+  const menuClassName = `c__dropdown-menu${variant === "tiny" ? " c__dropdown-menu--tiny" : ""}`;
   const onOpenChangeHandler = (isOpen: boolean) => {
     onOpenChange?.(isOpen);
   };
 
-  const getAriaLabel = (option: MenuItemAction): string => {
+  const getAriaLabel = (option: DropdownMenuOption): string => {
     if (option.opensInNewWindow) {
       return option.label + t("components.menu.newWindowLabelSuffix");
     }
     return option.label;
   };
 
+  // React Aria's Popover forces role="dialog" on the overlay, but for a
+  // dropdown menu that's wrong, screen readers announce "dialogue" instead
+  // of just letting the menu speak for itself. We patch it out with a
+  // MutationObserver so it gets removed even if React Aria re-applies it.
+
+  useEffect(() => {
+    const node = popoverRef.current;
+    if (!node) return;
+
+    const removeDialogRole = () => {
+      if (node.getAttribute("role") === "dialog") {
+        node.removeAttribute("role");
+      }
+    };
+
+    removeDialogRole();
+    const observer = new MutationObserver(removeDialogRole);
+    observer.observe(node, {
+      attributes: true,
+      attributeFilter: ["role"],
+    });
+
+    return () => observer.disconnect();
+  }, [isOpen]);
+
+  // Inject aria-expanded / aria-haspopup / aria-controls on the actual
+  // trigger button, not the wrapper div
+  const childWithAria = injectAriaAttrs(
+    children,
+    {
+      "aria-expanded": isOpen,
+      "aria-haspopup": "menu" as const,
+      "aria-controls": isOpen ? `${id}-menu` : undefined,
+    },
+    { done: false },
+  );
+
   const renderMenuItems = (items: DropdownMenuItem[]) =>
     items.map((option, index) => {
       if (isSeparator(option)) {
@@ -145,21 +228,25 @@ export const DropdownMenu = ({
           e.preventDefault();
         }}
       >
-        {children}
+        {childWithAria}
       </div>
 
       <Popover
+        ref={popoverRef}
         triggerRef={triggerRef}
-        style={{
-          marginTop: "0px",
-        }}
+        style={{ marginTop: "0px" }}
         isOpen={isOpen}
         shouldFlip
         containerPadding={16}
         shouldCloseOnInteractOutside={shouldCloseOnInteractOutside}
         onOpenChange={onOpenChangeHandler}
       >
-        <Menu className={menuClassName} aria-labelledby={id} autoFocus="first">
+        <Menu
+          id={`${id}-menu`}
+          className={menuClassName}
+          aria-labelledby={id}
+          autoFocus="first"
+        >
           {topMessage && (
             <Header
               className="c__dropdown-menu-item-top-message"