@c2n/avatar 0.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nguyen Thai Vinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,25 @@
+# @c2n/avatar
+
+Avatar built with Lit: image, initials or any slotted content, with an optional status dot or badge.
+
+```bash
+npm install @c2n/avatar
+```
+
+```html
+<script type="module">
+  import '@c2n/avatar'
+</script>
+
+<c2-avatar name="Ada Lovelace" initial-count="2"></c2-avatar>
+<c2-avatar name="Ada Lovelace" src="/ada.jpg" status="online"></c2-avatar>
+<c2-avatar name="Ada Lovelace" auto-color initial-count="2"></c2-avatar>
+```
+
+- **Content resolution**: the `src` image first (a failed load fires `error` and falls back to the initials), then slotted content (an icon, an emoji, an `<img>`), then the initials computed from `name`. `initial-count="2"` uses the first and last word of a longer name; `initials` overrides the computation.
+- **Colour**: `auto-color` derives a stable hue from the name, tunable with the `auto-color--saturation` and `--lightness` tokens.
+- **Status and badge**: `status="online|away|busy|offline"` draws a dot in the bottom-right corner; the `badge` slot replaces it with your own element (a count, an icon) and gets the same ring.
+- **Sizing**: one `--c2-avatar--size` token drives width, height and the font size (40% of the size by default); `--c2-avatar--width` and `--height` override it for non-square shapes.
+- **Accessibility**: the avatar is `role="img"` labelled by `alt` or `name`.
+
+Every visual aspect is a CSS custom property (`--c2-avatar--*`, `--c2-avatar__badge--*`, `--c2-avatar__image--*`). For stacked groups give each avatar `--c2-avatar--box-shadow: 0 0 0 2px <page background>` and a negative margin. The full list is in `custom-elements.json` and on the docs site.

package/dist/avatar.js

