@momentum-design/components 0.134.20 → 0.134.22

package/dist/react/popover/index.js

@@ -3,56 +3,10 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/popover';
 import { TAG_NAME } from '../../components/popover/popover.constants';
 /**
- * Popover is generic overlay which can be triggered by any actionable element.
- *
- * It can be used for tooltips, dropdowns, menus or any showing any other contextual content.
- *
- * The popover automatically positions itself based on available space and
- * supports dynamic height adjustments with scrollable content when needed.
- * It uses [Floating UI](https://floating-ui.com/) for maintaining the position of the popover.
- *
- * ## Limitations
- *
- * ### On trigger for multiple popovers
- *
- * A component (button, etc.) can trigger more than one popover, but only one of them should change the
- * aria-expanded and aria-haspopup attributes on the trigger.
- *
- * To prevent unexpected attribute changes on the trigger `disable-aria-expanded` attribute must be set on all linked
- * Popovers except one.
- *
- * ### React Popover with append-to attribute
- *
- * React mounts the popover based on the virtual DOM, but when the append-to attribute is set, the popover removes itself
- * and mounts to the specified element. React will not know about the move and will not know about the
- * newly created mdc-popoverportal element either. This throws a `NotFoundError` error when the Popover is directly
- * added/removed by React, for example:
- *
- * ```tsx
- * const SomeComponent = () => {
- *    const [isOpen, setIsOpen] = useState(false);
- *    return (<div>
- *      {isOpen && <Popover append-to="some-element-id">...</mdc-popover>}
- *    </div>);
- * }
- * ```
- * As a workaround Popover need to wrap with any other element/component, for example:
- * ```tsx
- * const SomeComponent = () => {
- *    const [isOpen, setIsOpen] = useState(false);
- *    return (<div>
- *      {isOpen && <div>
- *        <Popover append-to="some-element-id">...</mdc-popover>
- *      <div>}
- *    </div>);
- * }
- * ```
- * Note the wrapper <div> around the Popover component (React.Fragment does not work).
+ * @tagname mdc-popover
  *
  * @dependency mdc-button
  *
- * @tagname mdc-popover
- *
  * @event shown - (React: onShown) This event is dispatched when the popover is shown
  * @event hidden - (React: onHidden) This event is dispatched when the popover is hidden
  * @event created - (React: onCreated) This event is dispatched when the popover is created (added to the DOM)

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

@@ -1,15 +1,22 @@
 import Component from '../../components/presence';
 /**
- * The `mdc-presence` component is a versatile UI element used to
- * display the presence status of a user or entity within an avatar component.
- *
- * This component is ideal for use within avatar UIs where the presence status
- * needs to be visually represented.
- *
- * @dependency mdc-icon
- *
+ * The presence is a small status badge that visually represents the availability or activity state of a user or entity (for example: active, away, busy, do-not-disturb, on a call, presenting). It is sized to be paired with an avatar so the status renders as a corner indicator on top of the avatar artwork.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-presence` next to or on top of an `mdc-avatar` to indicate the represented user/entity's current availability or activity.
+ * - Use it whenever the application has a meaningful status signal to communicate alongside an avatar (online, in a meeting, away, etc.).
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it as a standalone status indicator divorced from an avatar — pair it with `mdc-avatar` so the icon size matches the avatar size.
+ * - Use `mdc-badge` for counts, dots, or non-status decorations.
+ * - Use `mdc-icon` if you need an arbitrary icon at custom sizes outside the supported avatar size set.
+ * 
  * @tagname mdc-presence
- *
+ * 
+ * @dependency mdc-icon
+ * 
  * @cssproperty --mdc-presence-active-background-color - The background color of the presence type active.
  * @cssproperty --mdc-presence-away-background-color - The background color of the presence type away.
  * @cssproperty --mdc-presence-away-calling-background-color - The background color of the presence type away-calling.
@@ -25,7 +32,7 @@ import Component from '../../components/presence';
  * @cssproperty --mdc-presence-quiet-background-color - The background color of the presence type quiet.
  * @cssproperty --mdc-presence-scheduled-background-color - The background color of the presence type scheduled.
  * @cssproperty --mdc-presence-overlay-background-color - The background color of the presence type overlay.
- *
+ * 
  * @csspart presence-content - The presence content.
  * @csspart mdc-presence-icon - The presence icon.
  * @csspart mdc-presence-icon__active - The presence icon for active.

package/dist/react/presence/index.js

@@ -3,16 +3,10 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/presence';
 import { TAG_NAME } from '../../components/presence/presence.constants';
 /**
- * The `mdc-presence` component is a versatile UI element used to
- * display the presence status of a user or entity within an avatar component.
- *
- * This component is ideal for use within avatar UIs where the presence status
- * needs to be visually represented.
+ * @tagname mdc-presence
  *
  * @dependency mdc-icon
  *
- * @tagname mdc-presence
- *
  * @cssproperty --mdc-presence-active-background-color - The background color of the presence type active.
  * @cssproperty --mdc-presence-away-background-color - The background color of the presence type away.
  * @cssproperty --mdc-presence-away-calling-background-color - The background color of the presence type away-calling.

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

@@ -1,27 +1,31 @@
 import Component from '../../components/progressbar';
 /**
- * mdc-progressbar component visually represents a progress indicator, typically used to show
- * the completion state of an ongoing process (e.g., loading, file upload, etc.).
- * It contains an optional label and an optional helper text.
- *
- * - It supports mainly two types: Default and Inline
- * - It supports three validation variants: Default, Success and Error.
- *
- * This component is created by extending FormfieldWrapper.
- *
+ * The progressbar is a determinate, linear progress indicator that visually represents the completion state of an ongoing process (loading, uploading, syncing, etc.). It renders an optional label, an optional helper/validation text, and a coloured bar that fills from 0 to 100 percent.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-progressbar` for a determinate task whose completion percentage is known.
+ * - Use the `default` variant when the progressbar should stand on its own with a label above it and a percentage readout.
+ * - Use the `inline` variant when the progressbar must sit on a single line next to its label (e.g. inside a list row).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-progressspinner` for a circular determinate indicator (for example to indicate progress in a compact area or to surface a completion/error glyph at 100%).
+ * - Use `mdc-spinner` for an indeterminate "work in progress" state where no percentage is known.
+ * 
  * @tagname mdc-progressbar
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @slot label - Slot for the label element. If not provided, the `label` property will be used to render the label.
  * @slot help-icon - Slot for the helper/validation icon. If not provided, the icon will be rendered based on the `helpTextType` property.
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart help-text - The helper/validation text element.
  * @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/progressbar/index.js

@@ -3,15 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/progressbar';
 import { TAG_NAME } from '../../components/progressbar/progressbar.constants';
 /**
- * mdc-progressbar component visually represents a progress indicator, typically used to show
- * the completion state of an ongoing process (e.g., loading, file upload, etc.).
- * It contains an optional label and an optional helper text.
- *
- * - It supports mainly two types: Default and Inline
- * - It supports three validation variants: Default, Success and Error.
- *
- * This component is created by extending FormfieldWrapper.
- *
  * @tagname mdc-progressbar
  *
  * @dependency mdc-icon

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

@@ -1,30 +1,25 @@
 import Component from '../../components/progressspinner';
 /**
- * `mdc-progressspinner` is a customizable, circular progress indicator component.
- * It visually represents the current completion state of a process, such as loading,
- * syncing, uploading, or any ongoing task that has a measurable percentage.
- *
- * The spinner is built using SVG with two concentric `<circle>` elements:
- * - The `progress` arc represents the portion of work completed.
- * - The `track` arc represents the remaining part.
- *
- * A visual gap is maintained between the progress and track arcs to clearly
- * distinguish the two segments. The component smoothly animates arc length
- * and respects accessibility best practices with ARIA attributes.
- *
- * The component supports different states:
- * - **Default**: Circular spinner shows the progress.
- * - **Success**: Displays a checkmark icon when progress reaches 100%.
- * - **Error**: Displays an error icon when in an error state.
- *
+ * The progressspinner is a determinate, circular progress indicator built from two concentric SVG arcs — one representing completed work and one representing remaining work. When the value reaches 100 the spinner is replaced by a check-circle success icon; when the component is in an error state it is replaced by an error icon.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-progressspinner` for a determinate task whose completion percentage is known and where a compact, circular indicator fits better than a linear bar.
+ * - Use it when the final state should be communicated with a clear success or error glyph rather than a filled bar.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-progressbar` when a linear bar with an explicit percentage readout and label is more appropriate.
+ * - Use `mdc-spinner` for an indeterminate spinner where no percentage is known.
+ * 
  * @tagname mdc-progressspinner
- *
+ * 
  * @cssproperty --mdc-spinner-size - The size of the spinner.
  * @cssproperty --mdc-track-color - The color of the spinner track.
  * @cssproperty --mdc-progress-color - The color of the spinner progress.
  * @cssproperty --mdc-progress-success-color - The color of the spinner when in success state.
  * @cssproperty --mdc-progress-error-color - The color of the spinner when in error state.
- *
+ * 
  * @csspart error-icon - The error icon of the progressspinner.
  * @csspart spinner-base - The base of the progressspinner.
  * @csspart spinner-container - The container of the progressspinner.

package/dist/react/progressspinner/index.js

@@ -3,23 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/progressspinner';
 import { TAG_NAME } from '../../components/progressspinner/progressspinner.constants';
 /**
- * `mdc-progressspinner` is a customizable, circular progress indicator component.
- * It visually represents the current completion state of a process, such as loading,
- * syncing, uploading, or any ongoing task that has a measurable percentage.
- *
- * The spinner is built using SVG with two concentric `<circle>` elements:
- * - The `progress` arc represents the portion of work completed.
- * - The `track` arc represents the remaining part.
- *
- * A visual gap is maintained between the progress and track arcs to clearly
- * distinguish the two segments. The component smoothly animates arc length
- * and respects accessibility best practices with ARIA attributes.
- *
- * The component supports different states:
- * - **Default**: Circular spinner shows the progress.
- * - **Success**: Displays a checkmark icon when progress reaches 100%.
- * - **Error**: Displays an error icon when in an error state.
- *
  * @tagname mdc-progressspinner
  *
  * @cssproperty --mdc-spinner-size - The size of the spinner.

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

@@ -2,58 +2,36 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/radio';
 import type { Events } from '../../components/radio/radio.types';
 /**
- * The Radio component allows users to select a single option from a group of mutually exclusive choices.
- * Unlike checkboxes which allow multiple selections, radio buttons ensure only one option can be selected
- * at a time within the same group. These are commonly used in forms, surveys, and settings where users
- * need to make a single selection from multiple options.
- *
- * To create a group of radio buttons, use the `mdc-radiogroup` component or ensure all radio buttons
- * share the same `name` attribute.
- *
- * ## Validation
- *
- * Radio component support native form validation. But it does not have default validation message.
- * Also, `required` attribute does not render indicator (red asterisk) for the radio component.
- *
- * The recommended way to show validation message for radio groups is to wrap the `mdc-radio` with `mdc-radiogroup`
- * and set the `help-text` of the `mdc-radiogroup` based on its validation state.
- *
- * Alternatively you can also set the `validation-message` attribute of the `mdc-radio`. This message will appear
- * in a native tooltip when the radio is checked and invalid.
- *
- * ## Accessibility
- *
- * - Provide clear labels that describe each option
- * - Use `data-aria-label` when a visual label is not present
- * - Keyboard navigation: Arrow keys to move between options, Space to select, Tab to navigate groups, Enter to submit form
- * - Group related radio buttons using the same `name` attribute or `mdc-radiogroup` component
- *
- * ## Styling
- *
- * Use the `radio-indicator` part to apply custom styles to the radio visual element.
- * This part exposes the underlying [StaticRadio](?path=/docs/components-decorator-staticradio--docs) component for advanced styling.
- *
- * The `indicator` slot allows replacing the default radio circle with a custom element.
- * When a custom indicator is slotted, the component automatically adds the `mdc-focus-ring`
- * class to the host element. This shifts the focus ring from the default static radio to the
- * entire host element, ensuring keyboard focus remains visible.
- *
+ * The radio is a single, form-associated radio button that lets the user pick exactly one option from a set of mutually exclusive choices. Radios that share a `name` attribute are grouped together — selecting one unchecks the others — and arrow-key navigation moves focus and selection between members of the group.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-radio` (typically inside `mdc-radiogroup`) when the user must pick exactly one option from a short, mutually exclusive list.
+ * - Use it in forms, surveys, and settings where every option needs to be visible at once.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-checkbox` when the user can pick zero, one, or more options.
+ * - Use `mdc-select` or `mdc-combobox` when the list of options is long or should be revealed on demand.
+ * - Use `mdc-cardradio` when each option should render as a larger, card-shaped surface.
+ * - Use `mdc-toggle` for an on/off binary control.
+ * 
+ * @tagname mdc-radio
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-staticradio
  * @dependency mdc-toggletip
- *
- * @tagname mdc-radio
- *
+ * 
  * @event input - (React: onInput) Event that gets dispatched when the radio state changes (before the change event).
  * @event change - (React: onChange) Event that gets dispatched when the radio state changes (after the input event).
  * @event focus - (React: onFocus) Event that gets dispatched when the radio receives focus.
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart radio-indicator - The staticradio that provides the visual radio appearance.
- *
+ * 
  * @slot indicator - Slot for the radio indicator element. If not provided, a default styled radio will be rendered.
  * @slot label - Slot for the label of the radio.
  */

