fix fallback flash when image is cached

Author: mj12albert

packages/react/src/avatar/image/AvatarImage.test.tsx

@@ -1,26 +1,61 @@
-import { Mock, vi, expect } from 'vitest';
+import { expect } from 'vitest';
 import * as React from 'react';
 import { Avatar } from '@base-ui/react/avatar';
 import { screen, waitFor } from '@mui/internal-test-utils';
 import { describeConformance, createRenderer, isJSDOM } from '#test-utils';
-import { useImageLoadingStatus } from './useImageLoadingStatus';
 
-vi.mock('./useImageLoadingStatus');
+/**
+ * Replaces `window.Image` with a constructor that simulates a browser's
+ * cached-image behavior: setting `.src` immediately makes `.complete = true`
+ * and `.naturalWidth > 0`, but the async `onload` callback has not yet fired
+ * (it would be queued as a task in a real browser).
+ *
+ * This is the exact state the fix targets — without the `image.complete`
+ * fast-path, the hook would be stuck at `'loading'` until `onload` fires.
+ */
+function mockCachedImageLoading({ naturalWidth = 100 } = {}) {
+  const OriginalImage = window.Image;
+
+  window.Image = function MockImage() {
+    let srcValue = '';
+    const obj = {
+      complete: false,
+      naturalWidth: 0,
+      onload: null as (() => void) | null,
+      onerror: null as (() => void) | null,
+      referrerPolicy: '',
+      crossOrigin: null as string | null,
+      get src() {
+        return srcValue;
+      },
+      set src(value: string) {
+        srcValue = value;
+        obj.complete = true;
+        obj.naturalWidth = naturalWidth;
+      },
+    };
+    return obj;
+  } as unknown as typeof window.Image;
+
+  return () => {
+    window.Image = OriginalImage;
+  };
+}
 
 describe('<Avatar.Image />', () => {
   const { render } = createRenderer();
 
-  const useImageLoadingStatusMock = useImageLoadingStatus as Mock;
+  let restoreImage: () => void;
 
   beforeEach(() => {
-    useImageLoadingStatusMock.mockReturnValue('loaded');
+    restoreImage = mockCachedImageLoading();
   });
 
   afterEach(() => {
-    vi.clearAllMocks();
+    restoreImage();
   });
 
-  describeConformance(<Avatar.Image />, () => ({
+  describeConformance(<Avatar.Image src="test.png" />, () => ({
     render: (node) => {
       return render(<Avatar.Root>{node}</Avatar.Root>);
     },
@@ -35,8 +70,6 @@ describe('<Avatar.Image />', () => {
     it('triggers enter animation via data-starting-style when mounting', async () => {
       globalThis.BASE_UI_ANIMATIONS_DISABLED = false;
 
-      useImageLoadingStatusMock.mockImplementation((src) => (src ? 'loaded' : 'idle'));
-
       let transitionFinished = false;
       function notifyTransitionFinished() {
         transitionFinished = true;
@@ -92,8 +125,6 @@ describe('<Avatar.Image />', () => {
     it('applies data-ending-style before unmount', async () => {
       globalThis.BASE_UI_ANIMATIONS_DISABLED = false;
 
-      useImageLoadingStatusMock.mockImplementation((src) => (src ? 'loaded' : 'idle'));
-
       const style = `
         @keyframes test-anim {
           to {
@@ -145,4 +176,80 @@ describe('<Avatar.Image />', () => {
       });
     });
   });
+
+  describe.skipIf(isJSDOM)('cached images', () => {
+    // 1x1 transparent PNG
+    const DATA_URI =
+      'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==';
+
+    it('shows the image for a pre-loaded src', async () => {
+      // Restore real Image so this test exercises actual browser caching
+      restoreImage();
+
+      // Pre-load so the browser cache has the decoded image
+      await new Promise<void>((resolve, reject) => {
+        const img = new window.Image();
+        img.onload = () => resolve();
+        img.onerror = () => reject(new Error('Failed to preload test image'));
+        img.src = DATA_URI;
+      });
+
+      await render(
+        <Avatar.Root>
+          <Avatar.Image src={DATA_URI} alt="Jane Doe" />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar.Root>,
+      );
+
+      expect(screen.getByRole('img')).toHaveAttribute('src', DATA_URI);
+      expect(screen.queryByText('JD')).toBe(null);
+    });
+
+    it('shows the fallback for an invalid src', async () => {
+      // Restore real Image so this test exercises actual browser behavior
+      restoreImage();
+
+      await render(
+        <Avatar.Root>
+          <Avatar.Image src="data:image/png;base64,invalid" alt="Jane Doe" />
+          <Avatar.Fallback>JD</Avatar.Fallback>
+        </Avatar.Root>,
+      );
+
+      await waitFor(() => {
+        expect(screen.queryByRole('img')).toBe(null);
+        expect(screen.getByText('JD')).toBeVisible();
+      });
+    });
+  });
+
+  it.skipIf(!isJSDOM)('shows the image immediately for a cached src', async () => {
+    await render(
+      <Avatar.Root>
+        <Avatar.Image src="https://example.com/cached-avatar.png" alt="Jane Doe" />
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    expect(screen.getByRole('img')).toHaveAttribute(
+      'src',
+      'https://example.com/cached-avatar.png',
+    );
+    expect(screen.queryByText('JD')).toBe(null);
+  });
+
+  it.skipIf(!isJSDOM)('shows the fallback for a cached broken image', async () => {
+    restoreImage();
+    restoreImage = mockCachedImageLoading({ naturalWidth: 0 });
+
+    await render(
+      <Avatar.Root>
+        <Avatar.Image src="https://example.com/broken.png" alt="Jane Doe" />
+        <Avatar.Fallback>JD</Avatar.Fallback>
+      </Avatar.Root>,
+    );
+
+    expect(screen.queryByRole('img')).toBe(null);
+    expect(screen.getByText('JD')).toBeVisible();
+  });
 });

packages/react/src/avatar/image/useImageLoadingStatus.ts

@@ -42,6 +42,11 @@ export function useImageLoadingStatus(
     image.crossOrigin = crossOrigin ?? null;
     image.src = src;
 
+    // Fast path for cached/decoded images
+    if (image.complete) {
+      setLoadingStatus(image.naturalWidth > 0 ? 'loaded' : 'error');
+    }
+
     return () => {
       isMounted = false;
     };