[Bug Fix] Add Avatar image fallback handling (#387)

* [Bug Fix] Add Avatar image fallback handling (#259)

* fix(avatar): preserve image visibility without JS

Image was hidden by default and only revealed by the Stimulus
controller's load handler, which meant clients with JS disabled
never saw the avatar image. Make the image visible by default and
let the controller hide it on connect when it isn't yet loaded;
load/error events restore the proper image/fallback toggle.

Author: djalmaaraujo

docs/app/javascript/controllers/index.js

@@ -13,6 +13,9 @@ application.register("ruby-ui--accordion", RubyUi__AccordionController)
 import RubyUi__AlertDialogController from "./ruby_ui/alert_dialog_controller"
 application.register("ruby-ui--alert-dialog", RubyUi__AlertDialogController)
 
+import RubyUi__AvatarController from "./ruby_ui/avatar_controller"
+application.register("ruby-ui--avatar", RubyUi__AvatarController)
+
 import RubyUi__CalendarController from "./ruby_ui/calendar_controller"
 application.register("ruby-ui--calendar", RubyUi__CalendarController)
 

docs/app/javascript/controllers/ruby_ui/avatar_controller.js

@@ -0,0 +1,29 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["image", "fallback"];
+
+  connect() {
+    if (!this.hasImageTarget) return;
+
+    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {
+      this.showImage();
+    } else {
+      this.showFallback();
+    }
+  }
+
+  showImage() {
+    this.imageTargets.forEach((image) => image.classList.remove("hidden"));
+    this.fallbackTargets.forEach((fallback) =>
+      fallback.classList.add("hidden"),
+    );
+  }
+
+  showFallback() {
+    this.imageTargets.forEach((image) => image.classList.add("hidden"));
+    this.fallbackTargets.forEach((fallback) =>
+      fallback.classList.remove("hidden"),
+    );
+  }
+}

gem/lib/ruby_ui/avatar/avatar.rb

@@ -24,6 +24,9 @@ def view_template(&)
 
     def default_attrs
       {
+        data: {
+          controller: "ruby-ui--avatar"
+        },
         class: ["relative flex shrink-0 overflow-hidden rounded-full", @size_classes]
       }
     end

gem/lib/ruby_ui/avatar/avatar_controller.js

@@ -0,0 +1,33 @@
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["image", "fallback"];
+
+  connect() {
+    if (!this.hasImageTarget) {
+      return;
+    }
+
+    if (this.imageTarget.complete && this.imageTarget.naturalWidth > 0) {
+      this.showImage();
+    } else {
+      // Image not yet loaded (or failed): hide it so the fallback shows.
+      // Image visibility is restored by the load/error handlers.
+      this.showFallback();
+    }
+  }
+
+  showImage() {
+    this.imageTargets.forEach((image) => image.classList.remove("hidden"));
+    this.fallbackTargets.forEach((fallback) =>
+      fallback.classList.add("hidden"),
+    );
+  }
+
+  showFallback() {
+    this.imageTargets.forEach((image) => image.classList.add("hidden"));
+    this.fallbackTargets.forEach((fallback) =>
+      fallback.classList.remove("hidden"),
+    );
+  }
+}

gem/lib/ruby_ui/avatar/avatar_fallback.rb

@@ -10,6 +10,9 @@ def view_template(&)
 
     def default_attrs
       {
+        data: {
+          ruby_ui__avatar_target: "fallback"
+        },
         class: "flex h-full w-full items-center justify-center rounded-full bg-muted"
       }
     end

gem/lib/ruby_ui/avatar/avatar_image.rb

@@ -17,6 +17,10 @@ def view_template
     def default_attrs
       {
         loading: "lazy",
+        data: {
+          ruby_ui__avatar_target: "image",
+          action: "load->ruby-ui--avatar#showImage error->ruby-ui--avatar#showFallback"
+        },
         class: "aspect-square h-full w-full",
         alt: @alt,
         src: @src

gem/test/ruby_ui/avatar_test.rb

@@ -12,5 +12,11 @@ def test_render_with_all_items
     end
 
     assert_match(/joeldrapper/, output)
+    assert_match(/data-controller="ruby-ui--avatar"/, output)
+    assert_match(/data-ruby-ui--avatar-target="image"/, output)
+    assert_match(/load->ruby-ui--avatar#showImage error->ruby-ui--avatar#showFallback/, output)
+    assert_match(/data-ruby-ui--avatar-target="fallback"/, output)
+    assert_match(/class="aspect-square h-full w-full"/, output)
+    refute_match(/class="[^"]*\bhidden\b[^"]*aspect-square/, output)
   end
 end