@@ -0,0 +1,106 @@
+import { LitElement, html, nothing, unsafeCSS } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+//#region src/avatar.scss?inline
+var avatar_default = "/* ex : var((width: 24px), width, c2-checkbox)  returns var(--c2-checkbox-width, 24px) */\n:host {\n  display: inline-flex;\n  position: relative;\n  vertical-align: middle;\n  flex: none;\n}\n\n.c2-avatar {\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  box-sizing: border-box;\n  overflow: hidden;\n  user-select: none;\n  line-height: 1;\n  width: var(--c2-avatar--width,var(--c2-avatar--size,32px));\n  height: var(--c2-avatar--height,var(--c2-avatar--size,32px));\n  font-size: var(--c2-avatar--font-size,calc(var(--c2-avatar--size, 32px) * 0.4));\n  font-weight: var(--c2-avatar--font-weight,600);\n  font-style: var(--c2-avatar--font-style);\n  font-family: var(--c2-avatar--font-family);\n  letter-spacing: var(--c2-avatar--letter-spacing,0.02em);\n  border-top-left-radius: var(--c2-avatar--border-top-left-radius,999px);\n  border-top-right-radius: var(--c2-avatar--border-top-right-radius,999px);\n  border-bottom-left-radius: var(--c2-avatar--border-bottom-left-radius,999px);\n  border-bottom-right-radius: var(--c2-avatar--border-bottom-right-radius,999px);\n  border-top: var(--c2-avatar--border-top);\n  border-bottom: var(--c2-avatar--border-bottom);\n  border-right: var(--c2-avatar--border-right);\n  border-left: var(--c2-avatar--border-left);\n  background: var(--c2-avatar--background,rgb(0, 122, 77));\n  color: var(--c2-avatar--color,#ffffff);\n  box-shadow: var(--c2-avatar--box-shadow);\n}\n.c2-avatar ::slotted(svg),\n.c2-avatar ::slotted(img) {\n  display: block;\n  width: 100%;\n  height: 100%;\n  object-fit: var(--c2-avatar__image--object-fit,cover);\n}\n.c2-avatar ::slotted(svg) {\n  width: 60%;\n  height: 60%;\n}\n\n:host([auto-color]) .c2-avatar {\n  background: hsl(var(--c2-avatar--hue, 160), var(--c2-avatar__auto-color--saturation,55%), var(--c2-avatar__auto-color--lightness,42%));\n}\n\n.c2-avatar-image {\n  display: block;\n  width: 100%;\n  height: 100%;\n  object-fit: var(--c2-avatar__image--object-fit,cover);\n}\n\n.c2-avatar-badge {\n  position: absolute;\n  right: calc(-1 * var(--c2-avatar__badge--offset,0px));\n  bottom: calc(-1 * var(--c2-avatar__badge--offset,0px));\n  display: flex;\n  z-index: 1;\n  line-height: 1;\n}\n.c2-avatar-badge::slotted(*) {\n  box-sizing: border-box;\n  border: var(--c2-avatar__badge--border,2px solid #ffffff);\n  border-radius: 999px;\n}\n\n.c2-avatar-status {\n  display: block;\n  box-sizing: content-box;\n  width: var(--c2-avatar__badge--size,10px);\n  height: var(--c2-avatar__badge--size,10px);\n  border: var(--c2-avatar__badge--border,2px solid #ffffff);\n  border-radius: 999px;\n  background: var(--c2-avatar__badge__offline--color,rgb(161, 161, 170));\n}\n\n:host([status=online]) .c2-avatar-status {\n  background: var(--c2-avatar__badge__online--color,rgb(34, 197, 94));\n}\n\n:host([status=away]) .c2-avatar-status {\n  background: var(--c2-avatar__badge__away--color,rgb(245, 158, 11));\n}\n\n:host([status=busy]) .c2-avatar-status {\n  background: var(--c2-avatar__badge__busy--color,rgb(239, 68, 68));\n}";
+//#endregion
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/avatar.ts
+var LEGACY_COUNT_ATTRIBUTE = "initialcount";
+var Avatar = class Avatar extends LitElement {
+	constructor(..._args) {
+		super(..._args);
+		this.name = "";
+		this.initialCount = 1;
+		this.initials = void 0;
+		this.src = void 0;
+		this.alt = void 0;
+		this.autoColor = false;
+		this.status = void 0;
+		this.imageFailed = false;
+	}
+	static {
+		this.styles = unsafeCSS(avatar_default);
+	}
+	/** Accepts the pre-1.0 camelCase `initialCount="2"` attribute as well. */
+	static get observedAttributes() {
+		return [...super.observedAttributes, LEGACY_COUNT_ATTRIBUTE];
+	}
+	attributeChangedCallback(name, old, value) {
+		if (name === LEGACY_COUNT_ATTRIBUTE) {
+			if (value !== null) this.initialCount = Number(value) || 1;
+			return;
+		}
+		super.attributeChangedCallback(name, old, value);
+	}
+	/** Initials shown when there is no image or slotted content. */
+	get initial() {
+		if (this.initials) return this.initials;
+		const words = this.name.trim().split(/\s+/).filter(Boolean);
+		if (words.length === 0) return "";
+		return (this.initialCount === 2 && words.length > 2 ? [words[0], words[words.length - 1]] : words.slice(0, Math.max(1, this.initialCount))).map((w) => w.charAt(0)).join("").toUpperCase();
+	}
+	/** Hue (0–359) derived from the name, used by `auto-color`. */
+	get hue() {
+		let hash = 2166136261;
+		for (const char of this.name) hash = Math.imul(hash ^ char.codePointAt(0), 16777619);
+		return (hash >>> 0) % 360;
+	}
+	willUpdate(changed) {
+		if (changed.has("src")) this.imageFailed = false;
+	}
+	handleImageError() {
+		this.imageFailed = true;
+		this.dispatchEvent(new Event("error"));
+	}
+	render() {
+		const showImage = !!this.src && !this.imageFailed;
+		const label = this.alt ?? this.name;
+		return html`
+      <div
+        class=${classMap({
+			"c2-avatar": true,
+			"has-image": showImage
+		})}
+        style=${this.autoColor ? `--c2-avatar--hue: ${this.hue}` : nothing}
+        role="img"
+        aria-label=${label || nothing}
+      >
+        ${showImage ? html`<img
+                class="c2-avatar-image"
+                src=${this.src}
+                alt=${ifDefined(this.alt ?? (this.name || void 0))}
+                loading="lazy"
+                @error=${this.handleImageError}
+              />` : html`<slot>${this.initial}</slot>`}
+      </div>
+      <slot name="badge" class="c2-avatar-badge"> ${this.status ? html`<span class="c2-avatar-status" aria-label=${this.status}></span>` : nothing} </slot>
+    `;
+	}
+};
+__decorate([property()], Avatar.prototype, "name", void 0);
+__decorate([property({
+	type: Number,
+	attribute: "initial-count"
+})], Avatar.prototype, "initialCount", void 0);
+__decorate([property()], Avatar.prototype, "initials", void 0);
+__decorate([property()], Avatar.prototype, "src", void 0);
+__decorate([property()], Avatar.prototype, "alt", void 0);
+__decorate([property({
+	type: Boolean,
+	reflect: true,
+	attribute: "auto-color"
+})], Avatar.prototype, "autoColor", void 0);
+__decorate([property({ reflect: true })], Avatar.prototype, "status", void 0);
+__decorate([state()], Avatar.prototype, "imageFailed", void 0);
+Avatar = __decorate([customElement("c2-avatar")], Avatar);
+//#endregion
+export { Avatar };

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@c2n/avatar",
+  "version": "0.0.6",
+  "type": "module",
+  "main": "dist/avatar.js",
+  "exports": {
+    ".": {
+      "default": "./dist/avatar.js",
+      "types": "./types/src/avatar.d.ts"
+    },
+    "./custom-elements.json": "./custom-elements.json"
+  },
+  "files": [
+    "dist",
+    "types"
+  ],
+  "keywords": [
+    "avatar",
+    "web component",
+    "lit"
+  ],
+  "author": "code2nguyen@gmail.com",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/code2nguyen/web-components.git"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "wireit",
+    "build:only": "vite build",
+    "type-check": "wireit"
+  },
+  "wireit": {
+    "type-check": {
+      "dependencies": [
+        "../../core:build"
+      ],
+      "command": "tsc -p tsconfig.lib.json --composite false"
+    },
+    "build": {
+      "dependencies": [
+        "type-check"
+      ],
+      "command": "vite build"
+    }
+  },
+  "dependencies": {
+    "@c2n/core": "0.0.6",
+    "lit": "3.3.3"
+  },
+  "devDependencies": {
+    "@c2n/config": "*"
+  },
+  "customElements": "custom-elements.json",
+  "gitHead": "2921054bc75299da66dad11c1e374246ff88a51e"
+}

