@momentum-design/components 0.129.13 → 0.129.14

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

@@ -1,23 +1,27 @@
 import { CSSResult } from 'lit';
 import { Component } from '../../models';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout.
- * It consists of three primary sections: leading, center, and trailing.
+ * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
  *
- * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.
- * - The **center section** can contain a **search bar**, **icons** or action controls.
- * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.
+ * ## 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 - Slot for the leading section (e.g., brand logo, brand name).
- * @slot center - Slot for the center section (e.g., search bar, icons).
- * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).
+ * @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 container for styling the header.
- * @csspart leading-section - The leading section of the header.
- * @csspart center-section - The center section of the header.
- * @csspart trailing-section - The trailing section of the header.
+ * @csspart container - The main header container.
+ * @csspart leading-section - The leading section wrapper (left side).
+ * @csspart center-section - The center section wrapper (middle).
+ * @csspart trailing-section - The trailing section wrapper (right side).
  */
 declare class Appheader extends Component {
     /**

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

@@ -2,23 +2,27 @@ 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.
- * It consists of three primary sections: leading, center, and trailing.
+ * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
  *
- * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.
- * - The **center section** can contain a **search bar**, **icons** or action controls.
- * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.
+ * ## 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 - Slot for the leading section (e.g., brand logo, brand name).
- * @slot center - Slot for the center section (e.g., search bar, icons).
- * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).
+ * @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 container for styling the header.
- * @csspart leading-section - The leading section of the header.
- * @csspart center-section - The center section of the header.
- * @csspart trailing-section - The trailing section of the header.
+ * @csspart container - The main header container.
+ * @csspart leading-section - The leading section wrapper (left side).
+ * @csspart center-section - The center section wrapper (middle).
+ * @csspart trailing-section - The trailing section wrapper (right side).
  */
 class Appheader extends Component {
     /**

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

@@ -3,24 +3,31 @@ 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 is used to represent a person or a space.
- * An avatar can be an icon, initials, counter and photo.
+ * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.
  *
- * To set the photo of an avatar,
- * you need to set "src" attribute.
+ * ## Display Priority
  *
- * While the avatar image is loading, as a placeholder,
- * we will show the initials text.
- * If the initials are not specified then,
- * we will show `user-regular` icon as a placeholder.
+ * 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
  *
- * By default, if there are no attributes specified,
- * then the default avatar will be an icon with `user-regular` name.
- *
- * The avatar component is non clickable and non interactive/focusable component.
- * If the avatar is typing, then the loading indicator will be displayed.
- * If the counter type avatar is set to a negative number, then we will display 0.
- * The presence indicator will be hidden when the counter property is set.
+ * ## 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
  *
  * @dependency mdc-icon
  * @dependency mdc-presence

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

@@ -17,24 +17,31 @@ 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 is used to represent a person or a space.
- * An avatar can be an icon, initials, counter and photo.
+ * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.
  *
- * To set the photo of an avatar,
- * you need to set "src" attribute.
+ * ## Display Priority
  *
- * While the avatar image is loading, as a placeholder,
- * we will show the initials text.
- * If the initials are not specified then,
- * we will show `user-regular` icon as a placeholder.
+ * 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
  *
- * By default, if there are no attributes specified,
- * then the default avatar will be an icon with `user-regular` name.
- *
- * The avatar component is non clickable and non interactive/focusable component.
- * If the avatar is typing, then the loading indicator will be displayed.
- * If the counter type avatar is set to a negative number, then we will display 0.
- * The presence indicator will be hidden when the counter property is set.
+ * ## 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
  *
  * @dependency mdc-icon
  * @dependency mdc-presence

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

@@ -3,25 +3,27 @@ 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 interactable version of the `mdc-avatar` component.
+ * 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 is made by extending `buttonsimple` class.
- * The button component acts as a wrapper for the avatar component.
+ * 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.
  *
- * To override styles of the avatar inside, use the specified css parts.
+ * ## Accessibility
+ * - Always provide an `aria-label` attribute to describe the button's purpose
  *
  * @dependency mdc-avatar
  *
- * @event click - (React: onClick) This event is dispatched when the avatarbutton is clicked.
- * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the avatarbutton.
- * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the avatarbutton.
- * @event focus - (React: onFocus) This event is dispatched when the avatarbutton receives focus.
+ * @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
+ * @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.
  *
  * @csspart overlay - The overlay part of the avatar button.
  * @csspart content - The main content of the avatar.

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

@@ -18,25 +18,27 @@ 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 interactable version of the `mdc-avatar` component.
+ * 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 is made by extending `buttonsimple` class.
- * The button component acts as a wrapper for the avatar component.
+ * 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.
  *
- * To override styles of the avatar inside, use the specified css parts.
+ * ## Accessibility
+ * - Always provide an `aria-label` attribute to describe the button's purpose
  *
  * @dependency mdc-avatar
  *
- * @event click - (React: onClick) This event is dispatched when the avatarbutton is clicked.
- * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the avatarbutton.
- * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the avatarbutton.
- * @event focus - (React: onFocus) This event is dispatched when the avatarbutton receives focus.
+ * @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
+ * @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.
  *
  * @csspart overlay - The overlay part of the avatar button.
  * @csspart content - The main content of the avatar.

package/dist/custom-elements.json

@@ -3267,37 +3267,43 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The `mdc-appheader` component provides a structured and accessible app header layout.\nIt consists of three primary sections: leading, center, and trailing.\n\n- The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.\n- The **center section** can contain a **search bar**, **icons** or action controls.\n- The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.",
+          "description": "The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.\n\n## Layout sections\n- **Leading** - Typically holds brand logo, brand name, or menu icon\n- **Center** - Can contain search bar, icons, navigation links, or action controls\n- **Trailing** - Generally includes profile avatar, icons, settings, or additional action controls\n\nEach section automatically handles flex alignment: leading aligns left, center aligns center, trailing aligns right.",
           "name": "Appheader",
+          "cssProperties": [
+            {
+              "description": "Height of the app header. Default is 4rem (64px).",
+              "name": "--mdc-appheader-height"
+            }
+          ],
           "cssParts": [
             {
-              "description": "The main container for styling the header.",
+              "description": "The main header container.",
               "name": "container"
             },
             {
-              "description": "The leading section of the header.",
+              "description": "The leading section wrapper (left side).",
               "name": "leading-section"
             },
             {
-              "description": "The center section of the header.",
+              "description": "The center section wrapper (middle).",
               "name": "center-section"
             },
             {
-              "description": "The trailing section of the header.",
+              "description": "The trailing section wrapper (right side).",
               "name": "trailing-section"
             }
           ],
           "slots": [
             {
-              "description": "Slot for the leading section (e.g., brand logo, brand name).",
+              "description": "Content for the leading section (left-aligned).",
               "name": "leading"
             },
             {
-              "description": "Slot for the center section (e.g., search bar, icons).",
+              "description": "Content for the center section (center-aligned).",
               "name": "center"
             },
             {
-              "description": "Slot for the trailing section (e.g., profile avatar, icons).",
+              "description": "Content for the trailing section (right-aligned).",
               "name": "trailing"
             }
           ],
@@ -3307,7 +3313,7 @@
             "module": "/src/models"
           },
           "tagName": "mdc-appheader",
-          "jsDoc": "/**\n * The `mdc-appheader` component provides a structured and accessible app header layout.\n * It consists of three primary sections: leading, center, and trailing.\n *\n * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.\n * - The **center section** can contain a **search bar**, **icons** or action controls.\n * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.\n *\n * @tagname mdc-appheader\n *\n * @slot leading - Slot for the leading section (e.g., brand logo, brand name).\n * @slot center - Slot for the center section (e.g., search bar, icons).\n * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).\n *\n * @csspart container - The main container for styling the header.\n * @csspart leading-section - The leading section of the header.\n * @csspart center-section - The center section of the header.\n * @csspart trailing-section - The trailing section of the header.\n */",
+          "jsDoc": "/**\n * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.\n *\n * ## Layout sections\n * - **Leading** - Typically holds brand logo, brand name, or menu icon\n * - **Center** - Can contain search bar, icons, navigation links, or action controls\n * - **Trailing** - Generally includes profile avatar, icons, settings, or additional action controls\n *\n * Each section automatically handles flex alignment: leading aligns left, center aligns center, trailing aligns right.\n *\n * @tagname mdc-appheader\n *\n * @slot leading - Content for the leading section (left-aligned).\n * @slot center - Content for the center section (center-aligned).\n * @slot trailing - Content for the trailing section (right-aligned).\n *\n * @cssproperty --mdc-appheader-height - Height of the app header. Default is 4rem (64px).\n *\n * @csspart container - The main header container.\n * @csspart leading-section - The leading section wrapper (left side).\n * @csspart center-section - The center section wrapper (middle).\n * @csspart trailing-section - The trailing section wrapper (right side).\n */",
           "customElement": true
         }
       ],
