@versini/ui-menu 7.1.2 → 7.3.0

package/dist/index.d.ts

@@ -38,8 +38,8 @@ export declare const MenuItem: {
 declare type MenuItemProps = {
     /**
      * The label to use for the menu item. Accepts any React node so you can
-     * compose richer labels (e.g. text plus a `<Badge>`, an icon, or styled
-     * inline elements). For a plain text label, pass a string.
+     * compose richer labels (e.g. text plus a `<Badge>`, an icon, or styled inline
+     * elements). For a plain text label, pass a string.
      */
     label?: React.ReactNode;
     /**
@@ -147,15 +147,15 @@ export declare const MenuSeparator: {
 declare type MenuSeparatorProps = React.HTMLAttributes<HTMLDivElement>;
 
 export declare const MenuSub: {
-    ({ label, icon, children, disabled, sideOffset, }: MenuSubProps): JSX.Element;
+    ({ label, icon, children, disabled, sideOffset, selected, }: MenuSubProps): JSX.Element;
     displayName: string;
 };
 
 declare type MenuSubProps = {
     /**
      * The label for the sub-menu trigger. Accepts any React node so you can
-     * compose richer labels (e.g. text plus a `<Badge>`). For a plain text
-     * label, pass a string.
+     * compose richer labels (e.g. text plus a `<Badge>`). For a plain text label,
+     * pass a string.
      */
     label: React.ReactNode;
     /**
@@ -176,6 +176,14 @@ declare type MenuSubProps = {
      * @default 20
      */
     sideOffset?: number;
+    /**
+     * Forces the "contains a selection" indicator on (true) or off (false),
+     * overriding automatic detection. Leave undefined to auto-detect from
+     * descendant MenuItems. Use this when MenuItem children are wrapped in a
+     * custom component that hides the `selected` prop from auto-detection.
+     * @default undefined (auto-detected)
+     */
+    selected?: boolean;
 };
 
 export { }

package/dist/index.js

@@ -1,5 +1,5 @@
 /*!
-  @versini/ui-menu v7.1.2
+  @versini/ui-menu v7.3.0
   © 2026 gizmette.com
 */
 
@@ -53,18 +53,20 @@ const TYPEAHEAD_TIMEOUT_MS = 500;
 function getTypeaheadMatchIndex(items, searchString, startIndex) {
     const count = items.length;
     const normalized = searchString.toLowerCase();
-    // When the same single character is repeated (e.g. "aaa"), cycle
-    // through items starting with that character instead of trying to
-    // match the full repeated string.
-    const isRepeatedChar = normalized.length > 1 && [
+    /**
+	 * When the same single character is repeated (e.g. "aaa"), cycle through items
+	 * starting with that character instead of trying to match the full repeated
+	 * string.
+	 */ const isRepeatedChar = normalized.length > 1 && [
         ...normalized
     ].every((c)=>c === normalized[0]);
     const matchStr = isRepeatedChar ? normalized[0] : normalized;
-    // For a single character (including repeated single-char), start
-    // searching from the item *after* the current one so we always
-    // advance to the next match.  For multi-character strings, start
-    // from the current item so the user can refine the match in-place.
-    const offset = normalized.length === 1 || isRepeatedChar ? 1 : 0;
+    /**
+	 * For a single character (including repeated single-char), start searching
+	 * from the item *after* the current one so we always advance to the next
+	 * match. For multi-character strings, start from the current item so the user
+	 * can refine the match in-place.
+	 */ const offset = normalized.length === 1 || isRepeatedChar ? 1 : 0;
     for(let i = 0; i < count; i++){
         const index = (startIndex + offset + i) % count;
         if (items[index].disabled) {
@@ -216,9 +218,10 @@ function getLastEnabledIndex(items) {
                     }
                 /* v8 ignore stop */ default:
                     {
-                        // Typeahead: printable single characters (ignore modifier-only
-                        // or functional keys such as Shift, Control, Alt, Meta, etc.).
-                        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
+                        /**
+					 * Typeahead: printable single characters (ignore modifier-only or
+					 * functional keys such as Shift, Control, Alt, Meta, etc.).
+					 */ if (event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
                             event.preventDefault();
                             event.stopPropagation();
                             // Reset the debounce timer.
@@ -264,6 +267,13 @@ function getLastEnabledIndex(items) {
 
 
 
+
+
+/**
+ * Shared classes for the small green "selected" dot, reused by MenuItem (inner
+ * dot) and MenuSub (nested-selection indicator) so the success token lives in
+ * one place.
+ */ const SELECTED_DOT_CLASS = "size-1.5 rounded-full bg-copy-success-light";
 const getDisplayName = (element)=>{
     if (typeof element === "string") {
         return element;
@@ -279,12 +289,41 @@ const getDisplayName = (element)=>{
     }
     return "Element";
 };
+/**
+ * Recursively walks a React children tree looking for a selected menu entry.
+ * Only `MenuItem`/`MenuSub` elements with `selected === true` count, so an
+ * unrelated `selected` prop on other nested content (e.g. a native `<option
+ * selected>`) does not produce a false indicator. Traversal still descends
+ * through any container (MenuGroup, fragments) to reach those entries.
+ *
+ * Used by MenuSub to surface a nested selection on its trigger row even while
+ * the sub-menu is closed (sub-menu children are conditionally mounted, so they
+ * cannot report selection upward via context).
+ *
+ */ const hasSelectedDescendant = (node)=>{
+    let found = false;
+    __rspack_external_react.Children.forEach(node, (child)=>{
+        if (found || !__rspack_external_react.isValidElement(child)) {
+            return;
+        }
+        const childProps = child.props;
+        const name = getDisplayName(child);
+        if ((name === "MenuItem" || name === "MenuSub") && childProps.selected === true) {
+            found = true;
+            return;
+        }
+        if (childProps.children) {
+            found = hasSelectedDescendant(childProps.children);
+        }
+    });
+    return found;
+};
 const calculatePosition = (triggerRect, menuRect, placement, sideOffset, viewportWidth, viewportHeight)=>{
     /* v8 ignore start - split always returns non-empty for valid placements */ const side = placement.split("-")[0] || "bottom";
     /* v8 ignore stop */ const alignment = placement.includes("-") ? placement.split("-")[1] : "center";
     let top = 0;
     let left = 0;
-    // Calculate base position based on side
+    // Calculate base position based on side.
     switch(side){
         case "bottom":
             top = triggerRect.bottom + sideOffset;
@@ -299,7 +338,7 @@ const calculatePosition = (triggerRect, menuRect, placement, sideOffset, viewpor
             left = triggerRect.left - menuRect.width - sideOffset;
             break;
     }
-    // Calculate alignment
+    // Calculate alignment.
     if (side === "bottom" || side === "top") {
         switch(alignment){
             case "start":
@@ -325,7 +364,7 @@ const calculatePosition = (triggerRect, menuRect, placement, sideOffset, viewpor
                 break;
         }
     }
-    // Auto-flip if overflowing viewport
+    // Auto-flip if overflowing viewport.
     /* v8 ignore start - auto-flip with fallback when flipped position also overflows */ if (side === "bottom" && top + menuRect.height > viewportHeight) {
         const flippedTop = triggerRect.top - menuRect.height - sideOffset;
         if (flippedTop >= 0) {
@@ -347,7 +386,7 @@ const calculatePosition = (triggerRect, menuRect, placement, sideOffset, viewpor
             left = flippedLeft;
         }
     }
-    /* v8 ignore stop */ // Clamp to viewport bounds
+    /* v8 ignore stop */ // Clamp to viewport bounds.
     left = Math.max(0, Math.min(left, viewportWidth - menuRect.width));
     top = Math.max(0, Math.min(top, viewportHeight - menuRect.height));
     return {
@@ -440,13 +479,13 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
         /* v8 ignore stop */ sideOffset,
         isOpen
     });
-    // Show/hide popover after the menu element is mounted/unmounted
+    // Show/hide popover after the menu element is mounted/unmounted.
     /* v8 ignore start - popover API may not be available in test env */ (0,__rspack_external_react.useEffect)(()=>{
         if (isOpen && menuRef.current && typeof menuRef.current.showPopover === "function") {
             try {
                 menuRef.current.showPopover();
             } catch  {
-            // Popover might already be shown
+            // Popover might already be shown.
             }
         }
     }, [
@@ -464,7 +503,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
             try {
                 menuRef.current.hidePopover();
             } catch  {
-            // Popover might already be hidden
+            // Popover might already be hidden.
             }
         }
         /* v8 ignore stop */ triggerRef.current?.focus();
@@ -472,7 +511,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
         isOpen,
         onOpenChange
     ]);
-    // Click-outside detection: only active when menu is open
+    // Click-outside detection: only active when menu is open.
     /* v8 ignore start - click-outside detection requires full browser env */ (0,__rspack_external_react.useEffect)(()=>{
         if (!isOpen) {
             return;
@@ -487,7 +526,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
                 triggerRef.current?.focus();
             }
         };
-        // Use a timeout to avoid catching the opening click itself
+        // Use a timeout to avoid catching the opening click itself.
         const timeoutId = setTimeout(()=>{
             document.addEventListener("mousedown", handleClickOutside);
         }, 0);
@@ -501,7 +540,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
     ]);
     /* v8 ignore stop */ const getItems = (0,__rspack_external_react.useCallback)(()=>itemsRef.current, []);
     const registerItem = (0,__rspack_external_react.useCallback)((element, disabled)=>{
-        // Maintain DOM order by using compareDocumentPosition
+        // Maintain DOM order by using compareDocumentPosition.
         const existing = itemsRef.current.findIndex((item)=>item.element === element);
         /* v8 ignore start - re-registration on re-render */ if (existing >= 0) {
             itemsRef.current[existing].disabled = disabled;
@@ -511,7 +550,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
             element,
             disabled
         };
-        // Insert in DOM order
+        // Insert in DOM order.
         const insertIndex = itemsRef.current.findIndex((item)=>item.element.compareDocumentPosition(element) & Node.DOCUMENT_POSITION_PRECEDING);
         /* v8 ignore start */ if (insertIndex === -1) {
             itemsRef.current.push(newItem);
@@ -537,7 +576,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
     const handleOpen = (0,__rspack_external_react.useCallback)(()=>{
         setIsOpen(true);
         onOpenChange?.(true);
-        // Focus first enabled item after menu renders
+        // Focus first enabled item after menu renders.
         /* v8 ignore start - rAF does not execute in test env */ requestAnimationFrame(()=>{
             const items = getItems();
             for(let i = 0; i < items.length; i++){
@@ -563,9 +602,9 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
         } else {
             /* v8 ignore stop */ handleOpen();
             /**
-			 * Dispatch a click event to parent elements.
-			 * This ensures that parent components like Tooltip can detect the
-			 * interaction and respond appropriately (e.g., disable tooltip display).
+			 * Dispatch a click event to parent elements. This ensures that parent
+			 * components like Tooltip can detect the interaction and respond
+			 * appropriately (e.g., disable tooltip display).
 			 */ /* v8 ignore start */ if (triggerRef.current) {
                 const clickEvent = new MouseEvent("click", {
                     bubbles: true,
@@ -592,7 +631,7 @@ const Menu = ({ trigger, children, label = "Open menu", defaultPlacement = "bott
         isOpen,
         handleOpen
     ]);
-    /* v8 ignore stop */ // Build trigger element with props
+    /* v8 ignore stop */ // Build trigger element with props.
     const noInternalClick = getDisplayName(trigger) === "Button" || getDisplayName(trigger) === "ButtonIcon";
     const uiButtonsExtraProps = noInternalClick ? {
         noInternalClick,
@@ -739,7 +778,7 @@ const MenuItem = ({ label, disabled, icon, raw = false, children, ignoreClick =
             setActiveIndex(myIndex);
             itemRef.current?.focus();
         }
-        /* v8 ignore stop */ // Close any open sub-menu when hovering a regular item
+        /* v8 ignore stop */ // Close any open sub-menu when hovering a regular item.
         setOpenSubMenuId(null);
         onMouseEnter?.(event);
     };
@@ -797,7 +836,7 @@ const MenuItem = ({ label, disabled, icon, raw = false, children, ignoreClick =
             selected === true && /*#__PURE__*/ jsx("span", {
                 className: "mr-2 flex size-4 shrink-0 items-center justify-center rounded-full border border-copy-medium",
                 children: /*#__PURE__*/ jsx("span", {
-                    className: "size-1.5 rounded-full bg-copy-success-light"
+                    className: SELECTED_DOT_CLASS
                 })
             }),
             selected === false && /*#__PURE__*/ jsx("span", {
@@ -868,7 +907,7 @@ const SUB_CONTENT_CLASS = getMenuClasses({
 const SUB_TRIGGER_CLASS = getMenuItemClasses({
     isSub: true
 });
-const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>{
+const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20, selected })=>{
     const subMenuId = useUniqueId("av-menu-sub-");
     const [isSubOpen, setIsSubOpen] = useState(false);
     const [subActiveIndex, setSubActiveIndex] = useState(-1);
@@ -878,7 +917,7 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
     const subItemsRef = useRef([]);
     const parentContext = useContext(MenuContentContext);
     const rootContext = useContext(MenuRootContext);
-    // Register as an item in the parent menu
+    // Register as an item in the parent menu.
     useEffect(()=>{
         const element = triggerItemRef.current;
         /* v8 ignore start - ref is always set after mount */ if (element) {
@@ -892,8 +931,10 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
         parentContext.registerItem,
         parentContext.unregisterItem
     ]);
-    // Close if a sibling sub-menu opens or parent signals close (openSubMenuId set to null)
-    useEffect(()=>{
+    /**
+	 * Close if a sibling sub-menu opens or parent signals close (openSubMenuId set
+	 * to null).
+	 */ useEffect(()=>{
         if (isSubOpen && parentContext.openSubMenuId !== subMenuId) {
             setIsSubOpen(false);
             setSubActiveIndex(-1);
@@ -901,7 +942,7 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
                 try {
                     subMenuRef.current.hidePopover();
                 } catch  {
-                // Already hidden
+                // Already hidden.
                 }
             }
         /* v8 ignore stop */ }
@@ -917,13 +958,13 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
         sideOffset,
         isOpen: isSubOpen
     });
-    // Show popover after the sub-menu element is mounted
+    // Show popover after the sub-menu element is mounted.
     /* v8 ignore start - popover API may not be available in test env */ useEffect(()=>{
         if (isSubOpen && subMenuRef.current && typeof subMenuRef.current.showPopover === "function") {
             try {
                 subMenuRef.current.showPopover();
             } catch  {
-            // Popover might already be shown
+            // Popover might already be shown.
             }
         }
     }, [
@@ -958,7 +999,7 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
             try {
                 subMenuRef.current.hidePopover();
             } catch  {
-            // Already hidden
+            // Already hidden.
             }
         }
         triggerItemRef.current?.focus();
@@ -969,7 +1010,7 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
         }
         /* v8 ignore stop */ setIsSubOpen(true);
         parentContext.setOpenSubMenuId(subMenuId);
-        // Focus first enabled item after render
+        // Focus first enabled item after render.
         /* v8 ignore start - rAF does not execute in test env */ requestAnimationFrame(()=>{
             const items = getSubItems();
             for(let i = 0; i < items.length; i++){
@@ -1017,14 +1058,24 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
             parentContext.setActiveIndex(myIndex);
             triggerItemRef.current?.focus();
         }
-        // Open sub-menu on hover (WAI-ARIA: hover opens sub-menus when parent menu is already open)
-        if (!isSubOpen && !disabled) {
+        /**
+		 * Open sub-menu on hover (WAI-ARIA: hover opens sub-menus when parent menu is
+		 * already open).
+		 */ if (!isSubOpen && !disabled) {
             openSubMenu();
         }
     };
     /* v8 ignore stop */ const myIndex = parentContext.getItems().findIndex((item)=>item.element === triggerItemRef.current);
     const isHighlighted = myIndex >= 0 && parentContext.activeIndex === myIndex;
     const labelSpanClass = icon ? "pl-2" : "";
+    /**
+	 * Surface a nested selection on the trigger row. An explicit `selected` prop
+	 * wins; otherwise auto-detect from the descendant children tree.
+	 */ const showSelectedIndicator = selected ?? hasSelectedDescendant(children);
+    /**
+	 * Screen-reader description id. Kept OUTSIDE the menuitem's text content so it
+	 * never pollutes typeahead navigation (which reads element.textContent).
+	 */ const selectionDescriptionId = `${subMenuId}-selection`;
     const subContentContextValue = {
         registerItem: registerSubItem,
         unregisterItem: unregisterSubItem,
@@ -1044,6 +1095,7 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
                 "aria-haspopup": "menu",
                 "aria-expanded": isSubOpen,
                 "aria-controls": subMenuId,
+                "aria-describedby": showSelectedIndicator ? selectionDescriptionId : undefined,
                 tabIndex: isHighlighted ? 0 : -1,
                 className: SUB_TRIGGER_CLASS,
                 "data-state": isSubOpen ? "open" : "closed",
@@ -1056,6 +1108,10 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
                     /*#__PURE__*/ jsxs("span", {
                         className: "flex items-center",
                         children: [
+                            showSelectedIndicator && /*#__PURE__*/ jsx("span", {
+                                className: `mr-2 shrink-0 ${SELECTED_DOT_CLASS}`,
+                                "aria-hidden": "true"
+                            }),
                             icon,
                             /*#__PURE__*/ jsx("span", {
                                 className: labelSpanClass,
@@ -1070,6 +1126,11 @@ const MenuSub = ({ label, icon, children, disabled = false, sideOffset = 20 })=>
                     })
                 ]
             }),
+            showSelectedIndicator && /*#__PURE__*/ jsx("span", {
+                id: selectionDescriptionId,
+                className: "sr-only",
+                children: "(contains a selection)"
+            }),
             isSubOpen && /*#__PURE__*/ jsx("div", {
                 ref: subMenuRef,
                 id: subMenuId,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@versini/ui-menu",
-	"version": "7.1.2",
+	"version": "7.3.0",
 	"license": "MIT",
 	"author": "Arno Versini",
 	"publishConfig": {
@@ -38,10 +38,10 @@
 	},
 	"devDependencies": {
 		"@testing-library/jest-dom": "6.9.1",
-		"@versini/ui-types": "10.0.0"
+		"@versini/ui-types": "10.1.0"
 	},
 	"dependencies": {
-		"@versini/ui-hooks": "6.1.1",
+		"@versini/ui-hooks": "6.2.0",
 		"@versini/ui-icons": "4.29.0",
 		"clsx": "2.1.1",
 		"tailwindcss": "4.3.1"
@@ -49,5 +49,5 @@
 	"sideEffects": [
 		"**/*.css"
 	],
-	"gitHead": "f25e4b557175f745705c249d10e2e77dc02ed462"
+	"gitHead": "fbfcead0c4637fdf2cf9c8f6a701fe5da9508d4b"
 }