@momentum-design/components 0.134.20 → 0.134.21

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

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 menu item styled to work as a navigation tab inside `mdc-sidenavigation`. It renders a leading icon, an optional badge, and a dynamic label that appears when the surrounding side navigation is expanded. The item can be in an active or inactive state to indicate the current page, and a tooltip can be attached for collapsed states or for parent items whose 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.
@@ -44,7 +45,7 @@ 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.

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

@@ -21,17 +21,6 @@ import { getIconNameWithoutStyle } from '../button/button.utils';
 import { ALLOWED_BADGE_TYPES, DEFAULTS, ICON_NAME } 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

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.

package/dist/components/popover/popover.component.js

@@ -26,56 +26,10 @@ import { PopoverEventManager } from './popover.events';
 import styles from './popover.styles';
 import { PopoverUtils } from './popover.utils';
 /**
- * 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).
+ * @tagname mdc-popover
  *
  * @dependency mdc-button
  *
- * @tagname mdc-popover
- *
  * @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)

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

@@ -2,16 +2,23 @@ import { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
 import type { PresenceType, PresenceSize } from './presence.types';
 /**
- * The `mdc-presence` component is a versatile UI element used to
- * display the presence status of a user or entity within an avatar component.
- *
- * This component is ideal for use within avatar UIs where the presence status
- * needs to be visually represented.
- *
- * @dependency mdc-icon
- *
+ * The presence is a small status badge that visually represents the availability or activity state of a user or entity (for example: active, away, busy, do-not-disturb, on a call, presenting). It is sized to be paired with an avatar so the status renders as a corner indicator on top of the avatar artwork.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-presence` next to or on top of an `mdc-avatar` to indicate the represented user/entity's current availability or activity.
+ * - Use it whenever the application has a meaningful status signal to communicate alongside an avatar (online, in a meeting, away, etc.).
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it as a standalone status indicator divorced from an avatar — pair it with `mdc-avatar` so the icon size matches the avatar size.
+ * - Use `mdc-badge` for counts, dots, or non-status decorations.
+ * - Use `mdc-icon` if you need an arbitrary icon at custom sizes outside the supported avatar size set.
+ * 
  * @tagname mdc-presence
- *
+ * 
+ * @dependency mdc-icon
+ * 
  * @cssproperty --mdc-presence-active-background-color - The background color of the presence type active.
  * @cssproperty --mdc-presence-away-background-color - The background color of the presence type away.
  * @cssproperty --mdc-presence-away-calling-background-color - The background color of the presence type away-calling.
@@ -27,7 +34,7 @@ import type { PresenceType, PresenceSize } from './presence.types';
  * @cssproperty --mdc-presence-quiet-background-color - The background color of the presence type quiet.
  * @cssproperty --mdc-presence-scheduled-background-color - The background color of the presence type scheduled.
  * @cssproperty --mdc-presence-overlay-background-color - The background color of the presence type overlay.
- *
+ * 
  * @csspart presence-content - The presence content.
  * @csspart mdc-presence-icon - The presence icon.
  * @csspart mdc-presence-icon__active - The presence icon for active.

package/dist/components/presence/presence.component.js

@@ -14,16 +14,10 @@ import { DEFAULTS, PRESENCE_SIZE } from './presence.constants';
 import styles from './presence.styles';
 import { getIconValue, getPresenceIconSize } from './presence.utils';
 /**
- * The `mdc-presence` component is a versatile UI element used to
- * display the presence status of a user or entity within an avatar component.
- *
- * This component is ideal for use within avatar UIs where the presence status
- * needs to be visually represented.
+ * @tagname mdc-presence
  *
  * @dependency mdc-icon
  *
- * @tagname mdc-presence
- *
  * @cssproperty --mdc-presence-active-background-color - The background color of the presence type active.
  * @cssproperty --mdc-presence-away-background-color - The background color of the presence type away.
  * @cssproperty --mdc-presence-away-calling-background-color - The background color of the presence type away-calling.