@momentum-design/components 0.12.3 → 0.12.4

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

@@ -1,28 +1,229 @@
 import { CSSResult } from 'lit';
+import type { PropertyValues, TemplateResult } from 'lit';
 import { Component } from '../../models';
-import { AvatarType } from './avatar.types';
+import type { IconNames } from '../icon/icon.types';
+import type { PresenceType } from '../presence/presence.types';
+import type { AvatarSize } from './avatar.types';
 /**
- * @slot - This is a default/unnamed slot
+ * The `mdc-avatar` component is used to represent a person or a space.
+ * An avatar can be an icon, initials, counter and photo.
  *
- * @summary This is MyElement
+ * 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.
+ *
+ * @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 -
+ *  Allows customization of the loading indicator background color.
+ * @cssproperty --mdc-avatar-loading-indicator-foreground-color -
+ *  Allows customization of the loading indicator foreground color.
+ * @cssproperty --mdc-avatar-loading-overlay-background-color -
+ *  Allows customization of the loading overlay background color.
  */
 declare class Avatar extends Component {
-    type?: AvatarType;
-    alt?: string;
+    /**
+     * The src is the url which will be used to display the avatar.
+     * When the src is loading, we will display the initials as a placeholder.
+     */
     src?: string;
     /**
-     * Scale of the avatar
+     * The initials to be displayed for the avatar.
+     */
+    initials?: string;
+    /**
+     * The presence is the status which can be used to display the
+     * activity state of a user or a space within an avatar component.
+     *
+     * Acceptable values include:
+     * - `active`
+     * - `away`
+     * - `away-calling`
+     * - `busy`
+     * - `dnd`
+     * - `meeting`
+     * - `on-call`
+     * - `on-device`
+     * - `on-mobile`
+     * - `pause`
+     * - `pto`
+     * - `presenting`
+     * - `quiet`
+     * - `scheduled`
+     */
+    presence?: PresenceType;
+    /**
+     * Acceptable values include:
+     * - xx_small
+     * - x_small
+     * - small
+     * - midsize
+     * - large
+     * - x_large
+     * - xx_large
+     *
+     * @default x_small
+     */
+    size: AvatarSize;
+    /**
+     * Name of the icon to be displayed inside the Avatar.
+     * Must be a valid icon name.
+     */
+    iconName?: IconNames;
+    /**
+     * The counter is the number which can be displayed on the avatar.
+     * The maximum number is 99 and if the give number is greater than 99,
+     * then the avatar will be displayed as `99+`.
+     * If the given number is a negative number,
+     * then the avatar will be displayed as `0`.
+     */
+    counter?: number;
+    /**
+     * Represents the typing indicator when the user is typing.
+     * @default false
+     */
+    isTyping: boolean;
+    /**
+     * @internal
+     */
+    private isPhotoLoaded;
+    /**
+     * @internal
+     * The avatar presence will be hidden if the avatar type is COUNTER.
+     * If the presence is set, it will be rendered as a child of the avatar.
+     *
+     * @param type - The type of the avatar.
+     * @returns The presence template or an empty template.
+     */
+    private getPresenceTemplateBasedOnType;
+    /**
+     * @internal
+     * Sets `isPhotoLoaded` to `true` when the avatar photo is loaded.
+     * This is used to hide the avatar photo initially and show it only when it is loaded.
+     */
+    private handleOnLoad;
+    /**
+     * @internal
+     * Handles errors that occur during the image loading process.
+     * Sets `isPhotoLoaded` to `false` to indicate the failure and throws an error message.
+     * The error message suggests checking the `src` attribute.
+     */
+    private handleOnError;
+    /**
+     * @internal
+     * Generates the photo template for the avatar component.
+     * Utilizes the `src` attribute to display an image.
+     * The photo remains hidden until it is fully loaded;
+     * upon successful loading, the `handleOnLoad` method sets `isPhotoLoaded` to true.
+     * In the event of a loading error, the `handleOnError` method sets `isPhotoLoaded` to false and raises an error.
+     *
+     * @returns The template result containing the avatar photo.
+     */
+    private photoTemplate;
+    /**
+     * @internal
+     * Generates the icon template for the photo avatar component.
+     * Utilizes the `mdc-icon` component to display an icon.
+     * If the `iconName` property is not provided, it defaults to the `DEFAULTS.ICON_NAME`.
+     *
+     * @returns The template result containing the avatar icon.
+     */
+    private iconTemplate;
+    /**
+     * @internal
+     * Generates the text template for the initials/counter avatar component.
+     * Utilizes the `mdc-text` component to display text.
+     *
+     * @param content - the text content to be displayed
+     * @returns The template result containing the avatar text.
+     */
+    private textTemplate;
+    /**
+     * @internal
+     * Generates the text content for counter avatar by converting the given number to a string.
+     * If the counter exceeds the maximum limit of 99, it will return the maximum limit as a string
+     * followed by a '+' character.
+     *
+     * @param counter - the number to be converted to a string
+     * @returns the counter text
+     */
+    private generateCounterText;
+    /**
+     * @internal
+     * Converts the given initials to uppercase and takes the first two characters.
+     * This is used to generate the text content for the initials avatar.
+     *
+     * @param initials - the string containing the initials
+     * @returns the first two uppercase characters of the given initials
+     */
+    private generateInitialsText;
+    /**
+     * @internal
+     * Generates the text content based on the given type.
+     * If the type is TEXT, it will use the initials property and generate the first two uppercase characters.
+     * If the type is COUNTER, it uses the value of counter property and
+     * generate the string representation of the counter.
+     * The generated content is then passed to the `textTemplate` method to generate the final template.
+     *
+     * @param type - the type of the avatar
+     * @returns the template result containing the avatar text
+     */
+    private generateTextContent;
+    /**
+     * @internal
+     * Returns the type of the avatar component based on the user-provided inputs.
+     *
+     * @returns the type of the avatar component
+     */
+    private getTypeBasedOnInputs;
+    /**
+     * @internal
+     * Returns the template result based on the type of the avatar component.
+     * The type is determined by `getTypeBasedOnInputs` based on user's input.
+     * Based on the generated type, template result is generated.
+     *
+     * @param type - the type of the avatar component
+     * @returns the template result containing the avatar content
+     */
+    private getTemplateBasedOnType;
+    /**
+     * @internal
+     * Represents the loading indicator for the avatar when typing.
+     * If the avatar is in typing state, this method returns a loading indicator
+     * comprising three small filled dots, scaled based on the avatar size.
+     *
+     * @returns The template result containing the loading indicator, or an empty template if not typing.
      */
-    size?: number;
+    private getLoadingContent;
     /**
-     * Updates the size by setting the width and height
+     * @internal
+     * Generates the photo placeholder content for the avatar component.
+     * If the photo is not yet loaded, and the avatar type is PHOTO with initials provided,
+     * it generates and returns the initials as a placeholder text.
+     * If the photo is already loaded, it returns an empty template.
+     *
+     * @param type - The type of the avatar.
+     * @returns The template result containing the placeholder content or an empty template.
      */
-    private updateSize;
-    updated(changedProperties: Map<string, any>): void;
-    photoTemplate(): import("lit-html").TemplateResult<1>;
-    render(): import("lit-html").TemplateResult<1>;
+    private getPhotoPlaceHolderContent;
+    update(changedProperties: PropertyValues): void;
+    render(): TemplateResult;
     static styles: Array<CSSResult>;
 }
 export default Avatar;

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

