@pablo-v/avatar 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pablo Viniegra
+
+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

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# @pablo-v/avatar
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+User avatar image with initials or identicon fallback
+
+```bash
+pnpm add @pablo-v/avatar @pablo-v/tokens
+```
+
+```tsx
+import '@pablo-v/tokens/styles.css';
+import '@pablo-v/avatar/style.css';
+import { Avatar } from '@pablo-v/avatar';
+```

package/dist/Avatar.d.ts

@@ -0,0 +1,27 @@
+import { type ComponentPropsWithRef, type ReactNode } from 'react';
+export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg';
+export type AvatarStatus = 'online' | 'away' | 'busy' | 'offline';
+export interface AvatarProps extends Omit<ComponentPropsWithRef<'span'>, 'children'> {
+    /** Person or entity shown; names the avatar and feeds the initials fallback. */
+    name: string;
+    src?: string;
+    /** Replaces the initials when there is no image or it fails to load. */
+    fallback?: ReactNode;
+    /** @default 'md' */
+    size?: AvatarSize;
+    /** @default 'circle' */
+    shape?: 'circle' | 'square';
+    /** Presence cell in the corner, announced with the name. */
+    status?: AvatarStatus;
+}
+/** Profile picture with an initials fallback while loading or on error. */
+export declare function Avatar({ name, src, fallback, size, shape, status, className, ...rest }: AvatarProps): import("react").JSX.Element;
+export interface AvatarGroupProps extends ComponentPropsWithRef<'div'> {
+    /** Avatars beyond this count collapse into a "+N" chip. */
+    max?: number;
+    /** Size of the overflow chip; match the avatars. @default 'md' */
+    size?: AvatarSize;
+}
+/** Overlapping row of avatars. */
+export declare function AvatarGroup({ max, size, className, children, ...rest }: AvatarGroupProps): import("react").JSX.Element;
+//# sourceMappingURL=Avatar.d.ts.map

package/dist/Avatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.d.ts","sourceRoot":"","sources":["../src/Avatar.tsx"],"names":[],"mappings":"AAGA,OAAO,EAAY,KAAK,qBAAqB,EAAE,KAAK,SAAS,EAAY,MAAM,OAAO,CAAC;AAEvF,MAAM,MAAM,UAAU,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AACnD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;AAElE,MAAM,WAAW,WAAY,SAAQ,IAAI,CAAC,qBAAqB,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC;IAClF,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wEAAwE;IACxE,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB,oBAAoB;IACpB,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,wBAAwB;IACxB,KAAK,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAC;IAC5B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAQD,2EAA2E;AAC3E,wBAAgB,MAAM,CAAC,EACrB,IAAI,EACJ,GAAG,EACH,QAAQ,EACR,IAAW,EACX,KAAgB,EAChB,MAAM,EACN,SAAS,EACT,GAAG,IAAI,EACR,EAAE,WAAW,+BAsCb;AAED,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB,CAAC,KAAK,CAAC;IACpE,2DAA2D;IAC3D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED,kCAAkC;AAClC,wBAAgB,WAAW,CAAC,EAAE,GAAG,EAAE,IAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,EAAE,gBAAgB,+BAsB/F"}

package/dist/Avatar.js

