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

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>;
   /**
@@ -80,5 +124,16 @@ export interface NitroImagePipeline extends HybridObject<{
   gaussianBlur(image: Image, radius: number): Promise<Image>;
   // Future: brightness, saturation, tint, etc.
 
+  /**
+   * Caps the in-memory cache of decoded bitmaps at `bytes`, evicting
+   * least-recently-used entries immediately if it is currently larger. Pass
+   * `0` to disable in-memory caching entirely (the disk cache still works).
+   *
+   * Defaults: 128 MB on iOS, 25% of the app's memory class on Android. The
+   * cache trades RAM for instant re-display; lower it (or use
+   * `cache: 'disk'` per request) in memory-constrained apps.
+   */
+  setMemoryCacheLimit(bytes: number): void;
+
   clearCache(): 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,
+  ]);
+}