@momentum-design/components 0.134.20 → 0.134.22

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

@@ -3,30 +3,35 @@ import type Option from '../option';
 import { Component } from '../../models';
 declare const ListBox_base: import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/ListNavigationMixin").ListNavigationMixinInterface & import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface & import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/lifecycle/CaptureDestroyEventForChildElement").CaptureDestroyEventForChildElementInterface> & typeof Component;
 /**
- * listbox component presents a list of options and allows a user to select one or more of them.
- *
- * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection
- * instead of replacing the current selection.
- *
- * Notes:
- * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.
- * - this component has name and value attributes and also emits change event,
- *   but it is not a form control (yet).
- *
+ * The listbox presents a list of `mdc-option` elements (optionally grouped by `mdc-optgroup`) and lets the user pick one option (default) or multiple options (`multiple`). Clicking an option, or pressing `Enter` / `Space` while it is focused, toggles selection in multi mode and replaces the selection in single mode.
+ * 
+ * The listbox emits a `change` event whenever the selection changes, with `value` (the most recently selected option's `value`) and `selectedValues` (all currently selected `value`s) in the event detail. It is not yet a form control — wire its `value` into a form manually if form submission is needed.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-listbox` to present a list of options where the user must pick one (single select) or several (`multiple`) — for example a side-panel filter list, a settings picker, or a stand-alone option group.
+ * - Use it when the WAI-ARIA listbox pattern (focus on selected option on entry, no looping, `aria-multiselectable` for multi) is the right semantic fit.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-select` (with `mdc-selectlistbox` inside) for a form-control select that opens a popover — the standalone `mdc-listbox` is the visible-options-only variant.
+ * - Use `mdc-menupopover` for application menus (commands), not for selection.
+ * - Use `mdc-list` with `mdc-listitem` for a navigable list that does not have selection semantics.
+ * 
+ * @tagname mdc-listbox
+ * 
  * @dependency mdc-list
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-option
  * @dependency mdc-optgroup
- *
- * @tagname mdc-listbox
- *
+ * 
  * @cssproperty --mdc-listbox-max-height - max height of the listbox
- *
+ * 
  * @slot default - This is a default/unnamed slot, where options and optgroups are placed
- *
+ * 
  * @csspart container - The container of the listbox
- *
+ * 
  * @event change - (React: onChange) This event is emitted when the selected item changed
  */
 declare class ListBox extends ListBox_base {

package/dist/components/listbox/listbox.component.js

@@ -18,15 +18,7 @@ import { Component } from '../../models';
 import { ElementStore } from '../../utils/controllers/ElementStore';
 import styles from './listbox.styles';
 /**
- * listbox component presents a list of options and allows a user to select one or more of them.
- *
- * When `multiple` is enabled, clicking/pressing Enter/Space on an option toggles its selection
- * instead of replacing the current selection.
- *
- * Notes:
- * - This is a standalone listbox component. Select has its own mdc-selectlistbox component.
- * - this component has name and value attributes and also emits change event,
- *   but it is not a form control (yet).
+ * @tagname mdc-listbox
  *
  * @dependency mdc-list
  * @dependency mdc-icon
@@ -34,8 +26,6 @@ import styles from './listbox.styles';
  * @dependency mdc-option
  * @dependency mdc-optgroup
  *
- * @tagname mdc-listbox
- *
  * @cssproperty --mdc-listbox-max-height - max height of the listbox
  *
  * @slot default - This is a default/unnamed slot, where options and optgroups are placed

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

@@ -2,17 +2,25 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { IconNames } from '../icon/icon.types';
 /**
- * Listheader component is used to display a header in a list.
- * It can include icons before and after the header text, and allows for additional content via slots.
- *
+ * The listheader is a header row rendered above the items of an `mdc-list` (via the list's `list-header` slot). It displays optional prefix and postfix icons and a header text, plus a default slot for actionable content (buttons, links) aligned to the trailing end. The header itself is not interactive — interactivity comes only from elements placed in the slot.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-listheader` (in the `list-header` slot of an `mdc-list`) to label a list with a heading, an optional leading icon, and optional trailing actions.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use `mdc-listheader` as an item inside the list's default slot — it is designed for the `list-header` slot only.
+ * - Use a plain section title outside the list when no leading icon, trailing icon, or trailing action is needed.
+ * 
  * @tagname mdc-listheader
- *
+ * 
  * @slot default - to pass in actionable content like buttons or links
- *
+ * 
  * @cssproperty --mdc-listheader-height - height of the header
  * @cssproperty --mdc-listheader-padding - padding around the header content
  * @cssproperty --mdc-listheader-gap - gap between content
- *
+ * 
  * @csspart header-text - The header text of list header
  * @csspart postfix-icon - The postfix icon of list header
  * @csspart prefix-icon - The prefix icon of list header

package/dist/components/listheader/listheader.component.js

@@ -12,9 +12,6 @@ import { property } from 'lit/decorators.js';
 import { Component } from '../../models';
 import styles from './listheader.styles';
 /**
- * Listheader component is used to display a header in a list.
- * It can include icons before and after the header text, and allows for additional content via slots.
- *
  * @tagname mdc-listheader
  *
  * @slot default - to pass in actionable content like buttons or links

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

@@ -4,23 +4,25 @@ import type { TextType } from '../text/text.types';
 import { ListItemVariants } from './listitem.types';
 declare const ListItem_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<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/TabIndexMixin").TabIndexMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/lifecycle/LifeCycleMixin").LifeCycleMixinInterface> & typeof Component;
 /**
- * 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.
@@ -30,7 +32,7 @@ declare const ListItem_base: import("../../utils/mixins/index.types").Constructo
  * @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.
@@ -45,12 +47,12 @@ declare const ListItem_base: import("../../utils/mixins/index.types").Constructo
  * @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/components/listitem/listitem.component.js

@@ -21,19 +21,6 @@ import { DEFAULTS } from './listitem.constants';
 import { ListItemEventManager } from './listitem.events';
 import styles from './listitem.styles';
 /**
- * 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/components/marker/marker.component.d.ts

@@ -2,23 +2,22 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { MarkerVariants } from './marker.types';
 /**
- * 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/components/marker/marker.component.js

@@ -12,21 +12,6 @@ import { Component } from '../../models';
 import styles from './marker.styles';
 import { MARKER_VARIANTS } from './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/components/menubar/menubar.component.d.ts

@@ -3,25 +3,18 @@ import { Component } from '../../models';
 import { DepthManager } from '../../utils/controllers/DepthManager';
 declare const MenuBar_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & typeof Component;
 /**
- * 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/components/menubar/menubar.component.js

@@ -21,25 +21,6 @@ import { KeyDownHandledMixin } from '../../utils/mixins/KeyDownHandledMixin';
 import { DEFAULTS, TAG_NAME as MENUBAR_TAGNAME } from './menubar.constants';
 import styles from './menubar.styles';
 /**
- * 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
  */
@@ -254,7 +235,8 @@ class MenuBar extends KeyDownHandledMixin(KeyToActionMixin(Component)) {
         return !!element.closest(MENUPOPOVER_TAGNAME) && element.role === ROLE.MENUITEM;
     }
     async closeAllMenuPopovers() {
-        const popovers = this.depthManager.popUntil(item => this.contains(item));
+        const allPopovers = this.getAllPopovers();
+        const popovers = this.depthManager.popUntil(item => allPopovers.includes(item));
         await Promise.all(popovers.map(popover => popover.updateComplete));
     }
     async crossMenubarNavigationOnLeft(element) {

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

@@ -2,25 +2,24 @@ import type { CSSResult } from 'lit';
 import ListItem from '../listitem/listitem.component';
 import type { ArrowPositions, ArrowDirections } from './menuitem.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 { ArrowPositions, ArrowDirections } from './menuitem.types';
  * @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 { ArrowPositions, ArrowDirections } from './menuitem.types';
  * @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/components/menuitem/menuitem.component.js

@@ -16,25 +16,11 @@ import { ACTIONS } from '../../utils/mixins/KeyToActionMixin';
 import { ARROW_ICONS, ARROW_DIRECTIONS, ARROW_POSITIONS } from './menuitem.constants';
 import styles from './menuitem.styles';
 /**
- * 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/components/menuitemcheckbox/menuitemcheckbox.component.d.ts

@@ -3,36 +3,25 @@ import MenuItem from '../menuitem/menuitem.component';
 import type { Indicator } from './menuitemcheckbox.types';
 declare const MenuItemCheckbox_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ControlTypeMixin").ControlTypeMixinInterface> & typeof MenuItem;
 /**
- * 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 @@ declare const MenuItemCheckbox_base: import("../../utils/mixins/index.types").Co
  * @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/components/menuitemcheckbox/menuitemcheckbox.component.js

@@ -18,36 +18,12 @@ import { ControlTypeMixin } from '../../utils/mixins/ControlTypeMixin';
 import { DEFAULTS, INDICATOR } from './menuitemcheckbox.constants';
 import styles from './menuitemcheckbox.styles';
 /**
- * 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.