@@ -7,78 +7,350 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
-import { html } from 'lit';
-import { property } from 'lit/decorators.js';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
-import styles from './avatar.styles';
 import { Component } from '../../models';
-import { DEFAULTS, LENGTH_UNIT } from './avatar.constants';
+import { AVATAR_TYPE, DEFAULTS, MAX_COUNTER } from './avatar.constants';
+import styles from './avatar.styles';
+import { getAvatarIconSize, getAvatarTextFontSize } from './avatar.utils';
 /**
- * @slot - This is a default/unnamed slot
+ * 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.
  *
- * @summary This is MyElement
+ * The avatar component is non clickable and non interactive/focusable component.
+ * If the avatar is typing, then the loading indicator will be displayed.
+ *
+ * @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 -
+ *  Allows customization of the loading indicator background color.
+ * @cssproperty --mdc-avatar-loading-indicator-foreground-color -
+ *  Allows customization of the loading indicator foreground color.
+ * @cssproperty --mdc-avatar-loading-overlay-background-color -
+ *  Allows customization of the loading overlay background color.
  */
 class Avatar extends Component {
     constructor() {
         super(...arguments);
-        this.type = DEFAULTS.TYPE;
         /**
-         * Scale of the avatar
+         * Acceptable values include:
+         * - xx_small
+         * - x_small
+         * - small
+         * - midsize
+         * - large
+         * - x_large
+         * - xx_large
+         *
+         * @default x_small
          */
         this.size = DEFAULTS.SIZE;
+        /**
+         * Represents the typing indicator when the user is typing.
+         * @default false
+         */
+        this.isTyping = false;
+        /**
+         * @internal
+         */
+        this.isPhotoLoaded = false;
     }
     /**
-     * Updates the size by setting the width and height
+     * @internal
+     * The avatar presence will be hidden if the avatar type is COUNTER.
+     * If the presence is set, it will be rendered as a child of the avatar.
+     *
+     * @param type - The type of the avatar.
+     * @returns The presence template or an empty template.
      */
-    updateSize() {
-        if (this.size) {
-            const value = `${this.size}${LENGTH_UNIT}`;
-            this.style.width = value;
-            this.style.height = value;
+    getPresenceTemplateBasedOnType(type) {
+        // avatar type of counter should not have presence
+        if (type === AVATAR_TYPE.COUNTER && (this.counter || this.counter === 0)) {
+            return nothing;
+        }
+        if (this.presence) {
+            return html `
+        <mdc-presence class="presence" type="${this.presence}" size="${this.size}"></mdc-presence>
+      `;
         }
+        return nothing;
+    }
+    /**
+     * @internal
+     * Sets `isPhotoLoaded` to `true` when the avatar photo is loaded.
+     * This is used to hide the avatar photo initially and show it only when it is loaded.
+     */
+    handleOnLoad() {
+        this.isPhotoLoaded = true;
     }
-    updated(changedProperties) {
-        super.updated(changedProperties);
-        if (changedProperties.has('size')) {
-            this.updateSize();
+    /**
+     * @internal
+     * Handles errors that occur during the image loading process.
+     * Sets `isPhotoLoaded` to `false` to indicate the failure and throws an error message.
+     * The error message suggests checking the `src` attribute.
+     */
+    handleOnError() {
+        this.isPhotoLoaded = false;
+        if (this.onerror) {
+            this.onerror('There was a problem while fetching the <img/>. Please check the src attribute and try again.');
         }
     }
+    /**
+     * @internal
+     * Generates the photo template for the avatar component.
+     * Utilizes the `src` attribute to display an image.
+     * The photo remains hidden until it is fully loaded;
+     * upon successful loading, the `handleOnLoad` method sets `isPhotoLoaded` to true.
+     * In the event of a loading error, the `handleOnError` method sets `isPhotoLoaded` to false and raises an error.
+     *
+     * @returns The template result containing the avatar photo.
+     */
     photoTemplate() {
         return html `
       <img
+        class="photo"
         src="${ifDefined(this.src)}"
-        alt="${ifDefined(this.alt)}"
+        aria-hidden="true"
+        ?hidden="${!this.isPhotoLoaded}"
+        @load="${this.handleOnLoad}"
+        @error="${this.handleOnError}"
       />
     `;
     }
-    render() {
-        let content;
-        if (this.type === 'photo') {
-            content = this.photoTemplate();
+    /**
+     * @internal
+     * Generates the icon template for the photo avatar component.
+     * Utilizes the `mdc-icon` component to display an icon.
+     * If the `iconName` property is not provided, it defaults to the `DEFAULTS.ICON_NAME`.
+     *
+     * @returns The template result containing the avatar icon.
+     */
+    iconTemplate() {
+        const name = this.iconName || DEFAULTS.ICON_NAME;
+        return html `
+      <mdc-icon
+        name="${ifDefined(name)}"
+        length-unit="rem"
+        size="${getAvatarIconSize(this.size)}"
+      ></mdc-icon>
+    `;
+    }
+    /**
+     * @internal
+     * Generates the text template for the initials/counter avatar component.
+     * Utilizes the `mdc-text` component to display text.
+     *
+     * @param content - the text content to be displayed
+     * @returns The template result containing the avatar text.
+     */
+    textTemplate(content) {
+        return html `
+      <mdc-text
+        type="${getAvatarTextFontSize(this.size)}"
+        tagname="span"
+      >
+        ${content}
+      </mdc-text>
+    `;
+    }
+    /**
+     * @internal
+     * Generates the text content for counter avatar by converting the given number to a string.
+     * If the counter exceeds the maximum limit of 99, it will return the maximum limit as a string
+     * followed by a '+' character.
+     *
+     * @param counter - the number to be converted to a string
+     * @returns the counter text
+     */
+    generateCounterText(counter) {
+        // If the consumer provides a negative number, we set it to 0.
+        if (counter < 0) {
+            return '0';
+        }
+        if (counter > MAX_COUNTER) {
+            return `${MAX_COUNTER}+`;
+        }
+        return counter.toString();
+    }
+    /**
+     * @internal
+     * Converts the given initials to uppercase and takes the first two characters.
+     * This is used to generate the text content for the initials avatar.
+     *
+     * @param initials - the string containing the initials
+     * @returns the first two uppercase characters of the given initials
+     */
+    generateInitialsText(initials) {
+        return initials.toUpperCase().slice(0, 2);
+    }
+    /**
+     * @internal
+     * Generates the text content based on the given type.
+     * If the type is TEXT, it will use the initials property and generate the first two uppercase characters.
+     * If the type is COUNTER, it uses the value of counter property and
+     * generate the string representation of the counter.
+     * The generated content is then passed to the `textTemplate` method to generate the final template.
+     *
+     * @param type - the type of the avatar
+     * @returns the template result containing the avatar text
+     */
+    generateTextContent(type) {
+        let content = '';
+        if (type === AVATAR_TYPE.TEXT && this.initials) {
+            content = this.generateInitialsText(this.initials);
         }
-        else {
-            content = html ``;
+        if (type === AVATAR_TYPE.COUNTER && (this.counter || this.counter === 0)) {
+            content = this.generateCounterText(this.counter);
         }
-        return html `${content}`;
+        return this.textTemplate(content);
+    }
+    /**
+     * @internal
+     * Returns the type of the avatar component based on the user-provided inputs.
+     *
+     * @returns the type of the avatar component
+     */
+    getTypeBasedOnInputs() {
+        if (this.src) {
+            return AVATAR_TYPE.PHOTO;
+        }
+        if (this.iconName) {
+            return AVATAR_TYPE.ICON;
+        }
+        if (this.initials) {
+            return AVATAR_TYPE.TEXT;
+        }
+        if (this.counter || this.counter === 0) {
+            return AVATAR_TYPE.COUNTER;
+        }
+        return AVATAR_TYPE.ICON;
+    }
+    /**
+     * @internal
+     * Returns the template result based on the type of the avatar component.
+     * The type is determined by `getTypeBasedOnInputs` based on user's input.
+     * Based on the generated type, template result is generated.
+     *
+     * @param type - the type of the avatar component
+     * @returns the template result containing the avatar content
+     */
+    getTemplateBasedOnType(type) {
+        switch (type) {
+            case AVATAR_TYPE.PHOTO:
+                return this.photoTemplate();
+            case AVATAR_TYPE.TEXT:
+            case AVATAR_TYPE.COUNTER:
+                return this.generateTextContent(type);
+            case AVATAR_TYPE.ICON:
+            default:
+                return this.iconTemplate();
+        }
+    }
+    /**
+     * @internal
+     * Represents the loading indicator for the avatar when typing.
+     * If the avatar is in typing state, this method returns a loading indicator
+     * comprising three small filled dots, scaled based on the avatar size.
+     *
+     * @returns The template result containing the loading indicator, or an empty template if not typing.
+     */
+    getLoadingContent() {
+        if (!this.isTyping) {
+            return nothing;
+        }
+        return html `<div class="loading__wrapper"><div class="loader"></div></div>`;
+    }
+    /**
+     * @internal
+     * Generates the photo placeholder content for the avatar component.
+     * If the photo is not yet loaded, and the avatar type is PHOTO with initials provided,
+     * it generates and returns the initials as a placeholder text.
+     * If the photo is already loaded, it returns an empty template.
+     *
+     * @param type - The type of the avatar.
+     * @returns The template result containing the placeholder content or an empty template.
+     */
+    getPhotoPlaceHolderContent(type) {
+        // if photo is already loaded then no need to show placeholder
+        if (this.isPhotoLoaded) {
+            return nothing;
+        }
+        if (type === AVATAR_TYPE.PHOTO) {
+            if (this.initials) {
+                return this.textTemplate(this.generateInitialsText(this.initials));
+            }
+            return this.iconTemplate();
+        }
+        return nothing;
+    }
+    update(changedProperties) {
+        super.update(changedProperties);
+        if (changedProperties.has('src') && !this.src) {
+            // Reset photo loaded if src is empty
+            this.isPhotoLoaded = false;
+        }
+    }
+    render() {
+        const type = this.getTypeBasedOnInputs();
+        return html `
+      <div class="content" aria-hidden="true">
+        ${this.getPhotoPlaceHolderContent(type)}
+        ${this.getTemplateBasedOnType(type)}
+        ${this.getLoadingContent()}
+        ${this.getPresenceTemplateBasedOnType(type)}
+      </div>
+    `;
     }
 }
 Avatar.styles = [...Component.styles, ...styles];
 __decorate([
-    property({ type: String, reflect: true }),
+    property({ type: String }),
     __metadata("design:type", String)
-], Avatar.prototype, "type", void 0);
+], Avatar.prototype, "src", void 0);
 __decorate([
     property({ type: String }),
     __metadata("design:type", String)
-], Avatar.prototype, "alt", void 0);
+], Avatar.prototype, "initials", void 0);
 __decorate([
     property({ type: String }),
     __metadata("design:type", String)
-], Avatar.prototype, "src", void 0);
+], Avatar.prototype, "presence", void 0);
+__decorate([
+    property({ type: String, reflect: true }),
+    __metadata("design:type", String)
+], Avatar.prototype, "size", void 0);
+__decorate([
+    property({ type: String, attribute: 'icon-name' }),
+    __metadata("design:type", String)
+], Avatar.prototype, "iconName", void 0);
 __decorate([
     property({ type: Number }),
     __metadata("design:type", Number)
-], Avatar.prototype, "size", void 0);
+], Avatar.prototype, "counter", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'is-typing' }),
+    __metadata("design:type", Object)
+], Avatar.prototype, "isTyping", void 0);
+__decorate([
+    state(),
+    __metadata("design:type", Object)
+], Avatar.prototype, "isPhotoLoaded", void 0);
 export default Avatar;

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

