openproject-primer_view_components 0.80.0 → 0.80.1

data/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;
 }

data/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);

data/app/components/primer/open_project/avatar_fallback.ts

@@ -1,61 +1,74 @@
-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.
+ */
 @controller
 export class AvatarFallbackElement extends HTMLElement {
-  @attr uniqueId = ''
-  @attr altText = ''
-  @attr fallbackSrc = ''
-
   private img: HTMLImageElement | null = null
-  private boundErrorHandler?: () => void
+  private testImage: HTMLImageElement | null = null
 
   connectedCallback() {
     this.img = this.querySelector<HTMLImageElement>('img') ?? null
     if (!this.img) return
 
-    this.boundErrorHandler = () => this.handleImageError(this.img!)
+    const uniqueId = this.getAttribute('data-unique-id') || ''
+    const altText = this.getAttribute('data-alt-text') || ''
+    const avatarSrc = this.getAttribute('data-avatar-src') || ''
 
-    // Handle image load errors (404, network failure, etc.)
-    this.img.addEventListener('error', this.boundErrorHandler)
+    // Apply hashed color to fallback SVG immediately
+    this.applyColor(this.img, uniqueId, altText)
 
-    // 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)
+    // 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
   }
 
-  private isImageBroken(img: HTMLImageElement): boolean {
-    // 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:')
-  }
-
-  private handleImageError(img: HTMLImageElement) {
-    // 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.
+   */
+  private testLoadImage(url: string) {
+    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
   }
 
-  private applyColor(img: HTMLImageElement) {
+  private applyColor(img: HTMLImageElement, uniqueId: string, altText: string) {
     // 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) return
+    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%)`
 
@@ -76,6 +89,8 @@ export class AvatarFallbackElement extends HTMLElement {
 
   private updateSvgColor(img: HTMLImageElement, color: string) {
     const dataUri = img.src
+    if (!dataUri.startsWith('data:image/svg+xml;base64,')) return
+
     const base64 = dataUri.replace('data:image/svg+xml;base64,', '')
 
     try {
@@ -87,8 +102,4 @@ export class AvatarFallbackElement extends HTMLElement {
       // to avoid breaking the component.
     }
   }
-
-  private isFallbackImage(img: HTMLImageElement): boolean {
-    return img.src === this.fallbackSrc
-  }
 }

data/app/components/primer/open_project/avatar_with_fallback.rb

@@ -5,14 +5,12 @@ module Primer
     # OpenProject-specific Avatar component that extends Primer::Beta::Avatar
     # to support fallback rendering with initials when no image source is provided.
     #
-    # When `src` is nil, this component renders an SVG with initials extracted from
-    # the alt text. The AvatarFallbackElement web component then enhances it client-side
-    # by applying a consistent background color based on the user's unique_id (using the
-    # same hash function as OP Core for consistency).
+    # Uses a "fallback first" pattern for flicker-free loading:
+    # 1. Always renders fallback SVG as initial <img> src (visible immediately)
+    # 2. Client-side JS test-loads the real URL in background
+    # 3. On success, swaps to real image; on failure, fallback stays visible
     #
-    # This component follows the "extension over mutation" pattern - it extends
-    # Primer::Beta::Avatar without modifying its interface, ensuring compatibility
-    # with upstream changes.
+    # This approach is inspired by OpenProject's Angular PrincipalRendererService.
     class AvatarWithFallback < Primer::Beta::Avatar
       status :open_project
 
@@ -21,8 +19,8 @@ module Primer
       #   - https://github.com/primer/css/blob/main/src/support/variables/typography.scss
       FONT_STACK = "-apple-system, BlinkMacSystemFont, 'Segoe UI', 'Noto Sans', Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji'"
 
-      # @param src [String] The source url of the avatar image. When nil or a broken URL, it renders a fallback with initials.
-      # @param alt [String] Alt text for the avatar. Used for accessibility and to generate initials when src is nil.
+      # @param src [String] 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.
+      # @param alt [String] Alt text for the avatar. Used for accessibility and to generate initials for the fallback SVG.
       # @param size [Integer] <%= one_of(Primer::Beta::Avatar::SIZE_OPTIONS) %>
       # @param shape [Symbol] Shape of the avatar. <%= one_of(Primer::Beta::Avatar::SHAPE_OPTIONS) %>
       # @param href [String] The URL to link to. If used, component will be wrapped by an `<a>` tag.
@@ -32,10 +30,11 @@ module Primer
         require_src_or_alt_arguments(src, alt)
 
         @unique_id = unique_id
+        @avatar_src = src.presence
         @fallback_svg = generate_fallback_svg(alt, size)
-        final_src = src.blank? ? @fallback_svg : src
 
-        super(src: final_src, alt: alt, size: size, shape: shape, href: href, **system_arguments)
+        # Always render fallback first - JS will swap to real image on successful load
+        super(src: @fallback_svg, alt: alt, size: size, shape: shape, href: href, **system_arguments)
       end
 
       def call
@@ -45,7 +44,7 @@ module Primer
             data: {
               unique_id: @unique_id,
               alt_text: @system_arguments[:alt],
-              fallback_src: @fallback_svg
+              avatar_src: @avatar_src
             }
           )
         ) { super }

data/lib/primer/view_components/version.rb

@@ -6,7 +6,7 @@ module Primer
     module VERSION
       MAJOR = 0
       MINOR = 80
-      PATCH = 0
+      PATCH = 1
 
       STRING = [MAJOR, MINOR, PATCH].join(".")
     end

data/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",

data/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",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: openproject-primer_view_components
 version: !ruby/object:Gem::Version
-  version: 0.80.0
+  version: 0.80.1
 platform: ruby
 authors:
 - GitHub Open Source
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-23 00:00:00.000000000 Z
+date: 2026-01-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionview