react-native-nitro-image-pipeline 1.4.0 → 1.5.0

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

@@ -0,0 +1,104 @@
+///
+/// ViewOptions.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
+
+// Forward declaration of `CacheOption` to properly resolve imports.
+namespace margelo::nitro::nitroimagepipeline { enum class CacheOption; }
+// Forward declaration of `CornerRadii` to properly resolve imports.
+namespace margelo::nitro::nitroimagepipeline { struct CornerRadii; }
+// Forward declaration of `ResizeOptions` to properly resolve imports.
+namespace margelo::nitro::nitroimagepipeline { struct ResizeOptions; }
+
+#include <optional>
+#include "CacheOption.hpp"
+#include "CornerRadii.hpp"
+#include <variant>
+#include "ResizeOptions.hpp"
+
+namespace margelo::nitro::nitroimagepipeline {
+
+  /**
+   * A struct which can be represented as a JavaScript object (ViewOptions).
+   */
+  struct ViewOptions final {
+  public:
+    std::optional<double> blur     SWIFT_PRIVATE;
+    std::optional<CacheOption> cache     SWIFT_PRIVATE;
+    std::optional<std::variant<double, CornerRadii>> cornerRadius     SWIFT_PRIVATE;
+    std::optional<ResizeOptions> resize     SWIFT_PRIVATE;
+
+  public:
+    ViewOptions() = default;
+    explicit ViewOptions(std::optional<double> blur, std::optional<CacheOption> cache, std::optional<std::variant<double, CornerRadii>> cornerRadius, std::optional<ResizeOptions> resize): blur(blur), cache(cache), cornerRadius(cornerRadius), resize(resize) {}
+
+  public:
+    friend bool operator==(const ViewOptions& lhs, const ViewOptions& rhs) = default;
+  };
+
+} // namespace margelo::nitro::nitroimagepipeline
+
+namespace margelo::nitro {
+
+  // C++ ViewOptions <> JS ViewOptions (object)
+  template <>
+  struct JSIConverter<margelo::nitro::nitroimagepipeline::ViewOptions> final {
+    static inline margelo::nitro::nitroimagepipeline::ViewOptions fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::nitroimagepipeline::ViewOptions(
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "blur"))),
+        JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::CacheOption>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cache"))),
+        JSIConverter<std::optional<std::variant<double, margelo::nitro::nitroimagepipeline::CornerRadii>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cornerRadius"))),
+        JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "resize")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::nitroimagepipeline::ViewOptions& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "blur"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.blur));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cache"), JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::CacheOption>>::toJSI(runtime, arg.cache));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cornerRadius"), JSIConverter<std::optional<std::variant<double, margelo::nitro::nitroimagepipeline::CornerRadii>>>::toJSI(runtime, arg.cornerRadius));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "resize"), JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::toJSI(runtime, arg.resize));
+      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<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "blur")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::CacheOption>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cache")))) return false;
+      if (!JSIConverter<std::optional<std::variant<double, margelo::nitro::nitroimagepipeline::CornerRadii>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cornerRadius")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::nitroimagepipeline::ResizeOptions>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "resize")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-image-pipeline",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "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",
@@ -17,7 +17,8 @@
     "release": "semantic-release",
     "build": "bun run typecheck && bob build",
     "codegen": "nitrogen --logLevel=\"debug\" && bun run build",
-    "verify:blur": "swiftc -O -o \"${TMPDIR:-/tmp}/nitro-verify-blur\" scripts/verify-blur.swift ios/GaussianBlur.swift && \"${TMPDIR:-/tmp}/nitro-verify-blur\""
+    "fixtures": "bun scripts/fixture-server.ts",
+    "verify:blur": "sh scripts/verify-blur.sh"
   },
   "keywords": [
     "react-native",
@@ -83,7 +84,7 @@
     "react": "*",
     "react-native": "*",
     "react-native-nitro-modules": "*",
-    "react-native-nitro-image": "0.15.1"
+    "react-native-nitro-image": ">=0.15.1 <0.16.0"
   },
   "overrides": {
     "lodash-es": "4.17.21",

package/src/NativePipelineImage.tsx

@@ -0,0 +1,103 @@
+import { type ComponentRef, forwardRef } from 'react';
+import type { HostComponent } from 'react-native';
+import { NativeNitroImage } from 'react-native-nitro-image';
+
+import { cornerRadiusForStyle } from './resizeForStyle';
+import type {
+  CacheOption,
+  CornerRadii,
+  ResizeOptions,
+} from './specs/nitro-image-toolkit.nitro';
+import { usePipelineImageLoader } from './usePipelineImageLoader';
+
+type ReactProps<T> = T extends HostComponent<infer P> ? P : never;
+type NativeImageProps = ReactProps<typeof NativeNitroImage>;
+
+/**
+ * The instance `<NativePipelineImage>` exposes through its `ref` — the
+ * underlying `NativeNitroImage` host view, with the usual native-view
+ * methods (`measure`, …).
+ */
+export type NativePipelineImageRef = ComponentRef<typeof NativeNitroImage>;
+
+export interface NativePipelineImageProps extends Omit<
+  NativeImageProps,
+  'image'
+> {
+  /** URL of the image to load through the pipeline. */
+  url: string;
+  /**
+   * Gaussian blur sigma in **points** (density-independent), like
+   * `PipelineImage`. Applied natively with the screen scale.
+   * @default 0
+   */
+  blur?: number;
+  /**
+   * Corner radius in **points** — a single number or per-corner radii.
+   * When omitted, it's derived from `style`'s `borderRadius`-family
+   * properties instead — set this prop to override that.
+   * @default undefined (derived from `style`, or square corners if unset there)
+   */
+  cornerRadius?: number | CornerRadii;
+  cache?: CacheOption;
+  /**
+   * Target bitmap size in **pixels**, overriding the size the native side
+   * measures from the view. Rarely needed.
+   * @default undefined (measure the view natively)
+   */
+  resize?: ResizeOptions;
+}
+
+/**
+ * The fully native-driven variant of `PipelineImage`: after the first render
+ * there is **zero JS work per image**. The native view starts the request
+ * when it attaches to the window — at its own laid-out size, so nothing
+ * waits for an `onLayout` round trip — and cancels it (releasing the bitmap)
+ * when it detaches, which makes off-screen list cells free. Loads go through
+ * the same pipeline and caches as `useImage`/`preLoadImage`.
+ *
+ * Compared to `PipelineImage`:
+ * - No `onLoad`/`onError` callbacks — the loaded `Image` never crosses into
+ *   JS. Use `PipelineImage` (or `useImage`) when you need them.
+ * - The bitmap is loaded once at the size the view first has; if the view is
+ *   resized later, the bitmap scales with it instead of reloading.
+ * @example
+ * ```tsx
+ * <NativePipelineImage
+ *   url="https://example.com/photo.jpg"
+ *   style={{ width: 300, height: 200, borderRadius: 24 }}
+ *   blur={4}
+ * />
+ * ```
+ */
+export const NativePipelineImage = forwardRef<
+  NativePipelineImageRef,
+  NativePipelineImageProps
+>(function NativePipelineImage(
+  { url, blur, cornerRadius, cache, resize, style, ...viewProps },
+  ref,
+) {
+  // Same precedence as PipelineImage: an explicit prop wins over style.
+  const effectiveCornerRadius = cornerRadius ?? cornerRadiusForStyle(style);
+  const loader = usePipelineImageLoader(url, {
+    blur,
+    cornerRadius: effectiveCornerRadius,
+    cache,
+    resize,
+  });
+
+  return (
+    <NativeNitroImage
+      // Before the spread so a caller-provided recyclingKey wins.
+      recyclingKey={url}
+      {...viewProps}
+      ref={ref}
+      style={style}
+      image={loader}
+    />
+  );
+});
+
+// Reanimated and DevTools read the display name; the forwardRef wrapper
+// would otherwise report as anonymous.
+NativePipelineImage.displayName = 'NativePipelineImage';

package/src/index.ts

@@ -1,3 +1,8 @@
+export {
+  NativePipelineImage,
+  type NativePipelineImageProps,
+  type NativePipelineImageRef,
+} from './NativePipelineImage';
 export { NitroImagePipeline } from './NitroImagePipeline';
 export {
   PipelineImage,
@@ -14,5 +19,7 @@ export type {
   CornerRadii,
   Options,
   ResizeOptions,
+  ViewOptions,
 } from './specs/nitro-image-toolkit.nitro';
 export { useImage } from './useImage';
+export { usePipelineImageLoader } from './usePipelineImageLoader';

package/src/specs/nitro-image-toolkit.nitro.ts

@@ -1,4 +1,4 @@
-import type { Image } from 'react-native-nitro-image';
+import type { Image, ImageLoader } from 'react-native-nitro-image';
 import type { HybridObject } from 'react-native-nitro-modules';
 
 export type CacheOption = 'memory' | 'disk' | 'none';
@@ -65,11 +65,55 @@ export type Options = {
   resize?: ResizeOptions;
 };
 
+/**
+ * Options for {@linkcode NitroImagePipeline.createImageLoader}. Unlike
+ * {@linkcode Options} (used by `loadImage`, where values are bitmap pixels),
+ * `blur` and `cornerRadius` here are in **points** (density-independent):
+ * the loader runs inside a view and converts to pixels natively with the
+ * screen scale. The one exception is {@linkcode resize}, which stays an
+ * explicit **pixel** size like everywhere else in the library.
+ */
+export type ViewOptions = {
+  /**
+   * Gaussian blur sigma in **points**. Multiplied by the screen scale
+   * natively, so the same value looks the same on every device.
+   * @default 0 (no blur)
+   */
+  blur?: number;
+  cache?: CacheOption;
+  /**
+   * Corner radius in **points**, uniform or per-corner. Converted to pixels
+   * with the screen scale and baked into the bitmap at the display size.
+   * @default 0 (square corners)
+   */
+  cornerRadius?: number | CornerRadii;
+  /**
+   * Target bitmap size in **pixels**, overriding the size measured from the
+   * view. Rarely needed — without it the loader resizes to the view's
+   * laid-out size × screen scale, which is what you want in a UI.
+   * @default undefined (measure the view)
+   */
+  resize?: ResizeOptions;
+};
+
 export interface NitroImagePipeline extends HybridObject<{
   ios: 'swift';
   android: 'kotlin';
 }> {
   loadImage(url: string, options?: Options): Promise<Image>;
+  /**
+   * Creates an {@linkcode ImageLoader} for `url` that a `<NativeNitroImage>`
+   * view drives entirely natively: the request starts when the view attaches
+   * to the window — at the view's own laid-out size, with no JS round trips —
+   * and is cancelled (and the bitmap released) when it detaches, so
+   * off-screen list cells stop costing memory. Loads go through the same
+   * pipeline and caches as {@linkcode loadImage}/{@linkcode preLoadImage}.
+   *
+   * `options` are in **points** (see {@linkcode ViewOptions}); the loader
+   * applies the screen scale natively. If the view has no size yet when it
+   * attaches, the load waits for its first layout.
+   */
+  createImageLoader(url: string, options?: ViewOptions): ImageLoader;
   preLoadImage(url: string): Promise<void>;
   preLoadImages(urls: string[]): Promise<void>;
   /**

package/src/usePipelineImageLoader.ts

@@ -0,0 +1,82 @@
+import { useMemo } from 'react';
+import type { ImageLoader } from 'react-native-nitro-image';
+
+import { NitroImagePipeline } from './NitroImagePipeline';
+import type {
+  CornerRadii,
+  ViewOptions,
+} from './specs/nitro-image-toolkit.nitro';
+
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * `<NativeNitroImage image={...} />`. The view drives it entirely natively:
+ * the request starts when the view attaches — at the view's laid-out size,
+ * with no JS round trips — and is cancelled when it detaches. See
+ * {@linkcode NitroImagePipeline.createImageLoader}.
+ *
+ * `blur`/`cornerRadius` are in **points** (unlike `useImage`, where they are
+ * bitmap pixels); the screen scale is applied natively. Inline object
+ * literals are fine — options are compared by value, not identity.
+ */
+export function usePipelineImageLoader(
+  url: string,
+  options?: ViewOptions,
+): ImageLoader {
+  // Split the options into primitives (like useImage does) so an inline
+  // literal — a new identity every render — doesn't recreate the loader;
+  // recreating it would re-trigger the native load.
+  const blur = options?.blur;
+  const cache = options?.cache;
+  const cornerRadius = options?.cornerRadius;
+  const isUniformRadius = typeof cornerRadius === 'number';
+  const uniformRadius = isUniformRadius ? cornerRadius : 0;
+  const hasCornerObject = !isUniformRadius && cornerRadius !== undefined;
+  const {
+    topLeft = 0,
+    topRight = 0,
+    bottomLeft = 0,
+    bottomRight = 0,
+  } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
+  const resizeWidth = options?.resize?.width;
+  const resizeHeight = options?.resize?.height;
+
+  return useMemo(() => {
+    const cornerRadiusOption: number | CornerRadii | undefined = isUniformRadius
+      ? uniformRadius
+      : hasCornerObject
+        ? { topLeft, topRight, bottomLeft, bottomRight }
+        : undefined;
+    const stableOptions: ViewOptions = {
+      blur,
+      cache,
+      cornerRadius: cornerRadiusOption,
+      resize:
+        resizeWidth !== undefined && resizeHeight !== undefined
+          ? { width: resizeWidth, height: resizeHeight }
+          : undefined,
+    };
+    const loader = NitroImagePipeline.createImageLoader(url, stableOptions);
+    // `NativeNitroImage` needs a way to tell two loader instances apart when
+    // diffing its `image` prop; tag the loader with what it will load (the
+    // same convention react-native-nitro-image's own loaders use).
+    Object.defineProperty(loader, '__source', {
+      enumerable: true,
+      configurable: true,
+      value: { url, options: stableOptions },
+    });
+    return loader;
+  }, [
+    url,
+    blur,
+    cache,
+    isUniformRadius,
+    uniformRadius,
+    hasCornerObject,
+    topLeft,
+    topRight,
+    bottomLeft,
+    bottomRight,
+    resizeWidth,
+    resizeHeight,
+  ]);
+}