react-native-image-collage 0.2.0

package/src/expo/index.tsx

@@ -0,0 +1,99 @@
+import React from "react";
+import { ImageCollage as BaseImageCollage } from "../ImageCollage";
+import type {
+  ExpoImageCollageOptions,
+  ImageCollageProps,
+  ImageCollageWithViewerProps,
+  ImagePriority,
+} from "../types";
+import { ImageCollageWithViewer as BaseImageCollageWithViewer } from "../viewer/ImageCollageWithViewer";
+import { createExpoImageRenderer } from "./createExpoImageRenderer";
+
+export { CollageImage, renderCollageImage } from "../CollageImage";
+export { CollageTile } from "../CollageTile";
+export { CollageWithViewer } from "../CollageWithViewer";
+export { ImageCollage as ImageCollague } from "../ImageCollage";
+export { ImageViewer, createDefaultViewerRenderer } from "../viewer/ImageViewer";
+export { ImageCollageWithViewer as BaseImageCollageWithViewer } from "../viewer/ImageCollageWithViewer";
+
+export type {
+  CollageImageInput,
+  CollageImageRenderProps,
+  CollageImageRenderer,
+  CollageViewerRenderProps,
+  CollageViewerRenderer,
+  CollageWithViewerProps,
+  ExpoImageCollageOptions,
+  ImageCollageProps,
+  ImageCollageWithViewerProps,
+  ImagePriority,
+  ImageViewerImage,
+  ImageViewerProps,
+  NormalizedCollageImage,
+} from "../types";
+
+export {
+  ANDROID_RIPPLE,
+  DEFAULT_BLURHASH,
+  DEFAULT_BORDER_RADIUS,
+  DEFAULT_LAYOUT_MAX_HEIGHT,
+  DEFAULT_LAYOUT_MIN_HEIGHT,
+  DEFAULT_MAX_VISIBLE_IMAGES,
+  DEFAULT_PLACEHOLDER_BG,
+  DEFAULT_PLACEHOLDER_COLOR,
+  DEFAULT_SPACING,
+} from "../constants";
+
+export {
+  createExpoImageRenderer,
+  expoImageRenderer,
+} from "./createExpoImageRenderer";
+
+type ExpoCollageProps = ImageCollageProps & ExpoImageCollageOptions;
+
+function buildExpoCollageProps({
+  blurhash,
+  prioritizeFirstImage = true,
+  renderImage,
+  getImagePriority,
+  ...props
+}: ExpoCollageProps): ImageCollageProps {
+  return {
+    ...props,
+    renderImage: renderImage ?? createExpoImageRenderer({ blurhash }),
+    getImagePriority:
+      getImagePriority ??
+      ((index: number): ImagePriority =>
+        index === 0 && prioritizeFirstImage ? "high" : "normal"),
+  };
+}
+
+export function ImageCollage(props: ExpoCollageProps) {
+  return <BaseImageCollage {...buildExpoCollageProps(props)} />;
+}
+
+export function ImageCollageWithViewer({
+  blurhash,
+  prioritizeFirstImage,
+  renderImage,
+  getImagePriority,
+  viewerProps,
+  renderViewer,
+  onImagePress,
+  ...collageProps
+}: ImageCollageWithViewerProps & ExpoImageCollageOptions) {
+  return (
+    <BaseImageCollageWithViewer
+      {...buildExpoCollageProps({
+        ...collageProps,
+        blurhash,
+        prioritizeFirstImage,
+        renderImage,
+        getImagePriority,
+      })}
+      viewerProps={viewerProps}
+      renderViewer={renderViewer}
+      onImagePress={onImagePress}
+    />
+  );
+}

package/src/hooks/useContainerWidth.ts

@@ -0,0 +1,29 @@
+import { useCallback, useState } from "react";
+import { useWindowDimensions, type LayoutChangeEvent } from "react-native";
+
+export function useContainerWidth({
+  width,
+  horizontalInset = 0,
+}: {
+  width?: number;
+  horizontalInset?: number;
+}) {
+  const { width: windowWidth } = useWindowDimensions();
+  const [measuredWidth, setMeasuredWidth] = useState<number | null>(null);
+
+  const onLayout = useCallback((event: LayoutChangeEvent) => {
+    const nextWidth = event.nativeEvent.layout.width;
+    if (nextWidth > 0) {
+      setMeasuredWidth(nextWidth);
+    }
+  }, []);
+
+  const fallbackWidth = Math.max(0, windowWidth - horizontalInset);
+  const containerWidth = width ?? measuredWidth ?? fallbackWidth;
+
+  return {
+    containerWidth,
+    onLayout,
+    isMeasured: measuredWidth != null,
+  };
+}

