@momentum-design/components 0.134.20 → 0.134.22

package/dist/components/iconprovider/iconprovider.component.js

@@ -12,29 +12,6 @@ import { Provider } from '../../models';
 import IconProviderContext from './iconprovider.context';
 import { ALLOWED_FILE_EXTENSIONS, DEFAULTS, ALLOWED_LENGTH_UNITS } from './iconprovider.constants';
 /**
- * IconProvider component, which allows to be consumed from sub components
- * (see `providerUtils.consume` for how to consume)
- *
- * Attribute `iconSet` can be set to either `momentum-icons` or `custom-icons`.
- * If `momentum-icons` is selected, the icons will be fetched from the
- * Momentum Design System icon set per a dynamic JS Import (no need to provide a URL).
- * This requires the consumer to have the `@momentum-design/icons` package installed and the
- * build tooling needs to support dynamic imports.
- *
- * If `custom-icons` is selected, the icons will be fetched from the provided URL.
- * This requires the consumer to provide a URL from which the icons will be fetched and
- * the consumer needs to make sure to bundle the icons in the application.
- *
- * If `cacheStrategy` is provided (only works with iconSet = `custom-icons`), the
- * IconProvider will cache the icons in the selected cache (either web-api-cache or in-memory-cache),
- * to avoid fetching the same icon multiple times over the network.
- * This is useful when the same icon is used multiple times in the application.
- * To consider:
- * - The `in-memory-cache` is not persisted and will be lost when the
- * IconProvider 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-iconprovider
  *
  * @slot - children

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

@@ -2,40 +2,24 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { IllustrationNames } from './illustration.types';
 /**
- * Illustration component that dynamically displays SVG illustrations based on a valid name.
- *
- * This component must be mounted within an `IllustrationProvider` component.
- *
- * The `IllustrationProvider` defines the source URL from which illustrations are consumed.
- * The `Illustration` component accepts a `name` attribute, which corresponds to
- * the file name of the illustration to be loaded from the specified URL.
- *
- * Once fetched, the illustration will be rendered. If the fetching process is unsuccessful,
- * no illustration will be displayed.
- *
- * Default sizing of the illustration is controlled by choosing a different illustration name, can be overridden with the `--mdc-illustration-size` CSS property.
- * Coloring of the illustration is currently baked into the svg, meaning that the illustration name determines
- * the coloring.
- *
- * Regarding accessibility, there are two types of illustrations: decorative and informative.
- *
- * ### Decorative Illustrations
- * - Decorative illustrations do not convey any essential information to the content of a page.
- * - They should be hidden from screen readers (SR) to prevent confusion for users.
- * - For decorative illustrations, an `aria-label` is not required, and the `role` will be set to null.
- *
- * ### Informative Illustrations
- * - Informative illustrations convey important information that is not adequately represented
- *   by surrounding text or components.
- * - They provide valuable context and must be announced by assistive technologies.
- * - For informative illustrations, an `aria-label` is required, and the `role` will be set to "img" automatically.
- * - If an `aria-label` is provided, the role will be set to 'img'; if it is absent,
- *   the role will be unset.
- *
+ * The illustration renders an SVG illustration by name. It must be mounted inside an `mdc-illustrationprovider`, which supplies the source URL (or selects the `momentum-illustrations` package), file extension, and optional cache strategy. Setting `name` triggers a fetch (or dynamic import); on success the SVG is inlined into the component, and on failure the component renders nothing.
+ * 
+ * Default sizing is baked into each illustration name. Override the rendered size with the `--mdc-illustration-size` CSS property. Colouring is also baked into the SVG, so the choice of `name` determines the palette.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-illustration` for larger illustrative graphics in empty states, onboarding screens, success/error confirmations, and feature highlights.
+ * - Use it when the asset should be loaded from the shared illustration source rather than bundled inline.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-icon` for small, single-colour interface icons rather than full illustrations.
+ * - Use an inline `<svg>` for one-off illustrations that do not need to be loaded through the illustration provider system.
+ * 
  * @tagname mdc-illustration
- *
+ * 
  * @cssproperty --mdc-illustration-size - Allows customization of the illustration size.
- *
+ * 
  * @csspart illustration - The svg inside the illustration element.
  */
 declare class Illustration extends Component {

package/dist/components/illustration/illustration.component.js

@@ -17,36 +17,6 @@ import styles from './illustration.styles';
 import { svgFetch } from './illustration.utils';
 import { DEFAULTS } from './illustration.constants';
 /**
- * Illustration component that dynamically displays SVG illustrations based on a valid name.
- *
- * This component must be mounted within an `IllustrationProvider` component.
- *
- * The `IllustrationProvider` defines the source URL from which illustrations are consumed.
- * The `Illustration` component accepts a `name` attribute, which corresponds to
- * the file name of the illustration to be loaded from the specified URL.
- *
- * Once fetched, the illustration will be rendered. If the fetching process is unsuccessful,
- * no illustration will be displayed.
- *
- * Default sizing of the illustration is controlled by choosing a different illustration name, can be overridden with the `--mdc-illustration-size` CSS property.
- * Coloring of the illustration is currently baked into the svg, meaning that the illustration name determines
- * the coloring.
- *
- * Regarding accessibility, there are two types of illustrations: decorative and informative.
- *
- * ### Decorative Illustrations
- * - Decorative illustrations do not convey any essential information to the content of a page.
- * - They should be hidden from screen readers (SR) to prevent confusion for users.
- * - For decorative illustrations, an `aria-label` is not required, and the `role` will be set to null.
- *
- * ### Informative Illustrations
- * - Informative illustrations convey important information that is not adequately represented
- *   by surrounding text or components.
- * - They provide valuable context and must be announced by assistive technologies.
- * - For informative illustrations, an `aria-label` is required, and the `role` will be set to "img" automatically.
- * - If an `aria-label` is provided, the role will be set to 'img'; if it is absent,
- *   the role will be unset.
- *
  * @tagname mdc-illustration
  *
  * @cssproperty --mdc-illustration-size - Allows customization of the illustration size.

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

@@ -2,31 +2,21 @@ import { Provider } from '../../models';
 import IllustrationProviderContext from './illustrationprovider.context';
 import type { CacheStrategy, IllustrationSet } from './illustrationprovider.types';
 /**
- * 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 class IllustrationProvider extends Provider<IllustrationProviderContext> {

package/dist/components/illustrationprovider/illustrationprovider.component.js

@@ -12,29 +12,6 @@ import { Provider } from '../../models';
 import IllustrationProviderContext from './illustrationprovider.context';
 import { ALLOWED_FILE_EXTENSIONS, DEFAULTS } from './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/components/input/input.component.d.ts

@@ -5,19 +5,24 @@ import { AssociatedFormControl } from '../../utils/mixins/FormInternalsMixin';
 import type { AutoCapitalizeType, AutoCompleteType, InputType } from './input.types';
 declare const Input_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/CharacterLimitMixin").CharacterLimitMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & import("../../utils/mixins/index.types").Constructor<import("../../models").Component & import("../../utils/mixins/AutoFocusOnMountMixin").AutoFocusOnMountMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FormInternalsMixin").FormInternalsMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & typeof FormfieldWrapper;
 /**
- * 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.
@@ -25,12 +30,12 @@ declare const Input_base: import("../../utils/mixins/index.types").Constructor<i
  * @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.
@@ -39,7 +44,7 @@ declare const Input_base: import("../../utils/mixins/index.types").Constructor<i
  * @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.
@@ -56,7 +61,7 @@ declare const Input_base: import("../../utils/mixins/index.types").Constructor<i
  * @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/components/input/input.component.js

@@ -21,17 +21,6 @@ import { CharacterLimitMixin } from '../../utils/mixins/CharacterLimitMixin';
 import { AUTO_CAPITALIZE, AUTO_COMPLETE, DEFAULTS, PREFIX_TEXT_OPTIONS } from './input.constants';
 import styles from './input.styles';
 /**
- * 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/components/inputchip/inputchip.component.d.ts

@@ -2,31 +2,37 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 declare const InputChip_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
 /**
- * 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 class InputChip extends InputChip_base {
     /**

package/dist/components/inputchip/inputchip.component.js

@@ -15,13 +15,6 @@ import { IconNameMixin } from '../../utils/mixins/IconNameMixin';
 import styles from './inputchip.styles';
 import { DEFAULTS } from './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/components/link/link.component.d.ts

@@ -3,23 +3,29 @@ import Linksimple from '../linksimple/linksimple.component';
 import type { LinkSize } from './link.types';
 declare const Link_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Linksimple;
 /**
- * `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/components/link/link.component.js

@@ -14,18 +14,10 @@ import Linksimple from '../linksimple/linksimple.component';
 import { DEFAULTS, LINK_ICON_SIZES, LINK_SIZES } from './link.constants';
 import styles from './link.styles';
 /**
- * `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/components/linkbutton/linkbutton.component.d.ts

@@ -3,25 +3,32 @@ import Buttonsimple from '../buttonsimple/buttonsimple.component';
 import type { LinkButtonSize } from './linkbutton.types';
 declare const LinkButton_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Buttonsimple;
 /**
- * `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/components/linkbutton/linkbutton.component.js

@@ -16,17 +16,10 @@ import { DEFAULTS, LINKBUTTON_SIZES } from './linkbutton.constants';
 import { getIconSize } from './linkbutton.utils';
 import styles from './linkbutton.styles';
 /**
- * `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/components/linksimple/linksimple.component.d.ts

@@ -2,20 +2,27 @@ import { PropertyValues, CSSResult } from 'lit';
 import { Component } from '../../models';
 declare const Linksimple_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
 /**
- * `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 @@ declare const Linksimple_base: import("../../utils/mixins/index.types").Construc
  * @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 class Linksimple extends Linksimple_base {

package/dist/components/linksimple/linksimple.component.js

@@ -16,13 +16,6 @@ import { DisabledMixin } from '../../utils/mixins/DisabledMixin';
 import { DEFAULTS } from './linksimple.constants';
 import styles from './linksimple.styles';
 /**
- * `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/components/list/list.component.d.ts

@@ -6,16 +6,26 @@ import type { BaseArray } from '../../utils/virtualIndexArray';
 import type { OrientationType } from './list.types';
 declare const List_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;
 /**
- * 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 class List extends List_base {

package/dist/components/list/list.component.js

@@ -20,11 +20,6 @@ import { ACTIONS } from '../../utils/mixins/KeyToActionMixin';
 import styles from './list.styles';
 import { DEFAULTS } from './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.