@momentum-design/components 0.134.19 → 0.134.21

package/dist/react/listitem/index.d.ts

@@ -2,23 +2,25 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/listitem';
 import type { Events } from '../../components/listitem/listitem.types';
 /**
- * mdc-listitem component is used to display a label with different types of controls.
- * There can be three types of controls, a radio button, a checkbox on the
- * leading side and a toggle on the trailing side.
- * The list item can contain an avatar on the leading side and a badge on the trailing side.
- * Additionally, the list item can contain a side header and a subline text.
- *
- * The leading and trailing slots can be used to display controls and text. <br/>
- * Based on the leading/trailing slot, the position of the controls and text can be adjusted. <br/>
- * Please use mdc-list as a parent element even when there is only listitem for a11y purpose.
- *
- * **Note**: If a listitem contains a long text, it is recommended to create a tooltip for the listitem that displays the full text on hover.
- * Consumers need to add a unique ID to this listitem 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 listitem using the `triggerID` attribute.
- *
+ * The listitem is a single row inside an `mdc-list`. It supports a leading control (radio, checkbox, avatar, icon), a trailing control (toggle, badge, icon), three leading text slots (primary / secondary / tertiary label), and two trailing text slots (side header, subline). The listitem is focusable, activates on click, `Enter`, or `Space` (dispatching a `click` event), and exposes life-cycle events (`enabled`, `disabled`, `created`, `destroyed`) that the surrounding list uses to track its items.
+ * 
+ * Three visual variants are available: `full-width` (default), `rectangle`, and `pill`. The `active` flag is a visual-only state that bolds the primary label; the canonical active / selected state belongs to the parent list pattern.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-listitem` as a row inside an `mdc-list`. Even a single listitem should be wrapped in `mdc-list` for screen-reader semantics.
+ * - Use it whenever a row needs to combine an icon / avatar / control with a label and optional trailing content.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-option` inside `mdc-listbox` / `mdc-selectlistbox` when the row represents a selectable option in a listbox pattern.
+ * - Use `mdc-menuitem`, `mdc-menuitemcheckbox`, or `mdc-menuitemradio` inside menu patterns rather than `mdc-listitem`.
+ * - Use `mdc-navmenuitem` when the row is a navigation entry inside `mdc-sidenavigation`.
+ * 
  * @tagname mdc-listitem
- *
+ * 
  * @dependency mdc-text
- *
+ * 
  * @slot leading-controls - slot for list item controls to appear of leading end.
  * @slot leading-text-primary-label - slot for list item primary label.
  * @slot leading-text-secondary-label - slot for list item secondary label.
@@ -28,7 +30,7 @@ import type { Events } from '../../components/listitem/listitem.types';
  * @slot trailing-controls - slot for list item controls to appear of trailing end.
  * @slot content - content slot can be used to override the content completely. Be aware that
  * this will override the default content of the list item.
- *
+ * 
  * @cssproperty --mdc-listitem-default-background-color - Allows customization of the default background color.
  * @cssproperty --mdc-listitem-background-color-hover - Allows customization of the background color on hover.
  * @cssproperty --mdc-listitem-background-color-active - Allows customization of the background color when pressed.
@@ -43,12 +45,12 @@ import type { Events } from '../../components/listitem/listitem.types';
  * @cssproperty --mdc-listitem-cursor - Allows customization of the cursor.
  * @cssproperty --mdc-listitem-width - Allows customization of the width of the list item.
  * @cssproperty --mdc-listitem-height - Allows customization of the height of the list item.
- *
+ * 
  * @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.
  * @csspart trailing-text - Allows customization of the trailing text part.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the listitem is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the listitem.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the listitem.

package/dist/react/listitem/index.js

@@ -3,19 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/listitem';
 import { TAG_NAME } from '../../components/listitem/listitem.constants';
 /**
- * mdc-listitem component is used to display a label with different types of controls.
- * There can be three types of controls, a radio button, a checkbox on the
- * leading side and a toggle on the trailing side.
- * The list item can contain an avatar on the leading side and a badge on the trailing side.
- * Additionally, the list item can contain a side header and a subline text.
- *
- * The leading and trailing slots can be used to display controls and text. <br/>
- * Based on the leading/trailing slot, the position of the controls and text can be adjusted. <br/>
- * Please use mdc-list as a parent element even when there is only listitem for a11y purpose.
- *
- * **Note**: If a listitem contains a long text, it is recommended to create a tooltip for the listitem that displays the full text on hover.
- * Consumers need to add a unique ID to this listitem 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 listitem using the `triggerID` attribute.
- *
  * @tagname mdc-listitem
  *
  * @dependency mdc-text

package/dist/react/marker/index.d.ts

@@ -1,22 +1,21 @@
 import Component from '../../components/marker';
 /**
- * The Marker component displays a vertical line (0.25rem wide) used to draw attention to specific content
- * or signify important information. It provides visual emphasis through color and pattern variations.
- *
- * Markers are commonly used alongside list items, cards, or content blocks to indicate status,
- * priority, or categorization.
- *
- * ## When to use
- * Use markers to highlight important content, indicate status or priority levels, or provide
- * visual categorization in lists and layouts.
- *
- * ## Accessibility
- * - Markers are purely decorative and should not convey information solely through color
- * - Always pair markers with text labels or other indicators to convey meaning
- * - Ensure sufficient color contrast for visibility
- *
+ * The marker is a thin vertical line (0.25rem wide by default) used to draw the eye to a piece of content — typically rendered alongside a list item, card, or content block to indicate status, priority, or categorisation. Two visual variants are available: `solid` (a single coloured line) and `striped` (a line with diagonal stripes for a high-attention variant).
+ * 
+ * The marker is purely presentational; its meaning must be conveyed elsewhere (label, status text, icon) because it has no accessible name.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-marker` to draw attention to important content, signal priority, or visually categorise items inside a layout.
+ * - Use it as a decorative companion to a list item, card, or content block — never as the sole signal for the information.
+ * 
+ * **When not to use**
+ * 
+ * - Use a label, status text, or an icon when the meaning must be announced to screen readers — the marker alone is invisible to assistive technology.
+ * - Use `mdc-divider` for separating content sections rather than highlighting a single block.
+ * 
  * @tagname mdc-marker
- *
+ * 
  * @cssproperty --mdc-marker-solid-background-color - Background color for solid variant markers.
  * @cssproperty --mdc-marker-striped-color - Stripe color for striped variant markers.
  * @cssproperty --mdc-marker-striped-background-color - Background color for striped variant markers.

package/dist/react/marker/index.js

@@ -3,21 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/marker';
 import { TAG_NAME } from '../../components/marker/marker.constants';
 /**
- * The Marker component displays a vertical line (0.25rem wide) used to draw attention to specific content
- * or signify important information. It provides visual emphasis through color and pattern variations.
- *
- * Markers are commonly used alongside list items, cards, or content blocks to indicate status,
- * priority, or categorization.
- *
- * ## When to use
- * Use markers to highlight important content, indicate status or priority levels, or provide
- * visual categorization in lists and layouts.
- *
- * ## Accessibility
- * - Markers are purely decorative and should not convey information solely through color
- * - Always pair markers with text labels or other indicators to convey meaning
- * - Ensure sufficient color contrast for visibility
- *
  * @tagname mdc-marker
  *
  * @cssproperty --mdc-marker-solid-background-color - Background color for solid variant markers.

package/dist/react/menubar/index.d.ts

@@ -1,24 +1,17 @@
 import Component from '../../components/menubar';
 /**
- * Menubar is a navigational menu component that provides a vertical fixed list of menu items,
- * with support for nested submenus and keyboard navigation. It serves as a container
- * for menu items and manages their interaction patterns, including:
- * - Keyboard navigation (Arrow keys, Home, End)
- * - Menu item activation (Enter/Space)
- * - Submenu toggling (Right/Left arrow keys)
- * - Focus management
- * - Integration with MenuPopover for nested menus
- *
- * A menubar will contain a set of menu items and their associated popovers.
- * Each menu item can have a popover for nested menus.
- *
- * The component automatically handles ARIA attributes and follows WAI-ARIA menu design patterns.
- * It works in conjunction with `mdc-menuitem` and `mdc-menupopover` to create accessible menu structures.
- *
- * **Note:** A menubar contains three types of menu items, including menuitem, menuitemradio and menuitemcheckbox. These menu items may optionally be nested in one or more group containers. Groups or items may optionally by separated with separator elements.
- *
- * `mdc-menubar` contains a group that wraps all its chilren passed within the default slot. This has been added to ensure the right accessibility behavior while using screen readers.
- *
+ * `mdc-menubar` is a navigational menu container that holds a fixed list of menu items and manages keyboard navigation, focus, and the opening of nested submenus. It wraps its children in an internal group so screen readers announce the menu structure correctly.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-menubar` when grouping a set of `mdc-menuitem`, `mdc-menuitemcheckbox`, or `mdc-menuitemradio` entries that may also expose nested submenus via `mdc-menupopover`.
+ * - Use it as the root for a persistent menu region (for example, the navigation tree inside `mdc-sidenavigation`).
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-menubar` for a single overlay menu opened from a trigger button — use `mdc-menupopover` directly.
+ * - Do not use it for selection lists where users pick a value to submit with a form — use `mdc-listbox` with `mdc-option` (typically inside `mdc-select`).
+ * 
  * @tagname mdc-menubar
  * @slot default - Contains the menu items and their associated popovers
  */

