♿️(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

@@ -1,5 +1,9 @@
 # @gouvfr-lasuite/ui-kit
 
+### Patch changes
+
+- ♿️(frontend) fix menu semantics and trigger ARIA for screen readers #210
+
 ## 0.20.1
 
 ### Patch Changes

src/components/dropdown-menu/DropdownMenu.tsx

@@ -7,7 +7,18 @@ import {
   SubmenuTrigger,
 } from "react-aria-components";
 import { DropdownMenuItem, DropdownMenuOption } from "./types";
-import { Fragment, PropsWithChildren, ReactNode, useId, useRef } from "react";
+import {
+  Children,
+  cloneElement,
+  Fragment,
+  isValidElement,
+  PropsWithChildren,
+  ReactElement,
+  ReactNode,
+  useEffect,
+  useId,
+  useRef,
+} from "react";
 import { MenuItemSeparator } from "../menu/types";
 import clsx from "clsx";
 
@@ -33,6 +44,42 @@ const MenuItemContent = ({ option }: { option: DropdownMenuOption }) => (
   </>
 );
 
+/**
+ * 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;
@@ -56,12 +103,55 @@ 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 menuClassName = `c__dropdown-menu${variant === "tiny" ? " c__dropdown-menu--tiny" : ""}`;
   const onOpenChangeHandler = (isOpen: boolean) => {
     onOpenChange?.(isOpen);
   };
 
+  // React Aria's Popover always adds role="dialog" on the overlay element.
+  // That's correct for dialogs, but wrong for menus: a screen reader would
+  // announce "dialogue" when opening a simple dropdown, which is confusing.
+  // The WAI-ARIA Menu Button pattern expects role="menu", not role="dialog".
+  // We use a MutationObserver to remove it as soon as Popover sets it,
+  // before the screen reader gets a chance to read it.
+  useEffect(() => {
+    const node = popoverRef.current;
+    if (!node) return;
+
+    const removeDialogRole = () => {
+      if (node.getAttribute("role") === "dialog") {
+        node.removeAttribute("role");
+      }
+      if (node.getAttribute("tabindex") === "-1") {
+        node.removeAttribute("tabindex");
+      }
+    };
+
+    removeDialogRole();
+    const observer = new MutationObserver(removeDialogRole);
+    observer.observe(node, {
+      attributes: true,
+      attributeFilter: ["role", "tabindex"],
+    });
+
+    return () => observer.disconnect();
+  }, [isOpen]);
+
+  // Inject aria-expanded / aria-haspopup / aria-controls on the actual
+  // trigger button, not the wrapper div. This tells the SR what kind of
+  // popup to expect and whether it is currently open.
+  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)) {
@@ -141,21 +231,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"