@elliemae/ds-menu-button 3.80.0-next.51 → 3.80.0-next.53

package/dist/cjs/parts/DSMenuBehaviouralContextProvider/config/useMenuItemEventsHandlers.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useMenuItemEventsHandlers.ts", "../../../../../../../../scripts/build/transpile/react-shim.js"],
-  "sourcesContent": ["/* eslint-disable no-console */\n/* eslint-disable max-lines */\n// in this files the returns are not useless, they are used to clearly demark the intended behavior shortcircuit for the next developer that reads the code\n/* eslint-disable no-useless-return */\n/* eslint-disable complexity */\n/* eslint-disable max-statements */\nimport React from 'react';\nimport { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport {\n  isFocusableNode,\n  isMultipleSelectNode,\n  isRootNode,\n  isSingleSelectNode,\n  isWithSubmenuNode,\n  isWithSubmenuOnlyNode,\n} from '../../../utils/nodesTypeguardsAndGetters.js';\nimport { FORBIDDEN_BEHAVIOURS, UNEXPECTED_INTERNAL_ERRORS } from '../constants/Errors.js';\nimport { type DSMenuBehaviouralContextProviderT } from '../react-desc-prop-types.js';\nimport { getNewSelectionMultipleSelect } from '../utils/multipleSelectionHelpers.js';\nimport { getSubMenusPath } from '../utils/nodeGettersByCriterias.js';\nimport { getNewSelectionSingleSelect } from '../utils/singleSelectionHelpers.js';\nimport type { useFocusTracker } from './useFocusTracker.js';\nimport type { useMenuOpenStatus } from './useMenuOpenStatus.js';\n\ntype ItemKeydownHelpersArgs = {\n  pseudoFocusedItemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n  event?: React.KeyboardEvent | React.MouseEvent;\n};\ntype SubmenuChangeMetainfo = {\n  itemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n  event?: React.SyntheticEvent;\n};\n\ntype UseMenuItemEventsHandlersConfig = {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n  focusTrackers: ReturnType<typeof useFocusTracker>;\n  menuOpenStatus: ReturnType<typeof useMenuOpenStatus>;\n  handleChangeOpenedSubItems: Required<DSMenuButtonT.MenuBehaviouralLayerOptionalProps>['onDisplayedSubmenuChange'];\n};\n\nexport const useMenuItemEventsHandlers = ({\n  propsWithDefault,\n  focusTrackers,\n  menuOpenStatus,\n  handleChangeOpenedSubItems,\n}: UseMenuItemEventsHandlersConfig) => {\n  const { onItemSelected, onActivateItem, selectedNodes } = propsWithDefault;\n  const { onOpinionatedClose } = menuOpenStatus;\n  const {\n    trackFocusFirstChildItem,\n    trackFocusLastChildItem,\n    trackFocusNextItem,\n    trackFocusPreviousItem,\n    trackFocusParentItem,\n    trackFocusNode,\n    focusedElementItemNode,\n    trackFocusTrigger,\n  } = focusTrackers;\n\n  const openSubmenu = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.WithSubmenuMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent | React.FocusEvent;\n    }) => {\n      if (!isWithSubmenuNode(itemNode)) {\n        console.log('openSubmenu -> itemNode:', itemNode);\n        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_OPEN_SUBMENU_OF_NODE_WITHOUT_SUBMENU;\n      }\n      const subMenuNodesPath = getSubMenusPath(itemNode);\n      const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n      const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...subMenuNodesPath, itemNode];\n      handleChangeOpenedSubItems(newOpenedItems, metainfo);\n    },\n    [handleChangeOpenedSubItems],\n  );\n  const closeSubmenusAfterNode = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent | React.FocusEvent;\n    }) => {\n      const subMenuNodesPath = getSubMenusPath(itemNode);\n      const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n      const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...subMenuNodesPath];\n      handleChangeOpenedSubItems(newOpenedItems, metainfo);\n    },\n    [handleChangeOpenedSubItems],\n  );\n  const closeCurrentSubmenu = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent;\n    }) => {\n      const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n      const subMenuNodesPath = getSubMenusPath(itemNode);\n      // if length is 0, it means the parent is the root node, so we close all the submenus\n      if (subMenuNodesPath.length === 0) {\n        handleChangeOpenedSubItems([], metainfo);\n        return { currentSubmenuWasMainMenu: true };\n      }\n\n      // we want to close current submenu, so we pop the last element\n      //  getSubMenusPath guarantees the order by walkParents + reverse at the end\n      subMenuNodesPath.pop();\n      handleChangeOpenedSubItems(subMenuNodesPath, metainfo);\n      return { currentSubmenuWasMainMenu: false };\n    },\n    [handleChangeOpenedSubItems],\n  );\n\n  /*\n   * 13th August 2024:\n   * https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/\n   * Additional roles, states, and properties needed for the menu element are described in the Menu and Menubar Pattern.\n   * https://www.w3.org/WAI/ARIA/apg/patterns/menubar/\n   * Because menubar and menu elements are composite widgets as described in the practice for Keyboard Navigation Inside Components,\n   *  Tab and Shift + Tab do not move focus among the items in the menu.\n   *  Instead, the keyboard commands described in this section enable users to move focus among the elements in a menubar or menu.\n   * Tab and Shift + Tab:\n   *   - Move focus into a menubar <- Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n   *   - When focus is on a menuitem in a menu or menubar, move focus out of the menu or menubar, and close all menus and submenus.\n   *     ************************************************************************************************************************************\n   *     this will be implemented by not setting document.activeElement to the menuitem but keeping it on the trigger button\n   *          why? because there is no javascript API to trigger a \"tab\"/\"shift+tab\" navigation and any algorithm trying to do so is fragile\n   *          also, this is enforced by w3.org too as per:\n   *     ************************************************************************************************************************************\n   *   Note that Tab and Shift + Tab do not move focus into a menu.\n   *     Unlike a menubar, a menu is not visually persistent,\n   *     and authors are responsible for ensuring focus moves to an item inside of a menu when the menu opens.\n   *\n   */\n  const handleMenuItemEnterKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Enter:\n      //   - When focus is on a menuitem that has a submenu, opens the submenu and places focus on its first item.\n      //   ...\n      if (isWithSubmenuOnlyNode(pseudoFocusedItemNode)) {\n        openSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusFirstChildItem(pseudoFocusedItemNode);\n      } else {\n        //  - Otherwise, activates the item...\n\n        //  ----------------------------------\n        //  4. Although it is recommended that authors avoid doing so,\n        //     some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu.\n        //     In such implementations, Enter and Space perform a navigation function,\n        //     e.g., load new content, while Down Arrow, in a horizontal menubar, opens the submenu associated with that same menuitem.\n        //   ---------------------------------\n        //   Based on an investigation, the above statement is not specific to \"navigation\" nor to ONLY \"menubars\", it really is about \"menuitems\" in general\n        //   as long as the role=\"menuitem\" & aria-haspopup=\"${id-of-the-submenu}\" & aria-expanded=\"${true/false}\" (& aria-orientation=\"vertical/horizontal\" if non-default)\n        //   are set, the Screen Readers will provide the same announcement for the menuitem regardless of the parent role\n\n        // \"activation\" is a concept,\n        //  WCAG here implies that for menuitemscheckbox and menuitemsradio this triggers the selection\n        //  for menuitems (that doesn't fit selection nor submenus) it triggers the action\n        //  this also triggers enter -> single-select-item-with-submenu as expected\n        if (isMultipleSelectNode(pseudoFocusedItemNode)) {\n          // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n          // useAdvancedValidation guarantees the non-null in this \"if\" branch\n          const newSelection = getNewSelectionMultipleSelect(selectedNodes!, pseudoFocusedItemNode);\n          onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        } else if (isSingleSelectNode(pseudoFocusedItemNode)) {\n          // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n          // useAdvancedValidation guarantees the non-null in this \"if\" branch\n          const newSelection = getNewSelectionSingleSelect(selectedNodes!, pseudoFocusedItemNode);\n          onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        } else {\n          // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n          // useAdvancedValidation guarantees the non-null in this \"if\" branch\n          onActivateItem!(pseudoFocusedItemNode, { itemNode: pseudoFocusedItemNode, event });\n        }\n        // ... and closes the menu.\n        const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n        onOpinionatedClose();\n      }\n    },\n    [\n      trackFocusFirstChildItem,\n      openSubmenu,\n      handleChangeOpenedSubItems,\n      onOpinionatedClose,\n      selectedNodes,\n      onItemSelected,\n      onActivateItem,\n    ],\n  );\n  const handleMenuItemSpaceKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Space:\n      // [X] (Optional): When focus is on a menuitem that has a submenu, opens the submenu and places focus on its first item.\n      //  ----------------------------------\n      //  4. Although it is recommended that authors avoid doing so,\n      //     some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu.\n      //     In such implementations, Enter and Space perform a navigation function,\n      //     e.g., load new content, while Down Arrow, in a horizontal menubar, opens the submenu associated with that same menuitem.\n      //   ---------------------------------\n      //   Based on an investigation, the above statement is not specific to \"navigation\" nor to ONLY \"menubars\", it really is about \"menuitems\" in general\n      //   as long as the role=\"menuitem\" & aria-haspopup=\"${id-of-the-submenu}\" & aria-expanded=\"${true/false}\" (& aria-orientation=\"vertical/horizontal\" if non-default)\n      //   are set, the Screen Readers will provide the same announcement for the menuitem regardless of the parent role\n      if (isWithSubmenuOnlyNode(pseudoFocusedItemNode)) {\n        openSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusFirstChildItem(pseudoFocusedItemNode);\n        return;\n      }\n      // [X] (Optional): When focus is on a menuitemcheckbox, changes the state without closing the menu.\n      if (isMultipleSelectNode(pseudoFocusedItemNode)) {\n        // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n        // useAdvancedValidation guarantees the non-null in this \"if\" branch\n        const newSelection = getNewSelectionMultipleSelect(selectedNodes!, pseudoFocusedItemNode);\n        onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        return;\n      }\n      // [X] (Optional): When focus is on a menuitemradio that is not checked, without closing the menu,\n      //   checks the focused menuitemradio and unchecks any other checked menuitemradio element in the same group.\n      if (isSingleSelectNode(pseudoFocusedItemNode)) {\n        // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n        // useAdvancedValidation guarantees the non-null in this \"if\" branch\n        const newSelection = getNewSelectionSingleSelect(selectedNodes!, pseudoFocusedItemNode);\n        onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        return;\n      }\n      // [X] (Optional): When focus is on a menuitem that does not have a submenu, activates the menuitem and closes the menu.\n      onActivateItem?.(pseudoFocusedItemNode, { itemNode: pseudoFocusedItemNode, event });\n\n      const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n      const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n      handleChangeOpenedSubItems(newOpenedItems, metainfo);\n      onOpinionatedClose();\n    },\n    [\n      onActivateItem,\n      handleChangeOpenedSubItems,\n      onOpinionatedClose,\n      trackFocusFirstChildItem,\n      openSubmenu,\n      selectedNodes,\n      onItemSelected,\n    ],\n  );\n  const handleMenuItemRightArrowKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Right Arrow:\n      // [N/A] When focus is in a menubar, moves focus to the next item, optionally wrapping from the last to the first.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n\n      // [X] When focus is in a menu and on a menuitem that has a submenu, opens the submenu and places focus on its first item.\n      // [N/A] When focus is in a menu and on an item that does not have a submenu, performs the following 3 actions:\n      //    [N/A] Closes the submenu and any parent menus.\n      //    [N/A] Moves focus to the next item in the menubar.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n\n      // [X] If focus is now on a menuitem with a submenu, either:\n      //   [X] (Recommended) opens the submenu of that menuitem without moving focus into the submenu,\n      //    /\\ we choose the recommended option\n      //    OR\n      //   [N/A] opens the submenu of that menuitem and places focus on the first item in the submenu.\n      //   ***********************************************************\n      //   Dimsum implements IoC, if APP side for whatever reason wants to open the new sub sub menu,\n      //    it's up to them to listen to the pseudo focus event and open the sub sub menu\n      //   ***********************************************************\n      if (isWithSubmenuNode(pseudoFocusedItemNode)) {\n        openSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusFirstChildItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Note that if the menubar were not present, e.g., the menus were opened from a menubutton,\n      //    Right Arrow would not do anything when focus is on an item that does not have a submenu.\n      return;\n    },\n    [openSubmenu, trackFocusFirstChildItem],\n  );\n\n  const handleMenuItemLeftArrowKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Left Arrow:\n      // [N/A] When focus is in a menubar, moves focus to the previous item, optionally wrapping from the first to the last.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n\n      // [X] When focus is in a submenu of an item in a menu, closes the submenu and returns focus to the parent menuitem.\n      const { currentSubmenuWasMainMenu } = closeCurrentSubmenu({ itemNode: pseudoFocusedItemNode, event });\n      if (!currentSubmenuWasMainMenu) {\n        trackFocusParentItem(pseudoFocusedItemNode);\n      }\n\n      // [N/A] When focus is in a submenu of an item in a menubar, performs the following 3 actions:\n      //     [N/A] Closes the submenu.\n      //     [N/A] Moves focus to the previous item in the menubar.\n      //     [N/A] If focus is now on a menuitem with a submenu, either:\n      //       (Recommended) opens the submenu of that menuitem without moving focus into the submenu,\n      //           or\n      //        opens the submenu of that menuitem and places focus on the first item in the submenu.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n    },\n    [closeCurrentSubmenu, trackFocusParentItem],\n  );\n\n  const handleFocusableMenuItemKeyDown = React.useCallback<React.KeyboardEventHandler<HTMLDivElement>>(\n    (event) => {\n      const pseudoFocusedItemNode = focusedElementItemNode.current;\n      // if there is no focused item, we can't handle the logics\n      if (pseudoFocusedItemNode === null) throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_NODE_NOT_SET;\n      // if the item contains an `onKeyDown` prop, we trigger it\n      if (pseudoFocusedItemNode.plainItem.onKeyDown) pseudoFocusedItemNode.plainItem.onKeyDown(event);\n      // TAB:\n      // When focus is on a menuitem in a menu or menubar, move focus to the trigger so tab flows occurs from there.\n      // Then close all menus and submenus.\n      if (event.key === 'Tab') {\n        trackFocusTrigger({ shouldFocusImmediately: true });\n        onOpinionatedClose();\n        return;\n      }\n      // Down Arrow:\n      // [N/A] When focus is on a menuitem in a menubar, and that menuitem has a submenu, opens the submenu and places focus on the first item in the submenu.\n      //    /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n      // [X] When focus is in a menu, moves focus to the next item,\n      //     [X] optionally wrapping from the last to the first.\n      if (event.key === 'ArrowDown') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        trackFocusNextItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Up Arrow:\n      // [X] When focus is in a menu, moves focus to the previous item,\n      //    [X] optionally wrapping from the first to the last.\n      // [N/A] (Optional): When focus is on a menuitem in a menubar, and that menuitem has a submenu, opens the submenu and places focus on the last item in the submenu.\n      //    /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n      if (event.key === 'ArrowUp') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        trackFocusPreviousItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Left Arrow:\n      if (event.key === 'ArrowLeft') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        handleMenuItemLeftArrowKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Home: If arrow key wrapping is not supported, moves focus to the first item in the current menu or menubar.\n      if (event.key === 'Home') {\n        if (!pseudoFocusedItemNode.parent) {\n          console.log('handleFocusableMenuItemKeyDown -> Home > focused item node', pseudoFocusedItemNode);\n          // should be impossible, at most the .parent is the root node, which is not able to trigger this event\n          throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_HAS_NO_PARENT;\n        }\n        trackFocusFirstChildItem(pseudoFocusedItemNode.parent);\n        return;\n      }\n      // End: If arrow key wrapping is not supported, moves focus to the last item in the current menu or menubar.\n      if (event.key === 'End') {\n        if (!pseudoFocusedItemNode.parent) {\n          console.log('handleFocusableMenuItemKeyDown -> Home > focused item node', pseudoFocusedItemNode);\n          // should be impossible, at most the .parent is the root node, which is not able to trigger this event\n          throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_HAS_NO_PARENT;\n        }\n        trackFocusLastChildItem(pseudoFocusedItemNode.parent);\n        return;\n      }\n      if (event.key === 'Escape') {\n        // if the item has no submenu, the alt key is transparent, we behave as if it's not even pressed\n        if (event.altKey && isWithSubmenuNode(pseudoFocusedItemNode)) {\n          // PUI-14639 - Implement submenu dismissal mechanism\n          // Description: we need to add a mechanism to close submenus that automatically expand when a menu item is focused with the keyboard.\n          // we have decided to implement a special shortcut (Alt/Option + Esc) as the dismissal mechanism.\n          // This change is necessary to comply with WCAG success criterion 1.4.13.\n          // https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html\n          // if the item has a submenu, we close it\n          closeSubmenusAfterNode({ itemNode: pseudoFocusedItemNode, event });\n          return;\n        }\n        // Escape: Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent menuitem, from which the menu was opened\n        const { currentSubmenuWasMainMenu } = closeCurrentSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        if (currentSubmenuWasMainMenu) {\n          // if the menu we are trying to close is the main menu, we additionally close the main menu itself\n          // we focus the trigger immediately (shouldFocusImmediately: true) so the focus return is synchronous\n          // and not deferred to requestAnimationFrame \u2014 Escape on the trigger is safe since it only calls\n          // onOpinionatedClose() which is already a no-op when the menu is closed\n          trackFocusTrigger({ shouldFocusImmediately: true });\n          onOpinionatedClose({ skipFocus: true });\n        } else {\n          trackFocusParentItem(pseudoFocusedItemNode);\n        }\n        return;\n      }\n\n      /* ************************************************************************************\n       * ******* ACTIVATION & SUBMENU keys doesn't apply if the item is \"disabled\" **********\n       * ************************************************************************************ */\n      if (pseudoFocusedItemNode.plainItem.disabled) return;\n      // Enter:\n      if (event.key === 'Enter') {\n        handleMenuItemEnterKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Space:\n      if (event.key === ' ') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        handleMenuItemSpaceKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Right Arrow:\n      if (event.key === 'ArrowRight') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        handleMenuItemRightArrowKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n    },\n    [\n      focusedElementItemNode,\n      trackFocusTrigger,\n      trackFocusNextItem,\n      trackFocusPreviousItem,\n      handleMenuItemLeftArrowKeyDown,\n      trackFocusFirstChildItem,\n      trackFocusLastChildItem,\n      closeCurrentSubmenu,\n      trackFocusParentItem,\n      closeSubmenusAfterNode,\n      onOpinionatedClose,\n      handleMenuItemEnterKeyDown,\n      handleMenuItemSpaceKeyDown,\n      handleMenuItemRightArrowKeyDown,\n    ],\n  );\n  const handleFocusableMenuItemClick = React.useCallback(\n    (event: React.MouseEvent<HTMLDivElement>) => {\n      const pseudoFocusedItemNode = focusedElementItemNode.current;\n      if (pseudoFocusedItemNode === null) throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_NODE_NOT_SET;\n      // if the item is disabled, we don't do anything\n      if (pseudoFocusedItemNode.plainItem.disabled) return;\n      // we need to handle which submenu needs to close automagically based on the click\n      // starting from the itemNode, we check:\n      //   - the parent of the itemNode is root?\n      //     -  yes -> we close all the submenus\n      const parentMenuNode = pseudoFocusedItemNode.parent;\n      if (isRootNode(parentMenuNode)) {\n        const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n      } else {\n        //     -  no  -> we close all the submenus that are not in the path to the root of the itemNode\n        // this is necessary on click because the user can still interact with other (visual) depths of the menu\n        // during keyboard navigation, the user is limited to the current (visual) depth\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...getSubMenusPath(pseudoFocusedItemNode)];\n        //     - if the clicked node has a submenu, keep it open\n        if (isWithSubmenuNode(pseudoFocusedItemNode)) {\n          newOpenedItems.push(pseudoFocusedItemNode);\n        }\n        const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n      }\n\n      // to all effects and purposes, the click event is the same as the space key\n      //  the main difference between enter and space is that\n      //   - enter ALWAYS closes the menu excepts for submenus\n      //   - space closes the menu if \"activable\", selections doesn't, submenus doesn't\n      handleMenuItemSpaceKeyDown({ pseudoFocusedItemNode, event });\n      // if the item contains an `onClick` prop, we trigger it\n      if (pseudoFocusedItemNode.plainItem.onClick) pseudoFocusedItemNode.plainItem.onClick(event);\n    },\n    [focusedElementItemNode, handleMenuItemSpaceKeyDown, handleChangeOpenedSubItems],\n  );\n\n  // the \"menu-button\" widget is an opinionated widget with a specific behaviour to follow when a focusable item is \"focused\"\n  //   this function achieve the opinionated \"focus an item\" opinionated behaviour (regardless of why the item is focused)\n  const opinionatedFocusBehaviour = React.useCallback(\n    // we currently know only one \"event\" that can trigger this opinionated behaviour\n    //   - focus      => React.FocusEvent <-- triggered by ATs \"focus mode\" or \"virtual cursor\" navigation\n    //      NOTE:\n    //           mouseEnter => React.MouseEvent\n    //      still ends up calling this function, but as a side effect of mouse-enter focusing the item, not as the main event\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes, event: React.FocusEvent) => {\n      if (!isFocusableNode(itemNode)) {\n        console.log('handleFocusableMenuItemOnMouseEnter > itemNode:', itemNode);\n        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;\n      }\n      // on hover -> we track the hovered item as the focused one on top of which events should work on\n      trackFocusNode(itemNode);\n      if (!isWithSubmenuNode(itemNode)) {\n        // if the item has nosubmenu we close all the siblings submenus\n        const subMenuNodesPath = getSubMenusPath(itemNode);\n        const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...subMenuNodesPath];\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n        return;\n      }\n      // if the item is disabled, we don't open the submenu, and there is nothing else to do\n      if (itemNode.plainItem.disabled) return;\n      // if not disabled and it has a submenu, we open it, and there is nothing else to do\n      openSubmenu({ itemNode, event });\n    },\n    [handleChangeOpenedSubItems, openSubmenu, trackFocusNode],\n  );\n\n  // when an item is hovered, we focus it\n  //   this effectively achieves:\n  //     - the item is focused (it trigger the handleFocusableMenuItemNativeFocusEvent function because render runs node.focus())\n  //     - if the user presses a keyboard key, the interaction will work starting from the (hovered hence focused) item\n  const handleFocusableMenuItemOnMouseEnter = React.useCallback(\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes) => {\n      if (!isFocusableNode(itemNode)) {\n        console.log('handleFocusableMenuItemOnMouseEnter > itemNode:', itemNode);\n        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;\n      }\n      // on hover -> we track the hovered item as the focused one on top of which events should work on\n      trackFocusNode(itemNode);\n    },\n    [trackFocusNode],\n  );\n\n  const handleFocusableMenuItemNativeFocusEvent = React.useCallback(\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes, event: React.FocusEvent) => {\n      opinionatedFocusBehaviour(itemNode, event);\n    },\n    [opinionatedFocusBehaviour],\n  );\n\n  return React.useMemo(\n    () => ({\n      handleFocusableMenuItemKeyDown,\n      handleFocusableMenuItemClick,\n      handleFocusableMenuItemOnMouseEnter,\n      handleFocusableMenuItemNativeFocusEvent,\n    }),\n    [\n      handleFocusableMenuItemClick,\n      handleFocusableMenuItemKeyDown,\n      handleFocusableMenuItemNativeFocusEvent,\n      handleFocusableMenuItemOnMouseEnter,\n    ],\n  );\n};\n", "import * as React from 'react';\nexport { React };\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADMvB,mBAAkB;AAElB,uCAOO;AACP,oBAAiE;AAEjE,sCAA8C;AAC9C,oCAAgC;AAChC,oCAA4C;AAoBrC,MAAM,4BAA4B,CAAC;AAAA,EACxC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,MAAuC;AACrC,QAAM,EAAE,gBAAgB,gBAAgB,cAAc,IAAI;AAC1D,QAAM,EAAE,mBAAmB,IAAI;AAC/B,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,QAAM,cAAc,aAAAA,QAAM;AAAA,IACxB,CAAC;AAAA,MACC;AAAA,MACA;AAAA,IACF,MAGM;AACJ,UAAI,KAAC,oDAAkB,QAAQ,GAAG;AAChC,gBAAQ,IAAI,4BAA4B,QAAQ;AAChD,cAAM,mCAAqB;AAAA,MAC7B;AACA,YAAM,uBAAmB,+CAAgB,QAAQ;AACjD,YAAM,WAAkC,EAAE,UAAU,MAAM;AAC1D,YAAM,iBAAuD,CAAC,GAAG,kBAAkB,QAAQ;AAC3F,iCAA2B,gBAAgB,QAAQ;AAAA,IACrD;AAAA,IACA,CAAC,0BAA0B;AAAA,EAC7B;AACA,QAAM,yBAAyB,aAAAA,QAAM;AAAA,IACnC,CAAC;AAAA,MACC;AAAA,MACA;AAAA,IACF,MAGM;AACJ,YAAM,uBAAmB,+CAAgB,QAAQ;AACjD,YAAM,WAAkC,EAAE,UAAU,MAAM;AAC1D,YAAM,iBAAuD,CAAC,GAAG,gBAAgB;AACjF,iCAA2B,gBAAgB,QAAQ;AAAA,IACrD;AAAA,IACA,CAAC,0BAA0B;AAAA,EAC7B;AACA,QAAM,sBAAsB,aAAAA,QAAM;AAAA,IAChC,CAAC;AAAA,MACC;AAAA,MACA;AAAA,IACF,MAGM;AACJ,YAAM,WAAkC,EAAE,UAAU,MAAM;AAC1D,YAAM,uBAAmB,+CAAgB,QAAQ;AAEjD,UAAI,iBAAiB,WAAW,GAAG;AACjC,mCAA2B,CAAC,GAAG,QAAQ;AACvC,eAAO,EAAE,2BAA2B,KAAK;AAAA,MAC3C;AAIA,uBAAiB,IAAI;AACrB,iCAA2B,kBAAkB,QAAQ;AACrD,aAAO,EAAE,2BAA2B,MAAM;AAAA,IAC5C;AAAA,IACA,CAAC,0BAA0B;AAAA,EAC7B;AAuBA,QAAM,6BAA6B,aAAAA,QAAM;AAAA,IACvC,CAAC,EAAE,uBAAuB,MAAM,MAA8B;AAI5D,cAAI,wDAAsB,qBAAqB,GAAG;AAChD,oBAAY,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACtD,iCAAyB,qBAAqB;AAAA,MAChD,OAAO;AAiBL,gBAAI,uDAAqB,qBAAqB,GAAG;AAG/C,gBAAM,mBAAe,+DAA8B,eAAgB,qBAAqB;AACxF,yBAAgB,cAAc,EAAE,UAAU,uBAAuB,MAAM,CAAC;AAAA,QAC1E,eAAW,qDAAmB,qBAAqB,GAAG;AAGpD,gBAAM,mBAAe,2DAA4B,eAAgB,qBAAqB;AACtF,yBAAgB,cAAc,EAAE,UAAU,uBAAuB,MAAM,CAAC;AAAA,QAC1E,OAAO;AAGL,yBAAgB,uBAAuB,EAAE,UAAU,uBAAuB,MAAM,CAAC;AAAA,QACnF;AAEA,cAAM,WAAkC,EAAE,UAAU,uBAAuB,MAAM;AACjF,cAAM,iBAAuD,CAAC;AAC9D,mCAA2B,gBAAgB,QAAQ;AACnD,2BAAmB;AAAA,MACrB;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,QAAM,6BAA6B,aAAAA,QAAM;AAAA,IACvC,CAAC,EAAE,uBAAuB,MAAM,MAA8B;AAY5D,cAAI,wDAAsB,qBAAqB,GAAG;AAChD,oBAAY,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACtD,iCAAyB,qBAAqB;AAC9C;AAAA,MACF;AAEA,cAAI,uDAAqB,qBAAqB,GAAG;AAG/C,cAAM,mBAAe,+DAA8B,eAAgB,qBAAqB;AACxF,uBAAgB,cAAc,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACxE;AAAA,MACF;AAGA,cAAI,qDAAmB,qBAAqB,GAAG;AAG7C,cAAM,mBAAe,2DAA4B,eAAgB,qBAAqB;AACtF,uBAAgB,cAAc,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACxE;AAAA,MACF;AAEA,uBAAiB,uBAAuB,EAAE,UAAU,uBAAuB,MAAM,CAAC;AAElF,YAAM,WAAkC,EAAE,UAAU,uBAAuB,MAAM;AACjF,YAAM,iBAAuD,CAAC;AAC9D,iCAA2B,gBAAgB,QAAQ;AACnD,yBAAmB;AAAA,IACrB;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,QAAM,kCAAkC,aAAAA,QAAM;AAAA,IAC5C,CAAC,EAAE,uBAAuB,MAAM,MAA8B;AAoB5D,cAAI,oDAAkB,qBAAqB,GAAG;AAC5C,oBAAY,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACtD,iCAAyB,qBAAqB;AAC9C;AAAA,MACF;AAGA;AAAA,IACF;AAAA,IACA,CAAC,aAAa,wBAAwB;AAAA,EACxC;AAEA,QAAM,iCAAiC,aAAAA,QAAM;AAAA,IAC3C,CAAC,EAAE,uBAAuB,MAAM,MAA8B;AAM5D,YAAM,EAAE,0BAA0B,IAAI,oBAAoB,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACpG,UAAI,CAAC,2BAA2B;AAC9B,6BAAqB,qBAAqB;AAAA,MAC5C;AAAA,IAUF;AAAA,IACA,CAAC,qBAAqB,oBAAoB;AAAA,EAC5C;AAEA,QAAM,iCAAiC,aAAAA,QAAM;AAAA,IAC3C,CAAC,UAAU;AACT,YAAM,wBAAwB,uBAAuB;AAErD,UAAI,0BAA0B,KAAM,OAAM,yCAA2B;AAErE,UAAI,sBAAsB,UAAU,UAAW,uBAAsB,UAAU,UAAU,KAAK;AAI9F,UAAI,MAAM,QAAQ,OAAO;AACvB,0BAAkB,EAAE,wBAAwB,KAAK,CAAC;AAClD,2BAAmB;AACnB;AAAA,MACF;AAMA,UAAI,MAAM,QAAQ,aAAa;AAC7B,eAAO,eAAe;AACtB,2BAAmB,qBAAqB;AACxC;AAAA,MACF;AAMA,UAAI,MAAM,QAAQ,WAAW;AAC3B,eAAO,eAAe;AACtB,+BAAuB,qBAAqB;AAC5C;AAAA,MACF;AAEA,UAAI,MAAM,QAAQ,aAAa;AAC7B,eAAO,eAAe;AACtB,uCAA+B,EAAE,uBAAuB,MAAM,CAAC;AAC/D;AAAA,MACF;AAEA,UAAI,MAAM,QAAQ,QAAQ;AACxB,YAAI,CAAC,sBAAsB,QAAQ;AACjC,kBAAQ,IAAI,8DAA8D,qBAAqB;AAE/F,gBAAM,yCAA2B;AAAA,QACnC;AACA,iCAAyB,sBAAsB,MAAM;AACrD;AAAA,MACF;AAEA,UAAI,MAAM,QAAQ,OAAO;AACvB,YAAI,CAAC,sBAAsB,QAAQ;AACjC,kBAAQ,IAAI,8DAA8D,qBAAqB;AAE/F,gBAAM,yCAA2B;AAAA,QACnC;AACA,gCAAwB,sBAAsB,MAAM;AACpD;AAAA,MACF;AACA,UAAI,MAAM,QAAQ,UAAU;AAE1B,YAAI,MAAM,cAAU,oDAAkB,qBAAqB,GAAG;AAO5D,iCAAuB,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACjE;AAAA,QACF;AAEA,cAAM,EAAE,0BAA0B,IAAI,oBAAoB,EAAE,UAAU,uBAAuB,MAAM,CAAC;AACpG,YAAI,2BAA2B;AAK7B,4BAAkB,EAAE,wBAAwB,KAAK,CAAC;AAClD,6BAAmB,EAAE,WAAW,KAAK,CAAC;AAAA,QACxC,OAAO;AACL,+BAAqB,qBAAqB;AAAA,QAC5C;AACA;AAAA,MACF;AAKA,UAAI,sBAAsB,UAAU,SAAU;AAE9C,UAAI,MAAM,QAAQ,SAAS;AACzB,mCAA2B,EAAE,uBAAuB,MAAM,CAAC;AAC3D;AAAA,MACF;AAEA,UAAI,MAAM,QAAQ,KAAK;AACrB,eAAO,eAAe;AACtB,mCAA2B,EAAE,uBAAuB,MAAM,CAAC;AAC3D;AAAA,MACF;AAEA,UAAI,MAAM,QAAQ,cAAc;AAC9B,eAAO,eAAe;AACtB,wCAAgC,EAAE,uBAAuB,MAAM,CAAC;AAChE;AAAA,MACF;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACA,QAAM,+BAA+B,aAAAA,QAAM;AAAA,IACzC,CAAC,UAA4C;AAC3C,YAAM,wBAAwB,uBAAuB;AACrD,UAAI,0BAA0B,KAAM,OAAM,yCAA2B;AAErE,UAAI,sBAAsB,UAAU,SAAU;AAK9C,YAAM,iBAAiB,sBAAsB;AAC7C,cAAI,6CAAW,cAAc,GAAG;AAC9B,cAAM,WAAkC,EAAE,UAAU,uBAAuB,MAAM;AACjF,cAAM,iBAAuD,CAAC;AAC9D,mCAA2B,gBAAgB,QAAQ;AAAA,MACrD,OAAO;AAIL,cAAM,iBAAuD,CAAC,OAAG,+CAAgB,qBAAqB,CAAC;AAEvG,gBAAI,oDAAkB,qBAAqB,GAAG;AAC5C,yBAAe,KAAK,qBAAqB;AAAA,QAC3C;AACA,cAAM,WAAkC,EAAE,UAAU,uBAAuB,MAAM;AACjF,mCAA2B,gBAAgB,QAAQ;AAAA,MACrD;AAMA,iCAA2B,EAAE,uBAAuB,MAAM,CAAC;AAE3D,UAAI,sBAAsB,UAAU,QAAS,uBAAsB,UAAU,QAAQ,KAAK;AAAA,IAC5F;AAAA,IACA,CAAC,wBAAwB,4BAA4B,0BAA0B;AAAA,EACjF;AAIA,QAAM,4BAA4B,aAAAA,QAAM;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMtC,CAAC,UAAkD,UAA4B;AAC7E,UAAI,KAAC,kDAAgB,QAAQ,GAAG;AAC9B,gBAAQ,IAAI,mDAAmD,QAAQ;AACvE,cAAM,mCAAqB;AAAA,MAC7B;AAEA,qBAAe,QAAQ;AACvB,UAAI,KAAC,oDAAkB,QAAQ,GAAG;AAEhC,cAAM,uBAAmB,+CAAgB,QAAQ;AACjD,cAAM,WAAkC,EAAE,UAAU,MAAM;AAC1D,cAAM,iBAAuD,CAAC,GAAG,gBAAgB;AACjF,mCAA2B,gBAAgB,QAAQ;AACnD;AAAA,MACF;AAEA,UAAI,SAAS,UAAU,SAAU;AAEjC,kBAAY,EAAE,UAAU,MAAM,CAAC;AAAA,IACjC;AAAA,IACA,CAAC,4BAA4B,aAAa,cAAc;AAAA,EAC1D;AAMA,QAAM,sCAAsC,aAAAA,QAAM;AAAA,IAChD,CAAC,aAAqD;AACpD,UAAI,KAAC,kDAAgB,QAAQ,GAAG;AAC9B,gBAAQ,IAAI,mDAAmD,QAAQ;AACvE,cAAM,mCAAqB;AAAA,MAC7B;AAEA,qBAAe,QAAQ;AAAA,IACzB;AAAA,IACA,CAAC,cAAc;AAAA,EACjB;AAEA,QAAM,0CAA0C,aAAAA,QAAM;AAAA,IACpD,CAAC,UAAkD,UAA4B;AAC7E,gCAA0B,UAAU,KAAK;AAAA,IAC3C;AAAA,IACA,CAAC,yBAAyB;AAAA,EAC5B;AAEA,SAAO,aAAAA,QAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;",
+  "sourcesContent": ["/* eslint-disable no-console */\n/* eslint-disable max-lines */\n// in this files the returns are not useless, they are used to clearly demark the intended behavior shortcircuit for the next developer that reads the code\n/* eslint-disable no-useless-return */\n/* eslint-disable complexity */\n/* eslint-disable max-statements */\nimport React from 'react';\nimport { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport {\n  isFocusableNode,\n  isMultipleSelectNode,\n  isRootNode,\n  isSingleSelectNode,\n  isWithSubmenuNode,\n  isWithSubmenuOnlyNode,\n} from '../../../utils/nodesTypeguardsAndGetters.js';\nimport { FORBIDDEN_BEHAVIOURS, UNEXPECTED_INTERNAL_ERRORS } from '../constants/Errors.js';\nimport { type DSMenuBehaviouralContextProviderT } from '../react-desc-prop-types.js';\nimport { getNewSelectionMultipleSelect } from '../utils/multipleSelectionHelpers.js';\nimport { getSubMenusPath } from '../utils/nodeGettersByCriterias.js';\nimport { getNewSelectionSingleSelect } from '../utils/singleSelectionHelpers.js';\nimport type { useFocusTracker } from './useFocusTracker.js';\nimport type { useMenuOpenStatus } from './useMenuOpenStatus.js';\n\ntype ItemKeydownHelpersArgs = {\n  pseudoFocusedItemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n  event?: React.KeyboardEvent | React.MouseEvent;\n};\ntype SubmenuChangeMetainfo = {\n  itemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n  event?: React.SyntheticEvent;\n};\n\ntype UseMenuItemEventsHandlersConfig = {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n  focusTrackers: ReturnType<typeof useFocusTracker>;\n  menuOpenStatus: ReturnType<typeof useMenuOpenStatus>;\n  handleChangeOpenedSubItems: Required<DSMenuButtonT.MenuBehaviouralLayerOptionalProps>['onDisplayedSubmenuChange'];\n};\n\n// the item's own `onClick` is part of the item contract for ANY activation (its type accepts keyboard events):\n//   the click path already invokes it, so the keyboard activation (Enter/Space) must invoke it too.\n//   The click path routes through the Space handler and then calls `onClick` itself, hence the `keydown` check to never fire it twice.\nconst invokeItemOnClickOnKeyboardActivation = (\n  pseudoFocusedItemNode: DSMenuButtonT.PseudoFocusableMenuNodes,\n  event?: React.KeyboardEvent | React.MouseEvent,\n) => {\n  if (event?.type === 'keydown' && pseudoFocusedItemNode.plainItem.onClick)\n    pseudoFocusedItemNode.plainItem.onClick(event as React.KeyboardEvent);\n};\n\nexport const useMenuItemEventsHandlers = ({\n  propsWithDefault,\n  focusTrackers,\n  menuOpenStatus,\n  handleChangeOpenedSubItems,\n}: UseMenuItemEventsHandlersConfig) => {\n  const { onItemSelected, onActivateItem, selectedNodes, buttonDOMNodeRef } = propsWithDefault;\n  const { onOpinionatedClose } = menuOpenStatus;\n  const {\n    trackFocusFirstChildItem,\n    trackFocusLastChildItem,\n    trackFocusNextItem,\n    trackFocusPreviousItem,\n    trackFocusParentItem,\n    trackFocusNode,\n    focusedElementItemNode,\n    trackFocusTrigger,\n    trackFocusRegionReset,\n  } = focusTrackers;\n\n  const openSubmenu = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.WithSubmenuMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent | React.FocusEvent;\n    }) => {\n      if (!isWithSubmenuNode(itemNode)) {\n        console.log('openSubmenu -> itemNode:', itemNode);\n        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_OPEN_SUBMENU_OF_NODE_WITHOUT_SUBMENU;\n      }\n      const subMenuNodesPath = getSubMenusPath(itemNode);\n      const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n      const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...subMenuNodesPath, itemNode];\n      handleChangeOpenedSubItems(newOpenedItems, metainfo);\n    },\n    [handleChangeOpenedSubItems],\n  );\n  const closeSubmenusAfterNode = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent | React.FocusEvent;\n    }) => {\n      const subMenuNodesPath = getSubMenusPath(itemNode);\n      const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n      const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...subMenuNodesPath];\n      handleChangeOpenedSubItems(newOpenedItems, metainfo);\n    },\n    [handleChangeOpenedSubItems],\n  );\n  const closeCurrentSubmenu = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent;\n    }) => {\n      const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n      const subMenuNodesPath = getSubMenusPath(itemNode);\n      // if length is 0, it means the parent is the root node, so we close all the submenus\n      if (subMenuNodesPath.length === 0) {\n        handleChangeOpenedSubItems([], metainfo);\n        return { currentSubmenuWasMainMenu: true };\n      }\n\n      // we want to close current submenu, so we pop the last element\n      //  getSubMenusPath guarantees the order by walkParents + reverse at the end\n      subMenuNodesPath.pop();\n      handleChangeOpenedSubItems(subMenuNodesPath, metainfo);\n      return { currentSubmenuWasMainMenu: false };\n    },\n    [handleChangeOpenedSubItems],\n  );\n\n  /*\n   * 13th August 2024:\n   * https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/\n   * Additional roles, states, and properties needed for the menu element are described in the Menu and Menubar Pattern.\n   * https://www.w3.org/WAI/ARIA/apg/patterns/menubar/\n   * Because menubar and menu elements are composite widgets as described in the practice for Keyboard Navigation Inside Components,\n   *  Tab and Shift + Tab do not move focus among the items in the menu.\n   *  Instead, the keyboard commands described in this section enable users to move focus among the elements in a menubar or menu.\n   * Tab and Shift + Tab:\n   *   - Move focus into a menubar <- Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n   *   - When focus is on a menuitem in a menu or menubar, move focus out of the menu or menubar, and close all menus and submenus.\n   *     ************************************************************************************************************************************\n   *     this will be implemented by not setting document.activeElement to the menuitem but keeping it on the trigger button\n   *          why? because there is no javascript API to trigger a \"tab\"/\"shift+tab\" navigation and any algorithm trying to do so is fragile\n   *          also, this is enforced by w3.org too as per:\n   *     ************************************************************************************************************************************\n   *   Note that Tab and Shift + Tab do not move focus into a menu.\n   *     Unlike a menubar, a menu is not visually persistent,\n   *     and authors are responsible for ensuring focus moves to an item inside of a menu when the menu opens.\n   *\n   */\n  const handleMenuItemEnterKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Enter:\n      //   - When focus is on a menuitem that has a submenu, opens the submenu and places focus on its first item.\n      //   ...\n      if (isWithSubmenuOnlyNode(pseudoFocusedItemNode)) {\n        openSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusFirstChildItem(pseudoFocusedItemNode);\n      } else {\n        //  - Otherwise, activates the item...\n\n        //  ----------------------------------\n        //  4. Although it is recommended that authors avoid doing so,\n        //     some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu.\n        //     In such implementations, Enter and Space perform a navigation function,\n        //     e.g., load new content, while Down Arrow, in a horizontal menubar, opens the submenu associated with that same menuitem.\n        //   ---------------------------------\n        //   Based on an investigation, the above statement is not specific to \"navigation\" nor to ONLY \"menubars\", it really is about \"menuitems\" in general\n        //   as long as the role=\"menuitem\" & aria-haspopup=\"${id-of-the-submenu}\" & aria-expanded=\"${true/false}\" (& aria-orientation=\"vertical/horizontal\" if non-default)\n        //   are set, the Screen Readers will provide the same announcement for the menuitem regardless of the parent role\n\n        // \"activation\" is a concept,\n        //  WCAG here implies that for menuitemscheckbox and menuitemsradio this triggers the selection\n        //  for menuitems (that doesn't fit selection nor submenus) it triggers the action\n        //  this also triggers enter -> single-select-item-with-submenu as expected\n        if (isMultipleSelectNode(pseudoFocusedItemNode)) {\n          // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n          // useAdvancedValidation guarantees the non-null in this \"if\" branch\n          const newSelection = getNewSelectionMultipleSelect(selectedNodes!, pseudoFocusedItemNode);\n          onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        } else if (isSingleSelectNode(pseudoFocusedItemNode)) {\n          // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n          // useAdvancedValidation guarantees the non-null in this \"if\" branch\n          const newSelection = getNewSelectionSingleSelect(selectedNodes!, pseudoFocusedItemNode);\n          onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        } else {\n          // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n          // useAdvancedValidation guarantees the non-null in this \"if\" branch\n          onActivateItem!(pseudoFocusedItemNode, { itemNode: pseudoFocusedItemNode, event });\n        }\n        invokeItemOnClickOnKeyboardActivation(pseudoFocusedItemNode, event);\n        // ... and closes the menu.\n        const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n        onOpinionatedClose({ reason: 'item-activation', event });\n      }\n    },\n    [\n      trackFocusFirstChildItem,\n      openSubmenu,\n      handleChangeOpenedSubItems,\n      onOpinionatedClose,\n      selectedNodes,\n      onItemSelected,\n      onActivateItem,\n    ],\n  );\n  const handleMenuItemSpaceKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Space:\n      // [X] (Optional): When focus is on a menuitem that has a submenu, opens the submenu and places focus on its first item.\n      //  ----------------------------------\n      //  4. Although it is recommended that authors avoid doing so,\n      //     some implementations of navigation menubars may have menuitem elements that both perform a function and open a submenu.\n      //     In such implementations, Enter and Space perform a navigation function,\n      //     e.g., load new content, while Down Arrow, in a horizontal menubar, opens the submenu associated with that same menuitem.\n      //   ---------------------------------\n      //   Based on an investigation, the above statement is not specific to \"navigation\" nor to ONLY \"menubars\", it really is about \"menuitems\" in general\n      //   as long as the role=\"menuitem\" & aria-haspopup=\"${id-of-the-submenu}\" & aria-expanded=\"${true/false}\" (& aria-orientation=\"vertical/horizontal\" if non-default)\n      //   are set, the Screen Readers will provide the same announcement for the menuitem regardless of the parent role\n      if (isWithSubmenuOnlyNode(pseudoFocusedItemNode)) {\n        openSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusFirstChildItem(pseudoFocusedItemNode);\n        return;\n      }\n      // [X] (Optional): When focus is on a menuitemcheckbox, changes the state without closing the menu.\n      if (isMultipleSelectNode(pseudoFocusedItemNode)) {\n        // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n        // useAdvancedValidation guarantees the non-null in this \"if\" branch\n        const newSelection = getNewSelectionMultipleSelect(selectedNodes!, pseudoFocusedItemNode);\n        onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        invokeItemOnClickOnKeyboardActivation(pseudoFocusedItemNode, event);\n        return;\n      }\n      // [X] (Optional): When focus is on a menuitemradio that is not checked, without closing the menu,\n      //   checks the focused menuitemradio and unchecks any other checked menuitemradio element in the same group.\n      if (isSingleSelectNode(pseudoFocusedItemNode)) {\n        // https://www.typescriptlang.org/docs/handbook/release-notes/typescript-2-0.html#non-null-assertion-operator\n        // useAdvancedValidation guarantees the non-null in this \"if\" branch\n        const newSelection = getNewSelectionSingleSelect(selectedNodes!, pseudoFocusedItemNode);\n        onItemSelected!(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        invokeItemOnClickOnKeyboardActivation(pseudoFocusedItemNode, event);\n        return;\n      }\n      // [X] (Optional): When focus is on a menuitem that does not have a submenu, activates the menuitem and closes the menu.\n      onActivateItem?.(pseudoFocusedItemNode, { itemNode: pseudoFocusedItemNode, event });\n      invokeItemOnClickOnKeyboardActivation(pseudoFocusedItemNode, event);\n\n      const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n      const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n      handleChangeOpenedSubItems(newOpenedItems, metainfo);\n      onOpinionatedClose({ reason: 'item-activation', event });\n    },\n    [\n      onActivateItem,\n      handleChangeOpenedSubItems,\n      onOpinionatedClose,\n      trackFocusFirstChildItem,\n      openSubmenu,\n      selectedNodes,\n      onItemSelected,\n    ],\n  );\n  const handleMenuItemRightArrowKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Right Arrow:\n      // [N/A] When focus is in a menubar, moves focus to the next item, optionally wrapping from the last to the first.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n\n      // [X] When focus is in a menu and on a menuitem that has a submenu, opens the submenu and places focus on its first item.\n      // [N/A] When focus is in a menu and on an item that does not have a submenu, performs the following 3 actions:\n      //    [N/A] Closes the submenu and any parent menus.\n      //    [N/A] Moves focus to the next item in the menubar.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n\n      // [X] If focus is now on a menuitem with a submenu, either:\n      //   [X] (Recommended) opens the submenu of that menuitem without moving focus into the submenu,\n      //    /\\ we choose the recommended option\n      //    OR\n      //   [N/A] opens the submenu of that menuitem and places focus on the first item in the submenu.\n      //   ***********************************************************\n      //   Dimsum implements IoC, if APP side for whatever reason wants to open the new sub sub menu,\n      //    it's up to them to listen to the pseudo focus event and open the sub sub menu\n      //   ***********************************************************\n      if (isWithSubmenuNode(pseudoFocusedItemNode)) {\n        openSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusFirstChildItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Note that if the menubar were not present, e.g., the menus were opened from a menubutton,\n      //    Right Arrow would not do anything when focus is on an item that does not have a submenu.\n      return;\n    },\n    [openSubmenu, trackFocusFirstChildItem],\n  );\n\n  const handleMenuItemLeftArrowKeyDown = React.useCallback(\n    ({ pseudoFocusedItemNode, event }: ItemKeydownHelpersArgs) => {\n      // Left Arrow:\n      // [N/A] When focus is in a menubar, moves focus to the previous item, optionally wrapping from the first to the last.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n\n      // [X] When focus is in a submenu of an item in a menu, closes the submenu and returns focus to the parent menuitem.\n      const { currentSubmenuWasMainMenu } = closeCurrentSubmenu({ itemNode: pseudoFocusedItemNode, event });\n      if (!currentSubmenuWasMainMenu) {\n        trackFocusParentItem(pseudoFocusedItemNode);\n      }\n\n      // [N/A] When focus is in a submenu of an item in a menubar, performs the following 3 actions:\n      //     [N/A] Closes the submenu.\n      //     [N/A] Moves focus to the previous item in the menubar.\n      //     [N/A] If focus is now on a menuitem with a submenu, either:\n      //       (Recommended) opens the submenu of that menuitem without moving focus into the submenu,\n      //           or\n      //        opens the submenu of that menuitem and places focus on the first item in the submenu.\n      //  /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n    },\n    [closeCurrentSubmenu, trackFocusParentItem],\n  );\n\n  /*\n   * TAB (APG): \"When focus is on a menuitem in a menu or menubar, move focus out of the menu or menubar, and close\n   *   all menus and submenus.\"\n   *\n   * Tab is an event of the TRIGGER, not of the items. The menu is the trigger's contextual child (it only lives in a\n   *   portal to solve z-index/visual issues): real browser focus sits on the items \u2014 instead of a simulated\n   *   pseudo-focus \u2014 so assistive technologies announce them, but to the browser the Tab must behave as if focus never\n   *   left the trigger. So the items do not take part in it at all (their own `onKeyDown` is not invoked for Tab) and\n   *   it cannot be altered from them: it is handled in the CAPTURE phase of the root menu, before anything else can\n   *   stop or alter the event.\n   *\n   * The ONE place in this widget where focus is moved from a handler instead of the focus tracker's ref callbacks \u2014\n   *   on purpose (see KNOWN_INTENTIONAL_DEVIATIONS.md, \"Tab moves focus from the keydown handler\"). Tab/Shift+Tab have\n   *   a browser DEFAULT ACTION that runs right after the keydown handlers: it moves focus on from wherever focus is at\n   *   that moment. Anything that moves focus later (tracker write -> render -> ref callback, throttled or deferred) is\n   *   too late: the default has already moved on from the (about to unmount) item and focus ends on the body (Tab) or\n   *   after the menu (Shift+Tab). So: focus the trigger ONCE, synchronously, and let the browser take over from there\n   *   (next tabbable for Tab, previous for Shift+Tab).\n   */\n  const handleMenuTabKeyDownCapture = React.useCallback<React.KeyboardEventHandler<HTMLElement>>(\n    (event) => {\n      if (event.key !== 'Tab') return;\n      buttonDOMNodeRef.current?.focus();\n      // focus is about to leave the whole button navigation for another element of the page: neutralize the focus\n      //   tracker (\"nothing to focus\") so nothing in it can ever steal the focus back\n      trackFocusRegionReset();\n      onOpinionatedClose({ skipFocus: true, reason: 'tab', event });\n    },\n    [buttonDOMNodeRef, onOpinionatedClose, trackFocusRegionReset],\n  );\n\n  const handleFocusableMenuItemKeyDown = React.useCallback<React.KeyboardEventHandler<HTMLDivElement>>(\n    (event) => {\n      // TAB is handled in the CAPTURE phase of the root menu (`handleMenuTabKeyDownCapture`, above): by the time this\n      //   handler runs, the trigger already holds focus and the tracker/menu state already moved on\n      if (event.key === 'Tab') return;\n      const pseudoFocusedItemNode = focusedElementItemNode.current;\n      // if there is no focused item, we can't handle the logics\n      if (pseudoFocusedItemNode === null) throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_NODE_NOT_SET;\n      // if the item contains an `onKeyDown` prop, we trigger it\n      if (pseudoFocusedItemNode.plainItem.onKeyDown) pseudoFocusedItemNode.plainItem.onKeyDown(event);\n      // Down Arrow:\n      // [N/A] When focus is on a menuitem in a menubar, and that menuitem has a submenu, opens the submenu and places focus on the first item in the submenu.\n      //    /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n      // [X] When focus is in a menu, moves focus to the next item,\n      //     [X] optionally wrapping from the last to the first.\n      if (event.key === 'ArrowDown') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        trackFocusNextItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Up Arrow:\n      // [X] When focus is in a menu, moves focus to the previous item,\n      //    [X] optionally wrapping from the first to the last.\n      // [N/A] (Optional): When focus is on a menuitem in a menubar, and that menuitem has a submenu, opens the submenu and places focus on the last item in the submenu.\n      //    /\\ Not relevant for this component, this is ONLY FOR MENU, not for MENUBARS\n      if (event.key === 'ArrowUp') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        trackFocusPreviousItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Left Arrow:\n      if (event.key === 'ArrowLeft') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        handleMenuItemLeftArrowKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Home: If arrow key wrapping is not supported, moves focus to the first item in the current menu or menubar.\n      if (event.key === 'Home') {\n        if (!pseudoFocusedItemNode.parent) {\n          console.log('handleFocusableMenuItemKeyDown -> Home > focused item node', pseudoFocusedItemNode);\n          // should be impossible, at most the .parent is the root node, which is not able to trigger this event\n          throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_HAS_NO_PARENT;\n        }\n        trackFocusFirstChildItem(pseudoFocusedItemNode.parent);\n        return;\n      }\n      // End: If arrow key wrapping is not supported, moves focus to the last item in the current menu or menubar.\n      if (event.key === 'End') {\n        if (!pseudoFocusedItemNode.parent) {\n          console.log('handleFocusableMenuItemKeyDown -> Home > focused item node', pseudoFocusedItemNode);\n          // should be impossible, at most the .parent is the root node, which is not able to trigger this event\n          throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_HAS_NO_PARENT;\n        }\n        trackFocusLastChildItem(pseudoFocusedItemNode.parent);\n        return;\n      }\n      if (event.key === 'Escape') {\n        // an item only receives keys while the menu is open: the menu consumes this Escape, so it must not also reach\n        //   an ancestor that closes on Escape (DSDialog, DSModalSlide... React bubbles through portals) \u2014 the old\n        //   DSDropdownMenuV2 listbox stopped every key here for the same reason\n        event.stopPropagation();\n        // if the item has no submenu, the alt key is transparent, we behave as if it's not even pressed\n        if (event.altKey && isWithSubmenuNode(pseudoFocusedItemNode)) {\n          // PUI-14639 - Implement submenu dismissal mechanism\n          // Description: we need to add a mechanism to close submenus that automatically expand when a menu item is focused with the keyboard.\n          // we have decided to implement a special shortcut (Alt/Option + Esc) as the dismissal mechanism.\n          // This change is necessary to comply with WCAG success criterion 1.4.13.\n          // https://www.w3.org/WAI/WCAG21/Understanding/content-on-hover-or-focus.html\n          // if the item has a submenu, we close it\n          closeSubmenusAfterNode({ itemNode: pseudoFocusedItemNode, event });\n          return;\n        }\n        // Escape: Close the menu that contains focus and return focus to the element or context, e.g., menu button or parent menuitem, from which the menu was opened\n        const { currentSubmenuWasMainMenu } = closeCurrentSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        if (currentSubmenuWasMainMenu) {\n          // if the menu we are trying to close is the main menu, we additionally close the main menu itself\n          // we focus the trigger immediately (shouldFocusImmediately: true) so the focus return is synchronous\n          // and not deferred to requestAnimationFrame \u2014 Escape on the trigger is safe since it only calls\n          // onOpinionatedClose() which is already a no-op when the menu is closed\n          trackFocusTrigger({ shouldFocusImmediately: true });\n          onOpinionatedClose({ skipFocus: true, reason: 'escape', event });\n        } else {\n          trackFocusParentItem(pseudoFocusedItemNode);\n        }\n        return;\n      }\n\n      /* ************************************************************************************\n       * ******* ACTIVATION & SUBMENU keys doesn't apply if the item is \"disabled\" **********\n       * ************************************************************************************ */\n      if (pseudoFocusedItemNode.plainItem.disabled) return;\n      // Enter:\n      if (event.key === 'Enter') {\n        handleMenuItemEnterKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Space:\n      if (event.key === ' ') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        handleMenuItemSpaceKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Right Arrow:\n      if (event.key === 'ArrowRight') {\n        event?.preventDefault(); // if scrollbar are present, this keydown event should not interact with the scrollbar\n        handleMenuItemRightArrowKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n    },\n    [\n      focusedElementItemNode,\n      trackFocusTrigger,\n      trackFocusNextItem,\n      trackFocusPreviousItem,\n      handleMenuItemLeftArrowKeyDown,\n      trackFocusFirstChildItem,\n      trackFocusLastChildItem,\n      closeCurrentSubmenu,\n      trackFocusParentItem,\n      closeSubmenusAfterNode,\n      onOpinionatedClose,\n      handleMenuItemEnterKeyDown,\n      handleMenuItemSpaceKeyDown,\n      handleMenuItemRightArrowKeyDown,\n    ],\n  );\n  const handleFocusableMenuItemClick = React.useCallback(\n    (event: React.MouseEvent<HTMLDivElement>) => {\n      const pseudoFocusedItemNode = focusedElementItemNode.current;\n      if (pseudoFocusedItemNode === null) throw UNEXPECTED_INTERNAL_ERRORS.FOCUSED_ITEM_NODE_NOT_SET;\n      // if the item is disabled, we don't do anything\n      if (pseudoFocusedItemNode.plainItem.disabled) return;\n      // we need to handle which submenu needs to close automagically based on the click\n      // starting from the itemNode, we check:\n      //   - the parent of the itemNode is root?\n      //     -  yes -> we close all the submenus\n      const parentMenuNode = pseudoFocusedItemNode.parent;\n      if (isRootNode(parentMenuNode)) {\n        const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n      } else {\n        //     -  no  -> we close all the submenus that are not in the path to the root of the itemNode\n        // this is necessary on click because the user can still interact with other (visual) depths of the menu\n        // during keyboard navigation, the user is limited to the current (visual) depth\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...getSubMenusPath(pseudoFocusedItemNode)];\n        //     - if the clicked node has a submenu, keep it open\n        if (isWithSubmenuNode(pseudoFocusedItemNode)) {\n          newOpenedItems.push(pseudoFocusedItemNode);\n        }\n        const metainfo: SubmenuChangeMetainfo = { itemNode: pseudoFocusedItemNode, event };\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n      }\n\n      // to all effects and purposes, the click event is the same as the space key\n      //  the main difference between enter and space is that\n      //   - enter ALWAYS closes the menu excepts for submenus\n      //   - space closes the menu if \"activable\", selections doesn't, submenus doesn't\n      handleMenuItemSpaceKeyDown({ pseudoFocusedItemNode, event });\n      // if the item contains an `onClick` prop, we trigger it\n      if (pseudoFocusedItemNode.plainItem.onClick) pseudoFocusedItemNode.plainItem.onClick(event);\n    },\n    [focusedElementItemNode, handleMenuItemSpaceKeyDown, handleChangeOpenedSubItems],\n  );\n\n  // the \"menu-button\" widget is an opinionated widget with a specific behaviour to follow when a focusable item is \"focused\"\n  //   this function achieve the opinionated \"focus an item\" opinionated behaviour (regardless of why the item is focused)\n  const opinionatedFocusBehaviour = React.useCallback(\n    // we currently know only one \"event\" that can trigger this opinionated behaviour\n    //   - focus      => React.FocusEvent <-- triggered by ATs \"focus mode\" or \"virtual cursor\" navigation\n    //      NOTE:\n    //           mouseEnter => React.MouseEvent\n    //      still ends up calling this function, but as a side effect of mouse-enter focusing the item, not as the main event\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes, event: React.FocusEvent) => {\n      if (!isFocusableNode(itemNode)) {\n        console.log('handleFocusableMenuItemOnMouseEnter > itemNode:', itemNode);\n        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;\n      }\n      // on hover -> we track the hovered item as the focused one on top of which events should work on\n      trackFocusNode(itemNode);\n      if (!isWithSubmenuNode(itemNode)) {\n        // if the item has nosubmenu we close all the siblings submenus\n        const subMenuNodesPath = getSubMenusPath(itemNode);\n        const metainfo: SubmenuChangeMetainfo = { itemNode, event };\n        const newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[] = [...subMenuNodesPath];\n        handleChangeOpenedSubItems(newOpenedItems, metainfo);\n        return;\n      }\n      // if the item is disabled, we don't open the submenu, and there is nothing else to do\n      if (itemNode.plainItem.disabled) return;\n      // if not disabled and it has a submenu, we open it, and there is nothing else to do\n      openSubmenu({ itemNode, event });\n    },\n    [handleChangeOpenedSubItems, openSubmenu, trackFocusNode],\n  );\n\n  // when an item is hovered, we focus it\n  //   this effectively achieves:\n  //     - the item is focused (it trigger the handleFocusableMenuItemNativeFocusEvent function because render runs node.focus())\n  //     - if the user presses a keyboard key, the interaction will work starting from the (hovered hence focused) item\n  const handleFocusableMenuItemOnMouseEnter = React.useCallback(\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes) => {\n      if (!isFocusableNode(itemNode)) {\n        console.log('handleFocusableMenuItemOnMouseEnter > itemNode:', itemNode);\n        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;\n      }\n      // on hover -> we track the hovered item as the focused one on top of which events should work on\n      trackFocusNode(itemNode);\n    },\n    [trackFocusNode],\n  );\n\n  const handleFocusableMenuItemNativeFocusEvent = React.useCallback(\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes, event: React.FocusEvent) => {\n      opinionatedFocusBehaviour(itemNode, event);\n    },\n    [opinionatedFocusBehaviour],\n  );\n\n  return React.useMemo(\n    () => ({\n      handleMenuTabKeyDownCapture,\n      handleFocusableMenuItemKeyDown,\n      handleFocusableMenuItemClick,\n      handleFocusableMenuItemOnMouseEnter,\n      handleFocusableMenuItemNativeFocusEvent,\n    }),\n    [\n      handleMenuTabKeyDownCapture,\n      handleFocusableMenuItemClick,\n      handleFocusableMenuItemKeyDown,\n      handleFocusableMenuItemNativeFocusEvent,\n      handleFocusableMenuItemOnMouseEnter,\n    ],\n  );\n};\n", "import * as React from 'react';\nexport { React };\n"],
+  "mappings": "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",
   "names": ["React"]
 }

