@momentum-design/components 0.134.20 → 0.134.22

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.
@@ -169,6 +175,11 @@ declare class DatePicker extends DatePicker_base implements AssociatedFormContro
     protected willUpdate(changedProperties: PropertyValueMap<any> | Map<PropertyKey, unknown>): void;
     private parseValueToInternal;
     private internalToValue;
+    private getParsedMin;
+    private getParsedMax;
+    private clampValueToRange;
+    private getFieldRange;
+    private getNextSpinbuttonValue;
     private syncFormValue;
     private commitValue;
     private notifyValueChange;

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
@@ -188,8 +179,8 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
             this.syncFormValue();
         }
     }
-    parseValueToInternal() {
-        const parts = parseISODate(this.value);
+    parseValueToInternal(value = this.value) {
+        const parts = parseISODate(value);
         if (parts) {
             this.internalMonth = parts.month;
             this.internalDay = parts.day;
@@ -204,6 +195,86 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
     internalToValue() {
         return buildISODate(this.internalMonth, this.internalDay, this.internalYear);
     }
+    // AI-Assisted: keep input spinbuttons aligned with valid min/max date boundaries.
+    getParsedMin() {
+        var _a;
+        return this.min ? (_a = parseISO(this.min)) !== null && _a !== void 0 ? _a : undefined : undefined;
+    }
+    getParsedMax() {
+        var _a;
+        return this.max ? (_a = parseISO(this.max)) !== null && _a !== void 0 ? _a : undefined : undefined;
+    }
+    clampValueToRange(value) {
+        var _a, _b;
+        const dt = parseISO(value);
+        if (!dt)
+            return value;
+        const minDt = this.getParsedMin();
+        const maxDt = this.getParsedMax();
+        if (minDt && isBefore(dt, minDt))
+            return (_a = this.min) !== null && _a !== void 0 ? _a : value;
+        if (maxDt && isAfter(dt, maxDt))
+            return (_b = this.max) !== null && _b !== void 0 ? _b : value;
+        return value;
+    }
+    getFieldRange(field) {
+        const currentMonth = parseInt(this.internalMonth, 10) || undefined;
+        const currentYear = parseInt(this.internalYear, 10) || undefined;
+        const baseMin = getFieldMin(field);
+        const baseMax = getFieldMax(field, currentMonth, currentYear);
+        let min = baseMin;
+        let max = baseMax;
+        const minDt = this.getParsedMin();
+        const maxDt = this.getParsedMax();
+        if (field === 'year') {
+            if (minDt)
+                min = Math.max(min, minDt.getFullYear());
+            if (maxDt)
+                max = Math.min(max, maxDt.getFullYear());
+        }
+        else if (field === 'month' && currentYear) {
+            if (minDt && currentYear === minDt.getFullYear())
+                min = Math.max(min, minDt.getMonth() + 1);
+            if (maxDt && currentYear === maxDt.getFullYear())
+                max = Math.min(max, maxDt.getMonth() + 1);
+        }
+        else if (field === 'day' && currentMonth && currentYear) {
+            if (minDt &&
+                currentYear === minDt.getFullYear() &&
+                currentMonth === minDt.getMonth() + 1) {
+                min = Math.max(min, minDt.getDate());
+            }
+            if (maxDt &&
+                currentYear === maxDt.getFullYear() &&
+                currentMonth === maxDt.getMonth() + 1) {
+                max = Math.min(max, maxDt.getDate());
+            }
+        }
+        if (min > max) {
+            return { min: baseMin, max: baseMax, isMinConstrained: false, isMaxConstrained: false };
+        }
+        return {
+            min,
+            max,
+            isMinConstrained: min !== baseMin,
+            isMaxConstrained: max !== baseMax,
+        };
+    }
+    getNextSpinbuttonValue(currentValue, range, increment) {
+        if (increment) {
+            if (currentValue < range.min)
+                return range.min;
+            if (currentValue >= range.max)
+                return range.isMaxConstrained ? range.max : range.min;
+            return currentValue + 1;
+        }
+        if (currentValue > range.max)
+            return range.max;
+        if (currentValue <= range.min)
+            return range.isMinConstrained ? range.min : range.max;
+        return currentValue - 1;
+    }
+    // End AI-Assisted
     syncFormValue() {
         const val = this.value || this.internalToValue();
         if (this.internals) {
@@ -220,17 +291,13 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
     }
     commitValue() {
         const newVal = this.internalToValue();
-        if (newVal && newVal !== this.value) {
-            const dt = parseISO(newVal);
-            if (dt) {
-                const minDt = this.min ? parseISO(this.min) : undefined;
-                const maxDt = this.max ? parseISO(this.max) : undefined;
-                if (minDt && isBefore(dt, minDt))
-                    return;
-                if (maxDt && isAfter(dt, maxDt))
-                    return;
-            }
-            this.value = newVal;
+        if (newVal) {
+            const clampedVal = this.clampValueToRange(newVal);
+            if (clampedVal !== newVal)
+                this.parseValueToInternal(clampedVal);
+            if (clampedVal === this.value)
+                return;
+            this.value = clampedVal;
             this.syncFormValue();
             this.notifyValueChange();
         }
@@ -373,22 +440,19 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
     handleSpinbuttonKeydown(event, field) {
         if (this.readonly)
             return;
-        const currentMonth = parseInt(this.internalMonth, 10) || undefined;
-        const currentYear = parseInt(this.internalYear, 10) || undefined;
-        const minVal = getFieldMin(field);
-        const maxVal = getFieldMax(field, currentMonth, currentYear);
+        const range = this.getFieldRange(field);
         const currentVal = parseInt(this.getFieldValue(field), 10) || 0;
         switch (event.key) {
             case KEYS.ARROW_UP: {
                 event.preventDefault();
-                const newVal = currentVal >= maxVal ? minVal : currentVal + 1;
+                const newVal = this.getNextSpinbuttonValue(currentVal, range, true);
                 this.setFieldValue(field, newVal);
                 this.commitValue();
                 break;
             }
             case KEYS.ARROW_DOWN: {
                 event.preventDefault();
-                const newVal = currentVal <= minVal ? maxVal : currentVal - 1;
+                const newVal = this.getNextSpinbuttonValue(currentVal, range, false);
                 this.setFieldValue(field, newVal);
                 this.commitValue();
                 break;
@@ -408,7 +472,7 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
             default: {
                 if (/^\d$/.test(event.key)) {
                     event.preventDefault();
-                    this.handleDigitInput(event.key, field, minVal, maxVal);
+                    this.handleDigitInput(event.key, field, range.min, range.max);
                 }
                 else {
                     event.preventDefault();
@@ -558,10 +622,7 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
     // -- Render methods --
     renderSpinbutton(field) {
         const value = this.getFieldValue(field);
-        const currentMonth = parseInt(this.internalMonth, 10) || undefined;
-        const currentYear = parseInt(this.internalYear, 10) || undefined;
-        const minVal = getFieldMin(field);
-        const maxVal = getFieldMax(field, currentMonth, currentYear);
+        const range = this.getFieldRange(field);
         const labelMap = {
             month: this.localeMonthLabel,
             day: this.localeDayLabel,
@@ -578,8 +639,8 @@ class DatePicker extends FormInternalsMixin(DataAriaLabelMixin(FormfieldWrapper)
         part="spinbutton spinbutton-${field}"
         role="spinbutton"
         aria-label="${labelMap[field]}"
-        aria-valuemin="${minVal}"
-        aria-valuemax="${maxVal}"
+        aria-valuemin="${range.min}"
+        aria-valuemax="${range.max}"
         aria-valuenow="${ifDefined(value ? parseInt(value, 10) : undefined)}"
         aria-description="${this.localeSpinbuttonDescription}"
         .value="${value}"