@openproject/primer-view-components 0.80.0 → 0.80.1

package/app/components/primer/open_project/avatar_fallback.d.ts

@@ -1,15 +1,28 @@
+/**
+ * AvatarFallbackElement implements "fallback first" loading pattern:
+ * 1. Fallback SVG is rendered immediately as <img> src
+ * 2. Real avatar URL is test-loaded in background using new Image()
+ * 3. On success, swaps to real image; on failure, fallback stays visible
+ *
+ * This approach prevents flicker by never showing a broken image state.
+ * Inspired by OpenProject's Angular PrincipalRendererService.
+ *
+ * Note: We read attributes directly via getAttribute() instead of using @attr
+ * due to a Catalyst bug where @attr accessors aren't properly initialized
+ * when elements have pre-existing attribute values.
+ */
 export declare class AvatarFallbackElement extends HTMLElement {
-    uniqueId: string;
-    altText: string;
-    fallbackSrc: string;
     private img;
-    private boundErrorHandler?;
+    private testImage;
     connectedCallback(): void;
     disconnectedCallback(): void;
-    private isImageBroken;
-    private handleImageError;
+    /**
+     * Test-loads the real avatar URL in background.
+     * On success, swaps the visible img to the real URL.
+     * On failure, does nothing - fallback stays visible.
+     */
+    private testLoadImage;
     private applyColor;
     private valueHash;
     private updateSvgColor;
-    private isFallbackImage;
 }

package/app/components/primer/open_project/avatar_fallback.js

@@ -4,57 +4,70 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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;
 };
-import { attr, controller } from '@github/catalyst';
+import { controller } from '@github/catalyst';
+/**
+ * AvatarFallbackElement implements "fallback first" loading pattern:
+ * 1. Fallback SVG is rendered immediately as <img> src
+ * 2. Real avatar URL is test-loaded in background using new Image()
+ * 3. On success, swaps to real image; on failure, fallback stays visible
+ *
+ * This approach prevents flicker by never showing a broken image state.
+ * Inspired by OpenProject's Angular PrincipalRendererService.
+ *
+ * Note: We read attributes directly via getAttribute() instead of using @attr
+ * due to a Catalyst bug where @attr accessors aren't properly initialized
+ * when elements have pre-existing attribute values.
+ */
 let AvatarFallbackElement = class AvatarFallbackElement extends HTMLElement {
     constructor() {
         super(...arguments);
-        this.uniqueId = '';
-        this.altText = '';
-        this.fallbackSrc = '';
         this.img = null;
+        this.testImage = null;
     }
     connectedCallback() {
         this.img = this.querySelector('img') ?? null;
         if (!this.img)
             return;
-        this.boundErrorHandler = () => this.handleImageError(this.img);
-        // Handle image load errors (404, network failure, etc.)
-        this.img.addEventListener('error', this.boundErrorHandler);
-        // Check if image already failed (error event fired before listener attached)
-        if (this.isImageBroken(this.img)) {
-            this.handleImageError(this.img);
-        }
-        else if (this.isFallbackImage(this.img)) {
-            this.applyColor(this.img);
+        const uniqueId = this.getAttribute('data-unique-id') || '';
+        const altText = this.getAttribute('data-alt-text') || '';
+        const avatarSrc = this.getAttribute('data-avatar-src') || '';
+        // Apply hashed color to fallback SVG immediately
+        this.applyColor(this.img, uniqueId, altText);
+        // Test-load real avatar URL in background
+        if (avatarSrc) {
+            this.testLoadImage(avatarSrc);
         }
     }
     disconnectedCallback() {
-        if (this.boundErrorHandler && this.img) {
-            this.img.removeEventListener('error', this.boundErrorHandler);
+        // Clean up test image and its event handler to prevent memory leaks
+        if (this.testImage) {
+            this.testImage.onload = null;
+            this.testImage = null;
         }
-        this.boundErrorHandler = undefined;
         this.img = null;
     }
-    isImageBroken(img) {
-        // Image is broken if loading completed but no actual image data loaded
-        // Skip check for data URIs (fallback SVGs) as they're always valid
-        return img.complete && img.naturalWidth === 0 && !img.src.startsWith('data:');
-    }
-    handleImageError(img) {
-        // Prevent infinite loop if fallback also fails
-        if (this.isFallbackImage(img))
-            return;
-        if (this.fallbackSrc) {
-            img.src = this.fallbackSrc;
-            this.applyColor(img);
-        }
+    /**
+     * Test-loads the real avatar URL in background.
+     * On success, swaps the visible img to the real URL.
+     * On failure, does nothing - fallback stays visible.
+     */
+    testLoadImage(url) {
+        this.testImage = new Image();
+        this.testImage.onload = () => {
+            // Success - swap to real image
+            if (this.img) {
+                this.img.src = url;
+            }
+        };
+        // On error: do nothing, fallback stays visible (no flicker)
+        this.testImage.src = url;
     }
-    applyColor(img) {
+    applyColor(img, uniqueId, altText) {
         // If either uniqueId or altText is missing, skip color customization so the SVG
         // keeps its default gray fill defined in the source and no color override is applied.
-        if (!this.uniqueId || !this.altText)
+        if (!uniqueId || !altText)
             return;
-        const text = `${this.uniqueId}${this.altText}`;
+        const text = `${uniqueId}${altText}`;
         const hue = this.valueHash(text);
         const color = `hsl(${hue}, 50%, 30%)`;
         this.updateSvgColor(img, color);
@@ -72,6 +85,8 @@ let AvatarFallbackElement = class AvatarFallbackElement extends HTMLElement {
     }
     updateSvgColor(img, color) {
         const dataUri = img.src;
+        if (!dataUri.startsWith('data:image/svg+xml;base64,'))
+            return;
         const base64 = dataUri.replace('data:image/svg+xml;base64,', '');
         try {
             const svg = atob(base64);
@@ -83,19 +98,7 @@ let AvatarFallbackElement = class AvatarFallbackElement extends HTMLElement {
             // to avoid breaking the component.
         }
     }
-    isFallbackImage(img) {
-        return img.src === this.fallbackSrc;
-    }
 };
-__decorate([
-    attr
-], AvatarFallbackElement.prototype, "uniqueId", void 0);
-__decorate([
-    attr
-], AvatarFallbackElement.prototype, "altText", void 0);
-__decorate([
-    attr
-], AvatarFallbackElement.prototype, "fallbackSrc", void 0);
 AvatarFallbackElement = __decorate([
     controller
 ], AvatarFallbackElement);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openproject/primer-view-components",
-  "version": "0.80.0",
+  "version": "0.80.1",
   "description": "ViewComponents of the Primer Design System for OpenProject",
   "main": "app/assets/javascripts/primer_view_components.js",
   "module": "app/components/primer/primer.js",

package/static/arguments.json

@@ -5775,13 +5775,13 @@
         "name": "src",
         "type": "String",
         "default": "`nil`",
-        "description": "The source url of the avatar image. When nil or a broken URL, it renders a fallback with initials."
+        "description": "The source URL of the avatar image. When provided, JavaScript will test-load it in the background and swap to it on success. When nil or blank, only the fallback SVG is displayed."
       },
       {
         "name": "alt",
         "type": "String",
         "default": "`nil`",
-        "description": "Alt text for the avatar. Used for accessibility and to generate initials when src is nil."
+        "description": "Alt text for the avatar. Used for accessibility and to generate initials for the fallback SVG."
       },
       {
         "name": "size",

package/static/info_arch.json

@@ -18866,7 +18866,7 @@
   },
   {
     "fully_qualified_name": "Primer::OpenProject::AvatarWithFallback",
-    "description": "OpenProject-specific Avatar component that extends Primer::Beta::Avatar\nto support fallback rendering with initials when no image source is provided.\n\nWhen `src` is nil, this component renders an SVG with initials extracted from\nthe alt text. The AvatarFallbackElement web component then enhances it client-side\nby applying a consistent background color based on the user's unique_id (using the\nsame hash function as OP Core for consistency).\n\nThis component follows the \"extension over mutation\" pattern - it extends\nPrimer::Beta::Avatar without modifying its interface, ensuring compatibility\nwith upstream changes.",
+    "description": "OpenProject-specific Avatar component that extends Primer::Beta::Avatar\nto support fallback rendering with initials when no image source is provided.\n\nUses a \"fallback first\" pattern for flicker-free loading:\n1. Always renders fallback SVG as initial <img> src (visible immediately)\n2. Client-side JS test-loads the real URL in background\n3. On success, swaps to real image; on failure, fallback stays visible\n\nThis approach is inspired by OpenProject's Angular PrincipalRendererService.",
     "accessibility_docs": null,
     "is_form_component": false,
     "is_published": true,
@@ -18882,13 +18882,13 @@
         "name": "src",
         "type": "String",
         "default": "`nil`",
-        "description": "The source url of the avatar image. When nil or a broken URL, it renders a fallback with initials."
+        "description": "The source URL of the avatar image. When provided, JavaScript will test-load it in the background and swap to it on success. When nil or blank, only the fallback SVG is displayed."
       },
       {
         "name": "alt",
         "type": "String",
         "default": "`nil`",
-        "description": "Alt text for the avatar. Used for accessibility and to generate initials when src is nil."
+        "description": "Alt text for the avatar. Used for accessibility and to generate initials for the fallback SVG."
       },
       {
         "name": "size",