@momentum-design/components 0.134.19 → 0.134.21

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

@@ -5,37 +5,28 @@ import type { RoleType } from '../../utils/roles';
 import type { ButtonSize, ButtonType } from './buttonsimple.types';
 declare const Buttonsimple_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/AutoFocusOnMountMixin").AutoFocusOnMountMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/TabIndexMixin").TabIndexMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/DisabledMixin").DisabledMixinInterface> & typeof Component;
 /**
- * `mdc-buttonsimple` is a simple button component that can be configured in various ways to suit different use cases.
- * It can be used standalone or as a base for more complex button components like `mdc-button`.
- *
- * ### Button Types
- *
- * The button type defines the behavior when clicked:
- *
- * - **button**: Standard button that performs an action on click
- * - **submit**: Submits the form data to the server
- * - **reset**: Resets the form data to its initial state
- *
- * ### Active State
- *
- * The `active` attribute toggles the button's active/toggled state,
- * automatically setting the appropriate ARIA state (e.g., `aria-pressed`).
- * This is useful for toggle buttons or buttons indicating a selected state.
- *
- * ### Disabled States
- *
- * - **disabled**: Completely disables the button, removing it from the tab order
- * - **soft-disabled**: Button appears disabled but remains focusable for accessibility
- *
+ * The buttonsimple is a low-level button primitive that handles keyboard activation, focus management, disabled/soft-disabled states, form association, and optional toggled state. It does not provide visual styling on its own — consumers wrap or compose it when they need button semantics without the opinionated appearance of `mdc-button`.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-buttonsimple` when you are building a custom button surface (for example a card, list item, or composite control) and need correct keyboard/ARIA semantics without inheriting the visual styling of `mdc-button`.
+ * - Use it inside design-system components that need to behave like buttons but render their own layout (e.g. `mdc-button`, `mdc-cardbutton`, `mdc-listitem` actions).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-button` when the design calls for the standard visual treatment (variant, color, size, prefix/postfix icons).
+ * - Use `mdc-buttonlink` when the control is a navigation that should render as an anchor.
+ * - Use `mdc-toggle` or `mdc-checkbox` for binary state in forms — they expose the correct form-control semantics and labelling.
+ * 
  * @tagname mdc-buttonsimple
- *
+ * 
  * @slot - Text label of the button.
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the button is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the button.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the button.
  * @event focus - (React: onFocus) This event is dispatched when the button receives focus.
- *
+ * 
  * @cssproperty --mdc-button-height - Height of the button
  * @cssproperty --mdc-button-background - Background color of the button
  * @cssproperty --mdc-button-border-color - Border color of the button

package/dist/components/buttonsimple/buttonsimple.component.js

@@ -18,28 +18,6 @@ import { KeyDownHandledMixin } from '../../utils/mixins/KeyDownHandledMixin';
 import { BUTTON_TYPE, DEFAULTS } from './buttonsimple.constants';
 import styles from './buttonsimple.styles';
 /**
- * `mdc-buttonsimple` is a simple button component that can be configured in various ways to suit different use cases.
- * It can be used standalone or as a base for more complex button components like `mdc-button`.
- *
- * ### Button Types
- *
- * The button type defines the behavior when clicked:
- *
- * - **button**: Standard button that performs an action on click
- * - **submit**: Submits the form data to the server
- * - **reset**: Resets the form data to its initial state
- *
- * ### Active State
- *
- * The `active` attribute toggles the button's active/toggled state,
- * automatically setting the appropriate ARIA state (e.g., `aria-pressed`).
- * This is useful for toggle buttons or buttons indicating a selected state.
- *
- * ### Disabled States
- *
- * - **disabled**: Completely disables the button, removing it from the tab order
- * - **soft-disabled**: Button appears disabled but remains focusable for accessibility
- *
  * @tagname mdc-buttonsimple
  *
  * @slot - Text label of the button.

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

@@ -3,21 +3,27 @@ import { Component } from '../../models';
 import type { SelectionMode } from './calendar.types';
 declare const Calendar_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyDownHandledMixin").KeyDownHandledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & typeof Component;
 /**
- * mdc-calendar is a component that displays a monthly calendar grid
- * allowing users to select dates, weeks, or date ranges.
- *
- * The component supports three selection modes:
- * - `single`: Select a single date
- * - `week`: Select an entire week
- * - `range`: Select a date range (start and end)
- *
+ * The calendar renders a month-by-month grid that lets users select a single date, an entire week, or a date range. It is keyboard-navigable, respects locale-defined week start and date formatting, and constrains selection to an optional `min`/`max` window.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-calendar` when the surface needs to display a full month grid for date selection — for example a standalone scheduler view or the calendar panel of a custom date picker.
+ * - Use the `week` selection mode to pick an entire week (Mon–Sun, locale dependent).
+ * - Use the `range` selection mode for booking-style flows where the user picks a start and an end date.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-datepicker` when you need an input field paired with a popover calendar; `mdc-calendar` is the grid only, not the input/popover wrapper.
+ * - Use `mdc-timepicker` for time-of-day selection without a calendar surface.
+ * - Use a plain `mdc-select`, `mdc-input`, or `mdc-combobox` when the user only needs to type or pick a textual value rather than navigate dates.
+ * 
  * @tagname mdc-calendar
- *
+ * 
  * @dependency mdc-button
- *
+ * 
  * @event date-selected - Fires when a date or date range is selected.
  * @event month-changed - Fires when the displayed month changes.
- *
+ * 
  * @cssproperty --mdc-calendar-background-color - Background color of the calendar.
  * @cssproperty --mdc-calendar-text-color - Text color of the calendar.
  * @cssproperty --mdc-calendar-day-selected-bg - Background color of selected days.

package/dist/components/calendar/calendar.component.js

@@ -20,14 +20,6 @@ import { CALENDAR_ICONS, DEFAULTS, SELECTION_MODE } from './calendar.constants';
 import styles from './calendar.styles';
 import { formatDateRangeForDisplay, generateCalendarGrid, getDatesInRange, getMonthYearLabel, getWeekdayNames, getWeekRange, } from './calendar.utils';
 /**
- * mdc-calendar is a component that displays a monthly calendar grid
- * allowing users to select dates, weeks, or date ranges.
- *
- * The component supports three selection modes:
- * - `single`: Select a single date
- * - `week`: Select an entire week
- * - `range`: Select a date range (start and end)
- *
  * @tagname mdc-calendar
  *
  * @dependency mdc-button

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

@@ -2,24 +2,25 @@ import { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
 declare const Card_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/CardComponentMixin").CardComponentMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FooterMixin").FooterMixinInterface> & typeof Component;
 /**
- * The card component allows users to organize information in a structured and tangible
- * format that is visually appealing. `mdc-card` is a static component.
- *
- * ## Card Structure
- * - **Image**: Optional visual content at the top
- * - **Header**: Contains icon, title, subtitle, and action buttons
- * - **Body**: Main text content area
- * - **Footer**: Optional footer with links and buttons
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal) and three visual variants (border, ghost, and promotional).
- * - Can be made interactive by adding elements to slots like `icon-button`, `footer-link`, and footer buttons.
- *
+ * The card groups related content — image, title and subtitle, body text, header action icons, and footer link/buttons — into a single visually contained surface. It is a static container: it has no built-in click handler or selection state, and is laid out either vertically (default, narrow) or horizontally (wide).
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-card` to present a self-contained piece of content (a record, a tile in a gallery, an information panel) with consistent padding, header, body, and footer regions.
+ * - Use the `promotional` variant for marketing, upsell, or feature-highlight surfaces; use `ghost` when the surrounding layout already provides the visual container; otherwise keep the default `border` variant.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-cardbutton` when the entire card should act as a single click target.
+ * - Use `mdc-cardcheckbox` or `mdc-cardradio` when the card represents a selectable option inside a form (multi-select / single-select).
+ * - Use `mdc-listitem` inside `mdc-list` when the content is a row of a scrolling list rather than a standalone tile.
+ * - Use `mdc-banner` or `mdc-toast` when the content is a transient or status message rather than a persistent record.
+ * 
  * @tagname mdc-card
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @slot image - This slot is for overriding the image content of the card
  * @slot before-body - This slot is for passing the content before the body
  * @slot body - This slot is for passing the text content for the card
@@ -34,7 +35,7 @@ declare const Card_base: import("../../utils/mixins/index.types").Constructor<im
  * within the footer section.
  * @slot footer -  This slot is for passing custom footer content. Only use this if really needed,
  * using the footer-link and footer-button slots is preferred.
- *
+ * 
  * @csspart header - The header part of the card
  * @csspart icon - The icon part of the card header
  * @csspart body - The body part of the card
@@ -45,7 +46,7 @@ declare const Card_base: import("../../utils/mixins/index.types").Constructor<im
  * @csspart footer-button-secondary - The secondary button part of the card footer
  * @csspart icon-button - The icon button part of the card header
  * @csspart text - The text part of the card
- *
+ * 
  * @cssproperty --mdc-card-width - The width of the card
  */
 declare class Card extends Card_base {

package/dist/components/card/card.component.js

@@ -16,19 +16,6 @@ import { FooterMixin } from '../../utils/mixins/FooterMixin';
 import { DEFAULTS } from './card.constants';
 import styles from './card.styles';
 /**
- * The card component allows users to organize information in a structured and tangible
- * format that is visually appealing. `mdc-card` is a static component.
- *
- * ## Card Structure
- * - **Image**: Optional visual content at the top
- * - **Header**: Contains icon, title, subtitle, and action buttons
- * - **Body**: Main text content area
- * - **Footer**: Optional footer with links and buttons
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal) and three visual variants (border, ghost, and promotional).
- * - Can be made interactive by adding elements to slots like `icon-button`, `footer-link`, and footer buttons.
- *
  * @tagname mdc-card
  *
  * @dependency mdc-icon

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

@@ -2,20 +2,26 @@ import { CSSResult } from 'lit';
 import Buttonsimple from '../buttonsimple/buttonsimple.component';
 declare const CardButton_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/CardComponentMixin").CardComponentMixinInterface> & typeof Buttonsimple;
 /**
- * cardbutton component looks like a card and behaves as a button component.
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal) and three visual variants (border, ghost, and promotional).
- * - Interacting anywhere on the card triggers the click event.
- * - Use `name` and `value` attributes when using within forms.
- *
- * **Note**: Only pass non-interactable elements within the slots to avoid nested interactive elements.
- *
+ * The card button looks like a card (image, header with icon/title/subtitle, body) but acts as one large button. Clicking, pressing `Enter`, or pressing `Space` anywhere on the card surface dispatches a `click` event. Use it when the entire tile should be a single activation target.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-cardbutton` when the whole tile is a clickable target — a navigation tile, a "create new" surface, or an action card in a grid where the user expects to click anywhere on the card.
+ * - Use the `name` and `value` attributes when the card button needs to participate in a form submission.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-card` when the surface is a static container and only specific children are interactive.
+ * - Use `mdc-cardcheckbox` when the card represents a multi-select option inside a form.
+ * - Use `mdc-cardradio` when the card represents a single-select option inside a group.
+ * - Use `mdc-listitem` inside `mdc-list` when the content is a row of a scrolling list rather than a standalone tile.
+ * - Use `mdc-button` when the action does not warrant a card-sized surface (no image, no header, no body content).
+ * 
  * @tagname mdc-cardbutton
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @slot image - This slot is for overriding the image content of the card
  * @slot before-body - This slot is for passing the content before the body
  * @slot body - This slot is for passing the text content for the card
@@ -24,14 +30,14 @@ declare const CardButton_base: import("../../utils/mixins/index.types").Construc
  * @slot subtitle - This slot is for passing the subtitle of the card in the header section
  * @slot footer-link - This slot is for passing `mdc-link` component within the footer section.
  * @slot footer-button-primary - This slot is for passing primary variant of `mdc-button` component within the footer section.
- *
+ * 
  * @event click - (React: onClick) Event that gets dispatched when the card is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the card.
  * It fires the click event when enter key is used.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the card.
  * It fires the click event when space key is used.
  * @event focus - (React: onFocus) Event that gets dispatched when the card receives focus.
- *
+ * 
  * @csspart header - The header part of the card
  * @csspart icon - The icon part of the card header
  * @csspart body - The body part of the card
@@ -42,7 +48,7 @@ declare const CardButton_base: import("../../utils/mixins/index.types").Construc
  * @csspart footer-button-secondary - The secondary button part of the card footer
  * @csspart icon-button - The icon button part of the card header
  * @csspart text - The text part of the card
- *
+ * 
  * @cssproperty --mdc-card-width - The width of the card
  */
 declare class CardButton extends CardButton_base {

package/dist/components/cardbutton/cardbutton.component.js

@@ -4,15 +4,6 @@ import Card from '../card/card.component';
 import { CardComponentMixin } from '../../utils/mixins/CardComponentMixin';
 import styles from './cardbutton.styles';
 /**
- * cardbutton component looks like a card and behaves as a button component.
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal) and three visual variants (border, ghost, and promotional).
- * - Interacting anywhere on the card triggers the click event.
- * - Use `name` and `value` attributes when using within forms.
- *
- * **Note**: Only pass non-interactable elements within the slots to avoid nested interactive elements.
- *
  * @tagname mdc-cardbutton
  *
  * @dependency mdc-icon

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

@@ -3,26 +3,27 @@ import Card from '../card/card.component';
 import type { SelectionType } from './cardcheckbox.types';
 declare const CardCheckbox_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/DisabledMixin").DisabledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/TabIndexMixin").TabIndexMixinInterface> & typeof Card;
 /**
- * cardcheckbox component extends `mdc-card` and supports checkbox selection interaction.
- * Multiple cards can be checked simultaneously.
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal), three visual variants (border, ghost, and promotional), and two selection types (check icon or checkbox component).
- * - Interacting anywhere on the card toggles the checked state and dispatches a `change` event.
- * - Card has `role="checkbox"` and manages `aria-checked` and `aria-disabled` attributes automatically.
- *
- * ## Usage
- * - The `card-title` attribute is required.
- * - When using within a form or group, wrap cards in a container with `role="group"` and provide an `aria-label`.
- *
- * **Note**: Only pass non-interactable elements within the slots to avoid nested interactive elements.
- *
+ * The card checkbox looks like a card (image, header with icon/title/subtitle, body) but behaves as a single checkbox. Clicking anywhere on the card, pressing `Enter`, or pressing `Space` toggles the `checked` state and dispatches a `change` event. Multiple card checkboxes in a group can be checked at the same time.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-cardcheckbox` when each option in a multi-select group needs the visual weight of a card (image, title, supporting copy) rather than a small inline control.
+ * - Use it inside a labelled group container (`role="group"` + `aria-label` / `aria-labelledby`) when several card checkboxes belong to the same selection set.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-card` when the surface is a static container and should not toggle a selection state.
+ * - Use `mdc-cardbutton` when activating the card should trigger an action rather than toggle a selection.
+ * - Use `mdc-cardradio` when only one card in the group can be selected at a time.
+ * - Use `mdc-checkbox` (or `mdc-staticcheckbox`) when a plain control is enough and the card surface is unnecessary.
+ * - Use `mdc-listitem` inside `mdc-list` when the content is a row of a scrolling list rather than a standalone selectable tile.
+ * 
  * @tagname mdc-cardcheckbox
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-staticcheckbox
  * @dependency mdc-text
- *
+ * 
  * @slot before-body - This slot is for passing the content before the body
  * @slot body - This slot is for passing the text content for the card
  * @slot after-body - This slot is for passing the content after the body
@@ -30,7 +31,7 @@ declare const CardCheckbox_base: import("../../utils/mixins/index.types").Constr
  * @slot subtitle - This slot is for passing the subtitle of the card in the header section
  * @slot footer-link - This slot is for passing `mdc-link` component within the footer section.
  * @slot footer-button-primary - This slot is for passing primary variant of `mdc-button` component within the footer section.
- *
+ * 
  * @event click - (React: onClick) Event that gets dispatched when the card is clicked. It toggles the checked state.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the card.
  * It toggles the checked state when enter key is used.
@@ -38,7 +39,7 @@ declare const CardCheckbox_base: import("../../utils/mixins/index.types").Constr
  * It toggles the checked state when space key is used.
  * @event focus - (React: onFocus) Event that gets dispatched when the card receives focus.
  * @event change - (React: onChange) Event that gets dispatched when the card's checked state changes.
- *
+ * 
  * @csspart header - The header part of the card
  * @csspart icon - The icon part of the card header
  * @csspart body - The body part of the card
@@ -52,7 +53,7 @@ declare const CardCheckbox_base: import("../../utils/mixins/index.types").Constr
  * @csspart check - The check part of the card
  * @csspart check-icon - The check icon part of the card
  * @csspart check-icon-button - The check icon button part of the card
- *
+ * 
  * @cssproperty --mdc-card-width - The width of the card
  */
 declare class CardCheckbox extends CardCheckbox_base {

package/dist/components/cardcheckbox/cardcheckbox.component.js

@@ -18,20 +18,6 @@ import { KeyDownHandledMixin } from '../../utils/mixins/KeyDownHandledMixin';
 import { CHECK_MARK, DEFAULTS, SELECTION_TYPE } from './cardcheckbox.constants';
 import styles from './cardcheckbox.styles';
 /**
- * cardcheckbox component extends `mdc-card` and supports checkbox selection interaction.
- * Multiple cards can be checked simultaneously.
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal), three visual variants (border, ghost, and promotional), and two selection types (check icon or checkbox component).
- * - Interacting anywhere on the card toggles the checked state and dispatches a `change` event.
- * - Card has `role="checkbox"` and manages `aria-checked` and `aria-disabled` attributes automatically.
- *
- * ## Usage
- * - The `card-title` attribute is required.
- * - When using within a form or group, wrap cards in a container with `role="group"` and provide an `aria-label`.
- *
- * **Note**: Only pass non-interactable elements within the slots to avoid nested interactive elements.
- *
  * @tagname mdc-cardcheckbox
  *
  * @dependency mdc-icon

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

@@ -2,27 +2,27 @@ import { CSSResult, PropertyValues } from 'lit';
 import Card from '../card/card.component';
 declare const CardRadio_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/DisabledMixin").DisabledMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/TabIndexMixin").TabIndexMixinInterface> & typeof Card;
 /**
- * cardradio component extends `mdc-card` and supports radio selection interaction.
- * Only one card can be selected at a time within the same group (defined by `name` attribute).
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal) and three visual variants (border, ghost, and promotional).
- * - Selecting a card automatically unselects other cards in the same group and dispatches a `change` event.
- * - Supports keyboard navigation with arrow keys to move between cards in the same group.
- * - Card has `role="radio"` and manages `aria-checked` and `aria-disabled` attributes automatically.
- *
- * ## Usage
- * - Both `card-title` and `name` attributes are required.
- * - When using within a form or group, wrap cards in a container with `role="radiogroup"` and provide an `aria-label`.
- *
- * **Note**: Only pass non-interactable elements within the slots to avoid nested interactive elements.
- *
+ * The card radio looks like a card (image, header with icon/title/subtitle, body) but behaves as a single radio option. Cards sharing the same `name` form a group: clicking, pressing `Enter`, or pressing `Space` on one card selects it and clears the others. Arrow keys move focus and selection between enabled cards in the group.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-cardradio` when each option in a single-select group needs the visual weight of a card (image, title, supporting copy) rather than a small inline control.
+ * - Use it inside a labelled radio-group container (`role="radiogroup"` + `aria-label` / `aria-labelledby`) when several card radios belong to the same selection set.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-card` when the surface is a static container and should not represent a selection.
+ * - Use `mdc-cardbutton` when activating the card should trigger an action rather than select an option.
+ * - Use `mdc-cardcheckbox` when more than one card in the group can be selected at the same time.
+ * - Use `mdc-radio` (or `mdc-radiogroup`) when a plain control is enough and the card surface is unnecessary.
+ * - Use `mdc-listitem` inside `mdc-list` when the content is a row of a scrolling list rather than a standalone selectable tile.
+ * 
  * @tagname mdc-cardradio
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-staticradio
  * @dependency mdc-text
- *
+ * 
  * @slot before-body - This slot is for passing the content before the body
  * @slot body - This slot is for passing the text content for the card
  * @slot after-body - This slot is for passing the content after the body
@@ -30,7 +30,7 @@ declare const CardRadio_base: import("../../utils/mixins/index.types").Construct
  * @slot subtitle - This slot is for passing the subtitle of the card in the header section
  * @slot footer-link - This slot is for passing `mdc-link` component within the footer section.
  * @slot footer-button-primary - This slot is for passing primary variant of `mdc-button` component within the footer section.
- *
+ * 
  * @event click - (React: onClick) Event that gets dispatched when the card is clicked. It selects the card and unselects others in the same group.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the card.
  * It selects the card when enter key or arrow keys are used.
@@ -38,7 +38,7 @@ declare const CardRadio_base: import("../../utils/mixins/index.types").Construct
  * It selects the card when space key is used.
  * @event focus - (React: onFocus) Event that gets dispatched when the card receives focus.
  * @event change - (React: onChange) Event that gets dispatched when the card's checked state changes.
- *
+ * 
  * @csspart header - The header part of the card
  * @csspart icon - The icon part of the card header
  * @csspart body - The body part of the card
@@ -52,7 +52,7 @@ declare const CardRadio_base: import("../../utils/mixins/index.types").Construct
  * @csspart check - The check part of the card
  * @csspart check-icon - The check icon part of the card
  * @csspart check-icon-button - The check icon button part of the card
- *
+ * 
  * @cssproperty --mdc-card-width - The width of the card
  */
 declare class CardRadio extends CardRadio_base {

package/dist/components/cardradio/cardradio.component.js

@@ -18,21 +18,6 @@ import { KeyToActionMixin, ACTIONS } from '../../utils/mixins/KeyToActionMixin';
 import { KeyDownHandledMixin } from '../../utils/mixins/KeyDownHandledMixin';
 import styles from './cardradio.styles';
 /**
- * cardradio component extends `mdc-card` and supports radio selection interaction.
- * Only one card can be selected at a time within the same group (defined by `name` attribute).
- *
- * ## Features
- * - Supports two orientations (vertical and horizontal) and three visual variants (border, ghost, and promotional).
- * - Selecting a card automatically unselects other cards in the same group and dispatches a `change` event.
- * - Supports keyboard navigation with arrow keys to move between cards in the same group.
- * - Card has `role="radio"` and manages `aria-checked` and `aria-disabled` attributes automatically.
- *
- * ## Usage
- * - Both `card-title` and `name` attributes are required.
- * - When using within a form or group, wrap cards in a container with `role="radiogroup"` and provide an `aria-label`.
- *
- * **Note**: Only pass non-interactable elements within the slots to avoid nested interactive elements.
- *
  * @tagname mdc-cardradio
  *
  * @dependency mdc-icon

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

@@ -4,38 +4,34 @@ import FormfieldWrapper from '../formfieldwrapper/formfieldwrapper.component';
 import type { CheckboxValidationType } from './checkbox.types';
 declare const Checkbox_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("../../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> & typeof FormfieldWrapper;
 /**
- * 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.
@@ -47,7 +43,7 @@ declare const Checkbox_base: import("../../utils/mixins/index.types").Constructo
  * @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 class Checkbox extends Checkbox_base implements AssociatedFormControl {

package/dist/components/checkbox/checkbox.component.js

@@ -20,26 +20,7 @@ import { KeyDownHandledMixin } from '../../utils/mixins/KeyDownHandledMixin';
 import styles from './checkbox.styles';
 import { CHECKBOX_VALIDATION } from './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
@@ -47,8 +28,6 @@ import { CHECKBOX_VALIDATION } from './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.
  *