package/src/index.ts

@@ -0,0 +1,42 @@
+export { ImageCollage } from "./ImageCollage";
+export { CollageWithViewer } from "./CollageWithViewer";
+export { CollageImage, renderCollageImage } from "./CollageImage";
+export { CollageTile } from "./CollageTile";
+
+/** @deprecated Use `ImageCollage` instead. Kept for backwards compatibility. */
+export { ImageCollage as ImageCollague } from "./ImageCollage";
+
+export type {
+  CollageImageInput,
+  CollageImageRenderProps,
+  CollageImageRenderer,
+  CollageViewerRenderProps,
+  CollageViewerRenderer,
+  CollageWithViewerProps,
+  ImageCollageProps,
+  ImagePriority,
+  NormalizedCollageImage,
+} from "./types";
+
+export {
+  DEFAULT_PLACEHOLDER_COLOR,
+  DEFAULT_PLACEHOLDER_BG,
+  DEFAULT_SPACING,
+  DEFAULT_BORDER_RADIUS,
+  DEFAULT_LAYOUT_MIN_HEIGHT,
+  DEFAULT_LAYOUT_MAX_HEIGHT,
+  DEFAULT_MAX_VISIBLE_IMAGES,
+  ANDROID_RIPPLE,
+} from "./constants";
+
+export {
+  normalizeImageInput,
+  normalizeImages,
+  measureImageAspectRatio,
+  resolveImagesWithAspectRatios,
+  toViewerImages,
+  getRemoteUri,
+} from "./utils/imageSources";
+
+export { computeLayoutHeight } from "./utils/layoutHeight";
+export { useContainerWidth } from "./hooks/useContainerWidth";

package/src/types.ts

@@ -0,0 +1,120 @@
+import type { ReactElement } from "react";
+import type {
+  ImageSourcePropType,
+  ImageStyle,
+  StyleProp,
+  ViewStyle,
+} from "react-native";
+
+export type ImagePriority = "low" | "normal" | "high";
+
+/** Remote URL, RN image source, or object with optional aspect ratio. */
+export type CollageImageInput =
+  | string
+  | ImageSourcePropType
+  | {
+      uri: string;
+      aspectRatio?: number;
+    };
+
+export type NormalizedCollageImage = {
+  source: ImageSourcePropType;
+  aspectRatio?: number;
+  cacheKey: string;
+  remoteUri?: string;
+};
+
+export type CollageImageRenderProps = {
+  source: ImageSourcePropType;
+  remoteUri?: string;
+  style?: StyleProp<ImageStyle>;
+  priority?: ImagePriority;
+  transition: number;
+};
+
+export type CollageImageRenderer = (
+  props: CollageImageRenderProps,
+) => ReactElement;
+
+export type ImageViewerImage = {
+  uri: string;
+};
+
+export type CollageViewerRenderProps = {
+  images: ImageViewerImage[];
+  visible: boolean;
+  imageIndex: number;
+  onRequestClose: () => void;
+};
+
+export type CollageViewerRenderer = (
+  props: CollageViewerRenderProps,
+) => ReactElement | null;
+
+export type ImageCollageProps = {
+  images: CollageImageInput[] | null | undefined;
+  /** Fixed layout height; when omitted, height is derived from container width. */
+  height?: number;
+  /** Explicit container width; when omitted, width is measured via `onLayout`. */
+  width?: number;
+  /**
+   * @deprecated Prefer automatic `onLayout` sizing. Subtracted from screen width
+   * only before the container has been measured.
+   */
+  horizontalInset?: number;
+  borderRadius?: number;
+  spacing?: number;
+  /**
+   * Maximum tiles to show. When there are more images, the last visible tile
+   * displays a `+N` overlay for the remaining count.
+   *
+   * @example `maxVisibleImages={3}` with 4 images → 3-tile layout, third tile shows `+1`
+   * @example `maxVisibleImages={4}` with 5 images → 2×2 grid, fourth tile shows `+1`
+   */
+  maxVisibleImages?: number;
+  onImagePress?: (index: number) => void;
+  layoutMinHeight?: number;
+  layoutMaxHeight?: number;
+  placeholderColor?: string;
+  /** Measure missing aspect ratios before rendering. */
+  measureAspectRatios?: boolean;
+  /** Optional per-tile loading priority (used by custom renderers such as expo-image). */
+  getImagePriority?: (index: number) => ImagePriority;
+  /** Custom image renderer. Defaults to React Native `Image`. */
+  renderImage?: CollageImageRenderer;
+  style?: StyleProp<ViewStyle>;
+};
+
+export type CollageWithViewerProps = ImageCollageProps & {
+  renderViewer: CollageViewerRenderer;
+  onImagePress?: (index: number) => void;
+};
+
+export type ImageViewerProps = {
+  images: ImageViewerImage[];
+  visible: boolean;
+  imageIndex?: number;
+  onRequestClose: () => void;
+  swipeToCloseEnabled?: boolean;
+  doubleTapToZoomEnabled?: boolean;
+  presentationStyle?: "fullScreen" | "pageSheet" | "formSheet" | "overFullScreen";
+  showCloseButton?: boolean;
+  showIndexFooter?: boolean;
+  closeButtonLabel?: string;
+};
+
+export type ImageCollageWithViewerProps = Omit<ImageCollageProps, "onImagePress"> & {
+  viewerProps?: Omit<
+    ImageViewerProps,
+    "images" | "visible" | "imageIndex" | "onRequestClose"
+  >;
+  /** Override the built-in `react-native-image-viewing` viewer. */
+  renderViewer?: CollageViewerRenderer;
+  onImagePress?: (index: number) => void;
+};
+
+/** Expo-only collage options (`react-native-image-collage/expo`). */
+export type ExpoImageCollageOptions = {
+  blurhash?: string;
+  prioritizeFirstImage?: boolean;
+};

