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

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';\n\nimport { DSMenuButtonName, MENU_BUTTON_SLOTS, type MENU_ITEMS_TYPES } from './constants/index.js';\nexport declare namespace DSMenuButtonT {\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  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    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    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    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    disabled?: boolean;\n    onClick?: (e: React.MouseEvent | React.KeyboardEvent) => void;\n    onKeyDown?: (e: React.KeyboardEvent) => null;\n  }\n\n  /* ***********************************************************************\n   * Single select items MUST always have a \"group\" as parent\n   *   Failing the condition fails ADA announcements (role='group' -> role='menuitemradio')\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    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\n  export type PseudoFocusableItemInterface =\n    | ActivableItem\n    | ActionableWithSubmenuItem\n    | SkeletonItem\n    | MultipleSelectItem\n    | MultiSelectWithSubmenuItem\n    | WithSubmenuItem\n    | SingleSelectItem\n    | SingleSelectWithSubmenuItem;\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 ItemRendererT = React.ComponentType<{ itemNode: MenuNode }>;\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\n    | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem;\n\n  export type SingleSelectionableMenuNodes =\n    | DSMenuButtonT.MenuNodeSingleSelectItem\n    | 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\n    | DSMenuButtonT.MenuNodeSingleSelectWithSubmenuItem;\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\n  export interface MenuBehaviouralLayerRequiredProps {\n    selectedItems: SelectionableMenuNodes[];\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\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,\n      ButtonInheritedRequiredProps,\n      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   * 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    selectedOptions: Record<string, boolean>;\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,\n      ButtonInheiredDefaultProps,\n      MenuBehaviouralLayerDefaultProps {}\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    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  }\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 MenuSpecificOptionalProps,\n      ButtonInheritedOptionalProps,\n      MenuBehaviouralLayerOptionalProps,\n      TypescriptHelpersT.PropsForGlobalOnSlots<typeof DSMenuButtonName, typeof MENU_BUTTON_SLOTS> {}\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 Partial<MenuBehaviouralLayerDefaultProps>,\n      MenuBehaviouralLayerOptionalProps,\n      MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificProps\n    extends Partial<MenuSpecifiDefaultProps>,\n      MenuSpecificOptionalProps,\n      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 extends RequiredProps, Partial<DefaultProps>, OptionalProps {}\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,\n      MenuBehaviouralLayerOptionalProps,\n      MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificInternalProps\n    extends MenuSpecifiDefaultProps,\n      MenuSpecificOptionalProps,\n      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 extends RequiredProps, DefaultProps, OptionalProps {}\n}\n\nexport const defaultProps: DSMenuButtonT.MenuSpecifiDefaultProps = {\n  selectedOptions: {},\n  onClickOutside: () => null,\n  onOptionClick: () => null,\n  openedSubmenus: {},\n  onSubmenuToggle: () => null,\n  isLoading: false,\n  isSkeleton: false,\n};\n\nexport const MenuBehaviouralLayerPropTypes: DSPropTypesSchema<DSMenuButtonT.MenuBehaviouralLayerProps> = {\n  selectedItems: PropTypes.arrayOf(PropTypes.object).description(\n    'an array of tree-nodes that have to be marked as selected in the GUI',\n  ).isRequired,\n\n  onItemSelected: PropTypes.func.description('IoC function in charge of handling the selection of a menu item')\n    .signature(`((\n      newSelection: DSMenuButtonT.PseudoFocusableMenuNodes[],\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`).isRequired,\n  onActivateItem: PropTypes.func.description(\n    'IoC function in charge of handling the activation (NOT INVOKED ON SELECTION) of a menu item',\n  ).signature(`((\n      itemNode: DSMenuButtonT.PseudoFocusableMenuNodes,\n      metainfo: { itemNode: DSMenuButtonT.PseudoFocusableMenuNodes; event?: React.SyntheticEvent },\n    ) => void)`).isRequired,\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  selectedOptions: PropTypes.object\n    .description(\n      'Object with the ids of the options as keys, and booleans as keys. Represents the state of the current selection in the dropdown menu',\n    )\n    .defaultValue({}),\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};\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  ...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;AAMpC,uBAA2E;AA8ZpE,MAAM,eAAsD;AAAA,EACjE,iBAAiB,CAAC;AAAA,EAClB,gBAAgB,MAAM;AAAA,EACtB,eAAe,MAAM;AAAA,EACrB,gBAAgB,CAAC;AAAA,EACjB,iBAAiB,MAAM;AAAA,EACvB,WAAW;AAAA,EACX,YAAY;AACd;AAEO,MAAM,gCAA4F;AAAA,EACvG,eAAe,kCAAU,QAAQ,kCAAU,MAAM,EAAE;AAAA,IACjD;AAAA,EACF,EAAE;AAAA,EAEF,gBAAgB,kCAAU,KAAK,YAAY,iEAAiE,EACzG,UAAU;AAAA;AAAA;AAAA,eAGA,EAAE;AAAA,EACf,gBAAgB,kCAAU,KAAK;AAAA,IAC7B;AAAA,EACF,EAAE,UAAU;AAAA;AAAA;AAAA,eAGC,EAAE;AAAA,EACf,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,iBAAiB,kCAAU,OACxB;AAAA,IACC;AAAA,EACF,EACC,aAAa,CAAC,CAAC;AAAA,EAClB,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;AACjH;AAEO,MAAM,wBAAgE;AAAA,EAC3E,SAAS,kCAAU,UAAU,CAAC,kCAAU,OAAO,kCAAU,MAAM,CAAC,EAAE;AAAA,IAChE;AAAA,EACF,EAAE;AAAA,EACF,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';\n\nimport { DSMenuButtonName, MENU_BUTTON_SLOTS, type MENU_ITEMS_TYPES } from './constants/index.js';\nexport declare namespace DSMenuButtonT {\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    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    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    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    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    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\n  export type PseudoFocusableItemInterface =\n    | ActivableItem\n    | ActionableWithSubmenuItem\n    | SkeletonItem\n    | MultipleSelectItem\n    | MultiSelectWithSubmenuItem\n    | WithSubmenuItem\n    | SingleSelectItem\n    | 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\n    | DSMenuButtonT.MenuNodeMultipleSelectWithSubmenuItem;\n\n  export type SingleSelectionableMenuNodes =\n    | DSMenuButtonT.MenuNodeSingleSelectItem\n    | 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\n    | 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,\n      ButtonInheritedRequiredProps,\n      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    selectedOptions: Record<string, boolean>;\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,\n      ButtonInheiredDefaultProps,\n      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    selectedItems?: SelectionableMenuNodes[];\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  }\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 MenuSpecificOptionalProps,\n      ButtonInheritedOptionalProps,\n      MenuBehaviouralLayerOptionalProps,\n      TypescriptHelpersT.PropsForGlobalOnSlots<typeof DSMenuButtonName, typeof MENU_BUTTON_SLOTS> {}\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 Partial<MenuBehaviouralLayerDefaultProps>,\n      MenuBehaviouralLayerOptionalProps,\n      MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificProps\n    extends Partial<MenuSpecifiDefaultProps>,\n      MenuSpecificOptionalProps,\n      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 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,\n      MenuBehaviouralLayerOptionalProps,\n      MenuBehaviouralLayerRequiredProps {}\n  export interface MenuSpecificInternalProps\n    extends MenuSpecifiDefaultProps,\n      MenuSpecificOptionalProps,\n      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 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 defaultProps: DSMenuButtonT.MenuSpecifiDefaultProps = {\n  selectedOptions: {},\n  onClickOutside: () => null,\n  onOptionClick: () => null,\n  openedSubmenus: {},\n  onSubmenuToggle: () => null,\n  isLoading: false,\n  isSkeleton: false,\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  selectedItems: PropTypes.arrayOf(PropTypes.object).description(\n    'an array of tree-nodes that have to be marked as selected in the GUI, required if the menu has selectionable items',\n  ),\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  selectedOptions: PropTypes.object\n    .description(\n      'Object with the ids of the options as keys, and booleans as keys. Represents the state of the current selection in the dropdown menu',\n    )\n    .defaultValue({}),\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};\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  ...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;AAMpC,uBAA2E;AAwcpE,MAAM,eAAsD;AAAA,EACjE,iBAAiB,CAAC;AAAA,EAClB,gBAAgB,MAAM;AAAA,EACtB,eAAe,MAAM;AAAA,EACrB,gBAAgB,CAAC;AAAA,EACjB,iBAAiB,MAAM;AAAA,EACvB,WAAW;AAAA,EACX,YAAY;AACd;AAYO,MAAM,gCAA4F;AAAA,EACvG,eAAe,kCAAU,QAAQ,kCAAU,MAAM,EAAE;AAAA,IACjD;AAAA,EACF;AAAA,EACA,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,iBAAiB,kCAAU,OACxB;AAAA,IACC;AAAA,EACF,EACC,aAAa,CAAC,CAAC;AAAA,EAClB,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;AACjH;AAEO,MAAM,wBAAgE;AAAA,EAC3E,SAAS,kCAAU,UAAU,CAAC,kCAAU,OAAO,kCAAU,MAAM,CAAC,EAAE;AAAA,IAChE;AAAA,EACF,EAAE;AAAA,EACF,GAAG;AAAA,EACH,GAAG;AAAA,EACH,GAAG;AAAA,EACH,OAAG,kDAAyB,mCAAkB,kCAAiB;AACjE;AAEO,MAAM,8BAA8B;",
   "names": []
 }

