react-native-nitro-image-pipeline 1.1.0 → 1.2.1

package/nitrogen/generated/shared/c++/ResizeOptions.hpp

@@ -0,0 +1,87 @@
+///
+/// ResizeOptions.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+
+
+namespace margelo::nitro::nitroimagepipeline {
+
+  /**
+   * A struct which can be represented as a JavaScript object (ResizeOptions).
+   */
+  struct ResizeOptions final {
+  public:
+    double width     SWIFT_PRIVATE;
+    double height     SWIFT_PRIVATE;
+
+  public:
+    ResizeOptions() = default;
+    explicit ResizeOptions(double width, double height): width(width), height(height) {}
+
+  public:
+    friend bool operator==(const ResizeOptions& lhs, const ResizeOptions& rhs) = default;
+  };
+
+} // namespace margelo::nitro::nitroimagepipeline
+
+namespace margelo::nitro {
+
+  // C++ ResizeOptions <> JS ResizeOptions (object)
+  template <>
+  struct JSIConverter<margelo::nitro::nitroimagepipeline::ResizeOptions> final {
+    static inline margelo::nitro::nitroimagepipeline::ResizeOptions fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::nitroimagepipeline::ResizeOptions(
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width"))),
+        JSIConverter<double>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitroimagepipeline::ResizeOptions& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "width"), JSIConverter<double>::toJSI(runtime, arg.width));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "height"), JSIConverter<double>::toJSI(runtime, arg.height));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "width")))) return false;
+      if (!JSIConverter<double>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "height")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "High-performance image loading, caching, and processing for React Native, built with Nitro Modules",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/module/index.js",

package/src/NitroImagePipeline.ts

@@ -0,0 +1,6 @@
+import { NitroModules } from 'react-native-nitro-modules';
+
+import type { NitroImagePipeline as NitroImagePipelineSpec } from './specs/nitro-image-toolkit.nitro';
+
+export const NitroImagePipeline =
+  NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');

package/src/PipelineImage.tsx

