fix(ui5-avatar): add dynamic image error handling with fallback logic (#11642)

This commit fixes image error handling in the Avatar component to ensure
fallback content is displayed when images fail to load.

**Problem Fixed:**
- Avatar would show broken/empty content when image sources were invalid
- No automatic fallback when images failed to load dynamically
- Missing error detection for already-broken images at initialization

**Solution:**
- **Dynamic Image Error Detection**: Added real-time monitoring of image
   load states with automatic fallback switching
- **Reactive Error Handling**: Image failures now trigger immediate UI
  updates to show appropriate fallback content
- **Comprehensive Error Detection**: Handles both runtime failures and
  already-broken images via `complete` and `naturalWidth` checks

**Technical Implementation:**
- Added `_imageLoadError` reactive property to track image state changes
- Implemented event listeners for `load` and `error` events on image
  elements
- Enhanced `hasImage` getter to consider both image presence and load
  state
- Added proper event listener lifecycle management to prevent memory
  leaks
- Optimized re-rendering with cached `_hasImage` property in template

**Fallback Hierarchy (unchanged):**
1. Image (if provided and loads successfully)
2. Icon (if `icon` property is set)
3. Initials (if valid and fit)
4. Fallback Icon (final fallback)

**Edge Cases Handled:**
- Images that fail after initial load (dynamic URL changes)
- Images that are already broken when component initializes
- Seamless switching between broken → fixed → broken states

**Files Modified:**
- Avatar.ts: Core image error handling and reactive state management
- AvatarTemplate.tsx: Updated to use cached `_hasImage` property
- Avatar.cy.tsx: Added comprehensive test coverage for error scenarios

Fixes: #11140

Author: kgogov

packages/main/cypress/specs/Avatar.cy.tsx

@@ -2,6 +2,8 @@ import Avatar from "../../src/Avatar.js";
 import Tag from "../../src/Tag.js";
 import Icon from "../../src/Icon.js";
 import "@ui5/webcomponents-icons/dist/supplier.js";
+import "@ui5/webcomponents-icons/dist/alert.js";
+import "@ui5/webcomponents-icons/dist/person-placeholder.js";
 
 describe("Accessibility", () => {
 	it("checks if initials of avatar are correctly announced", () => {
@@ -53,3 +55,254 @@ describe("Accessibility", () => {
 		cy.get("#click-event").should("have.value", "0");
 	});
 });
+
+describe("Fallback Logic", () => {
+	it("shows image when valid image is provided", () => {
+		cy.mount(
+			<Avatar id="avatar-with-image">
+				<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" alt="Test" />
+			</Avatar>
+		);
+
+		cy.get("#avatar-with-image")
+			.shadow()
+			.find(".ui5-avatar-root slot:not([name])")
+			.should("exist");
+
+		cy.get("#avatar-with-image")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("not.exist");
+	});
+
+	it("shows fallback icon when image fails to load", () => {
+		cy.mount(
+			<Avatar id="avatar-broken-image">
+				<img src="./invalid-image.png" alt="Broken" />
+			</Avatar>
+		);
+
+		// Wait for image error to trigger
+		cy.wait(100);
+
+		cy.get("#avatar-broken-image")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist")
+			.and("be.visible");
+	});
+
+	it("shows custom icon when icon property is set (no image)", () => {
+		cy.mount(<Avatar id="avatar-with-icon" icon="supplier"></Avatar>);
+
+		cy.get("#avatar-with-icon")
+			.shadow()
+			.find(".ui5-avatar-icon")
+			.should("exist")
+			.and("be.visible")
+			.and("have.attr", "name", "supplier");
+
+		cy.get("#avatar-with-icon")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("not.be.visible");
+	});
+
+	it("shows valid initials when provided (no image, no icon)", () => {
+		cy.mount(<Avatar id="avatar-with-initials" initials="JD"></Avatar>);
+
+		cy.get("#avatar-with-initials")
+			.shadow()
+			.find(".ui5-avatar-initials")
+			.should("exist")
+			.and("contain.text", "JD");
+
+		cy.get("#avatar-with-initials")
+			.shadow()
+			.find(".ui5-avatar-fallback-icon-hidden")
+			.should("exist");
+	});
+
+	it("shows fallback icon for invalid initials (too many characters)", () => {
+		cy.mount(<Avatar id="avatar-invalid-initials" initials="ABCD"></Avatar>);
+
+		cy.get("#avatar-invalid-initials")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist")
+			.and("be.visible");
+
+		cy.get("#avatar-invalid-initials")
+			.shadow()
+			.find(".ui5-avatar-initials")
+			.should("have.class", "ui5-avatar-initials-hidden");
+	});
+
+	it("shows fallback icon for non-Latin initials", () => {
+		cy.mount(<Avatar id="avatar-non-latin" initials="АБ"></Avatar>);
+
+		cy.get("#avatar-non-latin")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist")
+			.and("be.visible");
+	});
+
+	it("shows custom fallback icon when specified", () => {
+		cy.mount(<Avatar id="avatar-custom-fallback" fallbackIcon="alert"></Avatar>);
+
+		cy.get("#avatar-custom-fallback")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist")
+			.and("have.attr", "name", "alert");
+	});
+
+	it("prioritizes image over icon", () => {
+		cy.mount(
+			<Avatar id="avatar-image-over-icon" icon="supplier">
+				<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" alt="Test" />
+			</Avatar>
+		);
+
+		// Should show image, not icon
+		cy.get("#avatar-image-over-icon")
+			.shadow()
+			.find("slot:not([name])")
+			.should("exist");
+
+		cy.get("#avatar-image-over-icon")
+			.shadow()
+			.find(".ui5-avatar-icon")
+			.should("not.exist");
+	});
+
+	it("prioritizes icon over initials", () => {
+		cy.mount(<Avatar id="avatar-icon-over-initials" icon="supplier" initials="JD"></Avatar>);
+
+		cy.get("#avatar-icon-over-initials")
+			.shadow()
+			.find(".ui5-avatar-icon")
+			.should("exist")
+			.and("have.attr", "name", "supplier");
+
+		cy.get("#avatar-icon-over-initials")
+			.shadow()
+			.find(".ui5-avatar-initials")
+			.should("have.class", "ui5-avatar-initials-hidden");
+	});
+
+	it("switches from image to fallback when image fails dynamically", () => {
+		cy.mount(
+			<Avatar id="avatar-dynamic-fail">
+				<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==" alt="Test" />
+			</Avatar>
+		);
+
+		// Initially should show image
+		cy.get("#avatar-dynamic-fail")
+			.shadow()
+			.find("slot:not([name])")
+			.should("exist");
+
+		// Change image source to broken URL
+		cy.get("#avatar-dynamic-fail img").then(($img) => {
+			($img[0] as HTMLImageElement).src = "./broken-image.png";
+		});
+
+		// Wait for error handling
+		cy.wait(100);
+
+		// Should now show fallback icon
+		cy.get("#avatar-dynamic-fail")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist")
+			.and("be.visible");
+	});
+
+	it("switches from fallback back to image when image is fixed", () => {
+		cy.mount(
+			<Avatar id="avatar-dynamic-fix">
+				<img src="./broken-image.png" alt="Initially broken" />
+			</Avatar>
+		);
+
+		// Wait for initial error
+		cy.wait(100);
+
+		// Should show fallback initially
+		cy.get("#avatar-dynamic-fix")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist");
+
+		// Fix the image source
+		cy.get("#avatar-dynamic-fix img").then(($img) => {
+			($img[0] as HTMLImageElement).src = "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==";
+		});
+
+		// Wait for load handling
+		cy.wait(100);
+
+		// Should now show image
+		cy.get("#avatar-dynamic-fix")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("not.exist");
+	});
+
+	it("shows fallback icon when no content is provided", () => {
+		cy.mount(<Avatar id="avatar-empty"></Avatar>);
+
+		cy.get("#avatar-empty")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("exist")
+			.and("be.visible")
+			.and("have.attr", "name", "employee"); // Default fallback icon
+	});
+
+	it("correctly handles initials that don't fit in small sizes", () => {
+		cy.mount(<Avatar id="avatar-tight-initials" initials="WWW" size="XS"></Avatar>);
+
+		// For XS size, "WWW" likely won't fit, so should show fallback
+		cy.get("#avatar-tight-initials")
+			.shadow()
+			.find(".ui5-avatar-initials")
+			.should("have.class", "ui5-avatar-initials-hidden");
+
+		cy.get("#avatar-tight-initials")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("not.have.class", "ui5-avatar-fallback-icon-hidden");
+	});
+
+	it("maintains fallback hierarchy: Image > Icon > Initials > Fallback Icon", () => {
+		// Test with broken image, should show icon
+		cy.mount(
+			<Avatar id="hierarchy-test" icon="supplier" initials="JD">
+				<img src="./broken-image.png" alt="Broken" />
+			</Avatar>
+		);
+
+		cy.wait(100);
+
+		// Should show icon (not initials or fallback) when image fails
+		cy.get("#hierarchy-test")
+			.shadow()
+			.find(".ui5-avatar-icon")
+			.should("exist")
+			.and("have.attr", "name", "supplier");
+
+		cy.get("#hierarchy-test")
+			.shadow()
+			.find(".ui5-avatar-initials")
+			.should("have.class", "ui5-avatar-initials-hidden");
+
+		cy.get("#hierarchy-test")
+			.shadow()
+			.find(".ui5-avatar-icon-fallback")
+			.should("have.class", "ui5-avatar-fallback-icon-hidden");
+	});
+});

packages/main/src/Avatar.ts

@@ -215,6 +215,12 @@ class Avatar extends UI5Element implements ITabbable, IAvatarGroupItem {
 	@property({ type: Boolean })
 	_hasImage = false;
 
+	/**
+	 * @private
+	 */
+	@property({ type: Boolean, noAttribute: true })
+	_imageLoadError = false;
+
 	/**
 	 * Receives the desired `<img>` tag
 	 *
@@ -244,13 +250,19 @@ class Avatar extends UI5Element implements ITabbable, IAvatarGroupItem {
 	static i18nBundle: I18nBundle;
 
 	_handleResizeBound: ResizeObserverCallback;
+	_onImageLoadBound: (e: Event) => void;
+	_onImageErrorBound: (e: Event) => void;
 
 	constructor() {
 		super();
+
 		this._handleResizeBound = this.handleResize.bind(this);
+		this._onImageLoadBound = this._onImageLoad.bind(this);
+		this._onImageErrorBound = this._onImageError.bind(this);
 	}
 
 	onBeforeRendering() {
+		this._attachImageEventHandlers();
 		this._hasImage = this.hasImage;
 	}
 
@@ -316,7 +328,11 @@ class Avatar extends UI5Element implements ITabbable, IAvatarGroupItem {
 	}
 
 	get hasImage() {
-		return !!this.image.length;
+		return !!this.image.length && !this._imageLoadError;
+	}
+
+	get imageEl(): HTMLImageElement | null {
+		return this.image?.[0] instanceof HTMLImageElement ? this.image[0] : null;
 	}
 
 	get initialsContainer(): HTMLObjectElement | null {
@@ -346,6 +362,8 @@ class Avatar extends UI5Element implements ITabbable, IAvatarGroupItem {
 	onExitDOM() {
 		this.initialsContainer && ResizeHandler.deregister(this.initialsContainer,
 			this._handleResizeBound);
+
+		this._detachImageEventHandlers();
 	}
 
 	handleResize() {
@@ -414,6 +432,67 @@ class Avatar extends UI5Element implements ITabbable, IAvatarGroupItem {
 
 		return ariaHaspopup;
 	}
+
+	_attachImageEventHandlers() {
+		const imgEl = this.imageEl;
+		if (!imgEl) {
+			this._imageLoadError = false;
+			return;
+		}
+
+		// Remove previous handlers to avoid duplicates
+		imgEl.removeEventListener("load", this._onImageLoadBound);
+		imgEl.removeEventListener("error", this._onImageErrorBound);
+
+		// Attach new handlers
+		imgEl.addEventListener("load", this._onImageLoadBound);
+		imgEl.addEventListener("error", this._onImageErrorBound);
+
+		// Check existing image state
+		this._checkExistingImageState();
+	}
+
+	_checkExistingImageState() {
+		const imgEl = this.imageEl;
+		if (!imgEl) {
+			this._imageLoadError = false;
+			return;
+		}
+
+		if (imgEl.complete && imgEl.naturalWidth === 0) {
+			this._imageLoadError = true; // Already broken
+		} else if (imgEl.complete && imgEl.naturalWidth > 0) {
+			this._imageLoadError = false; // Already loaded
+		} else {
+			this._imageLoadError = false; // Pending load
+		}
+	}
+
+	_detachImageEventHandlers() {
+		const imgEl = this.imageEl;
+		if (!imgEl) {
+			return;
+		}
+
+		imgEl.removeEventListener("load", this._onImageLoadBound);
+		imgEl.removeEventListener("error", this._onImageErrorBound);
+	}
+
+	_onImageLoad(e: Event) {
+		if (e.target !== this.imageEl) {
+			(e.target as HTMLImageElement)?.removeEventListener("load", this._onImageLoadBound);
+			return;
+		}
+		this._imageLoadError = false;
+	}
+
+	_onImageError(e: Event) {
+		if (e.target !== this.imageEl) {
+			(e.target as HTMLImageElement)?.removeEventListener("error", this._onImageErrorBound);
+			return;
+		}
+		this._imageLoadError = true;
+	}
 }
 
 Avatar.define();