@pine-ds/core 5.0.0-mercury.0 → 5.0.0

package/dist/collection/components/pds-avatar/pds-avatar.js

@@ -1,47 +1,140 @@
 import { Host, h } from "@stencil/core";
 import { checkCircleFilled, userFilled } from "@pine-ds/icons/icons";
+import { restoreReflectedDefault } from "../../utils/reflected-attribute-default";
+// Used when `badgeLabel` is unset; an empty string hides the badge instead.
+const DEFAULT_BADGE_LABEL = 'Verified';
 /**
- * @part image - The main image element that represents the avatar component.
+ * @part asset-wrapper - Exposes the sized wrapper around the avatar's image, initials or icon, badge and status dot for styling.
+ * @part button - Exposes the dropdown trigger button for styling. Appears only when `dropdown` is set.
+ * @part initials - The text element that renders the avatar's initials, for restyling their color.
+ * @part status - Exposes the status dot for styling, such as a custom color. Appears only when `status` is set.
 */
 export class PdsAvatar {
     constructor() {
+        /**
+         * The alt for a custom user image.
+         * @defaultValue null
+         */
+        this.alt = null;
+        /**
+         * Determines whether the badge is visible or not.
+         * @defaultValue false
+         */
+        this.badge = false;
+        /**
+         * Determines whether the avatar functions as a dropdown trigger.
+         * @defaultValue false
+         */
+        this.dropdown = false;
+        /**
+         * The src for a custom user image.
+         * @defaultValue null
+         */
+        this.image = null;
+        /**
+         * The initials to display in the avatar when no image is provided.
+         * @defaultValue null
+         */
+        this.initials = null;
+        /**
+         * Sets the size of the avatar: `xs` (24px), `sm` (32px), `md` (40px), `lg` (56px), `xl` (64px),
+         * or a custom CSS length such as `128px`.
+         * @defaultValue lg
+         */
+        this.size = 'lg';
+        /**
+         * Displays a presence status indicator (a dot) on the avatar: `online`
+         * (success), `away` (warning), or `offline` (neutral). For a simple
+         * active/inactive presence, map active to `online` and inactive to `offline`.
+         * Takes precedence over `badge` — they share the same corner, so the badge is
+         * hidden while `status` is set.
+         * @defaultValue null
+         */
+        this.status = null;
+        /**
+         * Determines whether a ring is shown around the avatar in the `status` color.
+         * Has no effect unless `status` is set.
+         * @defaultValue false
+         */
+        this.statusRing = false;
+        /**
+         * Determines the variant of avatar. Changes appearance accordingly.
+         * @defaultValue customer
+         */
+        this.variant = 'customer';
+        /**
+         * Accessible label for the dropdown trigger button. Pass a translated string
+         * to localize it; defaults to English.
+         * @defaultValue 'Avatar dropdown trigger'
+         */
+        this.triggerLabel = 'Avatar dropdown trigger';
         this.renderAssetWrapper = () => {
             const style = {
                 height: this.avatarSize(),
                 width: this.avatarSize()
             };
-            return (h("div", { style: style, part: "asset-wrapper" }, this.renderIconOrImage(), this.renderBadge()));
+            return (h("div", { style: style, part: "asset-wrapper" }, this.renderIconOrImage(), this.renderBadge(), this.renderStatus()));
         };
         this.renderAvatar = () => {
             return (this.dropdown
                 ?
-                    h("button", { class: "pds-avatar__button", type: "button", "aria-label": "Avatar dropdown trigger" }, this.renderAssetWrapper())
+                    h("button", { class: "pds-avatar__button", type: "button", part: "button", "aria-label": this.triggerLabel }, this.renderAssetWrapper())
                 :
                     this.renderAssetWrapper());
         };
-        this.renderBadge = () => (this.badge
-            // Percentage is average size of icon in relation to total avatar size
-            // of all preset sizes found in Figma.
-            // Used to allow icons to scale to container size
-            && h("pds-icon", { class: "pds-avatar__badge", icon: checkCircleFilled, size: "33.53%" }));
-        this.renderIconOrImage = () => (this.image
-            ? h("img", { alt: this.alt, src: this.image })
+        this.renderBadge = () => {
+            var _a;
+            // Inside the dropdown trigger the button's aria-label is the name, so the
+            // badge is decorative there, as the status dot is. An empty label is
+            // decorative too, rather than an image with no name.
+            const badgeLabel = (_a = this.badgeLabel) !== null && _a !== void 0 ? _a : DEFAULT_BADGE_LABEL;
+            const label = this.dropdown || badgeLabel === '' ? undefined : badgeLabel;
+            return (
+            // `badge` and `status` share the bottom-end corner; `status` wins so the
+            // presence dot is never painted over the badge.
+            this.badge && !this.status
+                // Percentage is average size of icon in relation to total avatar size
+                // of all preset sizes found in Figma.
+                // Used to allow icons to scale to container size
+                && h("pds-icon", { color: "var(--pine-color-purple-600)", class: "pds-avatar__badge", icon: checkCircleFilled, size: "33.53%", "aria-label": label, "aria-hidden": label === undefined ? 'true' : undefined }));
+        };
+        this.renderStatus = () => {
+            var _a;
+            if (!this.status)
+                return null;
+            // Inside the dropdown trigger, the button's aria-label owns the accessible
+            // name, so the dot's own label is never announced. Mark it decorative there
+            // and let consumers convey presence via `triggerLabel`.
+            if (this.dropdown) {
+                return h("span", { class: "pds-avatar__status", part: "status", "aria-hidden": "true" });
+            }
+            return (h("span", { class: "pds-avatar__status", part: "status", role: "img", "aria-label": (_a = this.statusLabel) !== null && _a !== void 0 ? _a : `${this.status} status` }));
+        };
+        this.renderIconOrImage = () => {
+            if (this.image) {
+                return h("img", { alt: this.alt, src: this.image });
+            }
+            if (this.initials) {
+                return (h("svg", { class: "pds-avatar__initials", part: "initials", viewBox: "0 0 32 32" }, h("text", { x: "16", y: "20" }, this.initials)));
+            }
             // Percentage is average size of icon in relation to total avatar size
             // of all preset sizes found in Figma.
             // Used to allow icons to scale to container size
-            : h("pds-icon", { color: "var(--pine-color-blue-400)", icon: userFilled, size: "33.53%" }));
+            return h("pds-icon", { color: "var(--pine-color-brand)", icon: userFilled, size: "33.53%", "aria-hidden": "true" });
+        };
         this.classNames = () => ({
             'pds-avatar': true,
             [`pds-avatar--has-image`]: this.image !== '' && this.image !== null, // Remove when FF supports :has selector
-            [`pds-avatar--${this.variant}`]: this.variant === 'admin'
+            [`pds-avatar--has-initials`]: this.initials !== '' && this.initials !== null,
+            [`pds-avatar--${this.variant}`]: this.variant === 'admin',
+            [`pds-avatar--status-ring`]: !!this.status && this.statusRing,
         });
-        this.alt = null;
-        this.badge = false;
-        this.componentId = undefined;
-        this.dropdown = false;
-        this.image = null;
-        this.size = 'lg';
-        this.variant = 'customer';
+    }
+    restoreSizeDefault(newValue) {
+        this.size = restoreReflectedDefault(this.el, 'size', newValue, 'lg');
+    }
+    restoreVariantDefault(newValue) {
+        this.variant = restoreReflectedDefault(this.el, 'variant', newValue, 'customer');
     }
     avatarSize() {
         const sizes = {
@@ -59,7 +152,7 @@ export class PdsAvatar {
         }
     }
     render() {
-        return (h(Host, { key: '8c43a9de8b7799b5aafff0c12c2e95e53bed2041', id: this.componentId, class: Object.assign({}, this.classNames()) }, this.renderAvatar()));
+        return (h(Host, { key: '237598a069d4a3b1281b10b516c01c6d479ca3e9', class: Object.assign({}, this.classNames()) }, this.renderAvatar()));
     }
     static get is() { return "pds-avatar"; }
     static get encapsulation() { return "shadow"; }
@@ -92,8 +185,10 @@ export class PdsAvatar {
                         }],
                     "text": "The alt for a custom user image."
                 },
