react-native-nitro-image-pipeline 1.2.0 → 1.3.1

package/src/resizeForStyle.ts

@@ -0,0 +1,96 @@
+import {
+  PixelRatio,
+  type StyleProp,
+  StyleSheet,
+  type ViewStyle,
+} from 'react-native';
+
+import type {
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+
+/**
+ * Converts a layout size in points (dp) to the pipeline's `resize` option in
+ * whole bitmap pixels using `PixelRatio.getPixelSizeForLayoutSize`. Returns
+ * `undefined` unless both values are positive numbers.
+ */
+export function resizeForLayout(
+  width: unknown,
+  height: unknown,
+): ResizeOptions | undefined {
+  if (typeof width !== 'number' || typeof height !== 'number') {
+    return undefined;
+  }
+  const pixelWidth = PixelRatio.getPixelSizeForLayoutSize(width);
+  const pixelHeight = PixelRatio.getPixelSizeForLayoutSize(height);
+  return pixelWidth > 0 && pixelHeight > 0
+    ? { width: pixelWidth, height: pixelHeight }
+    : undefined;
+}
+
+/**
+ * Derives the pipeline's `resize` option from a view style whose `width` and
+ * `height` are numeric points, so the bitmap matches the display size on
+ * every screen density:
+ * ```ts
+ * useImage({ url, resize: resizeForStyle(styles.image) });
+ * ```
+ * Arrays and registered styles are flattened. Returns `undefined` when either
+ * dimension is missing or not a number (`'50%'`, `'auto'`, flex-driven) —
+ * use `<PipelineImage>` for those, which measures the view instead.
+ */
+export function resizeForStyle(
+  style: StyleProp<ViewStyle>,
+): ResizeOptions | undefined {
+  const flat = StyleSheet.flatten(style);
+  return resizeForLayout(flat?.width, flat?.height);
+}
+
+/**
+ * Derives a `cornerRadius` option from a view style's `borderRadius` /
+ * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius` /
+ * `borderBottomRightRadius`, in points. Per-corner properties override
+ * `borderRadius` for that corner; a corner with neither set stays square.
+ * Non-numeric values (percentages, animated values) are ignored, like
+ * {@linkcode resizeForStyle}. Returns `undefined` when none are set.
+ */
+export function cornerRadiusForStyle(
+  style: StyleProp<ViewStyle>,
+): number | CornerRadii | undefined {
+  const flat = StyleSheet.flatten(style);
+  const base =
+    typeof flat?.borderRadius === 'number' ? flat.borderRadius : undefined;
+  const topLeft =
+    typeof flat?.borderTopLeftRadius === 'number'
+      ? flat.borderTopLeftRadius
+      : undefined;
+  const topRight =
+    typeof flat?.borderTopRightRadius === 'number'
+      ? flat.borderTopRightRadius
+      : undefined;
+  const bottomLeft =
+    typeof flat?.borderBottomLeftRadius === 'number'
+      ? flat.borderBottomLeftRadius
+      : undefined;
+  const bottomRight =
+    typeof flat?.borderBottomRightRadius === 'number'
+      ? flat.borderBottomRightRadius
+      : undefined;
+
+  if (
+    topLeft === undefined &&
+    topRight === undefined &&
+    bottomLeft === undefined &&
+    bottomRight === undefined
+  ) {
+    return base;
+  }
+
+  return {
+    topLeft: topLeft ?? base,
+    topRight: topRight ?? base,
+    bottomLeft: bottomLeft ?? base,
+    bottomRight: bottomRight ?? base,
+  };
+}

package/src/useImage.ts

@@ -0,0 +1,149 @@
+import { useEffect, useRef, useState } from 'react';
+import type { Image } from 'react-native-nitro-image';
+
+import { NitroImagePipeline } from './NitroImagePipeline';
+import type {
+  CacheOption,
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+
+type Result =
+  // Loading State
+  | {
+      image: undefined;
+      error: undefined;
+    }
+  // Loaded state
+  | {
+      image: Image;
+      error: undefined;
+    }
+  // Error state
+  | {
+      image: undefined;
+      error: Error;
+    };
+
+/**
+ * A hook to asynchronously load an image from the
+ * given {@linkcode AsyncImageSource} into memory.
+ * @example
+ * ```ts
+ * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
+ * ```
+ */
+export function useImage({
+  url,
+  blur = 0,
+  cornerRadius = 0,
+  resize,
+  cache,
+  enabled = true,
+}: {
+  url: string;
+  /**
+   * Gaussian blur strength, as the standard deviation (sigma) of the blur in
+   * source-image pixels (of the resized bitmap when `resize` is set). Matches
+   * across iOS and Android; roughly half of React Native's `blurRadius`.
+   */
+  blur?: number;
+  /**
+   * Corner radius in pixels of the loaded bitmap. Pass a single number for
+   * uniform rounding, or per-corner radii (inline object literals are fine —
+   * the hook compares the radii by value, not identity). Pair with `resize`
+   * so the radii apply at the size you display instead of the source size.
+   */
+  cornerRadius?: number | CornerRadii;
+  /**
+   * Resize the bitmap to exactly this size in pixels (aspect-fill,
+   * center-crop) before blur/rounding. Typically your display size in points
+   * multiplied by `PixelRatio.get()`. Inline object literals are fine.
+   */
+  resize?: ResizeOptions;
+  cache?: CacheOption;
+  /**
+   * When `false`, no request is made and the result stays in the loading
+   * state (or keeps the current image if `url` is unchanged) until it becomes
+   * `true`. Use it to defer loading until inputs such as a layout size are
+   * known.
+   * @default true
+   */
+  enabled?: boolean;
+}): Result {
+  const [image, setImage] = useState<Result>({
+    image: undefined,
+    error: undefined,
+  });
+  const loadedUrlRef = useRef(url);
+
+  // Split the option into primitives so an inline `{ topLeft: 24, ... }`
+  // literal (new identity every render) doesn't re-trigger the effect.
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0,
+  } = isUniformRadius ? {} : cornerRadius;
+  const resizeWidth = resize?.width ?? 0;
+  const resizeHeight = resize?.height ?? 0;
+
+  useEffect(() => {
+    let cancelled = false;
+    // Only reset to the loading state when the URL changes; for same-URL
+    // param tweaks (blur/cornerRadius/cache) keep showing the current image
+    // until the new variant resolves, to avoid flashing empty.
+    if (loadedUrlRef.current !== url) {
+      loadedUrlRef.current = url;
+      setImage({ image: undefined, error: undefined });
+    }
+
+    if (enabled) {
+      (async () => {
+        try {
+          const result = await NitroImagePipeline.loadImage(url, {
+            blur,
+            cornerRadius: isUniformRadius
+              ? uniformRadius
+              : { topLeft, topRight, bottomLeft, bottomRight },
+            resize:
+              resizeWidth > 0 && resizeHeight > 0
+                ? { width: resizeWidth, height: resizeHeight }
+                : undefined,
+            cache,
+          });
+
+          if (!cancelled) {
+            setImage({ image: result, error: undefined });
+          }
+        } catch (e) {
+          const error = e instanceof Error ? e : new Error(`${e}`);
+          if (!cancelled) {
+            setImage({ image: undefined, error: error });
+          }
+        }
+      })();
+    }
+
+    return () => {
+      cancelled = true;
+    };
+  }, [
+    url,
+    blur,
+    isUniformRadius,
+    uniformRadius,
+    topLeft,
+    topRight,
+    bottomLeft,
+    bottomRight,
+    resizeWidth,
+    resizeHeight,
+    cache,
+    enabled,
+  ]);
+
+  return image;
+}