jazz-tools 0.16.6 → 0.17.1

package/src/media/utils.ts

@@ -0,0 +1,205 @@
+import type { CoID } from "cojson";
+import { Account, FileStream, ImageDefinition } from "jazz-tools";
+
+export function highestResAvailable(
+  image: ImageDefinition,
+  wantedWidth: number,
+  wantedHeight: number,
+): { width: number; height: number; image: FileStream } | null {
+  const availableSizes: [number, number, string][] = image._raw
+    .keys()
+    .filter((key) => /^\d+x\d+$/.test(key))
+    .map((key) => {
+      const [w, h] = key.split("x").map(Number) as [number, number];
+      return [w, h, key];
+    });
+
+  if (availableSizes.length === 0) {
+    return image.original
+      ? {
+          width: image.originalSize[0],
+          height: image.originalSize[1],
+          image: image.original,
+        }
+      : null;
+  }
+
+  const sortedSizes = availableSizes
+    .map((size) => {
+      return {
+        size,
+        match: sizesMatchWanted(size[0], size[1], wantedWidth, wantedHeight),
+        isLoaded: isLoaded(image._raw.get(size[2]) as CoID<any> | undefined),
+      };
+    })
+    .sort((a, b) => a.match - b.match);
+
+  // We try to find the better already loaded image
+  // note: `toReversed` is not available in react-native.
+  const bestLoaded = [...sortedSizes]
+    .reverse()
+    .find((el) => el.isLoaded && image[el.size[2]]?.getChunks());
+
+  // if I can't find a good match, let's use the highest resolution
+  const bestTarget =
+    sortedSizes.find((el) => el.match > 0.95) || sortedSizes.at(-1);
+
+  // if the best target is already loaded, we are done
+  if (image[bestTarget!.size[2]]?.getChunks()) {
+    return image[bestTarget!.size[2]]
+      ? {
+          width: bestTarget!.size[0],
+          height: bestTarget!.size[1],
+          image: image[bestTarget!.size[2]]!,
+        }
+      : null;
+  }
+
+  // if the best already loaded is not the best target
+  // let's trigger the load of the best target
+  if (bestLoaded) {
+    image[bestTarget!.size[2]]?.getChunks();
+    return image[bestLoaded.size[2]]
+      ? {
+          width: bestLoaded.size[0],
+          height: bestLoaded.size[1],
+          image: image[bestLoaded.size[2]]!,
+        }
+      : null;
+  }
+
+  // if nothing is loaded, then start fetching all the images till the best
+  for (let size of sortedSizes) {
+    if (size.match <= bestTarget!.match) {
+      image[size.size[2]]?.getChunks();
+    }
+  }
+
+  return null;
+}
+
+function sizesMatchWanted(
+  w: number,
+  h: number,
+  wantedW: number,
+  wantedH: number,
+): number {
+  const area1 = w * h;
+  const area2 = wantedW * wantedH;
+
+  const areaRatio = area1 / area2;
+
+  // // Below 0.95 means the image is too small, we don't want to upscale it
+  // if (areaRatio < 0.95) {
+  //   return 9999;
+  // }
+
+  return areaRatio;
+}
+
+function isLoaded(id: CoID<any> | null | undefined): boolean {
+  if (!id) {
+    return false;
+  }
+
+  return !!Account.getMe()._raw.core.node.getLoaded(id);
+}
+
+export async function loadImage(
+  imageOrId: ImageDefinition | string,
+): Promise<{ width: number; height: number; image: FileStream } | null> {
+  if (typeof imageOrId === "string") {
+    const image = await ImageDefinition.load(imageOrId, {
+      resolve: {
+        original: true,
+      },
+    });
+
+    if (image === null || image.original === null) {
+      return null;
+    }
+
+    return {
+      width: image.originalSize[0],
+      height: image.originalSize[1],
+      image: image.original,
+    };
+  }
+
+  if (!imageOrId.original) {
+    console.warn("Unable to find the original image");
+    return null;
+  }
+
+  const loadedOriginal = await FileStream.load(imageOrId.original.id);
+
+  if (!loadedOriginal) {
+    console.warn("Unable to find the original image");
+    return null;
+  }
+
+  return {
+    width: imageOrId.originalSize[0],
+    height: imageOrId.originalSize[1],
+    image: loadedOriginal,
+  };
+}
+
+export async function loadImageBySize(
+  imageOrId: ImageDefinition | string,
+  wantedWidth: number,
+  wantedHeight: number,
+): Promise<{ width: number; height: number; image: FileStream } | null> {
+  const image: ImageDefinition | null =
+    typeof imageOrId === "string"
+      ? await ImageDefinition.load(imageOrId)
+      : imageOrId;
+
+  if (image === null) {
+    return null;
+  }
+
+  if (image.progressive === false) {
+    return loadImage(imageOrId);
+  }
+
+  const availableSizes: [number, number, string][] = image._raw
+    .keys()
+    .filter((key) => /^\d+x\d+$/.test(key))
+    .map((key) => {
+      const [w, h] = key.split("x").map(Number) as [number, number];
+      return [w, h, key];
+    });
+
+  if (availableSizes.length === 0) {
+    return null;
+  }
+
+  const sortedSizes = availableSizes
+    .map((size) => ({
+      size,
+      match: sizesMatchWanted(size[0], size[1], wantedWidth, wantedHeight),
+    }))
+    .sort((a, b) => a.match - b.match);
+
+  const bestTarget =
+    sortedSizes.find((el) => el.match > 0.95) || sortedSizes.at(-1)!;
+
+  const file = image[bestTarget.size[2]];
+
+  if (!file) {
+    return null;
+  }
+
+  const loadedFile = await FileStream.load(file.id);
+
+  if (!loadedFile) {
+    return null;
+  }
+
+  return {
+    width: bestTarget.size[0],
+    height: bestTarget.size[1],
+    image: loadedFile,
+  };
+}