package/dist/react/radio/index.js

@@ -3,41 +3,7 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/radio';
 import { TAG_NAME } from '../../components/radio/radio.constants';
 /**
- * The Radio component allows users to select a single option from a group of mutually exclusive choices.
- * Unlike checkboxes which allow multiple selections, radio buttons ensure only one option can be selected
- * at a time within the same group. These are commonly used in forms, surveys, and settings where users
- * need to make a single selection from multiple options.
- *
- * To create a group of radio buttons, use the `mdc-radiogroup` component or ensure all radio buttons
- * share the same `name` attribute.
- *
- * ## Validation
- *
- * Radio component support native form validation. But it does not have default validation message.
- * Also, `required` attribute does not render indicator (red asterisk) for the radio component.
- *
- * The recommended way to show validation message for radio groups is to wrap the `mdc-radio` with `mdc-radiogroup`
- * and set the `help-text` of the `mdc-radiogroup` based on its validation state.
- *
- * Alternatively you can also set the `validation-message` attribute of the `mdc-radio`. This message will appear
- * in a native tooltip when the radio is checked and invalid.
- *
- * ## Accessibility
- *
- * - Provide clear labels that describe each option
- * - Use `data-aria-label` when a visual label is not present
- * - Keyboard navigation: Arrow keys to move between options, Space to select, Tab to navigate groups, Enter to submit form
- * - Group related radio buttons using the same `name` attribute or `mdc-radiogroup` component
- *
- * ## Styling
- *
- * Use the `radio-indicator` part to apply custom styles to the radio visual element.
- * This part exposes the underlying [StaticRadio](?path=/docs/components-decorator-staticradio--docs) component for advanced styling.
- *
- * The `indicator` slot allows replacing the default radio circle with a custom element.
- * When a custom indicator is slotted, the component automatically adds the `mdc-focus-ring`
- * class to the host element. This shifts the focus ring from the default static radio to the
- * entire host element, ensuring keyboard focus remains visible.
+ * @tagname mdc-radio
  *
  * @dependency mdc-button
  * @dependency mdc-icon
@@ -45,8 +11,6 @@ import { TAG_NAME } from '../../components/radio/radio.constants';
  * @dependency mdc-staticradio
  * @dependency mdc-toggletip
  *
- * @tagname mdc-radio
- *
  * @event input - (React: onInput) Event that gets dispatched when the radio state changes (before the change event).
  * @event change - (React: onChange) Event that gets dispatched when the radio state changes (after the input event).
  * @event focus - (React: onFocus) Event that gets dispatched when the radio receives focus.

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

@@ -1,11 +1,18 @@
 import Component from '../../components/radiogroup';
 /**
- * `mdc-radiogroup` - This is the wrapper component for radio buttons which are grouped together.
- * It can have a header text and a description. It enables users to select a single option from a set of options.
- * It is often used in forms, settings, and selection in lists. It automatically group the radio buttons inside it.
- *
+ * The radiogroup is a labelled wrapper that bundles related `mdc-radio` (or `mdc-cardradio`) elements together. It renders an optional header label and helper text, propagates a shared `name` and `required` state to its radio children, and exposes the wrapped controls as a `radiogroup` to assistive technologies.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-radiogroup` whenever you render a set of `mdc-radio` (or `mdc-cardradio`) options that belong to the same question.
+ * - Use it to surface a single label and a single helper/validation message for the whole group.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-formfieldgroup` directly when grouping checkbox or toggle controls instead of radios.
+ * - Use `mdc-select` or `mdc-combobox` when the user should pick one option from a long or dynamic list that does not need to be visible at once.
+ * 
  * @tagname mdc-radiogroup
- *
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;
 export default reactWrapper;

package/dist/react/radiogroup/index.js

@@ -3,10 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/radiogroup';
 import { TAG_NAME } from '../../components/radiogroup/radiogroup.constants';
 /**
- * `mdc-radiogroup` - This is the wrapper component for radio buttons which are grouped together.
- * It can have a header text and a description. It enables users to select a single option from a set of options.
- * It is often used in forms, settings, and selection in lists. It automatically group the radio buttons inside it.
- *
  * @tagname mdc-radiogroup
  *
  */

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