@@ -0,0 +1,28 @@
+'use client';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cx } from '@pablo-v/core';
+import { Children, useState } from 'react';
+function initials(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    const letters = words.length > 1 ? [words[0], words[words.length - 1]] : words;
+    return letters.map((w) => Array.from(w ?? '')[0]?.toUpperCase()).join('');
+}
+/** Profile picture with an initials fallback while loading or on error. */
+export function Avatar({ name, src, fallback, size = 'md', shape = 'circle', status, className, ...rest }) {
+    const [failed, setFailed] = useState();
+    const [loaded, setLoaded] = useState();
+    const showImage = src != null && failed !== src;
+    return (_jsxs("span", { role: "img", "aria-label": status ? `${name} (${status})` : name, className: cx('pxl-avatar', className), "data-size": size, "data-shape": shape, ...rest, children: [(!showImage || loaded !== src) && (_jsx("span", { className: "pxl-avatar__fallback", "aria-hidden": "true", children: fallback ?? initials(name) })), showImage && (_jsx("img", { className: "pxl-avatar__image", src: src, alt: "", "data-loaded": loaded === src || undefined, ref: (img) => {
+                    // Cached images can finish before hydration attaches onLoad.
+                    if (img?.complete)
+                        img.naturalWidth ? setLoaded(src) : setFailed(src);
+                }, onLoad: () => setLoaded(src), onError: () => setFailed(src) })), status && (_jsx("span", { className: "pxl-avatar__status", "data-status": status, "aria-hidden": "true" }, status))] }));
+}
+/** Overlapping row of avatars. */
+export function AvatarGroup({ max, size = 'md', className, children, ...rest }) {
+    const items = Children.toArray(children);
+    const visible = max != null && items.length > max ? items.slice(0, max) : items;
+    const hidden = items.length - visible.length;
+    return (_jsxs("div", { role: "group", className: cx('pxl-avatar-group', className), ...rest, children: [visible, hidden > 0 && (_jsx("span", { role: "img", "aria-label": `${hidden} more`, className: "pxl-avatar pxl-avatar__more", "data-size": size, "data-shape": "circle", children: _jsxs("span", { className: "pxl-avatar__fallback", "aria-hidden": "true", children: ["+", hidden] }) }))] }));
+}
+//# sourceMappingURL=Avatar.js.map

package/dist/Avatar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Avatar.js","sourceRoot":"","sources":["../src/Avatar.tsx"],"names":[],"mappings":"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"}

package/dist/avatar.css