package/src/react/index.ts

@@ -12,5 +12,4 @@ export {
 export { createInviteLink, parseInviteLink } from "jazz-tools/browser";
 
 export * from "./auth/auth.js";
-export * from "./media.js";
-export { createImage } from "jazz-tools/browser-media-images";
+export * from "./media/image.js";

package/src/react/media/image.tsx

@@ -0,0 +1,210 @@
+import { ImageDefinition } from "jazz-tools";
+import {
+  type JSX,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
+import { highestResAvailable } from "../../media/index.js";
+import { useCoState } from "../hooks.js";
+
+export type ImageProps = Omit<
+  JSX.IntrinsicElements["img"],
+  "src" | "srcSet" | "width" | "height"
+> & {
+  /** The ID of the ImageDefinition to display */
+  imageId: string;
+  /**
+   * The desired width of the image. Can be a number in pixels or "original" to use the image's original width.
+   * When set to a number, the component will select the best available resolution and maintain aspect ratio.
+   *
+   * @example
+   * ```tsx
+   * // Use original width
+   * <Image imageId="123" width="original" />
+   *
+   * // Set width to 600px, height will be calculated to maintain aspect ratio
+   * <Image imageId="123" width={600} />
+   *
+   * // Set both width and height to maintain aspect ratio
+   * <Image imageId="123" width={600} height={400} />
+   * ```
+   */
+  width?: number | "original";
+  /**
+   * The desired height of the image. Can be a number in pixels or "original" to use the image's original height.
+   * When set to a number, the component will select the best available resolution and maintain aspect ratio.
+   *
+   * @example
+   * ```tsx
+   * // Use original height
+   * <Image imageId="123" height="original" />
+   *
+   * // Set height to 400px, width will be calculated to maintain aspect ratio
+   * <Image imageId="123" height={400} />
+   *
+   * // Set both width and height to maintain aspect ratio
+   * <Image imageId="123" width={600} height={400} />
+   * ```
+   */
+  height?: number | "original";
+};
+
+/**
+ * A React component for displaying images stored as ImageDefinition CoValues.
+ *
+ * @example
+ * ```tsx
+ * import { Image } from "jazz-tools/react";
+ *
+ * // Force specific dimensions (may crop or stretch)
+ * function Avatar({ imageId }: { imageId: string }) {
+ *   return (
+ *     <Image
+ *       imageId={imageId}
+ *       width={100}
+ *       height={100}
+ *       alt="Avatar"
+ *       style={{ borderRadius: "50%", objectFit: "cover" }}
+ *     />
+ *   );
+ * }
+ * ```
+ */
+export const Image = forwardRef<HTMLImageElement, ImageProps>(function Image(
+  { imageId, width, height, ...props },
+  ref,
+) {
+  const image = useCoState(ImageDefinition, imageId);
+  const lastBestImage = useRef<[string, string] | null>(null);
+
+  /**
+   * For lazy loading, we use the browser's strategy for images with loading="lazy".
+   * We use an empty image, and when the browser triggers the load event, we load the best available image.
+   * On page loading, if the image url is already in browser's cache, the load event is triggered immediately.
+   * This is why we need to use a different blob url for every image.
+   */
+  const [waitingLazyLoading, setWaitingLazyLoading] = useState(
+    props.loading === "lazy",
+  );
+  const lazyPlaceholder = useMemo(
+    () =>
+      waitingLazyLoading ? URL.createObjectURL(emptyPixelBlob) : undefined,
+    [waitingLazyLoading],
+  );
+
+  const dimensions: { width: number | undefined; height: number | undefined } =
+    useMemo(() => {
+      const originalWidth = image?.originalSize?.[0];
+      const originalHeight = image?.originalSize?.[1];
+
+      // Both width and height are "original"
+      if (width === "original" && height === "original") {
+        return { width: originalWidth, height: originalHeight };
+      }
+
+      // Width is "original", height is a number
+      if (width === "original" && typeof height === "number") {
+        if (originalWidth && originalHeight) {
+          return {
+            width: Math.round((height * originalWidth) / originalHeight),
+            height,
+          };
+        }
+        return { width: undefined, height };
+      }
+
+      // Height is "original", width is a number
+      if (height === "original" && typeof width === "number") {
+        if (originalWidth && originalHeight) {
+          return {
+            width,
+            height: Math.round((width * originalHeight) / originalWidth),
+          };
+        }
+        return { width, height: undefined };
+      }
+
+      // In all other cases, use the property value:
+      return {
+        width: width === "original" ? originalWidth : width,
+        height: height === "original" ? originalHeight : height,
+      };
+    }, [image?.originalSize, width, height]);
+
+  const src = useMemo(() => {
+    if (waitingLazyLoading) {
+      return lazyPlaceholder;
+    }
+
+    if (!image) return undefined;
+
+    const bestImage = highestResAvailable(
+      image,
+      dimensions.width || dimensions.height || 9999,
+      dimensions.height || dimensions.width || 9999,
+    );
+
+    if (!bestImage) return image.placeholderDataURL;
+    if (lastBestImage.current?.[0] === bestImage.image.id)
+      return lastBestImage.current?.[1];
+
+    const blob = bestImage.image.toBlob();
+
+    if (blob) {
+      const url = URL.createObjectURL(blob);
+      revokeObjectURL(lastBestImage.current?.[1]);
+      lastBestImage.current = [bestImage.image.id, url];
+      return url;
+    }
+
+    return image.placeholderDataURL;
+  }, [image, dimensions.width, dimensions.height, waitingLazyLoading]);
+
+  const onThresholdReached = useCallback(() => {
+    setWaitingLazyLoading(false);
+  }, []);
+
+  // Revoke object URL when component unmounts
+  useEffect(
+    () => () => {
+      // In development mode we don't revokeObjectURL on unmount because
+      // it triggers twice under StrictMode.
+      if (process.env.NODE_ENV === "development") return;
+      revokeObjectURL(lastBestImage.current?.[1]);
+    },
+    [],
+  );
+
+  return (
+    <img
+      ref={ref}
+      src={src}
+      width={dimensions.width}
+      height={dimensions.height}
+      onLoad={waitingLazyLoading ? onThresholdReached : undefined}
+      {...props}
+    />
+  );
+});
+
+function revokeObjectURL(url: string | undefined) {
+  if (url && url.startsWith("blob:")) {
+    URL.revokeObjectURL(url);
+  }
+}
+
+const emptyPixelBlob = new Blob(
+  [
+    Uint8Array.from(
+      atob(
+        "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==",
+      ),
+      (c) => c.charCodeAt(0),
+    ),
+  ],
+  { type: "image/png" },
+);