Only auto-load a file field when the ref is a genuinely loaded img (#267)

`useCwaFile`'s mount-time "already loaded" shortcut read:

    if (ops.imageRef.value?.complete || ops.imageRef.value?.naturalHeight !== 0)

The ref is not always a bare <img>. `ref="file"` on a COMPONENT — as the
playground's Image.vue does with <NuxtImg ref="file"> — resolves to the
component instance, not the element. A ref name that doesn't match
`fileProp` resolves to null. And a file field needn't be an image at all.

In every one of those cases `naturalHeight` is `undefined`, and
`undefined !== 0` is TRUE, so `handleLoad()` fired on mount and `loaded`
was true from the start — defeating the whole load-detection mechanism.
Visibly, the placeholder vanished instantly and the image popped in
unfaded, because nothing was waiting for @load.

Unwrap a component instance to its root element, and only apply the
heuristic to something that can actually report img load state. Anything
else waits for @load, which still fires normally.

This is section 3 of #267. The `Cannot redefine property` crash and the
implicit-useTemplateRef design question are separate and remain open.

The existing `complete || naturalHeight !== 0` heuristic is deliberately
left as-is rather than re-litigated here — the fix is scoped to what the
ref resolves to, not to how a loaded img is recognised.

Author: silverbackdan

src/runtime/composables/cwa-file.spec.ts

@@ -137,5 +137,43 @@ describe('useCwaFile', () => {
       const { loaded } = useCwaFile(iri, ops)
       expect(loaded.value).toBe(false)
     })
+
+    /**
+     * The ref is not always a bare `<img>`. `ref="file"` on a COMPONENT (`<NuxtImg ref="file">`, as
+     * the playground uses) resolves to the component instance; a ref name that doesn't match
+     * `fileProp` resolves to null; a file field needn't be an image at all.
+     *
+     * In every one of those cases `naturalHeight` is `undefined`, and `undefined !== 0` is TRUE — so
+     * `loaded` flipped true on mount, before the image had loaded, and the placeholder vanished
+     * instantly. Anything we cannot positively identify as a loaded <img> must wait for `@load`.
+     */
+    describe('when the ref is not a bare img element', () => {
+      test('resolves a component instance to its root element and respects its load state', () => {
+        // <NuxtImg ref="file"> — useTemplateRef gives the component, whose $el is the real <img>
+        const component = { $el: { complete: false, naturalHeight: 0 } }
+        const ops = makeOps({ imageRef: ref(component as any) })
+        const { loaded } = useCwaFile(iri, ops)
+        expect(loaded.value).toBe(false)
+      })
+
+      test('a component instance whose image is already loaded still auto-loads', () => {
+        const component = { $el: { complete: true, naturalHeight: 100 } }
+        const ops = makeOps({ imageRef: ref(component as any) })
+        const { loaded } = useCwaFile(iri, ops)
+        expect(loaded.value).toBe(true)
+      })
+
+      test('does not auto-load when the ref is missing (e.g. ref name does not match fileProp)', () => {
+        const ops = makeOps({ imageRef: ref(null) as any })
+        const { loaded } = useCwaFile(iri, ops)
+        expect(loaded.value).toBe(false)
+      })
+
+      test('does not auto-load when the ref is a non-image element', () => {
+        const ops = makeOps({ imageRef: ref({ tagName: 'DIV' } as any) })
+        const { loaded } = useCwaFile(iri, ops)
+        expect(loaded.value).toBe(false)
+      })
+    })
   })
 })

src/runtime/composables/cwa-file.ts

@@ -60,8 +60,21 @@ export const useCwaFile = (iri: Ref<string>, ops: FileOpsType): CwaFileReturnTyp
     return `${mediaUrl}${query.value}`
   })
 
+  // An <img> that was already loaded (from cache) before the `@load` listener was attached never
+  // fires it, so detect that on mount. The ref is not necessarily a bare <img> though: `ref="file"`
+  // on a COMPONENT (`<NuxtImg ref="file">`) resolves to the component instance, a ref name that
+  // doesn't match `fileProp` resolves to null, and a file field needn't be an image at all. In each
+  // of those `naturalHeight` is `undefined` — and `undefined !== 0` is TRUE, which flipped `loaded`
+  // on mount before the image had loaded and made the placeholder vanish instantly.
   onMounted(() => {
-    if (ops.imageRef.value?.complete || ops.imageRef.value?.naturalHeight !== 0) {
+    const target = ops.imageRef.value as { $el?: unknown } | null
+    // unwrap a component instance to its root element
+    const el = (target && '$el' in target ? target.$el : target) as HTMLImageElement | null
+    // Only an <img> can report its own load state. Anything else must wait for `@load`.
+    if (!el || typeof el.naturalHeight !== 'number') {
+      return
+    }
+    if (el.complete || el.naturalHeight !== 0) {
       handleLoad()
     }
   })