@grapu-design/react-image 0.1.1

package/lib/index.js

@@ -0,0 +1,11 @@
+import { I as ImageContent, a as ImageFallback, b as ImageRoot } from './Image-12s-SR1fYJF4.js';
+export { u as useImage, c as useImageContext } from './Image-12s-SR1fYJF4.js';
+
+var Image_namespace = {
+  __proto__: null,
+  Content: ImageContent,
+  Fallback: ImageFallback,
+  Root: ImageRoot
+};
+
+export { Image_namespace as Image, ImageContent, ImageFallback, ImageRoot };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@grapu-design/react-image",
+  "version": "0.1.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/grapu-design/designsystem.git",
+    "directory": "packages/react-headless/image"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./lib/index.cjs",
+  "files": [
+    "lib",
+    "src"
+  ],
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build": "bunchee",
+    "lint:publish": "bun publint"
+  },
+  "dependencies": {
+    "@radix-ui/react-compose-refs": "^1.1.2",
+    "@radix-ui/react-use-callback-ref": "^1.1.1",
+    "@radix-ui/react-use-layout-effect": "^1.1.1",
+    "@grapu-design/dom-utils": "^0.1.0",
+    "@grapu-design/react-primitive": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/react": "^19.1.6",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/Image.namespace.ts

@@ -0,0 +1,8 @@
+export {
+  ImageRoot as Root,
+  ImageContent as Content,
+  ImageFallback as Fallback,
+  type ImageRootProps as RootProps,
+  type ImageContentProps as ContentProps,
+  type ImageFallbackProps as FallbackProps,
+} from "./Image";

package/src/Image.tsx

@@ -0,0 +1,71 @@
+"use client";
+
+import { composeRefs } from "@radix-ui/react-compose-refs";
+import { useLayoutEffect } from "@radix-ui/react-use-layout-effect";
+import { mergeProps } from "@grapu-design/dom-utils";
+import { Primitive, type PrimitiveProps } from "@grapu-design/react-primitive";
+import type * as React from "react";
+import { forwardRef } from "react";
+import { useImage, type UseImageProps } from "./useImage";
+import { ImageProvider, useImageContext } from "./useImageContext";
+
+export interface ImageRootProps
+  extends UseImageProps,
+    PrimitiveProps,
+    React.HTMLAttributes<HTMLDivElement> {}
+
+export const ImageRoot = forwardRef<HTMLDivElement, ImageRootProps>((props, ref) => {
+  const { onLoadingStatusChange, ...otherProps } = props;
+  const api = useImage({ onLoadingStatusChange });
+  return (
+    <ImageProvider value={api}>
+      <Primitive.div ref={ref} {...mergeProps(api.rootProps, otherProps)} />
+    </ImageProvider>
+  );
+});
+ImageRoot.displayName = "ImageRoot";
+
+export interface ImageContentProps
+  extends PrimitiveProps,
+    React.ImgHTMLAttributes<HTMLImageElement> {}
+
+export const ImageContent = forwardRef<HTMLImageElement, ImageContentProps>((props, ref) => {
+  const { src, onLoad, onError, ...otherProps } = props;
+
+  const { refs, setSrc, getContentProps, handleLoad, handleError } = useImageContext();
+
+  useLayoutEffect(() => {
+    setSrc(src);
+  }, [src, setSrc]);
+
+  const contentProps = getContentProps({ src });
+
+  return (
+    <Primitive.img
+      ref={composeRefs(refs.image, ref)}
+      {...mergeProps(contentProps, otherProps, {
+        // if loading is lazy, we should not hide the image even if it's not loaded yet,
+        // because the browser should be able to check if it's in the viewport.
+        // TODO: it should be better than this; why doesn't useImage properly handle this case?
+        hidden: otherProps.loading === "lazy" ? false : contentProps.hidden,
+      })}
+      onLoad={(e) => {
+        handleLoad();
+        onLoad?.(e);
+      }}
+      onError={(e) => {
+        handleError();
+        onError?.(e);
+      }}
+    />
+  );
+});
+ImageContent.displayName = "ImageContent";
+
+export interface ImageFallbackProps extends PrimitiveProps, React.HTMLAttributes<HTMLDivElement> {}
+
+export const ImageFallback = forwardRef<HTMLDivElement, ImageFallbackProps>((props, ref) => {
+  const { fallbackProps } = useImageContext();
+  return <Primitive.div ref={ref} {...mergeProps(fallbackProps, props)} />;
+});
+ImageFallback.displayName = "ImageFallback";

package/src/index.ts

@@ -0,0 +1,19 @@
+export {
+  ImageRoot,
+  ImageContent,
+  ImageFallback,
+  type ImageRootProps,
+  type ImageContentProps,
+  type ImageFallbackProps,
+} from "./Image";
+
+export { useImageContext, type UseImageContext } from "./useImageContext";
+
+export {
+  useImage,
+  type UseImageProps,
+  type UseImageReturn,
+  type ImageLoadingStatus,
+} from "./useImage";
+
+export * as Image from "./Image.namespace";

package/src/useImage.test.tsx

@@ -0,0 +1,48 @@
+import { render } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "bun:test";
+
+import type { ReactElement } from "react";
+
+import { useImage, type UseImageProps } from "./useImage";
+
+const ROOT_TEST_ID = "image-root";
+const FALLBACK_TEXT = "AB";
+const IMAGE_ALT_TEXT = "Fake Image";
+
+function setUp(jsx: ReactElement) {
+  return {
+    user: userEvent.setup(),
+    ...render(jsx),
+  };
+}
+
+function Image(props: UseImageProps) {
+  const { rootProps, getContentProps, fallbackProps } = useImage(props);
+  return (
+    <div data-testid={ROOT_TEST_ID} {...rootProps}>
+      <img {...getContentProps({})} alt={IMAGE_ALT_TEXT} />
+      <span {...fallbackProps}>{FALLBACK_TEXT}</span>
+    </div>
+  );
+}
+
+describe("useImage", () => {
+  it("initial state is loading", () => {
+    const { getByAltText } = setUp(<Image />);
+    const image = getByAltText(IMAGE_ALT_TEXT);
+    expect(image).toHaveAttribute("data-loading-state", "loading");
+  });
+
+  it("should not render the image initially", () => {
+    const { getByAltText } = setUp(<Image />);
+    const image = getByAltText(IMAGE_ALT_TEXT);
+    expect(image).not.toBeVisible();
+  });
+
+  it("should render the fallback initially", () => {
+    const { queryByText } = setUp(<Image />);
+    const fallback = queryByText(FALLBACK_TEXT);
+    expect(fallback).toBeVisible();
+  });
+});

package/src/useImage.ts

@@ -0,0 +1,101 @@
+import { useCallbackRef } from "@radix-ui/react-use-callback-ref";
+import { useLayoutEffect } from "@radix-ui/react-use-layout-effect";
+import { dataAttr, elementProps, imgProps } from "@grapu-design/dom-utils";
+import { useCallback, useMemo, useRef, useState } from "react";
+
+export type ImageLoadingStatus = "loading" | "loaded" | "error";
+
+export interface UseImageProps {
+  onLoadingStatusChange?: (status: ImageLoadingStatus) => void;
+}
+
+export type UseImageReturn = ReturnType<typeof useImage>;
+
+export function useImage(props: UseImageProps) {
+  const onLoadingStatusChange = useCallbackRef(props.onLoadingStatusChange);
+  const [loadingStatus, setLoadingStatus] = useState<ImageLoadingStatus>("loading");
+  const imageRef = useRef<HTMLImageElement>(null);
+
+  useLayoutEffect(() => {
+    if (imageRef.current) {
+      if (imageRef.current.complete) {
+        if (imageRef.current.naturalWidth === 0 || imageRef.current.naturalHeight === 0) {
+          setLoadingStatus("error");
+          onLoadingStatusChange?.("error");
+        } else {
+          setLoadingStatus("loaded");
+          onLoadingStatusChange?.("loaded");
+        }
+      }
+    }
+  }, [onLoadingStatusChange]);
+
+  const isLoaded = loadingStatus === "loaded";
+
+  const stateProps = useMemo(
+    () =>
+      elementProps({
+        "data-loading-state": loadingStatus,
+      }),
+    [loadingStatus],
+  );
+
+  const setSrc = useCallback(
+    (src: string | undefined) => {
+      if (src === undefined || src === null) {
+        setLoadingStatus("error");
+        onLoadingStatusChange?.("error");
+      } else {
+        setLoadingStatus("loading");
+        onLoadingStatusChange?.("loading");
+      }
+    },
+    [onLoadingStatusChange],
+  );
+
+  const getContentProps = useCallback(
+    ({ src }: { src?: string }) => {
+      return imgProps({
+        hidden: !isLoaded,
+        "data-visible": dataAttr(isLoaded),
+        src,
+        ...stateProps,
+      });
+    },
+    [isLoaded, stateProps],
+  );
+
+  const handleLoad = useCallback(() => {
+    setLoadingStatus("loaded");
+    onLoadingStatusChange?.("loaded");
+  }, [onLoadingStatusChange]);
+
+  const handleError = useCallback(() => {
+    setLoadingStatus("error");
+    onLoadingStatusChange?.("error");
+  }, [onLoadingStatusChange]);
+
+  const fallbackProps = useMemo(
+    () =>
+      elementProps({
+        hidden: isLoaded,
+        "data-visible": dataAttr(!isLoaded),
+        ...stateProps,
+      }),
+    [isLoaded, stateProps],
+  );
+
+  return {
+    refs: {
+      image: imageRef,
+    },
+    loadingStatus,
+    stateProps,
+    rootProps: stateProps,
+    setSrc,
+    getContentProps,
+    handleLoad,
+    handleError,
+    fallbackProps,
+  };
+}

package/src/useImageContext.tsx

@@ -0,0 +1,17 @@
+import { createContext, useContext } from "react";
+import type { UseImageReturn } from "./useImage";
+
+export interface UseImageContext extends UseImageReturn {}
+
+const ImageContext = createContext<UseImageContext | null>(null);
+
+export const ImageProvider = ImageContext.Provider;
+
+export function useImageContext({ strict = true }: { strict?: boolean } = {}): UseImageContext {
+  const context = useContext(ImageContext);
+  if (!context && strict) {
+    throw new Error("useImageContext must be used within an Image");
+  }
+
+  return context as UseImageContext;
+}