@@ -0,0 +1,156 @@
+import { useEffect, useRef, useState } from 'react';
+import {
+  type HostComponent,
+  type LayoutChangeEvent,
+  PixelRatio,
+} from 'react-native';
+import { type Image, NativeNitroImage } from 'react-native-nitro-image';
+
+import {
+  cornerRadiusForStyle,
+  resizeForLayout,
+  resizeForStyle,
+} from './resizeForStyle';
+import type {
+  CacheOption,
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+import { useImage } from './useImage';
+
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+
+export interface PipelineImageProps extends Omit<NativeImageProps, 'image'> {
+  /** URL of the image to load through the pipeline. */
+  url: string;
+  /**
+   * Gaussian blur sigma in **points** (density-independent). Unlike
+   * `useImage`/`loadImage`, where it is bitmap pixels, the component
+   * multiplies it by `PixelRatio.get()` so the same value looks the same on
+   * every device.
+   * @default 0
+   */
+  blur?: number;
+  /**
+   * Corner radius in **points** — a single number or per-corner radii.
+   * Converted to bitmap pixels with `PixelRatio.get()` and baked into the
+   * bitmap at the display size.
+   *
+   * When omitted, it's derived from `style`'s `borderRadius` /
+   * `borderTopLeftRadius` / `borderTopRightRadius` / `borderBottomLeftRadius`
+   * / `borderBottomRightRadius` instead — set this prop to override that.
+   * @default undefined (derived from `style`, or square corners if unset there)
+   */
+  cornerRadius?: number | CornerRadii;
+  cache?: CacheOption;
+  /** Called with the processed `Image` each time a new variant resolves. */
+  onLoad?: (image: Image) => void;
+  /** Called when loading fails. */
+  onError?: (error: Error) => void;
+}
+
+function sameSize(a?: ResizeOptions, b?: ResizeOptions): boolean {
+  return a?.width === b?.width && a?.height === b?.height;
+}
+
+function scaleRadius(
+  cornerRadius: number | CornerRadii,
+  scale: number,
+): number | CornerRadii {
+  if (typeof cornerRadius === 'number') {
+    return cornerRadius * scale;
+  }
+  return {
+    topLeft: (cornerRadius.topLeft ?? 0) * scale,
+    topRight: (cornerRadius.topRight ?? 0) * scale,
+    bottomLeft: (cornerRadius.bottomLeft ?? 0) * scale,
+    bottomRight: (cornerRadius.bottomRight ?? 0) * scale,
+  };
+}
+
+/**
+ * A `NativeNitroImage` that loads `url` through the pipeline at exactly the
+ * size it is displayed: the bitmap is resized to the view's size in points ×
+ * `PixelRatio.get()`, so `blur` and `cornerRadius` (both in points here) apply
+ * 1:1 to what is on screen and large sources are never decoded at full size.
+ *
+ * A numeric `width`/`height` in `style` starts loading immediately; otherwise
+ * (`'50%'`, `flex`, `aspectRatio`, …) loading waits for the first `onLayout`.
+ * If the layout size later changes, a new variant is loaded and swapped in
+ * without flashing. Without an explicit `cornerRadius` prop, `style`'s
+ * `borderRadius`-family properties are baked into the bitmap instead — no
+ * separate view-layer rounding needed.
+ * @example
+ * ```tsx
+ * <PipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200 }}
+ *   cornerRadius={24}
+ * />
+ * ```
+ */
+export function PipelineImage({
+  url,
+  blur = 0,
+  cornerRadius,
+  cache,
+  onLoad,
+  onError,
+  style,
+  onLayout,
+  ...viewProps
+}: PipelineImageProps) {
+  const scale = PixelRatio.get();
+  const styleSize = resizeForStyle(style);
+  const [layoutSize, setLayoutSize] = useState<ResizeOptions | undefined>(
+    undefined,
+  );
+  // A numeric style is what the caller declared, so it wins and starts the
+  // request a frame earlier; the measured layout is the fallback.
+  const resize = styleSize ?? layoutSize;
+  // Same precedence: an explicit prop wins over what style implies.
+  const effectiveCornerRadius =
+    cornerRadius ?? cornerRadiusForStyle(style) ?? 0;
+
+  const { image, error } = useImage({
+    url,
+    blur: blur * scale,
+    cornerRadius: scaleRadius(effectiveCornerRadius, scale),
+    cache,
+    resize,
+    enabled: resize !== undefined,
+  });
+
+  // Latest callbacks in refs so inline arrow props don't re-fire the effects.
+  const onLoadRef = useRef(onLoad);
+  const onErrorRef = useRef(onError);
+  useEffect(() => {
+    onLoadRef.current = onLoad;
+    onErrorRef.current = onError;
+  });
+  useEffect(() => {
+    if (image) onLoadRef.current?.(image);
+  }, [image]);
+  useEffect(() => {
+    if (error) onErrorRef.current?.(error);
+  }, [error]);
+
+  const handleLayout = (event: LayoutChangeEvent) => {
+    onLayout?.(event);
+    const { width, height } = event.nativeEvent.layout;
+    const next = resizeForLayout(width, height);
+    // Always record it (even when a numeric style is in charge) so a later
+    // switch to a non-numeric style has a size to fall back on.
+    setLayoutSize((prev) => (sameSize(prev, next) ? prev : next));
+  };
+
+  return (
+    <NativeNitroImage
+      {...viewProps}
+      style={style}
+      onLayout={handleLayout}
+      image={image}
+    />
+  );
+}

package/src/index.ts

@@ -1,127 +1,14 @@
-import { useEffect, useRef, useState } from 'react';
-import type { Image } from 'react-native-nitro-image';
-import { NitroModules } from 'react-native-nitro-modules';
-
-import type {
+export { NitroImagePipeline } from './NitroImagePipeline';
+export { PipelineImage, type PipelineImageProps } from './PipelineImage';
+export {
+  cornerRadiusForStyle,
+  resizeForLayout,
+  resizeForStyle,
+} from './resizeForStyle';
+export type {
   CacheOption,
   CornerRadii,
-  NitroImagePipeline as NitroImagePipelineSpec,
   Options,
+  ResizeOptions,
 } from './specs/nitro-image-toolkit.nitro';
-
-export type { CacheOption, CornerRadii, Options };
-
-export const NitroImagePipeline =
-  NitroModules.createHybridObject<NitroImagePipelineSpec>('NitroImagePipeline');
-
-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,
-  cache,
-}: {
-  url: string;
-  /**
-   * Gaussian blur strength, as the standard deviation (sigma) of the blur in
-   * source-image pixels. Matches across iOS and Android; roughly half of
-   * React Native's `blurRadius`.
-   */
-  blur?: number;
-  /**
-   * Corner radius in points, baked into 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).
-   */
-  cornerRadius?: number | CornerRadii;
-  cache?: CacheOption;
-}): 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;
-
-  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 });
-    }
-
-    (async () => {
-      try {
-        const result = await NitroImagePipeline.loadImage(url, {
-          blur,
-          cornerRadius: isUniformRadius
-            ? uniformRadius
-            : { topLeft, topRight, bottomLeft, bottomRight },
-          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,
-    cache,
-  ]);
-
-  return image;
-}
+export { useImage } from './useImage';

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/specs/nitro-image-toolkit.nitro.ts

@@ -4,7 +4,8 @@ import type { HybridObject } from 'react-native-nitro-modules';
 export type CacheOption = 'memory' | 'disk' | 'none';
 
 /**
- * Independent corner radii in points. Omitted corners stay square.
+ * Independent corner radii, in pixels of the loaded bitmap (see
+ * {@linkcode Options.cornerRadius}). Omitted corners stay square.
  */
 export interface CornerRadii {
   topLeft?: number;
@@ -13,12 +14,25 @@ export interface CornerRadii {
   bottomRight?: number;
 }
 
+/**
+ * Target bitmap size in pixels. The image is scaled to fill this size and
+ * center-cropped (like CSS `object-fit: cover`), upscaling if needed, so the
+ * result is exactly `width` × `height` pixels.
+ */
+export interface ResizeOptions {
+  width: number;
+  height: number;
+}
+
 export type Options = {
   /**
    * Gaussian blur strength, given as the standard deviation (sigma) of the
    * blur in **source-image pixels**. The same value on the same source image
    * produces the same result on iOS and Android.
    *
+   * When {@linkcode resize} is set, the blur runs after resizing, so sigma is
+   * in pixels of the resized bitmap instead.
+   *
    * React Native's `<Image blurRadius={n} />` is roughly `blur: n / 2`.
    *
    * @default 0 (no blur)
@@ -26,14 +40,29 @@ export type Options = {
   blur?: number;
   cache?: CacheOption;
   /**
-   * Corner radius in points, baked into the loaded bitmap. Pass a single
-   * number to round all four corners uniformly, or a {@linkcode CornerRadii}
-   * object to round each corner independently (e.g. a "ticket" shape with
-   * larger bottom corners).
+   * Corner radius baked into the loaded bitmap, in **pixels of that bitmap**.
+   * Pass a single number to round all four corners uniformly, or a
+   * {@linkcode CornerRadii} object to round each corner independently (e.g. a
+   * "ticket" shape with larger bottom corners).
+   *
+   * Without {@linkcode resize} the radius applies to the full-resolution
+   * source image, so on a large photo displayed small the rounding shrinks
+   * along with it. To get corners sized for your layout, pass `resize` with
+   * your display size in pixels (points × screen scale) — the radii then
+   * apply to that final bitmap, 1:1 with what you see.
    *
    * @default 0 (square corners)
    */
   cornerRadius?: number | CornerRadii;
+  /**
+   * Resize the image to exactly this size in pixels (aspect-fill,
+   * center-crop) before `blur` and `cornerRadius` are applied. Besides making
+   * `cornerRadius` predictable, this avoids decoding and processing
+   * full-resolution bitmaps you only display small.
+   *
+   * @default undefined (keep the source size)
+   */
+  resize?: ResizeOptions;
 };
 
 export interface NitroImagePipeline extends HybridObject<{