@momentum-design/components 0.134.19 → 0.134.21

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

@@ -3,27 +3,34 @@ import Buttonsimple from '../buttonsimple/buttonsimple.component';
 import type { ColorType } from '../staticchip/staticchip.types';
 declare const Chip_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Buttonsimple;
 /**
- * mdc-chip is an interactive element that can be used to represent a chip. It supports a leading icon along with label.
- * Consumers can wrap this component around a tooltip to provide additional context.
- *
- * It is recommended to keep the label text for the chip component concise and compact.<br/>
- * For best results, we recommend limiting the <b>maximum length of the label text to 20 characters</b>,
- * including empty spaces to split words.
- *
- * This component is built by extending `Buttonsimple`.
- *
+ * The chip is a compact interactive surface that renders an optional leading icon and a short label. It behaves like a button (single tap or `Enter`/`Space` activation, focus, hover, and disabled states) and is commonly used to represent a tag, attribute, filter trigger, or quick action.
+ * 
+ * Keep the label short — we recommend a maximum of **20 characters** (including spaces). Chips can be connected to an `mdc-tooltip` (via the tooltip's `triggerid` pointing at the chip's `id`) to surface additional context when the label is truncated or needs explanation.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-chip` to represent an attribute, tag, or quick action that fits in a single, short word or phrase.
+ * - Use it inside a horizontal row or wrap of chips when several short actions or attributes share the same visual weight.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-button` when the action needs more visual weight, more text, or icon-only treatment beyond a compact tag.
+ * - Use `mdc-filterchip` when the chip should reflect an applied filter that can be toggled and removed.
+ * - Use `mdc-alertchip` when the chip should communicate a status (information, warning, error) rather than trigger an action.
+ * - Use `mdc-staticchip` when the chip is purely decorative and should not be interactive (e.g. inside a list item that owns the click target).
+ * 
  * @tagname mdc-chip
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @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.
- *
+ * 
  * @csspart icon - The icon part of the chip.
  * @csspart label - The label part of the chip.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the chip is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the chip.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the chip.

package/dist/components/chip/chip.component.js

@@ -15,15 +15,6 @@ import StaticChip from '../staticchip/staticchip.component';
 import { DEFAULTS } from './chip.constants';
 import styles from './chip.styles';
 /**
- * mdc-chip is an interactive element that can be used to represent a chip. It supports a leading icon along with label.
- * Consumers can wrap this component around a tooltip to provide additional context.
- *
- * It is recommended to keep the label text for the chip component concise and compact.<br/>
- * For best results, we recommend limiting the <b>maximum length of the label text to 20 characters</b>,
- * including empty spaces to split words.
- *
- * This component is built by extending `Buttonsimple`.
- *
  * @tagname mdc-chip
  *
  * @dependency mdc-icon

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

@@ -1,33 +1,33 @@
 import Popover from '../popover/popover.component';
 import type { PopoverTrigger } from '../popover/popover.types';
 /**
- * A Coachmark is a contextual guidance component used to highlight a specific UI element and explain its purpose or functionality.
- * It is typically shown as part of onboarding, feature discovery, or progressive education within the product.
- *
- * Coachmark component based on top of the popover component,
- * with the default value of certain properties changed.
- * Coachmark component will always have an arrow attached to it.
- * The color of the coachmark is contrast.
- *
- * ## When to use
- * - Introducing a new or complex feature to users.
- * - Drawing attention to a UI element that might otherwise be missed.
- * - Providing step-by-step guidance in an onboarding or walkthrough flow.
- *
- * ## Accessibility
- * - The default role of coachmark is `"dialog"`, which can be changed via the `role` attribute.
- * - aria-label or aria-labelledby can be provided to give the coachmark an accessible name.
- *
- * @dependency mdc-popover
- *
+ * A coachmark is a contextual guidance overlay used to highlight a specific UI element and explain its purpose. It is typically shown as part of onboarding, feature discovery, or step-by-step walkthroughs.
+ * 
+ * It renders as a high-contrast bubble anchored to a trigger element with a visible arrow and a close button. Unlike a tooltip, the coachmark stays open until the user dismisses it (or the consumer toggles it programmatically), making it suitable for explanatory copy rather than a quick hover hint.
+ * 
+ * **When to use**
+ * 
+ * - Introducing a new or complex feature when users land on a screen for the first time.
+ * - Drawing attention to a UI element that might otherwise be overlooked (a secondary action, a settings entry point).
+ * - Providing step-by-step guidance in an onboarding flow or guided tour.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-tooltip` for a short, hover-triggered hint about a control that does not need a close affordance.
+ * - Use `mdc-toggletip` when a small piece of contextual help should appear on click and dismiss on outside interaction without a persistent step-flow.
+ * - Use `mdc-popover` directly when a generic dismissible overlay is needed and the onboarding-styled contrast bubble + arrow + close button defaults are not desired.
+ * - Use `mdc-dialog` (or `mdc-announcementdialog`) when the message is modal, must block the rest of the UI, or is not anchored to a specific element.
+ * 
  * @tagname mdc-coachmark
- *
+ * 
+ * @dependency mdc-popover
+ * 
  * @event shown - (React: onShown) This event is dispatched when the coachmark is shown
  * @event hidden - (React: onHidden) This event is dispatched when the coachmark is hidden
  * @event created - (React: onCreated) This event is dispatched when the coachmark is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) This event is dispatched when the coachmark is
  * destroyed (removed from the DOM)
- *
+ * 
  * @cssproperty --mdc-popover-arrow-border-radius - radius of the arrow border
  * @cssproperty --mdc-popover-arrow-border - border of the arrow
  * @cssproperty --mdc-popover-primary-background-color - primary background color of the popover
@@ -36,7 +36,7 @@ import type { PopoverTrigger } from '../popover/popover.types';
  * @cssproperty --mdc-popover-inverted-border-color - inverted border color of the popover
  * @cssproperty --mdc-popover-inverted-text-color - inverted text color of the popover
  * @cssproperty --mdc-popover-elevation-3 - elevation of the popover
- *
+ * 
  * @slot - Default slot for modal container
  */
 declare class Coachmark extends Popover {

package/dist/components/coachmark/coachmark.component.js

@@ -11,27 +11,10 @@ import { property } from 'lit/decorators.js';
 import Popover from '../popover/popover.component';
 import { DEFAULTS } from './coachmark.constants';
 /**
- * A Coachmark is a contextual guidance component used to highlight a specific UI element and explain its purpose or functionality.
- * It is typically shown as part of onboarding, feature discovery, or progressive education within the product.
- *
- * Coachmark component based on top of the popover component,
- * with the default value of certain properties changed.
- * Coachmark component will always have an arrow attached to it.
- * The color of the coachmark is contrast.
- *
- * ## When to use
- * - Introducing a new or complex feature to users.
- * - Drawing attention to a UI element that might otherwise be missed.
- * - Providing step-by-step guidance in an onboarding or walkthrough flow.
- *
- * ## Accessibility
- * - The default role of coachmark is `"dialog"`, which can be changed via the `role` attribute.
- * - aria-label or aria-labelledby can be provided to give the coachmark an accessible name.
+ * @tagname mdc-coachmark
  *
  * @dependency mdc-popover
  *
- * @tagname mdc-coachmark
- *
  * @event shown - (React: onShown) This event is dispatched when the coachmark is shown
  * @event hidden - (React: onHidden) This event is dispatched when the coachmark is hidden
  * @event created - (React: onCreated) This event is dispatched when the coachmark is created (added to the DOM)

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

@@ -6,57 +6,47 @@ import type { PopoverStrategy } from '../popover/popover.types';
 import type { ComboboxFilter, Placement } from './combobox.types';
 declare const Combobox_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/lifecycle/CaptureDestroyEventForChildElement").CaptureDestroyEventForChildElementInterface> & import("../../utils/mixins/index.types").Constructor<import("../../models").Component & import("../../utils/mixins/AutoFocusOnMountMixin").AutoFocusOnMountMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FormInternalsMixin").FormInternalsMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ControlTypeMixin").ControlTypeMixinInterface> & typeof FormfieldWrapper;
 /**
- * The Combobox component is a text-based dropdown control that allows users to select an option from a predefined list.
- * Users can type text to filter the options and select their desired choice.
- *
- * When the user starts typing, the filter uses a "starts with" search and displays options based on the text entered by the user.
- * If the user entered text that doesn't match with any of the options, then the text in the `no-result-text` attribute will be displayed.
- *
- * The `filter` attribute controls how options are narrowed as the user types.
- * The default `'match-starts-with'` strategy shows options whose label starts with the typed text.
- * Setting `filter="none"` disables internal filtering, which is useful when the consumer manages
- * filtering externally (e.g., fetching results from an API) and dynamically updates the slotted options.
- * A custom function can also be provided via the `filter` property for full control over the logic.
- *
- * If there is no text in the `no-result-text` attribute then nothing will be shown.
- *
- * Combobox is designed to work with `mdc-option` for individual options and `mdc-optgroup` for grouping related options.
- * The component ensures accessibility and usability while handling various use cases, including long text truncation with tooltip support.
- *
- * Every mdc-option should have a `value` attribute set to ensure proper form submission.
- *
- * To set a default option, use the `selected` attribute on the `mdc-option` element.
- *
- * When the combobox `control-type` attribute is "controlled", then the value should be set by the parent only, and the combobox will emit `change` and `input` events
- * with the selected option details when the user makes a selection or types in the input, but it won't update the selected value internally.
- * The parent component is expected to listen to these events and update the `value` property of the combobox accordingly to reflect the changes in the UI.
- *
- * **Note:** Make sure to add `mdc-selectlistbox` as a child of `mdc-combobox` and wrap options/optgroup in it to ensure proper accessibility functionality. Read more about it in SelectListBox documentation.
- *
- * If you need to use `mdc-tooltip` with any options, make sure to place the tooltip component outside the `mdc-selectlistbox` element. Read more about it in Options documentation.
- *
- * To understand more about combobox and its patterns, refer to this [WCAG example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/).
- *
+ * The combobox is a text-based dropdown control that lets the user type to filter a predefined list of options, then pick one. Typing narrows the visible options based on the configured `filter` strategy; clicking the trigger button or pressing arrow keys opens the dropdown without filtering.
+ * 
+ * The component is form-associated and participates in native form submission, validation, and reset.
+ * 
+ * It is designed to be used with `mdc-option` (individual options) and `mdc-optgroup` (grouped options) placed inside an `mdc-selectlistbox` slotted child — `mdc-selectlistbox` owns the `role="listbox"` and is required for correct screen-reader behaviour.
+ * 
+ * When the consumer needs to drive the value externally (e.g. server-side filtering), set `control-type="controlled"` on a wrapping `mdc-controltypeprovider` (or use `filter="none"`): the combobox will emit `input` and `change` events but will not mutate its own `value` — the parent component is expected to update `value` to reflect the selection.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-combobox` when the user must pick a single value from a long list and typing to filter is faster than scanning.
+ * - Use it when a predictive "starts with" filter (or a custom filter function) genuinely helps the user — short lists rarely justify a combobox.
+ * - Use it when the option list is fetched dynamically (set `filter="none"` and update slotted options as data arrives).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-select` when the user should only pick from a fixed list without typing.
+ * - Use `mdc-searchfield` when the user is searching for content rather than picking a single value from a known set.
+ * - Use `mdc-input` when free-form text is the goal and no constrained option list applies.
+ * - Use `mdc-radiogroup` when there are only a handful of options and they should all be visible at once.
+ * 
+ * @tagname mdc-combobox
+ * 
  * @dependency mdc-buttonsimple
  * @dependency mdc-icon
  * @dependency mdc-input
  * @dependency mdc-listitem
  * @dependency mdc-popover
- *
- * @tagname mdc-combobox
- *
+ * 
  * @slot default - This is a default/unnamed slot for Selectlistbox including options and/or option group.
  * @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.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the combobox is clicked.
  * @event change - (React: onChange) This event is dispatched when the combobox is changed.
  * @event input - (React: onInput) This event is dispatched when the combobox is changed.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the combobox.
  * @event focus - (React: onFocus) This event is dispatched when the combobox receives focus.
- *
+ * 
  * @cssproperty --mdc-combobox-border-color - The border color of the combobox
  * @cssproperty --mdc-combobox-height - The height of the combobox trigger control
  * @cssproperty --mdc-combobox-icon-color - The icon color of the combobox
@@ -73,7 +63,7 @@ declare const Combobox_base: import("../../utils/mixins/index.types").Constructo
  * @cssproperty --mdc-help-text-line-height - Line height for the help text.
  * @cssproperty --mdc-help-text-color - Color for the help text.
  * @cssproperty --mdc-required-indicator-color - Color for the required indicator text.
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element that is displayed next to the label when the `required` property is set to true.

package/dist/components/combobox/combobox.component.js

@@ -34,36 +34,7 @@ import { AUTOCOMPLETE_LIST, FILTER, ICON_NAME, TRIGGER_ID } from './combobox.con
 import { ComboboxEventManager } from './combobox.events';
 import styles from './combobox.styles';
 /**
- * The Combobox component is a text-based dropdown control that allows users to select an option from a predefined list.
- * Users can type text to filter the options and select their desired choice.
- *
- * When the user starts typing, the filter uses a "starts with" search and displays options based on the text entered by the user.
- * If the user entered text that doesn't match with any of the options, then the text in the `no-result-text` attribute will be displayed.
- *
- * The `filter` attribute controls how options are narrowed as the user types.
- * The default `'match-starts-with'` strategy shows options whose label starts with the typed text.
- * Setting `filter="none"` disables internal filtering, which is useful when the consumer manages
- * filtering externally (e.g., fetching results from an API) and dynamically updates the slotted options.
- * A custom function can also be provided via the `filter` property for full control over the logic.
- *
- * If there is no text in the `no-result-text` attribute then nothing will be shown.
- *
- * Combobox is designed to work with `mdc-option` for individual options and `mdc-optgroup` for grouping related options.
- * The component ensures accessibility and usability while handling various use cases, including long text truncation with tooltip support.
- *
- * Every mdc-option should have a `value` attribute set to ensure proper form submission.
- *
- * To set a default option, use the `selected` attribute on the `mdc-option` element.
- *
- * When the combobox `control-type` attribute is "controlled", then the value should be set by the parent only, and the combobox will emit `change` and `input` events
- * with the selected option details when the user makes a selection or types in the input, but it won't update the selected value internally.
- * The parent component is expected to listen to these events and update the `value` property of the combobox accordingly to reflect the changes in the UI.
- *
- * **Note:** Make sure to add `mdc-selectlistbox` as a child of `mdc-combobox` and wrap options/optgroup in it to ensure proper accessibility functionality. Read more about it in SelectListBox documentation.
- *
- * If you need to use `mdc-tooltip` with any options, make sure to place the tooltip component outside the `mdc-selectlistbox` element. Read more about it in Options documentation.
- *
- * To understand more about combobox and its patterns, refer to this [WCAG example](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/examples/combobox-autocomplete-list/).
+ * @tagname mdc-combobox
  *
  * @dependency mdc-buttonsimple
  * @dependency mdc-icon
@@ -71,8 +42,6 @@ import styles from './combobox.styles';
  * @dependency mdc-listitem
  * @dependency mdc-popover
  *
- * @tagname mdc-combobox
- *
  * @slot default - This is a default/unnamed slot for Selectlistbox including options and/or option group.
  * @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.

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

@@ -1,18 +1,26 @@
 import { Provider } from '../../models';
 import type { ControlType } from './controltypeprovider.types';
 /**
- * ContolTypeProvider component, which allows to be consumed from sub components
- * (see `providerUtils.consume` for how to consume)
- *
- * attribute 'control-type' sets the default control type for all consumers
-    - 'controlled' the consumer component will not handle any interaction itself, e.g. toggling a checkbox.
-    - 'uncontrolled' the consumer component will handle interactions
- *
- * ControlTypeMixin allows components to consume this context
- * note that this is intended to be set once, ControlTypeMixin will not update on changes to control-type
- *
+ * The control type provider is a context provider used to set whether descendant form controls operate as **controlled** or **uncontrolled** components.
+ * 
+ * - `uncontrolled` (default) — each control manages its own state. Toggling a checkbox, picking a combobox option, or moving a slider updates the control's internal value and dispatches a `change` event.
+ * - `controlled` — each control delegates state to its parent. The control emits `input` and `change` with the requested new value but does not update its own value; the parent component is expected to update the control's `value` attribute in response.
+ * 
+ * This mirrors the React controlled/uncontrolled pattern at the web-component level so the same component can be embedded in either consumer style without forking the API.
+ * 
+ * It is rendered as a transparent wrapper — the provider does not produce any visible UI.
+ * 
+ * **When to use**
+ * 
+ * - Wrap a tree of form controls (combobox, select, checkbox, etc.) in `mdc-controltypeprovider control-type="controlled"` when the parent owns the canonical state and the controls must always reflect what the parent passes in.
+ * - Use it when integrating with state-management libraries (React, Redux, signals, etc.) that need every user interaction to flow through the consumer's update cycle.
+ * 
+ * **When not to use**
+ * 
+ * - Leave the provider out (or rely on the default `uncontrolled`) when each control should own its own state and the consumer just listens to `change`.
+ * - Do not nest providers to switch modes mid-tree unless absolutely necessary — descendant controls subscribe to the context once and do not re-subscribe when the value changes.
+ * 
  * @tagname mdc-controltypeprovider
- *
  */
 declare class ControlTypeProvider extends Provider<ControlType> {
     constructor();

package/dist/components/controltypeprovider/controltypeprovider.component.js

@@ -12,16 +12,6 @@ import { Provider } from '../../models';
 import ControlTypeProviderContext from './controltypeprovider.context';
 import { DEFAULTS, VALID_VALUES } from './controltypeprovider.constants';
 /**
- * ContolTypeProvider component, which allows to be consumed from sub components
- * (see `providerUtils.consume` for how to consume)
- *
- * attribute 'control-type' sets the default control type for all consumers
-    - 'controlled' the consumer component will not handle any interaction itself, e.g. toggling a checkbox.
-    - 'uncontrolled' the consumer component will handle interactions
- *
- * ControlTypeMixin allows components to consume this context
- * note that this is intended to be set once, ControlTypeMixin will not update on changes to control-type
- *
  * @tagname mdc-controltypeprovider
  *
  */

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

@@ -6,40 +6,46 @@ import type { SelectionMode } from '../calendar/calendar.types';
 import type { DatePickerVariant, Placement } from './datepicker.types';
 declare const DatePicker_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FormInternalsMixin").FormInternalsMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DataAriaLabelMixin").DataAriaLabelMixinInterface> & typeof FormfieldWrapper;
 /**
- * mdc-datepicker is a component that allows users to select a date
- * or enter a date manually. It supports two variants:
- *
- * - `input`: Manual date entry with spinbutton inputs for month, day, and year
- * - `default`: A select-like trigger that opens a calendar for date range selection
- *
- * The component uses `mdc-calendar` inside a popover for date selection
- * and supports localization via a BCP 47 locale string.
- *
+ * The datepicker lets users pick a date either by typing it directly into month/day/year spinbutton fields or by opening an `mdc-calendar` inside a popover. It supports BCP 47 locale strings to drive field order, separators, placeholders, and localised accessible labels.
+ * 
+ * The component is form-associated and participates in native form submission, validation, and reset. When a range or week is selected, both the start (`value`) and end (`end-value`) dates are submitted together using the configured `name`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-datepicker` with `variant="input"` when the user typically knows the date and entering it digit-by-digit is fastest.
+ * - Use `mdc-datepicker` with `variant="default"` when picking from a calendar (range or week) is the primary interaction.
+ * - Use it when the value needs to be locale-aware (field order, separator, formatting) and accessible to spinbutton-aware screen readers.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-input` when free-form text is the goal and date semantics are not required.
+ * - Use `mdc-calendar` directly when the calendar should always be visible (e.g. embedded in a sidebar) without a popover trigger.
+ * 
  * @tagname mdc-datepicker
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-calendar
  * @dependency mdc-icon
  * @dependency mdc-popover
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the date value changes.
  * @event change - (React: onChange) This event is dispatched when the date value is committed.
  * @event focus - (React: onFocus) This event is dispatched when the datepicker receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the datepicker loses focus.
- *
+ * 
  * @slot label - Slot for the label element.
  * @slot toggletip - Slot for the toggletip info icon button.
  * @slot help-icon - Slot for the helper/validation icon.
  * @slot help-text - Slot for the helper/validation text.
- *
+ * 
  * @cssproperty --mdc-datepicker-background-color - Background color of the datepicker input.
  * @cssproperty --mdc-datepicker-border-color - Border color of the datepicker input.
  * @cssproperty --mdc-datepicker-text-color - Text color of the datepicker input.
  * @cssproperty --mdc-datepicker-height - The height of the datepicker trigger control.
  * @cssproperty --mdc-datepicker-width - Width of the datepicker component.
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element.

package/dist/components/datepicker/datepicker.component.js

@@ -22,15 +22,6 @@ import { CALENDAR_ICON, DEFAULTS, TRIGGER_ID, VARIANT } from './datepicker.const
 import styles from './datepicker.styles';
 import { buildISODate, getDateSeparator, getFieldMax, getFieldMin, getFieldOrder, getPlaceholder, parseISODate, } from './datepicker.utils';
 /**
- * mdc-datepicker is a component that allows users to select a date
- * or enter a date manually. It supports two variants:
- *
- * - `input`: Manual date entry with spinbutton inputs for month, day, and year
- * - `default`: A select-like trigger that opens a calendar for date range selection
- *
- * The component uses `mdc-calendar` inside a popover for date selection
- * and supports localization via a BCP 47 locale string.
- *
  * @tagname mdc-datepicker
  *
  * @dependency mdc-button

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

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

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

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