package/dist/esm/config/useMenuButton.js

@@ -1,12 +1,12 @@
 import * as React from "react";
-import React2 from "react";
 import { useGetXstyledProps, useMemoMergePropsWithDefault } from "@elliemae/ds-props-helpers";
+import React2 from "react";
 import { uid } from "uid";
 import { DSMenuButtonPropTypes, defaultProps } from "../react-desc-prop-types.js";
-import { useValidateProps } from "./useValidateProps.js";
-import { useSplitInherithedProps } from "./useSplitInherithedProps.js";
-import { useOptionsArrayToDsTree } from "../utils/useOptionsArrayToDsTree.js";
 import { getFocusableNodes } from "../utils/nodesTypeguardsAndGetters.js";
+import { useOptionsArrayToDsTree } from "../utils/useOptionsArrayToDsTree.js";
+import { useSplitInherithedProps } from "./useSplitInherithedProps.js";
+import { useValidateProps } from "./useValidateProps.js";
 const useMenuButton = (propsFromUser) => {
   const propsWithDefault = useMemoMergePropsWithDefault(propsFromUser, defaultProps);
   useValidateProps(propsWithDefault, DSMenuButtonPropTypes);
@@ -30,19 +30,6 @@ const useMenuButton = (propsFromUser) => {
     focusableNodes,
     treeRootNode
   });