@@ -3328,7 +3334,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The `mdc-avatar` component is used to represent a person or a space.\nAn avatar can be an icon, initials, counter and photo.\n\nTo set the photo of an avatar,\nyou need to set \"src\" attribute.\n\nWhile the avatar image is loading, as a placeholder,\nwe will show the initials text.\nIf the initials are not specified then,\nwe will show `user-regular` icon as a placeholder.\n\nBy default, if there are no attributes specified,\nthen the default avatar will be an icon with `user-regular` name.\n\nThe avatar component is non clickable and non interactive/focusable component.\nIf the avatar is typing, then the loading indicator will be displayed.\nIf the counter type avatar is set to a negative number, then we will display 0.\nThe presence indicator will be hidden when the counter property is set.",
+          "description": "The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.\n\n## Display Priority\n\nWhen multiple attributes are provided, the component determines what to display based on this priority:\n1. **Photo** (`src`) - Takes highest priority\n   - While loading: Shows `initials` as placeholder if provided (instant), otherwise shows icon (requires loading)\n   - After loading: Shows the photo\n   - On error: Placeholder remains visible (initials or icon)\n2. **Icon** (`icon-name`) - Takes priority if no `src` is provided\n   - Shows custom icon if `icon-name` is set (requires icon library to load)\n   - **Note:** If both `icon-name` and `initials` are provided (without `src`), icon takes precedence and initials are ignored.\n     This means users may see a delay while the icon loads, even though initials render instantly.\n   - Defaults to `user-regular` icon if no other content is available\n3. **Initials** (`initials`) - Displayed only if no `src` or `icon-name` is provided\n   - Shows first two characters, converted to uppercase\n   - Renders instantly (no loading required)\n4. **Counter** (`counter`) - Displayed only if none of the above are provided\n   - Shows numeric value (max 99+)\n   - Negative values display as 0\n\n## Behavior\n- Non-interactive and non-focusable component (use `mdc-avatarbutton` for clickable avatars)\n- Shows loading indicator overlay when `is-typing` is true (displays on top of existing content)\n- Presence indicator hidden when counter is set or when typing",
           "name": "Avatar",
           "cssProperties": [
             {
@@ -3481,7 +3487,7 @@
             "module": "/src/models"
           },
           "tagName": "mdc-avatar",
-          "jsDoc": "/**\n * The `mdc-avatar` component is used to represent a person or a space.\n * An avatar can be an icon, initials, counter and photo.\n *\n * To set the photo of an avatar,\n * you need to set \"src\" attribute.\n *\n * While the avatar image is loading, as a placeholder,\n * we will show the initials text.\n * If the initials are not specified then,\n * we will show `user-regular` icon as a placeholder.\n *\n * By default, if there are no attributes specified,\n * then the default avatar will be an icon with `user-regular` name.\n *\n * The avatar component is non clickable and non interactive/focusable component.\n * If the avatar is typing, then the loading indicator will be displayed.\n * If the counter type avatar is set to a negative number, then we will display 0.\n * The presence indicator will be hidden when the counter property is set.\n *\n * @dependency mdc-icon\n * @dependency mdc-presence\n * @dependency mdc-text\n *\n * @tagname mdc-avatar\n *\n * @cssproperty --mdc-avatar-default-background-color - Allows customization of the default background color.\n * @cssproperty --mdc-avatar-default-foreground-color - Allows customization of the default foreground color.\n * @cssproperty --mdc-avatar-loading-indicator-background-color -\n *  Allows customization of the loading indicator background color.\n * @cssproperty --mdc-avatar-loading-indicator-foreground-color -\n *  Allows customization of the loading indicator foreground color.\n * @cssproperty --mdc-avatar-loading-overlay-background-color -\n *  Allows customization of the loading overlay background color.\n *\n * @csspart photo - The photo of the avatar.\n * @csspart presence - The presence indicator of the avatar.\n * @csspart loading-wrapper - The wrapper for the loading indicator.\n * @csspart loader - The loading indicator of the avatar.\n */",
+          "jsDoc": "/**\n * The `mdc-avatar` component represents a person or a space. It displays as a photo, initials, icon, or counter.\n *\n * ## Display Priority\n *\n * When multiple attributes are provided, the component determines what to display based on this priority:\n * 1. **Photo** (`src`) - Takes highest priority\n *    - While loading: Shows `initials` as placeholder if provided (instant), otherwise shows icon (requires loading)\n *    - After loading: Shows the photo\n *    - On error: Placeholder remains visible (initials or icon)\n * 2. **Icon** (`icon-name`) - Takes priority if no `src` is provided\n *    - Shows custom icon if `icon-name` is set (requires icon library to load)\n *    - **Note:** If both `icon-name` and `initials` are provided (without `src`), icon takes precedence and initials are ignored.\n *      This means users may see a delay while the icon loads, even though initials render instantly.\n *    - Defaults to `user-regular` icon if no other content is available\n * 3. **Initials** (`initials`) - Displayed only if no `src` or `icon-name` is provided\n *    - Shows first two characters, converted to uppercase\n *    - Renders instantly (no loading required)\n * 4. **Counter** (`counter`) - Displayed only if none of the above are provided\n *    - Shows numeric value (max 99+)\n *    - Negative values display as 0\n *\n * ## Behavior\n * - Non-interactive and non-focusable component (use `mdc-avatarbutton` for clickable avatars)\n * - Shows loading indicator overlay when `is-typing` is true (displays on top of existing content)\n * - Presence indicator hidden when counter is set or when typing\n *\n * @dependency mdc-icon\n * @dependency mdc-presence\n * @dependency mdc-text\n *\n * @tagname mdc-avatar\n *\n * @cssproperty --mdc-avatar-default-background-color - Allows customization of the default background color.\n * @cssproperty --mdc-avatar-default-foreground-color - Allows customization of the default foreground color.\n * @cssproperty --mdc-avatar-loading-indicator-background-color -\n *  Allows customization of the loading indicator background color.\n * @cssproperty --mdc-avatar-loading-indicator-foreground-color -\n *  Allows customization of the loading indicator foreground color.\n * @cssproperty --mdc-avatar-loading-overlay-background-color -\n *  Allows customization of the loading overlay background color.\n *\n * @csspart photo - The photo of the avatar.\n * @csspart presence - The presence indicator of the avatar.\n * @csspart loading-wrapper - The wrapper for the loading indicator.\n * @csspart loader - The loading indicator of the avatar.\n */",
           "customElement": true,
           "attributes": [
             {
@@ -3590,19 +3596,19 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "The `mdc-avatarbutton` component is an interactable version of the `mdc-avatar` component.\n\nThis component is made by extending `buttonsimple` class.\nThe button component acts as a wrapper for the avatar component.\n\nTo override styles of the avatar inside, use the specified css parts.",
+          "description": "The `mdc-avatarbutton` component is an interactive, clickable version of `mdc-avatar`.\nIt wraps the avatar component in a button, making it focusable and actionable.\n\nThis component extends `buttonsimple` and includes all avatar display features (photo, initials, icon, counter, presence).\nUse CSS parts to customize the avatar's appearance inside the button.\n\n## Accessibility\n- Always provide an `aria-label` attribute to describe the button's purpose",
           "name": "AvatarButton",
           "cssProperties": [
             {
-              "description": "Background color of the overlay in rest state",
+              "description": "Background color of the overlay in rest state.",
               "name": "--mdc-avatarbutton-overlay-background-color-rest"
             },
             {
-              "description": "Background color of the overlay in hover state",
+              "description": "Background color of the overlay in hover state.",
               "name": "--mdc-avatarbutton-overlay-background-color-hover"
             },
             {
-              "description": "Background color of the overlay in active state",
+              "description": "Background color of the overlay in active state.",
               "name": "--mdc-avatarbutton-overlay-background-color-active"
             },
             {
@@ -4079,7 +4085,7 @@
           ],
           "events": [
             {
-              "description": "(React: onClick) This event is dispatched when the avatarbutton is clicked.",
+              "description": "(React: onClick) Dispatched when the avatar button is clicked.",
               "name": "click",
               "reactName": "onClick",
               "inheritedFrom": {
@@ -4088,7 +4094,7 @@
               }
             },
             {
-              "description": "(React: onKeyDown) This event is dispatched when a key is pressed down on the avatarbutton.",
+              "description": "(React: onKeyDown) Dispatched when a key is pressed on the avatar button.",
               "name": "keydown",
               "reactName": "onKeyDown",
               "inheritedFrom": {
@@ -4097,7 +4103,7 @@
               }
             },
             {
-              "description": "(React: onKeyUp) This event is dispatched when a key is released on the avatarbutton.",
+              "description": "(React: onKeyUp) Dispatched when a key is released on the avatar button.",
               "name": "keyup",
               "reactName": "onKeyUp",
               "inheritedFrom": {
@@ -4106,7 +4112,7 @@
               }
             },
             {
-              "description": "(React: onFocus) This event is dispatched when the avatarbutton receives focus.",
+              "description": "(React: onFocus) Dispatched when the avatar button receives focus.",
               "name": "focus",
               "reactName": "onFocus",
               "inheritedFrom": {
@@ -4355,7 +4361,7 @@
             "module": "/src/components/buttonsimple/buttonsimple.component"
           },
           "tagName": "mdc-avatarbutton",
-          "jsDoc": "/**\n * The `mdc-avatarbutton` component is an interactable version of the `mdc-avatar` component.\n *\n * This component is made by extending `buttonsimple` class.\n * The button component acts as a wrapper for the avatar component.\n *\n * To override styles of the avatar inside, use the specified css parts.\n *\n * @dependency mdc-avatar\n *\n * @event click - (React: onClick) This event is dispatched when the avatarbutton is clicked.\n * @event keydown - (React: onKeyDown) This event is dispatched when a key is pressed down on the avatarbutton.\n * @event keyup - (React: onKeyUp) This event is dispatched when a key is released on the avatarbutton.\n * @event focus - (React: onFocus) This event is dispatched when the avatarbutton receives focus.\n *\n * @tagname mdc-avatarbutton\n *\n * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state\n * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state\n * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state\n *\n * @csspart overlay - The overlay part of the avatar button.\n * @csspart content - The main content of the avatar.\n * @csspart photo - The photo part of the avatar.\n * @csspart presence - The presence indicator part of the avatar.\n * @csspart loading-wrapper - The wrapper for the loading indicator of the avatar.\n * @csspart loader - The loading indicator part of the avatar.\n */",
+          "jsDoc": "/**\n * The `mdc-avatarbutton` component is an interactive, clickable version of `mdc-avatar`.\n * It wraps the avatar component in a button, making it focusable and actionable.\n *\n * This component extends `buttonsimple` and includes all avatar display features (photo, initials, icon, counter, presence).\n * Use CSS parts to customize the avatar's appearance inside the button.\n *\n * ## Accessibility\n * - Always provide an `aria-label` attribute to describe the button's purpose\n *\n * @dependency mdc-avatar\n *\n * @event click - (React: onClick) Dispatched when the avatar button is clicked.\n * @event keydown - (React: onKeyDown) Dispatched when a key is pressed on the avatar button.\n * @event keyup - (React: onKeyUp) Dispatched when a key is released on the avatar button.\n * @event focus - (React: onFocus) Dispatched when the avatar button receives focus.\n *\n * @tagname mdc-avatarbutton\n *\n * @cssproperty --mdc-avatarbutton-overlay-background-color-rest - Background color of the overlay in rest state.\n * @cssproperty --mdc-avatarbutton-overlay-background-color-hover - Background color of the overlay in hover state.\n * @cssproperty --mdc-avatarbutton-overlay-background-color-active - Background color of the overlay in active state.\n *\n * @csspart overlay - The overlay part of the avatar button.\n * @csspart content - The main content of the avatar.\n * @csspart photo - The photo part of the avatar.\n * @csspart presence - The presence indicator part of the avatar.\n * @csspart loading-wrapper - The wrapper for the loading indicator of the avatar.\n * @csspart loader - The loading indicator part of the avatar.\n */",
           "customElement": true
         }
       ],

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

@@ -1,22 +1,26 @@
 import Component from '../../components/appheader';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout.
- * It consists of three primary sections: leading, center, and trailing.
+ * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
  *
- * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.
- * - The **center section** can contain a **search bar**, **icons** or action controls.
- * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.
+ * ## 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 - Slot for the leading section (e.g., brand logo, brand name).
- * @slot center - Slot for the center section (e.g., search bar, icons).
- * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).
+ * @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 container for styling the header.
- * @csspart leading-section - The leading section of the header.
- * @csspart center-section - The center section of the header.
- * @csspart trailing-section - The trailing section of the header.
+ * @csspart container - The main header container.
+ * @csspart leading-section - The leading section wrapper (left side).
+ * @csspart center-section - The center section wrapper (middle).
+ * @csspart trailing-section - The trailing section wrapper (right side).
  */
 declare const reactWrapper: import("@lit/react").ReactWebComponent<Component, {}>;
 export default reactWrapper;

package/dist/react/appheader/index.js

@@ -3,23 +3,27 @@ import { createComponent } from '@lit/react';
 import Component from '../../components/appheader';
 import { TAG_NAME } from '../../components/appheader/appheader.constants';
 /**
- * The `mdc-appheader` component provides a structured and accessible app header layout.
- * It consists of three primary sections: leading, center, and trailing.
+ * The `mdc-appheader` component provides a structured and accessible app header layout with three sections: leading, center, and trailing.
  *
- * - The **leading section** typically holds a **brand logo**, **brand name** or **menu icon**.
- * - The **center section** can contain a **search bar**, **icons** or action controls.
- * - The **trailing section** generally includes a **profile avatar**, **additional icons** or **action controls**.
+ * ## 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 - Slot for the leading section (e.g., brand logo, brand name).
- * @slot center - Slot for the center section (e.g., search bar, icons).
- * @slot trailing - Slot for the trailing section (e.g., profile avatar, icons).
+ * @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 container for styling the header.
- * @csspart leading-section - The leading section of the header.
- * @csspart center-section - The center section of the header.
- * @csspart trailing-section - The trailing section of the header.
+ * @csspart container - The main header container.
+ * @csspart leading-section - The leading section wrapper (left side).
+ * @csspart center-section - The center section wrapper (middle).
+ * @csspart trailing-section - The trailing section wrapper (right side).
  */
 const reactWrapper = createComponent({
     tagName: TAG_NAME,

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

@@ -1,23 +1,30 @@
 import Component from '../../components/avatar';
 /**
- * The `mdc-avatar` component is used to represent a person or a space.
- * An avatar can be an icon, initials, counter and photo.
- *
- * To set the photo of an avatar,
- * you need to set "src" attribute.
- *
- * While the avatar image is loading, as a placeholder,
- * we will show the initials text.
- * If the initials are not specified then,
- * we will show `user-regular` icon as a placeholder.
- *
- * By default, if there are no attributes specified,
- * then the default avatar will be an icon with `user-regular` name.
- *
- * The avatar component is non clickable and non interactive/focusable component.
- * If the avatar is typing, then the loading indicator will be displayed.
- * If the counter type avatar is set to a negative number, then we will display 0.
- * The presence indicator will be hidden when the counter property is set.
+ * 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
  *
  * @dependency mdc-icon
  * @dependency mdc-presence