@momentum-design/components 0.134.20 → 0.134.22

package/dist/components/menuitemradio/menuitemradio.component.d.ts

@@ -3,38 +3,25 @@ import MenuItem from '../menuitem/menuitem.component';
 import { Indicator } from './menuitemradio.types';
 declare const MenuItemRadio_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ControlTypeMixin").ControlTypeMixinInterface> & typeof MenuItem;
 /**
- * A menuitemradio component is a checkable menuitem that is used in a menu.
- * A menuitemradio should be checked only one at a time. <br/>
- * There should be no focusable descendants inside this menuitemradio component.
- *
- * The `checked` menuitemradio attribute is used to indicate that the menuitemradio is checked or not.
- *
- * Menu item radio has `name` and `value` attribute that can be used to identify the menu item when it is selected.
- *
- * If you want more than one item in a group to be checked, consider using menuitemcheckbox component.
- *
- * The `indicator` attribute is used to differentiate between <b>radio</b>, <b>checkmark</b> and <b>none</b>.
- * By default, the `indicator` is set to <b>radio</b>.<br/>
- *
- * The checkbox will always be positioned on the leading side of the menuitem label and
- * the checkmark will always be positioned on the trailing side.
- *
- * The radio will have the possible states of `true` or `false`.
- * If the indicator is set to <b>checkmark</b> and if the `checked` attribute is set to `true`,
- * then the checkmark will be displayed. if not, then no indicator will be displayed.
- *
- * The third options for the `indicator` is <b>none</b>, which will not display any indicator at all.
- * It is intended to be used for customised menu items where the indicator is implemented differently.
- * For example, you can use a custom icon or a different visual element to indicate the state of the menu item.
- * Make sure the new indicator is accessible.
- *
+ * `mdc-menuitemradio` is a checkable menu item used for single-selection within a group of related items. When checked, the component automatically un-checks every other `mdc-menuitemradio` that shares the same `name` inside the closest `mdc-menusection` or `mdc-menupopover`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-menuitemradio` for mutually exclusive options inside a menu (only one item in the group may be selected at a time).
+ * - Group related items by giving them the same `name` and placing them inside the same `mdc-menusection` or `mdc-menupopover`.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-menuitemcheckbox` when more than one item in the group can be checked simultaneously.
+ * - Use `mdc-menuitem` for actions that do not have a selected state.
+ * 
+ * @tagname mdc-menuitemradio
+ * 
  * @dependency mdc-icon
  * @dependency mdc-staticradio
  * @dependency mdc-text
  * @dependency mdc-tooltip
- *
- * @tagname mdc-menuitemradio
- *
+ * 
  * @slot leading-controls - slot for menu item radio controls to appear of leading end.
  * @slot leading-text-primary-label - slot for menu item radio primary label.
  * @slot leading-text-secondary-label - slot for menu item radio secondary label.
@@ -42,13 +29,13 @@ declare const MenuItemRadio_base: import("../../utils/mixins/index.types").Const
  * @slot trailing-text-side-header - slot for menu item radio side header text.
  * @slot trailing-text-subline - slot for menu item radio subline text.
  * @slot trailing-controls - slot for menu item radio controls to appear of trailing end.
- *
+ * 
  * @event change - (React: onChange) This event is dispatched when the menuitemradio changes.
  * @event click - (React: onClick) This event is dispatched when the menuitemradio is clicked.
  * @event focus - (React: onFocus) This event is dispatched when the menuitemradio receives focus.
- *
+ * 
  * @cssproperty --mdc-listitem-padding-left-and-right - Controls the padding on the left and right of the menuitemradio.
- *
+ * 
  * @csspart checkmark-icon - Allows customization of the checkmark icon.
  * @csspart leading - Allows customization of the leading part.
  * @csspart leading-arrow - Allows customization of leading arrow icon.

package/dist/components/menuitemradio/menuitemradio.component.js

@@ -19,38 +19,13 @@ import { ControlTypeMixin } from '../../utils/mixins/ControlTypeMixin';
 import { INDICATOR, DEFAULTS } from './menuitemradio.constants';
 import styles from './menuitemradio.styles';
 /**
- * A menuitemradio component is a checkable menuitem that is used in a menu.
- * A menuitemradio should be checked only one at a time. <br/>
- * There should be no focusable descendants inside this menuitemradio component.
- *
- * The `checked` menuitemradio attribute is used to indicate that the menuitemradio is checked or not.
- *
- * Menu item radio has `name` and `value` attribute that can be used to identify the menu item when it is selected.
- *
- * If you want more than one item in a group to be checked, consider using menuitemcheckbox component.
- *
- * The `indicator` attribute is used to differentiate between <b>radio</b>, <b>checkmark</b> and <b>none</b>.
- * By default, the `indicator` is set to <b>radio</b>.<br/>
- *
- * The checkbox will always be positioned on the leading side of the menuitem label and
- * the checkmark will always be positioned on the trailing side.
- *
- * The radio will have the possible states of `true` or `false`.
- * If the indicator is set to <b>checkmark</b> and if the `checked` attribute is set to `true`,
- * then the checkmark will be displayed. if not, then no indicator will be displayed.
- *
- * The third options for the `indicator` is <b>none</b>, which will not display any indicator at all.
- * It is intended to be used for customised menu items where the indicator is implemented differently.
- * For example, you can use a custom icon or a different visual element to indicate the state of the menu item.
- * Make sure the new indicator is accessible.
+ * @tagname mdc-menuitemradio
  *
  * @dependency mdc-icon
  * @dependency mdc-staticradio
  * @dependency mdc-text
  * @dependency mdc-tooltip
  *
- * @tagname mdc-menuitemradio
- *
  * @slot leading-controls - slot for menu item radio controls to appear of leading end.
  * @slot leading-text-primary-label - slot for menu item radio primary label.
  * @slot leading-text-secondary-label - slot for menu item radio secondary label.

package/dist/components/menupopover/menupopover.component.d.ts

@@ -2,49 +2,27 @@ import { CSSResult, PropertyValues } from 'lit';
 import Popover from '../popover/popover.component';
 import type { PopoverPlacement } from '../popover/popover.types';
 /**
- * A popover menu component that displays a list of menu items in a floating container.
- * It's designed to work in conjunction with `mdc-menubar` and `mdc-menuitem` to create
- * accessible, nested menu structures with the following features:
- * - Appears adjacent to the triggering menu item
- * - Supports keyboard navigation (arrow keys, Home, End)
- * - Manages focus trapping when open
- * - Closes on Escape key or outside click
- * - Supports both mouse and keyboard interactions
- * - Automatically handles ARIA attributes for accessibility
- *
- * The component extends `mdc-popover` and adds menu-specific behaviors and styling.
- * When nested within another `mdc-menupopover`, it automatically adjusts its behavior
- * to work as a submenu (right-aligned, shows on hover).
- *
- * The orientation of the menu popover is always set to `vertical`.
- *
- * Submenu opens when:
- * - Clicked on a menu item with a submenu
- * - Enter or Space key pressed on a menu item with a submenu
- *
- * Menu closes completely (with all sub menus) when:
- * - A menu item is clicked that does not have a submenu
- * - Enter key pressed on a menu item (not a submenu trigger), menu item radio or menu item checkbox
- * - Click outside the menu popover (on the backdrop)
- *
- * Close submenus when:
- * - Esc key pressed, only the current submenu closed
- * - Arrow Left key pressed, only the current submenu closed
- * - Open another submenu with Click, Enter or Space key,
- *   closes recursively all submenus until the selected item's submenu
- *
- * Menu does not close when:
- * - Space key pressed on a menu item radio or menu item checkbox
- *
+ * `mdc-menupopover` is a floating overlay that hosts menu items (`mdc-menuitem`, `mdc-menuitemcheckbox`, `mdc-menuitemradio`) optionally grouped in `mdc-menusection`. It is anchored to a trigger element via the `triggerid` attribute and provides keyboard navigation, focus trapping, dismissal, and automatic submenu behaviour when nested inside another `mdc-menupopover` or used with `mdc-menubar`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-menupopover` to surface a menu of actions from a trigger button or menu item.
+ * - Use it as a submenu by nesting it under another `mdc-menupopover` or by anchoring it to an `mdc-menuitem` inside an `mdc-menubar`.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-menupopover` for generic non-menu overlays — use `mdc-popover` for those.
+ * - Do not use it to host a single non-menu item or arbitrary form controls; the contents should be menu items.
+ * 
  * @tagname mdc-menupopover
- *
+ * 
  * @slot - Default slot for the menu popover content
- *
+ * 
  * @event change - (React: onChange) This event is dispatched when a `menuitemcheckbox`, or `menuitemradio` changes.
  * @event action - (React: onAction) This event is dispatched when a menuItem selected and the menu closes.
- *
+ * 
  * @slot default - Contains the menu items to be displayed in the popover
- *
+ * 
  * @csspart popover-close - The close button of the menupopover.
  * @csspart popover-content - The content of the menupopover.
  * @csspart popover-hover-bridge - The hover bridge of the menupopover.
@@ -124,7 +102,7 @@ declare class MenuPopover extends Popover {
     onOutsidePopoverClick: (event: MouseEvent) => void;
     /**
      * Toggles the visibility of the popover.
-     * This method checks if the trigger element has the `soft-disabled` attribute.
+     * This method checks if the trigger element has the `disabled` or `soft-disabled` attribute.
      * If it does, the popover will not be toggled.
      * If the popover is currently visible, it hides the popover; otherwise, it shows the popover.
      * @returns - This method does not return anything.

package/dist/components/menupopover/menupopover.component.js

@@ -21,40 +21,6 @@ import { DEFAULTS, TAG_NAME as MENU_POPOVER } from './menupopover.constants';
 import styles from './menupopover.styles';
 import { isValidMenuItem, isValidMenuPopover } from './menupopover.utils';
 /**
- * A popover menu component that displays a list of menu items in a floating container.
- * It's designed to work in conjunction with `mdc-menubar` and `mdc-menuitem` to create
- * accessible, nested menu structures with the following features:
- * - Appears adjacent to the triggering menu item
- * - Supports keyboard navigation (arrow keys, Home, End)
- * - Manages focus trapping when open
- * - Closes on Escape key or outside click
- * - Supports both mouse and keyboard interactions
- * - Automatically handles ARIA attributes for accessibility
- *
- * The component extends `mdc-popover` and adds menu-specific behaviors and styling.
- * When nested within another `mdc-menupopover`, it automatically adjusts its behavior
- * to work as a submenu (right-aligned, shows on hover).
- *
- * The orientation of the menu popover is always set to `vertical`.
- *
- * Submenu opens when:
- * - Clicked on a menu item with a submenu
- * - Enter or Space key pressed on a menu item with a submenu
- *
- * Menu closes completely (with all sub menus) when:
- * - A menu item is clicked that does not have a submenu
- * - Enter key pressed on a menu item (not a submenu trigger), menu item radio or menu item checkbox
- * - Click outside the menu popover (on the backdrop)
- *
- * Close submenus when:
- * - Esc key pressed, only the current submenu closed
- * - Arrow Left key pressed, only the current submenu closed
- * - Open another submenu with Click, Enter or Space key,
- *   closes recursively all submenus until the selected item's submenu
- *
- * Menu does not close when:
- * - Space key pressed on a menu item radio or menu item checkbox
- *
  * @tagname mdc-menupopover
  *
  * @slot - Default slot for the menu popover content
@@ -112,14 +78,14 @@ class MenuPopover extends Popover {
         };
         /**
          * Toggles the visibility of the popover.
-         * This method checks if the trigger element has the `soft-disabled` attribute.
+         * This method checks if the trigger element has the `disabled` or `soft-disabled` attribute.
          * If it does, the popover will not be toggled.
          * If the popover is currently visible, it hides the popover; otherwise, it shows the popover.
          * @returns - This method does not return anything.
          */
         this.togglePopoverVisible = (event) => {
-            var _a;
-            if ((_a = this.triggerElement) === null || _a === void 0 ? void 0 : _a.hasAttribute('soft-disabled'))
+            var _a, _b;
+            if (((_a = this.triggerElement) === null || _a === void 0 ? void 0 : _a.hasAttribute('disabled')) || ((_b = this.triggerElement) === null || _b === void 0 ? void 0 : _b.hasAttribute('soft-disabled')))
                 return;
             // Handle mouse click in the parent menupopover to hide open sibling submenus
             if (event.composedPath().find(el => el.tagName === this.tagName) === this) {
@@ -213,7 +179,7 @@ class MenuPopover extends Popover {
                 case ACTIONS.RIGHT: {
                     // If there is a submenu, open it.
                     const subMenu = this.getSubMenuPopoverOfTarget(target);
-                    if (subMenu) {
+                    if (subMenu && !target.hasAttribute('soft-disabled')) {
                         subMenu.show();
                         isKeyHandled = true;
                     }

package/dist/components/menusection/menusection.component.d.ts

@@ -2,26 +2,30 @@ import { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
 import type { IconNames } from '../icon/icon.types';
 /**
- * `mdc-menusection` is a container element used to group a set of menu items.
- *
- * This component supports a mix of `menuitem`, `menuitemcheckbox`, and `menuitemradio` components. MenuSection can not be nested.
- *
- * - If multiple `menuitemradio` components are slotted into the section, the group enforces a single-selection rule:
- *   only one radio item can be selected at a time.
- * - If `menuitemcheckbox` components are included, their checked state can be toggled independently.
- *
+ * `mdc-menusection` groups a set of menu items (`mdc-menuitem`, `mdc-menuitemcheckbox`, `mdc-menuitemradio`) under an optional visible header, optional prefix icon, and optional divider. It also enforces single-selection semantics across any `mdc-menuitemradio` children that share a `name`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-menusection` to label and visually separate related entries inside an `mdc-menupopover` or `mdc-menubar`.
+ * - Use it to scope a `mdc-menuitemradio` group: the section bounds the single-selection rule applied to radios with the same `name`.
+ * 
+ * **When not to use**
+ * 
+ * - Do not nest `mdc-menusection` inside another `mdc-menusection`; sections are flat.
+ * - Do not use it outside of a menu context (`mdc-menupopover`, `mdc-menubar`, `mdc-sidenavigation`).
+ * 
  * @tagname mdc-menusection
- *
+ * 
  * @slot - Default slot for inserting `menuitem`, `menuitemcheckbox`, or `menuitemradio`
- *
+ * 
  * @event change - (React: onChange) This event is dispatched when a `menuitemcheckbox`, or `menuitemradio` changes.
  * @event action - (React: onAction) This event is dispatched when a `menuitem` selected.
- *
+ * 
  * @csspart header - The header of the menusection.
  * @csspart align-header - The header of the menusection when it is aligned to the start.
  * @csspart container - The container of the menusection.
  * @csspart divider - The divider of the menusection.
- *
+ * 
  * @cssproperty --mdc-menusection-divider-margin-block - Sets the margin block of the divider.
  * @cssproperty --mdc-menusection-gap - Sets the gap between items in the menusection.
  * @cssproperty --mdc-menusection-divider-width - Sets the width of the divider.

package/dist/components/menusection/menusection.component.js

@@ -17,14 +17,6 @@ import SideNavigation from '../sidenavigation/sidenavigation.component';
 import styles from './menusection.styles';
 import { DEFAULTS } from './menusection.constants';
 /**
- * `mdc-menusection` is a container element used to group a set of menu items.
- *
- * This component supports a mix of `menuitem`, `menuitemcheckbox`, and `menuitemradio` components. MenuSection can not be nested.
- *
- * - If multiple `menuitemradio` components are slotted into the section, the group enforces a single-selection rule:
- *   only one radio item can be selected at a time.
- * - If `menuitemcheckbox` components are included, their checked state can be toggled independently.
- *
  * @tagname mdc-menusection
  *
  * @slot - Default slot for inserting `menuitem`, `menuitemcheckbox`, or `menuitemradio`

package/dist/components/navmenuitem/navmenuitem.component.d.ts

@@ -5,30 +5,31 @@ import type { PopoverPlacement } from '../popover/popover.types';
 import type { TooltipType } from '../tooltip/tooltip.types';
 import type { BadgeType } from './navmenuitem.types';
 /**
- * `mdc-navmenuitem` is a menuitem styled to work as a navigation tab.
- * It supports a leading icon, optional badge and dynamic text rendering.
- *
- * The navmenuitem can be in an active or inactive state, indicating whether it is currently selected.
- *
- * Note: `mdc-navmenuitem` is intended to be used inside `mdc-menubar` as part of the sideNavigation
- * component. Its structure, spacing, and interactions are designed to align with
- * the visual and functional requirements of side navigation layouts.
- *
- * By providing the tooltip-text attribute, a tooltip will be displayed on hover of the navmenuitem. This tooltip is useful when an active navmenuitem is present within a submenu of the sidenavigation component.
- *
+ * `mdc-navmenuitem` is a `menuitem`-role component styled as a navigation tab, supporting a leading icon, optional badge, and dynamic text rendering. It can operate as a simple item, as a parent with a flyout submenu (`mdc-menupopover`), or as a parent with an inline dropdown submenu, and a tooltip can be attached for collapsed states or when a nested child is active.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-navmenuitem` for primary navigation entries inside `mdc-sidenavigation` (or an `mdc-menubar` used as a side navigation tree).
+ * - Use the active/inactive state to reflect which destination corresponds to the current route or view.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-navmenuitem` for action menu items inside `mdc-menupopover`; use `mdc-menuitem`, `mdc-menuitemcheckbox`, or `mdc-menuitemradio` there.
+ * - Do not use it as a stand-alone link or button outside a navigation context — use `mdc-link` or `mdc-button` instead.
+ * 
  * @tagname mdc-navmenuitem
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-badge
  * @dependency mdc-tooltip
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the navmenuitem is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the navmenuitem.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the navmenuitem.
  * @event focus - (React: onFocus) This event is dispatched when the navmenuitem receives focus.
  * @event activechange - (React: onActiveChange) Dispatched when the active state of the navmenuitem changes.
- *
+ * 
  * @cssproperty --mdc-navmenuitem-in-sidenav-expanded-width - Width of the navmenuitem when expanded.
  * @cssproperty --mdc-navmenuitem-in-sidenav-expanded-margin-left - Left margin of the navmenuitem, when expanded.
  * @cssproperty --mdc-navmenuitem-in-sidenav-expanded-margin-right - Right margin of the navmenuitem, when expanded.
@@ -36,6 +37,7 @@ import type { BadgeType } from './navmenuitem.types';
  * @cssproperty --mdc-navmenuitem-in-sidenav-collapsed-margin-left - Left margin of the navmenuitem, when collapsed.
  * @cssproperty --mdc-navmenuitem-in-sidenav-collapsed-margin-right - Right margin of the navmenuitem, when collapsed.
  * @cssproperty --mdc-navmenuitem-color - Text color of the navmenuitem in its normal state.
+ * @cssproperty --mdc-navmenuitem-notch-color - Notch color of the navmenuitem (if applicable) when active.
  * @cssproperty --mdc-navmenuitem-disabled-color - Text color of the navmenuitem when disabled.
  * @cssproperty --mdc-navmenuitem-rest-active-background-color - Background color of the active nav item in its rest state.
  * @cssproperty --mdc-navmenuitem-hover-background-color - Background color of the navmenuitem when hovered.
@@ -44,12 +46,13 @@ import type { BadgeType } from './navmenuitem.types';
  * @cssproperty --mdc-navmenuitem-pressed-active-background-color - Background color of the active navmenuitem when pressed.
  * @cssproperty --mdc-navmenuitem-disabled-background-color - Background color of the navmenuitem when disabled.
  * @cssproperty --mdc-navmenuitem-disabled-active-background-color - Background color of the active navmenuitem when disabled.
- *
+ * 
  * @csspart arrow - The arrow of the navmenuitem.
  * @csspart badge - The badge of the navmenuitem.
  * @csspart icon-container - The container of the icon.
  * @csspart text-container - The container of the text.
- * @csspart trailing-arrow - The trailing arrow of the navmenuitem.
+ * @csspart trailing-arrow - The trailing arrow of the navmenuitem when it has a flyout menu.
+ * @csspart trailing-arrow-dropdown - The trailing arrow of the navmenuitem when it has a dropdown menu.
  */
 declare class NavMenuItem extends MenuItem {
     /**
@@ -166,6 +169,11 @@ declare class NavMenuItem extends MenuItem {
      * @internal
      */
     hasActiveChild: boolean;
+    /**
+     * Tracks whether the dropdown submenu controlled by this navmenuitem is currently open.
+     * @internal
+     */
+    private dropdownOpen;
     /**
      * @internal
      */
@@ -183,6 +191,11 @@ declare class NavMenuItem extends MenuItem {
      * This method assumes nesting implies deeper levels of nav hierarchy.
      */
     private isNested;
+    /**
+     * Check whether the navmenuitem is inside a dropdown container (div[data-trigger]).
+     * @internal
+     */
+    private isInsideDropdownContainer;
     /**
      * Dispatch the activechange event.
      * @internal
@@ -190,6 +203,24 @@ declare class NavMenuItem extends MenuItem {
      */
     private emitNavMenuItemActiveChange;
     private handleClickEvent;
+    /**
+     * Toggles the visibility of the dropdown container associated with this navmenuitem.
+     * @internal
+     */
+    private toggleDropdown;
+    /**
+     * Opens the dropdown if it is closed.
+     */
+    openDropdown(): void;
+    /**
+     * Closes the dropdown if it is open.
+     */
+    closeDropdown(): void;
+    /**
+     * Returns the sibling div[data-trigger] element associated with this navmenuitem.
+     * @internal
+     */
+    private getDropdownContainer;
     private getFilledIconName;
     private renderBadge;
     render(): TemplateResult<1>;