@@ -0,0 +1,184 @@
+.pxl-avatar {
+  --_size: var(--pxl-size-md);
+  --_text: var(--pxl-text-md);
+  --_radius: var(--pxl-radius-full);
+
+  position: relative;
+  display: inline-grid;
+  flex: none;
+  place-items: center;
+  width: var(--_size);
+  height: var(--_size);
+  border-radius: var(--_radius);
+  background: var(--pxl-gray-200);
+  color: var(--pxl-fg);
+  font-family: var(--pxl-font-sans);
+  font-size: var(--_text);
+  font-weight: 600;
+  line-height: 1;
+  user-select: none;
+  vertical-align: middle;
+}
+
+.pxl-avatar[data-size="xs"] {
+  --_size: var(--pxl-size-xs);
+  --_text: 10px;
+}
+
+.pxl-avatar[data-size="sm"] {
+  --_size: var(--pxl-size-sm);
+  --_text: var(--pxl-text-xs);
+}
+
+.pxl-avatar[data-size="lg"] {
+  --_size: var(--pxl-size-lg);
+  --_text: var(--pxl-text-lg);
+}
+
+.pxl-avatar[data-shape="square"] {
+  --_radius: var(--pxl-radius-md);
+}
+
+.pxl-avatar__fallback,
+.pxl-avatar__image {
+  grid-area: 1 / 1;
+}
+
+.pxl-avatar__fallback {
+  display: grid;
+  place-items: center;
+  width: 100%;
+  height: 100%;
+  min-width: 0;
+  letter-spacing: -0.02em;
+}
+
+.pxl-avatar__fallback > svg {
+  width: 60%;
+  height: 60%;
+}
+
+.pxl-avatar__image {
+  min-width: 0;
+  width: 100%;
+  height: 100%;
+  border-radius: inherit;
+  object-fit: cover;
+  opacity: 0;
+  transition: opacity var(--pxl-dur-base) var(--pxl-ease-out);
+}
+
+.pxl-avatar__image[data-loaded] {
+  opacity: 1;
+}
+
+/* Hairline inside the edge so photos with a white or black rim keep their shape. */
+.pxl-avatar::after {
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pxl-fg) 16%, transparent);
+  content: "";
+  pointer-events: none;
+}
+
+/* The presence marker is a single pixel cell, ringed by the page colour. */
+.pxl-avatar__status {
+  position: absolute;
+  inset-inline-end: 0;
+  bottom: 0;
+  z-index: 1;
+  display: grid;
+  place-items: center;
+  width: max(8px, calc(var(--_size) / 5));
+  height: max(8px, calc(var(--_size) / 5));
+  border-radius: var(--pxl-radius-xs);
+  background: var(--pxl-gray-600);
+  box-shadow: 0 0 0 2px var(--pxl-bg);
+  animation: pxl-pop-in var(--pxl-dur-base) var(--pxl-ease-out) both;
+}
+
+.pxl-avatar[data-shape="square"] .pxl-avatar__status {
+  inset-inline-end: -2px;
+  bottom: -2px;
+}
+
+.pxl-avatar__status[data-status="online"] {
+  background: var(--pxl-success);
+}
+
+.pxl-avatar__status[data-status="away"] {
+  background: var(--pxl-warning);
+}
+
+.pxl-avatar__status[data-status="busy"] {
+  background: var(--pxl-danger);
+}
+
+.pxl-avatar__status[data-status="busy"]::after {
+  width: 4px;
+  height: 2px;
+  background: var(--pxl-bg);
+  content: "";
+}
+
+.pxl-avatar__status[data-status="away"]::after {
+  width: 3px;
+  height: 3px;
+  border-inline-start: 1px solid var(--pxl-bg);
+  border-bottom: 1px solid var(--pxl-bg);
+  content: "";
+}
+
+.pxl-avatar__status[data-status="offline"] {
+  box-sizing: border-box;
+  border: 2px solid var(--pxl-gray-600);
+  background: var(--pxl-bg);
+}
+
+.pxl-avatar-group {
+  display: inline-flex;
+}
+
+.pxl-avatar-group > .pxl-avatar {
+  box-shadow: 0 0 0 2px var(--pxl-bg);
+}
+
+.pxl-avatar-group > .pxl-avatar + .pxl-avatar {
+  margin-inline-start: calc(var(--_size) / -4);
+}
+
+.pxl-avatar__more {
+  background: var(--pxl-fg);
+  color: var(--pxl-bg);
+  font-family: var(--pxl-font-mono);
+  font-size: var(--pxl-text-xs);
+  font-weight: 500;
+  font-variant-numeric: tabular-nums;
+}
+
+@media (forced-colors: active) {
+  .pxl-avatar::after {
+    border: 1px solid CanvasText;
+  }
+
+  .pxl-avatar__status[data-status] {
+    background: CanvasText;
+    outline: 2px solid Canvas;
+    forced-color-adjust: none;
+  }
+
+  .pxl-avatar__status[data-status="offline"] {
+    border-color: CanvasText;
+    background: Canvas;
+  }
+
+  .pxl-avatar__status[data-status]::after {
+    border-color: Canvas;
+    background: Canvas;
+  }
+
+  .pxl-avatar__status[data-status="away"]::after {
+    background: transparent;
+  }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, type AvatarStatus, } from './Avatar.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Avatar, AvatarGroup, } from './Avatar.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,MAAM,EACN,WAAW,GAKZ,MAAM,aAAa,CAAC"}

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@pablo-v/avatar",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Photo avatar with initials fallback, presence status and groups",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PabloViniegra/pixel-ui.git",
+    "directory": "packages/avatar"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./style.css": {
+      "source": "./src/avatar.css",
+      "default": "./dist/avatar.css"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@pablo-v/core": "^0.2.2"
+  },
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "@pablo-v/tokens": "^0.2.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b && node ../../scripts/copy-assets.mjs",
+    "clean": "rm -rf dist *.tsbuildinfo"
+  }
 }