-                "attribute": "alt",
+                "getter": false,
+                "setter": false,
                 "reflect": false,
+                "attribute": "alt",
                 "defaultValue": "null"
             },
             "badge": {
@@ -113,10 +208,34 @@ export class PdsAvatar {
                         }],
                     "text": "Determines whether the badge is visible or not."
                 },
-                "attribute": "badge",
+                "getter": false,
+                "setter": false,
                 "reflect": false,
+                "attribute": "badge",
                 "defaultValue": "false"
             },
+            "badgeLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "'Verified'"
+                        }],
+                    "text": "Accessible label for the badge icon. Pass a translated string to localize\nit; defaults to English. Pass an empty string to make the badge\ndecorative. Has no effect on dropdown avatars, where the trigger's\n`triggerLabel` owns the accessible name."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "badge-label"
+            },
             "componentId": {
                 "type": "string",
                 "mutable": false,
@@ -129,10 +248,12 @@ export class PdsAvatar {
                 "optional": false,
                 "docs": {
                     "tags": [],
-                    "text": "A unique identifier used for the underlying component `id` attribute."
+                    "text": "A unique identifier for this component instance. Does not set the host element's `id` attribute \u2014 set `id` directly if you need one."
                 },
-                "attribute": "component-id",
-                "reflect": false
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "component-id"
             },
             "dropdown": {
                 "type": "boolean",
@@ -151,8 +272,10 @@ export class PdsAvatar {
                         }],
                     "text": "Determines whether the avatar functions as a dropdown trigger."
                 },