-  const allNodes = treeRootNode.flatten();
-  const nodesWithRepeatedDsId = allNodes.filter(
-    (node, index, self) => self.findIndex((n) => n.dsId === node.dsId) !== index
-  );
-  if (nodesWithRepeatedDsId.length > 0) {
-    throw new Error(
-      `DSMenuButton:
-The following dsId are repeated:
-${nodesWithRepeatedDsId.map((n) => n.dsId).join("\n ")}
-
-The dsId must be unique.`
-    );
-  }
   return React2.useMemo(
     () => ({
       propsWithDefault,

package/dist/esm/config/useMenuButton.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../../scripts/build/transpile/react-shim.js", "../../../src/config/useMenuButton.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import React from 'react';\nimport { useGetXstyledProps, useMemoMergePropsWithDefault } from '@elliemae/ds-props-helpers';\nimport { uid } from 'uid';\nimport { type DSMenuButtonT, DSMenuButtonPropTypes, defaultProps } from '../react-desc-prop-types.js';\nimport { useValidateProps } from './useValidateProps.js';\nimport { useSplitInherithedProps } from './useSplitInherithedProps.js';\nimport { useOptionsArrayToDsTree } from '../utils/useOptionsArrayToDsTree.js';\nimport { getFocusableNodes } from '../utils/nodesTypeguardsAndGetters.js';\nexport interface MenuButtonCTX extends ReturnType<typeof useSplitInherithedProps> {\n  propsWithDefault: DSMenuButtonT.InternalProps;\n  xstyledProps: ReturnType<typeof useGetXstyledProps>;\n  instanceUid: string;\n}\n\nexport const useMenuButton = (propsFromUser: DSMenuButtonT.Props) => {\n  // =============================================================================\n  // MERGE WITH DEFAULT AND VALIDATE PROPS\n  // =============================================================================\n  const propsWithDefault = useMemoMergePropsWithDefault<DSMenuButtonT.InternalProps>(propsFromUser, defaultProps);\n  useValidateProps(propsWithDefault, DSMenuButtonPropTypes);\n  // =============================================================================\n  // XSTYLED PROPS\n  // =============================================================================\n  const xstyledProps = useGetXstyledProps(propsWithDefault);\n  // =============================================================================\n  // AD HOC PER COMPONENT LOGIC\n  // =============================================================================\n  // custom code goes here, this is an example\n  const instanceUid = React.useMemo(() => `menu-button${uid(5)}`, []);\n  // =============================================================================\n  // HELPERS HOOKS CONFIGS\n  // =============================================================================\n\n  // =============================================================================\n  // React hooks can't be invoked conditionally...\n  // =============================================================================\n  const { options: appOptions } = propsWithDefault;\n  const optionsArray: DSMenuButtonT.MenuItemInterface[] = Array.isArray(appOptions) ? appOptions : [];\n\n  const treeRootNodeFromOptionsArrayIfArray = useOptionsArrayToDsTree({\n    options: optionsArray,\n    instanceUid,\n    // this typecast is a safe type reconciliation, typescript checks they are compatible\n    // this typecast let us avoid to have to do the ` | OtherCompatibleType` dance\n  }).getRoot() as DSMenuButtonT.MenuNode;\n  const treeRootNode = React.useMemo(\n    () => (Array.isArray(appOptions) ? treeRootNodeFromOptionsArrayIfArray : appOptions),\n    [appOptions, treeRootNodeFromOptionsArrayIfArray],\n  );\n\n  // =============================================================================\n  // We calculate the focusableNodes from the treeRootNode.plainChildren via getFocusableNodes\n  // =============================================================================\n  const focusableNodes = React.useMemo(() => getFocusableNodes(treeRootNode), [treeRootNode]);\n  const splitInherithedProps = useSplitInherithedProps({\n    propsWithDefault,\n    focusableNodes,\n    treeRootNode,\n  });\n\n  // =============================================================================\n  // if any item as a repeated dsId, we must throw an error,\n  //   the component will not work properly if the dsId is not guaranteed to be unique\n  //   (only validating focusableNodes may work, but as a good practice it's better to validate the whole tree)\n  // =============================================================================\n  const allNodes = treeRootNode.flatten();\n  const nodesWithRepeatedDsId = allNodes.filter(\n    (node, index, self) => self.findIndex((n) => n.dsId === node.dsId) !== index,\n  );\n  if (nodesWithRepeatedDsId.length > 0) {\n    throw new Error(\n      `DSMenuButton:\\nThe following dsId are repeated:\\n${nodesWithRepeatedDsId\n        .map((n) => n.dsId)\n        .join('\\n ')}\\n\\nThe dsId must be unique.`,\n    );\n  }\n\n  return React.useMemo<MenuButtonCTX>(\n    () => ({\n      propsWithDefault,\n      xstyledProps,\n      instanceUid,\n      ...splitInherithedProps,\n    }),\n    [propsWithDefault, xstyledProps, instanceUid, splitInherithedProps],\n  );\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACAvB,OAAOA,YAAW;AAClB,SAAS,oBAAoB,oCAAoC;AACjE,SAAS,WAAW;AACpB,SAA6B,uBAAuB,oBAAoB;AACxE,SAAS,wBAAwB;AACjC,SAAS,+BAA+B;AACxC,SAAS,+BAA+B;AACxC,SAAS,yBAAyB;AAO3B,MAAM,gBAAgB,CAAC,kBAAuC;AAInE,QAAM,mBAAmB,6BAA0D,eAAe,YAAY;AAC9G,mBAAiB,kBAAkB,qBAAqB;AAIxD,QAAM,eAAe,mBAAmB,gBAAgB;AAKxD,QAAM,cAAcA,OAAM,QAAQ,MAAM,cAAc,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AAQlE,QAAM,EAAE,SAAS,WAAW,IAAI;AAChC,QAAM,eAAkD,MAAM,QAAQ,UAAU,IAAI,aAAa,CAAC;AAElG,QAAM,sCAAsC,wBAAwB;AAAA,IAClE,SAAS;AAAA,IACT;AAAA;AAAA;AAAA,EAGF,CAAC,EAAE,QAAQ;AACX,QAAM,eAAeA,OAAM;AAAA,IACzB,MAAO,MAAM,QAAQ,UAAU,IAAI,sCAAsC;AAAA,IACzE,CAAC,YAAY,mCAAmC;AAAA,EAClD;AAKA,QAAM,iBAAiBA,OAAM,QAAQ,MAAM,kBAAkB,YAAY,GAAG,CAAC,YAAY,CAAC;AAC1F,QAAM,uBAAuB,wBAAwB;AAAA,IACnD;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAOD,QAAM,WAAW,aAAa,QAAQ;AACtC,QAAM,wBAAwB,SAAS;AAAA,IACrC,CAAC,MAAM,OAAO,SAAS,KAAK,UAAU,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,MAAM;AAAA,EACzE;AACA,MAAI,sBAAsB,SAAS,GAAG;AACpC,UAAM,IAAI;AAAA,MACR;AAAA;AAAA,EAAoD,sBACjD,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,KAAK,CAAC;AAAA;AAAA;AAAA,IAChB;AAAA,EACF;AAEA,SAAOA,OAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAG;AAAA,IACL;AAAA,IACA,CAAC,kBAAkB,cAAc,aAAa,oBAAoB;AAAA,EACpE;AACF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "/* eslint-disable max-statements */\nimport { useGetXstyledProps, useMemoMergePropsWithDefault } from '@elliemae/ds-props-helpers';\nimport React from 'react';\nimport { uid } from 'uid';\nimport { DSMenuButtonPropTypes, defaultProps, type DSMenuButtonT } from '../react-desc-prop-types.js';\nimport { getFocusableNodes } from '../utils/nodesTypeguardsAndGetters.js';\nimport { useOptionsArrayToDsTree } from '../utils/useOptionsArrayToDsTree.js';\nimport { useSplitInherithedProps } from './useSplitInherithedProps.js';\nimport { useValidateProps } from './useValidateProps.js';\nexport interface MenuButtonCTX extends ReturnType<typeof useSplitInherithedProps> {\n  propsWithDefault: DSMenuButtonT.InternalProps;\n  xstyledProps: ReturnType<typeof useGetXstyledProps>;\n  instanceUid: string;\n}\n\nexport const useMenuButton = (propsFromUser: DSMenuButtonT.Props) => {\n  // =============================================================================\n  // MERGE WITH DEFAULT AND VALIDATE PROPS\n  // =============================================================================\n  const propsWithDefault = useMemoMergePropsWithDefault<DSMenuButtonT.InternalProps>(propsFromUser, defaultProps);\n  useValidateProps(propsWithDefault, DSMenuButtonPropTypes);\n  // =============================================================================\n  // XSTYLED PROPS\n  // =============================================================================\n  const xstyledProps = useGetXstyledProps(propsWithDefault);\n  // =============================================================================\n  // AD HOC PER COMPONENT LOGIC\n  // =============================================================================\n  // custom code goes here, this is an example\n  const instanceUid = React.useMemo(() => `menu-button${uid(5)}`, []);\n  // =============================================================================\n  // HELPERS HOOKS CONFIGS\n  // =============================================================================\n\n  // =============================================================================\n  // React hooks can't be invoked conditionally...\n  // =============================================================================\n  const { options: appOptions } = propsWithDefault;\n  const optionsArray: DSMenuButtonT.MenuItemInterface[] = Array.isArray(appOptions) ? appOptions : [];\n\n  const treeRootNodeFromOptionsArrayIfArray = useOptionsArrayToDsTree({\n    options: optionsArray,\n    instanceUid,\n    // this typecast is a safe type reconciliation, typescript checks they are compatible\n    // this typecast let us avoid to have to do the ` | OtherCompatibleType` dance\n  }).getRoot() as DSMenuButtonT.MenuNode;\n  const treeRootNode = React.useMemo(\n    () => (Array.isArray(appOptions) ? treeRootNodeFromOptionsArrayIfArray : appOptions),\n    [appOptions, treeRootNodeFromOptionsArrayIfArray],\n  );\n\n  // =============================================================================\n  // We calculate the focusableNodes from the treeRootNode.plainChildren via getFocusableNodes\n  // =============================================================================\n  const focusableNodes = React.useMemo(() => getFocusableNodes(treeRootNode), [treeRootNode]);\n  const splitInherithedProps = useSplitInherithedProps({\n    propsWithDefault,\n    focusableNodes,\n    treeRootNode,\n  });\n\n  return React.useMemo<MenuButtonCTX>(\n    () => ({\n      propsWithDefault,\n      xstyledProps,\n      instanceUid,\n      ...splitInherithedProps,\n    }),\n    [propsWithDefault, xstyledProps, instanceUid, splitInherithedProps],\n  );\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACCvB,SAAS,oBAAoB,oCAAoC;AACjE,OAAOA,YAAW;AAClB,SAAS,WAAW;AACpB,SAAS,uBAAuB,oBAAwC;AACxE,SAAS,yBAAyB;AAClC,SAAS,+BAA+B;AACxC,SAAS,+BAA+B;AACxC,SAAS,wBAAwB;AAO1B,MAAM,gBAAgB,CAAC,kBAAuC;AAInE,QAAM,mBAAmB,6BAA0D,eAAe,YAAY;AAC9G,mBAAiB,kBAAkB,qBAAqB;AAIxD,QAAM,eAAe,mBAAmB,gBAAgB;AAKxD,QAAM,cAAcA,OAAM,QAAQ,MAAM,cAAc,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AAQlE,QAAM,EAAE,SAAS,WAAW,IAAI;AAChC,QAAM,eAAkD,MAAM,QAAQ,UAAU,IAAI,aAAa,CAAC;AAElG,QAAM,sCAAsC,wBAAwB;AAAA,IAClE,SAAS;AAAA,IACT;AAAA;AAAA;AAAA,EAGF,CAAC,EAAE,QAAQ;AACX,QAAM,eAAeA,OAAM;AAAA,IACzB,MAAO,MAAM,QAAQ,UAAU,IAAI,sCAAsC;AAAA,IACzE,CAAC,YAAY,mCAAmC;AAAA,EAClD;AAKA,QAAM,iBAAiBA,OAAM,QAAQ,MAAM,kBAAkB,YAAY,GAAG,CAAC,YAAY,CAAC;AAC1F,QAAM,uBAAuB,wBAAwB;AAAA,IACnD;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAED,SAAOA,OAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA;AAAA,MACA,GAAG;AAAA,IACL;AAAA,IACA,CAAC,kBAAkB,cAAc,aAAa,oBAAoB;AAAA,EACpE;AACF;",
   "names": ["React"]
 }

package/dist/esm/index.js

@@ -1,10 +1,12 @@
 import * as React from "react";
 import { DSMenuButton, DSMenuButtonWithSchema } from "./DSMenuButton.js";
+import { DSMenuButtonPropTypes } from "./react-desc-prop-types.js";
 import { MENU_BUTTON_SLOTS, MENU_BUTTON_DATA_TESTID, MENU_ITEMS_TYPES } from "./constants/index.js";
 import { isFocusableNode } from "./utils/nodesTypeguardsAndGetters.js";
 import { useOptionsArrayToDsTree } from "./utils/useOptionsArrayToDsTree.js";
 export {
   DSMenuButton,
+  DSMenuButtonPropTypes,
   DSMenuButtonWithSchema,
   MENU_BUTTON_DATA_TESTID,
   MENU_BUTTON_SLOTS,

package/dist/esm/index.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../scripts/build/transpile/react-shim.js", "../../src/index.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "// this is a workaround to typescript error TS2742\n// https://github.com/microsoft/TypeScript/issues/47663\nimport type {} from '@xstyled/system';\nexport { DSMenuButton, DSMenuButtonWithSchema } from './DSMenuButton.js';\nexport { type DSMenuButtonT } from './react-desc-prop-types.js';\nexport { MENU_BUTTON_SLOTS, MENU_BUTTON_DATA_TESTID, MENU_ITEMS_TYPES } from './constants/index.js';\nexport { isFocusableNode } from './utils/nodesTypeguardsAndGetters.js';\nexport { useOptionsArrayToDsTree } from './utils/useOptionsArrayToDsTree.js';\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACGvB,SAAS,cAAc,8BAA8B;AAErD,SAAS,mBAAmB,yBAAyB,wBAAwB;AAC7E,SAAS,uBAAuB;AAChC,SAAS,+BAA+B;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "// this is a workaround to typescript error TS2742\n// https://github.com/microsoft/TypeScript/issues/47663\nimport type {} from '@xstyled/system';\nexport { DSMenuButton, DSMenuButtonWithSchema } from './DSMenuButton.js';\nexport { type DSMenuButtonT, DSMenuButtonPropTypes } from './react-desc-prop-types.js';\nexport { MENU_BUTTON_SLOTS, MENU_BUTTON_DATA_TESTID, MENU_ITEMS_TYPES } from './constants/index.js';\nexport { isFocusableNode } from './utils/nodesTypeguardsAndGetters.js';\nexport { useOptionsArrayToDsTree } from './utils/useOptionsArrayToDsTree.js';\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACGvB,SAAS,cAAc,8BAA8B;AACrD,SAA6B,6BAA6B;AAC1D,SAAS,mBAAmB,yBAAyB,wBAAwB;AAC7E,SAAS,uBAAuB;AAChC,SAAS,+BAA+B;",
   "names": []
 }

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

@@ -0,0 +1,56 @@
+import * as React from "react";
+import { useEffect } from "react";
+import { isActivableNode, isSelectionableNode } from "../../../utils/nodesTypeguardsAndGetters.js";
+const useAdvancedValidation = ({ propsWithDefault }) => {
+  const { onActivateItem, onItemSelected, selectedItems, optionsTree } = propsWithDefault;
+  useEffect(() => {
+    const allNodes = optionsTree.flatten();
+    const nodesByDsId = {};
+    const duplicatedIdsNodes = {};
+    let hasActivation = false;
+    let hasSelection = false;
+    let hasDuplicateDsId = false;
+    allNodes.forEach((node) => {
+      const { dsId } = node;
+      if (!Array.isArray(nodesByDsId[dsId])) {
+        nodesByDsId[dsId] = [node];
+      } else {
+        nodesByDsId[dsId].push(node);
+        hasDuplicateDsId = true;
+        duplicatedIdsNodes[dsId] = nodesByDsId[dsId];
+      }
+      if (isActivableNode(node)) {
+        hasActivation = true;
+      }
+      if (isSelectionableNode(node)) {
+        hasSelection = true;
+      }
+    });
+    if (hasDuplicateDsId) {
+      console.log("duplicatedIdsNodes", duplicatedIdsNodes);
+      throw new Error(
+        `DSMenuButton:
+The following dsId are repeated:
+${Object.keys(duplicatedIdsNodes).join(
+          "\n"
+        )}
+
+The dsId must be unique.`
+      );
+    }
+    if (hasActivation && !onActivateItem) {
+      throw new Error(
+        "DSMenuButton:\nSome items are activable, but onActivateItem is not provided.\n\nYou must provide onActivateItem to handle activation."
+      );
+    }
+    if (hasSelection && (!onItemSelected || !selectedItems)) {
+      throw new Error(
+        "DSMenuButton:\nSome items are selectionable, but onItemSelected or selectedItems are not provided.\n\nYou must provide onItemSelected and selectedItems to handle selection."
+      );
+    }
+  }, [onActivateItem, onItemSelected, selectedItems, optionsTree]);
+};
+export {
+  useAdvancedValidation
+};
+//# sourceMappingURL=useAdvancedValidation.js.map

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

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useAdvancedValidation.ts"],
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import { useEffect } from 'react';\nimport { type DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport { type DSMenuBehaviouralContextProviderT } from '../react-desc-prop-types.js';\nimport { isActivableNode, isSelectionableNode } from '../../../utils/nodesTypeguardsAndGetters.js';\n\ntype UseAdvancedValidationConfigT = {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n};\nexport const useAdvancedValidation = ({ propsWithDefault }: UseAdvancedValidationConfigT): void => {\n  const { onActivateItem, onItemSelected, selectedItems, optionsTree } = propsWithDefault;\n  // =============================================================================\n  // SPECIAL VALIDATIONS\n  // =============================================================================\n  //   We iterate onces, validate everything in one go for performance reasons\n  // =============================================================================\n  // - No repeated dsId\n  //   (only validating focusableNodes may work, but to avoid complexity we validate the whole tree)\n  // - if any item is \"selectionable\", selection IoC props must be provided\n  // - if any item is \"activable\",    activation IoC props must be provided\n  // =============================================================================\n  // we want to validate only when dependencies change, should improve performance if app is using memoization\n  //  and be virtually a free overhead if the app is not using memoization\n  // =============================================================================\n  useEffect(() => {\n    const allNodes = optionsTree.flatten();\n    const nodesByDsId: { [key: DSMenuButtonT.MenuNode['dsId']]: DSMenuButtonT.MenuNode[] } = {};\n    const duplicatedIdsNodes: { [key: DSMenuButtonT.MenuNode['dsId']]: DSMenuButtonT.MenuNode[] } = {};\n    let hasActivation = false;\n    let hasSelection = false;\n    let hasDuplicateDsId = false;\n    allNodes.forEach((node) => {\n      const { dsId } = node;\n      if (!Array.isArray(nodesByDsId[dsId])) {\n        nodesByDsId[dsId] = [node];\n      } else {\n        nodesByDsId[dsId].push(node);\n        hasDuplicateDsId = true;\n        duplicatedIdsNodes[dsId] = nodesByDsId[dsId];\n      }\n\n      if (isActivableNode(node)) {\n        hasActivation = true;\n      }\n      if (isSelectionableNode(node)) {\n        hasSelection = true;\n      }\n    });\n    if (hasDuplicateDsId) {\n      // eslint-disable-next-line no-console\n      console.log('duplicatedIdsNodes', duplicatedIdsNodes);\n      throw new Error(\n        `DSMenuButton:\\nThe following dsId are repeated:\\n${Object.keys(duplicatedIdsNodes).join(\n          '\\n',\n        )}\\n\\nThe dsId must be unique.`,\n      );\n    }\n    if (hasActivation && !onActivateItem) {\n      throw new Error(\n        'DSMenuButton:\\nSome items are activable, but onActivateItem is not provided.\\n\\nYou must provide onActivateItem to handle activation.',\n      );\n    }\n    if (hasSelection && (!onItemSelected || !selectedItems)) {\n      throw new Error(\n        'DSMenuButton:\\nSome items are selectionable, but onItemSelected or selectedItems are not provided.\\n\\nYou must provide onItemSelected and selectedItems to handle selection.',\n      );\n    }\n  }, [onActivateItem, onItemSelected, selectedItems, optionsTree]);\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,SAAS,iBAAiB;AAG1B,SAAS,iBAAiB,2BAA2B;AAK9C,MAAM,wBAAwB,CAAC,EAAE,iBAAiB,MAA0C;AACjG,QAAM,EAAE,gBAAgB,gBAAgB,eAAe,YAAY,IAAI;AAcvE,YAAU,MAAM;AACd,UAAM,WAAW,YAAY,QAAQ;AACrC,UAAM,cAAmF,CAAC;AAC1F,UAAM,qBAA0F,CAAC;AACjG,QAAI,gBAAgB;AACpB,QAAI,eAAe;AACnB,QAAI,mBAAmB;AACvB,aAAS,QAAQ,CAAC,SAAS;AACzB,YAAM,EAAE,KAAK,IAAI;AACjB,UAAI,CAAC,MAAM,QAAQ,YAAY,IAAI,CAAC,GAAG;AACrC,oBAAY,IAAI,IAAI,CAAC,IAAI;AAAA,MAC3B,OAAO;AACL,oBAAY,IAAI,EAAE,KAAK,IAAI;AAC3B,2BAAmB;AACnB,2BAAmB,IAAI,IAAI,YAAY,IAAI;AAAA,MAC7C;AAEA,UAAI,gBAAgB,IAAI,GAAG;AACzB,wBAAgB;AAAA,MAClB;AACA,UAAI,oBAAoB,IAAI,GAAG;AAC7B,uBAAe;AAAA,MACjB;AAAA,IACF,CAAC;AACD,QAAI,kBAAkB;AAEpB,cAAQ,IAAI,sBAAsB,kBAAkB;AACpD,YAAM,IAAI;AAAA,QACR;AAAA;AAAA,EAAoD,OAAO,KAAK,kBAAkB,EAAE;AAAA,UAClF;AAAA,QACF,CAAC;AAAA;AAAA;AAAA,MACH;AAAA,IACF;AACA,QAAI,iBAAiB,CAAC,gBAAgB;AACpC,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,QAAI,iBAAiB,CAAC,kBAAkB,CAAC,gBAAgB;AACvD,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AAAA,EACF,GAAG,CAAC,gBAAgB,gBAAgB,eAAe,WAAW,CAAC;AACjE;",
+  "names": []
+}

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

@@ -10,6 +10,7 @@ import { useGlobalEvents } from "./useGlobalEvents.js";
 import { useMenuItemEventsHandlers } from "./useMenuItemEventsHandlers.js";
 import { useMenuOpenStatus } from "./useMenuOpenStatus.js";
 import { useValidateProps } from "./useValidateProps.js";
+import { useAdvancedValidation } from "./useAdvancedValidation.js";
 const useMenuBehaviouralContextProvider = (propsFromUser) => {
   const propsWithDefault = React2.useMemo(
     () => ({
@@ -19,6 +20,7 @@ const useMenuBehaviouralContextProvider = (propsFromUser) => {
     [propsFromUser]
   );
   useValidateProps(propsWithDefault, DSMenuBehaviouralContextProviderPropTypesSchema);
+  useAdvancedValidation({ propsWithDefault });
   const { onDisplayedSubmenuChange } = propsWithDefault;
   const instanceUid = React2.useMemo(() => `ds-menu-behavioural-context-provider-${uid(5)}`, []);
   const [openedSubItems, setOpenedSubItems] = React2.useState([]);

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

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../../../../scripts/build/transpile/react-shim.js", "../../../../../src/parts/DSMenuBehaviouralContextProvider/config/useMenuBehaviouralContextProvider.ts"],
-  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import React from 'react';\nimport { uid } from 'uid';\nimport type { DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport {\n  DSMenuBehaviouralContextProviderPropTypesSchema,\n  defaultProps,\n  type DSMenuBehaviouralContextProviderT,\n} from '../react-desc-prop-types.js';\nimport { useFocusTracker } from './useFocusTracker.js';\nimport { useGlobalEvents } from './useGlobalEvents.js';\nimport { useMenuItemEventsHandlers } from './useMenuItemEventsHandlers.js';\nimport { useMenuOpenStatus } from './useMenuOpenStatus.js';\nimport { useValidateProps } from './useValidateProps.js';\n\nexport interface MenuBehaviouralContextProviderCTX\n  extends ReturnType<typeof useFocusTracker>,\n    ReturnType<typeof useMenuOpenStatus> {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n  instanceUid: string;\n  menuItemEventsHandlers: ReturnType<typeof useMenuItemEventsHandlers>;\n  openedSubItems: DSMenuButtonT.WithSubmenuMenuNodes[];\n  handleChangeOpenedSubItems: Required<DSMenuButtonT.MenuBehaviouralLayerOptionalProps>['onDisplayedSubmenuChange'];\n  globalEventsHelpers: ReturnType<typeof useGlobalEvents>;\n}\n\nexport const useMenuBehaviouralContextProvider = (propsFromUser: DSMenuBehaviouralContextProviderT.Props) => {\n  // =============================================================================\n  // MERGE WITH DEFAULT AND VALIDATE PROPS\n  // =============================================================================\n  // the component deals with HTML DOM elements,\n  //  Deep compare of HTML DOM elements is pointless and extremely costly\n  //  for this specific case, we are better of not using `useMemoMergePropsWithDefault`\n  const propsWithDefault = React.useMemo(\n    () => ({\n      ...defaultProps,\n      ...propsFromUser,\n    }),\n    [propsFromUser],\n  ) as DSMenuBehaviouralContextProviderT.InternalProps;\n  useValidateProps(propsWithDefault, DSMenuBehaviouralContextProviderPropTypesSchema);\n  // =============================================================================\n  // XSTYLED PROPS\n  // =============================================================================\n  // NO XSTYLED PROPS\n  // this is 100% a pure logic context provider, it's not a visual component\n\n  // =============================================================================\n  // AD HOC PER COMPONENT LOGIC\n  // =============================================================================\n  // custom code goes here, this is an example\n  const { onDisplayedSubmenuChange } = propsWithDefault;\n  const instanceUid = React.useMemo(() => `ds-menu-behavioural-context-provider-${uid(5)}`, []);\n  const [openedSubItems, setOpenedSubItems] = React.useState<DSMenuButtonT.WithSubmenuMenuNodes[]>([]);\n\n  const handleChangeOpenedSubItems = React.useCallback<\n    Required<DSMenuButtonT.MenuBehaviouralLayerOptionalProps>['onDisplayedSubmenuChange']\n  >(\n    (newOpenedItems, metainfo) => {\n      setOpenedSubItems(newOpenedItems);\n      onDisplayedSubmenuChange?.(newOpenedItems, metainfo);\n    },\n    [onDisplayedSubmenuChange],\n  );\n\n  // =============================================================================\n  // HELPERS HOOKS CONFIGS\n  // =============================================================================\n  const focusTrackers = useFocusTracker();\n  const menuOpenStatus = useMenuOpenStatus({ propsWithDefault, focusTrackers });\n\n  // why item events handlers declared in the menu behaviour context provider and not in the menu item itself?\n  //  1 - each menu item depending on it's own type (single select, multiple select, with submenu) will have different behaviours\n  //      having each menu item to declare it's own events handlers would make the single event handler way easier to create per se\n  //      BUT we would lose the big picture of how the menu items are interacting with each other\n  //  2 - having each item to declare it's own event handler repeatdly is a waste of resources (even if it's a useless micro-optimization, it hurts me)\n  const menuItemEventsHandlers = useMenuItemEventsHandlers({\n    propsWithDefault,\n    focusTrackers,\n    menuOpenStatus,\n    handleChangeOpenedSubItems,\n  });\n\n  // handle \"onClickOutside\" + on window blur...\n  // the helpers contain a way to register the submenu refs/mainmenu refs, used in checking \"if click is outside\"\n  const globalEventsHelpers = useGlobalEvents({ menuOpenStatus, handleChangeOpenedSubItems, propsWithDefault });\n\n  return React.useMemo<MenuBehaviouralContextProviderCTX>(\n    () => ({\n      propsWithDefault,\n      instanceUid,\n      ...focusTrackers,\n      ...menuOpenStatus,\n      menuItemEventsHandlers,\n      openedSubItems,\n      handleChangeOpenedSubItems,\n      globalEventsHelpers,\n    }),\n    [\n      propsWithDefault,\n      instanceUid,\n      focusTrackers,\n      menuOpenStatus,\n      menuItemEventsHandlers,\n      openedSubItems,\n      handleChangeOpenedSubItems,\n      globalEventsHelpers,\n    ],\n  );\n};\n"],
-  "mappings": "AAAA,YAAY,WAAW;ACAvB,OAAOA,YAAW;AAClB,SAAS,WAAW;AAEpB;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AACP,SAAS,uBAAuB;AAChC,SAAS,uBAAuB;AAChC,SAAS,iCAAiC;AAC1C,SAAS,yBAAyB;AAClC,SAAS,wBAAwB;AAa1B,MAAM,oCAAoC,CAAC,kBAA2D;AAO3G,QAAM,mBAAmBA,OAAM;AAAA,IAC7B,OAAO;AAAA,MACL,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,IACA,CAAC,aAAa;AAAA,EAChB;AACA,mBAAiB,kBAAkB,+CAA+C;AAWlF,QAAM,EAAE,yBAAyB,IAAI;AACrC,QAAM,cAAcA,OAAM,QAAQ,MAAM,wCAAwC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AAC5F,QAAM,CAAC,gBAAgB,iBAAiB,IAAIA,OAAM,SAA+C,CAAC,CAAC;AAEnG,QAAM,6BAA6BA,OAAM;AAAA,IAGvC,CAAC,gBAAgB,aAAa;AAC5B,wBAAkB,cAAc;AAChC,iCAA2B,gBAAgB,QAAQ;AAAA,IACrD;AAAA,IACA,CAAC,wBAAwB;AAAA,EAC3B;AAKA,QAAM,gBAAgB,gBAAgB;AACtC,QAAM,iBAAiB,kBAAkB,EAAE,kBAAkB,cAAc,CAAC;AAO5E,QAAM,yBAAyB,0BAA0B;AAAA,IACvD;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAID,QAAM,sBAAsB,gBAAgB,EAAE,gBAAgB,4BAA4B,iBAAiB,CAAC;AAE5G,SAAOA,OAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,GAAG;AAAA,MACH,GAAG;AAAA,MACH;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;",
+  "sourcesContent": ["import * as React from 'react';\nexport { React };\n", "import React from 'react';\nimport { uid } from 'uid';\nimport type { DSMenuButtonT } from '../../../react-desc-prop-types.js';\nimport {\n  DSMenuBehaviouralContextProviderPropTypesSchema,\n  defaultProps,\n  type DSMenuBehaviouralContextProviderT,\n} from '../react-desc-prop-types.js';\nimport { useFocusTracker } from './useFocusTracker.js';\nimport { useGlobalEvents } from './useGlobalEvents.js';\nimport { useMenuItemEventsHandlers } from './useMenuItemEventsHandlers.js';\nimport { useMenuOpenStatus } from './useMenuOpenStatus.js';\nimport { useValidateProps } from './useValidateProps.js';\nimport { useAdvancedValidation } from './useAdvancedValidation.js';\n\nexport interface MenuBehaviouralContextProviderCTX\n  extends ReturnType<typeof useFocusTracker>,\n    ReturnType<typeof useMenuOpenStatus> {\n  propsWithDefault: DSMenuBehaviouralContextProviderT.InternalProps;\n  instanceUid: string;\n  menuItemEventsHandlers: ReturnType<typeof useMenuItemEventsHandlers>;\n  openedSubItems: DSMenuButtonT.WithSubmenuMenuNodes[];\n  handleChangeOpenedSubItems: Required<DSMenuButtonT.MenuBehaviouralLayerOptionalProps>['onDisplayedSubmenuChange'];\n  globalEventsHelpers: ReturnType<typeof useGlobalEvents>;\n}\n\nexport const useMenuBehaviouralContextProvider = (propsFromUser: DSMenuBehaviouralContextProviderT.Props) => {\n  // =============================================================================\n  // MERGE WITH DEFAULT AND VALIDATE PROPS\n  // =============================================================================\n  // the component deals with HTML DOM elements,\n  //  Deep compare of HTML DOM elements is pointless and extremely costly\n  //  for this specific case, we are better of not using `useMemoMergePropsWithDefault`\n  const propsWithDefault = React.useMemo(\n    () => ({\n      ...defaultProps,\n      ...propsFromUser,\n    }),\n    [propsFromUser],\n  ) as DSMenuBehaviouralContextProviderT.InternalProps;\n  useValidateProps(propsWithDefault, DSMenuBehaviouralContextProviderPropTypesSchema);\n\n  // =============================================================================\n  // SPECIAL VALIDATIONS\n  // =============================================================================\n  useAdvancedValidation({ propsWithDefault });\n\n  // =============================================================================\n  // XSTYLED PROPS\n  // =============================================================================\n  // NO XSTYLED PROPS\n  // this is 100% a pure logic context provider, it's not a visual component\n\n  // =============================================================================\n  // AD HOC PER COMPONENT LOGIC\n  // =============================================================================\n  // custom code goes here, this is an example\n  const { onDisplayedSubmenuChange } = propsWithDefault;\n  const instanceUid = React.useMemo(() => `ds-menu-behavioural-context-provider-${uid(5)}`, []);\n  const [openedSubItems, setOpenedSubItems] = React.useState<DSMenuButtonT.WithSubmenuMenuNodes[]>([]);\n\n  const handleChangeOpenedSubItems = React.useCallback<\n    Required<DSMenuButtonT.MenuBehaviouralLayerOptionalProps>['onDisplayedSubmenuChange']\n  >(\n    (newOpenedItems, metainfo) => {\n      setOpenedSubItems(newOpenedItems);\n      onDisplayedSubmenuChange?.(newOpenedItems, metainfo);\n    },\n    [onDisplayedSubmenuChange],\n  );\n\n  // =============================================================================\n  // HELPERS HOOKS CONFIGS\n  // =============================================================================\n  const focusTrackers = useFocusTracker();\n  const menuOpenStatus = useMenuOpenStatus({ propsWithDefault, focusTrackers });\n\n  // why item events handlers declared in the menu behaviour context provider and not in the menu item itself?\n  //  1 - each menu item depending on it's own type (single select, multiple select, with submenu) will have different behaviours\n  //      having each menu item to declare it's own events handlers would make the single event handler way easier to create per se\n  //      BUT we would lose the big picture of how the menu items are interacting with each other\n  //  2 - having each item to declare it's own event handler repeatdly is a waste of resources (even if it's a useless micro-optimization, it hurts me)\n  const menuItemEventsHandlers = useMenuItemEventsHandlers({\n    propsWithDefault,\n    focusTrackers,\n    menuOpenStatus,\n    handleChangeOpenedSubItems,\n  });\n\n  // handle \"onClickOutside\" + on window blur...\n  // the helpers contain a way to register the submenu refs/mainmenu refs, used in checking \"if click is outside\"\n  const globalEventsHelpers = useGlobalEvents({ menuOpenStatus, handleChangeOpenedSubItems, propsWithDefault });\n\n  return React.useMemo<MenuBehaviouralContextProviderCTX>(\n    () => ({\n      propsWithDefault,\n      instanceUid,\n      ...focusTrackers,\n      ...menuOpenStatus,\n      menuItemEventsHandlers,\n      openedSubItems,\n      handleChangeOpenedSubItems,\n      globalEventsHelpers,\n    }),\n    [\n      propsWithDefault,\n      instanceUid,\n      focusTrackers,\n      menuOpenStatus,\n      menuItemEventsHandlers,\n      openedSubItems,\n      handleChangeOpenedSubItems,\n      globalEventsHelpers,\n    ],\n  );\n};\n"],
+  "mappings": "AAAA,YAAY,WAAW;ACAvB,OAAOA,YAAW;AAClB,SAAS,WAAW;AAEpB;AAAA,EACE;AAAA,EACA;AAAA,OAEK;AACP,SAAS,uBAAuB;AAChC,SAAS,uBAAuB;AAChC,SAAS,iCAAiC;AAC1C,SAAS,yBAAyB;AAClC,SAAS,wBAAwB;AACjC,SAAS,6BAA6B;AAa/B,MAAM,oCAAoC,CAAC,kBAA2D;AAO3G,QAAM,mBAAmBA,OAAM;AAAA,IAC7B,OAAO;AAAA,MACL,GAAG;AAAA,MACH,GAAG;AAAA,IACL;AAAA,IACA,CAAC,aAAa;AAAA,EAChB;AACA,mBAAiB,kBAAkB,+CAA+C;AAKlF,wBAAsB,EAAE,iBAAiB,CAAC;AAY1C,QAAM,EAAE,yBAAyB,IAAI;AACrC,QAAM,cAAcA,OAAM,QAAQ,MAAM,wCAAwC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;AAC5F,QAAM,CAAC,gBAAgB,iBAAiB,IAAIA,OAAM,SAA+C,CAAC,CAAC;AAEnG,QAAM,6BAA6BA,OAAM;AAAA,IAGvC,CAAC,gBAAgB,aAAa;AAC5B,wBAAkB,cAAc;AAChC,iCAA2B,gBAAgB,QAAQ;AAAA,IACrD;AAAA,IACA,CAAC,wBAAwB;AAAA,EAC3B;AAKA,QAAM,gBAAgB,gBAAgB;AACtC,QAAM,iBAAiB,kBAAkB,EAAE,kBAAkB,cAAc,CAAC;AAO5E,QAAM,yBAAyB,0BAA0B;AAAA,IACvD;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,CAAC;AAID,QAAM,sBAAsB,gBAAgB,EAAE,gBAAgB,4BAA4B,iBAAiB,CAAC;AAE5G,SAAOA,OAAM;AAAA,IACX,OAAO;AAAA,MACL;AAAA,MACA;AAAA,MACA,GAAG;AAAA,MACH,GAAG;AAAA,MACH;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,IACA;AAAA,MACE;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,MACA;AAAA,IACF;AAAA,EACF;AACF;",
   "names": ["React"]
 }

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

@@ -110,7 +110,7 @@ const useMenuItemEventsHandlers = ({
         onItemSelected(newSelection, { itemNode: pseudoFocusedItemNode, event });
         return;
       }
-      onActivateItem(pseudoFocusedItemNode, { itemNode: pseudoFocusedItemNode, event });
+      onActivateItem?.(pseudoFocusedItemNode, { itemNode: pseudoFocusedItemNode, event });
       const metainfo = { itemNode: pseudoFocusedItemNode, event };
       const newOpenedItems = [];
       handleChangeOpenedSubItems(newOpenedItems, metainfo);
@@ -221,25 +221,6 @@ const useMenuItemEventsHandlers = ({
       onOpinionatedClose
     ]
   );
-  const handleFocusableMenuItemOnMouseEnter = React2.useCallback(
-    (itemNode, event) => {
-      if (!isFocusableNode(itemNode)) {
-        console.log("handleFocusableMenuItemOnMouseEnter > itemNode:", itemNode);
-        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;
-      }
-      trackFocusNode(itemNode);
-      if (!isWithSubmenuNode(itemNode)) {
-        const subMenuNodesPath = getSubMenusPath(itemNode);
-        const metainfo = { itemNode, event };
-        const newOpenedItems = [...subMenuNodesPath];
-        handleChangeOpenedSubItems(newOpenedItems, metainfo);
-        return;
-      }
-      if (itemNode.plainItem.disabled) return;
-      openSubmenu({ itemNode, event });
-    },
-    [handleChangeOpenedSubItems, openSubmenu, trackFocusNode]
-  );
   const handleFocusableMenuItemClick = React2.useCallback(
     (event) => {
       const pseudoFocusedItemNode = focusedElementItemNode.current;
@@ -263,13 +244,59 @@ const useMenuItemEventsHandlers = ({
     },
     [focusedElementItemNode, handleMenuItemSpaceKeyDown, handleChangeOpenedSubItems]
   );
+  const opinionatedFocusBehaviour = React2.useCallback(
+    // we currently know only one "event" that can trigger this opinionated behaviour
+    //   - focus      => React.FocusEvent <-- triggered by ATs "focus mode" or "virtual cursor" navigation
+    //      NOTE:
+    //           mouseEnter => React.MouseEvent
+    //      still ends up calling this function, but as a side effect of mouse-enter focusing the item, not as the main event
+    (itemNode, event) => {
+      if (!isFocusableNode(itemNode)) {
+        console.log("handleFocusableMenuItemOnMouseEnter > itemNode:", itemNode);
+        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;
+      }
+      trackFocusNode(itemNode);
+      if (!isWithSubmenuNode(itemNode)) {
+        const subMenuNodesPath = getSubMenusPath(itemNode);
+        const metainfo = { itemNode, event };
+        const newOpenedItems = [...subMenuNodesPath];
+        handleChangeOpenedSubItems(newOpenedItems, metainfo);
+        return;
+      }
+      if (itemNode.plainItem.disabled) return;
+      openSubmenu({ itemNode, event });
+    },
+    [handleChangeOpenedSubItems, openSubmenu, trackFocusNode]
+  );
+  const handleFocusableMenuItemOnMouseEnter = React2.useCallback(
+    (itemNode) => {
+      if (!isFocusableNode(itemNode)) {
+        console.log("handleFocusableMenuItemOnMouseEnter > itemNode:", itemNode);
+        throw FORBIDDEN_BEHAVIOURS.TRYING_TO_FOCUS_NON_FOCUSABLE_NODE;
+      }
+      trackFocusNode(itemNode);
+    },
+    [trackFocusNode]
+  );
+  const handleFocusableMenuItemNativeFocusEvent = React2.useCallback(
+    (itemNode, event) => {
+      opinionatedFocusBehaviour(itemNode, event);
+    },
+    [opinionatedFocusBehaviour]
+  );
   return React2.useMemo(
     () => ({
       handleFocusableMenuItemKeyDown,
       handleFocusableMenuItemClick,
-      handleFocusableMenuItemOnMouseEnter
+      handleFocusableMenuItemOnMouseEnter,
+      handleFocusableMenuItemNativeFocusEvent
     }),
-    [handleFocusableMenuItemClick, handleFocusableMenuItemKeyDown, handleFocusableMenuItemOnMouseEnter]
+    [
+      handleFocusableMenuItemClick,
+      handleFocusableMenuItemKeyDown,
+      handleFocusableMenuItemNativeFocusEvent,
+      handleFocusableMenuItemOnMouseEnter
+    ]
   );
 };
 export {