package/dist/react/menubar/index.js

@@ -3,25 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/menubar';
 import { TAG_NAME } from '../../components/menubar/menubar.constants';
 /**
- * Menubar is a navigational menu component that provides a vertical fixed list of menu items,
- * with support for nested submenus and keyboard navigation. It serves as a container
- * for menu items and manages their interaction patterns, including:
- * - Keyboard navigation (Arrow keys, Home, End)
- * - Menu item activation (Enter/Space)
- * - Submenu toggling (Right/Left arrow keys)
- * - Focus management
- * - Integration with MenuPopover for nested menus
- *
- * A menubar will contain a set of menu items and their associated popovers.
- * Each menu item can have a popover for nested menus.
- *
- * The component automatically handles ARIA attributes and follows WAI-ARIA menu design patterns.
- * It works in conjunction with `mdc-menuitem` and `mdc-menupopover` to create accessible menu structures.
- *
- * **Note:** A menubar contains three types of menu items, including menuitem, menuitemradio and menuitemcheckbox. These menu items may optionally be nested in one or more group containers. Groups or items may optionally by separated with separator elements.
- *
- * `mdc-menubar` contains a group that wraps all its chilren passed within the default slot. This has been added to ensure the right accessibility behavior while using screen readers.
- *
  * @tagname mdc-menubar
  * @slot default - Contains the menu items and their associated popovers
  */

