@ds-mo/ui 0.2.4 → 0.3.0

package/src/components/Menu/Menu.tsx

@@ -1,4 +1,4 @@
-import React, { useState, useEffect, useLayoutEffect, useRef, useMemo } from 'react';
+import React, { useState, useEffect, useLayoutEffect, useRef, useMemo, useCallback } from 'react';
 import { createPortal } from 'react-dom';
 import { Text } from '@/components/Text';
 import { Surface } from '@/components/Surface';
@@ -53,6 +53,16 @@ export interface MenuProps {
   matchAnchorWidth?: boolean;
   matchAnchorWidthOffset?: number;
   usePortal?: boolean;
+  /** Container role + item role semantics. Defaults to `menu` (items are buttons with menuitem* roles, keyboard nav handled internally). `listbox` makes items render as `option` with `aria-selected`, with keyboard nav handled by the consumer via `activeIndex`. */
+  role?: 'menu' | 'listbox';
+  /** DOM id for the popup container — required when an external combobox references it via `aria-controls`/`aria-activedescendant`. */
+  id?: string;
+  /** Accessible label for the popup container. Defaults to `'Menu'` for menu role; omitted for listbox (let consumer provide via aria-labelledby on the combobox). */
+  ariaLabel?: string;
+  /** Active descendant index for listbox keyboard nav — highlights one option visually without moving DOM focus. */
+  activeIndex?: number;
+  /** Builds the DOM id for option `index`. Required in listbox mode if `aria-activedescendant` is used externally. */
+  getOptionId?: (index: number) => string;
 }
 
 export const Menu: React.FC<MenuProps> = ({
@@ -73,16 +83,25 @@ export const Menu: React.FC<MenuProps> = ({
   matchAnchorWidth = false,
   matchAnchorWidthOffset = 0,
   usePortal = true,
+  role = 'menu',
+  id,
+  ariaLabel,
+  activeIndex,
+  getOptionId,
 }) => {
+  const isListbox = role === 'listbox';
   const [isClosing, setIsClosing] = useState(false);
   const [shouldRender, setShouldRender] = useState(isOpen);
   const [isPositionReady, setIsPositionReady] = useState(false);
   const [position, setPosition] = useState<{ x: number; y: number }>({ x: 0, y: 0 });
   const [menuSize, setMenuSize] = useState<{ width: number; height: number }>({ width: 0, height: 0 });
   const [anchorSize, setAnchorSize] = useState<{ width: number; height: number }>({ width: 0, height: 0 });
+  const [focusedIndex, setFocusedIndex] = useState(0);
   const positionCalculatedRef = useRef(false);
   const menuRef = useRef<HTMLDivElement>(null);
   const lastSectionsRef = useRef<MenuSection[]>([]);
+  const itemRefs = useRef<Array<HTMLButtonElement | null>>([]);
+  const focusedOnOpenRef = useRef(false);
 
   const menuSections: MenuSection[] = sections || (items ? [{ items }] : []);
 
@@ -92,6 +111,14 @@ export const Menu: React.FC<MenuProps> = ({
   }
   const sectionsToRender = isClosing ? lastSectionsRef.current : menuSections;
 
+  const flatItems = useMemo(() => {
+    const list: MenuItemData[] = [];
+    sectionsToRender.forEach((section) => {
+      section.items.forEach((it) => list.push(it));
+    });
+    return list;
+  }, [sectionsToRender]);
+
   useEffect(() => {
     if (isOpen) {
       setShouldRender(true);
@@ -178,6 +205,15 @@ export const Menu: React.FC<MenuProps> = ({
     };
   }, [isOpen, shouldRender, anchorRef, side, align, sideOffset, alignOffset, sideOffsetToken, alignOffsetToken, menuSize.width, menuSize.height, menuSections.length, matchAnchorWidthOffset]);
 
+  const closeAndRestoreFocus = useCallback(() => {
+    const active = document.activeElement as HTMLElement | null;
+    const focusInside = !!(active && menuRef.current?.contains(active));
+    if (focusInside && anchorRef.current) {
+      anchorRef.current.focus();
+    }
+    onClose();
+  }, [onClose, anchorRef]);
+
   useEffect(() => {
     if (!isOpen || !shouldRender) return;
     const handleClickOutside = (event: MouseEvent) => {
@@ -192,38 +228,138 @@ export const Menu: React.FC<MenuProps> = ({
 
   useEffect(() => {
     if (!isOpen) return;
-    const handleEscape = (e: KeyboardEvent) => { if (e.key === 'Escape') onClose(); };
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        if (isListbox) {
+          onClose();
+        } else {
+          e.preventDefault();
+          closeAndRestoreFocus();
+        }
+      }
+    };
     document.addEventListener('keydown', handleEscape);
     return () => document.removeEventListener('keydown', handleEscape);
-  }, [isOpen, onClose]);
+  }, [isOpen, isListbox, onClose, closeAndRestoreFocus]);
+
+  useEffect(() => {
+    if (!isOpen) {
+      focusedOnOpenRef.current = false;
+      return;
+    }
+    if (isListbox || !isPositionReady || focusedOnOpenRef.current) return;
+    const firstEnabled = flatItems.findIndex((it) => !it.isInactive);
+    const targetIdx = firstEnabled >= 0 ? firstEnabled : 0;
+    setFocusedIndex(targetIdx);
+    itemRefs.current[targetIdx]?.focus();
+    focusedOnOpenRef.current = true;
+  }, [isOpen, isListbox, isPositionReady, flatItems]);
+
+  const moveFocus = useCallback((idx: number) => {
+    setFocusedIndex(idx);
+    itemRefs.current[idx]?.focus();
+  }, []);
+
+  const handleKeyDown = useCallback((e: React.KeyboardEvent<HTMLDivElement>) => {
+    if (isListbox || !flatItems.length) return;
+    const enabled: number[] = [];
+    flatItems.forEach((it, i) => { if (!it.isInactive) enabled.push(i); });
+    if (!enabled.length) return;
+    const currentPos = enabled.indexOf(focusedIndex);
+    const safePos = currentPos < 0 ? 0 : currentPos;
+
+    switch (e.key) {
+      case 'ArrowDown': {
+        e.preventDefault();
+        e.stopPropagation();
+        moveFocus(enabled[(safePos + 1) % enabled.length]);
+        break;
+      }
+      case 'ArrowUp': {
+        e.preventDefault();
+        e.stopPropagation();
+        moveFocus(enabled[(safePos - 1 + enabled.length) % enabled.length]);
+        break;
+      }
+      case 'Home': {
+        e.preventDefault();
+        e.stopPropagation();
+        moveFocus(enabled[0]);
+        break;
+      }
+      case 'End': {
+        e.preventDefault();
+        e.stopPropagation();
+        moveFocus(enabled[enabled.length - 1]);
+        break;
+      }
+      case 'Tab': {
+        e.preventDefault();
+        closeAndRestoreFocus();
+        break;
+      }
+    }
+  }, [isListbox, flatItems, focusedIndex, moveFocus, closeAndRestoreFocus]);
 
   if (!shouldRender || sectionsToRender.length === 0) return null;
 
-  const renderMenuItem = (item: MenuItemData, index: number) => {
+  const setItemRef = (flatIndex: number) => (el: HTMLButtonElement | null) => {
+    itemRefs.current[flatIndex] = el;
+  };
+
+  const handleItemFocus = (flatIndex: number) => () => {
+    setFocusedIndex(flatIndex);
+  };
+
+  const handleItemActivate = (item: MenuItemData) => {
+    if (item.isInactive) return;
+    item.onClick();
+    if (item.keepOpenOnClick) return;
+    if (isListbox) {
+      onClose();
+    } else {
+      closeAndRestoreFocus();
+    }
+  };
+
+  const renderMenuItem = (item: MenuItemData, key: number, flatIndex: number) => {
     if (item.isDestructive) {
+      const tabIndexValue = isListbox ? -1 : (focusedIndex === flatIndex ? 0 : -1);
       return (
         <DestructiveMenuItem
-          key={index}
+          key={key}
+          ref={setItemRef(flatIndex)}
           label={item.label}
           subtext={item.subtext}
           holdDuration={item.holdDuration ?? 4000}
-          onClick={() => { item.onClick(); if (!item.keepOpenOnClick) onClose(); }}
+          onClick={() => { item.onClick(); if (!item.keepOpenOnClick) { if (isListbox) onClose(); else closeAndRestoreFocus(); } }}
+          tabIndex={tabIndexValue}
+          onFocus={handleItemFocus(flatIndex)}
         />
       );
     }
+    const optionId = isListbox && getOptionId ? getOptionId(flatIndex) : undefined;
+    const tabIndexValue = isListbox ? -1 : (focusedIndex === flatIndex ? 0 : -1);
     return (
       <MenuItemComponent
-        key={index}
+        key={key}
+        ref={setItemRef(flatIndex)}
         icon={item.icon}
         label={item.label}
         subtext={item.subtext}
-        onClick={() => { if (!item.isInactive) { item.onClick(); if (!item.keepOpenOnClick) onClose(); } }}
+        onClick={() => handleItemActivate(item)}
         isSelected={item.isSelected}
         isInactive={item.isInactive}
         intent={item.intent}
         showToggle={item.showToggle}
         toggleValue={item.toggleValue}
         selectionStyle={item.selectionStyle}
+        role={isListbox ? 'option' : undefined}
+        id={optionId}
+        ariaSelected={isListbox ? !!item.isSelected : undefined}
+        isActive={isListbox && activeIndex === flatIndex}
+        tabIndex={tabIndexValue}
+        onFocus={handleItemFocus(flatIndex)}
       />
     );
   };
@@ -241,8 +377,19 @@ export const Menu: React.FC<MenuProps> = ({
     ...(maxWidth ? { maxWidth } : {}),
   };
 
+  let flatIndexCounter = 0;
+  const containerLabel = ariaLabel ?? (isListbox ? undefined : 'Menu');
   const menuContent = (
-    <div ref={menuRef} className={`${styles.menuContainer} ${isClosing ? styles.closing : ''}`} style={menuStyle} role="menu" aria-label="Menu">
+    <div
+      ref={menuRef}
+      id={id}
+      className={`${styles.menuContainer} ${isClosing ? styles.closing : ''}`}
+      style={menuStyle}
+      role={role}
+      aria-label={containerLabel}
+      aria-orientation="vertical"
+      onKeyDown={handleKeyDown}
+    >
       {sectionsToRender.map((section, sectionIndex) => (
         <Surface
           key={sectionIndex}
@@ -250,13 +397,15 @@ export const Menu: React.FC<MenuProps> = ({
           className={styles.menuSection}
           edge={sectionIndex < sectionsToRender.length - 1 ? 'bottom' : undefined}
           elevation="none"
+          role={section.header ? 'group' : undefined}
+          aria-label={section.header}
         >
           {section.header && (
-            <div className={styles.sectionHeader}>
+            <div className={styles.sectionHeader} aria-hidden="true">
               <Text variant="text-body-small-emphasis" as="span" className={styles.sectionLabel}>{section.header}</Text>
             </div>
           )}
-          {section.items.map((item, itemIndex) => renderMenuItem(item, itemIndex))}
+          {section.items.map((item, itemIndex) => renderMenuItem(item, itemIndex, flatIndexCounter++))}
         </Surface>
       ))}
     </div>

package/src/components/Menu/MenuItem.module.css

@@ -41,6 +41,8 @@
 
 .menuItemInactive { opacity: 0.5; cursor: default; pointer-events: none; }
 
+.menuItemActive { background-color: var(--color-interaction-hover); }
+
 .toggleSuffix { flex-shrink: 0; display: flex; align-items: center; }
 
 .toggle {

package/src/components/Menu/MenuItem.tsx

@@ -21,6 +21,18 @@ export interface MenuItemProps {
   showTrailingChevron?: boolean;
   checkIcon?: IconComponent;
   chevronIcon?: IconComponent;
+  /** Override the implicit role. Defaults derive from menu context: `menuitem`, `menuitemcheckbox` (showToggle), or `menuitemradio` (radio selectionStyle). Pass `'option'` for listbox usage. */
+  role?: string;
+  /** Element id — required when used as an `option` referenced by `aria-activedescendant`. */
+  id?: string;
+  /** Maps to `aria-selected`. Used when role is `option`. */
+  ariaSelected?: boolean;
+  /** Visual highlight for keyboard "active" cursor (separate from selection state). */
+  isActive?: boolean;
+  /** Override default tabIndex (e.g. -1 for listbox options driven by aria-activedescendant). */
+  tabIndex?: number;
+  onKeyDown?: (e: React.KeyboardEvent<HTMLButtonElement>) => void;
+  onFocus?: (e: React.FocusEvent<HTMLButtonElement>) => void;
 }
 
 export const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
@@ -39,11 +51,34 @@ export const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
     showTrailingChevron = false,
     checkIcon: CheckIcon,
     chevronIcon: ChevronIcon,
+    role,
+    id,
+    ariaSelected,
+    isActive = false,
+    tabIndex,
+    onKeyDown,
+    onFocus,
   }, ref) => {
     const useRadioStyle = selectionStyle === 'radio';
     const noOverlay = selectionStyle === 'noOverlay' || useRadioStyle;
     const showSelectedOverlay = isSelected && !noOverlay;
 
+    const resolvedRole = role ?? (
+      showToggle ? 'menuitemcheckbox'
+        : useRadioStyle ? 'menuitemradio'
+          : 'menuitem'
+    );
+
+    const ariaCheckedValue: boolean | undefined = role
+      ? undefined
+      : resolvedRole === 'menuitemcheckbox'
+        ? !!toggleValue
+        : resolvedRole === 'menuitemradio'
+          ? !!isSelected
+          : undefined;
+
+    const ariaSelectedValue: boolean | undefined = role && ariaSelected !== undefined ? ariaSelected : undefined;
+
     return (
       <Surface
         ref={ref as React.Ref<HTMLElement>}
@@ -51,13 +86,21 @@ export const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
         interactive={!isInactive}
         selected={showSelectedOverlay}
         radius="sm"
-        className={`${styles.menuItem} ${isSelected ? styles.menuItemSelected : ''} ${isInactive ? styles.menuItemInactive : ''} ${intent === 'negative' ? styles.menuItemNegative : ''} ${labelColor === 'tertiary' ? styles.menuItemLabelTertiary : ''}`}
+        className={`${styles.menuItem} ${isSelected ? styles.menuItemSelected : ''} ${isInactive ? styles.menuItemInactive : ''} ${intent === 'negative' ? styles.menuItemNegative : ''} ${labelColor === 'tertiary' ? styles.menuItemLabelTertiary : ''} ${isActive ? styles.menuItemActive : ''}`}
         onClick={onClick}
         type="button"
         inactive={isInactive}
+        role={resolvedRole}
+        id={id}
+        aria-checked={ariaCheckedValue}
+        aria-selected={ariaSelectedValue}
+        aria-disabled={isInactive || undefined}
+        tabIndex={tabIndex}
+        onKeyDown={onKeyDown}
+        onFocus={onFocus}
       >
         {Icon && (
-          <div className={styles.iconPrefix}>
+          <div className={styles.iconPrefix} aria-hidden="true">
             <Icon size={20} />
           </div>
         )}
@@ -77,19 +120,19 @@ export const MenuItem = forwardRef<HTMLButtonElement, MenuItemProps>(
           )}
         </div>
         {showToggle && (
-          <div className={styles.toggleSuffix}>
+          <div className={styles.toggleSuffix} aria-hidden="true">
             <div className={`${styles.toggle} ${toggleValue ? styles.toggleOn : ''}`}>
               <div className={styles.toggleThumb} />
             </div>
           </div>
         )}
         {useRadioStyle && isSelected && CheckIcon && (
-          <div className={styles.checkSuffix}>
+          <div className={styles.checkSuffix} aria-hidden="true">
             <CheckIcon size={20} />
           </div>
         )}
         {showTrailingChevron && ChevronIcon && (
-          <div className={styles.chevronSuffix}>
+          <div className={styles.chevronSuffix} aria-hidden="true">
             <ChevronIcon size={20} />
           </div>
         )}

package/src/components/Modal/Modal.tsx

@@ -14,6 +14,27 @@ const WIDTH_MAP: Record<ModalWidth, string> = {
 
 const CLOSE_ANIMATION_MS = 220;
 
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'iframe',
+  'object',
+  'embed',
+  '[contenteditable="true"]',
+  '[tabindex]:not([tabindex="-1"])',
+].join(',');
+
+const getFocusableElements = (root: HTMLElement): HTMLElement[] => {
+  const nodes = root.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+  return Array.from(nodes).filter(
+    (el) => !el.hasAttribute('disabled') && el.getAttribute('aria-hidden') !== 'true'
+  );
+};
+
 export interface ModalProps {
   isOpen: boolean;
   onClose: () => void;
@@ -23,6 +44,7 @@ export interface ModalProps {
   footer?: React.ReactNode;
   width?: ModalWidth | string;
   bodyClassName?: string;
+  initialFocus?: React.RefObject<HTMLElement>;
 }
 
 export const Modal: React.FC<ModalProps> = ({
@@ -34,9 +56,12 @@ export const Modal: React.FC<ModalProps> = ({
   footer,
   width = 'md',
   bodyClassName,
+  initialFocus,
 }) => {
   const dialogRef = useRef<HTMLDivElement>(null);
+  const previouslyFocusedRef = useRef<HTMLElement | null>(null);
   const titleId = useId();
+  const subtitleId = useId();
   const [isClosing, setIsClosing] = useState(false);
   const [shouldRender, setShouldRender] = useState(isOpen);
 
@@ -72,20 +97,69 @@ export const Modal: React.FC<ModalProps> = ({
 
   useEffect(() => {
     if (!isOpen || !shouldRender) return;
+    previouslyFocusedRef.current =
+      document.activeElement instanceof HTMLElement ? document.activeElement : null;
     const id = requestAnimationFrame(() => {
-      dialogRef.current?.focus();
+      const dialog = dialogRef.current;
+      if (!dialog) return;
+      if (initialFocus?.current) {
+        initialFocus.current.focus();
+        return;
+      }
+      const focusables = getFocusableElements(dialog);
+      if (focusables.length > 0) {
+        focusables[0].focus();
+      } else {
+        dialog.focus();
+      }
     });
-    return () => cancelAnimationFrame(id);
-  }, [isOpen, shouldRender]);
+    return () => {
+      cancelAnimationFrame(id);
+      const previous = previouslyFocusedRef.current;
+      if (previous && document.contains(previous)) {
+        previous.focus();
+      }
+      previouslyFocusedRef.current = null;
+    };
+  }, [isOpen, shouldRender, initialFocus]);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLDivElement>) => {
+    if (e.key !== 'Tab') return;
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+    const focusables = getFocusableElements(dialog);
+    if (focusables.length === 0) {
+      e.preventDefault();
+      dialog.focus();
+      return;
+    }
+    const first = focusables[0];
+    const last = focusables[focusables.length - 1];
+    const active = document.activeElement;
+    if (e.shiftKey) {
+      if (active === first || active === dialog || !dialog.contains(active)) {
+        e.preventDefault();
+        last.focus();
+      }
+    } else {
+      if (active === last || !dialog.contains(active)) {
+        e.preventDefault();
+        first.focus();
+      }
+    }
+  };
 
   if (!shouldRender) return null;
 
+  const describedById = subtitle != null ? subtitleId : undefined;
+
   return createPortal(
     <div
       className={`${styles.backdrop} ${isClosing ? styles.closing : ''}`}
       onMouseDown={(e) => {
         if (e.target === e.currentTarget) onClose();
       }}
+      onKeyDown={handleKeyDown}
     >
       <Surface
         ref={dialogRef}
@@ -97,6 +171,7 @@ export const Modal: React.FC<ModalProps> = ({
         role="dialog"
         aria-modal="true"
         aria-labelledby={titleId}
+        aria-describedby={describedById}
         tabIndex={-1}
       >
         <div className={styles.header}>
@@ -104,7 +179,9 @@ export const Modal: React.FC<ModalProps> = ({
             {title}
           </Text>
           {subtitle != null && (
-            <div className={styles.subtitle}>{subtitle}</div>
+            <div id={subtitleId} className={styles.subtitle}>
+              {subtitle}
+            </div>
           )}
         </div>
         <div className={`${styles.body} ${bodyClassName ?? ''}`.trim()}>