jazz-tools 0.16.5 → 0.17.0

package/src/react-native-core/media/image.tsx

@@ -0,0 +1,159 @@
+import { FileStream, ImageDefinition } from "jazz-tools";
+import { highestResAvailable } from "jazz-tools/media";
+import { forwardRef, useEffect, useMemo, useState } from "react";
+import { Image as RNImage, ImageProps as RNImageProps } from "react-native";
+import { useCoState } from "../hooks.js";
+
+export type ImageProps = Omit<RNImageProps, "width" | "height" | "source"> & {
+  /** The ID of the ImageDefinition to display */
+  imageId: string;
+  /**
+   * Width of the image. Can be a number or "original" to use the original image width.
+   * When set to "original", the component will calculate the appropriate height to maintain aspect ratio.
+   *
+   * @example
+   * ```tsx
+   * // Fixed width, auto-calculated height
+   * <Image imageId="123" width={600} />
+   *
+   * // Original width
+   * <Image imageId="123" width="original" />
+   * ```
+   */
+  width?: number | "original";
+  /**
+   * Height of the image. Can be a number or "original" to use the original image height.
+   * When set to "original", the component will calculate the appropriate width to maintain aspect ratio.
+   *
+   * @example
+   * ```tsx
+   * // Fixed height, auto-calculated width
+   * <Image imageId="123" height={400} />
+   *
+   * // Original height
+   * <Image imageId="123" height="original" />
+   * ```
+   */
+  height?: number | "original";
+};
+
+/**
+ * A React Native Image component that integrates with Jazz's ImageDefinition system.
+ *
+ * @example
+ * ```tsx
+ * import { Image } from "jazz-tools/react-native";
+ * import { StyleSheet } from "react-native";
+ *
+ * function ProfilePicture({ imageId }) {
+ *   return (
+ *     <Image
+ *       imageId={imageId}
+ *       style={styles.profilePic}
+ *       width={100}
+ *       height={100}
+ *       resizeMode="cover"
+ *     />
+ *   );
+ * }
+ *
+ * const styles = StyleSheet.create({
+ *   profilePic: {
+ *     borderRadius: 50,
+ *   }
+ * });
+ * ```
+ */
+export const Image = forwardRef<RNImage, ImageProps>(function Image(
+  { imageId, width, height, ...props },
+  ref,
+) {
+  const image = useCoState(ImageDefinition, imageId);
+  const [src, setSrc] = useState<string | undefined>(image?.placeholderDataURL);
+
+  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]);
+
+  useEffect(() => {
+    if (!image) return;
+
+    let lastBestImage: FileStream | string | undefined =
+      image.placeholderDataURL;
+
+    const unsub = image.subscribe({}, (update) => {
+      if (lastBestImage === undefined && update.placeholderDataURL) {
+        setSrc(update.placeholderDataURL);
+        lastBestImage = update.placeholderDataURL;
+      }
+
+      const bestImage = highestResAvailable(
+        update,
+        dimensions.width || dimensions.height || 9999,
+        dimensions.height || dimensions.width || 9999,
+      );
+
+      if (!bestImage) return;
+
+      if (lastBestImage === bestImage.image) return;
+
+      const url = bestImage.image.asBase64({ dataURL: true });
+
+      if (url) {
+        setSrc(url);
+        lastBestImage = bestImage.image;
+      }
+    });
+
+    return unsub;
+  }, [image]);
+
+  if (!image) {
+    return null;
+  }
+
+  return (
+    <RNImage
+      ref={ref}
+      source={{ uri: src }}
+      width={dimensions.width}
+      height={dimensions.height}
+      {...props}
+    />
+  );
+});

package/src/svelte/index.ts

@@ -3,3 +3,4 @@ export * from "./auth/index.js";
 export * from "./jazz.svelte.js";
 export * from "./jazz.class.svelte.js";
 export { useIsAuthenticated } from "./auth/useIsAuthenticated.svelte.js";
+export * from "./media/index.js";

package/src/svelte/media/image.svelte

@@ -0,0 +1,131 @@
+<script lang="ts">
+import { ImageDefinition } from "jazz-tools";
+import { highestResAvailable } from "jazz-tools/media";
+import { onDestroy } from "svelte";
+import type { HTMLImgAttributes } from "svelte/elements";
+import { CoState } from "../jazz.class.svelte";
+
+interface ImageProps extends Omit<HTMLImgAttributes, "width" | "height"> {
+  imageId: string;
+  width?: number | "original";
+  height?: number | "original";
+}
+
+const { imageId, width, height, ...rest }: ImageProps = $props();
+
+const imageState = new CoState(ImageDefinition, imageId);
+let lastBestImage: [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.
+ */
+let waitingLazyLoading = $state(rest.loading === "lazy");
+const lazyPlaceholder = $derived.by(() =>
+  waitingLazyLoading ? URL.createObjectURL(emptyPixelBlob) : undefined,
+);
+
+const dimensions = $derived.by<{
+  width: number | undefined;
+  height: number | undefined;
+}>(() => {
+  const originalWidth = imageState.current?.originalSize?.[0];
+  const originalHeight = imageState.current?.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,
+  };
+});
+
+const src = $derived.by(() => {
+  if (waitingLazyLoading) {
+    return lazyPlaceholder;
+  }
+
+  const image = imageState.current;
+  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?.[0] === bestImage.image.id) return lastBestImage?.[1];
+
+  const blob = bestImage.image.toBlob();
+
+  if (blob) {
+    const url = URL.createObjectURL(blob);
+    revokeObjectURL(lastBestImage?.[1]);
+    lastBestImage = [bestImage.image.id, url];
+    return url;
+  }
+
+  return image.placeholderDataURL;
+});
+
+// Cleanup object URL on component destroy
+onDestroy(() => {
+  revokeObjectURL(lastBestImage?.[1]);
+});
+
+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" },
+);
+</script>
+
+<img
+  {src}
+  width={dimensions.width}
+  height={dimensions.height}
+  alt={rest.alt}
+  onload={() => {waitingLazyLoading = false}}
+  {...rest}
+/>

package/src/svelte/media/index.ts

@@ -0,0 +1 @@
+export { default as Image } from "./image.svelte";