fix: support onLoadingComplete in modern next/image shim

packages/vinext/src/shims/image.tsx

@@ -107,6 +107,8 @@ interface ImageProps {
   className?: string;
   style?: React.CSSProperties;
   onLoad?: React.ReactEventHandler<HTMLImageElement>;
+  /** @deprecated Use onLoad instead. Still supported for migration compat. */
+  onLoadingComplete?: (img: HTMLImageElement) => void;
   onError?: React.ReactEventHandler<HTMLImageElement>;
   onClick?: React.MouseEventHandler<HTMLImageElement>;
   id?: string;
@@ -197,13 +199,24 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
     sizes,
     className,
     style,
+    onLoad,
+    onLoadingComplete,
     unoptimized: _unoptimized,
     overrideSrc: _overrideSrc,
     loading,
     ...rest
   },
   ref,
 ) {
+  // Wire onLoadingComplete (deprecated) into onLoad — matches Next.js behavior.
+  // onLoad fires first, then onLoadingComplete receives the HTMLImageElement.
+  const handleLoad = onLoadingComplete
+    ? (e: React.SyntheticEvent<HTMLImageElement>) => {
+        onLoad?.(e);
+        onLoadingComplete(e.currentTarget);
+      }
+    : onLoad;
+
   // Handle StaticImageData (import result)
   const src = typeof srcProp === "string" ? srcProp : srcProp.src;
   const imgWidth = width ?? (typeof srcProp === "object" ? srcProp.width : undefined);
@@ -225,6 +238,7 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
         decoding="async"
         sizes={sizes}
         className={className}
+        onLoad={handleLoad}
         style={
           fill
             ? {
@@ -269,6 +283,7 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
           sizes={sizes}
           className={className}
           background={bg}
+          onLoad={handleLoad}
         />
       );
     }
@@ -285,6 +300,7 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
           sizes={sizes}
           className={className}
           background={bg}
+          onLoad={handleLoad}
         />
       );
     }
@@ -350,6 +366,7 @@ const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
       sizes={sizes ?? (fill ? "100vw" : undefined)}
       className={className}
       data-nimg={fill ? "fill" : "1"}
+      onLoad={handleLoad}
       style={
         fill
           ? {
@@ -389,6 +406,8 @@ export function getImageProps(props: ImageProps): {
     sizes,
     className,
     style,
+    onLoad: _onLoad,
+    onLoadingComplete: _onLoadingComplete,
     unoptimized: _unoptimized,
     overrideSrc: _overrideSrc,
     loading,

packages/vinext/src/shims/next-shims.d.ts

@@ -155,6 +155,8 @@ declare module "next/image" {
     className?: string;
     style?: CSSProperties;
     onLoad?: ReactEventHandler<HTMLImageElement>;
+    /** @deprecated Use onLoad instead. Still supported for migration compat. */
+    onLoadingComplete?: (img: HTMLImageElement) => void;
     onError?: ReactEventHandler<HTMLImageElement>;
     onClick?: MouseEventHandler<HTMLImageElement>;
     id?: string;

tests/image-component.test.ts

@@ -477,3 +477,81 @@ describe("blurDataURL CSS injection prevention", () => {
     expect(html).toContain(validURL);
   });
 });
+
+// ─── onLoadingComplete (deprecated but supported) ────────────────────────
+// Next.js deprecated onLoadingComplete in v14 but still supports it.
+// It should be handled internally and NOT leak through to the returned props.
+
+describe("onLoadingComplete prop", () => {
+  it("getImageProps does not leak onLoadingComplete into returned props", () => {
+    const { props } = getImageProps({
+      alt: "test",
+      src: "/photo.jpg",
+      width: 400,
+      height: 300,
+      onLoadingComplete: () => {},
+    });
+    // onLoadingComplete must be consumed internally, not passed through
+    expect((props as any).onLoadingComplete).toBeUndefined();
+  });
+
+  it("getImageProps does not leak onLoad or onLoadingComplete when both provided", () => {
+    const { props } = getImageProps({
+      alt: "test",
+      src: "/photo.jpg",
+      width: 400,
+      height: 300,
+      onLoad: () => {},
+      onLoadingComplete: () => {},
+    });
+    expect((props as any).onLoadingComplete).toBeUndefined();
+    expect((props as any).onLoad).toBeUndefined();
+  });
+
+  it("does not leak onLoadingComplete as a DOM attribute in SSR (local image)", () => {
+    const html = ReactDOMServer.renderToString(
+      React.createElement(Image, {
+        alt: "test",
+        src: "/photo.jpg",
+        width: 400,
+        height: 300,
+        onLoadingComplete: () => {},
+      }),
+    );
+    expect(html).not.toContain("onLoadingComplete");
+    expect(html).not.toContain("onloadingcomplete");
+    expect(html).toContain('alt="test"');
+  });
+
+  it("does not leak onLoadingComplete as a DOM attribute in SSR (custom loader)", () => {
+    const html = ReactDOMServer.renderToString(
+      React.createElement(Image, {
+        alt: "cdn",
+        src: "/photo.jpg",
+        width: 200,
+        height: 150,
+        loader: ({ src, width }: { src: string; width: number }) =>
+          `https://cdn.example.com${src}?w=${width}`,
+        onLoadingComplete: () => {},
+      }),
+    );
+    expect(html).not.toContain("onLoadingComplete");
+    expect(html).not.toContain("onloadingcomplete");
+    expect(html).toContain('alt="cdn"');
+  });
+
+  it("does not leak onLoadingComplete as a DOM attribute in SSR (remote URL)", () => {
+    const html = ReactDOMServer.renderToString(
+      React.createElement(Image, {
+        alt: "remote",
+        src: "https://example.com/photo.jpg",
+        width: 400,
+        height: 300,
+        onLoadingComplete: () => {},
+      }),
+    );
+    expect(html).not.toContain("onLoadingComplete");
+    expect(html).not.toContain("onloadingcomplete");
+    expect(html).toContain('alt="remote"');
+  });
+});