package/src/utils/imageSources.ts

@@ -0,0 +1,170 @@
+import { Image, type ImageSourcePropType } from "react-native";
+import type { CollageImageInput, NormalizedCollageImage } from "../types";
+
+function cacheKeyForSource(source: ImageSourcePropType): string {
+  if (typeof source === "number") {
+    return `asset-${source}`;
+  }
+
+  if (typeof source === "object" && source) {
+    if ("uri" in source && source.uri) {
+      return source.uri;
+    }
+
+    if ("testUri" in source && typeof source.testUri === "string") {
+      return source.testUri;
+    }
+  }
+
+  return JSON.stringify(source);
+}
+
+export function getRemoteUri(
+  source: ImageSourcePropType,
+): string | undefined {
+  if (typeof source === "number") {
+    return Image.resolveAssetSource(source)?.uri;
+  }
+
+  if (typeof source === "object" && source && "uri" in source && source.uri) {
+    return source.uri;
+  }
+
+  return undefined;
+}
+
+export function normalizeImageInput(
+  input: CollageImageInput,
+): NormalizedCollageImage | null {
+  if (input == null || input === "") {
+    return null;
+  }
+
+  if (typeof input === "string") {
+    const source = { uri: input };
+    return {
+      source,
+      aspectRatio: undefined,
+      cacheKey: input,
+      remoteUri: input,
+    };
+  }
+
+  if (typeof input === "number") {
+    const source = input;
+    const resolved = Image.resolveAssetSource(source);
+    const aspectRatio =
+      resolved?.width && resolved?.height
+        ? resolved.width / resolved.height
+        : undefined;
+
+    return {
+      source,
+      aspectRatio,
+      cacheKey: cacheKeyForSource(source),
+      remoteUri: resolved?.uri,
+    };
+  }
+
+  if (typeof input === "object" && input != null && "uri" in input) {
+    const uri = (input as { uri: unknown }).uri;
+    if (typeof uri === "string") {
+      const keys = Object.keys(input);
+      const isUriDescriptor = keys.every(
+        (key) => key === "uri" || key === "aspectRatio",
+      );
+
+      if (isUriDescriptor) {
+        const aspectRatio =
+          "aspectRatio" in input
+            ? (input as { aspectRatio?: number }).aspectRatio
+            : undefined;
+
+        return {
+          source: { uri },
+          aspectRatio,
+          cacheKey: uri,
+          remoteUri: uri,
+        };
+      }
+    }
+  }
+
+  const source = input as ImageSourcePropType;
+  const remoteUri = getRemoteUri(source);
+
+  return {
+    source,
+    aspectRatio: undefined,
+    cacheKey: cacheKeyForSource(source),
+    remoteUri,
+  };
+}
+
+export function normalizeImages(
+  images: CollageImageInput[] | null | undefined,
+): NormalizedCollageImage[] {
+  return (images ?? [])
+    .map(normalizeImageInput)
+    .filter((image): image is NormalizedCollageImage => image != null);
+}
+
+export function measureImageAspectRatio(
+  image: NormalizedCollageImage,
+): Promise<number> {
+  if (image.aspectRatio != null) {
+    return Promise.resolve(image.aspectRatio);
+  }
+
+  if (typeof image.source === "number") {
+    const resolved = Image.resolveAssetSource(image.source);
+    if (resolved?.width && resolved?.height) {
+      return Promise.resolve(resolved.width / resolved.height);
+    }
+
+    return Promise.reject(new Error("Unable to resolve local image dimensions"));
+  }
+
+  const uri = getRemoteUri(image.source);
+  if (!uri) {
+    return Promise.reject(new Error("Unable to measure image without a URI"));
+  }
+
+  return new Promise((resolve, reject) => {
+    Image.getSize(
+      uri,
+      (width, height) => resolve(width / height),
+      reject,
+    );
+  });
+}
+
+export async function resolveImagesWithAspectRatios(
+  images: NormalizedCollageImage[],
+): Promise<NormalizedCollageImage[]> {
+  return Promise.all(
+    images.map(async (image) => {
+      if (image.aspectRatio != null) {
+        return image;
+      }
+
+      try {
+        const aspectRatio = await measureImageAspectRatio(image);
+        return { ...image, aspectRatio };
+      } catch {
+        return image;
+      }
+    }),
+  );
+}
+
+export function toViewerImages(
+  images: NormalizedCollageImage[],
+): { uri: string }[] {
+  return images
+    .map((image) => {
+      const uri = image.remoteUri ?? getRemoteUri(image.source);
+      return uri ? { uri } : null;
+    })
+    .filter((image): image is { uri: string } => image != null);
+}

