@momentum-design/components 0.134.19 → 0.134.21

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

@@ -4,59 +4,37 @@ import type { AutoCapitalizeType } from '../input/input.types';
 import type { WrapType, AutoCompleteType } from './textarea.types';
 declare const Textarea_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/CharacterLimitMixin").CharacterLimitMixinInterface> & 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;
 /**
- * mdc-textarea component, which is used to get the multi-line text input from the user.
- * It contains:
- * - label: It is the title of the textarea field.
- * - required: A boolean attribute depicting that the textarea field is required.
- * - Textarea: It is the multi-line text input field.
- * - helper-text: It is the text that provides additional information about the textarea field.
- * - max-character-limit: It is the text that shows the character count of the textarea field.
- * - Error, Warning, Success, Priority Help Text type: It is the text that provides additional information
- *   about the textarea field based on the validation state.
- * - limitexceeded: It is the event that is dispatched when the character limit exceeds or restored.
- *   This event exposes 3 properties:
- *   - currentCharacterCount - the current number of characters in the textarea field,
- *   - maxCharacterLimit - the maximum number of characters allowed in the textarea field,
- *   - value - the current value of the textarea field,
- *
- * **Note**: Consumers must set the help-text-type with 'error' and
- * help-text attribute with the error message using limitexceeded event.
- * The same help-text value will be used for the validation message to be displayed.
- *
- * ### Accessibility
- *
- * #### Resize
- *
- * Accessible text area resizing can be turned on with the `resizable`.
- * It is strongly recommended to set the `resize-button-aria-label` attribute as well to describe what it is and what are the shortcuts (up/down arrows) of the button.
- *
- * #### Best practices
- *
- * - Always provide a `label` for screen readers to identify the textarea's purpose
- * - Use `help-text` to provide additional context or instructions
- * - When using `max-character-limit`, consider providing `character-limit-announcement` for screen reader updates
- * - Use appropriate `help-text-type` (error, warning, success) to convey validation state
- * - Ensure `validation-message` is set for form validation errors
- *
+ * The textarea is a form-associated multi-line text input. It renders a label, an optional info toggletip, the multi-line input, an optional character counter, helper or validation text, and an optional resize button that grows or shrinks the visible rows.
+ * 
+ * **When to use**
+ * 
+ * - Use when users need to enter free-form text that may span multiple lines (messages, comments, descriptions).
+ * - Use when you want consistent label, helper-text, validation, and character-count chrome around a multi-line input.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use for short, single-line inputs — use `mdc-input` instead.
+ * - Do not use for structured values (email, time, password); use the dedicated form components.
+ * 
  * @tagname mdc-textarea
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the value of the textarea field changes (every press).
  * @event change - (React: onChange) This event is dispatched when the value of the textarea field changes (on blur).
  * @event focus - (React: onFocus) This event is dispatched when the textarea receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the textarea loses focus.
  * @event limitexceeded - (React: onLimitExceeded) This event is dispatched once when the character limit
  * exceeds or restored.
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
+ * 
  * @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.
- *
+ * 
  * @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.
@@ -70,7 +48,7 @@ declare const Textarea_base: import("../../utils/mixins/index.types").Constructo
  * @csspart help-text - The helper/validation text element.
  * @csspart helper-icon - The helper/validation icon element that is displayed next to the helper/validation text.
  * @csspart help-text-container - The container for the helper/validation icon and text elements.
- *
+ * 
  * @cssproperty --mdc-label-font-size - Font size for the label text.
  * @cssproperty --mdc-label-font-weight - Font weight for the label text.
  * @cssproperty --mdc-label-line-height - Line height for the label text.

package/dist/components/textarea/textarea.component.js

@@ -22,40 +22,6 @@ import { CharacterLimitMixin } from '../../utils/mixins/CharacterLimitMixin';
 import { AUTO_COMPLETE, WRAP, DEFAULTS } from './textarea.constants';
 import styles from './textarea.styles';
 /**
- * mdc-textarea component, which is used to get the multi-line text input from the user.
- * It contains:
- * - label: It is the title of the textarea field.
- * - required: A boolean attribute depicting that the textarea field is required.
- * - Textarea: It is the multi-line text input field.
- * - helper-text: It is the text that provides additional information about the textarea field.
- * - max-character-limit: It is the text that shows the character count of the textarea field.
- * - Error, Warning, Success, Priority Help Text type: It is the text that provides additional information
- *   about the textarea field based on the validation state.
- * - limitexceeded: It is the event that is dispatched when the character limit exceeds or restored.
- *   This event exposes 3 properties:
- *   - currentCharacterCount - the current number of characters in the textarea field,
- *   - maxCharacterLimit - the maximum number of characters allowed in the textarea field,
- *   - value - the current value of the textarea field,
- *
- * **Note**: Consumers must set the help-text-type with 'error' and
- * help-text attribute with the error message using limitexceeded event.
- * The same help-text value will be used for the validation message to be displayed.
- *
- * ### Accessibility
- *
- * #### Resize
- *
- * Accessible text area resizing can be turned on with the `resizable`.
- * It is strongly recommended to set the `resize-button-aria-label` attribute as well to describe what it is and what are the shortcuts (up/down arrows) of the button.
- *
- * #### Best practices
- *
- * - Always provide a `label` for screen readers to identify the textarea's purpose
- * - Use `help-text` to provide additional context or instructions
- * - When using `max-character-limit`, consider providing `character-limit-announcement` for screen reader updates
- * - Use appropriate `help-text-type` (error, warning, success) to convey validation state
- * - Ensure `validation-message` is set for form validation errors
- *
  * @tagname mdc-textarea
  *
  * @event input - (React: onInput) This event is dispatched when the value of the textarea field changes (every press).

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

@@ -2,35 +2,21 @@ import { CSSResult } from 'lit';
 import { Provider } from '../../models';
 import ThemeProviderContext from './themeprovider.context';
 /**
- * ThemeProvider component, which sets the passed in themeclass as class.
- * If the themeclass switches, the existing themeclass will be removed as a class
- * and the new themeclass will be added.
- *
- * CSS variables defined in the themeclass will be used for the styling of child dom nodes.
- *
- * Available Momentum theme classes:
- *
- * `mds-theme-stable-darkWebex`, `mds-theme-stable-lightWebex`
- *
- * `mds-theme-stable-darkBronzeWebex`, `mds-theme-stable-lightBronzeWebex`
- *
- * `mds-theme-stable-darkIndigoWebex`, `mds-theme-stable-lightIndigoWebex`
- *
- * `mds-theme-stable-darkJadeWebex`, `mds-theme-stable-lightJadeWebex`
- *
- * `mds-theme-stable-darkLavenderWebex`, `mds-theme-stable-lightLavenderWebex`
- *
- * `mds-theme-stable-darkRoseWebex`, `mds-theme-stable-lightRoseWebex`
- *
- * Themeclass context can be be consumed from Lit child components
- * (see providerUtils.consume for how to consume)
- *
- * ThemeProvider also includes basic font defaults for text.
- *
+ * The theme provider applies a Momentum theme class to its host element and exposes it as a context for descendant Lit components. CSS variables defined by the theme class drive token-based styling (colour, fonts, scrollbar). It also sets sensible defaults for text rendering (font family, weight, default text colour).
+ * 
+ * **When to use**
+ * 
+ * - Wrap the section of the app that should render with Momentum tokens. A single provider at the application root is the most common pattern.
+ * - Use nested providers to render a region (for example a modal or preview pane) with a different theme — switching themes adds the new class and removes the previous one automatically.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use to scope behaviour unrelated to theming.
+ * 
  * @tagname mdc-themeprovider
- *
+ * 
  * @slot - children
- *
+ * 
  * @cssproperty --mdc-themeprovider-color-default - Option to override the default color,
  * default: color-theme-text-primary-normal
  * @cssproperty --mdc-themeprovider-font-family - Option to override the font family,

package/dist/components/themeprovider/themeprovider.component.js

@@ -13,31 +13,6 @@ import { DEFAULTS } from './themeprovider.constants';
 import ThemeProviderContext from './themeprovider.context';
 import styles from './themeprovider.styles';
 /**
- * ThemeProvider component, which sets the passed in themeclass as class.
- * If the themeclass switches, the existing themeclass will be removed as a class
- * and the new themeclass will be added.
- *
- * CSS variables defined in the themeclass will be used for the styling of child dom nodes.
- *
- * Available Momentum theme classes:
- *
- * `mds-theme-stable-darkWebex`, `mds-theme-stable-lightWebex`
- *
- * `mds-theme-stable-darkBronzeWebex`, `mds-theme-stable-lightBronzeWebex`
- *
- * `mds-theme-stable-darkIndigoWebex`, `mds-theme-stable-lightIndigoWebex`
- *
- * `mds-theme-stable-darkJadeWebex`, `mds-theme-stable-lightJadeWebex`
- *
- * `mds-theme-stable-darkLavenderWebex`, `mds-theme-stable-lightLavenderWebex`
- *
- * `mds-theme-stable-darkRoseWebex`, `mds-theme-stable-lightRoseWebex`
- *
- * Themeclass context can be be consumed from Lit child components
- * (see providerUtils.consume for how to consume)
- *
- * ThemeProvider also includes basic font defaults for text.
- *
  * @tagname mdc-themeprovider
  *
  * @slot - children

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

@@ -7,46 +7,44 @@ import type { IconNames } from '../icon/icon.types';
 import type { OptionLabelFormatter, Placement, TimeFormat } from './timepicker.types';
 declare const TimePicker_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-timepicker is a component that allows users to select a specific time
- * or enter a time manually. It supports both 12-hour and 24-hour formats.
- *
- * The component consists of:
- * - label - describes the time picker field
- * - input field - made up of 2-3 spinbuttons (hours, minutes, optional AM/PM period)
- * - dropdown arrow button - opens a flyout menu with predefined time intervals
- * - helper text - displayed below the input field
- *
- * Users can input values by:
- * - Manually entering numbers/characters in spinbuttons
- * - Navigating using arrow keys to increment/decrement values
- * - Selecting a predefined time from the dropdown menu
- *
+ * The time picker is a composite form control for selecting a time. It exposes hour, minute, and (in 12-hour mode) AM/PM segments as ARIA spinbuttons that accept arrow-key adjustments and direct digit input, plus a dropdown arrow button that opens a list of preset times at a configurable interval.
+ * 
+ * **When to use**
+ * 
+ * - Use when users need to enter or pick a time of day, manually or from a preset list.
+ * - Use inside a form when the time value should participate in form submission and validation.
+ * 
+ * **When not to use**
+ * 
+ * - Do not use for date selection — use `mdc-datepicker` instead.
+ * - Do not use when you only need a free-form text field.
+ * 
  * @tagname mdc-timepicker
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-option
  * @dependency mdc-popover
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
+ * 
  * @event input - (React: onInput) This event is dispatched when the time value changes.
  * @event change - (React: onChange) This event is dispatched when the time value is committed.
  * @event focus - (React: onFocus) This event is dispatched when the timepicker receives focus.
  * @event blur - (React: onBlur) This event is dispatched when the timepicker 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-timepicker-background-color - Background color of the timepicker input.
  * @cssproperty --mdc-timepicker-border-color - Border color of the timepicker input.
  * @cssproperty --mdc-timepicker-text-color - Text color of the timepicker input.
  * @cssproperty --mdc-timepicker-height - The height of the timepicker trigger control.
  * @cssproperty --mdc-timepicker-width - Width of the timepicker component.
  * @cssproperty --mdc-timepicker-listbox-height - The max-height of the dropdown listbox. Default shows ~6 items.
- *
+ * 
  * @csspart label - The label element.
  * @csspart label-text - The container for the label and required indicator elements.
  * @csspart required-indicator - The required indicator element.

package/dist/components/timepicker/timepicker.component.js

@@ -18,20 +18,6 @@ import { POPOVER_PLACEMENT, TRIGGER, DEFAULTS as POPOVER_DEFAULTS } from '../pop
 import { ARROW_ICON, DEFAULTS, TIME_FORMAT, TRIGGER_ID, LISTBOX_ID } from './timepicker.constants';
 import styles from './timepicker.styles';
 /**
- * mdc-timepicker is a component that allows users to select a specific time
- * or enter a time manually. It supports both 12-hour and 24-hour formats.
- *
- * The component consists of:
- * - label - describes the time picker field
- * - input field - made up of 2-3 spinbuttons (hours, minutes, optional AM/PM period)
- * - dropdown arrow button - opens a flyout menu with predefined time intervals
- * - helper text - displayed below the input field
- *
- * Users can input values by:
- * - Manually entering numbers/characters in spinbuttons
- * - Navigating using arrow keys to increment/decrement values
- * - Selecting a predefined time from the dropdown menu
- *
  * @tagname mdc-timepicker
  *
  * @dependency mdc-button

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

@@ -5,27 +5,35 @@ import type { TagName } from '../text/text.types';
 import type { ToastVariant } from './toast.types';
 declare const Toast_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/FooterMixin").FooterMixinInterface> & typeof Component;
 /**
- * `mdc-toast` is a lightweight, non-blocking alert used to inform users about application processes.
- * It supports success, warning, error, and custom messages, and is designed to be controlled externally.
- *
- * **Note**: When using `slot="toast-body-normal"` and `slot="toast-body-detailed"`, it's strongly recommended to wrap the content with `<mdc-text tagname="span">`.
- * If not used, ensure your custom content is styled appropriately to match the design and alignment expectations of the toast component.
- *
+ * `mdc-toast` is a lightweight, non-blocking alert used to inform users about application processes. It supports `success`, `warning`, `error`, and `custom` variants, can optionally collapse/expand a detailed body, and is designed to be controlled externally (the host application decides when to show, hide, or auto-dismiss it).
+ * 
+ * **When to use**
+ * 
+ * - Surface short status messages about background or asynchronous processes (success confirmations, recoverable errors, warnings).
+ * - Provide a place to expose primary/secondary actions tied to a transient notification (e.g. "Undo", "Retry").
+ * - Show detailed information that the user can optionally expand via a show more/show less toggle.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-banner` for persistent, in-flow messaging tied to a region of the page.
+ * - Use `mdc-announcementdialog` or `mdc-dialog` for modal interruptions that require acknowledgement.
+ * - Use `mdc-alertchip` for status indicators inline with content rather than a floating notification surface.
+ * 
+ * @tagname mdc-toast
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
  * @dependency mdc-button
- *
+ * 
  * @slot content-prefix - Slot for custom content before the icon (only for custom variant).
  * @slot toast-body-normal - Slot for the main body content of the toast.
  * @slot toast-body-detailed - Slot for additional detailed content, shown when expanded.
  * @slot footer - Slot for custom footer content. Prefer using footer-button-primary and footer-button-secondary slots.
  * @slot footer-button-primary - Slot for passing the primary variant of `mdc-button` in the footer.
  * @slot footer-button-secondary - Slot for passing the secondary variant of `mdc-button` in the footer.
- *
- * @tagname mdc-toast
- *
+ * 
  * @event close - (React: onClose) Dispatched when the Close Button is clicked using mouse or keyboard.
- *
+ * 
  * @csspart content-container - The container for the toast's main content, including icon, text, and close button.
  * @csspart toast-prefix-icon - The icon shown at the start of the toast, styled by variant.
  * @csspart toast-content - The container for the header and body content of the toast.
@@ -34,7 +42,7 @@ declare const Toast_base: import("../../utils/mixins/index.types").Constructor<i
  * @csspart footer-button-toggle - The toggle button for showing/hiding detailed content.
  * @csspart toast-close-btn - The close button for the toast.
  * @csspart has-footer-buttons - Applied to the footer when it contains buttons or a toggle button.
- *
+ * 
  * @cssproperty --mdc-toast-background-color - Background color of the toast.
  * @cssproperty --mdc-toast-border-color - Border color of the toast.
  * @cssproperty --mdc-toast-header-text-color - Color of the header text in the toast.

package/dist/components/toast/toast.component.js

@@ -18,11 +18,7 @@ import { DEFAULTS } from './toast.constants';
 import { getIconNameForVariant } from './toast.utils';
 import styles from './toast.styles';
 /**
- * `mdc-toast` is a lightweight, non-blocking alert used to inform users about application processes.
- * It supports success, warning, error, and custom messages, and is designed to be controlled externally.
- *
- * **Note**: When using `slot="toast-body-normal"` and `slot="toast-body-detailed"`, it's strongly recommended to wrap the content with `<mdc-text tagname="span">`.
- * If not used, ensure your custom content is styled appropriately to match the design and alignment expectations of the toast component.
+ * @tagname mdc-toast
  *
  * @dependency mdc-icon
  * @dependency mdc-text
@@ -35,8 +31,6 @@ import styles from './toast.styles';
  * @slot footer-button-primary - Slot for passing the primary variant of `mdc-button` in the footer.
  * @slot footer-button-secondary - Slot for passing the secondary variant of `mdc-button` in the footer.
  *
- * @tagname mdc-toast
- *
  * @event close - (React: onClose) Dispatched when the Close Button is clicked using mouse or keyboard.
  *
  * @csspart content-container - The container for the toast's main content, including icon, text, and close button.

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

@@ -4,37 +4,31 @@ import FormfieldWrapper from '../formfieldwrapper';
 import type { ToggleSize } from './toggle.types';
 declare const Toggle_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/KeyToActionMixin").KeyToActionInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/ControlTypeMixin").ControlTypeMixinInterface> & 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 Toggle component is an interactive control used to switch between two mutually exclusive states,
- * such as On/Off or Active/Inactive. It is commonly used in settings panels, forms, and preference selections
- * where users need to enable or disable a feature.
- *
- * To create a group of toggles, use the `mdc-formfieldgroup` component.
- *
- * **Note:** This component internally renders a native checkbox input element with the `switch` role, styled as a toggle switch.
- *
- * ## When to use
- * Use toggles for binary choices where the change takes effect immediately, such as enabling/disabling settings or features.
- *
- * ## Accessibility
- * - Provide clear labels that describe what the toggle 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-toggle` part to apply custom styles to the toggle switch visual element.
- * This part exposes the underlying [StaticToggle](?path=/docs/components-decorator-statictoggle--docs) component for advanced styling.
- *
+ * `mdc-toggle` is an interactive switch control used to flip between two mutually exclusive states, such as on/off or active/inactive. Changes take effect immediately and the component participates in HTML forms via the platform's element internals API.
+ * 
+ * **When to use**
+ * 
+ * - Binary settings where the change applies immediately (e.g. enabling a feature, switching a preference on or off).
+ * - Inside settings panels, preference dialogs, or forms where users need to flip a single option.
+ * - As a member of a group of related options grouped together via `mdc-formfieldgroup`.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-checkbox` for options that require an explicit submit step before they take effect, or for selecting multiple items from a list.
+ * - Use `mdc-radio` (with `mdc-radiogroup`) when a user must choose one of several mutually exclusive options.
+ * - Use `mdc-button` for one-off actions that don't represent a persistent state.
+ * 
+ * @tagname mdc-toggle
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-statictoggle
  * @dependency mdc-text
  * @dependency mdc-toggletip
- *
- * @tagname mdc-toggle
- *
+ * 
  * @event change - (React: onChange) Event that gets dispatched when the toggle state changes.
  * @event focus - (React: onFocus) Event that gets dispatched when the toggle 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.

package/dist/components/toggle/toggle.component.js

@@ -21,25 +21,7 @@ import { ACTIONS, KeyToActionMixin, NAV_MODES } from '../../utils/mixins/KeyToAc
 import { DEFAULTS, TOGGLE_SIZE } from './toggle.constants';
 import styles from './toggle.styles';
 /**
- * The Toggle component is an interactive control used to switch between two mutually exclusive states,
- * such as On/Off or Active/Inactive. It is commonly used in settings panels, forms, and preference selections
- * where users need to enable or disable a feature.
- *
- * To create a group of toggles, use the `mdc-formfieldgroup` component.
- *
- * **Note:** This component internally renders a native checkbox input element with the `switch` role, styled as a toggle switch.
- *
- * ## When to use
- * Use toggles for binary choices where the change takes effect immediately, such as enabling/disabling settings or features.
- *
- * ## Accessibility
- * - Provide clear labels that describe what the toggle 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-toggle` part to apply custom styles to the toggle switch visual element.
- * This part exposes the underlying [StaticToggle](?path=/docs/components-decorator-statictoggle--docs) component for advanced styling.
+ * @tagname mdc-toggle
  *
  * @dependency mdc-button
  * @dependency mdc-icon
@@ -47,8 +29,6 @@ import styles from './toggle.styles';
  * @dependency mdc-text
  * @dependency mdc-toggletip
  *
- * @tagname mdc-toggle
- *
  * @event change - (React: onChange) Event that gets dispatched when the toggle state changes.
  * @event focus - (React: onFocus) Event that gets dispatched when the toggle receives focus.
  *

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

@@ -2,43 +2,33 @@ import { CSSResult, PropertyValueMap } from 'lit';
 import Popover from '../popover/popover.component';
 import { PopoverPlacement } from '../popover/popover.types';
 /**
- * A toggletip is triggered by clicking a trigger element and can contain interactive content.
- * Unlike tooltips which disappear on blur, toggletips remain visible until explicitly dismissed
- * by clicking outside, pressing escape, or clicking the optional close button.
- *
- * Toggletips are ideal for displaying contextual help text, additional information, or interactive
- * elements like links and buttons that users need time to read and interact with.
- *
- * The component uses [mdc-screenreaderannouncer](?path=/docs/components-screenreaderannouncer--docs) internally to announce the toggletip content
- * to screen readers when shown, ensuring proper accessibility support.
- *
- * **Note:** This component extends the Popover component with toggletip-specific defaults.
- *
- * ## When to use
- * Use toggletips when you need to display interactive content or detailed information that requires
- * user interaction. For simple, non-interactive text hints, use tooltips instead.
- *
- * ## Accessibility
- * - Toggletip content is announced to screen readers when shown
- * - Use `screenreader-announcer-identity` attribute to control announcement placement in the DOM
- * - Focus is trapped within the toggletip when open, allowing navigation of interactive elements
- * - Keyboard shortcuts: Escape to close, Tab to move between elements
- * - Focus returns to the trigger element when the toggletip is closed
- *
+ * `mdc-toggletip` is a click-triggered overlay used to surface contextual help text or interactive content (links, buttons) next to a target element. It stays visible until the user dismisses it via the close button, an outside click, or the Escape key, and announces its content to screen readers when it appears.
+ * 
+ * **When to use**
+ * 
+ * - Reveal additional information or interactive controls that the user needs time to read or interact with (e.g. an info button next to a form label).
+ * - Group an action with a small amount of explanatory content that should remain visible after the user opens it.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-tooltip` for short, non-interactive hints that should appear on hover or focus and disappear automatically.
+ * - Use `mdc-popover` directly when you need full control over trigger semantics, placement defaults, or behavior beyond a click-triggered tip.
+ * - Use `mdc-dialog` for modal flows that require explicit user acknowledgement or block the rest of the page.
+ * 
+ * @tagname mdc-toggletip
+ * 
  * @dependency mdc-screenreaderannouncer
  * @dependency mdc-button
- *
- * @tagname mdc-toggletip
- *
+ * 
  * @event shown - (React: onShown) This event is dispatched when the toggletip is shown
  * @event hidden - (React: onHidden) This event is dispatched when the toggletip is hidden
  * @event created - (React: onCreated) This event is dispatched when the toggletip is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) This event is dispatched when the toggletip is destroyed (removed from the DOM)
- *
+ * 
  * @cssproperty --mdc-toggletip-max-width - The maximum width of the toggletip.
  * @cssproperty --mdc-toggletip-text-color - The text color of the toggletip.
  * @cssproperty --mdc-toggletip-text-color-contrast - The text color of the toggletip when the color is contrast.
- *
+ * 
  * @slot - Default slot for the toggletip content
  */
 declare class ToggleTip extends Popover {

package/dist/components/toggletip/toggletip.component.js

@@ -15,34 +15,11 @@ import { POPOVER_PLACEMENT } from '../popover/popover.constants';
 import { DEFAULTS } from './toggletip.constants';
 import styles from './toggletip.styles';
 /**
- * A toggletip is triggered by clicking a trigger element and can contain interactive content.
- * Unlike tooltips which disappear on blur, toggletips remain visible until explicitly dismissed
- * by clicking outside, pressing escape, or clicking the optional close button.
- *
- * Toggletips are ideal for displaying contextual help text, additional information, or interactive
- * elements like links and buttons that users need time to read and interact with.
- *
- * The component uses [mdc-screenreaderannouncer](?path=/docs/components-screenreaderannouncer--docs) internally to announce the toggletip content
- * to screen readers when shown, ensuring proper accessibility support.
- *
- * **Note:** This component extends the Popover component with toggletip-specific defaults.
- *
- * ## When to use
- * Use toggletips when you need to display interactive content or detailed information that requires
- * user interaction. For simple, non-interactive text hints, use tooltips instead.
- *
- * ## Accessibility
- * - Toggletip content is announced to screen readers when shown
- * - Use `screenreader-announcer-identity` attribute to control announcement placement in the DOM
- * - Focus is trapped within the toggletip when open, allowing navigation of interactive elements
- * - Keyboard shortcuts: Escape to close, Tab to move between elements
- * - Focus returns to the trigger element when the toggletip is closed
+ * @tagname mdc-toggletip
  *
  * @dependency mdc-screenreaderannouncer
  * @dependency mdc-button
  *
- * @tagname mdc-toggletip
- *
  * @event shown - (React: onShown) This event is dispatched when the toggletip is shown
  * @event hidden - (React: onHidden) This event is dispatched when the toggletip is hidden
  * @event created - (React: onCreated) This event is dispatched when the toggletip is created (added to the DOM)

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

@@ -3,31 +3,31 @@ import type { CSSResult } from 'lit';
 import Popover from '../popover/popover.component';
 import type { TooltipType } from './tooltip.types';
 /**
- * A Tooltip is a special type of popovers that provide additional context to content on the screen. <br/>
- * Tooltip is triggered by mouse hover or by keyboard focus and will disappear upon mouse exit or focus change.
- *
- * Because of this, tooltips cannot contain content that can be focused or interacted with.
- * When a tooltip must contain a focusable element like a link or button, use a toggle tip instead.
- *
- * A tooltip is triggered by mouse hover or by keyboard focus
- * and will disappear upon mouse exit or focus change.
- *
- * Note:
- *  - Tooltips cannot contain content that can be focused or interacted with.
- *  - Tooltips will contain the default `aria-hidden="true"` so that VO will never focus the tooltip.
- *
+ * `mdc-tooltip` is a lightweight overlay that surfaces a short, non-interactive hint about a target element. It opens on hover or keyboard focus of the trigger and disappears when the pointer leaves or focus moves away. It can be configured to act as the trigger's accessible description, label, or as a purely visual hint.
+ * 
+ * **When to use**
+ * 
+ * - Reveal short, text-only context for a control whose purpose isn't fully clear from its visual presentation (e.g. icon-only buttons).
+ * - Provide an accessible name or description for a trigger that has no visible label.
+ * - Show the full text of a truncated label only when it is actually overflowing.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-toggletip` when the content needs to remain visible after activation or includes interactive elements (links, buttons).
+ * - Use `mdc-popover` for richer overlay content, click-triggered surfaces, or when you need explicit control over open/close behavior.
+ * - Avoid tooltips for critical information — users on touch devices and some assistive technologies may not surface hover-triggered content.
+ * 
  * @tagname mdc-tooltip
- *
+ * 
  * @event shown - (React: onShown) This event is dispatched when the tooltip is shown
  * @event hidden - (React: onHidden) This event is dispatched when the tooltip is hidden
  * @event created - (React: onCreated) This event is dispatched when the tooltip is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) This event is dispatched when the tooltip is destroyed (removed from the DOM)
- *
+ * 
  * @cssproperty --mdc-tooltip-max-width - The maximum width of the tooltip.
  * @cssproperty --mdc-tooltip-padding - The padding of the tooltip.
  * @cssproperty --mdc-tooltip-text-color - The text color of the tooltip.
  * @cssproperty --mdc-tooltip-text-color-contrast - The text color of the tooltip when the color is contrast.
- *
  */
 declare class Tooltip extends Popover {
     /**