@momentum-design/components 0.134.20 → 0.134.22

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

@@ -4,52 +4,37 @@ import { StackChange, type StackedOverlayComponent } from '../../utils/controlle
 import type { DialogRole, DialogSize, DialogVariant } from './dialog.types';
 declare const Dialog_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/BackdropMixin").BackdropMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/PreventScrollMixin").PreventScrollMixinInterface> & import("../../utils/mixins/index.types").Constructor<Component & import("../../utils/mixins/focus/FocusTrapMixin").FocusTrapClassInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FooterMixin").FooterMixinInterface> & typeof Component;
 /**
- * Dialog component is a modal dialog that can be used to display information or prompt the user for input.
- * It can be used to create custom dialogs where content for the body and footer actions is provided by the consumer.
- * The dialog is available in 5 sizes: small, medium, large, xlarge and fullscreen. It may also receive custom styling/sizing.
- * The dialog interrupts the user and will block interaction with the rest of the application until it is closed.
- *
- * Dialog component have 2 variants: default and promotional.
- *
- * ## Visibility
- *
- * The dialog can be controlled solely through the `visible` property, no trigger element is required.
- * If a `triggerID` is provided, the dialog will manage focus with that element, otherwise it will
- * remember the previously focused element before the dialog was opened.
- *
- * The dialog is a controlled component, meaning it does not have its own state management for visibility.
- * Use the `visible` property to control the visibility of the dialog.
- * Use the `onClose` event to handle the close action of the dialog (fired when Close button is clicked
- * or Escape is pressed).
- *
- * ## Accessibility
- *
- * Some attributes have to be explicitly set by the consumer of the component:
- *
- * - The dialog should have an aria-label or aria-labelledby attribute to provide a label for screen readers.
- * - Use aria-labelledby to reference the ID of the element that labels the dialog when there is no visible title.
- *
- * ## Responsive design
- *
- * Dialog has few built in logic to prevent content clipping on small screens
- *
- * - maximum height limited to the viewport height
- * - dialog body has `overflow: auto` by default
- * - dialog itself also has `overflow: auto`, it activates only when the body can not shrink more
- *
- *
+ * A dialog is a modal surface that interrupts the user to display information, confirm a destructive action, or collect input. It blocks interaction with the rest of the application until it is closed.
+ * 
+ * The dialog is a controlled component: the consumer drives visibility through the `visible` property and listens to the `close` event to react to the user dismissing the dialog. Visibility is not toggled internally.
+ * 
+ * Five sizes are available: `small` (432px), `medium` (656px), `large` (992px), `xlarge` (90% viewport), and `fullscreen` (100% viewport). Two visual variants are available: `default` and `promotional`. When the surrounding `mdc-responsivesettingsprovider` has `forceFullscreenDialog` enabled, every dialog is rendered as `fullscreen` regardless of its `size`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-dialog` to confirm a destructive action (e.g. deleting an item) before it happens.
+ * - Use it to collect a short input that should block the underlying flow until completed.
+ * - Use it for messages that demand the user's attention and cannot be deferred to a banner or toast.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-announcementdialog` when the surface is a curated marketing/announcement layout with a fixed structure.
+ * - Use `mdc-popover` or `mdc-coachmark` for non-modal overlays anchored to a trigger.
+ * - Use `mdc-toast` for transient, dismissable notifications that should not block interaction.
+ * - Use `mdc-banner` for persistent in-page messages.
+ * 
+ * @tagname mdc-dialog
+ * 
  * @dependency mdc-button
  * @dependency mdc-text
- *
- * @tagname mdc-dialog
- *
+ * 
  * @event shown - (React: onShown) Dispatched when the dialog is shown
  * @event hidden - (React: onHidden) Dispatched when the dialog is hidden
  * @event created - (React: onCreated) Dispatched when the dialog is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) Dispatched when the dialog is destroyed (removed from the DOM)
  * @event close - (React: onClose) Dispatched when the Close Button is clicked or Escape key is pressed
  * (this does not hide the dialog)
- *
+ * 
  * @cssproperty --mdc-dialog-primary-background-color - primary background color of the dialog
  * @cssproperty --mdc-dialog-border-color - border color of the dialog
  * @cssproperty --mdc-dialog-header-text-color - text color of the header/title of the dialog
@@ -58,14 +43,14 @@ declare const Dialog_base: import("../../utils/mixins/index.types").Constructor<
  * @cssproperty --mdc-dialog-width - width of the dialog
  * @cssproperty --mdc-dialog-height - height of the dialog
  * @cssproperty --mdc-dialog-backdrop-color - background color of the backdrop (if backdrop is enabled)
- *
+ * 
  * @csspart body - The body section of the dialog.
  * @csspart description-text - The description text of the dialog.
  * @csspart dialog-close-btn - The close button of the dialog.
  * @csspart header - The header of the dialog.
  * @csspart header-section - The header section of the dialog.
  * @csspart header-text - The header text of the dialog.
- *
+ * 
  * @slot header-prefix - Slot for the dialog header content. This can be used to pass custom header content.
  * @slot dialog-body - Slot for the dialog body content
  * @slot footer-link - This slot is for passing `mdc-link` component within the footer section.

package/dist/components/dialog/dialog.component.js

@@ -26,45 +26,11 @@ import { DEFAULTS } from './dialog.constants';
 import { DialogEventManager } from './dialog.events';
 import styles from './dialog.styles';
 /**
- * Dialog component is a modal dialog that can be used to display information or prompt the user for input.
- * It can be used to create custom dialogs where content for the body and footer actions is provided by the consumer.
- * The dialog is available in 5 sizes: small, medium, large, xlarge and fullscreen. It may also receive custom styling/sizing.
- * The dialog interrupts the user and will block interaction with the rest of the application until it is closed.
- *
- * Dialog component have 2 variants: default and promotional.
- *
- * ## Visibility
- *
- * The dialog can be controlled solely through the `visible` property, no trigger element is required.
- * If a `triggerID` is provided, the dialog will manage focus with that element, otherwise it will
- * remember the previously focused element before the dialog was opened.
- *
- * The dialog is a controlled component, meaning it does not have its own state management for visibility.
- * Use the `visible` property to control the visibility of the dialog.
- * Use the `onClose` event to handle the close action of the dialog (fired when Close button is clicked
- * or Escape is pressed).
- *
- * ## Accessibility
- *
- * Some attributes have to be explicitly set by the consumer of the component:
- *
- * - The dialog should have an aria-label or aria-labelledby attribute to provide a label for screen readers.
- * - Use aria-labelledby to reference the ID of the element that labels the dialog when there is no visible title.
- *
- * ## Responsive design
- *
- * Dialog has few built in logic to prevent content clipping on small screens
- *
- * - maximum height limited to the viewport height
- * - dialog body has `overflow: auto` by default
- * - dialog itself also has `overflow: auto`, it activates only when the body can not shrink more
- *
+ * @tagname mdc-dialog
  *
  * @dependency mdc-button
  * @dependency mdc-text
  *
- * @tagname mdc-dialog
- *
  * @event shown - (React: onShown) Dispatched when the dialog is shown
  * @event hidden - (React: onHidden) Dispatched when the dialog is hidden
  * @event created - (React: onCreated) Dispatched when the dialog is created (added to the DOM)

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

@@ -3,31 +3,29 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { Directions, DividerOrientation, DividerVariant } from './divider.types';
 /**
- * The Divider component provides a visual line to separate and organize content within layouts.
- * It supports both horizontal and vertical orientations with solid or gradient styles, and can
- * optionally include centered text labels or interactive grabber buttons.
- *
- * The divider automatically infers its type based on the content in its slot:
- * - **Primary**: Simple line with no content
- * - **Text**: Horizontal line with centered text label
- * - **Grabber Button**: Line with centered interactive button
- *
- * **Note:**
- * - Vertical text dividers are not currently supported.
- * - If the slot contains invalid tag names or multiple elements, the divider defaults to the Primary type
- * - Use the provided CSS custom properties to customize divider styles
- *
- * ## When to use
- * Use dividers to create visual separation between content sections, list items, or layout regions.
- * Add text labels to provide context, or grabber buttons to create resizable panes.
- *
- * ## Accessibility
- * - When using a grabber button, provide `aria-label` to describe its purpose
- * - Set `aria-expanded` on the button to indicate the current state of resizable sections
- * - Ensure sufficient color contrast for the divider line
- *
+ * The divider draws a thin separator line between sections of a layout. It supports both horizontal and vertical orientations and two visual variants — `solid` (uniform colour) and `gradient` (fades on both ends).
+ * 
+ * The component infers its type from the slotted content:
+ * 
+ * - **Primary** — no slotted content; renders just the line.
+ * - **Text** — a single `mdc-text` child; renders the line with a centred label.
+ * - **Grabber Button** — a single `mdc-button` child; renders the line with a centred interactive button (typically used to collapse/expand a resizable pane).
+ * 
+ * If the slot contains multiple elements or unrecognised tag names, the divider falls back to the primary type.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-divider` to separate sections of content within a layout, list, or table.
+ * - Use a text divider to add a short caption between two visually similar sections.
+ * - Use a grabber-button divider to create a resizable boundary between two panes.
+ * 
+ * **When not to use**
+ * 
+ * - Use whitespace, padding, or background-colour groupings when a visible line is not needed — a divider should add meaning, not decoration.
+ * - Use `mdc-list` separators rather than nesting dividers inside list items, since lists already render their own dividers.
+ * 
  * @tagname mdc-divider
- *
+ * 
  * @cssproperty --mdc-divider-background-color - Background color of the divider line.
  * @cssproperty --mdc-divider-width - Width (thickness) of the divider line.
  * @cssproperty --mdc-divider-horizontal-gradient - Gradient for horizontal dividers.
@@ -41,7 +39,7 @@ import type { Directions, DividerOrientation, DividerVariant } from './divider.t
  * @cssproperty --mdc-divider-grabber-button-background-color-pressed - Background color of the grabber button in pressed state.
  * @cssproperty --mdc-divider-grabber-button-border-color - Border color of the grabber button.
  * @cssproperty --mdc-divider-grabber-button-border-radius - Border radius of the grabber button.
- *
+ * 
  * @slot - Content for the divider. Use `mdc-text` for text labels or `mdc-button` for grabber buttons.
  */
 declare class Divider extends Component {

package/dist/components/divider/divider.component.js

@@ -13,29 +13,6 @@ import { Component } from '../../models';
 import { ARROW_ICONS, BUTTON_TAG, DEFAULTS, DIRECTIONS, DIVIDER_ORIENTATION, DIVIDER_VARIANT, TEXT_TAG, } from './divider.constants';
 import styles from './divider.styles';
 /**
- * The Divider component provides a visual line to separate and organize content within layouts.
- * It supports both horizontal and vertical orientations with solid or gradient styles, and can
- * optionally include centered text labels or interactive grabber buttons.
- *
- * The divider automatically infers its type based on the content in its slot:
- * - **Primary**: Simple line with no content
- * - **Text**: Horizontal line with centered text label
- * - **Grabber Button**: Line with centered interactive button
- *
- * **Note:**
- * - Vertical text dividers are not currently supported.
- * - If the slot contains invalid tag names or multiple elements, the divider defaults to the Primary type
- * - Use the provided CSS custom properties to customize divider styles
- *
- * ## When to use
- * Use dividers to create visual separation between content sections, list items, or layout regions.
- * Add text labels to provide context, or grabber buttons to create resizable panes.
- *
- * ## Accessibility
- * - When using a grabber button, provide `aria-label` to describe its purpose
- * - Set `aria-expanded` on the button to indicate the current state of resizable sections
- * - Ensure sufficient color contrast for the divider line
- *
  * @tagname mdc-divider
  *
  * @cssproperty --mdc-divider-background-color - Background color of the divider line.

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

@@ -1,22 +1,33 @@
 import { CSSResult, PropertyValues } from 'lit';
 import Chip from '../chip/chip.component';
 /**
- * mdc-filterchip component is an interactive chip that consumers can use to select or deselect.
- * They can be found with lists or tables as quick filters.
- *
- * This component is built on top of the mdc-chip component.
- *
+ * The filterchip is a compact, togglable chip used to represent a single filter in a list, table, or search context. Activating the chip flips its `selected` state and the component swaps its leading icon to a checkmark to indicate the active filter.
+ * 
+ * Filterchips are typically rendered in a horizontal row next to a result set; users toggle them on and off to narrow the set.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-filterchip` when each chip toggles a single filter that can be applied or removed independently.
+ * - Use it inside a row of filters where the selected state should be visually obvious at a glance.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-chip` when the chip triggers an action rather than a toggle.
+ * - Use `mdc-alertchip` when the chip communicates a status (information, warning, error) rather than a togglable filter.
+ * - Use `mdc-staticchip` when the chip is purely decorative and should not be interactive.
+ * - Use `mdc-checkbox` or `mdc-radio` when the control should appear inside a form field group rather than as a compact filter row.
+ * 
  * @tagname mdc-filterchip
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @csspart label - The label 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.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the chip is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the chip.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the chip.

package/dist/components/filterchip/filterchip.component.js

@@ -12,11 +12,6 @@ import Chip from '../chip/chip.component';
 import styles from './filterchip.styles';
 import { DEFAULTS } from './filterchip.constants';
 /**
- * mdc-filterchip component is an interactive chip that consumers can use to select or deselect.
- * They can be found with lists or tables as quick filters.
- *
- * This component is built on top of the mdc-chip component.
- *
  * @tagname mdc-filterchip
  *
  * @dependency mdc-icon

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

@@ -1,34 +1,33 @@
 import type { CSSResult } from 'lit';
 import FormfieldWrapper from '../formfieldwrapper/formfieldwrapper.component';
 /**
- * `mdc-formfieldgroup` component, groups the form field components together.
- * All passed in children will have a gap of 12px (0.75rem) each applied.
- *
- * This component is specifically for creating a `checkbox` group and a `toggle` group component.
- * For the radiogroup use the RadioGroup component instead.
- *
- * The header text and description text are displayed above the items with accessible labels.<br/>
- * The consumer has to provide atleast the header-text or the aria-label,
- * like one of them <b>has</b> to be passed in always, otherwise its not accessible.
- *
- * The role will be set to `group`.
- * The aria-label will be set with the data-aria-label property.
- * The aria-labelledby will be set with the header id which contains the header text information.
- * The aria-describedby will be set with the description id which contains the description text information.
- *
+ * The formfieldgroup groups several related form fields under a single shared label, helper text, and group role. It is intended for checkbox groups and toggle groups; each child is rendered with a 12px (0.75rem) gap between siblings.
+ * 
+ * The group is announced to screen readers as a single semantic unit via `role="group"`, with the header text and helper text wired as the accessible name and description.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-formfieldgroup` to wrap a set of related `mdc-checkbox` controls so they share a single label and helper text.
+ * - Use it to wrap a set of related `mdc-toggle` controls in the same way.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-radiogroup` for radio buttons — radios require the `radiogroup` role and arrow-key navigation, which `mdc-formfieldgroup` does not provide.
+ * - Use `mdc-formfieldwrapper` for a single labelled form field rather than a group.
+ * 
  * @tagname mdc-formfieldgroup
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
+ * 
  * @slot default - This is a default slot for checkbox or toggle components.
  * @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.
  * @slot help-text - Slot for the helper/validation text. If not provided, the `helpText` property will be used to render the helper/validation 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.
@@ -38,7 +37,7 @@ import FormfieldWrapper from '../formfieldwrapper/formfieldwrapper.component';
  * @csspart helper-icon - The helper/validation icon element that is displayed next to the helper/validation text.
  * @csspart help-text-container - The container for the helper/validation icon and text elements.
  * @csspart group-header - This contains the label and help text for the group
- *
+ * 
  * @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.

package/dist/components/formfieldgroup/formfieldgroup.component.js

@@ -3,21 +3,6 @@ import { ROLE } from '../../utils/roles';
 import FormfieldWrapper from '../formfieldwrapper/formfieldwrapper.component';
 import styles from './formfieldgroup.styles';
 /**
- * `mdc-formfieldgroup` component, groups the form field components together.
- * All passed in children will have a gap of 12px (0.75rem) each applied.
- *
- * This component is specifically for creating a `checkbox` group and a `toggle` group component.
- * For the radiogroup use the RadioGroup component instead.
- *
- * The header text and description text are displayed above the items with accessible labels.<br/>
- * The consumer has to provide atleast the header-text or the aria-label,
- * like one of them <b>has</b> to be passed in always, otherwise its not accessible.
- *
- * The role will be set to `group`.
- * The aria-label will be set with the data-aria-label property.
- * The aria-labelledby will be set with the header id which contains the header text information.
- * The aria-describedby will be set with the description id which contains the description text information.
- *
  * @tagname mdc-formfieldgroup
  *
  * @dependency mdc-button

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

@@ -4,22 +4,30 @@ import type { PopoverPlacement, PopoverStrategy } from '../popover/popover.types
 import type { ValidationType } from './formfieldwrapper.types';
 declare const FormfieldWrapper_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
 /**
- * formfieldwrapper is a component that contains the label and helper/validation text
- *  that can be configured in various ways to suit different use cases (most of the input related components).
- * It is used as an internal component and is not intended to be used directly by consumers.
- *
+ * The formfieldwrapper is an internal base component that renders the label row (label, required indicator, optional info-icon toggletip) and the helper/validation row (icon + text) used by every form field. It is **not** intended to be instantiated directly by consumers — components such as `mdc-input`, `mdc-textarea`, `mdc-checkbox`, `mdc-radio`, `mdc-select`, `mdc-combobox`, `mdc-datepicker`, `mdc-formfieldgroup`, and others extend it to inherit a consistent label and helper-text contract.
+ * 
+ * This entry documents the properties, slots, and accessibility hooks that every extending component exposes to consumers. Consumers will interact with these via the concrete form-field component (e.g. set `label` on an `mdc-input`), not on `mdc-formfieldwrapper` itself.
+ * 
+ * **When to use**
+ * 
+ * - Use the formfieldwrapper indirectly by extending it from a new form-field component that needs the standard label, required indicator, helper text, and toggletip layout.
+ * 
+ * **When not to use**
+ * 
+ * - Do not render `mdc-formfieldwrapper` directly in application code — pick the concrete form-field component (`mdc-input`, `mdc-textarea`, `mdc-checkbox`, etc.) instead.
+ * 
  * @tagname mdc-formfieldwrapper
- *
+ * 
  * @dependency mdc-text
  * @dependency mdc-icon
  * @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.
  * @slot help-text - Slot for the helper/validation text. If not provided, the `helpText` property will be used to render the helper/validation 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.
@@ -28,7 +36,7 @@ declare const FormfieldWrapper_base: import("../../utils/mixins/index.types").Co
  * @csspart help-text - The helper/validation text element.
  * @csspart helper-icon - The helper/validation icon element that is displayed next to the helper/validation text.
  * @csspart help-text-container - The container for the helper/validation icon and text elements.
- *
+ * 
  * @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.

package/dist/components/formfieldwrapper/formfieldwrapper.component.js

@@ -18,10 +18,6 @@ import { DEFAULTS, MDC_TEXT_OPTIONS } from './formfieldwrapper.constants';
 import styles from './formfieldwrapper.styles';
 import { getHelperIcon } from './formfieldwrapper.utils';
 /**
- * formfieldwrapper is a component that contains the label and helper/validation text
- *  that can be configured in various ways to suit different use cases (most of the input related components).
- * It is used as an internal component and is not intended to be used directly by consumers.
- *
  * @tagname mdc-formfieldwrapper
  *
  * @dependency mdc-text

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

@@ -2,51 +2,26 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 import type { IconNames } from './icon.types';
 /**
- * Icon component that dynamically displays SVG icons based on a valid name.
- *
- * This component must be mounted within an `IconProvider` component.
- *
- * The `IconProvider` defines the source URL from which icons are consumed.
- * The `Icon` component accepts a `name` attribute, which corresponds to
- * the file name of the icon to be loaded from the specified URL.
- *
- * Once fetched, the icon will be rendered. If the fetching process is unsuccessful,
- * no icon will be displayed.
- *
- * The `size` attribute allows for dynamic sizing of the icon based on the provided
- * `length-unit` attribute. This unit can either come from the `IconProvider`
- * or can be overridden for each individual icon. For example:
- * if `size = 1` and `length-unit = 'em'`, the dimensions of the icon will be
- * `width: 1em; height: 1em`.
- *
- * Regarding accessibility, there are three types of icons: decorative, informative and informative standalone.
- *
- * ### Decorative Icons
- * - Decorative icons 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 icons, an `aria-label` is not required, and the `role` will be set to null.
- *
- * ### Informative Icons
- * - Informative icons 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 icons, 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.
- *
- * ### Informative Standalone Icons
- * - If an icon is informative (as mentioned above) and does not belong to a button (=standalone), it must
- * have a Tooltip that describes what it means.
- * - For informative standalone icons, an `aria-label` & `tabindex="0"` is required,
- * and the `role` will be set to "img" automatically.
- * - **Only use this when a Icon is standalone and is not part of a button or other interactive elements.**
- *
+ * The icon renders an SVG by name. It must be mounted inside an `mdc-iconprovider`, which supplies the source URL (or selects the `momentum-icons` package), file extension, default size, and length unit. Setting `name` triggers a fetch (or dynamic import) for that icon; on success the SVG is inlined into the component, and on failure the component renders nothing.
+ * 
+ * The size is computed from the `size` and `length-unit` attributes, with fallbacks to the values broadcast by `mdc-iconprovider`. The accessibility contract depends on whether the icon is decorative, informative, or informative-standalone — see the Accessibility section.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-icon` inside any component or layout that needs a Momentum design-system icon.
+ * - Use it when the icon source is shared across the app — the surrounding `mdc-iconprovider` configures it once.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-illustration` when the asset is a larger illustrative graphic rather than a simple, single-colour icon.
+ * - Use an inline `<svg>` when the icon is a one-off graphic that does not need to be loaded through the icon provider system.
+ * 
  * @tagname mdc-icon
- *
+ * 
  * @cssproperty --mdc-icon-fill-color - Allows customization of the default fill color.
  * @cssproperty --mdc-icon-size - Allows customization of the icon size.
  * @cssproperty --mdc-icon-border-radius - Allows customization of the icon border radius.
- *
+ * 
  * @csspart icon - The svg inside the icon element.
  */
 declare class Icon extends Component {

package/dist/components/icon/icon.component.js

@@ -16,45 +16,6 @@ import styles from './icon.styles';
 import { svgFetch } from './icon.utils';
 import { DEFAULTS } from './icon.constants';
 /**
- * Icon component that dynamically displays SVG icons based on a valid name.
- *
- * This component must be mounted within an `IconProvider` component.
- *
- * The `IconProvider` defines the source URL from which icons are consumed.
- * The `Icon` component accepts a `name` attribute, which corresponds to
- * the file name of the icon to be loaded from the specified URL.
- *
- * Once fetched, the icon will be rendered. If the fetching process is unsuccessful,
- * no icon will be displayed.
- *
- * The `size` attribute allows for dynamic sizing of the icon based on the provided
- * `length-unit` attribute. This unit can either come from the `IconProvider`
- * or can be overridden for each individual icon. For example:
- * if `size = 1` and `length-unit = 'em'`, the dimensions of the icon will be
- * `width: 1em; height: 1em`.
- *
- * Regarding accessibility, there are three types of icons: decorative, informative and informative standalone.
- *
- * ### Decorative Icons
- * - Decorative icons 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 icons, an `aria-label` is not required, and the `role` will be set to null.
- *
- * ### Informative Icons
- * - Informative icons 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 icons, 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.
- *
- * ### Informative Standalone Icons
- * - If an icon is informative (as mentioned above) and does not belong to a button (=standalone), it must
- * have a Tooltip that describes what it means.
- * - For informative standalone icons, an `aria-label` & `tabindex="0"` is required,
- * and the `role` will be set to "img" automatically.
- * - **Only use this when a Icon is standalone and is not part of a button or other interactive elements.**
- *
  * @tagname mdc-icon
  *
  * @cssproperty --mdc-icon-fill-color - Allows customization of the default fill color.

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

@@ -2,31 +2,21 @@ import { Provider } from '../../models';
 import IconProviderContext from './iconprovider.context';
 import type { CacheStrategy, IconSet } from './iconprovider.types';
 /**
- * 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).
- *
+ * The iconprovider is a context provider for `mdc-icon`. It broadcasts the configuration every nested icon needs to resolve its `name` into a rendered SVG: which icon set to use, where to fetch from (for custom icons), what file extension to apply, the default size and length unit, and an optional cache strategy.
+ * 
+ * Wrap the application (or a sub-tree) with an `mdc-iconprovider` once; every `mdc-icon` inside it reads the same configuration via context. Without a surrounding iconprovider, an `mdc-icon` cannot resolve its source and renders nothing.
+ * 
+ * **When to use**
+ * 
+ * - Wrap the root of the application (or any sub-tree that uses icons) with `mdc-iconprovider` to configure the icon source for all nested `mdc-icon` components in one place.
+ * - Use it when icons should be cached across re-renders or page navigations to avoid repeated network fetches.
+ * 
+ * **When not to use**
+ * 
+ * - Do not nest multiple `mdc-iconprovider`s when one provider is enough — the nearest provider wins per icon, so nesting only makes sense when different sub-trees genuinely need different sources.
+ * 
  * @tagname mdc-iconprovider
- *
+ * 
  * @slot - children
  */
 declare class IconProvider extends Provider<IconProviderContext> {