package/src/utils/layoutHeight.ts

@@ -0,0 +1,54 @@
+import type { NormalizedCollageImage } from "../types";
+
+function heightRatioForImageCount(count: number) {
+  if (count <= 1) return 0.9;
+  if (count === 2) return 0.75;
+  if (count === 3) return 0.9;
+  if (count === 4) return 1.0;
+  return 1.05;
+}
+
+function averageAspectRatio(images: NormalizedCollageImage[]): number | undefined {
+  const ratios = images
+    .map((image) => image.aspectRatio)
+    .filter((ratio): ratio is number => ratio != null && ratio > 0);
+
+  if (!ratios.length) {
+    return undefined;
+  }
+
+  return ratios.reduce((sum, ratio) => sum + ratio, 0) / ratios.length;
+}
+
+export function computeLayoutHeight({
+  contentWidth,
+  images,
+  height,
+  layoutMinHeight,
+  layoutMaxHeight,
+}: {
+  contentWidth: number;
+  images: NormalizedCollageImage[];
+  height?: number;
+  layoutMinHeight: number;
+  layoutMaxHeight: number;
+}): number {
+  if (height != null) {
+    return Math.max(layoutMinHeight, Math.min(height, layoutMaxHeight));
+  }
+
+  const count = images.length;
+  let ratio = heightRatioForImageCount(count);
+
+  if (count === 1 && images[0]?.aspectRatio) {
+    ratio = 1 / images[0].aspectRatio;
+  } else if (count === 2) {
+    const averageRatio = averageAspectRatio(images);
+    if (averageRatio) {
+      ratio = 1 / averageRatio;
+    }
+  }
+
+  const computedHeight = Math.round(contentWidth * ratio);
+  return Math.max(layoutMinHeight, Math.min(computedHeight, layoutMaxHeight));
+}