feat(Avatar): improve image loading status handling and add crossOrigin prop (#1838)

sadeghbarati · zernonia · web-flow · commit 554cbb0c98cf · 2025-05-06T17:48:31.000+08:00
* fix(avatar): improve image loading status handling and add crossOrigin prop

* fix: use watchEffect cleanup, watch cleanup feature is for vue 3.5+

* fix: move `resolveLoadingStatus` fn inside watchEffect instead of using another watch fn

* fix: test case

---------

Co-authored-by: zernonia &lt;zernonia@gmail.com&gt;
diff --git a/packages/core/src/Avatar/Avatar.test.ts b/packages/core/src/Avatar/Avatar.test.ts
@@ -9,6 +9,36 @@ import Avatar from './story/_Avatar.vue'
 const FALLBACK = 'CT'
 const DELAY = 350
 
+const ImgClass = class MockImage {
+  onload: () => void = () => {}
+  src = ''
+  eventListeners: Record<string, Array<() => void>> = {}
+
+  constructor() {
+    setTimeout(() => {
+      this.onload()
+      // Also trigger 'load' event listeners
+      if (this.eventListeners.load) {
+        this.eventListeners.load.forEach(callback => callback())
+      }
+    }, DELAY)
+    return this
+  }
+
+  addEventListener(event: string, callback: () => void) {
+    if (!this.eventListeners[event]) {
+      this.eventListeners[event] = []
+    }
+    this.eventListeners[event].push(callback)
+  }
+
+  removeEventListener(event: string, callback: () => void) {
+    if (this.eventListeners[event]) {
+      this.eventListeners[event] = this.eventListeners[event].filter(cb => cb !== callback)
+    }
+  }
+}
+
 it('should pass axe accessibility tests', async () => {
   const wrapper = mount(Avatar)
   expect(await axe(wrapper.element)).toHaveNoViolations()
@@ -17,16 +47,7 @@ it('should pass axe accessibility tests', async () => {
 describe('given an Avatar with fallback and a working image', async () => {
   let wrapper: VueWrapper<InstanceType<typeof Avatar>>
   beforeAll(async () => {
-    (window.Image as any) = class MockImage {
-      onload: () => void = () => {}
-      src = ''
-      constructor() {
-        setTimeout(() => {
-          this.onload()
-        }, DELAY)
-        return this
-      }
-    }
+    (window.Image as any) = ImgClass
     wrapper = mount(Avatar)
   })
 
@@ -60,16 +81,7 @@ describe('given an Avatar with fallback and delayed render', () => {
   let wrapper: VueWrapper<InstanceType<typeof Avatar>>
 
   beforeAll(async () => {
-    (window.Image as any) = class MockImage {
-      onload: () => void = () => {}
-      src = ''
-      constructor() {
-        setTimeout(() => {
-          this.onload()
-        }, DELAY)
-        return this
-      }
-    }
+    (window.Image as any) = ImgClass
     wrapper = mount(Avatar, {
       props: {
         delay: 300,
diff --git a/packages/core/src/Avatar/AvatarFallback.vue b/packages/core/src/Avatar/AvatarFallback.vue
@@ -10,34 +10,29 @@ export interface AvatarFallbackProps extends PrimitiveProps {
 
 <script setup lang="ts">
 import { Primitive } from '@/Primitive'
-import { ref, watch } from 'vue'
+import { ref, watchEffect } from 'vue'
 import { injectAvatarRootContext } from './AvatarRoot.vue'
 
 const props = withDefaults(defineProps<AvatarFallbackProps>(), {
-  delayMs: 0,
   as: 'span',
 })
 
 const rootContext = injectAvatarRootContext()
 useForwardExpose()
 
-const canRender = ref(false)
-let timeout: ReturnType<typeof setTimeout> | undefined
-
-watch(rootContext.imageLoadingStatus, (value) => {
-  if (value === 'loading') {
-    canRender.value = false
-    if (props.delayMs) {
-      timeout = setTimeout(() => {
-        canRender.value = true
-        clearTimeout(timeout)
-      }, props.delayMs)
-    }
-    else {
+const canRender = ref(props.delayMs === undefined)
+
+watchEffect((onCleanup) => {
+  if (props.delayMs) {
+    const timerId = window.setTimeout(() => {
       canRender.value = true
-    }
+    }, props.delayMs)
+
+    onCleanup(() => {
+      window.clearTimeout(timerId)
+    })
   }
-}, { immediate: true })
+})
 </script>
 
 <template>
diff --git a/packages/core/src/Avatar/AvatarImage.vue b/packages/core/src/Avatar/AvatarImage.vue
@@ -13,6 +13,7 @@ export type AvatarImageEmits = {
 export interface AvatarImageProps extends PrimitiveProps {
   src: string
   referrerPolicy?: ImgHTMLAttributes['referrerpolicy']
+  crossOrigin?: ImgHTMLAttributes['crossorigin']
 }
 </script>
 
@@ -26,11 +27,11 @@ import { useImageLoadingStatus } from './utils'
 const props = withDefaults(defineProps<AvatarImageProps>(), { as: 'img' })
 const emits = defineEmits<AvatarImageEmits>()
 
-const { src, referrerPolicy } = toRefs(props)
+const { src, referrerPolicy, crossOrigin } = toRefs(props)
 useForwardExpose()
 const rootContext = injectAvatarRootContext()
 
-const imageLoadingStatus = useImageLoadingStatus(src, referrerPolicy)
+const imageLoadingStatus = useImageLoadingStatus(src, { referrerPolicy, crossOrigin })
 
 watch(
   imageLoadingStatus,
diff --git a/packages/core/src/Avatar/AvatarRoot.vue b/packages/core/src/Avatar/AvatarRoot.vue
@@ -25,7 +25,7 @@ withDefaults(defineProps<AvatarRootProps>(), {
 useForwardExpose()
 
 provideAvatarRootContext({
-  imageLoadingStatus: ref<ImageLoadingStatus>('loading'),
+  imageLoadingStatus: ref<ImageLoadingStatus>('idle'),
 })
 </script>
 
diff --git a/packages/core/src/Avatar/utils.ts b/packages/core/src/Avatar/utils.ts
@@ -1,11 +1,35 @@
 import type { ImgHTMLAttributes, Ref } from 'vue'
-import { onMounted, onUnmounted, ref, watch } from 'vue'
+import { computed, onMounted, onUnmounted, ref, watchEffect } from 'vue'
 
 export type ImageLoadingStatus = 'idle' | 'loading' | 'loaded' | 'error'
 
-export function useImageLoadingStatus(src: Ref<string>, referrerPolicy?: Ref<ImgHTMLAttributes['referrerpolicy']>) {
-  const loadingStatus = ref<ImageLoadingStatus>('idle')
+function resolveLoadingStatus(image: HTMLImageElement | null, src?: string): ImageLoadingStatus {
+  if (!image) {
+    return 'idle'
+  }
+  if (!src) {
+    return 'error'
+  }
+  if (image.src !== src) {
+    image.src = src
+  }
+  return image.complete && image.naturalWidth > 0 ? 'loaded' : 'loading'
+}
+
+export function useImageLoadingStatus(src: Ref<string>, { referrerPolicy, crossOrigin }: { referrerPolicy?: Ref<ImgHTMLAttributes['referrerpolicy']>, crossOrigin?: Ref<ImgHTMLAttributes['crossorigin']> } = {}) {
   const isMounted = ref(false)
+  const imageRef = ref<HTMLImageElement | null>(null)
+  const image = computed(() => {
+    if (!isMounted.value) {
+      return null
+    }
+    if (!imageRef.value) {
+      imageRef.value = new window.Image()
+    }
+    return imageRef.value
+  })
+
+  const loadingStatus = ref<ImageLoadingStatus>(resolveLoadingStatus(image.value, src.value))
 
   const updateStatus = (status: ImageLoadingStatus) => () => {
     if (isMounted.value)
@@ -15,21 +39,29 @@ export function useImageLoadingStatus(src: Ref<string>, referrerPolicy?: Ref<Img
   onMounted(() => {
     isMounted.value = true
 
-    watch([() => src.value, () => referrerPolicy?.value], ([src, referrer]) => {
-      if (!src) {
-        loadingStatus.value = 'error'
-      }
-      else {
-        const image = new window.Image()
-        loadingStatus.value = 'loading'
-        image.onload = updateStatus('loaded')
-        image.onerror = updateStatus('error')
-        image.src = src
-        if (referrer) {
-          image.referrerPolicy = referrer
-        }
-      }
-    }, { immediate: true })
+    watchEffect((onCleanup) => {
+      const img = image.value
+      if (!img)
+        return
+
+      loadingStatus.value = resolveLoadingStatus(img, src.value)
+
+      const handleLoad = updateStatus('loaded')
+      const handleError = updateStatus('error')
+
+      img.addEventListener('load', handleLoad)
+      img.addEventListener('error', handleError)
+
+      if (referrerPolicy?.value)
+        img.referrerPolicy = referrerPolicy.value
+      if (typeof crossOrigin?.value === 'string')
+        img.crossOrigin = crossOrigin.value
+
+      onCleanup(() => {
+        img.removeEventListener('load', handleLoad)
+        img.removeEventListener('error', handleError)
+      })
+    })
   })
 
   onUnmounted(() => {
diff --git a/packages/core/src/Combobox/story/ComboboxCancel.story.vue b/packages/core/src/Combobox/story/ComboboxCancel.story.vue
@@ -1,7 +1,7 @@
 <script setup lang="ts">
+import { Icon } from '@iconify/vue'
 import { ref } from 'vue'
 import { ComboboxAnchor, ComboboxCancel, ComboboxContent, ComboboxEmpty, ComboboxGroup, ComboboxInput, ComboboxItem, ComboboxItemIndicator, ComboboxLabel, ComboboxRoot, ComboboxSeparator, ComboboxTrigger, ComboboxViewport } from '..'
-import { Icon } from '@iconify/vue'
 
 const modelValue = ref('Banana')
 