package/dist/react/menuitem/index.d.ts

@@ -2,25 +2,24 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/menuitem';
 import type { Events as EventsInherited } from '../../components/listitem/listitem.types';
 /**
- * menuitem component is inherited by listitem component with the role set `menuitem`.<br/>
- * A menu item can contain an icon on the leading or trailing side.
- *
- * The leading and trailing slots can be used to display controls and text.<br/>
- * Based on the leading/trailing slot, the position of the controls and text can be adjusted.
- *
- * Please use element with role=menu as a parent element even when there is only menuitem for a11y purpose.
- * For example mdc-menupopover or mdc-menubar.
- *
- * Menu item has `name` and `value` attribute that can be used to identify the menu item when it is selected.
- *
- * **Note**: If a menuitem contains a long text, it is recommended to create a tooltip for the menuitem that displays the full text on hover.
- * Consumers need to add a unique ID to this menuitem 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 menuitem using the `triggerID` attribute.
- *
+ * `mdc-menuitem` is an actionable entry placed inside a `mdc-menubar` or `mdc-menupopover`. It exposes leading and trailing slots for controls and text, supports an optional arrow indicator for items that open submenus, and emits a click event when activated by mouse, `Enter`, or `Space`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-menuitem` for the individual entries inside a menubar or menu popover that perform an action or open a submenu.
+ * - Use it as the trigger element for a nested `mdc-menupopover` by giving it a unique `id` and pointing the popover's `triggerid` at it.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-menuitem` for toggleable state — use `mdc-menuitemcheckbox` or `mdc-menuitemradio`.
+ * - Do not use it inside `mdc-listbox`/`mdc-select` (selection lists) — use `mdc-option` there.
+ * - Do not use it as a stand-alone clickable row outside of a `menu`/`menubar`/`menupopover` context; use `mdc-listitem` for generic lists.
+ * 
+ * @tagname mdc-menuitem
+ * 
  * @dependency mdc-text
  * @dependency mdc-icon
- *
- * @tagname mdc-menuitem
- *
+ * 
  * @slot leading-controls - slot for menu item controls to appear of leading end.
  * @slot leading-text-primary-label - slot for menu item primary label.
  * @slot leading-text-secondary-label - slot for menu item secondary label.
@@ -28,7 +27,7 @@ import type { Events as EventsInherited } from '../../components/listitem/listit
  * @slot trailing-text-side-header - slot for menu item side header text.
  * @slot trailing-text-subline - slot for menu item subline text.
  * @slot trailing-controls - slot for menu item controls to appear of trailing end.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the menuitem is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the menuitem.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the menuitem.
@@ -37,7 +36,7 @@ import type { Events as EventsInherited } from '../../components/listitem/listit
  * @event disabled - (React: onDisabled) This event is dispatched after the menuitem is disabled
  * @event created - (React: onCreated) This event is dispatched after the menuitem is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) This event is dispatched after the menuitem is destroyed (removed from the DOM)
- *
+ * 
  * @csspart leading - Allows customization of the leading part.
  * @csspart leading-arrow - Allows customization of leading arrow icon.
  * @csspart leading-text - Allows customization of the leading text part.

package/dist/react/menuitem/index.js

@@ -3,25 +3,11 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/menuitem';
 import { TAG_NAME } from '../../components/menuitem/menuitem.constants';
 /**
- * menuitem component is inherited by listitem component with the role set `menuitem`.<br/>
- * A menu item can contain an icon on the leading or trailing side.
- *
- * The leading and trailing slots can be used to display controls and text.<br/>
- * Based on the leading/trailing slot, the position of the controls and text can be adjusted.
- *
- * Please use element with role=menu as a parent element even when there is only menuitem for a11y purpose.
- * For example mdc-menupopover or mdc-menubar.
- *
- * Menu item has `name` and `value` attribute that can be used to identify the menu item when it is selected.
- *
- * **Note**: If a menuitem contains a long text, it is recommended to create a tooltip for the menuitem that displays the full text on hover.
- * Consumers need to add a unique ID to this menuitem 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 menuitem using the `triggerID` attribute.
+ * @tagname mdc-menuitem
  *
  * @dependency mdc-text
  * @dependency mdc-icon
  *
- * @tagname mdc-menuitem
- *
  * @slot leading-controls - slot for menu item controls to appear of leading end.
  * @slot leading-text-primary-label - slot for menu item primary label.
  * @slot leading-text-secondary-label - slot for menu item secondary label.

package/dist/react/menuitemcheckbox/index.d.ts

@@ -3,36 +3,25 @@ import Component from '../../components/menuitemcheckbox';
 import type { Events } from '../../components/menuitemcheckbox/menuitemcheckbox.types';
 import type { Events as EventsInherited } from '../../components/listitem/listitem.types';
 /**
- * A menuitemcheckbox component is a checkable menuitem.
- * There should be no focusable descendants inside this menuitemcheckbox component.
- *
- * The `checked` attribute indicates whether the menuitemcheckbox is checked or not.
- *
- * Menu item checkbox has `name` and `value` attribute that can be used to identify the menu item when it is selected.
- *
- * The `indicator` attribute is used to differentiate between <b>checkbox</b>, <b>checkmark</b>, <b>toggle</b> and <b>none</b>.
- * By default, the `indicator` is set to <b>checkbox</b>.<br/>
- *
- * The checkbox will always be positioned on the leading side of the menuitem label and
- * the toggle and checkmark will always be positioned on the trailing side.
- *
- * The checkbox 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 forth 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.
- *
- * If you want only one item in a group to be checked, consider using menuitemradio component.
- *
+ * `mdc-menuitemcheckbox` is a checkable menu item used inside a `mdc-menupopover`, `mdc-menubar`, or `mdc-menusection`. Its checked state can be toggled independently of other items in the same group and is reflected to assistive technology through `aria-checked`. Visual feedback is provided by a checkbox (leading), toggle (trailing), checkmark (trailing), or no indicator at all.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-menuitemcheckbox` for menu entries that toggle an independent on/off setting.
+ * - Use it when several items in the same menu can be checked at the same time.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-menuitemradio` when only one item in a group may be selected.
+ * - Use `mdc-menuitem` for actions that do not have a checked state.
+ * - Do not use `mdc-checkbox` directly inside a menu; the dedicated `mdc-menuitemcheckbox` provides the correct role and keyboard behaviour.
+ * 
+ * @tagname mdc-menuitemcheckbox
+ * 
  * @dependency mdc-staticcheckbox
  * @dependency mdc-statictoggle
  * @dependency mdc-icon
- *
- * @tagname mdc-menuitemcheckbox
- *
+ * 
  * @slot leading-controls - slot for menu item checkbox controls to appear of leading end.
  * @slot leading-text-primary-label - slot for menu item checkbox primary label.
  * @slot leading-text-secondary-label - slot for menu item checkbox secondary label.
@@ -40,13 +29,13 @@ import type { Events as EventsInherited } from '../../components/listitem/listit
  * @slot trailing-text-side-header - slot for menu item checkbox side header text.
  * @slot trailing-text-subline - slot for menu item checkbox subline text.
  * @slot trailing-controls - slot for menu item checkbox controls to appear of trailing end.
- *
+ * 
  * @event change - (React: onChange) This event is dispatched when the menuitemcheckbox changes.
  * @event click - (React: onClick) This event is dispatched when the menuitemcheckbox is clicked.
  * @event focus - (React: onFocus) This event is dispatched when the menuitemcheckbox receives focus.
- *
+ * 
  * @cssproperty --mdc-listitem-padding-left-and-right - Controls the padding on the left and right of the menuitemcheckbox.
- *
+ * 
  * @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/react/menuitemcheckbox/index.js

@@ -3,36 +3,12 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/menuitemcheckbox';
 import { TAG_NAME } from '../../components/menuitemcheckbox/menuitemcheckbox.constants';
 /**
- * A menuitemcheckbox component is a checkable menuitem.
- * There should be no focusable descendants inside this menuitemcheckbox component.
- *
- * The `checked` attribute indicates whether the menuitemcheckbox is checked or not.
- *
- * Menu item checkbox has `name` and `value` attribute that can be used to identify the menu item when it is selected.
- *
- * The `indicator` attribute is used to differentiate between <b>checkbox</b>, <b>checkmark</b>, <b>toggle</b> and <b>none</b>.
- * By default, the `indicator` is set to <b>checkbox</b>.<br/>
- *
- * The checkbox will always be positioned on the leading side of the menuitem label and
- * the toggle and checkmark will always be positioned on the trailing side.
- *
- * The checkbox 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 forth 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.
- *
- * If you want only one item in a group to be checked, consider using menuitemradio component.
+ * @tagname mdc-menuitemcheckbox
  *
  * @dependency mdc-staticcheckbox
  * @dependency mdc-statictoggle
  * @dependency mdc-icon
  *
- * @tagname mdc-menuitemcheckbox
- *
  * @slot leading-controls - slot for menu item checkbox controls to appear of leading end.
  * @slot leading-text-primary-label - slot for menu item checkbox primary label.
  * @slot leading-text-secondary-label - slot for menu item checkbox secondary label.

package/dist/react/menuitemradio/index.d.ts

@@ -3,38 +3,25 @@ import Component from '../../components/menuitemradio';
 import type { Events } from '../../components/menuitemradio/menuitemradio.types';
 import type { Events as EventsInherited } from '../../components/listitem/listitem.types';
 /**
- * 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 @@ import type { Events as EventsInherited } from '../../components/listitem/listit
  * @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/react/menuitemradio/index.js

@@ -3,38 +3,13 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/menuitemradio';
 import { TAG_NAME } from '../../components/menuitemradio/menuitemradio.constants';
 /**
- * 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/react/menupopover/index.d.ts

@@ -3,49 +3,27 @@ import Component from '../../components/menupopover';
 import type { Events } from '../../components/menupopover/menupopover.types';
 import type { Events as EventsInherited } from '../../components/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.