@@ -1,34 +1,16 @@
 import Component from '../../components/responsivesettingsprovider';
 /**
- * `mdc-responsivesettingsprovider` is a provider component that supplies responsive settings
- * context to its child components.
- *
- * This component does not make any assumptions about how the values are determined. Values can be set
- * based on media queries or other device detection mechanisms.This way consumer can mix and match
- * different settings depending on their target devices and use cases.
- *
- * For example, when the device has table screen size/resolution, but because it is fixed dialog like
- * popovers provide better user experience.
- *
- * ## Responsive settings
- *
- * ### Media
- *
- * Generic media type to enforce responsive behavior in child components.
- * Consumer component can use the media type from the context or
- * just use CSS selector like [media="mobile"] to apply responsive styles.
- *
- * It is "unknown" by default so components can fall back to there default behavior.
- *
- * ### Popover Positioning
- *
- * By default, popovers are positioned close to the trigger element. But on small screens (e.g.: mobile devices),
- * it is often better to show popovers/menus at the center of the screen like dialogs.
- *
- * ### Force Fullscreen Dialog
- *
- * Some components like dialogs can be shown in fullscreen mode on small screens for better user experience.
- *
+ * The responsivesettingsprovider is a provider component that supplies a shared responsive-settings context to every descendant component that consumes it. The provider does not detect screen size itself — the consumer chooses when and how to update its attributes (via media queries, device-detection scripts, or any other strategy) so the same descendant components can adapt their layout without each one re-implementing breakpoint logic.
+ * 
+ * **When to use**
+ * 
+ * - Wrap a subtree (typically near the application root) with `mdc-responsivesettingsprovider` when descendant components should adapt their layout based on a shared responsive signal — for example, rendering popovers centred on small screens or forcing dialogs to fullscreen on mobile.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it as a generic media-query helper for arbitrary CSS — components that don't read this context will not be affected.
+ * - Do not use it for theme tokens (use `mdc-themeprovider`) or icon set configuration (use `mdc-iconprovider`).
+ * 
  * @tagname mdc-responsivesettingsprovider
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/responsivesettingsprovider/index.js

@@ -3,35 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/responsivesettingsprovider';
 import { TAG_NAME } from '../../components/responsivesettingsprovider/responsivesettingsprovider.constants';
 /**
- * `mdc-responsivesettingsprovider` is a provider component that supplies responsive settings
- * context to its child components.
- *
- * This component does not make any assumptions about how the values are determined. Values can be set
- * based on media queries or other device detection mechanisms.This way consumer can mix and match
- * different settings depending on their target devices and use cases.
- *
- * For example, when the device has table screen size/resolution, but because it is fixed dialog like
- * popovers provide better user experience.
- *
- * ## Responsive settings
- *
- * ### Media
- *
- * Generic media type to enforce responsive behavior in child components.
- * Consumer component can use the media type from the context or
- * just use CSS selector like [media="mobile"] to apply responsive styles.
- *
- * It is "unknown" by default so components can fall back to there default behavior.
- *
- * ### Popover Positioning
- *
- * By default, popovers are positioned close to the trigger element. But on small screens (e.g.: mobile devices),
- * it is often better to show popovers/menus at the center of the screen like dialogs.
- *
- * ### Force Fullscreen Dialog
- *
- * Some components like dialogs can be shown in fullscreen mode on small screens for better user experience.
- *
  * @tagname mdc-responsivesettingsprovider
  */
 const reactWrapper = createComponent({

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

@@ -1,56 +1,17 @@
 import Component from '../../components/screenreaderannouncer';
 /**
- * `mdc-screenreaderannouncer` can be used to announce messages with the screen reader.
- *
- * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
- *
- * Consumers can also use the public `announce` function to trigger announcements programmatically
- * by passing an options object where `announcement` is required and all other fields are optional.
- *
- * **Internal logic**
- *
- * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
- * provided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created
- * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
- * is created in the DOM.
- *
- * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
- *
- * Example CSS:
- *
- * ```css
- * #your-custom-announcer-id {
- *   clip: rect(0 0 0 0);
- *   clip-path: inset(50%);
- *   height: 1px;
- *   overflow: hidden;
- *   position: absolute;
- *   white-space: nowrap;
- *   width: 1px;
- * }
- * ```
- *
- * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
- * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
- *
- * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
- *
- * When the screen announcer component is disconnected from the DOM, all the timeouts are cleared and
- * all the announcement elements added are removed from the DOM and timeouts cleared.
- *
- * **Note**
- * 1. The default delay of 150 miliseconds is used as we dynamically generate the
- * aria-live region in the DOM and add the announcement text to it.
- * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
- * for that identity is effectively determined by the first instance that creates announcements for it.
- * Changing `data-aria-live` in later instances for the same identity will not update already-created
- * live-region containers.
- * 3. If no `identity` is provided, all the screen reader components will create and use only one
- * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
- *
- * Reference: https://patrickhlauke.github.io/aria/tests/live-regions/
- *
+ * The screenreaderannouncer is a non-visual helper component that pushes text into a shared aria-live region in the light DOM so that screen readers announce it. It manages the live-region container, debouncing, and clean-up so consumers only need to set an `announcement` (or call the public `announce()` method) when they want a message read out.
+ * 
+ * **When to use**
+ * 
+ * - Use it to surface a status update that has no visible UI counterpart — for example, "5 new messages", "Saved", or "Failed to load" — so screen-reader users hear the change.
+ * - Use it when a visible status message exists but is rendered outside the natural reading order or only briefly, and you want to guarantee assistive-technology announcement.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it for content that is already in a visible, ARIA-live container, or for content that the screen reader will naturally announce because of focus changes.
+ * - Do not use it as a logging or toast surface — it is not a UI component and renders nothing visible.
+ * 
  * @tagname mdc-screenreaderannouncer
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;

package/dist/react/screenreaderannouncer/index.js

@@ -3,57 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/screenreaderannouncer';
 import { TAG_NAME } from '../../components/screenreaderannouncer/screenreaderannouncer.constants';
 /**
- * `mdc-screenreaderannouncer` can be used to announce messages with the screen reader.
- *
- * To make an announcement set `announcement` attribute on the `mdc-screenreaderannouncer` element.
- *
- * Consumers can also use the public `announce` function to trigger announcements programmatically
- * by passing an options object where `announcement` is required and all other fields are optional.
- *
- * **Internal logic**
- *
- * When the screenreader announcer is connected to the DOM, if the `identity` attribute is not
- * provided, it is set to `mdc-screenreaderannouncer-identity` and a `<div>` element with this id is created
- * in the DOM. If the `identity` attribute is provided, the identity element is used and no new element
- * is created in the DOM.
- *
- * If you provide a custom `identity`, you must ensure that the element exists and is visually hidden.
- *
- * Example CSS:
- *
- * ```css
- * #your-custom-announcer-id {
- *   clip: rect(0 0 0 0);
- *   clip-path: inset(50%);
- *   height: 1px;
- *   overflow: hidden;
- *   position: absolute;
- *   white-space: nowrap;
- *   width: 1px;
- * }
- * ```
- *
- * When the `announcement` attribute is set, the screenreader announcer will create a `<div>` element with
- * `aria-live` attribute set to the value of `data-aria-live` attribute and append it to the `identity` element.
- * After delay of `delay` milliseconds, a `<p>` element with the announcement text is appended to the `<div>` element.
- *
- * The announcement `<div>` element is removed from the DOM after `timeout` milliseconds.
- *
- * When the screen announcer component is disconnected from the DOM, all the timeouts are cleared and
- * all the announcement elements added are removed from the DOM and timeouts cleared.
- *
- * **Note**
- * 1. The default delay of 150 miliseconds is used as we dynamically generate the
- * aria-live region in the DOM and add the announcement text to it.
- * 2. If multiple `mdc-screenreaderannouncer` instances use the same `identity`, `data-aria-live`
- * for that identity is effectively determined by the first instance that creates announcements for it.
- * Changing `data-aria-live` in later instances for the same identity will not update already-created
- * live-region containers.
- * 3. If no `identity` is provided, all the screen reader components will create and use only one
- * `<div>` element with id `mdc-screenreaderannouncer-identity` in the DOM.
- *
- * Reference: https://patrickhlauke.github.io/aria/tests/live-regions/
- *
  * @tagname mdc-screenreaderannouncer
  */
 const reactWrapper = createComponent({