@@ -1,7 +1,14 @@
 declare const TAG_NAME: "mdc-avatar";
-declare const LENGTH_UNIT = "rem";
+declare const AVATAR_TYPE: {
+    readonly COUNTER: "counter";
+    readonly ICON: "icon";
+    readonly PHOTO: "photo";
+    readonly TEXT: "text";
+};
+declare const MAX_COUNTER = 99;
 declare const DEFAULTS: {
     readonly TYPE: "photo";
-    readonly SIZE: 1.5;
+    readonly SIZE: "x_small";
+    readonly ICON_NAME: "user-regular";
 };
-export { TAG_NAME, DEFAULTS, LENGTH_UNIT };
+export { TAG_NAME, DEFAULTS, AVATAR_TYPE, MAX_COUNTER, };

package/dist/components/avatar/avatar.constants.js

@@ -1,8 +1,17 @@
 import utils from '../../utils/tag-name';
+import { SIZE as AVATAR_SIZE } from '../presence/presence.constants';
 const TAG_NAME = utils.constructTagName('avatar');
-const LENGTH_UNIT = 'rem';
+const AVATAR_TYPE = {
+    COUNTER: 'counter',
+    ICON: 'icon',
+    PHOTO: 'photo',
+    TEXT: 'text',
+};
+const MAX_COUNTER = 99;
+const ICON_NAME = 'user-regular';
 const DEFAULTS = {
-    TYPE: 'photo',
-    SIZE: 1.5,
+    TYPE: AVATAR_TYPE.PHOTO,
+    SIZE: AVATAR_SIZE.X_SMALL,
+    ICON_NAME,
 };
-export { TAG_NAME, DEFAULTS, LENGTH_UNIT };
+export { TAG_NAME, DEFAULTS, AVATAR_TYPE, MAX_COUNTER, };

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

@@ -1,2 +1,2 @@
-declare const _default: import("lit").CSSResult[];
-export default _default;
+declare const styles: import("lit").CSSResult[];
+export default styles;