Added the avatar component (#64)

# Pull Request

## 📖 Description

<!--- Provide some background and a description of your work. -->
This change adds the avatar foundation component.

### 🎫 Issues

<!---
List and link relevant issues here using the keyword "closes"
if this PR will close an issue, eg. closes #411
-->
Continues work on #31

## ✅ Checklist

### General

<!--- Review the list and put an x in the boxes that apply. -->

- [x] I have added tests for my changes.
- [x] I have tested my changes.
- [x] I have updated the project documentation to reflect my changes.

## ⏭ Next Steps

<!---
If there is relevant follow-up work to this PR, please list any existing issues or provide brief descriptions of what you would like to do next.
-->
- Continue work on #31

change/@microsoft-fast-cli-36712620-a12e-4198-91f7-2951eeb7e33e.json

@@ -0,0 +1,7 @@
+{
+  "type": "none",
+  "comment": "Added the avatar component",
+  "packageName": "@microsoft/fast-cli",
+  "email": "7559015+janechu@users.noreply.github.com",
+  "dependentChangeType": "none"
+}

packages/fast-cli/src/components/avatar/README.md

@@ -0,0 +1,3 @@
+# Description
+
+This template is used as a avatar component template from which a user can modify without having to do the initial scaffolding.

packages/fast-cli/src/components/avatar/template.pw.spec.ts

@@ -0,0 +1,33 @@
+import { expect, test } from "@playwright/test";
+import { execSync } from "child_process";
+import {
+    expectedGeneratedComponentTemplateFiles,
+    setupComponent,
+    teardown,
+    getGeneratedComponentFiles,
+    getTempDir,
+    getTempComponentDir,
+} from "../../test/helpers.js";
+
+const uuid: string = "avatar";
+const tempDir: string = getTempDir(uuid);
+const tempComponentDir: string = getTempComponentDir(uuid);
+
+test.describe(`CLI add-foundation-component ${uuid}`, () => {
+    test.beforeAll(() => {
+        setupComponent(uuid, tempDir, tempComponentDir);
+    });
+    test.afterAll(() => {
+        teardown(tempDir, tempComponentDir);
+    });
+    test("should copy files from the template", () => {
+        expect(getGeneratedComponentFiles(tempDir)).toEqual(expectedGeneratedComponentTemplateFiles);
+    });
+    test("should be able to run the build", () => {
+        expect(
+            () => {
+                execSync(`cd ${tempDir} && npm run build`);
+            }
+        ).not.toThrow();
+    });
+});

packages/fast-cli/src/components/avatar/template/README.ts

@@ -0,0 +1,8 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string => `
+# ${config.className}
+
+The avatar component is used to visually represent a user or an object.
+
+For more information on the building blocks used to create this component, please refer to https://www.fast.design/docs/components/avatar`;

packages/fast-cli/src/components/avatar/template/component.definition.ts

@@ -0,0 +1,32 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string => 
+`import { template } from "./${config.tagName}.template.js";
+import { styles } from "./${config.tagName}.styles.js";
+import type { ${config.className} } from "./${config.tagName}.js";
+import { html, when } from "@microsoft/fast-element";
+import { Avatar } from "@microsoft/fast-foundation";
+
+export const definition = {
+    baseName: "${config.tagName}",
+    baseClass: Avatar,
+    template,
+    styles,
+    media: html<${config.className}>\`
+        \${when(
+            x => x.imgSrc,
+            html\`
+                <img
+                    src="\${x => x.imgSrc}"
+                    alt="\${x => x.alt}"
+                    slot="media"
+                    class="media"
+                    part="media"
+                />
+            \`
+        )}
+    \`,
+    shadowOptions: {
+        delegatesFocus: true,
+    },
+};`;

packages/fast-cli/src/components/avatar/template/component.pw.spec.ts

@@ -0,0 +1,25 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string => `
+import { expect, test } from "@playwright/test";
+import { fixtureURL } from "@microsoft/fast-cli/dist/esm/utilities/playwright.js";
+
+test.describe("${config.tagName}", () => {
+    const fixture = fixtureURL("${config.tagName}");
+
+    test.beforeEach(async ({ page }) => {
+        await page.goto(fixture);
+    });
+
+    test("should load the fixture URL", async ({ page }) => {
+        const pageUrl = page.url();
+
+        expect(pageUrl).toBe(\`http://localhost:3000/\${fixture}\`);
+    });
+    test("should contain the component in the URL", async ({ page }) => {
+        const element = page.locator("${config.tagName}");
+
+        await expect(element).not.toBeNull();
+    });
+});
+`

packages/fast-cli/src/components/avatar/template/component.stories.ts

@@ -0,0 +1,12 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string => `
+import Template from "./fixtures/base.html";
+import "./define.js";
+
+export default {
+    title: "${config.tagName}",
+};
+
+export const ${config.className}: () => "*.html" = () => Template;
+`;

packages/fast-cli/src/components/avatar/template/component.styles.ts

@@ -0,0 +1,102 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string =>
+`import { css, ElementStyles } from "@microsoft/fast-element";
+import {
+    AvatarOptions,
+    Badge,
+    display,
+    FoundationElementTemplate,
+} from "@microsoft/fast-foundation";
+import {
+    baseHeightMultiplier,
+    controlCornerRadius,
+    DirectionalStyleSheetBehavior,
+    density,
+    designUnit,
+    neutralForegroundRest,
+    typeRampBaseFontSize,
+} from "@microsoft/adaptive-ui";
+
+const rtl = (context, definition) => css\`
+    ::slotted(\${context.tagFor(Badge)}) {
+        left: 0;
+    }
+\`;
+
+const ltr = (context, definition) => css\`
+    ::slotted(\${context.tagFor(Badge)}) {
+        right: 0;
+    }
+\`;
+
+/**
+ * Styles for ${config.className}
+ * @public
+ */
+export const styles: FoundationElementTemplate<ElementStyles> = (
+    context,
+    definition
+) =>
+    css\`
+        \${display("flex")} :host {
+            position: relative;
+            height: var(--avatar-size, var(--avatar-size-default));
+            max-width: var(--avatar-size, var(--avatar-size-default));
+            --avatar-size-default: calc(
+                (
+                        (\${baseHeightMultiplier} + \${density}) * \${designUnit} +
+                            ((\${designUnit} * 8) - 40)
+                    ) * 1px
+            );
+            --avatar-text-size: \${typeRampBaseFontSize};
+            --avatar-text-ratio: \${designUnit};
+        }
+        .link {
+            text-decoration: none;
+            color: \${neutralForegroundRest};
+            display: flex;
+            flex-direction: row;
+            justify-content: center;
+            align-items: center;
+            min-width: 100%;
+        }
+        .square {
+            border-radius: calc(\${controlCornerRadius} * 1px);
+            min-width: 100%;
+            overflow: hidden;
+        }
+        .circle {
+            border-radius: 100%;
+            min-width: 100%;
+            overflow: hidden;
+        }
+        .backplate {
+            position: relative;
+            display: flex;
+        }
+        .media,
+        ::slotted(img) {
+            max-width: 100%;
+            position: absolute;
+            display: block;
+        }
+        .content {
+            font-size: calc(
+                (var(--avatar-text-size) + var(--avatar-size, var(--avatar-size-default))) /
+                    var(--avatar-text-ratio)
+            );
+            line-height: var(--avatar-size, var(--avatar-size-default));
+            display: block;
+            min-height: var(--avatar-size, var(--avatar-size-default));
+        }
+        ::slotted(\${context.tagFor(Badge)}) {
+            position: absolute;
+            display: block;
+        }
+        \`.withBehaviors(
+            new DirectionalStyleSheetBehavior(
+                ltr(context, definition),
+                rtl(context, definition)
+            )
+        );`

packages/fast-cli/src/components/avatar/template/component.template.ts

@@ -0,0 +1,12 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string => `
+import { Avatar, avatarTemplate, FoundationElementTemplate } from "@microsoft/fast-foundation";
+import type { ViewTemplate } from "@microsoft/fast-element";
+
+/**
+ * The template for ${config.className} component.
+ * @public
+ */
+export const template: FoundationElementTemplate<ViewTemplate<Avatar>> = avatarTemplate;
+`;

packages/fast-cli/src/components/avatar/template/component.ts

@@ -0,0 +1,29 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string =>
+`import { attr } from "@microsoft/fast-element";
+import { Avatar } from "@microsoft/fast-foundation";
+
+/**
+ * A class derived from the Avatar foundation component
+ */
+export class ${config.className} extends Avatar {
+    /**
+     * Indicates the Avatar should have an image source
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: src
+     */
+    @attr({ attribute: "src" })
+    public imgSrc: string | undefined;
+
+    /**
+     * Indicates the Avatar should have alt text
+     *
+     * @public
+     * @remarks
+     * HTML Attribute: alt
+     */
+    @attr public alt: string | undefined;
+};`

packages/fast-cli/src/components/avatar/template/define.ts

@@ -0,0 +1,7 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string =>
+`import { ${config.className} } from "./${config.tagName}.js";
+import { definition } from "./${config.tagName}.definition.js";
+
+export const ${config.definitionName} = ${config.className}.compose(definition);`;

packages/fast-cli/src/components/avatar/template/fast.add-component.json

@@ -0,0 +1,8 @@
+{
+    "packageJson": {
+        "dependencies": {
+            "@microsoft/adaptive-ui": "../adaptive-ui",
+            "@microsoft/fast-foundation": "^2.46.2"
+        }
+    }
+}

packages/fast-cli/src/components/avatar/template/fixture.ts

@@ -0,0 +1,55 @@
+import type { ComponentTemplateConfig } from "../../../utilities/template";
+
+export default (config: ComponentTemplateConfig): string =>
+`<style>
+${config.tagName} {
+    --avatar-fill-accent-primary: #cf4073;
+    --avatar-fill-accent-secondary: #0078d4;
+    --avatar-color-foo: hsl(0, 0%, 100%);
+    --avatar-color-bar: grey;
+    --avatar-text-ratio: 3;
+}
+
+.container {
+    padding: 1em;
+}
+</style>
+<div class="container">
+    <h1>${config.className}</h1>
+
+    <h2>Circle shaped avatar</h2>
+
+    <h3>Circle avatar with image</h3>
+    <${config.tagName}
+        alt="Annie's profile image"
+        link="#"
+        shape="circle"
+        fill="accent-primary"
+        color="bar"
+    >
+        <img class="image" slot="media" src="https://via.placeholder.com/32" />
+    </${config.tagName}>
+
+    <h3>Circle avatar with text content</h3>
+    <${config.tagName}
+        alt="Carlos's profile image"
+        link="#"
+        shape="circle"
+        fill="accent-primary"
+        color="foo"
+    >
+        CR
+    </${config.tagName}>
+
+    <h2>Square shaped avatar</h2>
+
+    <h3>Square avatar with image</h3>
+    <${config.tagName}
+        src="https://via.placeholder.com/32"
+        alt="Fang's profile image"
+        link="#"
+        shape="square"
+        fill="accent-secondary"
+    ></${config.tagName}>
+
+</div>`;

packages/fast-cli/src/components/avatar/template/index.ts

@@ -0,0 +1,2 @@
+// Import added to include the json file in the transpiled template
+import "./fast.add-component.json";

packages/fast-cli/src/components/options.ts

@@ -1,4 +1,5 @@
 export const availableTemplates = [
+    "avatar",
     "badge",
     "blank",
     "card",