@momentum-design/components 0.134.19 → 0.134.21

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

@@ -1,22 +1,32 @@
 import type { CSSResult, PropertyValues } from 'lit';
 import AccordionButton from '../accordionbutton/accordionbutton.component';
 /**
+ * The accordion is a vertically stacked component with a header and an expandable/collapsible body section. The header displays an optional prefix icon, header text, optional leading and trailing control slots, and a dedicated expand/collapse button. Unlike `mdc-accordionbutton`, only the expand/collapse button is interactive — the rest of the header is not clickable.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-accordion` when you need additional interactive controls (chips, badges, buttons, icons) in the header alongside the expand/collapse behaviour.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-accordionbutton` instead when you only need a simple clickable header without extra controls in the header row.
+ * 
  * @tagname mdc-accordion
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @slot leading-header-text - The leading header text slot of the accordion on the header section. Placed after the prefix icon.
  * @slot leading-controls - The leading controls slot of the accordion on the header section. Placed after the header text.
  * @slot trailing-controls - The trailing controls slot of the accordion on the header section. Placed before the expand/collapse button.
  * @slot default - The default slot contains the body section of the accordion. User can place anything inside this body slot.
- *
+ * 
  * @event shown - (React: onShown) This event is triggered when the accordion is toggled (expanded or collapsed).
- *
+ * 
  * @cssproperty --mdc-accordionbutton-border-color - The border color of the accordion.
  * @cssproperty --mdc-accordionbutton-disabled-color - The disabled text color of the accordion.
- *
+ * 
  * @csspart body-section - The body section of the accordion.
  * @csspart header-section - The header section of the accordion.
  * @csspart leading-header - The leading header of the accordion.

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

@@ -6,43 +6,31 @@ import type { IconNames } from '../icon/icon.types';
 import type { IconName, Variant, TogglePosition } from './accordionbutton.types';
 declare const AccordionButton_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> & typeof Component;
 /**
- * An accordion button is a vertically stacked component with a clickable header and expandable/collapsible body section.
- * The entire header is clickable to toggle the visibility of the body content.
- *
- * ## Header contains
- * - Optional prefix icon
- * - Header text (default H3, customizable via `data-aria-level`)
- * - Expand/collapse arrow icon (visual indicator)
- *
- * ## Body contains
- * - Default slot for any content
- *
- * The accordion button supports different border styles through the `variant` attribute and different spacing through the `size` attribute.
- * An accordion button can be disabled, which prevents the header from being clickable.
- *
- * ## When to use
+ * The accordion button is a vertically stacked component with a clickable header and an expandable/collapsible body section. The entire header is clickable to toggle the visibility of the body content. The header contains an optional prefix icon, header text (default H3, customizable via `data-aria-level`), and an expand/collapse arrow icon as visual indicator. The body contains a default slot for any content. The component supports different border styles through the `variant` attribute and different spacing through the `size` attribute, and can be disabled to prevent the header from being clickable.
+ * 
+ * **When to use**
+ * 
  * - Use `mdc-accordionbutton` for simple clickable headers without additional controls.
- * - Use `mdc-accordion` instead if you need extra controls (chips, badges, icons) in the header.
- *
- * ## Accessibility
- * - Adjust `data-aria-level` based on heading hierarchy in your page.
- * - Note: Screen readers may lose focus when toggling if accordion button is expanded by default.
- *
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-accordion` instead if you need extra controls (chips, badges, icons) in the header itself.
+ * 
  * @tagname mdc-accordionbutton
- *
+ * 
  * @dependency mdc-button
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @slot default - The default slot contains the body section of the accordion. User can place anything inside this body slot.
- *
+ * 
  * @event shown - (React: onShown) This event is triggered when the accordion button is toggled (expanded or collapsed).
- *
+ * 
  * @cssproperty --mdc-accordionbutton-border-color - The border color of the accordion button.
  * @cssproperty --mdc-accordionbutton-hover-color - The hover background color of the accordion button header.
  * @cssproperty --mdc-accordionbutton-active-color - The active background color of the accordion button header.
  * @cssproperty --mdc-accordionbutton-disabled-color - The disabled text color of the accordion button.
- *
+ * 
  * @csspart body-section - The body section of the accordion button.
  * @csspart header-button-section - The header button section of the accordion button.
  * @csspart header-section - The header section of the accordion button.

package/dist/components/accordionbutton/accordionbutton.component.js

@@ -19,28 +19,6 @@ import { KeyDownHandledMixin } from '../../utils/mixins/KeyDownHandledMixin';
 import { DEFAULTS, ICON_NAME, TOGGLE_POSITION } from './accordionbutton.constants';
 import styles from './accordionbutton.styles';
 /**
- * An accordion button is a vertically stacked component with a clickable header and expandable/collapsible body section.
- * The entire header is clickable to toggle the visibility of the body content.
- *
- * ## Header contains
- * - Optional prefix icon
- * - Header text (default H3, customizable via `data-aria-level`)
- * - Expand/collapse arrow icon (visual indicator)
- *
- * ## Body contains
- * - Default slot for any content
- *
- * The accordion button supports different border styles through the `variant` attribute and different spacing through the `size` attribute.
- * An accordion button can be disabled, which prevents the header from being clickable.
- *
- * ## When to use
- * - Use `mdc-accordionbutton` for simple clickable headers without additional controls.
- * - Use `mdc-accordion` instead if you need extra controls (chips, badges, icons) in the header.
- *
- * ## Accessibility
- * - Adjust `data-aria-level` based on heading hierarchy in your page.
- * - Note: Screen readers may lose focus when toggling if accordion button is expanded by default.
- *
  * @tagname mdc-accordionbutton
  *
  * @dependency mdc-button

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

@@ -2,24 +2,20 @@ import type { CSSResult, PropertyValues } from 'lit';
 import { Component } from '../../models';
 import type { Size, Variant } from './accordiongroup.types';
 /**
- * An accordion group is a container that manages multiple accordion or accordionbutton components as a unified set.
- * It controls the visual styling, spacing, and expansion behavior of all child accordions.
- *
- * The group applies consistent `variant` and `size` attributes to all children automatically.
- * By default, expanding one accordion collapses others (`allow-multiple` is false). Set `allow-multiple` to true to allow multiple expanded items.
- *
- * ## Accepted children
- * - Use `mdc-accordionbutton` children for simple clickable headers.
- * - Use `mdc-accordion` children when you need additional controls (chips, badges, icons) in the headers.
- * - Other elements in the slot are ignored.
- *
- * ## Accessibility
- * - Note: Screen readers may lose focus when toggling if the first accordion is expanded by default.
- *
+ * The accordion group is a container that manages multiple accordion or accordionbutton components as a unified set. It controls the visual styling, spacing, and expansion behavior of all child accordions. The group applies consistent `variant` and `size` attributes to all children automatically. By default, expanding one accordion collapses the others (`allow-multiple` is false); set `allow-multiple` to true to allow multiple expanded items.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-accordiongroup` when you need to render two or more related `mdc-accordion` or `mdc-accordionbutton` items with consistent styling, spacing, and coordinated expansion behaviour.
+ * 
+ * **When not to use**
+ * 
+ * - Use a single `mdc-accordion` or `mdc-accordionbutton` directly when only one collapsible section is needed.
+ * 
  * @tagname mdc-accordiongroup
- *
+ * 
  * @slot default - The default slot can contain the `accordion` or `accordionbutton` components.
- *
+ * 
  * @cssproperty --mdc-accordiongroup-items-border-color - The border color applied to all child accordion items and their separators.
  */
 declare class AccordionGroup extends Component {

package/dist/components/accordiongroup/accordiongroup.component.js

@@ -15,20 +15,6 @@ import { Component } from '../../models';
 import { DEFAULTS } from './accordiongroup.constants';
 import styles from './accordiongroup.styles';
 /**
- * An accordion group is a container that manages multiple accordion or accordionbutton components as a unified set.
- * It controls the visual styling, spacing, and expansion behavior of all child accordions.
- *
- * The group applies consistent `variant` and `size` attributes to all children automatically.
- * By default, expanding one accordion collapses others (`allow-multiple` is false). Set `allow-multiple` to true to allow multiple expanded items.
- *
- * ## Accepted children
- * - Use `mdc-accordionbutton` children for simple clickable headers.
- * - Use `mdc-accordion` children when you need additional controls (chips, badges, icons) in the headers.
- * - Other elements in the slot are ignored.
- *
- * ## Accessibility
- * - Note: Screen readers may lose focus when toggling if the first accordion is expanded by default.
- *
  * @tagname mdc-accordiongroup
  *
  * @slot default - The default slot can contain the `accordion` or `accordionbutton` components.

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

@@ -3,26 +3,30 @@ import Buttonsimple from '../buttonsimple/buttonsimple.component';
 import type { VariantType } from './alertchip.types';
 declare const AlertChip_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Buttonsimple;
 /**
- * mdc-alertchip component is an interactive chip that consumers can use to represent an alert.
- *
- * - It supports a leading icon along with label.
- * - It supports 5 variants of alerts - error, informational, neutral, success and warning.
- *
- * This component is built by extending Buttonsimple.
- *
+ * The alert chip is an interactive chip whose color and leading icon indicate one of five visual states — `error`, `informational`, `neutral`, `success`, and `warning`. The variant only changes the visual styling; it does not announce or read out any alert content to assistive technologies on its own.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-alertchip` to surface a short, interactive status (error, success, warning, informational, neutral) inline within content.
+ * 
+ * **When not to use**
+ * 
+ * - Use a non-interactive status indicator (e.g. `mdc-badge` or `mdc-staticchip`) when the chip should not be clickable or focusable.
+ * - Use `mdc-toast` or `mdc-banner` when the message needs more length, dedicated actions, or system-level prominence.
+ * 
  * @tagname mdc-alertchip
- *
+ * 
  * @dependency mdc-icon
  * @dependency mdc-text
- *
+ * 
  * @cssproperty --mdc-chip-color - The color of the label text
  * @cssproperty --mdc-chip-icon-color - The color of the icon
  * @cssproperty --mdc-chip-border-color - The border color of the alertchip
  * @cssproperty --mdc-chip-background-color - The background color of the alertchip
- *
+ * 
  * @csspart icon - The alert icon
  * @csspart label - The text label of the alertchip
- *
+ * 
  * @event click - (React: onClick) This event is dispatched when the alertchip is clicked.
  * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the alertchip.
  * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the alertchip.

package/dist/components/alertchip/alertchip.component.js

@@ -16,13 +16,6 @@ import styles from './alertchip.styles';
 import { DEFAULTS } from './alertchip.constants';
 import { getAlertIcon } from './alertchip.utils';
 /**
- * mdc-alertchip component is an interactive chip that consumers can use to represent an alert.
- *
- * - It supports a leading icon along with label.
- * - It supports 5 variants of alerts - error, informational, neutral, success and warning.
- *
- * This component is built by extending Buttonsimple.
- *
  * @tagname mdc-alertchip
  *
  * @dependency mdc-icon

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

@@ -3,13 +3,21 @@ import { AnimationItem } from 'lottie-web/build/player/lottie_light';
 import { Component } from '../../models';
 import type { AnimationNames, LoopType } from './animation.types';
 /**
- * The `mdc-animation` component is a wrapper around the Lottie animation library.
- * It fetches the animation data dynamically based on the provided name and renders it.
- * This is a display only component that does not have any interactive functionality.
- * From accessibility perspective, (by default) it is a decorative image component.
- *
+ * The animation component is a wrapper around the Lottie animation library. It fetches the animation data dynamically based on the provided name (or a `src` URL) and renders it. It is a display-only component with no interactive functionality and is treated as a decorative image by default.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-animation` to play short, looping or one-shot Lottie animations inline within UI — for example illustrations, loading indicators, or success/empty-state visuals.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-icon` for a static glyph that does not need motion.
+ * - Use `mdc-illustration` for a non-animated illustration asset.
+ * - Use `mdc-progressspinner` or `mdc-progressbar` when the animation needs to communicate determinate or indeterminate progress with proper progress semantics.
+ * - Use `mdc-spinner` when you only need a lightweight, generic loading indicator without a dedicated Lottie asset.
+ * 
  * @tagname mdc-animation
- *
+ * 
  * @event load - (React: onLoad) This event is dispatched when the animation is loaded
  * @event complete - (React: onComplete) This event is dispatched when all animation loops completed
  * @event error - (React: onError) This event is dispatched when animation loading failed

package/dist/components/animation/animation.component.js

@@ -17,11 +17,6 @@ import { ROLE } from '../../utils/roles';
 import styles from './animation.styles';
 import { DEFAULTS } from './animation.constants';
 /**
- * The `mdc-animation` component is a wrapper around the Lottie animation library.
- * It fetches the animation data dynamically based on the provided name and renders it.
- * This is a display only component that does not have any interactive functionality.
- * From accessibility perspective, (by default) it is a decorative image component.
- *
  * @tagname mdc-animation
  *
  * @event load - (React: onLoad) This event is dispatched when the animation is loaded

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

@@ -3,37 +3,30 @@ import Dialog from '../dialog/dialog.component';
 import type { IllustrationNames } from '../illustration/illustration.types';
 import type { AnnouncementDialogSize } from './announcementdialog.types';
 /**
- * AnnouncementDialog component is a modal dialog that can be used to display announcements, extending the existing Dialog component.
- * It can be used to create custom dialogs where a illustration, content and footer actions are provided by the consumer.
- * The dialog is available in 4 sizes:  medium, large, xlarge and fullscreen. It may also receive custom styling/sizing.
- * The dialog interrupts the user and will block interaction with the rest of the application until it is closed.
- *
- * The dialog can be controlled solely through the `visible` property, no trigger element is required.
- * If a `triggerId` is provided, the dialog will manage focus with that element, otherwise it will
- * remember the previously focused element before the dialog was opened.
- *
- * The dialog is a controlled component, meaning it does not have its own state management for visibility.
- * Use the `visible` property to control the visibility of the dialog.
- * Use the `onClose` event to handle the close action of the dialog (fired when Close button is clicked
- * or Escape is pressed).
- *
- * ## Accessibility
- * - You have to be explicitly set the following attributes:
- *  * The dialog should have an aria-label or aria-labelledby attribute to provide a label for screen readers.
- *  * Use aria-labelledby to reference the ID of the element that labels the dialog when there is no visible title.
- *
+ * The announcement dialog is a modal dialog used to display announcements. Consumers provide an illustration, content, and footer actions through slots. It is available in four sizes — `medium`, `large`, `xlarge`, and `fullscreen` — and may also receive custom styling/sizing. The dialog interrupts the user and blocks interaction with the rest of the application until it is closed.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-announcementdialog` to highlight a one-off announcement, onboarding moment, or feature reveal that benefits from a prominent illustration alongside the message and primary action.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-dialog` for a generic modal that does not need an illustration-led layout.
+ * - Use `mdc-toast` for non-blocking, transient feedback that should not interrupt the user.
+ * - Use `mdc-banner` for persistent in-page messaging that should sit within the flow rather than blocking it.
+ * 
+ * @tagname mdc-announcementdialog
+ * 
  * @dependency mdc-illustration
  * @dependency mdc-text
- *
- * @tagname mdc-announcementdialog
- *
+ * 
  * @event shown - (React: onShown) Dispatched when the dialog is shown
  * @event hidden - (React: onHidden) Dispatched when the dialog is hidden
  * @event created - (React: onCreated) Dispatched when the dialog is created (added to the DOM)
  * @event destroyed - (React: onDestroyed) Dispatched when the dialog is destroyed (removed from the DOM)
  * @event close - (React: onClose) Dispatched when the Close Button is clicked or Escape key is pressed
  * (this does not hide the dialog)
- *
+ * 
  * @cssproperty --mdc-announcementdialog-illustration-background-color - background color of the illustration section
  * @cssproperty --mdc-dialog-primary-background-color - primary background color of the dialog
  * @cssproperty --mdc-dialog-border-color - border color of the dialog
@@ -42,12 +35,12 @@ import type { AnnouncementDialogSize } from './announcementdialog.types';
  * @cssproperty --mdc-dialog-elevation-3 - elevation of the dialog
  * @cssproperty --mdc-dialog-width - width of the dialog
  * @cssproperty --mdc-dialog-height - height of the dialog
- *
+ * 
  * @csspart body - The main body container that holds the illustration and content sections
  * @csspart illustration-container - The container for the illustration section
  * @csspart content-container - The container for the content section
  * @csspart header-text - The header text
- *
+ * 
  * @slot header-prefix - Slot for the dialog header content. This can be used to pass custom header content.
  * @slot dialog-body - Slot for the dialog body content
  * @slot illustration-container - Slot for the illustration container section

package/dist/components/announcementdialog/announcementdialog.component.js

@@ -16,30 +16,11 @@ import { DIALOG_VARIANT } from '../dialog/dialog.constants';
 import styles from './announcementdialog.styles';
 import { DEFAULTS } from './announcementdialog.constants';
 /**
- * AnnouncementDialog component is a modal dialog that can be used to display announcements, extending the existing Dialog component.
- * It can be used to create custom dialogs where a illustration, content and footer actions are provided by the consumer.
- * The dialog is available in 4 sizes:  medium, large, xlarge and fullscreen. It may also receive custom styling/sizing.
- * The dialog interrupts the user and will block interaction with the rest of the application until it is closed.
- *
- * The dialog can be controlled solely through the `visible` property, no trigger element is required.
- * If a `triggerId` is provided, the dialog will manage focus with that element, otherwise it will
- * remember the previously focused element before the dialog was opened.
- *
- * The dialog is a controlled component, meaning it does not have its own state management for visibility.
- * Use the `visible` property to control the visibility of the dialog.
- * Use the `onClose` event to handle the close action of the dialog (fired when Close button is clicked
- * or Escape is pressed).
- *
- * ## Accessibility
- * - You have to be explicitly set the following attributes:
- *  * The dialog should have an aria-label or aria-labelledby attribute to provide a label for screen readers.
- *  * Use aria-labelledby to reference the ID of the element that labels the dialog when there is no visible title.
+ * @tagname mdc-announcementdialog
  *
  * @dependency mdc-illustration
  * @dependency mdc-text
  *
- * @tagname mdc-announcementdialog
- *
  * @event shown - (React: onShown) Dispatched when the dialog is shown
  * @event hidden - (React: onHidden) Dispatched when the dialog is hidden
  * @event created - (React: onCreated) Dispatched when the dialog is created (added to the DOM)

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

@@ -1,23 +1,24 @@
 import { CSSResult } from 'lit';
 import { Component } from '../../models';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
- *
- * ## Layout sections
- * - **Leading** - Typically holds brand logo, brand name, or menu icon
- * - **Center** - Can contain search bar, icons, navigation links, or action controls
- * - **Trailing** - Generally includes profile avatar, icons, settings, or additional action controls
- *
- * Each section automatically handles flex alignment: leading aligns left, center aligns center, trailing aligns right.
- *
+ * The app header provides a structured layout for the top of an application with three sections: leading, center, and trailing. Each section automatically handles flex alignment — leading aligns left, center aligns center, trailing aligns right.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-appheader` as the top-level bar of an application to host branding, primary navigation/search, and account or action controls in a consistent layout.
+ * 
+ * **When not to use**
+ * 
+ * - Use a plain `<header>` element when you only need a simple top bar without the leading/center/trailing three-section structure.
+ * 
  * @tagname mdc-appheader
- *
+ * 
  * @slot leading - Content for the leading section (left-aligned).
  * @slot center - Content for the center section (center-aligned).
  * @slot trailing - Content for the trailing section (right-aligned).
- *
+ * 
  * @cssproperty --mdc-appheader-height - Height of the app header. Default is 4rem (64px).
- *
+ * 
  * @csspart container - The main header container.
  * @csspart leading-section - The leading section wrapper (left side).
  * @csspart center-section - The center section wrapper (middle).

package/dist/components/appheader/appheader.component.js

@@ -2,15 +2,6 @@ import { html } from 'lit';
 import { Component } from '../../models';
 import styles from './appheader.styles';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
- *
- * ## Layout sections
- * - **Leading** - Typically holds brand logo, brand name, or menu icon
- * - **Center** - Can contain search bar, icons, navigation links, or action controls
- * - **Trailing** - Generally includes profile avatar, icons, settings, or additional action controls
- *
- * Each section automatically handles flex alignment: leading aligns left, center aligns center, trailing aligns right.
- *
  * @tagname mdc-appheader
  *
  * @slot leading - Content for the leading section (left-aligned).

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

@@ -3,42 +3,22 @@ import { CSSResult } from 'lit';
 import { Component } from '../../models';
 declare const Avatar_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/AvatarComponentMixin").AvatarComponentMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Component;
 /**
- * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.
- *
- * ## Display Priority
- *
- * When multiple attributes are provided, the component determines what to display based on this priority:
- * 1. **Photo** (`src`) - Takes highest priority
- *    - While loading: Shows `initials` as placeholder if provided (instant), otherwise shows icon (requires loading)
- *    - After loading: Shows the photo
- *    - On error: Placeholder remains visible (initials or icon)
- * 2. **Icon** (`icon-name`) - Takes priority if no `src` is provided
- *    - Shows custom icon if `icon-name` is set (requires icon library to load)
- *    - **Note:** If both `icon-name` and `initials` are provided (without `src`), icon takes precedence and initials are ignored.
- *      This means users may see a delay while the icon loads, even though initials render instantly.
- *    - Defaults to `user-regular` icon if no other content is available
- * 3. **Initials** (`initials`) - Displayed only if no `src` or `icon-name` is provided
- *    - Shows first two characters, converted to uppercase
- *    - Renders instantly (no loading required)
- * 4. **Counter** (`counter`) - Displayed only if none of the above are provided
- *    - Shows numeric value (max 99+)
- *    - Negative values display as 0
- *
- * ## Behavior
- * - Non-interactive and non-focusable component (use `mdc-avatarbutton` for clickable avatars)
- * - Shows loading indicator overlay when `is-typing` is true (displays on top of existing content)
- * - Presence indicator hidden when counter is set or when typing
- *
- * ## Accessibility
- * - By default, the component is hidden from assistive technologies (`aria-hidden="true"`).
- * - Consumers can override this attribute `aria-hidden="false"` if needed.
- *
+ * The avatar represents a person or a group. It can be rendered as a photo, initials, icon, or counter, and is non-interactive and non-focusable by default. An optional presence indicator and a typing loading state are also supported.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-avatar` to visually represent a person or group inline within content (e.g. lists, cards, message rows).
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-avatarbutton` when the avatar must be clickable or focusable (profile menu, account switcher, etc.).
+ * 
+ * @tagname mdc-avatar
+ * 
  * @dependency mdc-icon
  * @dependency mdc-presence
  * @dependency mdc-text
- *
- * @tagname mdc-avatar
- *
+ * 
  * @cssproperty --mdc-avatar-default-background-color - Allows customization of the default background color.
  * @cssproperty --mdc-avatar-default-foreground-color - Allows customization of the default foreground color.
  * @cssproperty --mdc-avatar-loading-indicator-background-color -
@@ -47,7 +27,7 @@ declare const Avatar_base: import("../../utils/mixins/index.types").Constructor<
  *  Allows customization of the loading indicator foreground color.
  * @cssproperty --mdc-avatar-loading-overlay-background-color -
  *  Allows customization of the loading overlay background color.
- *
+ * 
  * @csspart photo - The photo of the avatar.
  * @csspart presence - The presence indicator of the avatar.
  * @csspart loading-wrapper - The wrapper for the loading indicator.

package/dist/components/avatar/avatar.component.js

@@ -17,42 +17,12 @@ import { AVATAR_TYPE, DEFAULTS, MAX_COUNTER } from './avatar.constants';
 import styles from './avatar.styles';
 import { getAvatarIconSize, getAvatarTextFontSize, getPresenceSize } from './avatar.utils';
 /**
- * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.
- *
- * ## Display Priority
- *
- * When multiple attributes are provided, the component determines what to display based on this priority:
- * 1. **Photo** (`src`) - Takes highest priority
- *    - While loading: Shows `initials` as placeholder if provided (instant), otherwise shows icon (requires loading)
- *    - After loading: Shows the photo
- *    - On error: Placeholder remains visible (initials or icon)
- * 2. **Icon** (`icon-name`) - Takes priority if no `src` is provided
- *    - Shows custom icon if `icon-name` is set (requires icon library to load)
- *    - **Note:** If both `icon-name` and `initials` are provided (without `src`), icon takes precedence and initials are ignored.
- *      This means users may see a delay while the icon loads, even though initials render instantly.
- *    - Defaults to `user-regular` icon if no other content is available
- * 3. **Initials** (`initials`) - Displayed only if no `src` or `icon-name` is provided
- *    - Shows first two characters, converted to uppercase
- *    - Renders instantly (no loading required)
- * 4. **Counter** (`counter`) - Displayed only if none of the above are provided
- *    - Shows numeric value (max 99+)
- *    - Negative values display as 0
- *
- * ## Behavior
- * - Non-interactive and non-focusable component (use `mdc-avatarbutton` for clickable avatars)
- * - Shows loading indicator overlay when `is-typing` is true (displays on top of existing content)
- * - Presence indicator hidden when counter is set or when typing
- *
- * ## Accessibility
- * - By default, the component is hidden from assistive technologies (`aria-hidden="true"`).
- * - Consumers can override this attribute `aria-hidden="false"` if needed.
+ * @tagname mdc-avatar
  *
  * @dependency mdc-icon
  * @dependency mdc-presence
  * @dependency mdc-text
  *
- * @tagname mdc-avatar
- *
  * @cssproperty --mdc-avatar-default-background-color - Allows customization of the default background color.
  * @cssproperty --mdc-avatar-default-foreground-color - Allows customization of the default foreground color.
  * @cssproperty --mdc-avatar-loading-indicator-background-color -

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

@@ -3,24 +3,25 @@ import { CSSResult } from 'lit';
 import Buttonsimple from '../buttonsimple/buttonsimple.component';
 declare const AvatarButton_base: import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/AvatarComponentMixin").AvatarComponentMixinInterface> & import("../../utils/mixins/index.types").Constructor<import("../../utils/mixins/IconNameMixin").IconNameMixinInterface> & typeof Buttonsimple;
 /**
- * The `mdc-avatarbutton` component is an interactive, clickable version of `mdc-avatar`.
- * It wraps the avatar component in a button, making it focusable and actionable.
- *
- * This component extends `buttonsimple` and includes all avatar display features (photo, initials, icon, counter, presence).
- * Use CSS parts to customize the avatar's appearance inside the button.
- *
- * ## Accessibility
- * - Always provide an `aria-label` attribute to describe the button's purpose
- *
+ * The avatar button is an interactive, clickable version of the avatar. It wraps the avatar in a button so it becomes focusable and actionable, while still supporting all avatar display modes (photo, initials, icon, counter) and the presence indicator. Use CSS parts to customise the avatar appearance inside the button.
+ * 
+ * **When to use**
+ * 
+ * - Use `mdc-avatarbutton` when the avatar must be clickable or keyboard-focusable — for example a profile menu trigger, account switcher, or a member chip that opens a details panel.
+ * 
+ * **When not to use**
+ * 
+ * - Use `mdc-avatar` when the avatar is purely decorative or informational and should not be interactive.
+ * 
+ * @tagname mdc-avatarbutton
+ * 
  * @dependency mdc-avatar
- *
+ * 
  * @event click - (React: onClick) Dispatched when the avatar button is clicked.
  * @event keydown - (React: onKeyDown) Dispatched when a key is pressed on the avatar button.
  * @event keyup - (React: onKeyUp) Dispatched when a key is released on the avatar button.
  * @event focus - (React: onFocus) Dispatched when the avatar button receives focus.
- *
- * @tagname mdc-avatarbutton
- *
+ * 
  * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state.
  * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state.
  * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state.
@@ -29,7 +30,7 @@ declare const AvatarButton_base: import("../../utils/mixins/index.types").Constr
  * @cssproperty --mdc-avatarbutton-loading-indicator-background-color - Background color of the loading indicator.
  * @cssproperty --mdc-avatarbutton-loading-indicator-foreground-color - Foreground color of the loading indicator.
  * @cssproperty --mdc-avatarbutton-loading-overlay-background-color - Background color of the loading overlay.
- *
+ * 
  * @csspart overlay - The overlay part of the avatar button.
  * @csspart content - The main content of the avatar.
  * @csspart photo - The photo part of the avatar.

package/dist/components/avatarbutton/avatarbutton.component.js

@@ -18,14 +18,7 @@ import { DEFAULTS as BUTTON_DEFAULTS } from '../button/button.constants';
 import Buttonsimple from '../buttonsimple/buttonsimple.component';
 import styles from './avatarbutton.styles';
 /**
- * The `mdc-avatarbutton` component is an interactive, clickable version of `mdc-avatar`.
- * It wraps the avatar component in a button, making it focusable and actionable.
- *
- * This component extends `buttonsimple` and includes all avatar display features (photo, initials, icon, counter, presence).
- * Use CSS parts to customize the avatar's appearance inside the button.
- *
- * ## Accessibility
- * - Always provide an `aria-label` attribute to describe the button's purpose
+ * @tagname mdc-avatarbutton
  *
  * @dependency mdc-avatar
  *
@@ -34,8 +27,6 @@ import styles from './avatarbutton.styles';
  * @event keyup - (React: onKeyUp) Dispatched when a key is released on the avatar button.
  * @event focus - (React: onFocus) Dispatched when the avatar button receives focus.
  *
- * @tagname mdc-avatarbutton
- *
  * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state.
  * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state.
  * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state.