@momentum-design/components 0.134.20 → 0.134.21

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

@@ -1,30 +1,28 @@
 import Component from '../../components/divider';
 /**
- * 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.
@@ -38,7 +36,7 @@ import Component from '../../components/divider';
  * @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 const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/divider/index.js

@@ -3,29 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/divider';
 import { TAG_NAME } from '../../components/divider/divider.constants';
 /**
- * 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/react/filterchip/index.d.ts

@@ -2,22 +2,33 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/filterchip';
 import type { Events as EventsInherited } from '../../components/buttonsimple/buttonsimple.types';
 /**
- * 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/react/filterchip/index.js

@@ -3,11 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/filterchip';
 import { TAG_NAME } from '../../components/filterchip/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/react/formfieldgroup/index.d.ts

@@ -1,33 +1,32 @@
 import Component from '../../components/formfieldgroup';
 /**
- * `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.
@@ -37,7 +36,7 @@ import Component from '../../components/formfieldgroup';
  * @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/react/formfieldgroup/index.js

@@ -3,21 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/formfieldgroup';
 import { TAG_NAME } from '../../components/formfieldgroup/formfieldgroup.constants';
 /**
- * `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/react/formfieldwrapper/index.d.ts

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

@@ -3,10 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/formfieldwrapper';
 import { TAG_NAME } from '../../components/formfieldwrapper/formfieldwrapper.constants';
 /**
- * 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/react/icon/index.d.ts

@@ -1,50 +1,25 @@
 import Component from '../../components/icon';
 /**
- * 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 const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/icon/index.js

@@ -3,45 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/icon';
 import { TAG_NAME } from '../../components/icon/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/react/iconprovider/index.d.ts

@@ -1,30 +1,20 @@
 import Component from '../../components/iconprovider';
 /**
- * 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 const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/iconprovider/index.js

@@ -3,29 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/iconprovider';
 import { TAG_NAME } from '../../components/iconprovider/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/react/illustration/index.d.ts

@@ -1,39 +1,23 @@
 import Component from '../../components/illustration';
 /**
- * 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 const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/illustration/index.js

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