@grantcodes/ui 2.15.7 → 2.16.0

package/src/components/avatar/avatar.component.js

@@ -1,78 +1,89 @@
-import { LitElement } from "lit";
-import { html } from "lit/static-html.js";
-import avatarStyles from "./avatar.css" with { type: "css" };
+import { LitElement } from 'lit';
+import { html } from 'lit/static-html.js';
+import avatarStyles from './avatar.css' with { type: 'css' };
+
+// Mirrors the 3rem square in avatar.css (--g-spacing-2xl); the image fills that box.
+const AVATAR_SIZE = 48;
 
 export class GrantCodesAvatar extends LitElement {
-	static properties = {
-		src: { type: String },
-		name: { type: String },
-		alt: { type: String },
-		initials: { type: String },
-		size: { type: String },
-	};
+  static properties = {
+    src: { type: String },
+    name: { type: String },
+    alt: { type: String },
+    initials: { type: String },
+    size: { type: String },
+  };
 
-	static styles = [avatarStyles];
+  static styles = [avatarStyles];
 
-	constructor() {
-		super();
+  constructor() {
+    super();
 
-		/**
-		 * Image source for the avatar
-		 */
-		this.src = "";
-		/**
-		 * The full name of the person
-		 */
-		this.name = "";
-		/**
-		 * Alt attribute text
-		 */
-		this.alt = "";
-		/**
-		 * Optional initials, used when there is no src set
-		 */
-		this.initials = "";
-		/**
-		 * Size variant: 'small', 'medium', or 'large'
-		 */
-		this.size = "medium";
-	}
+    /**
+     * Image source for the avatar
+     */
+    this.src = '';
+    /**
+     * The full name of the person
+     */
+    this.name = '';
+    /**
+     * Alt attribute text
+     */
+    this.alt = '';
+    /**
+     * Optional initials, used when there is no src set
+     */
+    this.initials = '';
+    /**
+     * Size variant: 'small', 'medium', or 'large'
+     */
+    this.size = 'medium';
+  }
 
-	/**
-	 * Helper function to get initials from the name (if not already provided)
-	 *
-	 * @return {String}  First 2 initials of the passed name
-	 */
-	getInitials() {
-		if (this.initials) return this.initials;
-		if (this.name) {
-			const [first = "", second = ""] = this.name.trim().split(" ");
-			const firstInitial = first ? first[0] : "";
-			const secondInitial = second ? second[0] : "";
-			return `${firstInitial}${secondInitial}`;
-		}
-		return "";
-	}
+  /**
+   * Helper function to get initials from the name (if not already provided)
+   *
+   * @return {String}  First 2 initials of the passed name
+   */
+  getInitials() {
+    if (this.initials) return this.initials;
+    if (this.name) {
+      const [first = '', second = ''] = this.name.trim().split(' ');
+      const firstInitial = first ? first[0] : '';
+      const secondInitial = second ? second[0] : '';
+      return `${firstInitial}${secondInitial}`;
+    }
+    return '';
+  }
 
-	getAlt() {
-		if (this.alt) return this.alt;
-		return `${this.name || this.initials} avatar`;
-	}
+  getAlt() {
+    if (this.alt) return this.alt;
+    return this.name || this.initials || '';
+  }
 
-	/** @returns {import('lit').TemplateResult} */
-	getImg() {
-		if (this.src) {
-			return html`<img src=${this.src} alt=${this.getAlt()} />`;
-		}
-		return html``;
-	}
+  /** @returns {import('lit').TemplateResult} */
+  getImg() {
+    if (this.src) {
+      return html`<img
+        src=${this.src}
+        alt=${this.getAlt()}
+        class="avatar__image"
+        width=${AVATAR_SIZE}
+        height=${AVATAR_SIZE}
+        loading="lazy"
+        decoding="async"
+      />`;
+    }
+    return html``;
+  }
 
-	/** @returns {import('lit').TemplateResult} */
-	render() {
-		const content = this.src
-			? this.getImg()
-			: html`<span class="avatar__initials">${this.getInitials()}</span>`;
-		const sizeClass = this.size ? `avatar--${this.size}` : "";
-		return html` <div class="avatar ${sizeClass}">${content}</div> `;
-	}
+  /** @returns {import('lit').TemplateResult} */
+  render() {
+    const content = this.src
+      ? this.getImg()
+      : html`<span class="avatar__initials">${this.getInitials()}</span>`;
+    const sizeClass = this.size ? `avatar--${this.size}` : '';
+    return html` <div class="avatar ${sizeClass}">${content}</div> `;
+  }
 }

