@momentum-design/components 0.134.20 → 0.134.21

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

@@ -1,30 +1,20 @@
 import Component from '../../components/illustrationprovider';
 /**
- * IllustrationProvider component, which allows to be consumed from sub components
- * (see `providerUtils.consume` for how to consume)
- *
- * Attribute `illustrationSet` can be set to either `momentum-illustrations` or `custom-illustrations`.
- * If `momentum-illustrations` is selected, the illustrations will be fetched from the
- * Momentum Design System illustration set per a dynamic JS Import (no need to provide a URL).
- * This requires the consumer to have the `@momentum-design/illustrations` package installed and the
- * build tooling needs to support dynamic imports.
- *
- * If `custom-illustrations` is selected, the illustrations will be fetched from the provided URL.
- * This requires the consumer to provide a URL from which the illustrations will be fetched and
- * the consumer needs to make sure to bundle the illustrations in the application.
- *
- * If `cacheStrategy` is provided (only works with illustrationSet = `custom-illustrations`), the
- * IllustrationProvider will cache the illustrations in the selected cache (either web-api-cache or in-memory-cache),
- * to avoid fetching the same illustration multiple times over the network.
- * This is useful when the same illustration is used multiple times in the application.
- * To consider:
- * - The `in-memory-cache` is not persisted and will be lost when the
- * IllustrationProvider is removed from the DOM.
- * - The `web-api-cache` is persisted, but only works in https environments
- * (https://developer.mozilla.org/en-US/docs/Web/API/Cache).
- *
+ * The illustrationprovider is a context provider for `mdc-illustration`. It broadcasts the configuration every nested illustration needs to resolve its `name` into a rendered SVG: which illustration set to use, where to fetch from (for custom illustrations), what file extension to apply, and an optional cache strategy.
+ * 
+ * Wrap the application (or a sub-tree) with an `mdc-illustrationprovider` once; every `mdc-illustration` inside it reads the same configuration via context. Without a surrounding illustrationprovider, an `mdc-illustration` cannot resolve its source and renders nothing.
+ * 
+ * **When to use**
+ * 
+ * - Wrap the root of the application (or any sub-tree that uses illustrations) with `mdc-illustrationprovider` to configure the source once for every nested `mdc-illustration`.
+ * - Use it when illustrations should be cached across re-renders or page navigations to avoid repeated network fetches.
+ * 
+ * **When not to use**
+ * 
+ * - Do not nest multiple `mdc-illustrationprovider`s when one provider is enough — the nearest provider wins per illustration, so nesting only makes sense when different sub-trees genuinely need different sources.
+ * 
  * @tagname mdc-illustrationprovider
- *
+ * 
  * @slot - children
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/illustrationprovider/index.js

@@ -3,29 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/illustrationprovider';
 import { TAG_NAME } from '../../components/illustrationprovider/illustrationprovider.constants';
 /**
- * IllustrationProvider component, which allows to be consumed from sub components
- * (see `providerUtils.consume` for how to consume)
- *
- * Attribute `illustrationSet` can be set to either `momentum-illustrations` or `custom-illustrations`.
- * If `momentum-illustrations` is selected, the illustrations will be fetched from the
- * Momentum Design System illustration set per a dynamic JS Import (no need to provide a URL).
- * This requires the consumer to have the `@momentum-design/illustrations` package installed and the
- * build tooling needs to support dynamic imports.
- *
- * If `custom-illustrations` is selected, the illustrations will be fetched from the provided URL.
- * This requires the consumer to provide a URL from which the illustrations will be fetched and
- * the consumer needs to make sure to bundle the illustrations in the application.
- *
- * If `cacheStrategy` is provided (only works with illustrationSet = `custom-illustrations`), the
- * IllustrationProvider will cache the illustrations in the selected cache (either web-api-cache or in-memory-cache),
- * to avoid fetching the same illustration multiple times over the network.
- * This is useful when the same illustration is used multiple times in the application.
- * To consider:
- * - The `in-memory-cache` is not persisted and will be lost when the
- * IllustrationProvider is removed from the DOM.
- * - The `web-api-cache` is persisted, but only works in https environments
- * (https://developer.mozilla.org/en-US/docs/Web/API/Cache).
- *
  * @tagname mdc-illustrationprovider
  *
  * @slot - children

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

@@ -3,19 +3,24 @@ import Component from '../../components/input';
 import type { Events } from '../../components/input/input.types';
 import type { Events as EventsInherited } from '../../utils/mixins/CharacterLimitMixin.ts';
 /**
- * mdc-input is a component that allows users to input text.
- *  It contains:
- * - label field - describe the input field.
- * - input field - contains the value
- * - help text or validation message - displayed below the input field.
- * - trailing button - it displays a clear the input field.
- * - prefix text - displayed before the input field.
- * - leading icon - displayed before the input field.
- * - clear-aria-label - aria label for the trailing button.
- * - all the attributes of the input field.
- *
+ * The input is a single-line text field with a label, optional helper or validation text, and an optional trailing clear button. It supports a leading icon, a static prefix text, character counting, and full HTML form integration (the host is form-associated and submits its `value` under `name`).
+ * 
+ * The label, required indicator, and helper text rendering follow the standard form-field layout; an optional info-icon toggletip can be attached next to the label for additional context.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-input` for any short, free-form text entry: names, search terms, single-line addresses, codes, or any value that fits on one line.
+ * - Use it when the field needs label, helper/validation text, and form integration without writing the wiring by hand.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-textarea` for multi-line input.
+ * - Use `mdc-password` for password entry that needs show/hide toggling.
+ * - Use `mdc-searchfield` for search-specific input with built-in search styling.
+ * - Use `mdc-select` or `mdc-combobox` when the value must be chosen from a fixed list.
+ * 
  * @tagname mdc-input
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).
  * @event change - (React: onChange) This event is dispatched when the value of the input field changes (on blur).
  * @event focus - (React: onFocus) This event is dispatched when the input receives focus.
@@ -23,12 +28,12 @@ import type { Events as EventsInherited } from '../../utils/mixins/CharacterLimi
  * @event clear - (React: onClear) This event is dispatched when the input text is cleared.
  * @event limitexceeded - (React: onLimitExceeded) This event is dispatched once when the character limit
  * exceeds or restored.
- *
+ * 
  * @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.
@@ -37,7 +42,7 @@ import type { Events as EventsInherited } from '../../utils/mixins/CharacterLimi
  * @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.
- *
+ * 
  * @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.
@@ -54,7 +59,7 @@ import type { Events as EventsInherited } from '../../utils/mixins/CharacterLimi
  * @cssproperty --mdc-input-support-text-color - Text color for the help text
  * @cssproperty --mdc-input-selection-text-color - Text color for the selected text
  * @cssproperty --mdc-input-selection-background-color - Background color for the selected text
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.

package/dist/react/input/index.js

@@ -3,17 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/input';
 import { TAG_NAME } from '../../components/input/input.constants';
 /**
- * mdc-input is a component that allows users to input text.
- *  It contains:
- * - label field - describe the input field.
- * - input field - contains the value
- * - help text or validation message - displayed below the input field.
- * - trailing button - it displays a clear the input field.
- * - prefix text - displayed before the input field.
- * - leading icon - displayed before the input field.
- * - clear-aria-label - aria label for the trailing button.
- * - all the attributes of the input field.
- *
  * @tagname mdc-input
  *
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).

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

@@ -2,31 +2,37 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/inputchip';
 import type { Events } from '../../components/inputchip/inputchip.types';
 /**
- * mdc-inputchip component is an interactive chip that consumers can use to represent an input.
- *
- * - It supports a leading icon along with label.
- * - It supports a prefix slot for avatars (takes precedence over icon-name).
- * - It supports an error state for validation.
- * - It supports a close button to remove the chip.
- *
+ * The inputchip represents a single tokenised value: a short label with an optional leading prefix (icon name or arbitrary slotted content such as an avatar) and a close button that fires a `remove` event when activated. It is used in patterns where multiple values are collected into a list of chips (recipients, filters, tags).
+ * 
+ * The chip supports an `error` visual state for invalid values, a `disabled` state that also disables the close button, and a `prefix` slot that takes precedence over `icon-name` when both are provided.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-inputchip` to represent individual values inside a multi-value input pattern: token-style inputs for recipients, tags, filters, or any list of removable items.
+ * - Use it when the consumer needs full control over chip removal — the chip emits `remove` and the consumer decides what to do with that signal.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-filterchip` for chips that toggle a selected/unselected state to filter a list, rather than representing a removable input value.
+ * - Use `mdc-chip` for static, non-removable display chips.
+ * 
  * @tagname mdc-inputchip
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @event remove - This event is dispatched when the close button is activated. It bubbles and is composed.
- *
+ * 
  * @slot prefix - A slot for prefix content such as avatars.
- *
+ * 
  * @csspart label - The label part of the chip.
  * @csspart icon - The icon part of the chip.
  * @csspart close-icon - The close icon part of the chip.
- *
+ * 
  * @cssproperty --mdc-chip-color - The color of the chip.
  * @cssproperty --mdc-chip-border-color - The border color of the chip.
  * @cssproperty --mdc-chip-background-color - The background color of the chip.
- *
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {
     onRemove: EventName<Events["onRemoveEvent"]>;

package/dist/react/inputchip/index.js

@@ -3,13 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/inputchip';
 import { TAG_NAME } from '../../components/inputchip/inputchip.constants';
 /**
- * mdc-inputchip component is an interactive chip that consumers can use to represent an input.
- *
- * - It supports a leading icon along with label.
- * - It supports a prefix slot for avatars (takes precedence over icon-name).
- * - It supports an error state for validation.
- * - It supports a close button to remove the chip.
- *
  * @tagname mdc-inputchip
  *
  * @dependency mdc-button

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

@@ -2,23 +2,29 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/link';
 import type { Events as EventsInherited } from '../../components/linksimple/linksimple.types';
 /**
- * `mdc-link` component can be used to navigate to a different page
- * within the application or to an external site. It can be used to link to
- * emails or phone numbers.
- *
- * The `children` of the link component is expected to be the text content.
- *
- * For `icon`, the `mdc-icon` component is used to render the icon.
- *
- * @dependency mdc-icon
- *
+ * The link renders a navigational hyperlink. The slotted children supply the link text; setting `icon-name` adds a trailing icon (commonly used for "opens external site" or "download" affordances). Three sizes are available (`small`, `midsize`, `large`), and the link supports inline / standalone display and an inverted colour scheme for dark backgrounds.
+ * 
+ * Like a native `<a>`, the link supports `href`, `target`, `rel`, `download`, `ping`, `hreflang`, `type`, and `referrerpolicy`. When `disabled`, navigation is suppressed and the link is removed from the tab order.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-link` for navigation: routing within the application, opening an external URL, launching an email client (`mailto:`), or a phone dialler (`tel:`).
+ * - Use it when the destination is a URL — that is, when the user expectation is "go somewhere", not "perform an action".
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-button` (or `mdc-linkbutton` when a link's visual treatment is required) for in-page actions that do not change the URL.
+ * - Use `mdc-linksimple` when no default size, no trailing icon, or a custom child layout (e.g. an icon as the entire content) is required.
+ * 
  * @tagname mdc-link
- *
+ * 
+ * @dependency mdc-icon
+ * 
  * @event click - (React: onClick) Fired when the user activates the Link using a mouse or assistive technology.
  * @event keydown - (React: onKeyDown) Fired when the user presses a key while the Link has focus.
  * @event focus - (React: onFocus) Fired when the Link receives keyboard or mouse focus.
  * @event blur - (React: onBlur) Fired when the Link loses keyboard or mouse focus.
- *
+ * 
  * @csspart anchor - The anchor element that wraps the link content.
  * @csspart text - The element that wraps the link text.
  * @csspart icon - The icon element.

package/dist/react/link/index.js

@@ -3,18 +3,10 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/link';
 import { TAG_NAME } from '../../components/link/link.constants';
 /**
- * `mdc-link` component can be used to navigate to a different page
- * within the application or to an external site. It can be used to link to
- * emails or phone numbers.
- *
- * The `children` of the link component is expected to be the text content.
- *
- * For `icon`, the `mdc-icon` component is used to render the icon.
+ * @tagname mdc-link
  *
  * @dependency mdc-icon
  *
- * @tagname mdc-link
- *
  * @event click - (React: onClick) Fired when the user activates the Link using a mouse or assistive technology.
  * @event keydown - (React: onKeyDown) Fired when the user presses a key while the Link has focus.
  * @event focus - (React: onFocus) Fired when the Link receives keyboard or mouse focus.

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

@@ -3,25 +3,32 @@ import Component from '../../components/linkbutton';
 import type { Events } from '../../components/linkbutton/linkbutton.types';
 import type { Events as EventsInherited } from '../../components/buttonsimple/buttonsimple.types';
 /**
- * `mdc-linkbutton` visually mimics a hyperlink while functioning as a button. It blends the appearance of `mdc-link` with the accessibility and interaction capabilities of `mdc-button`.
- *
- * ### Features:
- * - Looks like a link, behaves like a button.
- * - Supports slots for a text label and an optional trailing icon.
- * - Inherits accessibility and keyboard interaction behavior from `mdc-buttonsimple`.
- *
- * @dependency mdc-icon
- *
+ * The linkbutton renders as a link visually but behaves as a button: activating it fires a `click` event rather than navigating to a URL. Use it for in-page actions (open a panel, copy a value, trigger a workflow) that should sit in body text or alongside other links without standing out as a button.
+ * 
+ * The slotted children supply the label; an optional trailing icon can be added via `icon-name`. Three text sizes are supported, plus inline / standalone display and an inverted colour scheme for dark backgrounds.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-linkbutton` for in-page actions that should visually mimic a hyperlink — for example a "Show more" toggle inside a paragraph, an undo prompt after a toast, or an action embedded in a sentence.
+ * - Use it when the surrounding design treats the affordance as link-styled text but the underlying behaviour is a button (no URL navigation).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-link` when the affordance actually navigates to a URL — even if the URL is in-app, the user expectation is "go somewhere".
+ * - Use `mdc-button` when the surrounding design expects a button-shaped control.
+ * 
  * @tagname mdc-linkbutton
- *
+ * 
+ * @dependency mdc-icon
+ * 
  * @slot - Text label of the linkbutton.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the linkbutton is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the linkbutton.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the linkbutton.
  * @event focus - (React: onFocus) This event is dispatched when the linkbutton receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the linkbutton loses focus.
- *
+ * 
  * @cssproperty --mdc-link-border-radius - Border radius of the linkbutton.
  * @cssproperty --mdc-link-color-active - Color of the linkbutton’s child content in the active state.
  * @cssproperty --mdc-link-color-disabled - Color of the linkbutton’s child content in the disabled state.

package/dist/react/linkbutton/index.js

@@ -3,17 +3,10 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/linkbutton';
 import { TAG_NAME } from '../../components/linkbutton/linkbutton.constants';
 /**
- * `mdc-linkbutton` visually mimics a hyperlink while functioning as a button. It blends the appearance of `mdc-link` with the accessibility and interaction capabilities of `mdc-button`.
- *
- * ### Features:
- * - Looks like a link, behaves like a button.
- * - Supports slots for a text label and an optional trailing icon.
- * - Inherits accessibility and keyboard interaction behavior from `mdc-buttonsimple`.
+ * @tagname mdc-linkbutton
  *
  * @dependency mdc-icon
  *
- * @tagname mdc-linkbutton
- *
  * @slot - Text label of the linkbutton.
  *
  * @event click - (React: onClick) This event is dispatched when the linkbutton is clicked.

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

@@ -2,20 +2,27 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/linksimple';
 import type { Events } from '../../components/linksimple/linksimple.types';
 /**
- * `mdc-linksimple` is a lightweight link component that can be used to navigate
- * within the application or to an external URL. It does not have any predefined default size.
- *
- * The `children` of the `mdc-linksimple` component can be customized to suit
- * different use cases, including text, icons, or other inline content. For the child to be an icon,
- * the `mdc-icon` component should be used to render.
- *
+ * The linksimple is a minimal hyperlink: it renders an `<a>`, forwards the standard anchor attributes, and lets the slotted children supply whatever content the consumer needs (text, an icon, a mix of inline elements). It does not impose a default size or a built-in trailing icon — those are the job of `mdc-link`.
+ * 
+ * Use linksimple when the visual treatment of `mdc-link` does not fit (icon-only navigation, custom layouts inside the link, embedding in a tight design) but the link's accessibility and interaction contract is still needed.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-linksimple` when you need a hyperlink but the slotted content is not plain text (an icon-only link, a link wrapping a small layout) or the default sizing of `mdc-link` would interfere with the surrounding design.
+ * - Use it when the link should sit unstyled in a tight context and the consumer's own CSS will handle the typography.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-link` when the link is plain text with a clearly defined size and an optional trailing icon — `mdc-link` already wraps `mdc-linksimple` with the standard text + icon treatment.
+ * - Use `mdc-button` or `mdc-linkbutton` for in-page actions that do not navigate to a URL.
+ * 
  * @tagname mdc-linksimple
- *
+ * 
  * @event click - (React: onClick) Fired when the user activates the buttonLink using a mouse or assistive technology.
  * @event keydown - (React: onKeyDown) Fired when the user presses a key while the buttonLink has focus.
  * @event focus - (React: onFocus) Fired when the buttonLink receives keyboard or mouse focus.
  * @event blur - (React: onBlur) Fired when the buttonLink loses keyboard or mouse focus.
- *
+ * 
  * @cssproperty --mdc-link-border-radius - Border radius of the link.
  * @cssproperty --mdc-link-color-active - Color of the link’s child content in the active state.
  * @cssproperty --mdc-link-color-disabled - Color of the link’s child content in the disabled state.
@@ -25,7 +32,7 @@ import type { Events } from '../../components/linksimple/linksimple.types';
  * @cssproperty --mdc-link-inverted-color-disabled - Color of the inverted link’s child content in the disabled state.
  * @cssproperty --mdc-link-inverted-color-hover - Color of the inverted link’s child content in the hover state.
  * @cssproperty --mdc-link-inverted-color-normal - Color of the inverted link’s child content in the normal state.
- *
+ * 
  * @csspart anchor - The anchor element that wraps the linksimple content.
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {

package/dist/react/linksimple/index.js

@@ -3,13 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/linksimple';
 import { TAG_NAME } from '../../components/linksimple/linksimple.constants';
 /**
- * `mdc-linksimple` is a lightweight link component that can be used to navigate
- * within the application or to an external URL. It does not have any predefined default size.
- *
- * The `children` of the `mdc-linksimple` component can be customized to suit
- * different use cases, including text, icons, or other inline content. For the child to be an icon,
- * the `mdc-icon` component should be used to render.
- *
  * @tagname mdc-linksimple
  *
  * @event click - (React: onClick) Fired when the user activates the buttonLink using a mouse or assistive technology.

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

@@ -1,15 +1,25 @@
 import Component from '../../components/list';
 /**
- * mdc-list component is used to display a group of list items. It is used as a container to wrap other list items.
- *
- * To add a header to the list, use the `mdc-listheader` component and place it in the `list-header` slot.
- * `mdc-listitem` components can be placed in the default slot.
- *
+ * The list is a container that groups `mdc-listitem` children and provides shared keyboard navigation across them. Listitems are placed in the default slot; an optional `mdc-listheader` can be placed in the `list-header` slot. The list manages roving tabindex across items so the keyboard user only enters the list once, then moves between items with arrow keys.
+ * 
+ * The list's orientation (`vertical` or `horizontal`) selects whether arrow Up/Down or Left/Right navigate; looping (`loop="true"` / `loop="false"`) chooses whether navigation wraps at the ends; `initial-focus` selects which item receives focus when the list is entered for the first time.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-list` to display a related group of `mdc-listitem` elements (selection lists, navigation lists, settings lists) that should share keyboard navigation.
+ * - Use it whenever a list of two or more listitems is rendered — even a single listitem should be wrapped in `mdc-list` for screen-reader semantics.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-listbox` for a list of selectable options that participate in single- or multi-select selection semantics (the listbox uses `role="listbox"` and `mdc-option` children rather than `mdc-listitem`).
+ * - Use `mdc-menubar` / `mdc-menupopover` for application menus.
+ * - Use `mdc-virtualizedlist` for very large lists where DOM virtualisation is needed.
+ * 
  * @tagname mdc-list
- *
+ * 
  * @slot default - This is a default/unnamed slot, where listitems can be placed.
  * @slot list-header - This slot is used to pass a header for the list, which can be a `mdc-listheader` component.
- *
+ * 
  * @csspart container - The container slot around the list items
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/list/index.js

@@ -3,11 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/list';
 import { TAG_NAME } from '../../components/list/list.constants';
 /**
- * mdc-list component is used to display a group of list items. It is used as a container to wrap other list items.
- *
- * To add a header to the list, use the `mdc-listheader` component and place it in the `list-header` slot.
- * `mdc-listitem` components can be placed in the default slot.
- *
  * @tagname mdc-list
  *
  * @slot default - This is a default/unnamed slot, where listitems can be placed.

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

@@ -2,30 +2,35 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/listbox';
 import type { Events } from '../../components/listbox/listbox.types';
 /**
- * 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 const reactWrapper: import("@lit/react").ReactWebComponent<Component, {

package/dist/react/listbox/index.js

@@ -3,15 +3,7 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/listbox';
 import { TAG_NAME } from '../../components/listbox/listbox.constants';
 /**
- * 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
@@ -19,8 +11,6 @@ import { TAG_NAME } from '../../components/listbox/listbox.constants';
  * @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/react/listheader/index.d.ts

@@ -1,16 +1,24 @@
 import Component from '../../components/listheader';
 /**
- * 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/react/listheader/index.js

@@ -3,9 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/listheader';
 import { TAG_NAME } from '../../components/listheader/listheader.constants';
 /**
- * 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