Image component and magnified image

package.json

@@ -52,7 +52,8 @@
     "@fontsource-variable/inter": "^5.2.8",
     "@mui/icons-material": "^7.0.0",
     "react-icons": "^5.3.0",
-    "utif": "^3.1.0"
+    "utif": "^3.1.0",
+    "@mui/icons-material": "^7.0.0"
   },
   "peerDependencies": {
     "@emotion/react": "^11.13.3",

src/components/controls/Image.stories.tsx

@@ -0,0 +1,42 @@
+import { Meta, StoryObj } from "@storybook/react";
+import { Image } from "./Image";
+
+import diamond from "../../public/images/diamond.jpg";
+
+const meta: Meta<typeof Image> = {
+  title: "Components/Controls/Image",
+  component: Image,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: "Image with placeholder, fallback and loading indicator",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const BasicImage: Story = {
+  args: { src: diamond, style: { width: "20vw" } },
+  parameters: {
+    docs: {
+      description: {
+        story: "Basic Image",
+      },
+    },
+  },
+};
+
+export const ErrorImage: Story = {
+  args: { src: "doesnotexist.jpg", style: { width: "20vw" } },
+  parameters: {
+    docs: {
+      description: {
+        story: "Image displayed when original image fails to load",
+      },
+    },
+  },
+};

src/components/controls/Image.test.tsx

@@ -0,0 +1,27 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { Image } from "./Image";
+
+import placeholderStaticImport from "../../public/images/diamond.jpg";
+
+describe("Image", () => {
+  it("should render spinner while image isn't loaded", () => {
+    render(<Image src={placeholderStaticImport} alt={"foo"} />);
+
+    const image = screen.getByAltText("foo");
+
+    expect(image).toHaveAttribute("aria-busy", "true");
+
+    fireEvent.load(image);
+
+    expect(image).toHaveAttribute("aria-busy", "false");
+  });
+
+  it("should render placeholder image if an error occurs while loading image", () => {
+    render(<Image src={placeholderStaticImport} alt={"foo"} />);
+
+    const image = screen.getByAltText("foo");
+    fireEvent.error(image);
+
+    expect(image).toHaveAttribute("aria-errormessage", "Image not available");
+  });
+});

src/components/controls/Image.tsx

@@ -0,0 +1,87 @@
+"use client";
+import {
+  DetailedHTMLProps,
+  ImgHTMLAttributes,
+  SyntheticEvent,
+  useState,
+} from "react";
+import placeholder from "../../public/generic/no-image.png";
+import CircularProgress from "@mui/material/CircularProgress";
+import Box from "@mui/material/Box";
+
+export interface ImageProps
+  extends Omit<
+    Omit<
+      DetailedHTMLProps<ImgHTMLAttributes<HTMLImageElement>, HTMLImageElement>,
+      "onLoad" | "onError"
+    >,
+    "src"
+  > {
+  src?: string | null;
+  onLoad?: () => void;
+  onError?: () => void;
+}
+
+/**
+ * Smart image component that displays a placeholder on error, and a loading indicator if the image is still loading
+ */
+export const Image = ({ src, alt, onLoad, onError, ...props }: ImageProps) => {
+  const [isLoading, setIsLoading] = useState(true);
+  const [isError, setIsError] = useState(false);
+
+  const handleError = (e: SyntheticEvent<HTMLImageElement>) => {
+    if (onError) {
+      onError();
+    }
+
+    e.currentTarget.src = placeholder;
+    setIsError(true);
+  };
+
+  const handleLoad = () => {
+    if (onLoad) {
+      onLoad();
+    }
+
+    setIsLoading(false);
+  };
+
+  return (
+    <Box
+      display="flex"
+      alignItems="center"
+      justifyContent="center"
+      width={props.style?.width}
+      height={props.style?.height}
+    >
+      {isLoading && (
+        <Box
+          display="flex"
+          width={props.style?.width}
+          paddingY="3em"
+          justifyContent="center"
+          alignItems="center"
+        >
+          <CircularProgress />
+        </Box>
+      )}
+      <img
+        aria-busy={isLoading}
+        src={src ?? placeholder}
+        aria-errormessage={isError ? "Image not available" : undefined}
+        onError={handleError}
+        onLoad={handleLoad}
+        alt={alt ?? "Placeholder Image"}
+        {...props}
+        style={{
+          width: "100%",
+          height: "auto",
+          maxHeight: "100%",
+          objectFit: "contain",
+          display: isLoading ? "none" : "block",
+          ...props.style,
+        }}
+      />
+    </Box>
+  );
+};

src/components/controls/ImageWithZoom.stories.tsx

@@ -0,0 +1,42 @@
+import { Meta, StoryObj } from "@storybook/react";
+import { ImageWithZoom } from "./ImageWithZoom";
+
+import diamond from "../../public/images/diamond.jpg";
+
+const meta: Meta<typeof ImageWithZoom> = {
+  title: "Components/Controls/ImageWithZoom",
+  component: ImageWithZoom,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: "Image with user-controlled magnified area",
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const BasicImage: Story = {
+  args: { src: diamond, alt: "Diamond" },
+  parameters: {
+    docs: {
+      description: {
+        story: "Basic image with magnified view on side",
+      },
+    },
+  },
+};
+
+export const Brightness: Story = {
+  args: { src: diamond, alt: "Diamond", brightness: 0.5 },
+  parameters: {
+    docs: {
+      description: {
+        story: "Image with brightness filter applied",
+      },
+    },
+  },
+};

src/components/controls/ImageWithZoom.test.tsx

@@ -0,0 +1,68 @@
+import { ImageWithZoom } from "./ImageWithZoom";
+import { render, screen } from "@testing-library/react";
+
+/**
+ * This is particularly hard to test without visual testing (screenshot matching)
+ * With unit tests, refs don't work properly, nor is it particularly useful because there might be visual changes,
+ * but CSS remains the same. We should revisit this once we implement visual matching through Playwright/Vitest browser mode.
+ */
+
+vi.mock("./Image", () => ({
+  Image: ({
+    onLoad,
+    alt,
+    src,
+    onClick,
+  }: {
+    onClick?: (e: Record<string, unknown>) => void;
+    onLoad?: () => void;
+    alt: string;
+    src: string;
+  }) => {
+    if (onLoad) {
+      onLoad();
+    }
+    if (onClick) {
+      onClick({
+        currentTarget: {
+          getBoundingClientRect: () => ({
+            left: 0,
+            top: 0,
+            width: 100,
+            height: 100,
+          }),
+        },
+      });
+    }
+    return <img alt={alt} src={src} />;
+  },
+}));
+
+describe("Image with Zoom Viewer", () => {
+  it("should update brightness/contrast", () => {
+    render(
+      <ImageWithZoom src="foo.jpg" alt="foo" brightness={1.5} contrast={0.5} />,
+    );
+
+    // https://github.com/vitest-dev/vitest/issues/9797
+    const zoomView = screen.getByLabelText("Zoom View");
+    expect(zoomView).toHaveAttribute(
+      "style",
+      expect.stringContaining("brightness(1.5)"),
+    );
+    expect(zoomView).toHaveAttribute(
+      "style",
+      expect.stringContaining("contrast(0.5)"),
+    );
+  });
+
+  it("should update image colour inversion", () => {
+    render(<ImageWithZoom src="foo.jpg" alt="foo" invert={true} />);
+
+    const zoomView = screen.getByLabelText("Zoom View");
+    expect(zoomView).toHaveAttribute(
+      "style",
+      expect.stringContaining("invert(1)"),
+    );
+  });
+});