package/src/components/avatar/avatar.css

@@ -2,34 +2,34 @@
 *,
 *::before,
 *::after {
-	box-sizing: border-box;
+  box-sizing: border-box;
 }
 
 :host {
-	display: block;
+  display: block;
 }
 
 .avatar {
-	display: flex;
-	align-items: center;
-	justify-content: center;
-	inline-size: var(--g-spacing-2xl);
-	block-size: var(--g-spacing-2xl);
-	border-radius: 50%;
-	overflow: hidden;
-	background-color: var(--g-color-primary-200);
-	color: var(--g-color-primary-900);
-	text-align: center;
-	font: var(--g-typography-h6-font)
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  inline-size: var(--g-spacing-2xl);
+  block-size: var(--g-spacing-2xl);
+  border-radius: 50%;
+  overflow: hidden;
+  background-color: var(--g-color-primary-200);
+  color: var(--g-color-primary-900);
+  text-align: center;
+  font: var(--g-typography-h6-font);
 }
 
 .avatar__image {
-	inline-size: 100%;
-	block-size: 100%;
-	object-fit: cover;
-	object-position: center;
+  inline-size: 100%;
+  block-size: 100%;
+  object-fit: cover;
+  object-position: center;
 }
 
 .avatar__fallback {
-	line-height: 1;
+  line-height: 1;
 }

package/src/components/avatar/avatar.js

@@ -1,6 +1,6 @@
-import { GrantCodesAvatar } from "./avatar.component.js";
+import { GrantCodesAvatar } from './avatar.component.js';
 
-export * from "./avatar.component.js";
+export * from './avatar.component.js';
 export default GrantCodesAvatar;
 
-customElements.define("grantcodes-avatar", GrantCodesAvatar);
+customElements.define('grantcodes-avatar', GrantCodesAvatar);

package/src/components/avatar/avatar.react.js

@@ -1,9 +1,9 @@
-import React from "react";
-import { createComponent } from "@lit/react";
-import { GrantCodesAvatar } from "./avatar.js";
+import { createComponent } from '@lit/react';
+import React from 'react';
+import { GrantCodesAvatar } from './avatar.js';
 
 export const Avatar = createComponent({
-	tagName: "grantcodes-avatar",
-	elementClass: GrantCodesAvatar,
-	react: React,
+  tagName: 'grantcodes-avatar',
+  elementClass: GrantCodesAvatar,
+  react: React,
 });

package/src/components/avatar/avatar.stories.js

@@ -1,25 +1,26 @@
-import { getStorybookHelpers } from "@wc-toolkit/storybook-helpers";
-const { events, args, argTypes, template } =
-	getStorybookHelpers("grantcodes-avatar");
-import "./avatar.js";
+import { getStorybookHelpers } from '@wc-toolkit/storybook-helpers';
+
+const { events, args, argTypes, template } = getStorybookHelpers('grantcodes-avatar');
+
+import './avatar.js';
 
 const meta = {
-	title: "Components/Avatar",
-	component: "grantcodes-avatar",
-	args: {
-		...args,
-		src: "https://placehold.co/160x160",
-		name: "Tommy Tobasco",
-		alt: "Tommy Tomasco Avatar",
-		initials: "2T",
-	},
-	argTypes,
-	render: (args) => template(args),
-	parameters: {
-		actions: {
-			handles: events,
-		},
-	},
+  title: 'Components/Avatar',
+  component: 'grantcodes-avatar',
+  args: {
+    ...args,
+    src: 'https://placehold.co/160x160',
+    name: 'Tommy Tobasco',
+    alt: 'Tommy Tomasco Avatar',
+    initials: '2T',
+  },
+  argTypes,
+  render: (args) => template(args),
+  parameters: {
+    actions: {
+      handles: events,
+    },
+  },
 };
 
 export default meta;
@@ -27,7 +28,7 @@ export default meta;
 export const Avatar = {};
 
 export const Initials = {
-	args: {
-		src: undefined,
-	},
+  args: {
+    src: undefined,
+  },
 };

package/src/components/avatar/avatar.test.js

