@momentum-design/components 0.134.20 → 0.134.22

package/dist/components/navmenuitem/navmenuitem.component.js

@@ -13,25 +13,14 @@ import { ifDefined } from 'lit/directives/if-defined.js';
 import { v4 } from 'uuid';
 import { TYPE, VALID_TEXT_TAGS } from '../text/text.constants';
 import { TAG_NAME as MENUPOPOVER_TAGNAME } from '../menupopover/menupopover.constants';
+import { TAG_NAME as TOOLTIP_TAG_NAME } from '../tooltip/tooltip.constants';
 import MenuItem from '../menuitem/menuitem.component';
 import providerUtils from '../../utils/provider';
 import SideNavigation from '../sidenavigation/sidenavigation.component';
-import { TAG_NAME as TOOLTIP_TAG_NAME } from '../tooltip/tooltip.constants';
 import { getIconNameWithoutStyle } from '../button/button.utils';
-import { ALLOWED_BADGE_TYPES, DEFAULTS, ICON_NAME } from './navmenuitem.constants';
+import { ALLOWED_BADGE_TYPES, DEFAULTS, ICON_NAME, TAG_NAME as NAVMENUITEM_TAGNAME } from './navmenuitem.constants';
 import styles from './navmenuitem.styles';
 /**
- * `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.
- *
  * @tagname mdc-navmenuitem
  *
  * @dependency mdc-icon
@@ -52,6 +41,7 @@ import styles from './navmenuitem.styles';
  * @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.
@@ -65,7 +55,8 @@ import styles from './navmenuitem.styles';
  * @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.
  */
 class NavMenuItem extends MenuItem {
     constructor() {
@@ -107,6 +98,11 @@ class NavMenuItem extends MenuItem {
          * @internal
          */
         this.hasActiveChild = false;
+        /**
+         * Tracks whether the dropdown submenu controlled by this navmenuitem is currently open.
+         * @internal
+         */
+        this.dropdownOpen = false;
         /**
          * @internal
          */
@@ -133,6 +129,8 @@ class NavMenuItem extends MenuItem {
         }
         // Set in-menupopover attribute if nested
         this.toggleAttribute('in-menupopover', this.isNested());
+        // Set in-dropdown-container attribute if inside a dropdown div
+        this.toggleAttribute('in-dropdown-container', this.isInsideDropdownContainer());
     }
     disconnectedCallback() {
         super.disconnectedCallback();
@@ -150,7 +148,8 @@ class NavMenuItem extends MenuItem {
         super.updated(changedProperties);
         if (changedProperties.has('tooltipText') ||
             changedProperties.has('showLabel') ||
-            changedProperties.has('hasActiveChild')) {
+            changedProperties.has('hasActiveChild') ||
+            changedProperties.has('dropdownOpen')) {
             this.renderDynamicTooltip();
         }
         if (changedProperties.has('showLabel')) {
@@ -163,11 +162,36 @@ class NavMenuItem extends MenuItem {
         if (!context)
             return;
         // Determine expansion state
-        this.showLabel = this.isNested() ? true : context.expanded;
+        this.showLabel = this.isNested() || this.isInsideDropdownContainer() ? true : context.expanded;
+        // When sidenavigation collapses, close any open dropdown
+        if (!context.expanded && this.dropdownOpen) {
+            this.closeDropdown();
+        }
+        // When dropdown submenu type is turned off, close any open dropdown
+        if (!context.isDropdownSubmenuType && this.dropdownOpen) {
+            this.closeDropdown();
+        }
+        // In dropdown mode, manage parent active styling based on expanded state:
+        // Expanded + dropdown open: only the child should appear active, not the parent.
+        // Expanded + dropdown closed: parent should appear active when it has an active child.
+        // Collapsed (icon-only): parent should appear active when it has an active child.
+        if (context.isDropdownSubmenuType && this.hasActiveChild && context.isDropDownParent(this)) {
+            if (context.expanded && this.dropdownOpen) {
+                this.removeAttribute('active');
+                this.active = false;
+            }
+            else {
+                this.setAttribute('active', '');
+                this.active = true;
+            }
+        }
     }
     renderDynamicTooltip() {
         var _a;
         this.removeTooltip();
+        if (this.disabled || this.dropdownOpen) {
+            return;
+        }
         if (this.hasActiveChild && !this.isActiveParentTooltipText) {
             return;
         }
@@ -217,11 +241,90 @@ class NavMenuItem extends MenuItem {
         }
         return false;
     }
+    /**
+     * Check whether the navmenuitem is inside a dropdown container (div[data-trigger]).
+     * @internal
+     */
+    isInsideDropdownContainer() {
+        let parent = this.parentElement;
+        while (parent) {
+            if (parent.matches('div[data-trigger]')) {
+                return true;
+            }
+            parent = parent.parentElement;
+        }
+        return false;
+    }
     handleClickEvent() {
-        if (this.disabled || this.cannotActivate)
+        var _a;
+        if (this.disabled || this.cannotActivate || this.softDisabled)
+            return;
+        const context = (_a = this.sideNavigationContext) === null || _a === void 0 ? void 0 : _a.value;
+        if ((context === null || context === void 0 ? void 0 : context.isDropdownSubmenuType) && (context === null || context === void 0 ? void 0 : context.expanded) && (context === null || context === void 0 ? void 0 : context.isDropDownParent(this))) {
+            this.toggleDropdown();
+            // move the focus to the first navmenuitem in the dropdown when opening the dropdown
+            if (this.dropdownOpen) {
+                const dropdownContainer = this.getDropdownContainer();
+                const firstNavMenuItem = dropdownContainer === null || dropdownContainer === void 0 ? void 0 : dropdownContainer.querySelector(NAVMENUITEM_TAGNAME);
+                firstNavMenuItem === null || firstNavMenuItem === void 0 ? void 0 : firstNavMenuItem.focus();
+            }
             return;
+        }
         this.emitNavMenuItemActiveChange(this.active);
     }
+    /**
+     * Toggles the visibility of the dropdown container associated with this navmenuitem.
+     * @internal
+     */
+    toggleDropdown() {
+        const dropdownContainer = this.getDropdownContainer();
+        if (!dropdownContainer)
+            return;
+        this.dropdownOpen = !this.dropdownOpen;
+        dropdownContainer.style.display = this.dropdownOpen ? 'flex' : 'none';
+        if (this.dropdownOpen) {
+            this.setAttribute('aria-expanded', 'true');
+        }
+        else {
+            this.removeAttribute('aria-expanded');
+        }
+    }
+    /**
+     * Opens the dropdown if it is closed.
+     */
+    openDropdown() {
+        if (this.dropdownOpen)
+            return;
+        const dropdownContainer = this.getDropdownContainer();
+        if (dropdownContainer) {
+            dropdownContainer.style.display = 'flex';
+        }
+        this.dropdownOpen = true;
+        this.setAttribute('aria-expanded', 'true');
+    }
+    /**
+     * Closes the dropdown if it is open.
+     */
+    closeDropdown() {
+        if (!this.dropdownOpen)
+            return;
+        const dropdownContainer = this.getDropdownContainer();
+        if (dropdownContainer) {
+            dropdownContainer.style.display = 'none';
+        }
+        this.dropdownOpen = false;
+        this.removeAttribute('aria-expanded');
+    }
+    /**
+     * Returns the sibling div[data-trigger] element associated with this navmenuitem.
+     * @internal
+     */
+    getDropdownContainer() {
+        var _a;
+        if (!this.id)
+            return null;
+        return (_a = this.parentElement) === null || _a === void 0 ? void 0 : _a.querySelector(`div[data-trigger="${this.id}"]`);
+    }
     getFilledIconName() {
         if (!this.iconName) {
             return undefined;
@@ -252,10 +355,20 @@ class NavMenuItem extends MenuItem {
     render() {
         var _a;
         const context = (_a = this.sideNavigationContext) === null || _a === void 0 ? void 0 : _a.value;
+        const isDropdownMode = (context === null || context === void 0 ? void 0 : context.isDropdownSubmenuType) && (context === null || context === void 0 ? void 0 : context.expanded);
+        const isDropDownParent = context === null || context === void 0 ? void 0 : context.isDropDownParent(this);
+        const hasFlyoutSibling = context === null || context === void 0 ? void 0 : context.hasSiblingWithTriggerId(this);
         return html `
       <div part="icon-container">
-        <mdc-icon name="${this.iconName}" size="1.5" length-unit="rem" part="regular-icon"></mdc-icon>
-        ${!this.cannotActivate
+        ${this.iconName
+            ? html `<mdc-icon
+              name="${this.iconName}"
+              size="1.5"
+              length-unit="rem"
+              part="regular-icon"
+            ></mdc-icon>`
+            : nothing}
+        ${!this.cannotActivate && this.iconName
             ? html `<mdc-icon
               name="${this.getFilledIconName()}"
               size="1.5"
@@ -277,7 +390,16 @@ class NavMenuItem extends MenuItem {
             ${this.renderBadge(this.showLabel)}
           `
             : nothing}
-      ${(context === null || context === void 0 ? void 0 : context.hasSiblingWithTriggerId(this))
+      ${isDropdownMode && isDropDownParent
+            ? html ` <mdc-icon
+            name=${ICON_NAME.DOWN_ARROW}
+            length-unit="rem"
+            part="trailing-arrow-dropdown"
+            class="${this.dropdownOpen ? 'arrow-rotated' : ''}"
+          >
+          </mdc-icon>`
+            : nothing}
+      ${hasFlyoutSibling
             ? html ` <mdc-icon name=${ICON_NAME.RIGHT_ARROW} length-unit="rem" part="trailing-arrow"> </mdc-icon>`
             : nothing}
     `;
@@ -352,4 +474,8 @@ __decorate([
     state(),
     __metadata("design:type", Boolean)
 ], NavMenuItem.prototype, "hasActiveChild", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Boolean)
+], NavMenuItem.prototype, "dropdownOpen", void 0);
 export default NavMenuItem;

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

@@ -6,6 +6,7 @@ declare const ALLOWED_BADGE_TYPES: {
 };
 declare const ICON_NAME: {
     readonly RIGHT_ARROW: Extract<IconNames, "arrow-right-bold">;
+    readonly DOWN_ARROW: Extract<IconNames, "arrow-down-bold">;
 };
 declare const DEFAULTS: {
     readonly MAX_COUNTER: 99;

package/dist/components/navmenuitem/navmenuitem.constants.js

@@ -10,6 +10,7 @@ const ALLOWED_BADGE_TYPES = {
 };
 const ICON_NAME = {
     RIGHT_ARROW: 'arrow-right-bold',
+    DOWN_ARROW: 'arrow-down-bold',
 };
 const DEFAULTS = {
     MAX_COUNTER: 99,

package/dist/components/navmenuitem/navmenuitem.styles.js

@@ -12,6 +12,7 @@ const styles = [
       --mdc-navmenuitem-in-sidenav-collapsed-margin-right: var(--mdc-sidenavigation-collapsed-right-padding, 1rem);
 
       --mdc-navmenuitem-color: var(--mds-color-theme-text-primary-normal);
+      --mdc-navmenuitem-notch-color: var(--mds-color-theme-text-primary-normal);
       --mdc-navmenuitem-disabled-color: var(--mds-color-theme-text-primary-disabled);
 
       /* Background color when in default (normal) or active state */
@@ -25,6 +26,7 @@ const styles = [
 
       position: relative;
       flex-shrink: 0;
+      height: 2.5rem;
       display: flex;
       align-items: center;
       gap: 0.5rem;
@@ -54,8 +56,10 @@ const styles = [
       display: none;
     }
 
-    :host([in-menupopover]) {
+    :host([in-menupopover]),
+    :host([in-dropdown-container]) {
       width: 100%;
+      padding: 1rem;
     }
 
     :host(:not([in-menupopover])) {
@@ -112,11 +116,12 @@ const styles = [
       background-color: var(--mdc-navmenuitem-pressed-active-background-color);
     }
 
-    :host(:not([in-menupopover]))::before {
+    :host(:not([in-menupopover]))::before,
+    :host([in-dropdown-container])::before {
       content: '';
       display: block;
       position: absolute;
-      background-color: var(--mdc-navmenuitem-color);
+      background-color: var(--mdc-navmenuitem-notch-color);
       width: 0.25rem;
       height: 1rem;
       pointer-events: none;
@@ -175,14 +180,20 @@ const styles = [
       flex-shrink: 0;
 
       position: absolute;
-      inset-inline-end: -0.25rem;
+      inset-inline-end: -0.125rem;
       top: 0.875rem;
     }
 
-    :host([show-label])::part(trailing-arrow) {
+    :host([show-label])::part(trailing-arrow),
+    :host([show-label])::part(trailing-arrow-dropdown) {
       flex-shrink: 0;
     }
 
+    /* Arrow rotation when dropdown is open */
+    .arrow-rotated {
+      transform: rotate(180deg);
+    }
+
     :host mdc-badge {
       --mdc-badge-dot-width: 1rem;
       --mdc-badge-dot-height: 1rem;

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

@@ -3,16 +3,26 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 declare const OptGroup_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
 /**
- * optgroup component, which creates a grouping of mdc-option within a listbox element.
- *
- * @dependency mdc-text
- *
+ * `mdc-optgroup` groups a set of `mdc-option` elements under a shared label inside a listbox (typically the `mdc-selectlistbox` rendered by `mdc-select`). It exposes the grouping to assistive technology via `role="group"` and an associated label.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-optgroup` to organise related options inside an `mdc-selectlistbox` or `mdc-listbox` (for example, grouping countries by continent).
+ * - Use it to disable a whole set of options at once via the `disabled` attribute.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-optgroup` for grouping menu items — use `mdc-menusection` inside `mdc-menupopover` or `mdc-menubar`.
+ * - Do not nest `mdc-optgroup` inside another `mdc-optgroup`.
+ * 
  * @tagname mdc-optgroup
- *
+ * 
+ * @dependency mdc-text
+ * 
  * @slot default - This is a default slot for mdc-option elements.
- *
+ * 
  * @cssproperty --mdc-optgroup-disabled-color - Allows customization of the disabled option color.
- *
+ * 
  * @csspart header-text - The header text of the optgroup.
  */
 declare class OptGroup extends OptGroup_base {

package/dist/components/optgroup/optgroup.component.js

@@ -18,12 +18,10 @@ import { TAG_NAME as OPTION_TAGNAME } from '../option/option.constants';
 import { HEADER_ID } from './optgroup.constants';
 import styles from './optgroup.styles';
 /**
- * optgroup component, which creates a grouping of mdc-option within a listbox element.
+ * @tagname mdc-optgroup
  *
  * @dependency mdc-text
  *
- * @tagname mdc-optgroup
- *
  * @slot default - This is a default slot for mdc-option elements.
  *
  * @cssproperty --mdc-optgroup-disabled-color - Allows customization of the disabled option color.

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

@@ -3,33 +3,31 @@ import type { IconNames } from '../icon/icon.types';
 import ListItem from '../listitem/listitem.component';
 declare const Option_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FormInternalsMixin").FormInternalsMixinInterface> & typeof ListItem;
 /**
- * Option component, which is used within Selectlistbox within Select component.
- *
- * The label and secondary label of the option can be set using the `label` and `secondaryLabel` properties respectively.
- * The `label` is the primary text displayed in the option, while the `secondaryLabel` is the secondary text displayed below the primary label.
- *
- * The `selected` property is used to indicate whether the option is selected or not.
- * When the `selected` property is set to true, a checkmark icon will be displayed
- * on the right side of the option to indicate that it is selected.
- *
- * The `prefixIcon` property can be used to display an icon on the left side of the option label.
- *
- * **Note**: If an option contains a long text, it is recommended to create a tooltip for the option that displays the full text on hover.
- * Consumers need to add a unique ID to this option and use that ID in the tooltip's `triggerID` attribute. We are not creating the tooltip automatically, consumers need to add `<mdc-tooltip>` element manually and associate it with the option using the `triggerID` attribute.
- *
+ * `mdc-option` is a selectable entry rendered inside a listbox (`mdc-selectlistbox` / `mdc-listbox`), typically as a child of `mdc-select`. It supports a primary and secondary label, an optional prefix icon, and renders a checkmark on the trailing side when selected. The component participates in form submission through its associated form-control behaviour.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-option` for each selectable value inside an `mdc-select`, `mdc-selectlistbox`, or `mdc-listbox`.
+ * - Group related options together with `mdc-optgroup`.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-option` inside menus — use `mdc-menuitem`, `mdc-menuitemcheckbox`, or `mdc-menuitemradio` inside `mdc-menupopover`/`mdc-menubar`.
+ * - Do not use it as a stand-alone list row; use `mdc-listitem` for generic lists.
+ * 
+ * @tagname mdc-option
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
- * @tagname mdc-option
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the option is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the option.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the option.
  * @event focus - (React: onFocus) This event is dispatched when the option receives focus.
- *
+ * 
  * @cssproperty --mdc-listitem-column-gap - gap between columns in the option
  * @cssproperty --mdc-option-icon-width - width of the icon in the option
- *
+ * 
  * @csspart leading - Allows customization of the leading part.
  * @csspart leading-text - Allows customization of the leading text part.
  * @csspart trailing - Allows customization of the trailing part.

package/dist/components/option/option.component.js

@@ -17,25 +17,11 @@ import { TYPE } from '../text/text.constants';
 import { SELECTED_ICON_NAME } from './option.constants';
 import styles from './option.styles';
 /**
- * Option component, which is used within Selectlistbox within Select component.
- *
- * The label and secondary label of the option can be set using the `label` and `secondaryLabel` properties respectively.
- * The `label` is the primary text displayed in the option, while the `secondaryLabel` is the secondary text displayed below the primary label.
- *
- * The `selected` property is used to indicate whether the option is selected or not.
- * When the `selected` property is set to true, a checkmark icon will be displayed
- * on the right side of the option to indicate that it is selected.
- *
- * The `prefixIcon` property can be used to display an icon on the left side of the option label.
- *
- * **Note**: If an option contains a long text, it is recommended to create a tooltip for the option that displays the full text on hover.
- * Consumers need to add a unique ID to this option and use that ID in the tooltip's `triggerID` attribute. We are not creating the tooltip automatically, consumers need to add `<mdc-tooltip>` element manually and associate it with the option using the `triggerID` attribute.
+ * @tagname mdc-option
  *
  * @dependency mdc-icon
  * @dependency mdc-text
  *
- * @tagname mdc-option
- *
  * @event click - (React: onClick) This event is dispatched when the option is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the option.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the option.

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

@@ -2,29 +2,31 @@ import { CSSResult, nothing } from 'lit';
 import Input from '../input/input.component';
 import type { InputType } from '../input/input.types';
 /**
- * `mdc-password` is a component that allows users to input their password.
- *  It extends the `mdc-input` component and provides additional features specific to password fields.
- *  It contains:
- * - `label` field - describe the password field.
- * - `password` field - contains the value
- * - `help-text` or `validation-message` - displayed below the password field.
- * - `help-text-type` - type of the help text, can be 'default', 'error', 'warning', 'success', 'priority'.
- * - `show-button-aria-label` - aria label for the trailing show button.
- * - `hide-button-aria-label` - aria label for the trailing hide button.
- * - all the attributes of the native password field.
- *
+ * `mdc-password` is a form-associated password input. It renders the same label, help-text, validation, prefix, and leading-icon surface as `mdc-input`, but the input type defaults to `password` and a trailing show/hide button is always present so users can reveal or mask the entered value.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-password` whenever the user needs to enter a credential or other secret string that should be visually masked.
+ * - Use it as the password field in sign-in, sign-up, and credential-change forms inside a `form` element.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-password` for regular text — use `mdc-input` instead.
+ * - Do not use it for multi-line secrets — use `mdc-textarea`.
+ * - Do not use it for one-time codes that should be visible as the user types — use `mdc-input`.
+ * 
  * @tagname mdc-password
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the value of the password field changes (every press).
  * @event change - (React: onChange) This event is dispatched when the value of the password field changes (on blur).
  * @event focus - (React: onFocus) This event is dispatched when the password receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the password loses focus.
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-button
  * @dependency mdc-toggletip
- *
+ * 
  * @slot label - Slot for the label element. If not provided, the `label` property will be used to render the label.
  * @slot toggletip - Slot for the toggletip info icon button. If not provided, the `toggletip-text` property will be used to render the info icon button and toggletip.
  * @slot help-icon - Slot for the helper/validation icon. If not provided, the icon will be rendered based on the `helpTextType` property.
@@ -33,7 +35,7 @@ import type { InputType } from '../input/input.types';
  * @slot input-leading-icon - Slot for the leading icon before the input field. If not provided, the `leadingIcon` property will be used to render the leading icon.
  * @slot input-prefix-text - Slot for the prefix text before the input field. If not provided, the `prefixText` property will be used to render the prefix text.
  * @slot trailing-button - Slot for the trailing button to clear the input field. If not provided, the clear button will be rendered when `trailingButton` property is set to true.
- *
+ * 
  * @csspart input-container - The container that wraps the input field, leading icon, prefix text, and trailing button.
  * @csspart input-section - The container that wraps the input field and prefix text.
  * @csspart input-text - The input field element.
@@ -43,7 +45,7 @@ import type { InputType } from '../input/input.types';
  * @csspart helper-icon - The helper/validation icon element.
  * @csspart toggletip - The toggletip icon button element.
  * @csspart toggletip-text - The toggletip text element.
- *
+ * 
  * @cssproperty --mdc-label-font-size - Font size for the label text.
  * @cssproperty --mdc-label-font-weight - Font weight for the label text.
  * @cssproperty --mdc-label-line-height - Line height for the label text.
@@ -58,7 +60,6 @@ import type { InputType } from '../input/input.types';
  * @cssproperty --mdc-input-background-color - Background color for the input field
  * @cssproperty --mdc-input-selection-text-color - Text color for the selected text
  * @cssproperty --mdc-input-selection-background-color - Background color for the selected text
- *
  */
 declare class Password extends Input {
     /**

package/dist/components/password/password.component.js

@@ -16,17 +16,6 @@ import { DEFAULTS } from '../formfieldwrapper/formfieldwrapper.constants';
 import { PASSWORD_VISIBILITY_ICONS } from './password.constants';
 import styles from './password.styles';
 /**
- * `mdc-password` is a component that allows users to input their password.
- *  It extends the `mdc-input` component and provides additional features specific to password fields.
- *  It contains:
- * - `label` field - describe the password field.
- * - `password` field - contains the value
- * - `help-text` or `validation-message` - displayed below the password field.
- * - `help-text-type` - type of the help text, can be 'default', 'error', 'warning', 'success', 'priority'.
- * - `show-button-aria-label` - aria label for the trailing show button.
- * - `hide-button-aria-label` - aria label for the trailing hide button.
- * - all the attributes of the native password field.
- *
  * @tagname mdc-password
  *
  * @event input - (React: onInput) This event is dispatched when the value of the password field changes (every press).

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

@@ -5,61 +5,29 @@ import { DepthManager, StackChange, StackedOverlayComponent } from '../../utils/
 import { PopoverBoundaryRoot, PopoverColor, PopoverPlacement, PopoverStrategy, PopoverTrigger } from './popover.types';
 declare const Popover_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/BackdropMixin").BackdropMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/PreventScrollMixin").PreventScrollMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/focus/FocusTrapMixin").FocusTrapClassInterface> & typeof Component;
 /**
- * Popover is generic overlay which can be triggered by any actionable element.
- *
- * It can be used for tooltips, dropdowns, menus or any showing any other contextual content.
- *
- * The popover automatically positions itself based on available space and
- * supports dynamic height adjustments with scrollable content when needed.
- * It uses [Floating UI](https://floating-ui.com/) for maintaining the position of the popover.
- *
- * ## Limitations
- *
- * ### On trigger for multiple popovers
- *
- * A component (button, etc.) can trigger more than one popover, but only one of them should change the
- * aria-expanded and aria-haspopup attributes on the trigger.
- *
- * To prevent unexpected attribute changes on the trigger `disable-aria-expanded` attribute must be set on all linked
- * Popovers except one.
- *
- * ### React Popover with append-to attribute
- *
- * React mounts the popover based on the virtual DOM, but when the append-to attribute is set, the popover removes itself
- * and mounts to the specified element. React will not know about the move and will not know about the
- * newly created mdc-popoverportal element either. This throws a `NotFoundError` error when the Popover is directly
- * added/removed by React, for example:
- *
- * ```tsx
- * const SomeComponent = () => {
- *    const [isOpen, setIsOpen] = useState(false);
- *    return (<div>
- *      {isOpen && <Popover append-to="some-element-id">...</mdc-popover>}
- *    </div>);
- * }
- * ```
- * As a workaround Popover need to wrap with any other element/component, for example:
- * ```tsx
- * const SomeComponent = () => {
- *    const [isOpen, setIsOpen] = useState(false);
- *    return (<div>
- *      {isOpen && <div>
- *        <Popover append-to="some-element-id">...</mdc-popover>
- *      <div>}
- *    </div>);
- * }
- * ```
- * Note the wrapper <div> around the Popover component (React.Fragment does not work).
- *
- * @dependency mdc-button
- *
+ * The popover is a generic overlay that can be anchored to any actionable element on the page (identified by its `id`) and used to host tooltips, dropdowns, menus, or any other contextual content. It automatically positions itself based on available space, can resize to fit the viewport, and uses [Floating UI](https://floating-ui.com/) to keep its position correct as the page scrolls or resizes.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-popover` to render contextual UI floating next to a trigger element — additional information, action menus, or interactive panels.
+ * - Use it when you need fine control over trigger events (click, hover, focus, manual), placement, offset, arrow, focus trap, or backdrop behaviour.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-tooltip` for short, non-interactive descriptive text shown on hover/focus.
+ * - Use `mdc-toggletip` for short text shown on click that does not need focus trapping.
+ * - Use `mdc-dialog` for modal flows that interrupt the user, render in the centre of the viewport, and own their own header/footer chrome.
+ * - Use `mdc-menupopover` / `mdc-coachmark` / `mdc-searchpopover` when one of those higher-level widgets already composes a popover for the use case.
+ * 
  * @tagname mdc-popover
- *
+ * 
+ * @dependency mdc-button
+ * 
  * @event shown - (React: onShown) This event is dispatched when the popover is shown
  * @event hidden - (React: onHidden) This event is dispatched when the popover is hidden
  * @event created - (React: onCreated) This event is dispatched when the popover is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) This event is dispatched when the popover is destroyed (removed from the DOM)
- *
+ * 
  * @cssproperty --mdc-popover-arrow-border-radius - radius of the arrow border
  * @cssproperty --mdc-popover-arrow-border - border of the arrow
  * @cssproperty --mdc-popover-primary-background-color - primary background color of the popover
@@ -72,9 +40,9 @@ declare const Popover_base: import("../../utils/mixins/index.types").Constructor
  * @cssproperty --mdc-popover-max-height - max height of the popover
  * @cssproperty --mdc-popover-width - width of the popover
  * @cssproperty --mdc-popover-backdrop-color - background color of the backdrop (if backdrop is enabled)
- *
+ * 
  * @slot - Default slot for the popover content
- *
+ * 
  * @csspart popover-close - The close button of the popover.
  * @csspart popover-content - The content of the popover.
  * @csspart popover-hover-bridge - The hover bridge of the popover.