@justeattakeaway/pie-avatar 0.1.1 → 0.3.0

package/README.md

@@ -30,9 +30,12 @@ Ideally, you should install the component using the **`@justeattakeaway/pie-webc
 ## Documentation
 
 ### Properties
-| Prop             | Options                                                                                                                                                                  | Description                                                                                                                                                                                                         | Default        |
-|------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------|
-| | | | |
+
+| Prop | Options | Description | Default |
+|------|---------|-------------|---------|
+| `src` | — | The src attribute for the underlying image tag. | `""` |
+| `tag` | "button",  "a",  "div" | Which HTML element to use when rendering the avatar.| `div` |
+| `label` | - | User or company name that will be rendered as initials inside the avatar.| `""` |
 
 ### Slots
 | Slot     | Description                                                                                                                                                                                                                                                                         |

package/custom-elements.json

@@ -11,8 +11,42 @@
     {
       "kind": "javascript-module",
       "path": "src/defs.js",
-      "declarations": [],
-      "exports": []
+      "declarations": [
+        {
+          "kind": "variable",
+          "name": "tags",
+          "type": {
+            "text": "['a', 'button', 'div']"
+          },
+          "default": "['a', 'button', 'div']"
+        },
+        {
+          "kind": "variable",
+          "name": "defaultProps",
+          "type": {
+            "text": "DefaultProps"
+          },
+          "default": "{\n    tag: 'div',\n}"
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "tags",
+          "declaration": {
+            "name": "tags",
+            "module": "src/defs.js"
+          }
+        },
+        {
+          "kind": "js",
+          "name": "defaultProps",
+          "declaration": {
+            "name": "defaultProps",
+            "module": "src/defs.js"
+          }
+        }
+      ]
     },
     {
       "kind": "javascript-module",
@@ -22,7 +56,99 @@
           "kind": "class",
           "description": "",
           "name": "PieAvatar",
-          "members": [],
+          "members": [
+            {
+              "kind": "field",
+              "name": "tag",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "label",
+              "type": {
+                "text": "AvatarProps['label']"
+              },
+              "privacy": "public"
+            },
+            {
+              "kind": "method",
+              "name": "getInitials",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Initials | null"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "name",
+                  "type": {
+                    "text": "string"
+                  }
+                }
+              ],
+              "description": "Attempts to extract initials from the label string.\nIf the label is not provided or is invalid, it returns null."
+            },
+            {
+              "kind": "method",
+              "name": "renderInitials",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "initials",
+                  "type": {
+                    "text": "Initials"
+                  }
+                }
+              ],
+              "description": "Renders the initials both for visual display and for screen readers."
+            },
+            {
+              "kind": "method",
+              "name": "renderIcon",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "description": "Renders the icon (placeholder span for now)."
+            },
+            {
+              "kind": "field",
+              "name": "avatarContent",
+              "type": {
+                "text": "TemplateResult"
+              },
+              "privacy": "private",
+              "description": "Renders the inner content of the avatar such as initials, an icon or an image.\nIt is a getter because the value is computed based on properties",
+              "readonly": true
+            },
+            {
+              "kind": "method",
+              "name": "renderAvatarWrapper",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "TemplateResult"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "content",
+                  "type": {
+                    "text": "TemplateResult"
+                  }
+                }
+              ],
+              "description": "Renders the avatar wrapper element based on the `tag` property.\nCan be a `button`, `a` or a `div`."
+            }
+          ],
           "mixins": [
             {
               "name": "RtlMixin",

package/dist/index.d.ts

@@ -1,20 +1,75 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import { CSSResult } from 'lit';
 import { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
 import { RTLInterface } from '@justeattakeaway/pie-webc-core';
-import { TemplateResult } from 'lit-html';
+import { TemplateResult } from 'lit';
 
 export declare interface AvatarProps {
+    /**
+     * Label for the username that will be turned into initials inside the avatar, if provided.
+     */
+    label?: string;
+    /**
+     * What HTML element the avatar should be such as button, a  or div.
+     */
+    tag: typeof tags[number];
 }
 
+export declare type DefaultProps = ComponentDefaultProps<AvatarProps, keyof Omit<AvatarProps, 'label'>>;
+
+export declare const defaultProps: DefaultProps;
+
+export declare type Initials = {
+    visual: string;
+    screenreader: string;
+};
+
 /**
  * @tagname pie-avatar
  */
 export declare class PieAvatar extends PieAvatar_base implements AvatarProps {
-    render(): TemplateResult<1>;
+    tag: "a" | "button" | "div";
+    label: AvatarProps['label'];
+    /**
+     * Attempts to extract initials from the label string.
+     * If the label is not provided or is invalid, it returns null.
+     *
+     * @private
+     */
+    private getInitials;
+    /**
+     * Renders the initials both for visual display and for screen readers.
+     *
+     * @private
+     */
+    private renderInitials;
+    /**
+     * Renders the icon (placeholder span for now).
+     *
+     * @private
+     */
+    private renderIcon;
+    /**
+     * Renders the inner content of the avatar such as initials, an icon or an image.
+     * It is a getter because the value is computed based on properties
+     *
+     * @private
+     */
+    private get avatarContent();
+    /**
+     * Renders the avatar wrapper element based on the `tag` property.
+     * Can be a `button`, `a` or a `div`.
+     *
+     * @private
+     */
+    private renderAvatarWrapper;
+    render(): TemplateResult;
     static styles: CSSResult;
 }
 
 declare const PieAvatar_base: GenericConstructor<RTLInterface> & typeof PieElement;
 
+export declare const tags: readonly ["a", "button", "div"];
+
 export { }

package/dist/index.js

@@ -1,27 +1,107 @@
-import { LitElement as p, html as f, unsafeCSS as h } from "lit";
-import { RtlMixin as c, safeCustomElement as d } from "@justeattakeaway/pie-webc-core";
-const e = class e extends p {
+import { LitElement as h, html as n, unsafeCSS as f } from "lit";
+import { RtlMixin as g, validPropertyValues as b, safeCustomElement as y } from "@justeattakeaway/pie-webc-core";
+import "@justeattakeaway/pie-icons-webc/dist/IconUser.js";
+import { property as u } from "lit/decorators.js";
+const o = class o extends h {
   willUpdate() {
-    this.getAttribute("v") || this.setAttribute("v", e.v);
+    this.getAttribute("v") || this.setAttribute("v", o.v);
   }
 };
-e.v = "0.1.1";
-let s = e;
-const u = "*,*:after,*:before{box-sizing:inherit}:host{display:block}";
-var b = Object.getOwnPropertyDescriptor, m = (i, l, v, o) => {
-  for (var t = o > 1 ? void 0 : o ? b(l, v) : l, r = i.length - 1, n; r >= 0; r--)
-    (n = i[r]) && (t = n(t) || t);
-  return t;
+o.v = "0.3.0";
+let d = o;
+const m = "*,*:after,*:before{box-sizing:inherit}:host{display:block}.c-avatar-visuallyHidden{position:absolute;display:block;height:1px;width:1px;overflow:hidden;padding:1px;white-space:nowrap}.c-avatar-content{display:flex;justify-content:center;align-items:center;font-size:calc(var(--dt-font-body-s-size) * 1px);background-color:var(--dt-color-container-inverse);color:var(--dt-color-content-interactive-primary);width:32px;height:32px;border-radius:var(--dt-radius-rounded-e)}", x = ["a", "button", "div"], v = {
+  tag: "div"
 };
-let a = class extends c(s) {
+var w = Object.defineProperty, S = Object.getOwnPropertyDescriptor, c = (t, e, r, i) => {
+  for (var a = i > 1 ? void 0 : i ? S(e, r) : e, l = t.length - 1, p; l >= 0; l--)
+    (p = t[l]) && (a = (i ? p(e, r, a) : p(a)) || a);
+  return i && a && w(e, r, a), a;
+};
+const C = "pie-avatar";
+let s = class extends g(d) {
+  constructor() {
+    super(...arguments), this.tag = v.tag;
+  }
+  /**
+   * Attempts to extract initials from the label string.
+   * If the label is not provided or is invalid, it returns null.
+   *
+   * @private
+   */
+  getInitials(t) {
+    try {
+      if (!t || typeof t != "string" || t.trim().length === 0)
+        return null;
+      const r = t.trim().replace(/-/g, " ").split(/\s+/).slice(0, 2).map((i) => i[0].toUpperCase());
+      return r.length === 0 ? null : {
+        visual: r.join(""),
+        screenreader: r.join(", ")
+        // joins the two words by comma so initials are correctly pronounced by screenreaders
+      };
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Renders the initials both for visual display and for screen readers.
+   *
+   * @private
+   */
+  renderInitials(t) {
+    return n`
+            <span aria-hidden="true" data-test-id="pie-avatar-initials-visual">${t.visual}</span>
+            <span class="c-avatar-visuallyHidden" data-test-id="pie-avatar-initials-screenreader">${t.screenreader}</span>
+        `;
+  }
+  /**
+   * Renders the icon (placeholder span for now).
+   *
+   * @private
+   */
+  renderIcon() {
+    return n`<icon-user size="s" aria-hidden="true" data-test-id="pie-avatar-icon"></icon-user>`;
+  }
+  /**
+   * Renders the inner content of the avatar such as initials, an icon or an image.
+   * It is a getter because the value is computed based on properties
+   *
+   * @private
+   */
+  get avatarContent() {
+    if (this.label) {
+      const t = this.getInitials(this.label);
+      if (t)
+        return this.renderInitials(t);
+    }
+    return this.renderIcon();
+  }
+  /**
+   * Renders the avatar wrapper element based on the `tag` property.
+   * Can be a `button`, `a` or a `div`.
+   *
+   * @private
+   */
+  renderAvatarWrapper(t) {
+    const { tag: e } = this;
+    return e === "button" ? n`<button data-test-id="pie-avatar-button">${t}</button>` : e === "a" ? n`<a data-test-id="pie-avatar-anchor">${t}</a>` : n`<div class="c-avatar-content" data-test-id="pie-avatar-div">${t}</div>`;
+  }
   render() {
-    return f`<h1 data-test-id="pie-avatar">Hello world!</h1>`;
+    return this.renderAvatarWrapper(this.avatarContent);
   }
 };
-a.styles = h(u);
-a = m([
-  d("pie-avatar")
-], a);
+s.styles = f(m);
+c([
+  u({ type: String }),
+  b(C, x, v.tag)
+], s.prototype, "tag", 2);
+c([
+  u({ type: String })
+], s.prototype, "label", 2);
+s = c([
+  y("pie-avatar")
+], s);
 export {
-  a as PieAvatar
+  s as PieAvatar,
+  v as defaultProps,
+  x as tags
 };

package/dist/react.d.ts

@@ -1,20 +1,73 @@
+import { ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
 import { CSSResult } from 'lit';
 import { GenericConstructor } from '@justeattakeaway/pie-webc-core';
 import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
 import * as React_2 from 'react';
 import { RTLInterface } from '@justeattakeaway/pie-webc-core';
-import { TemplateResult } from 'lit-html';
+import { TemplateResult } from 'lit';
 
 export declare interface AvatarProps {
+    /**
+     * Label for the username that will be turned into initials inside the avatar, if provided.
+     */
+    label?: string;
+    /**
+     * What HTML element the avatar should be such as button, a  or div.
+     */
+    tag: typeof tags[number];
 }
 
+export declare type DefaultProps = ComponentDefaultProps<AvatarProps, keyof Omit<AvatarProps, 'label'>>;
+
+export declare const defaultProps: DefaultProps;
+
+export declare type Initials = {
+    visual: string;
+    screenreader: string;
+};
+
 export declare const PieAvatar: React_2.ForwardRefExoticComponent<React_2.PropsWithoutRef<AvatarProps> & React_2.RefAttributes<PieAvatar_2> & ReactBaseType>;
 
 /**
  * @tagname pie-avatar
  */
 declare class PieAvatar_2 extends PieAvatar_base implements AvatarProps {
-    render(): TemplateResult<1>;
+    tag: "a" | "button" | "div";
+    label: AvatarProps['label'];
+    /**
+     * Attempts to extract initials from the label string.
+     * If the label is not provided or is invalid, it returns null.
+     *
+     * @private
+     */
+    private getInitials;
+    /**
+     * Renders the initials both for visual display and for screen readers.
+     *
+     * @private
+     */
+    private renderInitials;
+    /**
+     * Renders the icon (placeholder span for now).
+     *
+     * @private
+     */
+    private renderIcon;
+    /**
+     * Renders the inner content of the avatar such as initials, an icon or an image.
+     * It is a getter because the value is computed based on properties
+     *
+     * @private
+     */
+    private get avatarContent();
+    /**
+     * Renders the avatar wrapper element based on the `tag` property.
+     * Can be a `button`, `a` or a `div`.
+     *
+     * @private
+     */
+    private renderAvatarWrapper;
+    render(): TemplateResult;
     static styles: CSSResult;
 }
 
@@ -22,4 +75,6 @@ declare const PieAvatar_base: GenericConstructor<RTLInterface> & typeof PieEleme
 
 declare type ReactBaseType = React_2.HTMLAttributes<HTMLElement>;
 
+export declare const tags: readonly ["a", "button", "div"];
+
 export { }

package/dist/react.js

@@ -1,13 +1,16 @@
 import * as a from "react";
-import { createComponent as e } from "@lit/react";
-import { PieAvatar as t } from "./index.js";
-const r = e({
+import { createComponent as t } from "@lit/react";
+import { PieAvatar as e } from "./index.js";
+import { defaultProps as v, tags as c } from "./index.js";
+const r = t({
   displayName: "PieAvatar",
-  elementClass: t,
+  elementClass: e,
   react: a,
   tagName: "pie-avatar",
   events: {}
-}), m = r;
+}), i = r;
 export {
-  m as PieAvatar
+  i as PieAvatar,
+  v as defaultProps,
+  c as tags
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@justeattakeaway/pie-avatar",
   "description": "PIE Design System Avatar built using Web Components",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "type": "module",
   "main": "dist/index.js",
   "module": "dist/index.js",
@@ -39,6 +39,7 @@
     "cem-plugin-module-file-extensions": "0.0.5"
   },
   "dependencies": {
+    "@justeattakeaway/pie-icons-webc": "1.14.2",
     "@justeattakeaway/pie-webc-core": "1.1.0"
   },
   "volta": {

package/src/avatar.scss

@@ -5,3 +5,20 @@
     // "block" or "inline-block", otherwise it can be ommited for floating elements
     display: block;
 }
+
+.c-avatar-visuallyHidden {
+    @include p.visually-hidden;
+}
+
+.c-avatar-content {
+    display: flex;
+    justify-content: center;
+    align-items: center;
+    @include p.font-size(--dt-font-body-s-size);
+    background-color: var(--dt-color-container-inverse);
+    color: var(--dt-color-content-interactive-primary); 
+    width: 32px;
+    height: 32px;
+    border-radius:var(--dt-radius-rounded-e);
+
+}

package/src/defs.ts

@@ -1,3 +1,25 @@
-// TODO - please remove the eslint disable comment below when you add props to this interface
-// eslint-disable-next-line @typescript-eslint/no-empty-interface
-export interface AvatarProps {}
+import { type ComponentDefaultProps } from '@justeattakeaway/pie-webc-core';
+
+export const tags = ['a', 'button', 'div'] as const;
+
+export interface AvatarProps {
+    /**
+     * Label for the username that will be turned into initials inside the avatar, if provided.
+     */
+    label?: string;
+    /**
+     * What HTML element the avatar should be such as button, a  or div.
+     */
+    tag: typeof tags[number];
+
+}
+
+export type DefaultProps = ComponentDefaultProps<AvatarProps, keyof Omit<AvatarProps, 'label'>>;
+export const defaultProps: DefaultProps = {
+    tag: 'div',
+};
+
+export type Initials = {
+    visual: string,
+    screenreader: string
+}

package/src/index.ts

@@ -1,9 +1,15 @@
-import { html, unsafeCSS } from 'lit';
+import {
+    html, type TemplateResult, unsafeCSS,
+} from 'lit';
 import { PieElement } from '@justeattakeaway/pie-webc-core/src/internals/PieElement';
-import { RtlMixin, safeCustomElement } from '@justeattakeaway/pie-webc-core';
+import { RtlMixin, safeCustomElement, validPropertyValues } from '@justeattakeaway/pie-webc-core';
+import '@justeattakeaway/pie-icons-webc/dist/IconUser.js';
 
+import { property } from 'lit/decorators.js';
 import styles from './avatar.scss?inline';
-import { type AvatarProps } from './defs';
+import {
+    type AvatarProps, defaultProps, tags, type Initials,
+} from './defs';
 
 // Valid values available to consumers
 export * from './defs';
@@ -13,10 +19,106 @@ const componentSelector = 'pie-avatar';
 /**
  * @tagname pie-avatar
  */
+
 @safeCustomElement('pie-avatar')
 export class PieAvatar extends RtlMixin(PieElement) implements AvatarProps {
+    @property({ type: String })
+    @validPropertyValues(componentSelector, tags, defaultProps.tag)
+    public tag = defaultProps.tag;
+
+    @property({ type: String })
+    public label: AvatarProps['label'];
+
+    /**
+     * Attempts to extract initials from the label string.
+     * If the label is not provided or is invalid, it returns null.
+     *
+     * @private
+     */
+    private getInitials (name: string): Initials | null {
+        try {
+            if (!name || typeof name !== 'string' || name.trim().length === 0) {
+                return null;
+            }
+
+            const nameSplit: string[] = name.trim().replace(/-/g, ' ').split(/\s+/); // [Ada, Lovelace]
+            const initials: string[] = nameSplit.slice(0, 2).map((word) => word[0].toUpperCase()); // [A, L]
+
+            if (initials.length === 0) {
+                return null;
+            }
+
+            return {
+                visual: initials.join(''),
+                screenreader: initials.join(', '), // joins the two words by comma so initials are correctly pronounced by screenreaders
+            };
+        } catch (error) {
+            return null;
+        }
+    }
+
+    /**
+     * Renders the initials both for visual display and for screen readers.
+     *
+     * @private
+     */
+    private renderInitials (initials: Initials): TemplateResult {
+        return html`
+            <span aria-hidden="true" data-test-id="pie-avatar-initials-visual">${initials.visual}</span>
+            <span class="c-avatar-visuallyHidden" data-test-id="pie-avatar-initials-screenreader">${initials.screenreader}</span>
+        `;
+    }
+
+    /**
+     * Renders the icon (placeholder span for now).
+     *
+     * @private
+     */
+    private renderIcon (): TemplateResult {
+        return html`<icon-user size="s" aria-hidden="true" data-test-id="pie-avatar-icon"></icon-user>`;
+    }
+
+    /**
+     * Renders the inner content of the avatar such as initials, an icon or an image.
+     * It is a getter because the value is computed based on properties
+     *
+     * @private
+     */
+    private get avatarContent (): TemplateResult {
+        // TODO: handle unauthenticated and src here
+
+        if (this.label) {
+            const initials = this.getInitials(this.label);
+            if (initials) {
+                return this.renderInitials(initials);
+            }
+        }
+
+        return this.renderIcon();
+    }
+
+    /**
+     * Renders the avatar wrapper element based on the `tag` property.
+     * Can be a `button`, `a` or a `div`.
+     *
+     * @private
+     */
+    private renderAvatarWrapper (content: TemplateResult): TemplateResult {
+        const { tag } = this;
+
+        if (tag === 'button') {
+            return html`<button data-test-id="pie-avatar-button">${content}</button>`;
+        }
+
+        if (tag === 'a') {
+            return html`<a data-test-id="pie-avatar-anchor">${content}</a>`;
+        }
+
+        return html`<div class="c-avatar-content" data-test-id="pie-avatar-div">${content}</div>`;
+    }
+
     render () {
-        return html`<h1 data-test-id="pie-avatar">Hello world!</h1>`;
+        return this.renderAvatarWrapper(this.avatarContent);
     }
 
     // Renders a `CSSResult` generated from SCSS by Vite