@@ -1,85 +1,129 @@
-import { describe, it, afterEach } from "node:test";
-import { strict as assert } from "node:assert";
-import { fixture, cleanup } from "../../test-utils/index.js";
-import "./avatar.js";
-
-describe("Avatar Component", () => {
-	let element;
-
-	afterEach(() => {
-		cleanup(element);
-	});
-
-	it("should render with default properties", async () => {
-		element = await fixture("grantcodes-avatar");
-		assert.ok(element, "Element should be created");
-		assert.ok(element.shadowRoot, "Element should have shadow root");
-	});
-
-	it("should display initials when name is provided", async () => {
-		element = await fixture("grantcodes-avatar", {
-			name: "John Doe",
-		});
-
-		const initialsElement =
-			element.shadowRoot.querySelector(".avatar__initials");
-		assert.ok(initialsElement, "Initials element should exist");
-		assert.strictEqual(
-			initialsElement.textContent,
-			"JD",
-			"Should display correct initials",
-		);
-	});
-
-	it("should handle single name", async () => {
-		element = await fixture("grantcodes-avatar", {
-			name: "John",
-		});
-
-		const initialsElement =
-			element.shadowRoot.querySelector(".avatar__initials");
-		assert.strictEqual(
-			initialsElement.textContent,
-			"J",
-			"Should display single initial",
-		);
-	});
-
-	it("should display image when src is provided", async () => {
-		element = await fixture("grantcodes-avatar", {
-			src: "https://example.com/avatar.jpg",
-			alt: "User avatar",
-		});
-
-		const imgElement = element.shadowRoot.querySelector("img");
-		assert.ok(imgElement, "Image element should exist");
-		assert.strictEqual(imgElement.src, "https://example.com/avatar.jpg");
-		assert.strictEqual(imgElement.alt, "User avatar");
-	});
-
-	it("should apply size variant", async () => {
-		element = await fixture("grantcodes-avatar", {
-			size: "large",
-		});
-
-		const avatarElement = element.shadowRoot.querySelector(".avatar");
-		assert.ok(
-			avatarElement.classList.contains("avatar--large"),
-			"Should have large size class",
-		);
-	});
-
-	it("should support different sizes", async () => {
-		const sizes = ["small", "medium", "large"];
-
-		for (const size of sizes) {
-			element = await fixture("grantcodes-avatar", { size });
-			const avatarElement = element.shadowRoot.querySelector(".avatar");
-			assert.ok(
-				avatarElement.classList.contains(`avatar--${size}`),
-				`Should have ${size} size class`,
-			);
-			cleanup(element);
-		}
-	});
+import { strict as assert } from 'node:assert';
+import { afterEach, describe, it } from 'node:test';
+import { cleanup, fixture } from '../../test-utils/index.js';
+import './avatar.js';
+
+describe('Avatar Component', () => {
+  let element;
+
+  afterEach(() => {
+    cleanup(element);
+  });
+
+  it('should render with default properties', async () => {
+    element = await fixture('grantcodes-avatar');
+    assert.ok(element, 'Element should be created');
+    assert.ok(element.shadowRoot, 'Element should have shadow root');
+  });
+
+  it('should display initials when name is provided', async () => {
+    element = await fixture('grantcodes-avatar', {
+      name: 'John Doe',
+    });
+
+    const initialsElement = element.shadowRoot.querySelector('.avatar__initials');
+    assert.ok(initialsElement, 'Initials element should exist');
+    assert.strictEqual(initialsElement.textContent, 'JD', 'Should display correct initials');
+  });
+
+  it('should handle single name', async () => {
+    element = await fixture('grantcodes-avatar', {
+      name: 'John',
+    });
+
+    const initialsElement = element.shadowRoot.querySelector('.avatar__initials');
+    assert.strictEqual(initialsElement.textContent, 'J', 'Should display single initial');
+  });
+
+  it('should display image when src is provided', async () => {
+    element = await fixture('grantcodes-avatar', {
+      src: 'https://example.com/avatar.jpg',
+      alt: 'User avatar',
+    });
+
+    const imgElement = element.shadowRoot.querySelector('img');
+    assert.ok(imgElement, 'Image element should exist');
+    assert.strictEqual(imgElement.src, 'https://example.com/avatar.jpg');
+    assert.strictEqual(imgElement.alt, 'User avatar');
+  });
+
+  it('should apply size variant', async () => {
+    element = await fixture('grantcodes-avatar', {
+      size: 'large',
+    });
+
+    const avatarElement = element.shadowRoot.querySelector('.avatar');
+    assert.ok(avatarElement.classList.contains('avatar--large'), 'Should have large size class');
+  });
+
+  it('should support different sizes', async () => {
+    const sizes = ['small', 'medium', 'large'];
+
+    for (const size of sizes) {
+      element = await fixture('grantcodes-avatar', { size });
+      const avatarElement = element.shadowRoot.querySelector('.avatar');
+      assert.ok(
+        avatarElement.classList.contains(`avatar--${size}`),
+        `Should have ${size} size class`,
+      );
+      cleanup(element);
+    }
+  });
+
+  it('should fill the avatar box with the image', async () => {
+    element = await fixture('grantcodes-avatar', {
+      src: 'https://example.com/avatar.jpg',
+    });
+
+    const img = element.shadowRoot.querySelector('img');
+    assert.ok(
+      img.classList.contains('avatar__image'),
+      'Image must carry the class that sizes it to 100% of the avatar box',
+    );
+  });
+
+  it('should defer the avatar image and reserve its square box', async () => {
+    element = await fixture('grantcodes-avatar', {
+      src: 'https://example.com/avatar.jpg',
+      name: 'John Doe',
+    });
+
+    const img = element.shadowRoot.querySelector('img');
+    assert.strictEqual(img.getAttribute('loading'), 'lazy', 'Avatars are off the critical path');
+    assert.strictEqual(img.getAttribute('decoding'), 'async');
+    assert.ok(Number(img.getAttribute('width')) > 0, 'Width should be set to avoid CLS');
+    assert.strictEqual(
+      img.getAttribute('width'),
+      img.getAttribute('height'),
+      'Avatar images are square',
+    );
+  });
+
+  it('should not invent alt text when nothing is known about the avatar', async () => {
+    element = await fixture('grantcodes-avatar', { src: 'https://example.com/avatar.jpg' });
+
+    const img = element.shadowRoot.querySelector('img');
+    assert.strictEqual(img.getAttribute('alt'), '', 'An unknown avatar is decorative');
+  });
+
+  it('should use the name as alt text without an " avatar" suffix', async () => {
+    element = await fixture('grantcodes-avatar', {
+      src: 'https://example.com/avatar.jpg',
+      name: 'John Doe',
+    });
+
+    const img = element.shadowRoot.querySelector('img');
+    assert.strictEqual(img.getAttribute('alt'), 'John Doe');
+  });
+
+  it('should prefer an explicit alt over the name', async () => {
+    element = await fixture('grantcodes-avatar', {
+      src: 'https://example.com/avatar.jpg',
+      name: 'John Doe',
+      alt: 'Custom alt',
+    });
+
+    const img = element.shadowRoot.querySelector('img');
+    assert.strictEqual(img.getAttribute('alt'), 'Custom alt');
+  });
 });

package/src/components/avatar/index.js

@@ -1 +1 @@
-export * from "./avatar.js";
+export * from './avatar.js';

package/src/components/badge/badge.component.js

@@ -1,37 +1,37 @@
-import { LitElement } from "lit";
-import { html } from "lit/static-html.js";
-import { classMap } from "lit/directives/class-map.js";
-import badgeStyles from "./badge.css" with { type: "css" };
+import { LitElement } from 'lit';
+import { classMap } from 'lit/directives/class-map.js';
+import { html } from 'lit/static-html.js';
+import badgeStyles from './badge.css' with { type: 'css' };
 
 export class GrantCodesBadge extends LitElement {
-	static styles = [badgeStyles];
+  static styles = [badgeStyles];
 
-	static properties = {
-		variant: { type: String },
-	};
+  static properties = {
+    variant: { type: String },
+  };
 
-	constructor() {
-		super();
+  constructor() {
+    super();
 
-		/**
-		 * Visual variant of the badge
-		 * @type {'primary' | 'success' | 'warning' | 'error' | 'info' | 'neutral'}
-		 */
-		this.variant = "neutral";
-	}
+    /**
+     * Visual variant of the badge
+     * @type {'primary' | 'success' | 'warning' | 'error' | 'info' | 'neutral'}
+     */
+    this.variant = 'neutral';
+  }
 
-	render() {
-		const classes = classMap({
-			badge: true,
-			[`badge--${this.variant}`]: Boolean(this.variant),
-		});
+  render() {
+    const classes = classMap({
+      badge: true,
+      [`badge--${this.variant}`]: Boolean(this.variant),
+    });
 
-		return html`
+    return html`
 			<span class=${classes}>
 				<span class="badge__content">
 					<slot></slot>
 				</span>
 			</span>
 		`;
-	}
+  }
 }