package/types/src/avatar.d.ts

@@ -0,0 +1,85 @@
+import { LitElement, type PropertyValues } from 'lit';
+export type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
+/**
+ * Shows a person or entity as an image, initials or any slotted content, with an optional status dot or badge.
+ *
+ * Resolution order: the `src` image (falling back to initials if it fails to load), then slotted content, then the
+ * initials computed from `name`. Set `auto-color` to derive a stable background hue from the name.
+ *
+ * @tag c2-avatar
+ *
+ * @slot - Custom content shown instead of the initials (an icon, an emoji, an `<img>`).
+ * @slot badge - Small element pinned to the bottom-right corner (a count, an icon). Replaces the `status` dot.
+ *
+ * @event {Event} error - Fired when the `src` image fails to load; the initials are shown instead.
+ *
+ * @cssproperty {pixel} [--c2-avatar--size=32px]
+ * @cssproperty {pixel} --c2-avatar--width - Falls back to `--c2-avatar--size`.
+ * @cssproperty {pixel} --c2-avatar--height - Falls back to `--c2-avatar--size`.
+ * @cssproperty {color} [--c2-avatar--color=#ffffff]
+ * @cssproperty {background} [--c2-avatar--background=rgb(0, 122, 77)] - Ignored when `auto-color` is set.
+ * @cssproperty {box-shadow} --c2-avatar--box-shadow - e.g. `0 0 0 2px #fff` for a ring in stacked groups.
+ *
+ * @cssproperty {border-radius} [--c2-avatar--border-top-left-radius=999px]
+ * @cssproperty {border-radius} [--c2-avatar--border-top-right-radius=999px]
+ * @cssproperty {border-radius} [--c2-avatar--border-bottom-left-radius=999px]
+ * @cssproperty {border-radius} [--c2-avatar--border-bottom-right-radius=999px]
+ *
+ * @cssproperty {border} --c2-avatar--border-top
+ * @cssproperty {border} --c2-avatar--border-bottom
+ * @cssproperty {border} --c2-avatar--border-right
+ * @cssproperty {border} --c2-avatar--border-left
+ *
+ * @cssproperty {font-size} [--c2-avatar--font-size=calc(var(--c2-avatar--size) * 0.4)]
+ * @cssproperty {font-weight} [--c2-avatar--font-weight=600]
+ * @cssproperty {font-style} --c2-avatar--font-style
+ * @cssproperty {font-family} --c2-avatar--font-family
+ * @cssproperty {letter-spacing} [--c2-avatar--letter-spacing=0.02em]
+ *
+ * @cssproperty {saturation} [--c2-avatar__auto-color--saturation=55%] - Saturation of the hue derived from the name.
+ * @cssproperty {lightness} [--c2-avatar__auto-color--lightness=42%] - Lightness of the hue derived from the name.
+ *
+ * @cssproperty {object-fit} [--c2-avatar__image--object-fit=cover]
+ *
+ * @cssproperty {pixel} [--c2-avatar__badge--size=10px] - Diameter of the status dot; slotted badges size themselves.
+ * @cssproperty {border} [--c2-avatar__badge--border=2px solid #ffffff] - Ring separating the badge from the avatar.
+ * @cssproperty {pixel} [--c2-avatar__badge--offset=0px] - Positive values push the badge outwards.
+ * @cssproperty {color} [--c2-avatar__badge__online--color=rgb(34, 197, 94)]
+ * @cssproperty {color} [--c2-avatar__badge__away--color=rgb(245, 158, 11)]
+ * @cssproperty {color} [--c2-avatar__badge__busy--color=rgb(239, 68, 68)]
+ * @cssproperty {color} [--c2-avatar__badge__offline--color=rgb(161, 161, 170)]
+ */
+export declare class Avatar extends LitElement {
+    static styles: import("lit").CSSResult;
+    /** Full name: source of the initials, the accessible label and the `auto-color` hue. */
+    name: string;
+    /** Number of initials to show. With 2 and a name of three or more words, the first and last word are used. */
+    initialCount: number;
+    /** Explicit initials; overrides the ones computed from `name`. */
+    initials: string | undefined;
+    /** Image URL. Falls back to the initials when the image fails to load. */
+    src: string | undefined;
+    /** Image alt text; defaults to `name`. */
+    alt: string | undefined;
+    /** Derive a stable background hue from `name` (same name, same color). */
+    autoColor: boolean;
+    /** Presence dot in the bottom-right corner. */
+    status: AvatarStatus | undefined;
+    private imageFailed;
+    /** Accepts the pre-1.0 camelCase `initialCount="2"` attribute as well. */
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /** Initials shown when there is no image or slotted content. */
+    get initial(): string;
+    /** Hue (0–359) derived from the name, used by `auto-color`. */
+    get hue(): number;
+    willUpdate(changed: PropertyValues<this>): void;
+    private handleImageError;
+    render(): import("lit-html").TemplateResult<1>;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'c2-avatar': Avatar;
+    }
+}
+//# sourceMappingURL=avatar.d.ts.map

