@momentum-design/components 0.134.19 → 0.134.21

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({

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

@@ -4,35 +4,27 @@ import type { Events } from '../../components/searchfield/searchfield.types';
 import type { Events as EventsInherited0 } from '../../components/input/input.types';
 import type { Events as EventsInherited1 } from '../../utils/mixins/CharacterLimitMixin.ts';
 /**
- * `mdc-searchfield` component is used as an input field for search functionality.
- *
- * It supports any interactable Chip component as filters. (`mdc-inputchip`, `mdc-alertchip`, `mdc-chip`)
- * Chips are rendered inline with the search input text, behaving like single characters.
- * Users can traverse the cursor between chips and text using arrow keys,
- * and remove a chip by pressing Backspace when the cursor is adjacent to it.
- *
- * This component is built by extending the `mdc-input` component.
- *
- * Searchfield supports controlled vs uncontrolled behavior for chip filters, which can be set via the `control-type` attribute:
- * - In **uncontrolled** mode (default), when a chip is removed via the UI, it is automatically removed from the DOM and a `chipRemove` event is dispatched with the removed chip in the event detail. The consumer can listen to the `chipRemove` event but does not need to do anything to remove the chip from the DOM.
- * - In **controlled** mode (`control-type="controlled"`), when a chip is removed via the UI, it is NOT removed from the DOM, but a `chipRemove` event is still dispatched with the "removed" chip in the event detail. The consumer must listen to the `chipRemove` event and handle removing the chip from the DOM themselves (e.g., by updating their state that controls which chips are rendered).
- *
- * **Accessibility:**
- *
- * NOTE: this component should not be used in combination with a Popover or Listbox component.
- * Search results should be shown permanently on the page if using this component.
- *
- * For a search field that opens a Popover, use the `mdc-searchpopover` widget instead.
- *
+ * The searchfield is a single-line text input tailored for search. It renders a leading search icon, a trailing clear button, and an inline area in front of the text caret where chip filters can be slotted. Chips behave like single characters in the input flow: they share the cursor with the text and can be focused, navigated, and removed with the keyboard.
+ * 
+ * **When to use**
+ * 
+ * - Use it whenever the user types a query to search a list, table, or other content rendered on the same page.
+ * - Use it with slotted chip filters (`mdc-inputchip`, `mdc-chip`, `mdc-alertchip`) when the search query is refined by removable filter tokens that should appear inline with the input text.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use it for a search that opens a popover / listbox of suggestions or results. Use `mdc-searchpopover` instead — pairing this component with a Popover or Listbox is not supported.
+ * - Do not use it for free-form text entry that is not a search query — use `mdc-input` (or `mdc-textarea`) directly.
+ * 
  * @tagname mdc-searchfield
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).
  * @event change - (React: onChange) This event is dispatched when the value of the input field changes (on blur).
  * @event focus - (React: onFocus) This event is dispatched when the input receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the input loses focus.
  * @event clear - (React: onClear) This event is dispatched when the input text is cleared.
  * @event chipRemove - (React: onChipRemove) This event is dispatched when a chip filter is removed. The removed chip element is available in event.detail.chip. In `uncontrolled` mode (default) the chip is removed from the DOM automatically; in `controlled` mode only the event is fired and the consumer is responsible for removing the chip.
- *
+ * 
  * @slot filters - Slot for chip filters rendered inline with the input text
  * @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.
@@ -42,7 +34,7 @@ import type { Events as EventsInherited1 } from '../../utils/mixins/CharacterLim
  * @slot input-leading-icon - Slot for the leading icon before the input field. If not provided, the `leadingIcon` property will be used to render the leading icon.
  * @slot input-prefix-text - Slot for the prefix text before the input field. If not provided, the `prefixText` property will be used to render the prefix text.
  * @slot trailing-button - Slot for the trailing button to clear the input field. If not provided, the clear button will be rendered when `trailingButton` property is set to true.
- *
+ * 
  * @cssproperty --mdc-label-font-size - Font size for the label text.
  * @cssproperty --mdc-label-font-weight - Font weight for the label text.
  * @cssproperty --mdc-label-line-height - Line height for the label text.
@@ -58,7 +50,7 @@ import type { Events as EventsInherited1 } from '../../utils/mixins/CharacterLim
  * @cssproperty --mdc-input-support-text-color - Text color for the help text
  * @cssproperty --mdc-input-selection-text-color - Text color for the selected text
  * @cssproperty --mdc-input-selection-background-color - Background color for the selected text
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.

package/dist/react/searchfield/index.js

@@ -3,26 +3,6 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/searchfield';
 import { TAG_NAME } from '../../components/searchfield/searchfield.constants';
 /**
- * `mdc-searchfield` component is used as an input field for search functionality.
- *
- * It supports any interactable Chip component as filters. (`mdc-inputchip`, `mdc-alertchip`, `mdc-chip`)
- * Chips are rendered inline with the search input text, behaving like single characters.
- * Users can traverse the cursor between chips and text using arrow keys,
- * and remove a chip by pressing Backspace when the cursor is adjacent to it.
- *
- * This component is built by extending the `mdc-input` component.
- *
- * Searchfield supports controlled vs uncontrolled behavior for chip filters, which can be set via the `control-type` attribute:
- * - In **uncontrolled** mode (default), when a chip is removed via the UI, it is automatically removed from the DOM and a `chipRemove` event is dispatched with the removed chip in the event detail. The consumer can listen to the `chipRemove` event but does not need to do anything to remove the chip from the DOM.
- * - In **controlled** mode (`control-type="controlled"`), when a chip is removed via the UI, it is NOT removed from the DOM, but a `chipRemove` event is still dispatched with the "removed" chip in the event detail. The consumer must listen to the `chipRemove` event and handle removing the chip from the DOM themselves (e.g., by updating their state that controls which chips are rendered).
- *
- * **Accessibility:**
- *
- * NOTE: this component should not be used in combination with a Popover or Listbox component.
- * Search results should be shown permanently on the page if using this component.
- *
- * For a search field that opens a Popover, use the `mdc-searchpopover` widget instead.
- *
  * @tagname mdc-searchfield
  *
  * @event input - (React: onInput) This event is dispatched when the value of the input field changes (every press).