-                "attribute": "dropdown",
+                "getter": false,
+                "setter": false,
                 "reflect": false,
+                "attribute": "dropdown",
                 "defaultValue": "false"
             },
             "image": {
@@ -172,13 +295,38 @@ export class PdsAvatar {
                         }],
                     "text": "The src for a custom user image."
                 },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
                 "attribute": "image",
+                "defaultValue": "null"
+            },
+            "initials": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string | null",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "null"
+                        }],
+                    "text": "The initials to display in the avatar when no image is provided."
+                },
+                "getter": false,
+                "setter": false,
                 "reflect": false,
+                "attribute": "initials",
                 "defaultValue": "null"
             },
             "size": {
                 "type": "string",
-                "mutable": false,
+                "mutable": true,
                 "complexType": {
                     "original": "| 'xl' // 64px\n  | 'lg' // 56px\n  | 'md' // 40px\n  | 'sm' // 32px\n  | 'xs' // 24px\n  | string",
                     "resolved": "string",
@@ -191,15 +339,85 @@ export class PdsAvatar {
                             "name": "defaultValue",
                             "text": "lg"
                         }],
-                    "text": "Size of the avatar. Value can be preset or custom."
+                    "text": "Sets the size of the avatar: `xs` (24px), `sm` (32px), `md` (40px), `lg` (56px), `xl` (64px),\nor a custom CSS length such as `128px`."
                 },
-                "attribute": "size",
+                "getter": false,
+                "setter": false,
                 "reflect": true,
+                "attribute": "size",
                 "defaultValue": "'lg'"
             },
-            "variant": {
+            "status": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "'online' | 'away' | 'offline' | null",
+                    "resolved": "\"away\" | \"offline\" | \"online\"",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "null"
+                        }],
+                    "text": "Displays a presence status indicator (a dot) on the avatar: `online`\n(success), `away` (warning), or `offline` (neutral). For a simple\nactive/inactive presence, map active to `online` and inactive to `offline`.\nTakes precedence over `badge` \u2014 they share the same corner, so the badge is\nhidden while `status` is set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": true,
+                "attribute": "status",
+                "defaultValue": "null"
+            },
+            "statusLabel": {
                 "type": "string",
                 "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "null"
+                        }],
+                    "text": "Accessible label for the presence status indicator. Pass a translated\nstring to localize it; defaults to English (`\"{status} status\"`). Has no\neffect on dropdown avatars, where the trigger's `triggerLabel` owns the\naccessible name \u2014 fold presence into `triggerLabel` there."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "status-label"
+            },
+            "statusRing": {
+                "type": "boolean",
+                "mutable": false,
+                "complexType": {
+                    "original": "boolean",
+                    "resolved": "boolean",
+                    "references": {}
+                },
+                "required": false,
+                "optional": true,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "false"
+                        }],
+                    "text": "Determines whether a ring is shown around the avatar in the `status` color.\nHas no effect unless `status` is set."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "status-ring",
+                "defaultValue": "false"
+            },
+            "variant": {
+                "type": "string",
+                "mutable": true,
                 "complexType": {
                     "original": "'customer' | 'admin'",
                     "resolved": "\"admin\" | \"customer\"",
@@ -214,11 +432,45 @@ export class PdsAvatar {
                         }],
                     "text": "Determines the variant of avatar. Changes appearance accordingly."
                 },
