@elliemae/ds-menu-button 3.45.0-rc.0 → 3.45.0-rc.2

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useMenuItemEventsHandlers.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* 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 debounce from 'lodash/debounce';\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, selectedItems } = propsWithDefault;\n  const { onOpinionatedClose } = menuOpenStatus;\n  const {\n    trackFocusFirstChildItem,\n    trackFocusLastChildItem,\n    trackFocusNextItem,\n    trackFocusPreviousItem,\n    trackFocusParentItem,\n    trackFocusNode,\n    focusedElementItemNode,\n  } = focusTrackers;\n\n  const openSubmenu = React.useCallback(\n    ({\n      itemNode,\n      event,\n    }: {\n      itemNode: DSMenuButtonT.WithSubmenuMenuNodes;\n      event?: React.KeyboardEvent | React.MouseEvent;\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 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   * 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          const newSelection = getNewSelectionMultipleSelect(selectedItems, pseudoFocusedItemNode);\n          onItemSelected(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        } else if (isSingleSelectNode(pseudoFocusedItemNode)) {\n          const newSelection = getNewSelectionSingleSelect(selectedItems, pseudoFocusedItemNode);\n          onItemSelected(newSelection, { itemNode: pseudoFocusedItemNode, event });\n        } else {\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      selectedItems,\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        const newSelection = getNewSelectionMultipleSelect(selectedItems, 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        const newSelection = getNewSelectionSingleSelect(selectedItems, 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      selectedItems,\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\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        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        trackFocusPreviousItem(pseudoFocusedItemNode);\n        return;\n      }\n      // Left Arrow:\n      if (event.key === 'ArrowLeft') {\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      // 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      if (event.key === 'Escape') {\n        const { currentSubmenuWasMainMenu } = closeCurrentSubmenu({ itemNode: pseudoFocusedItemNode, event });\n        trackFocusParentItem(pseudoFocusedItemNode);\n        // if the menu we are trying to close is the main menu, we adittionally close the main menu itself\n        if (currentSubmenuWasMainMenu) {\n          // if parent is the root node, we close also the main menu\n          onOpinionatedClose();\n        }\n        return;\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        handleMenuItemSpaceKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n      // Right Arrow:\n      if (event.key === 'ArrowRight') {\n        handleMenuItemRightArrowKeyDown({ pseudoFocusedItemNode, event });\n        return;\n      }\n    },\n    [\n      focusedElementItemNode,\n      handleMenuItemEnterKeyDown,\n      handleMenuItemSpaceKeyDown,\n      trackFocusNextItem,\n      trackFocusPreviousItem,\n      handleMenuItemRightArrowKeyDown,\n      handleMenuItemLeftArrowKeyDown,\n      trackFocusFirstChildItem,\n      trackFocusLastChildItem,\n      closeCurrentSubmenu,\n      trackFocusParentItem,\n      onOpinionatedClose,\n    ],\n  );\n\n  const handleFocusableMenuItemOnMouseEnter = React.useCallback(\n    (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes, event: React.MouseEvent) => {\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\n      if (itemNode.plainItem.disabled) return;\n      // if not disabled and it has a submenu, we open it\n      openSubmenu({ itemNode, event });\n    },\n    [handleChangeOpenedSubItems, openSubmenu, trackFocusNode],\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  // SR softwares have a setting (that is on by default in mac VoiceOver)\n  //  that express the will from the user to have the \"voice over pseudo navigation\"\n  //  also \"act as a navigation\", it usually isn't so easy to catch/see this\n  //   because usually special key navigation is a secondary way to navigate\n  //   BUT, some role (surprise suprise, menu falls into this category)\n  //     inverts the \"navigation\" and \"special key navigation\" when SR is on by default\n  // Long story short, if when the item triggers a focus event, we don't track it\n  //   and the user uses the \"special key navigation\" to navigate\n  //    weird navigation and visual feedbacks will happen\n  // This handler ensures that\n  //  the focus is tracked when the item is focused via special key navigation in the SR software preference asking for it is on\n  // IMPORTANT:\n  // we need to make sure this is only invoked for the last focused item if many focus events are triggered in quick succession\n  // so we MUST debounce this\n  const handleMenuItemFocusReconciliation: (itemNode: DSMenuButtonT.PseudoFocusableMenuNodes) => void =\n    React.useCallback(\n      (itemNode) => {\n        debounce(\n          () => {\n            if (focusedElementItemNode.current?.dsId !== itemNode.dsId) trackFocusNode(itemNode);\n          },\n          10,\n          { leading: false, trailing: true },\n        );\n      },\n\n      [focusedElementItemNode, trackFocusNode],\n    );\n  return React.useMemo(\n    () => ({\n      handleFocusableMenuItemKeyDown,\n      handleFocusableMenuItemClick,\n      handleFocusableMenuItemOnMouseEnter,\n      handleMenuItemFocusReconciliation,\n    }),\n    [\n      handleFocusableMenuItemClick,\n      handleFocusableMenuItemKeyDown,\n      handleFocusableMenuItemOnMouseEnter,\n      handleMenuItemFocusReconciliation,\n    ],\n  );\n};\n"],
+  "mappings": "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",
+  "names": ["React"]
+}

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

@@ -0,0 +1,36 @@
+import * as React from "react";
+import React2 from "react";
+const useMenuOpenStatus = ({ propsWithDefault, focusTrackers }) => {
+  const { trackFocusTrigger, trackFocusFirstChildItem, trackFocusLastChildItem, preventBlurReset } = focusTrackers;
+  const { onClose, onOpen, optionsTree } = propsWithDefault;
+  const [isMenuOpen, setIsMenuOpen] = React2.useState(false);
+  const onOpinionatedClose = React2.useCallback(
+    ({ skipFocus } = { skipFocus: false }) => {
+      setIsMenuOpen(false);
+      if (onClose) onClose();
+      if (!skipFocus) trackFocusTrigger();
+      preventBlurReset.current = false;
+    },
+    [onClose, preventBlurReset, trackFocusTrigger]
+  );
+  const onOpinionatedOpen = React2.useCallback(
+    (config) => {
+      const { focusLastChild = false } = config || {};
+      setIsMenuOpen(true);
+      if (onOpen) onOpen();
+      const typeCastedOptionsTree = optionsTree;
+      if (focusLastChild) trackFocusLastChildItem(typeCastedOptionsTree);
+      else trackFocusFirstChildItem(typeCastedOptionsTree);
+      preventBlurReset.current = true;
+    },
+    [onOpen, optionsTree, preventBlurReset, trackFocusFirstChildItem, trackFocusLastChildItem]
+  );
+  return React2.useMemo(
+    () => ({ isMenuOpen, onOpinionatedClose, onOpinionatedOpen }),
+    [isMenuOpen, onOpinionatedClose, onOpinionatedOpen]
+  );
+};
+export {
+  useMenuOpenStatus
+};
+//# sourceMappingURL=useMenuOpenStatus.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useMenuOpenStatus.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "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"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,OAAOA,YAAW;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,IAAIA,OAAM,SAAS,KAAK;AAExD,QAAM,qBAAqBA,OAAM;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,oBAAoBA,OAAM;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,SAAOA,OAAM;AAAA,IACX,OAAO,EAAE,YAAY,oBAAoB,kBAAkB;AAAA,IAC3D,CAAC,YAAY,oBAAoB,iBAAiB;AAAA,EACpD;AACF;",
+  "names": ["React"]
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/config/useValidateProps.js

@@ -0,0 +1,10 @@
+import * as React from "react";
+import { useValidateTypescriptPropTypes } from "@elliemae/ds-props-helpers";
+import { DSMenuBehaviouralContextProviderName } from "../constants/index.js";
+const useValidateProps = (props, propTypes) => {
+  useValidateTypescriptPropTypes(props, propTypes, DSMenuBehaviouralContextProviderName);
+};
+export {
+  useValidateProps
+};
+//# sourceMappingURL=useValidateProps.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/config/useValidateProps.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useValidateProps.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { useValidateTypescriptPropTypes } from '@elliemae/ds-props-helpers';\nimport type { ValidationMap } from '@elliemae/ds-props-helpers';\nimport { type DSMenuBehaviouralContextProviderT } from '../react-desc-prop-types.js';\nimport { DSMenuBehaviouralContextProviderName } from '../constants/index.js';\n\nexport const useValidateProps = (\n  props: DSMenuBehaviouralContextProviderT.InternalProps,\n  propTypes: ValidationMap<DSMenuBehaviouralContextProviderT.Props>,\n): void => {\n  // we validate the \"required if\" via 'isRequiredIf from our custom PropTypes\n  useValidateTypescriptPropTypes(props, propTypes, DSMenuBehaviouralContextProviderName);\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,sCAAsC;AAG/C,SAAS,4CAA4C;AAE9C,MAAM,mBAAmB,CAC9B,OACA,cACS;AAET,iCAA+B,OAAO,WAAW,oCAAoC;AACvF;",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/constants/Errors.js

@@ -0,0 +1,28 @@
+import * as React from "react";
+const TREE_STRUCTURE_ERRORS = {
+  PARENT_NOT_GROUP: new Error(
+    "Tree structure violation: parent node of single-selectionable node MUST ALWAYS be a single select group node"
+  ),
+  GROUP_WITHOUT_PARENT: new Error("Tree structure violation: single select group node has no parent"),
+  NODE_CANNOT_HAVE_CHILDREN: new Error("Tree structure violation: node cannot have children")
+};
+const FORBIDDEN_BEHAVIOURS = {
+  TRYING_TO_FOCUS_NON_FOCUSABLE_NODE: new Error("Behavioural violation: trying to focus a non-focusable node"),
+  TRYING_TO_OPEN_SUBMENU_OF_NODE_WITHOUT_SUBMENU: new Error(
+    "Behavioural violation: trying to open submenu of node without submenu"
+  )
+};
+const UNEXPECTED_INTERNAL_ERRORS = {
+  FOCUSED_ITEM_NODE_NOT_SET: new Error("Internal error: focused item node not set"),
+  FOCUSED_ITEM_HAS_NO_PARENT: new Error("Internal error: focused item has no parent node (is root?)"),
+  NODE_WITHOUT_PARENT: new Error("Internal error: the node has no parent"),
+  CALCULATING_MULTI_SELECTION_OF_NON_MULTI_SELECTION_NODE: new Error(
+    "Internal error: the node is not multi-selectable or wrongly recognized as non-multi-selectable"
+  )
+};
+export {
+  FORBIDDEN_BEHAVIOURS,
+  TREE_STRUCTURE_ERRORS,
+  UNEXPECTED_INTERNAL_ERRORS
+};
+//# sourceMappingURL=Errors.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/constants/Errors.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/constants/Errors.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "export const TREE_STRUCTURE_ERRORS = {\n  PARENT_NOT_GROUP: new Error(\n    'Tree structure violation: parent node of single-selectionable node MUST ALWAYS be a single select group node',\n  ),\n  GROUP_WITHOUT_PARENT: new Error('Tree structure violation: single select group node has no parent'),\n  NODE_CANNOT_HAVE_CHILDREN: new Error('Tree structure violation: node cannot have children'),\n};\n\nexport const FORBIDDEN_BEHAVIOURS = {\n  TRYING_TO_FOCUS_NON_FOCUSABLE_NODE: new Error('Behavioural violation: trying to focus a non-focusable node'),\n  TRYING_TO_OPEN_SUBMENU_OF_NODE_WITHOUT_SUBMENU: new Error(\n    'Behavioural violation: trying to open submenu of node without submenu',\n  ),\n};\n\nexport const UNEXPECTED_INTERNAL_ERRORS = {\n  FOCUSED_ITEM_NODE_NOT_SET: new Error('Internal error: focused item node not set'),\n  FOCUSED_ITEM_HAS_NO_PARENT: new Error('Internal error: focused item has no parent node (is root?)'),\n  NODE_WITHOUT_PARENT: new Error('Internal error: the node has no parent'),\n  CALCULATING_MULTI_SELECTION_OF_NON_MULTI_SELECTION_NODE: new Error(\n    'Internal error: the node is not multi-selectable or wrongly recognized as non-multi-selectable',\n  ),\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAhB,MAAM,wBAAwB;AAAA,EACnC,kBAAkB,IAAI;AAAA,IACpB;AAAA,EACF;AAAA,EACA,sBAAsB,IAAI,MAAM,kEAAkE;AAAA,EAClG,2BAA2B,IAAI,MAAM,qDAAqD;AAC5F;AAEO,MAAM,uBAAuB;AAAA,EAClC,oCAAoC,IAAI,MAAM,6DAA6D;AAAA,EAC3G,gDAAgD,IAAI;AAAA,IAClD;AAAA,EACF;AACF;AAEO,MAAM,6BAA6B;AAAA,EACxC,2BAA2B,IAAI,MAAM,2CAA2C;AAAA,EAChF,4BAA4B,IAAI,MAAM,4DAA4D;AAAA,EAClG,qBAAqB,IAAI,MAAM,wCAAwC;AAAA,EACvE,yDAAyD,IAAI;AAAA,IAC3D;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/constants/index.js

@@ -0,0 +1,14 @@
+import * as React from "react";
+const DSMenuBehaviouralContextProviderName = "DSMenuBehaviouralContextProvider";
+const MENU_FOCUS_REGIONS = {
+  TRIGGER: "trigger",
+  // eslint thinks this is unnecceary, but this forces the string format, without it, it would be a generic string
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion
+  ITEM_BY_DSID: (dsId) => `item-${dsId}`,
+  RESET: ""
+};
+export {
+  DSMenuBehaviouralContextProviderName,
+  MENU_FOCUS_REGIONS
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/constants/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/constants/index.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import type { DSMenuButtonT } from '../../../react-desc-prop-types.js';\nexport const DSMenuBehaviouralContextProviderName = 'DSMenuBehaviouralContextProvider';\n\nexport const MENU_FOCUS_REGIONS = {\n  TRIGGER: 'trigger',\n  // eslint thinks this is unnecceary, but this forces the string format, without it, it would be a generic string\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion\n  ITEM_BY_DSID: (dsId: DSMenuButtonT.MenuNode['dsId']) =>\n    `item-${dsId}` as `item-dsid-${DSMenuButtonT.MenuNode['dsId']}`,\n  RESET: '',\n} as const;\n\n/* **************************************************************** */\n// THIS HAS NO STYLES/SLOTS/DOM, IT'S A PURE LOGIC CONTEXT PROVIDER\n/* **************************************************************** */\n\n// we are naming this with the ${component_name}_slots convention to namespace & avoid errors on duplicate exports variables in aggregators\n// export const MENU_BEHAVIOURAL_CONTEXT_PROVIDER_SLOTS = {\n//   ROOT: 'root',\n// } as const;\n\n// // we are naming this with the ${component_name}_data_testid convention to namespace & avoid errors on duplicate exports variables in aggregators\n// export const MENU_BEHAVIOURAL_CONTEXT_PROVIDER_DATA_TESTID = slotObjectToDataTestIds(DSMenuBehaviouralContextProviderName, MENU_BEHAVIOURAL_CONTEXT_PROVIDER_SLOTS)\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACChB,MAAM,uCAAuC;AAE7C,MAAM,qBAAqB;AAAA,EAChC,SAAS;AAAA;AAAA;AAAA,EAGT,cAAc,CAAC,SACb,QAAQ,IAAI;AAAA,EACd,OAAO;AACT;",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/index.js

@@ -0,0 +1,10 @@
+import * as React from "react";
+import {
+  DSMenuBehaviouralContextProvider,
+  DSMenuBehaviouralContextProviderWithSchema
+} from "./DSMenuBehaviouralContextProvider.js";
+export {
+  DSMenuBehaviouralContextProvider,
+  DSMenuBehaviouralContextProviderWithSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../scripts/build/transpile/react-shim.js", "../../../../src/parts/DSMenuBehaviouralContextProvider/index.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "export {\n  DSMenuBehaviouralContextProvider,\n  DSMenuBehaviouralContextProviderWithSchema,\n} from './DSMenuBehaviouralContextProvider.js';\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB;AAAA,EACE;AAAA,EACA;AAAA,OACK;",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/react-desc-prop-types.js

@@ -0,0 +1,23 @@
+import * as React from "react";
+import { PropTypes } from "@elliemae/ds-props-helpers";
+import { MenuBehaviouralLayerPropTypes } from "../../react-desc-prop-types.js";
+const defaultProps = {};
+const DSMenuBehaviouralContextProviderPropTypes = {
+  buttonDOMNode: PropTypes.object.description("The DOM node of the button (on close -> return focus to)").isRequired,
+  buttonDOMNodeRef: PropTypes.object.description(
+    "The DOM node of the button as a mutable Refs (required for performance reasons)"
+  ).isRequired,
+  children: PropTypes.node.description("the menu trigger and the menu components").isRequired,
+  optionsTree: PropTypes.object.description("DSTree node to build branches from").isRequired,
+  focusableNodes: PropTypes.arrayOf(PropTypes.object).description(
+    "an array of nodes that can receive pseudoFocus, obtainable via ds-tree flatten + filter(isFocusable)"
+  ).isRequired,
+  ...MenuBehaviouralLayerPropTypes
+};
+const DSMenuBehaviouralContextProviderPropTypesSchema = DSMenuBehaviouralContextProviderPropTypes;
+export {
+  DSMenuBehaviouralContextProviderPropTypes,
+  DSMenuBehaviouralContextProviderPropTypesSchema,
+  defaultProps
+};
+//# sourceMappingURL=react-desc-prop-types.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/react-desc-prop-types.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../scripts/build/transpile/react-shim.js", "../../../../src/parts/DSMenuBehaviouralContextProvider/react-desc-prop-types.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable @typescript-eslint/no-empty-interface */\nimport type { DSPropTypesSchema, ValidationMap } from '@elliemae/ds-props-helpers';\nimport { PropTypes } from '@elliemae/ds-props-helpers';\nimport { type TypescriptHelpersT } from '@elliemae/ds-typescript-helpers';\nimport { type DSMenuButtonT, MenuBehaviouralLayerPropTypes } from '../../react-desc-prop-types.js';\n\nexport declare namespace DSMenuBehaviouralContextProviderT {\n  /*\n   * everything that is specifically added in this namespace declaration and is not part of the original component\n   * is because the original component is an \"opinionated widget\" that offloads a chunk of responsibilities from dev to dimsum\n   * as such, the widget generates those interfaces,\n   *  but the app developer is not supposed to know about them\n   *    untill they go atomic composition (this namespace)\n   */\n  export interface RequiredProps extends DSMenuButtonT.MenuBehaviouralLayerRequiredProps {\n    buttonDOMNode: HTMLElement | null;\n    buttonDOMNodeRef: React.MutableRefObject<HTMLElement | null>;\n    optionsTree: DSMenuButtonT.MenuNode;\n    children: TypescriptHelpersT.ReactChildrenComplete;\n    focusableNodes: DSMenuButtonT.PseudoFocusableMenuNodes[];\n  }\n\n  export interface DefaultProps extends DSMenuButtonT.MenuBehaviouralLayerDefaultProps {}\n\n  export interface OptionalProps extends DSMenuButtonT.MenuBehaviouralLayerOptionalProps {}\n  export interface Props extends Partial<DefaultProps>, OptionalProps, RequiredProps {}\n\n  export interface InternalProps extends DefaultProps, OptionalProps, RequiredProps {}\n}\n\nexport const defaultProps: DSMenuBehaviouralContextProviderT.DefaultProps = {};\n\nexport const DSMenuBehaviouralContextProviderPropTypes: DSPropTypesSchema<DSMenuBehaviouralContextProviderT.Props> = {\n  buttonDOMNode: PropTypes.object.description('The DOM node of the button (on close -> return focus to)').isRequired,\n  buttonDOMNodeRef: PropTypes.object.description(\n    'The DOM node of the button as a mutable Refs (required for performance reasons)',\n  ).isRequired,\n  children: PropTypes.node.description('the menu trigger and the menu components').isRequired,\n  optionsTree: PropTypes.object.description('DSTree node to build branches from').isRequired,\n  focusableNodes: PropTypes.arrayOf(PropTypes.object).description(\n    'an array of nodes that can receive pseudoFocus, obtainable via ds-tree flatten + filter(isFocusable)',\n  ).isRequired,\n  ...MenuBehaviouralLayerPropTypes,\n};\n\nexport const DSMenuBehaviouralContextProviderPropTypesSchema =\n  DSMenuBehaviouralContextProviderPropTypes as unknown as ValidationMap<DSMenuBehaviouralContextProviderT.Props>;\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACEvB,SAAS,iBAAiB;AAE1B,SAA6B,qCAAqC;AA0B3D,MAAM,eAA+D,CAAC;AAEtE,MAAM,4CAAwG;AAAA,EACnH,eAAe,UAAU,OAAO,YAAY,0DAA0D,EAAE;AAAA,EACxG,kBAAkB,UAAU,OAAO;AAAA,IACjC;AAAA,EACF,EAAE;AAAA,EACF,UAAU,UAAU,KAAK,YAAY,0CAA0C,EAAE;AAAA,EACjF,aAAa,UAAU,OAAO,YAAY,oCAAoC,EAAE;AAAA,EAChF,gBAAgB,UAAU,QAAQ,UAAU,MAAM,EAAE;AAAA,IAClD;AAAA,EACF,EAAE;AAAA,EACF,GAAG;AACL;AAEO,MAAM,kDACX;",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/utils/multipleSelectionHelpers.js

@@ -0,0 +1,113 @@
+import * as React from "react";
+import {
+  isMultipleSelectNode,
+  isMultipleSelectOnlyNode,
+  isMultipleSelectWithSubmenuNode
+} from "../../../utils/nodesTypeguardsAndGetters.js";
+import { UNEXPECTED_INTERNAL_ERRORS } from "../constants/Errors.js";
+import { getChildrenByCriterias } from "./nodeGettersByCriterias.js";
+const getIsMultipleSelectNodeWithSubmenuSelected = ({
+  itemNode,
+  selectedItems
+}) => {
+  if (selectedItems.length === 0) return false;
+  const { multiSelectionableChilrens } = getChildrenByCriterias(itemNode);
+  const selectedMultiChildren = [];
+  let isSelectedItself = false;
+  selectedItems.forEach((itemMarkesAsSelected) => {
+    if (itemMarkesAsSelected.dsId === itemNode.dsId) isSelectedItself = true;
+    if (isMultipleSelectNode(itemMarkesAsSelected)) {
+      if (multiSelectionableChilrens.some((child) => child.dsId === itemMarkesAsSelected.dsId))
+        selectedMultiChildren.push(itemMarkesAsSelected);
+    }
+  });
+  if (!isSelectedItself) return false;
+  if (multiSelectionableChilrens.length === 0) return true;
+  if (selectedMultiChildren.length === 0) return false;
+  if (selectedMultiChildren.length !== multiSelectionableChilrens.length) return "mixed";
+  return true;
+};
+const getNewSelectionForMultipleSelectOnlyNode = (selectedItems, selectedItem) => {
+  const isDeselectingItem = selectedItems.find((item) => item.dsId === selectedItem.dsId) ?? false;
+  let newSelection = isDeselectingItem ? selectedItems.filter(({ dsId }) => dsId !== selectedItem.dsId) : [...selectedItems, selectedItem];
+  const notSelectedMultiParents = [];
+  const selectedMultiParents = [];
+  const multiParentsToDeselect = [];
+  selectedItem.walkParents((parent) => {
+    if (parent.dsId === selectedItem.dsId) return true;
+    const typedParent = parent;
+    if (isMultipleSelectWithSubmenuNode(typedParent)) {
+      const isAlreadySelected = newSelection.find((item) => item.dsId === typedParent.dsId);
+      if (isAlreadySelected) {
+        selectedMultiParents.push(typedParent);
+        const isParentSelected = getIsMultipleSelectNodeWithSubmenuSelected({
+          itemNode: typedParent,
+          selectedItems: newSelection
+        });
+        if (isParentSelected === false) multiParentsToDeselect.push(typedParent);
+      } else notSelectedMultiParents.push(typedParent);
+    }
+    return true;
+  });
+  if (isDeselectingItem) {
+    newSelection = newSelection.filter(({ dsId }) => !multiParentsToDeselect.some((parent) => parent.dsId === dsId));
+  } else {
+    newSelection.push(...notSelectedMultiParents);
+  }
+  return newSelection;
+};
+const getNewSelectionForMultipleSelectionWithSubmenuNode = (selectedItems, selectedItem) => {
+  const currentStatus = getIsMultipleSelectNodeWithSubmenuSelected({
+    itemNode: selectedItem,
+    selectedItems
+  });
+  const isDeselectingItem = currentStatus === true;
+  let newSelection = isDeselectingItem ? selectedItems.filter(({ dsId }) => dsId !== selectedItem.dsId) : [...selectedItems, selectedItem];
+  selectedItem.walk((child) => {
+    const typedChild = child;
+    if (isDeselectingItem) {
+      newSelection = newSelection.filter(({ dsId }) => dsId !== typedChild.dsId);
+    } else if (isMultipleSelectNode(typedChild) && !newSelection.find((item) => item.dsId === typedChild.dsId)) {
+      newSelection.push(typedChild);
+    }
+    return true;
+  });
+  const notSelectedMultiParents = [];
+  const selectedMultiParents = [];
+  const multiParentsToDeselect = [];
+  selectedItem.walkParents((parent) => {
+    if (parent.dsId === selectedItem.dsId) return true;
+    const typedParent = parent;
+    if (isMultipleSelectWithSubmenuNode(typedParent)) {
+      const isAlreadySelected = newSelection.find((item) => item.dsId === typedParent.dsId);
+      if (isAlreadySelected) {
+        selectedMultiParents.push(typedParent);
+        const isParentSelected = getIsMultipleSelectNodeWithSubmenuSelected({
+          itemNode: typedParent,
+          selectedItems: newSelection
+        });
+        if (isParentSelected === false) multiParentsToDeselect.push(typedParent);
+      } else notSelectedMultiParents.push(typedParent);
+    }
+    return true;
+  });
+  if (isDeselectingItem) {
+    newSelection = newSelection.filter(({ dsId }) => !multiParentsToDeselect.some((parent) => parent.dsId === dsId));
+  } else {
+    newSelection.push(...notSelectedMultiParents);
+  }
+  return newSelection;
+};
+const getNewSelectionMultipleSelect = (selectedItems, selectedItem) => {
+  if (isMultipleSelectOnlyNode(selectedItem))
+    return getNewSelectionForMultipleSelectOnlyNode(selectedItems, selectedItem);
+  if (isMultipleSelectWithSubmenuNode(selectedItem))
+    return getNewSelectionForMultipleSelectionWithSubmenuNode(selectedItems, selectedItem);
+  console.log(selectedItem);
+  throw UNEXPECTED_INTERNAL_ERRORS.CALCULATING_MULTI_SELECTION_OF_NON_MULTI_SELECTION_NODE;
+};
+export {
+  getIsMultipleSelectNodeWithSubmenuSelected,
+  getNewSelectionMultipleSelect
+};
+//# sourceMappingURL=multipleSelectionHelpers.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/utils/multipleSelectionHelpers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/utils/multipleSelectionHelpers.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable no-console */\n/* eslint-disable max-statements */\nimport { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport {\n  isMultipleSelectNode,\n  isMultipleSelectOnlyNode,\n  isMultipleSelectWithSubmenuNode,\n} from '../../../utils/nodesTypeguardsAndGetters.js';\nimport { UNEXPECTED_INTERNAL_ERRORS } from '../constants/Errors.js';\nimport { getChildrenByCriterias } from './nodeGettersByCriterias.js';\n\nexport const getIsMultipleSelectNodeWithSubmenuSelected = ({\n  itemNode,\n  selectedItems,\n}: {\n  itemNode: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem;\n  selectedItems: DSMenuButtonT.SelectionableMenuNodes[];\n}) => {\n  // no selected items, nothing is selected <- this is not selected neither, nothing else to check\n  if (selectedItems.length === 0) return false;\n\n  const { multiSelectionableChilrens } = getChildrenByCriterias(itemNode);\n  const selectedMultiChildren: DSMenuButtonT.MultipleSelectionableMenuNodes[] = [];\n  let isSelectedItself = false;\n  selectedItems.forEach((itemMarkesAsSelected) => {\n    if (itemMarkesAsSelected.dsId === itemNode.dsId) isSelectedItself = true;\n    if (isMultipleSelectNode(itemMarkesAsSelected)) {\n      // we reduce scenarios of O(n*m), if the node is not a multi-selectable node, we don't iterate the multiSelectionable childrens\n      if (multiSelectionableChilrens.some((child) => child.dsId === itemMarkesAsSelected.dsId))\n        selectedMultiChildren.push(itemMarkesAsSelected);\n    }\n  });\n  // console.group(`${itemNode.dsId} > getting \"selected\" (true/false/mixed) status`);\n  // console.log({\n  //   itemNode: itemNode.dsId,\n  //   selectedItems: selectedItems.map((itm) => itm.dsId),\n  //   multiSelectionableChilrens: multiSelectionableChilrens.map((itm) => itm.dsId),\n  //   selectedMultiChildren: selectedMultiChildren.map((itm) => itm.dsId),\n  //   isSelectedItself,\n  // });\n  // console.groupEnd();\n  // if it's not marked as selected, it's not selected.\n  if (!isSelectedItself) return false;\n  // if the node doesn't even have multi children, to calculate 'mixed' status upon (it may still have radios)\n  //  (and is selected itself), it's selected\n  if (multiSelectionableChilrens.length === 0) return true;\n\n  // multi children exist and the node is selected\n  //  it can be\n  //    true if all the multi children are selected\n  //    mixed if not all the multi children are selected\n  //    false if all the multi children are not selected\n\n  // multi children exist but none are selected at all?\n  if (selectedMultiChildren.length === 0) return false;\n  // any multi children is not selected?\n  if (selectedMultiChildren.length !== multiSelectionableChilrens.length) return 'mixed';\n  // there is a multi selection, and everything is selected\n  return true;\n};\n\nconst getNewSelectionForMultipleSelectOnlyNode = (\n  selectedItems: DSMenuButtonT.SelectionableMenuNodes[],\n  selectedItem: DSMenuButtonT.MenuNodeMultipleSelectItem,\n) => {\n  const isDeselectingItem = selectedItems.find((item) => item.dsId === selectedItem.dsId) ?? false;\n\n  let newSelection = isDeselectingItem\n    ? selectedItems.filter(({ dsId }) => dsId !== selectedItem.dsId)\n    : [...selectedItems, selectedItem];\n  const notSelectedMultiParents: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem[] = [];\n  const selectedMultiParents: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem[] = [];\n  const multiParentsToDeselect: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem[] = [];\n\n  // we walk the parents and track info about them\n  selectedItem.walkParents((parent) => {\n    // discard ourself, only interested in the parents\n    if (parent.dsId === selectedItem.dsId) return true;\n    // DSTree typescripst doesn't understand ethereogenic nodes, so we need to typecast\n    const typedParent = parent as unknown as DSMenuButtonT.MenuNode;\n    if (isMultipleSelectWithSubmenuNode(typedParent)) {\n      // before we add the parent, we need to check if it's already in the selection\n      const isAlreadySelected = newSelection.find((item) => item.dsId === typedParent.dsId);\n      if (isAlreadySelected) {\n        selectedMultiParents.push(typedParent);\n        // we check if the parent is mixed or should be false (so we can deselect it)\n        const isParentSelected = getIsMultipleSelectNodeWithSubmenuSelected({\n          itemNode: typedParent,\n          selectedItems: newSelection,\n        });\n        if (isParentSelected === false) multiParentsToDeselect.push(typedParent);\n      } else notSelectedMultiParents.push(typedParent);\n    }\n    return true;\n  });\n\n  if (isDeselectingItem) {\n    // if we are deselecting:\n    //  we need to remove the parent nodes that are not selected anymore\n    //   (they transition from mixed to not selected because of this item deselection)\n    newSelection = newSelection.filter(({ dsId }) => !multiParentsToDeselect.some((parent) => parent.dsId === dsId));\n  } else {\n    // if we are selecting:\n    //  we need to add the parent nodes that are not selected yet\n    //   (they transition from not selected to mixed because of this item selection)\n    newSelection.push(...notSelectedMultiParents);\n  }\n\n  return newSelection;\n};\n\nconst getNewSelectionForMultipleSelectionWithSubmenuNode = (\n  selectedItems: DSMenuButtonT.SelectionableMenuNodes[],\n  selectedItem: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem,\n) => {\n  // when selecting/deselecting a node with a submenu, we need to consider the hierarchy of the selection starting from here\n  //  both upwards and downwards\n  // - upwards\n  //   we have to check if any multi-selectable-with-submenu parent transition from not selected to mixed || mixed to selected\n  // - downwards\n  //   - Deselect\n  //     we have to deselect all the selectable children (regarless of the depth of the children and kind of selection)\n  //   - Select\n  //     we have to select all the multi-selectable children that are not selected yet (both with and without submenu)\n\n  // console.group(`${selectedItem.dsId} > getting new selection`);\n  const currentStatus = getIsMultipleSelectNodeWithSubmenuSelected({\n    itemNode: selectedItem,\n    selectedItems,\n  });\n  const isDeselectingItem = currentStatus === true;\n\n  let newSelection = isDeselectingItem\n    ? selectedItems.filter(({ dsId }) => dsId !== selectedItem.dsId)\n    : [...selectedItems, selectedItem];\n\n  // console.log(\n  //   'starting newSelection',\n  //   newSelection.map(({ dsId }) => dsId),\n  // );\n\n  // we walk the children first and update the new selection accordingly\n  //  (it's important we first traverse the children, so we can update the selection of the parents accordingly to the new selection)\n  selectedItem.walk((child) => {\n    // DSTree typescripst doesn't understand ethereogenic nodes, so we need to typecast\n    const typedChild = child as unknown as DSMenuButtonT.SelectionableMenuNodes;\n    if (isDeselectingItem) {\n      // if we are deselecting, we need to remove the children from the selection\n      newSelection = newSelection.filter(({ dsId }) => dsId !== typedChild.dsId);\n    } else if (isMultipleSelectNode(typedChild) && !newSelection.find((item) => item.dsId === typedChild.dsId)) {\n      // if we are selecting, we need to add all the multi children to the selection (if they are not already there)\n      // (we don't do anything with single-selectable nodes, they are not affected by this operation by definition)\n      newSelection.push(typedChild);\n    }\n    return true;\n  });\n\n  // console.log(\n  //   'newSelection after applying logic to children, pre parents traversal',\n  //   newSelection.map(({ dsId }) => dsId),\n  // );\n\n  // now newSelection has the correct information about the node itself and its children\n  // we need to update the parents accordingly\n\n  const notSelectedMultiParents: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem[] = [];\n  const selectedMultiParents: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem[] = [];\n  const multiParentsToDeselect: DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem[] = [];\n  // we walk the parents and track info about them\n  selectedItem.walkParents((parent) => {\n    // discard ourself, only interested in the parents\n    if (parent.dsId === selectedItem.dsId) return true;\n    // DSTree typescripst doesn't understand ethereogenic nodes, so we need to typecast\n    const typedParent = parent as unknown as DSMenuButtonT.MenuNode;\n    if (isMultipleSelectWithSubmenuNode(typedParent)) {\n      // before we add the parent, we need to check if it's already in the selection\n      const isAlreadySelected = newSelection.find((item) => item.dsId === typedParent.dsId);\n      if (isAlreadySelected) {\n        selectedMultiParents.push(typedParent);\n        // we check if the parent is mixed or should be false (so we can deselect it)\n        const isParentSelected = getIsMultipleSelectNodeWithSubmenuSelected({\n          itemNode: typedParent,\n          selectedItems: newSelection,\n        });\n        if (isParentSelected === false) multiParentsToDeselect.push(typedParent);\n      } else notSelectedMultiParents.push(typedParent);\n    }\n    return true;\n  });\n\n  // console.log(\n  //   'parents info > notSelectedMultiParents',\n  //   notSelectedMultiParents.map(({ dsId }) => dsId),\n  // );\n  // console.log(\n  //   'parents info > selectedMultiParents',\n  //   selectedMultiParents.map(({ dsId }) => dsId),\n  // );\n  // console.log(\n  //   'parents info > multiParentsToDeselect',\n  //   multiParentsToDeselect.map(({ dsId }) => dsId),\n  // );\n\n  // finally we use the info we gathered to update the selection\n  if (isDeselectingItem) {\n    // if we are deselecting:\n    //  we need to remove the parent nodes that are not selected anymore\n    //   (they transition from mixed to not selected because of this item deselection)\n    newSelection = newSelection.filter(({ dsId }) => !multiParentsToDeselect.some((parent) => parent.dsId === dsId));\n  } else {\n    // if we are selecting:\n    //  we need to add the parent nodes that are not selected yet\n    //   (they transition from not selected to mixed because of this item selection)\n    newSelection.push(...notSelectedMultiParents);\n  }\n\n  // console.log(\n  //   'final newSelection',\n  //   newSelection.map(({ dsId }) => dsId),\n  // );\n\n  // console.groupEnd();\n  return newSelection;\n};\n\nexport const getNewSelectionMultipleSelect = (\n  selectedItems: DSMenuButtonT.SelectionableMenuNodes[],\n  selectedItem: DSMenuButtonT.MultipleSelectionableMenuNodes,\n) => {\n  // depending on if we are selecting/deselecting an item with/without submenu, we need to handle the selection differently\n  if (isMultipleSelectOnlyNode(selectedItem))\n    return getNewSelectionForMultipleSelectOnlyNode(selectedItems, selectedItem);\n\n  if (isMultipleSelectWithSubmenuNode(selectedItem))\n    return getNewSelectionForMultipleSelectionWithSubmenuNode(selectedItems, selectedItem);\n\n  // if we reach this point, we are in an invalid state, we should never reach here\n  console.log(selectedItem);\n  throw UNEXPECTED_INTERNAL_ERRORS.CALCULATING_MULTI_SELECTION_OF_NON_MULTI_SELECTION_NODE;\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/utils/nodeGettersByCriterias.js

@@ -0,0 +1,123 @@
+import * as React from "react";
+import {
+  isFocusableNode,
+  isGroup,
+  isMenuNodeAllowedToHaveChildren,
+  isMultipleSelectNode,
+  isSelectionableNode,
+  isSelectionableWithSubmenuNode,
+  isSingleSelectNode,
+  isWithSubmenuNode
+} from "../../../utils/nodesTypeguardsAndGetters.js";
+import { TREE_STRUCTURE_ERRORS, UNEXPECTED_INTERNAL_ERRORS } from "../constants/Errors.js";
+const getSubMenusPath = (itemNode) => {
+  const subMenuNodesPath = [];
+  itemNode.walkParents((node) => {
+    if (node.dsId === itemNode.dsId) return true;
+    if (isWithSubmenuNode(node)) {
+      subMenuNodesPath.push(node);
+    }
+    return true;
+  });
+  return subMenuNodesPath.reverse();
+};
+const getFocusableSiblingsList = (itemNode) => {
+  const { parent: parentNode } = itemNode;
+  if (!parentNode) {
+    console.log("getFocusableSiblingsList > itemNode", itemNode);
+    throw UNEXPECTED_INTERNAL_ERRORS.NODE_WITHOUT_PARENT;
+  }
+  if (!isMenuNodeAllowedToHaveChildren(parentNode)) {
+    console.log("parentNode", parentNode);
+    console.log("itemNode", itemNode);
+    throw TREE_STRUCTURE_ERRORS.NODE_CANNOT_HAVE_CHILDREN;
+  }
+  const focusableSiblingsNodes = [];
+  let parseableParentNode = parentNode;
+  if (isGroup(parentNode)) {
+    if (!parentNode.parent) {
+      throw TREE_STRUCTURE_ERRORS.GROUP_WITHOUT_PARENT;
+    }
+    parseableParentNode = parentNode.parent;
+  }
+  parseableParentNode.children.forEach((node) => {
+    if (isFocusableNode(node)) {
+      focusableSiblingsNodes.push(node);
+    }
+    if (isGroup(node)) {
+      node.children.forEach((groupChild) => {
+        if (isFocusableNode(groupChild)) {
+          focusableSiblingsNodes.push(groupChild);
+        }
+      });
+    }
+  });
+  return focusableSiblingsNodes;
+};
+const getAllSingleSelectIdsFromParent = (oldestParent) => {
+  const singleSelectionableItemsIds = [];
+  oldestParent.walk((node) => {
+    const typeCastedNode = node;
+    if (isSingleSelectNode(typeCastedNode)) {
+      singleSelectionableItemsIds.push(node.dsId);
+    }
+    return true;
+  });
+  return singleSelectionableItemsIds;
+};
+const getParentsByCriterias = (menuNode) => {
+  let oldestGroupFoundSoFar;
+  const selectionableParentsWithSubmenu = [];
+  const groupParents = [];
+  menuNode.walkParents((node) => {
+    if (node.dsId === menuNode.dsId) return true;
+    const typeCastedNode = node;
+    if (isGroup(typeCastedNode)) {
+      oldestGroupFoundSoFar = typeCastedNode;
+      groupParents.push(oldestGroupFoundSoFar);
+      return true;
+    }
+    if (isSelectionableWithSubmenuNode(typeCastedNode)) {
+      selectionableParentsWithSubmenu.push(typeCastedNode);
+      return true;
+    }
+    return true;
+  });
+  if (!oldestGroupFoundSoFar) {
+    console.log("node:", menuNode);
+    console.log("parent:", menuNode.parent);
+    throw TREE_STRUCTURE_ERRORS.PARENT_NOT_GROUP;
+  }
+  return {
+    oldestGroup: oldestGroupFoundSoFar,
+    selectionableParentsWithSubmenu,
+    groupParents
+  };
+};
+const getChildrenByCriterias = (menuNode) => {
+  const selectionableChilrens = [];
+  const multiSelectionableChilrens = [];
+  menuNode.walk((node) => {
+    if (node.dsId === menuNode.dsId) return true;
+    const typeCastedNode = node;
+    if (isSelectionableNode(typeCastedNode)) {
+      selectionableChilrens.push(typeCastedNode);
+      if (isMultipleSelectNode(typeCastedNode)) {
+        multiSelectionableChilrens.push(typeCastedNode);
+      }
+    }
+    return true;
+  });
+  return {
+    selectionableChilrens,
+    multiSelectionableChilrens
+  };
+};
+export {
+  getAllSingleSelectIdsFromParent,
+  getChildrenByCriterias,
+  getFocusableSiblingsList,
+  getParentsByCriterias,
+  getSubMenusPath
+};
+//# sourceMappingURL=nodeGettersByCriterias.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/utils/nodeGettersByCriterias.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/utils/nodeGettersByCriterias.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable no-console */\n/* eslint-disable max-lines */\n/* eslint-disable max-statements */\n/* eslint-disable complexity */\nimport type { DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport {\n  isFocusableNode,\n  isGroup,\n  isMenuNodeAllowedToHaveChildren,\n  isMultipleSelectNode,\n  isSelectionableNode,\n  isSelectionableWithSubmenuNode,\n  isSingleSelectNode,\n  isWithSubmenuNode,\n} from '../../../utils/nodesTypeguardsAndGetters.js';\nimport { TREE_STRUCTURE_ERRORS, UNEXPECTED_INTERNAL_ERRORS } from '../constants/Errors.js';\n\nexport const getSubMenusPath = (itemNode: DSMenuButtonT.MenuNode) => {\n  const subMenuNodesPath: DSMenuButtonT.WithSubmenuMenuNodes[] = [];\n  itemNode.walkParents((node) => {\n    // discards itself, we want the parents only\n    if (node.dsId === itemNode.dsId) return true;\n    if (isWithSubmenuNode(node)) {\n      subMenuNodesPath.push(node);\n    }\n    return true;\n  });\n  return subMenuNodesPath.reverse();\n};\n\nexport const getFocusableSiblingsList = (itemNode: DSMenuButtonT.MenuNode) => {\n  const { parent: parentNode } = itemNode;\n  if (!parentNode) {\n    console.log('getFocusableSiblingsList > itemNode', itemNode);\n    throw UNEXPECTED_INTERNAL_ERRORS.NODE_WITHOUT_PARENT;\n  }\n  if (!isMenuNodeAllowedToHaveChildren(parentNode)) {\n    // this should be impossible to reach, if this is reached, there is a bug in the code/validation checks\n    console.log('parentNode', parentNode);\n    console.log('itemNode', itemNode);\n    throw TREE_STRUCTURE_ERRORS.NODE_CANNOT_HAVE_CHILDREN;\n  }\n  // each tree depth may be composed of a mix of focusable and non-focusable nodes\n  //  in particular, the parent node may be a group node which is not focusable but it's children are (and are visually siblings)\n  // we need to do our calculations only on top of focusable nodes, and we also need to consider the scenario of a group node\n  const focusableSiblingsNodes: DSMenuButtonT.PseudoFocusableMenuNodes[] = [];\n\n  let parseableParentNode = parentNode;\n  // nesting a group node inside another group node is not allowed\n  //  I could not find a supporting explicit statement in the WCAG standard,\n  //   but given how everything else is defined and graphically represented,\n  //   it's the only logical conclusion.\n  //     Nesting would result in nodes being visually siblings\n  //      but logically non-exclusively selectable,\n  //        which would be a contradiction of the visuals\n  //        so violating the WCAG standard for other reasons\n  if (isGroup(parentNode)) {\n    if (!parentNode.parent) {\n      throw TREE_STRUCTURE_ERRORS.GROUP_WITHOUT_PARENT;\n    }\n    parseableParentNode = parentNode.parent;\n  }\n\n  parseableParentNode.children.forEach((node) => {\n    if (isFocusableNode(node)) {\n      focusableSiblingsNodes.push(node);\n    }\n    // if we encounter a group node we need to add it's children too\n    // (which here is guaranteed because we checked it in the if statement above)\n    if (isGroup(node)) {\n      node.children.forEach((groupChild) => {\n        if (isFocusableNode(groupChild)) {\n          focusableSiblingsNodes.push(groupChild);\n        }\n      });\n    }\n  });\n\n  return focusableSiblingsNodes;\n};\n\n/**\n * This functions walks the tree downwards starting from the oldest shared parent and returns all the single-selectable items ids\n * @param oldestParent - the oldest parent to start the walk from\n * @returns string | number[] - the list of all the single-selectable items ids starting from the oldest shared group\n */\nexport const getAllSingleSelectIdsFromParent = (oldestParent: DSMenuButtonT.MenuNodesAllowedToHaveChildren) => {\n  const singleSelectionableItemsIds: (string | number)[] = [];\n  oldestParent.walk((node) => {\n    // DSTree typescript doesn't understand ethereogeneous subitems, so we need to typecast manually\n    const typeCastedNode = node as unknown as\n      | DSMenuButtonT.SingleSelectionableMenuNodes\n      | DSMenuButtonT.MenuNodeSeparatorItem;\n    // is the node is a single-selectable item, we add it to the list\n    if (isSingleSelectNode(typeCastedNode)) {\n      singleSelectionableItemsIds.push(node.dsId);\n    }\n    // we walk all the tree (from the shared group), we never shortcircuit\n    return true;\n  });\n  return singleSelectionableItemsIds;\n};\n\n/**\n * walk all parents from a given node and gives back multiple supporting datastructures by different criterias\n *\n * @param menuNode\n * @returns {object} - an object holding different datastructures and information about the parents\n * @property {Object} oldestGroup - the oldest shared group\n * @property {Object[]} selectionableParentsWithSubmenu - the single/multiple selection parents with submenu\n * @property {Object[]} groupParents - all the 'groups' encountered while traversing the tree upwards\n */\nexport const getParentsByCriterias = (menuNode: DSMenuButtonT.MenuNode) => {\n  // group\n  let oldestGroupFoundSoFar: DSMenuButtonT.MenuNodeGroupItem;\n  const selectionableParentsWithSubmenu: DSMenuButtonT.SelectionablesWithSubmenuMenuNodes[] = [];\n  const groupParents: DSMenuButtonT.MenuNodeGroupItem[] = [];\n\n  menuNode.walkParents((node) => {\n    // discards itself, we want the parents only\n    if (node.dsId === menuNode.dsId) return true;\n    // DSTree is not able to understand ethereogeneous subitems, so we need to typecast manually\n    const typeCastedNode = node as unknown as DSMenuButtonT.MenuNode;\n\n    if (isGroup(typeCastedNode)) {\n      oldestGroupFoundSoFar = typeCastedNode;\n      groupParents.push(oldestGroupFoundSoFar);\n      // nothing else to do in this walking step, returing true to continue the walk\n      return true;\n    }\n    // we continue checking shared parents untill we see the pattern\n    //  group -> single-select-with-submenu -> group -> ...\n    // the moment the parent of a group is not a single-select-with-submenu we can stop,\n    //  we have found the oldest shared group\n    if (isSelectionableWithSubmenuNode(typeCastedNode)) {\n      selectionableParentsWithSubmenu.push(typeCastedNode);\n      return true;\n    }\n    // the node is not a single-select-with-submenu, we can stop the walk\n    return true;\n  });\n  // if we found no group parent starting from menuNode, the tree is malformed\n  // @ts-expect-error - typescript doesn't understand that \"walkParents\" actually executes the function synchronously\n  //  so it thinks that oldestGroupFoundSoFar was never assigned, it's a false positive\n  if (!oldestGroupFoundSoFar) {\n    console.log('node:', menuNode);\n    console.log('parent:', menuNode.parent);\n    throw TREE_STRUCTURE_ERRORS.PARENT_NOT_GROUP;\n  }\n  return {\n    oldestGroup: oldestGroupFoundSoFar,\n    selectionableParentsWithSubmenu,\n    groupParents,\n  };\n};\n\n/**\n * walk all childrens from a given node and gives back multiple supporting datastructures by different criterias\n *\n * @param menuNode\n * @returns {object} - an object holding different datastructures and information about the children\n * @property {Object[]} selectionableChilrens - the single/multiple selection children (regardless of the presence of a submenu)\n * @property {Object[]} multiSelectionableChilrens - the multiple selection children (regardless of the presence of a submenu)\n */\nexport const getChildrenByCriterias = (menuNode: DSMenuButtonT.MenuNode) => {\n  const selectionableChilrens: DSMenuButtonT.SelectionableMenuNodes[] = [];\n  const multiSelectionableChilrens: DSMenuButtonT.MultipleSelectionableMenuNodes[] = [];\n  menuNode.walk((node) => {\n    // discards itself, we want the children only\n    if (node.dsId === menuNode.dsId) return true;\n    // DSTree is not able to understand ethereogeneous subitems, so we need to typecast manually\n    const typeCastedNode = node as unknown as DSMenuButtonT.MenuNode;\n    if (isSelectionableNode(typeCastedNode)) {\n      selectionableChilrens.push(typeCastedNode);\n      if (isMultipleSelectNode(typeCastedNode)) {\n        multiSelectionableChilrens.push(typeCastedNode);\n      }\n    }\n    // we walk all the tree (from the shared group), we never shortcircuit\n    return true;\n  });\n  return {\n    selectionableChilrens,\n    multiSelectionableChilrens,\n  };\n};\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/esm/parts/DSMenuBehaviouralContextProvider/utils/singleSelectionHelpers.js

@@ -0,0 +1,14 @@
+import * as React from "react";
+import { getAllSingleSelectIdsFromParent, getParentsByCriterias } from "./nodeGettersByCriterias.js";
+const getNewSelectionSingleSelect = (selectedItems, selectedItem) => {
+  const { oldestGroup, selectionableParentsWithSubmenu } = getParentsByCriterias(selectedItem);
+  const itemsIdsToDeselect = getAllSingleSelectIdsFromParent(oldestGroup);
+  const newSelection = selectedItems.filter((item) => !itemsIdsToDeselect.includes(item.plainItem.dsId));
+  newSelection.push(...selectionableParentsWithSubmenu);
+  newSelection.push(selectedItem);
+  return newSelection;
+};
+export {
+  getNewSelectionSingleSelect
+};
+//# sourceMappingURL=singleSelectionHelpers.js.map

package/dist/esm/parts/DSMenuBehaviouralContextProvider/utils/singleSelectionHelpers.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/utils/singleSelectionHelpers.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport { getAllSingleSelectIdsFromParent, getParentsByCriterias } from './nodeGettersByCriterias.js';\n\n/**\n * When a single-selectable item is selected, all other single-selectable items in the same group are deselected;\n *\n * If the (visual) parent is a single-select-with-submenu,\n *  the selection must be propagated because\n *  a single-select within a single-select-with-submenu can't be selected without implying the selection of the parent single-select-with-submenu\n *\n * @param selectedItems - the current selected items\n * @param selectedItem - the newly selected item\n * @returns DSMenuButtonT.SelectionableMenuNodes[] - the new selection\n */\nexport const getNewSelectionSingleSelect = (\n  selectedItems: DSMenuButtonT.SelectionableMenuNodes[],\n  selectedItem: DSMenuButtonT.MenuNodeSingleSelectItem | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem,\n) => {\n  const { oldestGroup, selectionableParentsWithSubmenu } = getParentsByCriterias(selectedItem);\n  const itemsIdsToDeselect = getAllSingleSelectIdsFromParent(oldestGroup);\n  // we remove all the ids of single selection parents from the previous selection\n  const newSelection = selectedItems.filter((item) => !itemsIdsToDeselect.includes(item.plainItem.dsId));\n  // we add all the parents submenus to the selection\n  newSelection.push(...selectionableParentsWithSubmenu);\n  // finally we add the newly selected item\n  newSelection.push(selectedItem);\n\n  return newSelection;\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACCvB,SAAS,iCAAiC,6BAA6B;AAahE,MAAM,8BAA8B,CACzC,eACA,iBACG;AACH,QAAM,EAAE,aAAa,gCAAgC,IAAI,sBAAsB,YAAY;AAC3F,QAAM,qBAAqB,gCAAgC,WAAW;AAEtE,QAAM,eAAe,cAAc,OAAO,CAAC,SAAS,CAAC,mBAAmB,SAAS,KAAK,UAAU,IAAI,CAAC;AAErG,eAAa,KAAK,GAAG,+BAA+B;AAEpD,eAAa,KAAK,YAAY;AAE9B,SAAO;AACT;",
+  "names": []
+}