package/dist/cjs/parts/DSMenuBehaviouralContextProvider/config/useMenuOpenStatus.js

@@ -35,22 +35,28 @@ var React = __toESM(require("react"));
 var import_react = __toESM(require("react"));
 const useMenuOpenStatus = ({ propsWithDefault, focusTrackers }) => {
   const { trackFocusTrigger, trackFocusFirstChildItem, trackFocusLastChildItem, preventBlurReset } = focusTrackers;
-  const { onClose, onOpen, optionsTree } = propsWithDefault;
-  const [isMenuOpen, setIsMenuOpen] = import_react.default.useState(false);
+  const { onClose, onOpen, optionsTree, a11yDangerouslyConsumerOwnedMenuOpenState } = propsWithDefault;
+  const [internalIsMenuOpen, setIsMenuOpen] = import_react.default.useState(false);
+  const isMenuOpen = a11yDangerouslyConsumerOwnedMenuOpenState ?? internalIsMenuOpen;
+  const isMenuOpenRef = import_react.default.useRef(isMenuOpen);
+  isMenuOpenRef.current = isMenuOpen;
+  const openIntentPendingRef = import_react.default.useRef(false);
   const onOpinionatedClose = import_react.default.useCallback(
-    ({ skipFocus } = { skipFocus: false }) => {
+    ({ skipFocus = false, reason, event }) => {
+      if (!isMenuOpenRef.current) return;
+      openIntentPendingRef.current = false;
       setIsMenuOpen(false);
-      if (onClose) onClose();
+      if (onClose) onClose({ reason, event });
       if (!skipFocus) trackFocusTrigger();
       preventBlurReset.current = false;
     },
     [onClose, preventBlurReset, trackFocusTrigger]
   );
   const onOpinionatedOpen = import_react.default.useCallback(
-    (config) => {
-      const { focusLastChild = false } = config || {};
+    ({ focusLastChild = false, reason, event }) => {
+      if (onOpen && !isMenuOpenRef.current) onOpen({ reason, event });
       setIsMenuOpen(true);
-      if (onOpen) onOpen();
+      openIntentPendingRef.current = true;
       const typeCastedOptionsTree = optionsTree;
       if (focusLastChild) trackFocusLastChildItem(typeCastedOptionsTree);
       else trackFocusFirstChildItem(typeCastedOptionsTree);
@@ -59,7 +65,7 @@ const useMenuOpenStatus = ({ propsWithDefault, focusTrackers }) => {
     [onOpen, optionsTree, preventBlurReset, trackFocusFirstChildItem, trackFocusLastChildItem]
   );
   return import_react.default.useMemo(
-    () => ({ isMenuOpen, onOpinionatedClose, onOpinionatedOpen }),
+    () => ({ isMenuOpen, onOpinionatedClose, onOpinionatedOpen, openIntentPendingRef }),
     [isMenuOpen, onOpinionatedClose, onOpinionatedOpen]
   );
 };

package/dist/cjs/parts/DSMenuBehaviouralContextProvider/config/useMenuOpenStatus.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useMenuOpenStatus.ts", "../../../../../../../../scripts/build/transpile/react-shim.js"],
-  "sourcesContent": ["import React from 'react';\nimport { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport { type DSMenuBehaviouralContextProviderT } from '../react-desc-prop-types.js';\nimport type { useFocusTracker } from './useFocusTracker.js';\n\ntype UseMenuOpenStatusConfig = {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n  focusTrackers: ReturnType<typeof useFocusTracker>;\n};\n\ntype OnOpinionatedOpenConfig = {\n  focusLastChild?: boolean;\n};\n\nexport const useMenuOpenStatus = ({ propsWithDefault, focusTrackers }: UseMenuOpenStatusConfig) => {\n  // when the menu closes the focus must be returned to the trigger\n  const { trackFocusTrigger, trackFocusFirstChildItem, trackFocusLastChildItem, preventBlurReset } = focusTrackers;\n  const { onClose, onOpen, optionsTree } = propsWithDefault;\n  const [isMenuOpen, setIsMenuOpen] = React.useState(false);\n\n  const onOpinionatedClose = React.useCallback(\n    ({ skipFocus } = { skipFocus: false }) => {\n      setIsMenuOpen(false);\n      if (onClose) onClose();\n      if (!skipFocus) trackFocusTrigger();\n      preventBlurReset.current = false;\n    },\n    [onClose, preventBlurReset, trackFocusTrigger],\n  );\n\n  const onOpinionatedOpen = React.useCallback(\n    (config?: OnOpinionatedOpenConfig) => {\n      const { focusLastChild = false } = config || {};\n      setIsMenuOpen(true);\n      if (onOpen) onOpen();\n      // Focus on the first item\n      // this conversion is a unsafe but that's because we are handling the treeroot node\n      //  and DSTree doesn't have direct support for typescript tree-root interfaces being different from the rest of the tree\n      // the function trackFocusLastChildItem takes any MenuNode and generates the list from subitems autonomously\n      // except for the \"trigger\" scenario, we always expect to invoke this function with a PseudoFocusableMenuNodes\n      //  so we typecast here instead of losing the type safety in the rest of the code\n      const typeCastedOptionsTree = optionsTree as DSMenuButtonT.PseudoFocusableMenuNodes;\n      if (focusLastChild) trackFocusLastChildItem(typeCastedOptionsTree);\n      else trackFocusFirstChildItem(typeCastedOptionsTree);\n      preventBlurReset.current = true;\n    },\n    [onOpen, optionsTree, preventBlurReset, trackFocusFirstChildItem, trackFocusLastChildItem],\n  );\n\n  return React.useMemo(\n    () => ({ isMenuOpen, onOpinionatedClose, onOpinionatedOpen }),\n    [isMenuOpen, onOpinionatedClose, onOpinionatedOpen],\n  );\n};\n", "import * as React from 'react';\nexport { React };\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADAvB,mBAAkB;AAcX,MAAM,oBAAoB,CAAC,EAAE,kBAAkB,cAAc,MAA+B;AAEjG,QAAM,EAAE,mBAAmB,0BAA0B,yBAAyB,iBAAiB,IAAI;AACnG,QAAM,EAAE,SAAS,QAAQ,YAAY,IAAI;AACzC,QAAM,CAAC,YAAY,aAAa,IAAI,aAAAA,QAAM,SAAS,KAAK;AAExD,QAAM,qBAAqB,aAAAA,QAAM;AAAA,IAC/B,CAAC,EAAE,UAAU,IAAI,EAAE,WAAW,MAAM,MAAM;AACxC,oBAAc,KAAK;AACnB,UAAI,QAAS,SAAQ;AACrB,UAAI,CAAC,UAAW,mBAAkB;AAClC,uBAAiB,UAAU;AAAA,IAC7B;AAAA,IACA,CAAC,SAAS,kBAAkB,iBAAiB;AAAA,EAC/C;AAEA,QAAM,oBAAoB,aAAAA,QAAM;AAAA,IAC9B,CAAC,WAAqC;AACpC,YAAM,EAAE,iBAAiB,MAAM,IAAI,UAAU,CAAC;AAC9C,oBAAc,IAAI;AAClB,UAAI,OAAQ,QAAO;AAOnB,YAAM,wBAAwB;AAC9B,UAAI,eAAgB,yBAAwB,qBAAqB;AAAA,UAC5D,0BAAyB,qBAAqB;AACnD,uBAAiB,UAAU;AAAA,IAC7B;AAAA,IACA,CAAC,QAAQ,aAAa,kBAAkB,0BAA0B,uBAAuB;AAAA,EAC3F;AAEA,SAAO,aAAAA,QAAM;AAAA,IACX,OAAO,EAAE,YAAY,oBAAoB,kBAAkB;AAAA,IAC3D,CAAC,YAAY,oBAAoB,iBAAiB;AAAA,EACpD;AACF;",
+  "sourcesContent": ["import React from 'react';\nimport { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport { type DSMenuBehaviouralContextProviderT } from '../react-desc-prop-types.js';\nimport type { useFocusTracker } from './useFocusTracker.js';\n\ntype UseMenuOpenStatusConfig = {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n  focusTrackers: ReturnType<typeof useFocusTracker>;\n};\n\ntype OnOpinionatedOpenConfig = {\n  focusLastChild?: boolean;\n  reason: DSMenuButtonT.MenuOpenReason;\n  event?: DSMenuButtonT.MenuOpenMetainfo['event'];\n};\n\ntype OnOpinionatedCloseConfig = {\n  skipFocus?: boolean;\n  reason: DSMenuButtonT.MenuCloseReason;\n  event?: DSMenuButtonT.MenuCloseMetainfo['event'];\n};\n\nexport const useMenuOpenStatus = ({ propsWithDefault, focusTrackers }: UseMenuOpenStatusConfig) => {\n  // when the menu closes the focus must be returned to the trigger\n  const { trackFocusTrigger, trackFocusFirstChildItem, trackFocusLastChildItem, preventBlurReset } = focusTrackers;\n  const { onClose, onOpen, optionsTree, a11yDangerouslyConsumerOwnedMenuOpenState } = propsWithDefault;\n  const [internalIsMenuOpen, setIsMenuOpen] = React.useState(false);\n  /*\n   * Escape hatch (a11yDangerouslyConsumerOwnedMenuOpenState): when the consumer provides a boolean\n   *   they own the effective open state \u2014 this resolved value is the single source of truth read by\n   *   the flyout visibility, the floating context's `externallyControlledIsOpen` and the trigger's\n   *   open/close toggle check, so consumer-ownership propagates through the already-controlled paths.\n   *   The intents below still fire `onOpen`/`onClose` (+ focus tracking) so the consumer can sync;\n   *   if they don't, the documented trade-off applies: focus may leave a panel that stays open.\n   */\n  const isMenuOpen = a11yDangerouslyConsumerOwnedMenuOpenState ?? internalIsMenuOpen;\n  // read through a ref to keep `onOpinionatedClose` referentially stable (it is a dependency of many handlers/effects)\n  const isMenuOpenRef = React.useRef(isMenuOpen);\n  isMenuOpenRef.current = isMenuOpen;\n  /*\n   * An open INTENT that already armed the focus tracker (trigger click / ArrowDown / ArrowUp) and whose menu has not\n   *   mounted yet. The tracker throttles its calls (50ms, last one wins), so the armed region may not be visible yet\n   *   when the menu mounts: this synchronous flag tells the root flyout \"the focus target is already decided, do not\n   *   decide a second one\" (otherwise ArrowUp -> last item would be overridden by the default \"first item\").\n   */\n  const openIntentPendingRef = React.useRef(false);\n\n  const onOpinionatedClose = React.useCallback(\n    ({ skipFocus = false, reason, event }: OnOpinionatedCloseConfig) => {\n      // closing a menu that is not open is a no-op: no `onClose`, no focus change.\n      //  without this guard every closed instance reports a \"close intent\" on window blur / Escape on the trigger\n      if (!isMenuOpenRef.current) return;\n      openIntentPendingRef.current = false;\n      setIsMenuOpen(false);\n      if (onClose) onClose({ reason, event });\n      if (!skipFocus) trackFocusTrigger();\n      preventBlurReset.current = false;\n    },\n    [onClose, preventBlurReset, trackFocusTrigger],\n  );\n\n  const onOpinionatedOpen = React.useCallback(\n    ({ focusLastChild = false, reason, event }: OnOpinionatedOpenConfig) => {\n      // `onOpen` reports a closed -> open intent only; re-arming the focus while already open (ArrowDown/Up) is still allowed\n      if (onOpen && !isMenuOpenRef.current) onOpen({ reason, event });\n      setIsMenuOpen(true);\n      openIntentPendingRef.current = true;\n      // Focus on the first item\n      // this conversion is a unsafe but that's because we are handling the treeroot node\n      //  and DSTree doesn't have direct support for typescript tree-root interfaces being different from the rest of the tree\n      // the function trackFocusLastChildItem takes any MenuNode and generates the list from subitems autonomously\n      // except for the \"trigger\" scenario, we always expect to invoke this function with a PseudoFocusableMenuNodes\n      //  so we typecast here instead of losing the type safety in the rest of the code\n      const typeCastedOptionsTree = optionsTree as DSMenuButtonT.PseudoFocusableMenuNodes;\n      if (focusLastChild) trackFocusLastChildItem(typeCastedOptionsTree);\n      else trackFocusFirstChildItem(typeCastedOptionsTree);\n      preventBlurReset.current = true;\n    },\n    [onOpen, optionsTree, preventBlurReset, trackFocusFirstChildItem, trackFocusLastChildItem],\n  );\n\n  return React.useMemo(\n    () => ({ isMenuOpen, onOpinionatedClose, onOpinionatedOpen, openIntentPendingRef }),\n    [isMenuOpen, onOpinionatedClose, onOpinionatedOpen],\n  );\n};\n", "import * as React from 'react';\nexport { React };\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADAvB,mBAAkB;AAsBX,MAAM,oBAAoB,CAAC,EAAE,kBAAkB,cAAc,MAA+B;AAEjG,QAAM,EAAE,mBAAmB,0BAA0B,yBAAyB,iBAAiB,IAAI;AACnG,QAAM,EAAE,SAAS,QAAQ,aAAa,0CAA0C,IAAI;AACpF,QAAM,CAAC,oBAAoB,aAAa,IAAI,aAAAA,QAAM,SAAS,KAAK;AAShE,QAAM,aAAa,6CAA6C;AAEhE,QAAM,gBAAgB,aAAAA,QAAM,OAAO,UAAU;AAC7C,gBAAc,UAAU;AAOxB,QAAM,uBAAuB,aAAAA,QAAM,OAAO,KAAK;AAE/C,QAAM,qBAAqB,aAAAA,QAAM;AAAA,IAC/B,CAAC,EAAE,YAAY,OAAO,QAAQ,MAAM,MAAgC;AAGlE,UAAI,CAAC,cAAc,QAAS;AAC5B,2BAAqB,UAAU;AAC/B,oBAAc,KAAK;AACnB,UAAI,QAAS,SAAQ,EAAE,QAAQ,MAAM,CAAC;AACtC,UAAI,CAAC,UAAW,mBAAkB;AAClC,uBAAiB,UAAU;AAAA,IAC7B;AAAA,IACA,CAAC,SAAS,kBAAkB,iBAAiB;AAAA,EAC/C;AAEA,QAAM,oBAAoB,aAAAA,QAAM;AAAA,IAC9B,CAAC,EAAE,iBAAiB,OAAO,QAAQ,MAAM,MAA+B;AAEtE,UAAI,UAAU,CAAC,cAAc,QAAS,QAAO,EAAE,QAAQ,MAAM,CAAC;AAC9D,oBAAc,IAAI;AAClB,2BAAqB,UAAU;AAO/B,YAAM,wBAAwB;AAC9B,UAAI,eAAgB,yBAAwB,qBAAqB;AAAA,UAC5D,0BAAyB,qBAAqB;AACnD,uBAAiB,UAAU;AAAA,IAC7B;AAAA,IACA,CAAC,QAAQ,aAAa,kBAAkB,0BAA0B,uBAAuB;AAAA,EAC3F;AAEA,SAAO,aAAAA,QAAM;AAAA,IACX,OAAO,EAAE,YAAY,oBAAoB,mBAAmB,qBAAqB;AAAA,IACjF,CAAC,YAAY,oBAAoB,iBAAiB;AAAA,EACpD;AACF;",
   "names": ["React"]
 }

package/dist/cjs/parts/DSOpinionatedButton/config/useTriggerEventsHandlers.js

@@ -37,7 +37,15 @@ var import_resolveRef = require("../../../utils/resolveRef.js");
 var import_MenuBehaviouralContextProviderCTX = require("../../DSMenuBehaviouralContextProvider/MenuBehaviouralContextProviderCTX.js");
 var import_constants = require("../../DSMenuBehaviouralContextProvider/constants/index.js");
 const useTriggerEventsHandlers = ({ propsWithDefault, floatingContext }) => {
-  const { focusRegion, isMenuOpen, onOpinionatedOpen, onOpinionatedClose, trackFocusTrigger, shouldFocusImmediately } = import_react.default.useContext(import_MenuBehaviouralContextProviderCTX.MenuBehaviouralContextProviderContext);
+  const {
+    focusRegion,
+    isMenuOpen,
+    onOpinionatedOpen,
+    onOpinionatedClose,
+    trackFocusTrigger,
+    shouldFocusImmediately,
+    shouldRefocusTrigger
+  } = import_react.default.useContext(import_MenuBehaviouralContextProviderCTX.MenuBehaviouralContextProviderContext);
   const { onClick, onFocus, innerRef, onKeyDown } = propsWithDefault;
   const {
     refs: { setReference }
@@ -51,23 +59,24 @@ const useTriggerEventsHandlers = ({ propsWithDefault, floatingContext }) => {
     (e, ...args) => {
       if (onClick) onClick(e, ...args);
       if (mutableIsMenuOpen.current) {
-        onOpinionatedClose();
+        onOpinionatedClose({ reason: "trigger-toggle", event: e });
       } else {
-        onOpinionatedOpen();
+        onOpinionatedOpen({ reason: "trigger-click", event: e });
       }
     },
     [onClick, onOpinionatedClose, onOpinionatedOpen]
   );
   const handleOnFocus = import_react.default.useCallback(
     (e, ...args) => {
-      if (focusedRegionPerformanceHelper.current !== import_constants.MENU_FOCUS_REGIONS.TRIGGER) trackFocusTrigger();
+      if (focusedRegionPerformanceHelper.current !== import_constants.MENU_FOCUS_REGIONS.TRIGGER)
+        trackFocusTrigger({ shouldFocusImmediately: false, refocusTrigger: false });
       if (onFocus) onFocus(e, ...args);
     },
     [onFocus, trackFocusTrigger]
   );
   const handleFocusIfTriggerIsFocusRegion = import_react.default.useCallback(
     (node) => {
-      if (reRenderButtonToAllowFocus && node) {
+      if (reRenderButtonToAllowFocus && node && shouldRefocusTrigger.current) {
         if (!shouldFocusImmediately.current) {
           requestAnimationFrame(() => {
             node.focus();
@@ -79,18 +88,19 @@ const useTriggerEventsHandlers = ({ propsWithDefault, floatingContext }) => {
       setReference(node);
       if (innerRef) (0, import_resolveRef.resolveRef)(innerRef, node);
     },
-    [innerRef, reRenderButtonToAllowFocus, setReference, shouldFocusImmediately]
+    [innerRef, reRenderButtonToAllowFocus, setReference, shouldFocusImmediately, shouldRefocusTrigger]
   );
   const handleTriggerKeyDown = import_react.default.useCallback(
     (event, ...args) => {
       if (event.key === "ArrowDown") {
-        onOpinionatedOpen();
+        onOpinionatedOpen({ reason: "trigger-arrow-down", event });
       }
       if (event.key === "ArrowUp") {
-        onOpinionatedOpen({ focusLastChild: true });
+        onOpinionatedOpen({ focusLastChild: true, reason: "trigger-arrow-up", event });
       }
       if (event.key === "Escape") {
-        onOpinionatedClose();
+        if (mutableIsMenuOpen.current) event.stopPropagation();
+        onOpinionatedClose({ reason: "escape", event });
       }
       if (onKeyDown) onKeyDown(event, ...args);
     },

package/dist/cjs/parts/DSOpinionatedButton/config/useTriggerEventsHandlers.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/parts/DSOpinionatedButton/config/useTriggerEventsHandlers.ts", "../../../../../../../../scripts/build/transpile/react-shim.js"],
-  "sourcesContent": ["import type { DSButtonV3T } from '@elliemae/ds-button-v2';\nimport { type useFloatingContext } from '@elliemae/ds-floating-context';\nimport React from 'react';\nimport { resolveRef } from '../../../utils/resolveRef.js';\nimport { MenuBehaviouralContextProviderContext } from '../../DSMenuBehaviouralContextProvider/MenuBehaviouralContextProviderCTX.js';\nimport { MENU_FOCUS_REGIONS } from '../../DSMenuBehaviouralContextProvider/constants/index.js';\nimport { type DSOpinionatedButtonT } from '../react-desc-prop-types.js';\n\ntype UseTriggerEventsHandlersConfig = {\n  propsWithDefault: DSOpinionatedButtonT.InternalProps;\n  floatingContext: ReturnType<typeof useFloatingContext>;\n};\n\nexport const useTriggerEventsHandlers = ({ propsWithDefault, floatingContext }: UseTriggerEventsHandlersConfig) => {\n  // =============================================================================\n  // on click -> open the submenu\n  //  if the props already include an onClick, we will wrap it\n  // =============================================================================\n  const { focusRegion, isMenuOpen, onOpinionatedOpen, onOpinionatedClose, trackFocusTrigger, shouldFocusImmediately } =\n    React.useContext(MenuBehaviouralContextProviderContext);\n  const { onClick, onFocus, innerRef, onKeyDown } = propsWithDefault;\n  const {\n    refs: { setReference },\n  } = floatingContext;\n\n  const focusedRegionPerformanceHelper = React.useRef(focusRegion);\n  // when the focus region is on the trigger, we need to re-render the button so it invokes the ref callback again to focus itself\n  //   we don't need to rerender at every focus region change, only when it changes to the trigger itself.\n  // by checking the ref stored value against the current focus region, the flag will stay mostly false and change to true only when needed\n  const reRenderButtonToAllowFocus =\n    focusRegion === MENU_FOCUS_REGIONS.TRIGGER && focusedRegionPerformanceHelper.current !== focusRegion;\n  focusedRegionPerformanceHelper.current = focusRegion;\n\n  const mutableIsMenuOpen = React.useRef(isMenuOpen);\n  // this is a boolean, so a primitive value,\n  //   we don't need to useEffect to change it\n  //   because we don't need to ensure referencial equality\n  mutableIsMenuOpen.current = isMenuOpen;\n\n  const handleOnClick = React.useCallback<Required<DSButtonV3T.Props>['onClick']>(\n    (e, ...args) => {\n      if (onClick) onClick(e, ...args);\n      // no reason to change this function reference every time the menu opens/closes\n      //  so we are using a mutable ref to optimize this\n      if (mutableIsMenuOpen.current) {\n        onOpinionatedClose();\n      } else {\n        onOpinionatedOpen();\n      }\n    },\n    [onClick, onOpinionatedClose, onOpinionatedOpen],\n  );\n  const handleOnFocus = React.useCallback<Required<DSButtonV3T.Props>['onFocus']>(\n    (e, ...args) => {\n      if (focusedRegionPerformanceHelper.current !== MENU_FOCUS_REGIONS.TRIGGER) trackFocusTrigger();\n      if (onFocus) onFocus(e, ...args);\n    },\n    [onFocus, trackFocusTrigger],\n  );\n\n  const handleFocusIfTriggerIsFocusRegion = React.useCallback<React.RefCallback<HTMLButtonElement>>(\n    (node) => {\n      if (reRenderButtonToAllowFocus && node) {\n        // when user presses \"Enter\" different things happen depending on top of what element the focus is\n        //   if it is in the trigger (this function) then it spawns the submenu and focuses the first item\n        //   if it is in a menu item, it activates the item and closes the menu, triggering this function again\n        // So, why do we need the requestAnimationFrame?\n        //   pressing enter in an item will focus the trigger\n        //      -> current react behaviour means the menu button \"keyDown\" event will also trigger with \"Enter\"\n        //        -> which will open the menu again\n        // as of react 18 and 28/october/2025, this requestAnimationFrame prevents the keyDown event from triggering on top of the button\n        if (!shouldFocusImmediately.current) {\n          requestAnimationFrame(() => {\n            node.focus();\n          });\n        } else {\n          // In some cases, like when user presses \"Tab\" within a menu, we want to focus the trigger immediately.\n          // So that the tab flow occurs from the trigger to the next focusable element in the page.\n          // Therefore, we don't need to wait for the next frame.\n          node.focus();\n        }\n      }\n      setReference(node);\n      if (innerRef) resolveRef(innerRef, node);\n    },\n    [innerRef, reRenderButtonToAllowFocus, setReference, shouldFocusImmediately],\n  );\n\n  /*\n   * 13th August 2024:\n   * https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/\n   * With focus on the button:\n   * Enter: opens the menu and places focus on the first menu item.\n   * Space: Opens the menu and places focus on the first menu item.\n   * (Optional) Down Arrow: opens the menu and moves focus to the first menu item.\n   * (Optional) Up Arrow: opens the menu and moves focus to the last menu item.\n   */\n  const handleTriggerKeyDown = React.useCallback<Required<DSButtonV3T.Props>['onKeyDown']>(\n    (event, ...args) => {\n      // DSButtonV3 triggers the onClick on Enter and Space, so we don't need to handle it here\n      // if (event.key === 'Enter' || event.key === ' ') {\n      //   onOpinionatedOpen();\n      // }\n      if (event.key === 'ArrowDown') {\n        onOpinionatedOpen();\n      }\n      if (event.key === 'ArrowUp') {\n        onOpinionatedOpen({ focusLastChild: true });\n      }\n      if (event.key === 'Escape') {\n        onOpinionatedClose();\n      }\n      if (onKeyDown) onKeyDown(event, ...args);\n    },\n    [onKeyDown, onOpinionatedOpen, onOpinionatedClose],\n  );\n\n  return React.useMemo(\n    () => ({ handleTriggerKeyDown, handleOnClick, handleOnFocus, handleFocusIfTriggerIsFocusRegion }),\n    [handleFocusIfTriggerIsFocusRegion, handleOnClick, handleOnFocus, handleTriggerKeyDown],\n  );\n};\n", "import * as React from 'react';\nexport { React };\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADEvB,mBAAkB;AAClB,wBAA2B;AAC3B,+CAAsD;AACtD,uBAAmC;AAQ5B,MAAM,2BAA2B,CAAC,EAAE,kBAAkB,gBAAgB,MAAsC;AAKjH,QAAM,EAAE,aAAa,YAAY,mBAAmB,oBAAoB,mBAAmB,uBAAuB,IAChH,aAAAA,QAAM,WAAW,8EAAqC;AACxD,QAAM,EAAE,SAAS,SAAS,UAAU,UAAU,IAAI;AAClD,QAAM;AAAA,IACJ,MAAM,EAAE,aAAa;AAAA,EACvB,IAAI;AAEJ,QAAM,iCAAiC,aAAAA,QAAM,OAAO,WAAW;AAI/D,QAAM,6BACJ,gBAAgB,oCAAmB,WAAW,+BAA+B,YAAY;AAC3F,iCAA+B,UAAU;AAEzC,QAAM,oBAAoB,aAAAA,QAAM,OAAO,UAAU;AAIjD,oBAAkB,UAAU;AAE5B,QAAM,gBAAgB,aAAAA,QAAM;AAAA,IAC1B,CAAC,MAAM,SAAS;AACd,UAAI,QAAS,SAAQ,GAAG,GAAG,IAAI;AAG/B,UAAI,kBAAkB,SAAS;AAC7B,2BAAmB;AAAA,MACrB,OAAO;AACL,0BAAkB;AAAA,MACpB;AAAA,IACF;AAAA,IACA,CAAC,SAAS,oBAAoB,iBAAiB;AAAA,EACjD;AACA,QAAM,gBAAgB,aAAAA,QAAM;AAAA,IAC1B,CAAC,MAAM,SAAS;AACd,UAAI,+BAA+B,YAAY,oCAAmB,QAAS,mBAAkB;AAC7F,UAAI,QAAS,SAAQ,GAAG,GAAG,IAAI;AAAA,IACjC;AAAA,IACA,CAAC,SAAS,iBAAiB;AAAA,EAC7B;AAEA,QAAM,oCAAoC,aAAAA,QAAM;AAAA,IAC9C,CAAC,SAAS;AACR,UAAI,8BAA8B,MAAM;AAStC,YAAI,CAAC,uBAAuB,SAAS;AACnC,gCAAsB,MAAM;AAC1B,iBAAK,MAAM;AAAA,UACb,CAAC;AAAA,QACH,OAAO;AAIL,eAAK,MAAM;AAAA,QACb;AAAA,MACF;AACA,mBAAa,IAAI;AACjB,UAAI,SAAU,mCAAW,UAAU,IAAI;AAAA,IACzC;AAAA,IACA,CAAC,UAAU,4BAA4B,cAAc,sBAAsB;AAAA,EAC7E;AAWA,QAAM,uBAAuB,aAAAA,QAAM;AAAA,IACjC,CAAC,UAAU,SAAS;AAKlB,UAAI,MAAM,QAAQ,aAAa;AAC7B,0BAAkB;AAAA,MACpB;AACA,UAAI,MAAM,QAAQ,WAAW;AAC3B,0BAAkB,EAAE,gBAAgB,KAAK,CAAC;AAAA,MAC5C;AACA,UAAI,MAAM,QAAQ,UAAU;AAC1B,2BAAmB;AAAA,MACrB;AACA,UAAI,UAAW,WAAU,OAAO,GAAG,IAAI;AAAA,IACzC;AAAA,IACA,CAAC,WAAW,mBAAmB,kBAAkB;AAAA,EACnD;AAEA,SAAO,aAAAA,QAAM;AAAA,IACX,OAAO,EAAE,sBAAsB,eAAe,eAAe,kCAAkC;AAAA,IAC/F,CAAC,mCAAmC,eAAe,eAAe,oBAAoB;AAAA,EACxF;AACF;",
+  "sourcesContent": ["import type { DSButtonV3T } from '@elliemae/ds-button-v2';\nimport { type useFloatingContext } from '@elliemae/ds-floating-context';\nimport React from 'react';\nimport { resolveRef } from '../../../utils/resolveRef.js';\nimport { MenuBehaviouralContextProviderContext } from '../../DSMenuBehaviouralContextProvider/MenuBehaviouralContextProviderCTX.js';\nimport { MENU_FOCUS_REGIONS } from '../../DSMenuBehaviouralContextProvider/constants/index.js';\nimport { type DSOpinionatedButtonT } from '../react-desc-prop-types.js';\n\ntype UseTriggerEventsHandlersConfig = {\n  propsWithDefault: DSOpinionatedButtonT.InternalProps;\n  floatingContext: ReturnType<typeof useFloatingContext>;\n};\n\nexport const useTriggerEventsHandlers = ({ propsWithDefault, floatingContext }: UseTriggerEventsHandlersConfig) => {\n  // =============================================================================\n  // on click -> open the submenu\n  //  if the props already include an onClick, we will wrap it\n  // =============================================================================\n  const {\n    focusRegion,\n    isMenuOpen,\n    onOpinionatedOpen,\n    onOpinionatedClose,\n    trackFocusTrigger,\n    shouldFocusImmediately,\n    shouldRefocusTrigger,\n  } = React.useContext(MenuBehaviouralContextProviderContext);\n  const { onClick, onFocus, innerRef, onKeyDown } = propsWithDefault;\n  const {\n    refs: { setReference },\n  } = floatingContext;\n\n  const focusedRegionPerformanceHelper = React.useRef(focusRegion);\n  // when the focus region is on the trigger, we need to re-render the button so it invokes the ref callback again to focus itself\n  //   we don't need to rerender at every focus region change, only when it changes to the trigger itself.\n  // by checking the ref stored value against the current focus region, the flag will stay mostly false and change to true only when needed\n  const reRenderButtonToAllowFocus =\n    focusRegion === MENU_FOCUS_REGIONS.TRIGGER && focusedRegionPerformanceHelper.current !== focusRegion;\n  focusedRegionPerformanceHelper.current = focusRegion;\n\n  const mutableIsMenuOpen = React.useRef(isMenuOpen);\n  // this is a boolean, so a primitive value,\n  //   we don't need to useEffect to change it\n  //   because we don't need to ensure referencial equality\n  mutableIsMenuOpen.current = isMenuOpen;\n\n  const handleOnClick = React.useCallback<Required<DSButtonV3T.Props>['onClick']>(\n    (e, ...args) => {\n      if (onClick) onClick(e, ...args);\n      // no reason to change this function reference every time the menu opens/closes\n      //  so we are using a mutable ref to optimize this\n      if (mutableIsMenuOpen.current) {\n        onOpinionatedClose({ reason: 'trigger-toggle', event: e });\n      } else {\n        onOpinionatedOpen({ reason: 'trigger-click', event: e });\n      }\n    },\n    [onClick, onOpinionatedClose, onOpinionatedOpen],\n  );\n  const handleOnFocus = React.useCallback<Required<DSButtonV3T.Props>['onFocus']>(\n    (e, ...args) => {\n      if (focusedRegionPerformanceHelper.current !== MENU_FOCUS_REGIONS.TRIGGER)\n        // passive tracking only: focus is ALREADY on the trigger by definition of this event,\n        //   so it must not be re-requested \u2014 a deferred refocus would race a Tab\n        //   that has already legitimately moved focus to the next element, and could win, stealing it back\n        trackFocusTrigger({ shouldFocusImmediately: false, refocusTrigger: false });\n      if (onFocus) onFocus(e, ...args);\n    },\n    [onFocus, trackFocusTrigger],\n  );\n\n  const handleFocusIfTriggerIsFocusRegion = React.useCallback<React.RefCallback<HTMLButtonElement>>(\n    (node) => {\n      if (reRenderButtonToAllowFocus && node && shouldRefocusTrigger.current) {\n        // when user presses \"Enter\" different things happen depending on top of what element the focus is\n        //   if it is in the trigger (this function) then it spawns the submenu and focuses the first item\n        //   if it is in a menu item, it activates the item and closes the menu, triggering this function again\n        // So, why do we need the requestAnimationFrame?\n        //   pressing enter in an item will focus the trigger\n        //      -> current react behaviour means the menu button \"keyDown\" event will also trigger with \"Enter\"\n        //        -> which will open the menu again\n        // as of react 18 and 28/october/2025, this requestAnimationFrame prevents the keyDown event from triggering on top of the button\n        if (!shouldFocusImmediately.current) {\n          requestAnimationFrame(() => {\n            node.focus();\n          });\n        } else {\n          // In some cases, like when user presses \"Tab\" within a menu, we want to focus the trigger immediately.\n          // So that the tab flow occurs from the trigger to the next focusable element in the page.\n          // Therefore, we don't need to wait for the next frame.\n          node.focus();\n        }\n      }\n      setReference(node);\n      if (innerRef) resolveRef(innerRef, node);\n    },\n    [innerRef, reRenderButtonToAllowFocus, setReference, shouldFocusImmediately, shouldRefocusTrigger],\n  );\n\n  /*\n   * 13th August 2024:\n   * https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/\n   * With focus on the button:\n   * Enter: opens the menu and places focus on the first menu item.\n   * Space: Opens the menu and places focus on the first menu item.\n   * (Optional) Down Arrow: opens the menu and moves focus to the first menu item.\n   * (Optional) Up Arrow: opens the menu and moves focus to the last menu item.\n   */\n  const handleTriggerKeyDown = React.useCallback<Required<DSButtonV3T.Props>['onKeyDown']>(\n    (event, ...args) => {\n      // DSButtonV3 triggers the onClick on Enter and Space, so we don't need to handle it here\n      // if (event.key === 'Enter' || event.key === ' ') {\n      //   onOpinionatedOpen();\n      // }\n      if (event.key === 'ArrowDown') {\n        onOpinionatedOpen({ reason: 'trigger-arrow-down', event });\n      }\n      if (event.key === 'ArrowUp') {\n        onOpinionatedOpen({ focusLastChild: true, reason: 'trigger-arrow-up', event });\n      }\n      if (event.key === 'Escape') {\n        // the menu consumes the Escape only when it is open: the event must not also reach an ancestor that closes on\n        //   Escape (DSDialog, DSModalSlide... React bubbles through portals). A closed menu has nothing to close,\n        //   so the Escape keeps propagating and the ancestor still gets it.\n        if (mutableIsMenuOpen.current) event.stopPropagation();\n        onOpinionatedClose({ reason: 'escape', event });\n      }\n      if (onKeyDown) onKeyDown(event, ...args);\n    },\n    [onKeyDown, onOpinionatedOpen, onOpinionatedClose],\n  );\n\n  return React.useMemo(\n    () => ({ handleTriggerKeyDown, handleOnClick, handleOnFocus, handleFocusIfTriggerIsFocusRegion }),\n    [handleFocusIfTriggerIsFocusRegion, handleOnClick, handleOnFocus, handleTriggerKeyDown],\n  );\n};\n", "import * as React from 'react';\nexport { React };\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADEvB,mBAAkB;AAClB,wBAA2B;AAC3B,+CAAsD;AACtD,uBAAmC;AAQ5B,MAAM,2BAA2B,CAAC,EAAE,kBAAkB,gBAAgB,MAAsC;AAKjH,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,IAAI,aAAAA,QAAM,WAAW,8EAAqC;AAC1D,QAAM,EAAE,SAAS,SAAS,UAAU,UAAU,IAAI;AAClD,QAAM;AAAA,IACJ,MAAM,EAAE,aAAa;AAAA,EACvB,IAAI;AAEJ,QAAM,iCAAiC,aAAAA,QAAM,OAAO,WAAW;AAI/D,QAAM,6BACJ,gBAAgB,oCAAmB,WAAW,+BAA+B,YAAY;AAC3F,iCAA+B,UAAU;AAEzC,QAAM,oBAAoB,aAAAA,QAAM,OAAO,UAAU;AAIjD,oBAAkB,UAAU;AAE5B,QAAM,gBAAgB,aAAAA,QAAM;AAAA,IAC1B,CAAC,MAAM,SAAS;AACd,UAAI,QAAS,SAAQ,GAAG,GAAG,IAAI;AAG/B,UAAI,kBAAkB,SAAS;AAC7B,2BAAmB,EAAE,QAAQ,kBAAkB,OAAO,EAAE,CAAC;AAAA,MAC3D,OAAO;AACL,0BAAkB,EAAE,QAAQ,iBAAiB,OAAO,EAAE,CAAC;AAAA,MACzD;AAAA,IACF;AAAA,IACA,CAAC,SAAS,oBAAoB,iBAAiB;AAAA,EACjD;AACA,QAAM,gBAAgB,aAAAA,QAAM;AAAA,IAC1B,CAAC,MAAM,SAAS;AACd,UAAI,+BAA+B,YAAY,oCAAmB;AAIhE,0BAAkB,EAAE,wBAAwB,OAAO,gBAAgB,MAAM,CAAC;AAC5E,UAAI,QAAS,SAAQ,GAAG,GAAG,IAAI;AAAA,IACjC;AAAA,IACA,CAAC,SAAS,iBAAiB;AAAA,EAC7B;AAEA,QAAM,oCAAoC,aAAAA,QAAM;AAAA,IAC9C,CAAC,SAAS;AACR,UAAI,8BAA8B,QAAQ,qBAAqB,SAAS;AAStE,YAAI,CAAC,uBAAuB,SAAS;AACnC,gCAAsB,MAAM;AAC1B,iBAAK,MAAM;AAAA,UACb,CAAC;AAAA,QACH,OAAO;AAIL,eAAK,MAAM;AAAA,QACb;AAAA,MACF;AACA,mBAAa,IAAI;AACjB,UAAI,SAAU,mCAAW,UAAU,IAAI;AAAA,IACzC;AAAA,IACA,CAAC,UAAU,4BAA4B,cAAc,wBAAwB,oBAAoB;AAAA,EACnG;AAWA,QAAM,uBAAuB,aAAAA,QAAM;AAAA,IACjC,CAAC,UAAU,SAAS;AAKlB,UAAI,MAAM,QAAQ,aAAa;AAC7B,0BAAkB,EAAE,QAAQ,sBAAsB,MAAM,CAAC;AAAA,MAC3D;AACA,UAAI,MAAM,QAAQ,WAAW;AAC3B,0BAAkB,EAAE,gBAAgB,MAAM,QAAQ,oBAAoB,MAAM,CAAC;AAAA,MAC/E;AACA,UAAI,MAAM,QAAQ,UAAU;AAI1B,YAAI,kBAAkB,QAAS,OAAM,gBAAgB;AACrD,2BAAmB,EAAE,QAAQ,UAAU,MAAM,CAAC;AAAA,MAChD;AACA,UAAI,UAAW,WAAU,OAAO,GAAG,IAAI;AAAA,IACzC;AAAA,IACA,CAAC,WAAW,mBAAmB,kBAAkB;AAAA,EACnD;AAEA,SAAO,aAAAA,QAAM;AAAA,IACX,OAAO,EAAE,sBAAsB,eAAe,eAAe,kCAAkC;AAAA,IAC/F,CAAC,mCAAmC,eAAe,eAAe,oBAAoB;AAAA,EACxF;AACF;",
   "names": ["React"]
 }

package/dist/cjs/react-desc-prop-types.js

@@ -62,8 +62,15 @@ const MenuBehaviouralLayerPropTypes = {
       itemNode: DSMenuButtonT.PseudoFocusableMenuNodes,
       metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },
     ) => void)`),
-  onOpen: import_ds_props_helpers.PropTypes.func.description("function triggered when the widget opens the menu").signature(`(()=>void)`),
-  onClose: import_ds_props_helpers.PropTypes.func.description("function triggered when the widget closes the menu").signature(`(()=>void)`),
+  onOpen: import_ds_props_helpers.PropTypes.func.description("function triggered when the widget opens the menu, with the reason (intent) that triggered it").signature(
+    `((metainfo: { reason: 'trigger-click' | 'trigger-arrow-down' | 'trigger-arrow-up'; event?: React.SyntheticEvent }) => void)`
+  ),
+  onClose: import_ds_props_helpers.PropTypes.func.description("function triggered when the widget closes the menu, with the reason (intent) that triggered it").signature(
+    `((metainfo: { reason: 'outside-click' | 'window-blur' | 'escape' | 'tab' | 'item-activation' | 'trigger-toggle'; event?: React.SyntheticEvent | MouseEvent | TouchEvent | FocusEvent }) => void)`
+  ),
+  a11yDangerouslyConsumerOwnedMenuOpenState: import_ds_props_helpers.PropTypes.bool.description(
+    "Escape hatch: when a boolean is provided, the consumer owns the menu open state; onOpen/onClose fire for each intent that changes the effective state, and the consumer is expected to sync the prop from them. Invalidates the open-state-related a11y guarantees of the widget"
+  ),
   onDisplayedSubmenuChange: import_ds_props_helpers.PropTypes.func.description("function triggered when the widget's closes or opens a submenu").signature(`((
       newOpenedItems: DSMenuButtonT.PseudoFocusableMenuNodes[],
       metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },

package/dist/cjs/react-desc-prop-types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/react-desc-prop-types.ts", "../../../../../scripts/build/transpile/react-shim.js"],
-  "sourcesContent": ["/* eslint-disable max-lines */\n/* eslint-disable @typescript-eslint/no-empty-interface */\nimport { PropTypes, getPropsPerSlotPropTypes } from '@elliemae/ds-props-helpers';\nimport { DSButtonV3PropTypes } from '@elliemae/ds-button-v2';\nimport type { DSPropTypesSchema, ValidationMap } from '@elliemae/ds-props-helpers';\nimport { type TypescriptHelpersT } from '@elliemae/ds-typescript-helpers';\nimport type { DSButtonV3T } from '@elliemae/ds-button-v2';\nimport type { UseDSTreeT } from '@elliemae/ds-tree-model';\nimport type { DSHookFloatingContextT } from '@elliemae/ds-floating-context';\n\nimport { DSMenuButtonName, MENU_BUTTON_SLOTS, type MENU_ITEMS_TYPES } from './constants/index.js';\nexport declare namespace DSMenuButtonT {\n  /* *******************************************************\n   * Slot function-form prop arguments \u2014 one entry per slot in MENU_BUTTON_SLOTS.\n   * Backs the typescript-testing/slot-props.ts exhaustiveness check.\n   ******************************************************* */\n  export type SlotFunctionArguments = {\n    dsMenubuttonRoot: () => object;\n  };\n\n  /* *******************************************************\n   * YURI's NOTE:\n   *\n   * This polymorphic interface \"looks similar\" between the diffent types\n   *  but it's actually different upon closer inspection\n   *\n   * If you are smarter then me, you can probably find a way to make this more DRY\n   *  but I prefeer AHA (Avoid Hasty Abstractions) that gives me an easier to mantain code\n   *   ESPECIALLY when the types are so similar but not the same & in typescript (polymorphism is hard in TS)\n   *\n   * So I'm going to keep them separate and explicit\n   *  key difference is what's required to exist and what is required to explicitly NOT exist\n   *\n   * If someone's review this and make this DRY, I'm NOT going to mantain this code moving forward\n   *   whoever makes this TS DRY will be responsible for it and own it.\n   ******************************************************* */\n\n  /* **************************************************************************************************************\n   *********************************** POLYMORPHIC INTERFACES FOR MENU ITEMS  *************************************\n   ************************************************************************************************************** */\n  export interface RootItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: 'ROOT_ITEM'; // HARDCODED BECAUSE THIS IS NOT A MENU ITEM, IT'S EXCLUSIVE TO THE ROOT NODE\n    dsId: string;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    label?: undefined;\n    secondaryLabel?: undefined;\n    leftDecoration?: undefined;\n    minWidth?: undefined;\n    disabled?: undefined;\n    onClick?: undefined;\n    onKeyDown?: undefined;\n  }\n  export interface SeparatorItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SEPARATOR'];\n    dsId: string;\n    label?: undefined;\n    secondaryLabel?: undefined;\n    leftDecoration?: undefined;\n    minWidth?: undefined;\n    disabled?: undefined;\n    onClick?: undefined;\n    onKeyDown?: undefined;\n  }\n  export interface ActivableItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['ACTIVABLE_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface ActionableWithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['ACTIVABLE_WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface SkeletonItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SKELETON_ITEM'];\n    dsId: string;\n    minWidth?: string | number;\n    label?: undefined;\n    secondaryLabel?: undefined;\n    leftDecoration?: undefined;\n    disabled?: undefined;\n    onClick?: undefined;\n    onKeyDown?: undefined;\n  }\n  export interface MultipleSelectItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['MULTIPLE_SELECT_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n\n  export interface MultiSelectWithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['MULTIPLE_SELECT_WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface WithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface SingleSelectItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SINGLE_SELECT_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface SingleSelectWithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SINGLE_SELECT_WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n\n  export interface GroupItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['GROUP'];\n    dsId: string;\n    label?: string; // if present, add a title to the group\n    leftDecoration?: React.ComponentType; // if present, a label must also be present\n    minWidth?: string | number;\n  }\n\n  export type MenuItemInterface =\n    | SeparatorItem\n    | ActivableItem\n    | ActionableWithSubmenuItem\n    | SkeletonItem\n    | MultipleSelectItem\n    | MultiSelectWithSubmenuItem\n    | WithSubmenuItem\n    | GroupItem\n    | SingleSelectItem\n    | SingleSelectWithSubmenuItem;\n\n  export type PseudoFocusableItemInterface =\n    | ActivableItem\n    | ActionableWithSubmenuItem\n    | SkeletonItem\n    | MultipleSelectItem\n    | MultiSelectWithSubmenuItem\n    | WithSubmenuItem\n    | SingleSelectItem\n    | SingleSelectWithSubmenuItem;\n\n  export type SelectionableMenuItemInterface =\n    MultipleSelectItem | MultiSelectWithSubmenuItem | SingleSelectItem | SingleSelectWithSubmenuItem;\n\n  /* **************************************************************************************************************\n   *************************** POLYMORPHIC INTERFACES FOR ITEMS USING DSTREE  *************************************\n   ************************************************************************************************************** */\n  // Define MenuNode types directly\n  export type MenuNodeRootItem = UseDSTreeT.TreeNode<RootItem>; // MenuNodesAllowedToHaveChildren is the only expected reference to this type\n  export type MenuNodeSeparatorItem = UseDSTreeT.TreeNode<SeparatorItem>;\n  export type MenuNodeActivableItem = UseDSTreeT.TreeNode<ActivableItem>;\n  export type MenuNodeActivableWithSubmenuItem = UseDSTreeT.TreeNode<ActionableWithSubmenuItem>;\n  export type MenuNodeSkeletonItem = UseDSTreeT.TreeNode<SkeletonItem>;\n  export type MenuNodeMultipleSelectItem = UseDSTreeT.TreeNode<MultipleSelectItem>;\n  export type MenuNodeMultipleSelectWithSubmenuItem = UseDSTreeT.TreeNode<MultiSelectWithSubmenuItem>;\n  export type MenuNodeWithSubmenuItem = UseDSTreeT.TreeNode<WithSubmenuItem>;\n  export type MenuNodeSingleSelectItem = UseDSTreeT.TreeNode<SingleSelectItem>;\n  export type MenuNodeSingleSelectWithSubmenuItem = UseDSTreeT.TreeNode<SingleSelectWithSubmenuItem>;\n  export type MenuNodeGroupItem = UseDSTreeT.TreeNode<GroupItem>;\n\n  // in the future we want to better describe the polymorphic nature of the MenuNode\n  //  having each type be able to have it's own \"subitems\" type that isn't necessarily the same as the parent\n  //  but currenctly the DS tree model typescript definitions don't support this\n  //  will be addresssed via PUI-XXXX\n  export type MenuNode =\n    // DO NOT ADD MenuNodeRootItem HERE, WILL BREAK THE SUBTREES\n    | MenuNodeSeparatorItem\n    | MenuNodeActivableItem\n    | MenuNodeActivableWithSubmenuItem\n    | MenuNodeSkeletonItem\n    | MenuNodeMultipleSelectItem\n    | MenuNodeMultipleSelectWithSubmenuItem\n    | MenuNodeWithSubmenuItem\n    | MenuNodeSingleSelectItem\n    | MenuNodeSingleSelectWithSubmenuItem\n    | MenuNodeGroupItem;\n\n  export type PseudoFocusableMenuNodes =\n    | MenuNodeActivableItem\n    | MenuNodeActivableWithSubmenuItem\n    | MenuNodeSkeletonItem\n    | MenuNodeSingleSelectItem\n    | MenuNodeMultipleSelectItem\n    | MenuNodeMultipleSelectWithSubmenuItem\n    | MenuNodeWithSubmenuItem\n    | MenuNodeSingleSelectWithSubmenuItem;\n\n  export type MenuNodesAllowedToHaveChildren =\n    | MenuNodeRootItem\n    | MenuNodeWithSubmenuItem\n    | MenuNodeGroupItem\n    | MenuNodeActivableWithSubmenuItem\n    | MenuNodeMultipleSelectWithSubmenuItem\n    | MenuNodeSingleSelectWithSubmenuItem;\n\n  export type SelectionableMenuNodes =\n    | DSMenuButtonT.MenuNodeMultipleSelectItem\n    | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem\n    | DSMenuButtonT.MenuNodeSingleSelectItem\n    | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  export type MultipleSelectionableMenuNodes =\n    DSMenuButtonT.MenuNodeMultipleSelectItem | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem;\n\n  export type SingleSelectionableMenuNodes =\n    DSMenuButtonT.MenuNodeSingleSelectItem | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  export type WithSubmenuMenuNodes =\n    | DSMenuButtonT.MenuNodeWithSubmenuItem\n    | DSMenuButtonT.MenuNodeActivableWithSubmenuItem\n    | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem\n    | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  export type SelectionablesWithSubmenuMenuNodes =\n    DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  /* **************************************************************************************************************\n   ********************************** PROPS/INTERNAL PROPS DEFINITIONS  *******************************************\n   ************************************************************************************************************** */\n\n  export type ItemRendererT = React.ComponentType<{ itemNode: MenuNode }>;\n\n  /* **************************************************************************************************************\n   ******************************************* \"REQUIRED\" PROPS  **************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * From official source definition\n   *\n   * Menu Button Pattern\n   *  About This Pattern:\n   *    A menu button is a button\n   *      that opens a menu\n   *         (as described in the Menu and Menubar Pattern).\n   *\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   *\n   * This is effectively an OOP \"extension\" of the Button component,\n   *  so it has the same props,\n   *  BUT also a few more to handle the specific behavior of the menu.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificRequiredProps {}\n  /* *******************************************************\n   * Required Props + Inherited Required Props\n   *  - We inherit the required props from the button\n   *  - We add the required props for the menu\n   *\n   *  - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  export interface ButtonInheritedRequiredProps\n    // by using Omit, we remove the keys that are present in the MenuSpecificRequiredProps to ensure collision are handled as expected\n    extends Omit<DSButtonV3T.RequiredProps, keyof MenuSpecificRequiredProps> {}\n  // the final RequiredProps will be the combination of the two with proper collision handling\n  export interface RequiredProps\n    extends MenuSpecificRequiredProps, ButtonInheritedRequiredProps, MenuBehaviouralLayerRequiredProps {\n    // it's the Menu Widget sole responsibility to receive the options and convert them to a tree\n    options: MenuItemInterface[] | MenuNode;\n  }\n\n  /* **************************************************************************************************************\n   ******************************************** \"DEFAULT\" PROPS  **************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerDefaultProps {}\n  export interface MenuSpecifiDefaultProps {\n    onClickOutside: (e: MouseEvent | React.KeyboardEvent | TouchEvent) => void;\n    onOptionClick: (\n      nextSelectedOptions: Record<string, boolean>,\n      clickedOption: MenuItemInterface,\n      e: React.MouseEvent | React.KeyboardEvent,\n    ) => void;\n    openedSubmenus: Record<string, boolean>;\n    onSubmenuToggle: (\n      nextOpenedSubmenus: Record<string, boolean>,\n      submenu: MenuItemInterface,\n      e: React.MouseEvent | React.KeyboardEvent,\n    ) => void;\n    isLoading: boolean;\n    isSkeleton: boolean;\n    maxHeight: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n  }\n\n  /* *******************************************************\n   * Default Props + Inherited Default Props\n   *  - We inherit the default props from the button\n   *  - We add the default props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  // by using Omit, we remove the keys that are present in the MenuSpecificDefaultProps to ensure collision are handled as expected\n  export interface ButtonInheiredDefaultProps extends Omit<DSButtonV3T.DefaultProps, keyof MenuSpecifiDefaultProps> {}\n  // the final DefaultProps will be the combination of the two with proper collision handling\n  export interface DefaultProps\n    extends MenuSpecifiDefaultProps, ButtonInheiredDefaultProps, MenuBehaviouralLayerDefaultProps {}\n\n  /* **************************************************************************************************************\n   ******************************************* \"OPTIONAL\" PROPS  **************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerOptionalProps {\n    // **********************************************************************************************\n    // IoC Pattern\n    //   - in scenarios where not \"selectionable\" items are present,\n    //      - the \"selectedItems\" prop is not required\n    //      - the \"onItemSelected\" prop is not required\n    //   - in scenarios where no \"activation\" items are present,\n    //      - the \"onActivateItem\" prop is not required\n    // AFAIK Typescipt doesn't support this kind of \"conditional\" required props\n    //   so we will rely on javascript error throwing to handle this + documentation\n    // **********************************************************************************************\n    onItemSelected?: (\n      newSelection: SelectionableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.SelectionableMenuNodes; event?: React.SyntheticEvent },\n    ) => void | TypescriptHelpersT.StateSetter<DSMenuButtonT.SelectionableMenuNodes[]>;\n    onActivateItem?: (\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes,\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void;\n    // **********************************************************************************************\n    onOpen?: () => void;\n    onClose?: () => void;\n    onDisplayedSubmenuChange?: (\n      newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[],\n      metainfo: {\n        itemNode: DSMenuButtonT.PseudoFocusableMenuNodes | null;\n        event?: React.SyntheticEvent | FocusEvent | TouchEvent;\n      },\n    ) => void | TypescriptHelpersT.StateSetter<DSMenuButtonT.WithSubmenuMenuNodes[]>;\n  }\n  export interface MenuSpecificOptionalProps {\n    ItemRenderer?: ItemRendererT;\n    floatingConfig?: Partial<Omit<DSHookFloatingContextT.Props, 'externallyControlledIsOpen' | 'onOpen' | 'onClose'>>;\n  }\n  /* *******************************************************\n   * Optional Props + Inherited Optional Props\n   *  - We inherit the optional props from the button\n   *  - We add the optional props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  export interface ButtonInheritedOptionalProps\n    // by using Omit, we remove the keys that are present in the MenuSpecificOptionalProps to ensure collision are handled as expected\n    extends Omit<DSButtonV3T.OptionalProps, keyof MenuSpecificOptionalProps> {}\n  export interface OptionalProps\n    extends\n      MenuSpecificOptionalProps,\n      ButtonInheritedOptionalProps,\n      // we convert the (selected) options to a Nodes as part of the widget's logic\n      MenuBehaviouralLayerOptionalProps,\n      TypescriptHelpersT.PropsForGlobalOnSlots<typeof DSMenuButtonName, typeof MENU_BUTTON_SLOTS> {\n    // we convert the (selected) options to a Nodes as part of the widget's logic\n    selectedItems?: SelectionableMenuNodes[] | SelectionableMenuItemInterface[];\n  }\n\n  /* **************************************************************************************************************\n   ************************************************  PROPS  *******************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerProps\n    extends\n      Partial<MenuBehaviouralLayerDefaultProps>,\n      MenuBehaviouralLayerOptionalProps,\n      MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificProps\n    extends Partial<MenuSpecifiDefaultProps>, MenuSpecificOptionalProps, MenuSpecificRequiredProps {}\n  /* *******************************************************\n   * Props + Inherited Props\n   *  - We inherit the props from the button\n   *  - We add the props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  // by using Omit, we remove the keys that are present in the MenuSpecificProps to ensure collision are handled as expected\n  //  THIS IS ALSO INHERITING THE GLOBAL ATTRIBUTES & XSTYLED PROPS FROM THE BUTTON!!!\n  export interface ButtonInheritedProps extends Omit<DSButtonV3T.Props, keyof MenuSpecificProps> {}\n\n  export interface Props\n    extends\n      RequiredProps,\n      Partial<DefaultProps>,\n      OptionalProps,\n      // the global and xstyled props are only part of \"props\"/\"internalProps\" in our namespaces\n      //  to properly inherith button's global & xstyled props, we need to also include the following\n      Omit<DSButtonV3T.Props, keyof RequiredProps | keyof DefaultProps | keyof OptionalProps> {}\n\n  /* **************************************************************************************************************\n   ******************************************** INTERNAL PROPS  ***************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerInternalProps\n    extends MenuBehaviouralLayerDefaultProps, MenuBehaviouralLayerOptionalProps, MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificInternalProps\n    extends MenuSpecifiDefaultProps, MenuSpecificOptionalProps, MenuSpecificRequiredProps {}\n\n  /* *******************************************************\n   * Internal Props\n   *  - We inherit the internal props from the button\n   *  - We add the internal props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  export interface ButtonInheritedInternalProps\n    // by using Omit, we remove the keys that are present in the MenuSpecificInternalProps to ensure collision are handled as expected\n    //  THIS IS ALSO INHERITING THE GLOBAL ATTRIBUTES & XSTYLED PROPS FROM THE BUTTON!!!\n    extends Omit<DSButtonV3T.InternalProps, keyof MenuSpecificInternalProps> {}\n  export interface InternalProps\n    extends\n      RequiredProps,\n      DefaultProps,\n      OptionalProps,\n      // the global and xstyled props are only part of \"props\"/\"internalProps\" in our namespaces\n      //  to properly inherith button's global & xstyled props, we need to also include the following\n      Omit<DSButtonV3T.Props, keyof RequiredProps | keyof DefaultProps | keyof OptionalProps> {}\n}\n\nexport const menuSpecificDefaultProps: DSMenuButtonT.MenuSpecifiDefaultProps = {\n  onClickOutside: () => null,\n  onOptionClick: () => null,\n  openedSubmenus: {},\n  onSubmenuToggle: () => null,\n  isLoading: false,\n  isSkeleton: false,\n  maxHeight: '256px', // was available in dropdownmenu-v2, have to provide for retrocompatibility\n};\n/* *******************************************************\n * We are building a widget composed of 3 ATOMIC composition components\n * - Button\n * - Menu\n * - Behavioural Layer\n * The final API facing the users is a sum of all 3 interfaces\n * THOSE INTERFACES ARE NOT EQUAL TO THE FINAL \"PARTS\" INTERFACES\n *   The widget embeds \"assumptions\" (as all widgets do) that are AGNOSTIC to the \"parts\" interfaces\n * The \"Parts\" interfaces \"mostly\" inherit the following interfaces, but with meaningful meant and planned differences\n * (E.G. the widget accepts an array of options, but the Menu part accepts a DSTree only)\n ******************************************************* */\nexport const MenuBehaviouralLayerPropTypes: DSPropTypesSchema<DSMenuButtonT.MenuBehaviouralLayerProps> = {\n  onItemSelected: PropTypes.func.description(\n    'IoC function in charge of handling the selection of a menu item, required if the menu has selectionable items',\n  ).signature(`((\n      newSelection: DSMenuButtonT.PseudoFocusableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`),\n\n  onActivateItem: PropTypes.func.description(\n    'IoC function in charge of handling the activation (NOT INVOKED ON SELECTION) of a menu item, required if the menu has activable items',\n  ).signature(`((\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes,\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`),\n\n  onOpen: PropTypes.func.description('function triggered when the widget opens the menu').signature(`(()=>void)`),\n  onClose: PropTypes.func.description('function triggered when the widget closes the menu').signature(`(()=>void)`),\n  onDisplayedSubmenuChange: PropTypes.func.description(\"function triggered when the widget's closes or opens a submenu\")\n    .signature(`((\n      newOpenedItems: DSMenuButtonT.PseudoFocusableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`),\n};\n\nexport const DSMenuSpecificPropTypes: DSPropTypesSchema<DSMenuButtonT.MenuSpecificProps> = {\n  ItemRenderer: PropTypes.node.description('Component to be used to render the items'),\n  onClickOutside: PropTypes.func\n    .description('Callback executed when you click outside the dropdown menu, or press the Esc key')\n    .defaultValue(() => null),\n  onOptionClick: PropTypes.func\n    .description(\n      'Callback triggered when an item is clicked or pressed. We provide the next selected options, the clicked option and the event, in that order',\n    )\n    .defaultValue(() => null),\n  openedSubmenus: PropTypes.object\n    .description(\n      'Object with the ids of the submenus as keys, and booleans as keys. Represents the state of the current opened submenus',\n    )\n    .defaultValue({}),\n  onSubmenuToggle: PropTypes.func\n    .description('Callback triggered when a submenu is opened or closed.')\n    .signature(\n      '((nextOpenedSubmenus: Record<string, boolean>, submenu: Item, e: React.MouseEvent | React.KeyboardEvent) => void)',\n    )\n    .defaultValue(() => null),\n  isLoading: PropTypes.bool\n    .description('Whether the flyout menu should render the loading indicator')\n    .defaultValue(false),\n  isSkeleton: PropTypes.bool.description('Whether the flyout menu should render the skeleton').defaultValue(false),\n  maxHeight: PropTypes.oneOfType([PropTypes.string, PropTypes.number])\n    .description('The maximum height of the flyout menu')\n    .defaultValue('256px'),\n  floatingConfig: PropTypes.object.description(\n    'Configuration object for the floating context (placement, placementOrderPreference, customOffset, animationDuration, withoutPortal, withoutAnimation, portalDOMContainer)',\n  ),\n};\n\nexport const DSMenuButtonPropTypes: DSPropTypesSchema<DSMenuButtonT.Props> = {\n  options: PropTypes.oneOfType([PropTypes.array, PropTypes.object]).description(\n    'Array of options to display in the menu or a DSTree node to build branches from',\n  ).isRequired,\n  selectedItems: PropTypes.arrayOf(PropTypes.object).description(\n    'an array of tree-nodes or tree-items that have to be marked as selected in the GUI, required if the menu has selectionable items',\n  ),\n  ...DSButtonV3PropTypes,\n  ...MenuBehaviouralLayerPropTypes,\n  ...DSMenuSpecificPropTypes,\n  ...getPropsPerSlotPropTypes(DSMenuButtonName, MENU_BUTTON_SLOTS),\n};\n\nexport const DSMenuButtonPropTypesSchema = DSMenuButtonPropTypes as unknown as ValidationMap<DSMenuButtonT.Props>;\n", "import * as React from 'react';\nexport { React };\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADEvB,8BAAoD;AACpD,0BAAoC;AAOpC,uBAA2E;AAqdpE,MAAM,2BAAkE;AAAA,EAC7E,gBAAgB,MAAM;AAAA,EACtB,eAAe,MAAM;AAAA,EACrB,gBAAgB,CAAC;AAAA,EACjB,iBAAiB,MAAM;AAAA,EACvB,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,WAAW;AAAA;AACb;AAYO,MAAM,gCAA4F;AAAA,EACvG,gBAAgB,kCAAU,KAAK;AAAA,IAC7B;AAAA,EACF,EAAE,UAAU;AAAA;AAAA;AAAA,eAGC;AAAA,EAEb,gBAAgB,kCAAU,KAAK;AAAA,IAC7B;AAAA,EACF,EAAE,UAAU;AAAA;AAAA;AAAA,eAGC;AAAA,EAEb,QAAQ,kCAAU,KAAK,YAAY,mDAAmD,EAAE,UAAU,YAAY;AAAA,EAC9G,SAAS,kCAAU,KAAK,YAAY,oDAAoD,EAAE,UAAU,YAAY;AAAA,EAChH,0BAA0B,kCAAU,KAAK,YAAY,gEAAgE,EAClH,UAAU;AAAA;AAAA;AAAA,eAGA;AACf;AAEO,MAAM,0BAA8E;AAAA,EACzF,cAAc,kCAAU,KAAK,YAAY,0CAA0C;AAAA,EACnF,gBAAgB,kCAAU,KACvB,YAAY,kFAAkF,EAC9F,aAAa,MAAM,IAAI;AAAA,EAC1B,eAAe,kCAAU,KACtB;AAAA,IACC;AAAA,EACF,EACC,aAAa,MAAM,IAAI;AAAA,EAC1B,gBAAgB,kCAAU,OACvB;AAAA,IACC;AAAA,EACF,EACC,aAAa,CAAC,CAAC;AAAA,EAClB,iBAAiB,kCAAU,KACxB,YAAY,wDAAwD,EACpE;AAAA,IACC;AAAA,EACF,EACC,aAAa,MAAM,IAAI;AAAA,EAC1B,WAAW,kCAAU,KAClB,YAAY,6DAA6D,EACzE,aAAa,KAAK;AAAA,EACrB,YAAY,kCAAU,KAAK,YAAY,oDAAoD,EAAE,aAAa,KAAK;AAAA,EAC/G,WAAW,kCAAU,UAAU,CAAC,kCAAU,QAAQ,kCAAU,MAAM,CAAC,EAChE,YAAY,uCAAuC,EACnD,aAAa,OAAO;AAAA,EACvB,gBAAgB,kCAAU,OAAO;AAAA,IAC/B;AAAA,EACF;AACF;AAEO,MAAM,wBAAgE;AAAA,EAC3E,SAAS,kCAAU,UAAU,CAAC,kCAAU,OAAO,kCAAU,MAAM,CAAC,EAAE;AAAA,IAChE;AAAA,EACF,EAAE;AAAA,EACF,eAAe,kCAAU,QAAQ,kCAAU,MAAM,EAAE;AAAA,IACjD;AAAA,EACF;AAAA,EACA,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AAAA,EACH,OAAG,kDAAyB,mCAAkB,kCAAiB;AACjE;AAEO,MAAM,8BAA8B;",
+  "sourcesContent": ["/* eslint-disable max-lines */\n/* eslint-disable @typescript-eslint/no-empty-interface */\nimport { PropTypes, getPropsPerSlotPropTypes } from '@elliemae/ds-props-helpers';\nimport { DSButtonV3PropTypes } from '@elliemae/ds-button-v2';\nimport type { DSPropTypesSchema, ValidationMap } from '@elliemae/ds-props-helpers';\nimport { type TypescriptHelpersT } from '@elliemae/ds-typescript-helpers';\nimport type { DSButtonV3T } from '@elliemae/ds-button-v2';\nimport type { UseDSTreeT } from '@elliemae/ds-tree-model';\nimport type { DSHookFloatingContextT } from '@elliemae/ds-floating-context';\n\nimport { DSMenuButtonName, MENU_BUTTON_SLOTS, type MENU_ITEMS_TYPES } from './constants/index.js';\nexport declare namespace DSMenuButtonT {\n  /* *******************************************************\n   * Slot function-form prop arguments \u2014 one entry per slot in MENU_BUTTON_SLOTS.\n   * Backs the typescript-testing/slot-props.ts exhaustiveness check.\n   ******************************************************* */\n  export type SlotFunctionArguments = {\n    dsMenubuttonRoot: () => object;\n  };\n\n  /* *******************************************************\n   * YURI's NOTE:\n   *\n   * This polymorphic interface \"looks similar\" between the diffent types\n   *  but it's actually different upon closer inspection\n   *\n   * If you are smarter then me, you can probably find a way to make this more DRY\n   *  but I prefeer AHA (Avoid Hasty Abstractions) that gives me an easier to mantain code\n   *   ESPECIALLY when the types are so similar but not the same & in typescript (polymorphism is hard in TS)\n   *\n   * So I'm going to keep them separate and explicit\n   *  key difference is what's required to exist and what is required to explicitly NOT exist\n   *\n   * If someone's review this and make this DRY, I'm NOT going to mantain this code moving forward\n   *   whoever makes this TS DRY will be responsible for it and own it.\n   ******************************************************* */\n\n  /* **************************************************************************************************************\n   *********************************** POLYMORPHIC INTERFACES FOR MENU ITEMS  *************************************\n   ************************************************************************************************************** */\n  export interface RootItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: 'ROOT_ITEM'; // HARDCODED BECAUSE THIS IS NOT A MENU ITEM, IT'S EXCLUSIVE TO THE ROOT NODE\n    dsId: string;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    label?: undefined;\n    secondaryLabel?: undefined;\n    leftDecoration?: undefined;\n    minWidth?: undefined;\n    disabled?: undefined;\n    onClick?: undefined;\n    onKeyDown?: undefined;\n  }\n  export interface SeparatorItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SEPARATOR'];\n    dsId: string;\n    label?: undefined;\n    secondaryLabel?: undefined;\n    leftDecoration?: undefined;\n    minWidth?: undefined;\n    disabled?: undefined;\n    onClick?: undefined;\n    onKeyDown?: undefined;\n  }\n  export interface ActivableItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['ACTIVABLE_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface ActionableWithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['ACTIVABLE_WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface SkeletonItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SKELETON_ITEM'];\n    dsId: string;\n    minWidth?: string | number;\n    label?: undefined;\n    secondaryLabel?: undefined;\n    leftDecoration?: undefined;\n    disabled?: undefined;\n    onClick?: undefined;\n    onKeyDown?: undefined;\n  }\n  export interface MultipleSelectItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['MULTIPLE_SELECT_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n\n  export interface MultiSelectWithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['MULTIPLE_SELECT_WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface WithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight?: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface SingleSelectItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SINGLE_SELECT_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n  export interface SingleSelectWithSubmenuItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['SINGLE_SELECT_WITH_SUBMENU_ITEM'];\n    dsId: string;\n    label: string;\n    secondaryLabel?: string;\n    leftDecoration?: React.ComponentType;\n    minWidth?: string | number;\n    maxHeight: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n\n  export interface GroupItem extends UseDSTreeT.AnyObjectWithoutReservedKeys {\n    type: (typeof MENU_ITEMS_TYPES)['GROUP'];\n    dsId: string;\n    label?: string; // if present, add a title to the group\n    leftDecoration?: React.ComponentType; // if present, a label must also be present\n    minWidth?: string | number;\n  }\n\n  export type MenuItemInterface =\n    | SeparatorItem\n    | ActivableItem\n    | ActionableWithSubmenuItem\n    | SkeletonItem\n    | MultipleSelectItem\n    | MultiSelectWithSubmenuItem\n    | WithSubmenuItem\n    | GroupItem\n    | SingleSelectItem\n    | SingleSelectWithSubmenuItem;\n\n  export type PseudoFocusableItemInterface =\n    | ActivableItem\n    | ActionableWithSubmenuItem\n    | SkeletonItem\n    | MultipleSelectItem\n    | MultiSelectWithSubmenuItem\n    | WithSubmenuItem\n    | SingleSelectItem\n    | SingleSelectWithSubmenuItem;\n\n  export type SelectionableMenuItemInterface =\n    MultipleSelectItem | MultiSelectWithSubmenuItem | SingleSelectItem | SingleSelectWithSubmenuItem;\n\n  /* **************************************************************************************************************\n   *************************** POLYMORPHIC INTERFACES FOR ITEMS USING DSTREE  *************************************\n   ************************************************************************************************************** */\n  // Define MenuNode types directly\n  export type MenuNodeRootItem = UseDSTreeT.TreeNode<RootItem>; // MenuNodesAllowedToHaveChildren is the only expected reference to this type\n  export type MenuNodeSeparatorItem = UseDSTreeT.TreeNode<SeparatorItem>;\n  export type MenuNodeActivableItem = UseDSTreeT.TreeNode<ActivableItem>;\n  export type MenuNodeActivableWithSubmenuItem = UseDSTreeT.TreeNode<ActionableWithSubmenuItem>;\n  export type MenuNodeSkeletonItem = UseDSTreeT.TreeNode<SkeletonItem>;\n  export type MenuNodeMultipleSelectItem = UseDSTreeT.TreeNode<MultipleSelectItem>;\n  export type MenuNodeMultipleSelectWithSubmenuItem = UseDSTreeT.TreeNode<MultiSelectWithSubmenuItem>;\n  export type MenuNodeWithSubmenuItem = UseDSTreeT.TreeNode<WithSubmenuItem>;\n  export type MenuNodeSingleSelectItem = UseDSTreeT.TreeNode<SingleSelectItem>;\n  export type MenuNodeSingleSelectWithSubmenuItem = UseDSTreeT.TreeNode<SingleSelectWithSubmenuItem>;\n  export type MenuNodeGroupItem = UseDSTreeT.TreeNode<GroupItem>;\n\n  // in the future we want to better describe the polymorphic nature of the MenuNode\n  //  having each type be able to have it's own \"subitems\" type that isn't necessarily the same as the parent\n  //  but currenctly the DS tree model typescript definitions don't support this\n  //  will be addresssed via PUI-XXXX\n  export type MenuNode =\n    // DO NOT ADD MenuNodeRootItem HERE, WILL BREAK THE SUBTREES\n    | MenuNodeSeparatorItem\n    | MenuNodeActivableItem\n    | MenuNodeActivableWithSubmenuItem\n    | MenuNodeSkeletonItem\n    | MenuNodeMultipleSelectItem\n    | MenuNodeMultipleSelectWithSubmenuItem\n    | MenuNodeWithSubmenuItem\n    | MenuNodeSingleSelectItem\n    | MenuNodeSingleSelectWithSubmenuItem\n    | MenuNodeGroupItem;\n\n  export type PseudoFocusableMenuNodes =\n    | MenuNodeActivableItem\n    | MenuNodeActivableWithSubmenuItem\n    | MenuNodeSkeletonItem\n    | MenuNodeSingleSelectItem\n    | MenuNodeMultipleSelectItem\n    | MenuNodeMultipleSelectWithSubmenuItem\n    | MenuNodeWithSubmenuItem\n    | MenuNodeSingleSelectWithSubmenuItem;\n\n  export type MenuNodesAllowedToHaveChildren =\n    | MenuNodeRootItem\n    | MenuNodeWithSubmenuItem\n    | MenuNodeGroupItem\n    | MenuNodeActivableWithSubmenuItem\n    | MenuNodeMultipleSelectWithSubmenuItem\n    | MenuNodeSingleSelectWithSubmenuItem;\n\n  export type SelectionableMenuNodes =\n    | DSMenuButtonT.MenuNodeMultipleSelectItem\n    | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem\n    | DSMenuButtonT.MenuNodeSingleSelectItem\n    | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  export type MultipleSelectionableMenuNodes =\n    DSMenuButtonT.MenuNodeMultipleSelectItem | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem;\n\n  export type SingleSelectionableMenuNodes =\n    DSMenuButtonT.MenuNodeSingleSelectItem | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  export type WithSubmenuMenuNodes =\n    | DSMenuButtonT.MenuNodeWithSubmenuItem\n    | DSMenuButtonT.MenuNodeActivableWithSubmenuItem\n    | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem\n    | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  export type SelectionablesWithSubmenuMenuNodes =\n    DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\n\n  /* **************************************************************************************************************\n   ********************************** PROPS/INTERNAL PROPS DEFINITIONS  *******************************************\n   ************************************************************************************************************** */\n\n  export type ItemRendererT = React.ComponentType<{ itemNode: MenuNode }>;\n\n  /* **************************************************************************************************************\n   ******************************************* \"REQUIRED\" PROPS  **************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * From official source definition\n   *\n   * Menu Button Pattern\n   *  About This Pattern:\n   *    A menu button is a button\n   *      that opens a menu\n   *         (as described in the Menu and Menubar Pattern).\n   *\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   *\n   * This is effectively an OOP \"extension\" of the Button component,\n   *  so it has the same props,\n   *  BUT also a few more to handle the specific behavior of the menu.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificRequiredProps {}\n  /* *******************************************************\n   * Required Props + Inherited Required Props\n   *  - We inherit the required props from the button\n   *  - We add the required props for the menu\n   *\n   *  - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  export interface ButtonInheritedRequiredProps\n    // by using Omit, we remove the keys that are present in the MenuSpecificRequiredProps to ensure collision are handled as expected\n    extends Omit<DSButtonV3T.RequiredProps, keyof MenuSpecificRequiredProps> {}\n  // the final RequiredProps will be the combination of the two with proper collision handling\n  export interface RequiredProps\n    extends MenuSpecificRequiredProps, ButtonInheritedRequiredProps, MenuBehaviouralLayerRequiredProps {\n    // it's the Menu Widget sole responsibility to receive the options and convert them to a tree\n    options: MenuItemInterface[] | MenuNode;\n  }\n\n  /* **************************************************************************************************************\n   ******************************************** \"DEFAULT\" PROPS  **************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerDefaultProps {}\n  export interface MenuSpecifiDefaultProps {\n    onClickOutside: (e: MouseEvent | React.KeyboardEvent | TouchEvent) => void;\n    onOptionClick: (\n      nextSelectedOptions: Record<string, boolean>,\n      clickedOption: MenuItemInterface,\n      e: React.MouseEvent | React.KeyboardEvent,\n    ) => void;\n    openedSubmenus: Record<string, boolean>;\n    onSubmenuToggle: (\n      nextOpenedSubmenus: Record<string, boolean>,\n      submenu: MenuItemInterface,\n      e: React.MouseEvent | React.KeyboardEvent,\n    ) => void;\n    isLoading: boolean;\n    isSkeleton: boolean;\n    maxHeight: string | number; // was available in dropdownmenu-v2, have to provide for retrocompatibility\n  }\n\n  /* *******************************************************\n   * Default Props + Inherited Default Props\n   *  - We inherit the default props from the button\n   *  - We add the default props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  // by using Omit, we remove the keys that are present in the MenuSpecificDefaultProps to ensure collision are handled as expected\n  export interface ButtonInheiredDefaultProps extends Omit<DSButtonV3T.DefaultProps, keyof MenuSpecifiDefaultProps> {}\n  // the final DefaultProps will be the combination of the two with proper collision handling\n  export interface DefaultProps\n    extends MenuSpecifiDefaultProps, ButtonInheiredDefaultProps, MenuBehaviouralLayerDefaultProps {}\n\n  /* **************************************************************************************************************\n   ******************************************* \"OPTIONAL\" PROPS  **************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export type MenuOpenReason = 'trigger-click' | 'trigger-arrow-down' | 'trigger-arrow-up';\n  export type MenuCloseReason =\n    'outside-click' | 'window-blur' | 'escape' | 'tab' | 'item-activation' | 'trigger-toggle';\n  export interface MenuOpenMetainfo {\n    reason: MenuOpenReason;\n    event?: React.SyntheticEvent;\n  }\n  export interface MenuCloseMetainfo {\n    reason: MenuCloseReason;\n    event?: React.SyntheticEvent | MouseEvent | TouchEvent | FocusEvent;\n  }\n  export interface MenuBehaviouralLayerOptionalProps {\n    // **********************************************************************************************\n    // IoC Pattern\n    //   - in scenarios where not \"selectionable\" items are present,\n    //      - the \"selectedItems\" prop is not required\n    //      - the \"onItemSelected\" prop is not required\n    //   - in scenarios where no \"activation\" items are present,\n    //      - the \"onActivateItem\" prop is not required\n    // AFAIK Typescipt doesn't support this kind of \"conditional\" required props\n    //   so we will rely on javascript error throwing to handle this + documentation\n    // **********************************************************************************************\n    onItemSelected?: (\n      newSelection: SelectionableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.SelectionableMenuNodes; event?: React.SyntheticEvent },\n    ) => void | TypescriptHelpersT.StateSetter<DSMenuButtonT.SelectionableMenuNodes[]>;\n    onActivateItem?: (\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes,\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void;\n    // **********************************************************************************************\n    // both carry the intent that triggered them (`reason`) and the originating event, so consumers that own the\n    //   open state (a11yDangerouslyConsumerOwnedMenuOpenState) can tell WHY the widget asks to open/close\n    onOpen?: (metainfo: DSMenuButtonT.MenuOpenMetainfo) => void;\n    onClose?: (metainfo: DSMenuButtonT.MenuCloseMetainfo) => void;\n    /*\n     * Escape hatch \u2014 when a boolean is provided the consumer OWNS the menu open state\n     *   and the widget's internal open bookkeeping degrades to an *intent* signal:\n     *   `onOpen`/`onClose` fire for each open/close intent that changes the effective state (trigger click, Escape,\n     *   click-outside, item activation, window blur; an intent that matches the current state, like a close\n     *   while closed, is ignored) and the consumer is expected to sync this prop accordingly or the menu will\n     *   not reflect the requested state.\n     * Reaching for it invalidates the widget's open-state-related a11y guarantees\n     *   (focus is still returned/tracked on intent, not on the effective transition \u2014\n     *   if the consumer does not flip the prop, focus can leave a panel that stays open).\n     * Named \"long on purpose\": it must not be missable when skimming code.\n     */\n    a11yDangerouslyConsumerOwnedMenuOpenState?: boolean;\n    onDisplayedSubmenuChange?: (\n      newOpenedItems: DSMenuButtonT.WithSubmenuMenuNodes[],\n      metainfo: {\n        itemNode: DSMenuButtonT.PseudoFocusableMenuNodes | null;\n        event?: React.SyntheticEvent | FocusEvent | TouchEvent;\n      },\n    ) => void | TypescriptHelpersT.StateSetter<DSMenuButtonT.WithSubmenuMenuNodes[]>;\n  }\n  export interface MenuSpecificOptionalProps {\n    ItemRenderer?: ItemRendererT;\n    floatingConfig?: Partial<Omit<DSHookFloatingContextT.Props, 'externallyControlledIsOpen' | 'onOpen' | 'onClose'>>;\n  }\n  /* *******************************************************\n   * Optional Props + Inherited Optional Props\n   *  - We inherit the optional props from the button\n   *  - We add the optional props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  export interface ButtonInheritedOptionalProps\n    // by using Omit, we remove the keys that are present in the MenuSpecificOptionalProps to ensure collision are handled as expected\n    extends Omit<DSButtonV3T.OptionalProps, keyof MenuSpecificOptionalProps> {}\n  export interface OptionalProps\n    extends\n      MenuSpecificOptionalProps,\n      ButtonInheritedOptionalProps,\n      // we convert the (selected) options to a Nodes as part of the widget's logic\n      MenuBehaviouralLayerOptionalProps,\n      TypescriptHelpersT.PropsForGlobalOnSlots<typeof DSMenuButtonName, typeof MENU_BUTTON_SLOTS> {\n    // we convert the (selected) options to a Nodes as part of the widget's logic\n    selectedItems?: SelectionableMenuNodes[] | SelectionableMenuItemInterface[];\n  }\n\n  /* **************************************************************************************************************\n   ************************************************  PROPS  *******************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerProps\n    extends\n      Partial<MenuBehaviouralLayerDefaultProps>,\n      MenuBehaviouralLayerOptionalProps,\n      MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificProps\n    extends Partial<MenuSpecifiDefaultProps>, MenuSpecificOptionalProps, MenuSpecificRequiredProps {}\n  /* *******************************************************\n   * Props + Inherited Props\n   *  - We inherit the props from the button\n   *  - We add the props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  // by using Omit, we remove the keys that are present in the MenuSpecificProps to ensure collision are handled as expected\n  //  THIS IS ALSO INHERITING THE GLOBAL ATTRIBUTES & XSTYLED PROPS FROM THE BUTTON!!!\n  export interface ButtonInheritedProps extends Omit<DSButtonV3T.Props, keyof MenuSpecificProps> {}\n\n  export interface Props\n    extends\n      RequiredProps,\n      Partial<DefaultProps>,\n      OptionalProps,\n      // the global and xstyled props are only part of \"props\"/\"internalProps\" in our namespaces\n      //  to properly inherith button's global & xstyled props, we need to also include the following\n      Omit<DSButtonV3T.Props, keyof RequiredProps | keyof DefaultProps | keyof OptionalProps> {}\n\n  /* **************************************************************************************************************\n   ******************************************** INTERNAL PROPS  ***************************************************\n   ************************************************************************************************************** */\n  /* *******************************************************\n   * Since the menu button is a button, it inherits all the props from the Button component.\n   * Since the menu button MUST have a menu, it also have a set of specific props used to handle the menu.\n   * Because we build with atomic composition in mind, the \"logic layer\" is separated and has a yet another set of props.\n   ******************************************************* */\n  export interface MenuBehaviouralLayerInternalProps\n    extends MenuBehaviouralLayerDefaultProps, MenuBehaviouralLayerOptionalProps, MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificInternalProps\n    extends MenuSpecifiDefaultProps, MenuSpecificOptionalProps, MenuSpecificRequiredProps {}\n\n  /* *******************************************************\n   * Internal Props\n   *  - We inherit the internal props from the button\n   *  - We add the internal props for the menu\n   *\n   * - if a collision occurs, the menu specific are meant to be the most important and specific ones\n   ******************************************************* */\n  export interface ButtonInheritedInternalProps\n    // by using Omit, we remove the keys that are present in the MenuSpecificInternalProps to ensure collision are handled as expected\n    //  THIS IS ALSO INHERITING THE GLOBAL ATTRIBUTES & XSTYLED PROPS FROM THE BUTTON!!!\n    extends Omit<DSButtonV3T.InternalProps, keyof MenuSpecificInternalProps> {}\n  export interface InternalProps\n    extends\n      RequiredProps,\n      DefaultProps,\n      OptionalProps,\n      // the global and xstyled props are only part of \"props\"/\"internalProps\" in our namespaces\n      //  to properly inherith button's global & xstyled props, we need to also include the following\n      Omit<DSButtonV3T.Props, keyof RequiredProps | keyof DefaultProps | keyof OptionalProps> {}\n}\n\nexport const menuSpecificDefaultProps: DSMenuButtonT.MenuSpecifiDefaultProps = {\n  onClickOutside: () => null,\n  onOptionClick: () => null,\n  openedSubmenus: {},\n  onSubmenuToggle: () => null,\n  isLoading: false,\n  isSkeleton: false,\n  maxHeight: '256px', // was available in dropdownmenu-v2, have to provide for retrocompatibility\n};\n/* *******************************************************\n * We are building a widget composed of 3 ATOMIC composition components\n * - Button\n * - Menu\n * - Behavioural Layer\n * The final API facing the users is a sum of all 3 interfaces\n * THOSE INTERFACES ARE NOT EQUAL TO THE FINAL \"PARTS\" INTERFACES\n *   The widget embeds \"assumptions\" (as all widgets do) that are AGNOSTIC to the \"parts\" interfaces\n * The \"Parts\" interfaces \"mostly\" inherit the following interfaces, but with meaningful meant and planned differences\n * (E.G. the widget accepts an array of options, but the Menu part accepts a DSTree only)\n ******************************************************* */\nexport const MenuBehaviouralLayerPropTypes: DSPropTypesSchema<DSMenuButtonT.MenuBehaviouralLayerProps> = {\n  onItemSelected: PropTypes.func.description(\n    'IoC function in charge of handling the selection of a menu item, required if the menu has selectionable items',\n  ).signature(`((\n      newSelection: DSMenuButtonT.PseudoFocusableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`),\n\n  onActivateItem: PropTypes.func.description(\n    'IoC function in charge of handling the activation (NOT INVOKED ON SELECTION) of a menu item, required if the menu has activable items',\n  ).signature(`((\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes,\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`),\n\n  onOpen: PropTypes.func\n    .description('function triggered when the widget opens the menu, with the reason (intent) that triggered it')\n    .signature(\n      `((metainfo: { reason: 'trigger-click' | 'trigger-arrow-down' | 'trigger-arrow-up'; event?: React.SyntheticEvent }) => void)`,\n    ),\n  onClose: PropTypes.func\n    .description('function triggered when the widget closes the menu, with the reason (intent) that triggered it')\n    .signature(\n      `((metainfo: { reason: 'outside-click' | 'window-blur' | 'escape' | 'tab' | 'item-activation' | 'trigger-toggle'; event?: React.SyntheticEvent | MouseEvent | TouchEvent | FocusEvent }) => void)`,\n    ),\n  a11yDangerouslyConsumerOwnedMenuOpenState: PropTypes.bool.description(\n    'Escape hatch: when a boolean is provided, the consumer owns the menu open state; onOpen/onClose fire for each intent that changes the effective state, and the consumer is expected to sync the prop from them. Invalidates the open-state-related a11y guarantees of the widget',\n  ),\n  onDisplayedSubmenuChange: PropTypes.func.description(\"function triggered when the widget's closes or opens a submenu\")\n    .signature(`((\n      newOpenedItems: DSMenuButtonT.PseudoFocusableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`),\n};\n\nexport const DSMenuSpecificPropTypes: DSPropTypesSchema<DSMenuButtonT.MenuSpecificProps> = {\n  ItemRenderer: PropTypes.node.description('Component to be used to render the items'),\n  onClickOutside: PropTypes.func\n    .description('Callback executed when you click outside the dropdown menu, or press the Esc key')\n    .defaultValue(() => null),\n  onOptionClick: PropTypes.func\n    .description(\n      'Callback triggered when an item is clicked or pressed. We provide the next selected options, the clicked option and the event, in that order',\n    )\n    .defaultValue(() => null),\n  openedSubmenus: PropTypes.object\n    .description(\n      'Object with the ids of the submenus as keys, and booleans as keys. Represents the state of the current opened submenus',\n    )\n    .defaultValue({}),\n  onSubmenuToggle: PropTypes.func\n    .description('Callback triggered when a submenu is opened or closed.')\n    .signature(\n      '((nextOpenedSubmenus: Record<string, boolean>, submenu: Item, e: React.MouseEvent | React.KeyboardEvent) => void)',\n    )\n    .defaultValue(() => null),\n  isLoading: PropTypes.bool\n    .description('Whether the flyout menu should render the loading indicator')\n    .defaultValue(false),\n  isSkeleton: PropTypes.bool.description('Whether the flyout menu should render the skeleton').defaultValue(false),\n  maxHeight: PropTypes.oneOfType([PropTypes.string, PropTypes.number])\n    .description('The maximum height of the flyout menu')\n    .defaultValue('256px'),\n  floatingConfig: PropTypes.object.description(\n    'Configuration object for the floating context (placement, placementOrderPreference, customOffset, animationDuration, withoutPortal, withoutAnimation, portalDOMContainer)',\n  ),\n};\n\nexport const DSMenuButtonPropTypes: DSPropTypesSchema<DSMenuButtonT.Props> = {\n  options: PropTypes.oneOfType([PropTypes.array, PropTypes.object]).description(\n    'Array of options to display in the menu or a DSTree node to build branches from',\n  ).isRequired,\n  selectedItems: PropTypes.arrayOf(PropTypes.object).description(\n    'an array of tree-nodes or tree-items that have to be marked as selected in the GUI, required if the menu has selectionable items',\n  ),\n  ...DSButtonV3PropTypes,\n  ...MenuBehaviouralLayerPropTypes,\n  ...DSMenuSpecificPropTypes,\n  ...getPropsPerSlotPropTypes(DSMenuButtonName, MENU_BUTTON_SLOTS),\n};\n\nexport const DSMenuButtonPropTypesSchema = DSMenuButtonPropTypes as unknown as ValidationMap<DSMenuButtonT.Props>;\n", "import * as React from 'react';\nexport { React };\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;ACAA,YAAuB;ADEvB,8BAAoD;AACpD,0BAAoC;AAOpC,uBAA2E;AA+epE,MAAM,2BAAkE;AAAA,EAC7E,gBAAgB,MAAM;AAAA,EACtB,eAAe,MAAM;AAAA,EACrB,gBAAgB,CAAC;AAAA,EACjB,iBAAiB,MAAM;AAAA,EACvB,WAAW;AAAA,EACX,YAAY;AAAA,EACZ,WAAW;AAAA;AACb;AAYO,MAAM,gCAA4F;AAAA,EACvG,gBAAgB,kCAAU,KAAK;AAAA,IAC7B;AAAA,EACF,EAAE,UAAU;AAAA;AAAA;AAAA,eAGC;AAAA,EAEb,gBAAgB,kCAAU,KAAK;AAAA,IAC7B;AAAA,EACF,EAAE,UAAU;AAAA;AAAA;AAAA,eAGC;AAAA,EAEb,QAAQ,kCAAU,KACf,YAAY,+FAA+F,EAC3G;AAAA,IACC;AAAA,EACF;AAAA,EACF,SAAS,kCAAU,KAChB,YAAY,gGAAgG,EAC5G;AAAA,IACC;AAAA,EACF;AAAA,EACF,2CAA2C,kCAAU,KAAK;AAAA,IACxD;AAAA,EACF;AAAA,EACA,0BAA0B,kCAAU,KAAK,YAAY,gEAAgE,EAClH,UAAU;AAAA;AAAA;AAAA,eAGA;AACf;AAEO,MAAM,0BAA8E;AAAA,EACzF,cAAc,kCAAU,KAAK,YAAY,0CAA0C;AAAA,EACnF,gBAAgB,kCAAU,KACvB,YAAY,kFAAkF,EAC9F,aAAa,MAAM,IAAI;AAAA,EAC1B,eAAe,kCAAU,KACtB;AAAA,IACC;AAAA,EACF,EACC,aAAa,MAAM,IAAI;AAAA,EAC1B,gBAAgB,kCAAU,OACvB;AAAA,IACC;AAAA,EACF,EACC,aAAa,CAAC,CAAC;AAAA,EAClB,iBAAiB,kCAAU,KACxB,YAAY,wDAAwD,EACpE;AAAA,IACC;AAAA,EACF,EACC,aAAa,MAAM,IAAI;AAAA,EAC1B,WAAW,kCAAU,KAClB,YAAY,6DAA6D,EACzE,aAAa,KAAK;AAAA,EACrB,YAAY,kCAAU,KAAK,YAAY,oDAAoD,EAAE,aAAa,KAAK;AAAA,EAC/G,WAAW,kCAAU,UAAU,CAAC,kCAAU,QAAQ,kCAAU,MAAM,CAAC,EAChE,YAAY,uCAAuC,EACnD,aAAa,OAAO;AAAA,EACvB,gBAAgB,kCAAU,OAAO;AAAA,IAC/B;AAAA,EACF;AACF;AAEO,MAAM,wBAAgE;AAAA,EAC3E,SAAS,kCAAU,UAAU,CAAC,kCAAU,OAAO,kCAAU,MAAM,CAAC,EAAE;AAAA,IAChE;AAAA,EACF,EAAE;AAAA,EACF,eAAe,kCAAU,QAAQ,kCAAU,MAAM,EAAE;AAAA,IACjD;AAAA,EACF;AAAA,EACA,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AAAA,EACH,OAAG,kDAAyB,mCAAkB,kCAAiB;AACjE;AAEO,MAAM,8BAA8B;",
   "names": []
 }