-                "attribute": "variant",
+                "getter": false,
+                "setter": false,
                 "reflect": true,
+                "attribute": "variant",
                 "defaultValue": "'customer'"
+            },
+            "triggerLabel": {
+                "type": "string",
+                "mutable": false,
+                "complexType": {
+                    "original": "string",
+                    "resolved": "string",
+                    "references": {}
+                },
+                "required": false,
+                "optional": false,
+                "docs": {
+                    "tags": [{
+                            "name": "defaultValue",
+                            "text": "'Avatar dropdown trigger'"
+                        }],
+                    "text": "Accessible label for the dropdown trigger button. Pass a translated string\nto localize it; defaults to English."
+                },
+                "getter": false,
+                "setter": false,
+                "reflect": false,
+                "attribute": "trigger-label",
+                "defaultValue": "'Avatar dropdown trigger'"
             }
         };
     }
+    static get elementRef() { return "el"; }
+    static get watchers() {
+        return [{
+                "propName": "size",
+                "methodName": "restoreSizeDefault"
+            }, {
+                "propName": "variant",
+                "methodName": "restoreVariantDefault"
+            }];
+    }
 }
-//# sourceMappingURL=pds-avatar.js.map

package/dist/collection/components/pds-avatar/stories/pds-avatar.stories.js

@@ -1,7 +1,7 @@
 import { html } from 'lit';
+import { ifDefined } from 'lit/directives/if-defined.js';
 import imgFile from '../assets/demi_wilkinson.jpg';
 
-import { extractArgTypes } from '@pxtrn/storybook-addon-docs-stencil';
 
 export default {
   args: {
@@ -10,10 +10,12 @@ export default {
 		componentId: null,
     dropdown: false,
     image: null,
+    initials: null,
     size: null,
+    status: null,
+    statusRing: false,
     variant: 'customer',
   },
-  argTypes: extractArgTypes('pds-avatar'),
   component: 'pds-avatar',
   title: 'components/Avatar',
 }
@@ -21,10 +23,14 @@ export default {
 const BaseTemplate = (args) => html`<pds-avatar
 	alt="${args.alt}"
 	badge="${args.badge}"
+	badge-label=${ifDefined(args.badgeLabel)}
 	dropdown="${args.dropdown}"
 	component-id="${args.componentId}"
 	image="${args.image}"
+	initials="${args.initials}"
 	size="${args.size}"
+	status="${args.status}"
+	status-ring="${args.statusRing}"
 	variant="${args.variant}"
 >
 </pds-avatar>`;
@@ -59,7 +65,39 @@ DropdownTrigger.args = {
 
 export const Image = BaseTemplate.bind();
 Image.args = {
-	alt: 'Customer Profile',
+	alt: 'Demi Wilkinson',
 	image: imgFile,
 	size: 'xl'
 }
+
+export const Initials = BaseTemplate.bind();
+Initials.args = {
+	initials: 'KJ',
+	size: 'lg'
+}
+
+export const InitialsWithBadge = BaseTemplate.bind();
+InitialsWithBadge.args = {
+	badge: true,
+	initials: 'KJ',
+	size: 'lg'
+}
+
+export const Status = BaseTemplate.bind();
+Status.args = {
+	initials: 'KJ',
+	size: 'lg',
+	status: 'online'
+}
+
+export const AllStatuses = () => html`<div style="display: flex; gap: 16px; align-items: center;">
+	<pds-avatar initials="KJ" size="lg" status="online"></pds-avatar>
+	<pds-avatar initials="KJ" size="lg" status="away"></pds-avatar>
+	<pds-avatar initials="KJ" size="lg" status="offline"></pds-avatar>
+</div>`;
+
+export const StatusRing = () => html`<div style="display: flex; gap: 16px; align-items: center;">
+	<pds-avatar initials="KJ" size="lg" status="online" status-ring="true"></pds-avatar>
+	<pds-avatar initials="KJ" size="lg" status="away" status-ring="true"></pds-avatar>
+	<pds-avatar initials="KJ" size="lg" status="offline" status-ring="true"></pds-avatar>
+</div>`;