@momentum-design/components 0.134.20 → 0.134.22

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

@@ -2,38 +2,34 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/checkbox';
 import type { Events } from '../../components/checkbox/checkbox.types';
 /**
- * The Checkbox component allows users to select one or multiple options from a list, toggle features on/off,
- * or indicate agreement in forms and settings. These are commonly used in forms, lists, and settings panels
- * where users need to make selections or express preferences.
- *
- * To create a group of checkboxes, use the `mdc-formfieldgroup` component.
- *
- * **Note:** This component internally renders a native checkbox input element with custom styling.
- *
- * ## When to use
- *
- * Use checkboxes when users can select multiple options from a list, or when a single checkbox represents a binary choice (e.g., agreeing to terms).
- *
- * ## Accessibility
- * - Provide clear labels that describe what the checkbox controls
- * - Use `data-aria-label` when a visual label is not present
- * - Keyboard navigation: Space to toggle, Tab to navigate, Enter to submit form
- *
- * ## Styling
- * Use the `static-checkbox` part to apply custom styles to the checkbox visual element.
- * This part exposes the underlying [StaticCheckbox](?path=/docs/components-decorator-staticcheckbox--docs) component for advanced styling.
- *
+ * The checkbox is a form control that represents a binary choice ("checked"/"unchecked") or, when used in a group, allows multiple selections from a list. It wraps a native `<input type="checkbox">` and renders a custom visual through `mdc-staticcheckbox`, while preserving full form participation (value, name, validation, reset).
+ * 
+ * A checkbox can also be in an `indeterminate` (mixed) state — typically used when a parent checkbox summarises a nested group whose children are not all in the same state.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-checkbox` when the user can select **any number** of options from a list (zero, one, or many).
+ * - Use a single `mdc-checkbox` for a binary choice that does not need to take effect immediately (e.g. agreeing to terms before submitting a form).
+ * - Use it inside `mdc-formfieldgroup` when several checkboxes belong to the same labelled group.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-radio` (or `mdc-radiogroup`) when **only one** option in a set can be selected.
+ * - Use `mdc-toggle` for a binary on/off setting that takes effect immediately.
+ * - Use `mdc-cardcheckbox` when each option needs the visual weight of a card surface (image, title, supporting copy).
+ * - Use `mdc-staticcheckbox` when the visual is purely decorative and not user-interactive (e.g. inside a list item that owns the click target).
+ * 
+ * @tagname mdc-checkbox
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-staticcheckbox
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
- * @tagname mdc-checkbox
- *
+ * 
  * @event change - (React: onChange) Event that gets dispatched when the checkbox state changes.
  * @event focus - (React: onFocus) Event that gets dispatched when the checkbox receives focus.
- *
+ * 
  * @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.
@@ -45,7 +41,7 @@ import type { Events } from '../../components/checkbox/checkbox.types';
  * @csspart checkbox-input - The native checkbox input element that provides the interactive functionality.
  * @csspart text-container - The container for the label and helper text elements.
  * @csspart static-checkbox - The staticcheckbox that provides the visual checkbox appearance.
- *
+ * 
  * @cssstate checked - Active when the checkbox is checked.
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {

package/dist/react/checkbox/index.js

@@ -3,26 +3,7 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/checkbox';
 import { TAG_NAME } from '../../components/checkbox/checkbox.constants';
 /**
- * The Checkbox component allows users to select one or multiple options from a list, toggle features on/off,
- * or indicate agreement in forms and settings. These are commonly used in forms, lists, and settings panels
- * where users need to make selections or express preferences.
- *
- * To create a group of checkboxes, use the `mdc-formfieldgroup` component.
- *
- * **Note:** This component internally renders a native checkbox input element with custom styling.
- *
- * ## When to use
- *
- * Use checkboxes when users can select multiple options from a list, or when a single checkbox represents a binary choice (e.g., agreeing to terms).
- *
- * ## Accessibility
- * - Provide clear labels that describe what the checkbox controls
- * - Use `data-aria-label` when a visual label is not present
- * - Keyboard navigation: Space to toggle, Tab to navigate, Enter to submit form
- *
- * ## Styling
- * Use the `static-checkbox` part to apply custom styles to the checkbox visual element.
- * This part exposes the underlying [StaticCheckbox](?path=/docs/components-decorator-staticcheckbox--docs) component for advanced styling.
+ * @tagname mdc-checkbox
  *
  * @dependency mdc-button
  * @dependency mdc-icon
@@ -30,8 +11,6 @@ import { TAG_NAME } from '../../components/checkbox/checkbox.constants';
  * @dependency mdc-text
  * @dependency mdc-toggletip
  *
- * @tagname mdc-checkbox
- *
  * @event change - (React: onChange) Event that gets dispatched when the checkbox state changes.
  * @event focus - (React: onFocus) Event that gets dispatched when the checkbox receives focus.
  *

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

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

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

@@ -2,33 +2,33 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/coachmark';
 import type { Events as EventsInherited } from '../../components/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
@@ -37,7 +37,7 @@ import type { Events as EventsInherited } from '../../components/popover/popover
  * @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 const reactWrapper: import("@lit/react").ReactWebComponent<Component, {

package/dist/react/coachmark/index.js

@@ -3,27 +3,10 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/coachmark';
 import { TAG_NAME } from '../../components/coachmark/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/react/combobox/index.d.ts

@@ -2,57 +2,47 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/combobox';
 import type { Events } from '../../components/combobox/combobox.types';
 /**
- * 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
@@ -69,7 +59,7 @@ import type { Events } from '../../components/combobox/combobox.types';
  * @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/react/combobox/index.js

@@ -3,36 +3,7 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/combobox';
 import { TAG_NAME } from '../../components/combobox/combobox.constants';
 /**
- * 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
@@ -40,8 +11,6 @@ import { TAG_NAME } from '../../components/combobox/combobox.constants';
  * @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/react/controltypeprovider/index.d.ts

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

package/dist/react/controltypeprovider/index.js

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

@@ -2,40 +2,46 @@ import { type EventName } from '@lit/react';
 import Component from '../../components/datepicker';
 import type { Events } from '../../components/datepicker/datepicker.types';
 /**
- * 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/react/datepicker/index.js

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