package/types/src/avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"avatar.d.ts","sourceRoot":"","sources":["../../src/avatar.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAA4B,KAAK,cAAc,EAAE,MAAM,KAAK,CAAA;AAM/E,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;AAIjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AACH,qBACa,MAAO,SAAQ,UAAU;IACpC,OAAgB,MAAM,0BAAoB;IAE1C,wFAAwF;IAC5E,IAAI,SAAK;IAErB,8GAA8G;IACtD,YAAY,SAAI;IAExE,kEAAkE;IACtD,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAY;IAEpD,0EAA0E;IAC9D,GAAG,EAAE,MAAM,GAAG,SAAS,CAAY;IAE/C,0CAA0C;IAC9B,GAAG,EAAE,MAAM,GAAG,SAAS,CAAY;IAE/C,0EAA0E;IACL,SAAS,UAAQ;IAEtF,+CAA+C;IAClB,MAAM,EAAE,YAAY,GAAG,SAAS,CAAY;IAEhE,OAAO,CAAC,WAAW,CAAQ;IAEpC,0EAA0E;IAC1E,WAAoB,kBAAkB,aAErC;IAEQ,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAQxF,gEAAgE;IAChE,IAAI,OAAO,IAAI,MAAM,CASpB;IAED,+DAA+D;IAC/D,IAAI,GAAG,IAAI,MAAM,CAKhB;IAEQ,UAAU,CAAC,OAAO,EAAE,cAAc,CAAC,IAAI,CAAC;IAIjD,OAAO,CAAC,gBAAgB;IAKf,MAAM;CAyBhB;AAED,OAAO,CAAC,MAAM,CAAC;IACb,UAAU,qBAAqB;QAC7B,WAAW,EAAE,MAAM,CAAA;KACpB;CACF"}