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

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

@@ -15,13 +15,46 @@ export interface CornerRadii {
 }
 
 /**
- * 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.
+ * How the source is fitted into the {@linkcode ResizeOptions} box. Mirrors
+ * `NativeNitroImage`'s `resizeMode`, so a view's `resizeMode` and the bitmap
+ * it displays can be derived from one value. With a `w` × `h` source and a
+ * `W` × `H` box, the produced bitmap is:
+ *
+ * - `cover`: scale by `max(W/w, H/h)`, center-crop → exactly `W` × `H`
+ *   (CSS `object-fit: cover`).
+ * - `contain`: scale by `min(W/w, H/h)` → `round(w·s)` × `round(h·s)`, the
+ *   largest size with the source's aspect ratio that fits the box. The
+ *   bitmap is *not* padded to the box.
+ * - `stretch`: scale each axis independently → exactly `W` × `H`, aspect
+ *   ratio ignored.
+ * - `center`: no scaling; center-crop to `min(w, W)` × `min(h, H)`. A source
+ *   smaller than the box is left untouched.
+ */
+export type ResizeFit = 'cover' | 'contain' | 'stretch' | 'center';
+
+/**
+ * Target bitmap size in pixels. By default 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; {@linkcode fit}
+ * selects the other resize modes.
  */
 export interface ResizeOptions {
   width: number;
   height: number;
+  /**
+   * How the source is fitted into `width` × `height` — see
+   * {@linkcode ResizeFit} for the size each mode produces.
+   * @default 'cover'
+   */
+  fit?: ResizeFit;
+  /**
+   * `false` never enlarges the source: the scale is clamped to at most 1 for
+   * `cover`, `contain` and `stretch`, so a source smaller than the box keeps
+   * its own size (and, under `cover`, is only cropped to the box). No effect
+   * on `center`, which never scales.
+   * @default true
+   */
+  allowUpscale?: boolean;
 }
 
 export type Options = {
@@ -55,10 +88,11 @@ export type Options = {
    */
   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.
+   * Resize the image into this box in pixels — aspect-fill + center-crop by
+   * default, or another {@linkcode ResizeFit} — 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)
    */
@@ -90,16 +124,65 @@ export type ViewOptions = {
   /**
    * 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.
+   * laid-out size × screen scale, which is what you want in a UI. Its own
+   * `fit`/`allowUpscale`, when set, win over the top-level ones below.
    * @default undefined (measure the view)
    */
   resize?: ResizeOptions;
+  /**
+   * How the source is fitted into the box the loader resizes to (the view's
+   * size, or {@linkcode resize}) — see {@linkcode ResizeFit}. Pass the view's
+   * `resizeMode` so the bitmap matches how the view displays it.
+   * @default 'cover'
+   */
+  fit?: ResizeFit;
+  /**
+   * `false` never enlarges the source — see
+   * {@linkcode ResizeOptions.allowUpscale}.
+   * @default true
+   */
+  allowUpscale?: boolean;
+  /**
+   * Called when a view finishes displaying the image, with the size of the
+   * bitmap it displays in **pixels**.
+   *
+   * The bitmap itself deliberately stays native — passing the `Image` into JS
+   * would keep it alive there and defeat the point of the native path. Use
+   * `useImage`/`loadImage` when you need the `Image` object.
+   *
+   * This reports "the view is now showing this image", not a one-shot event:
+   * a loader is per URL + options, not per view, so every view using it
+   * reports, a recycled cell reports again when it re-attaches, and a single
+   * view can report more than once (it requests the image both when its
+   * `image` prop is set and when it becomes visible). Memory-cache hits, which
+   * resolve synchronously, report too. It does not fire for imperative loads
+   * through `ImageLoader.loadImage()` — those resolve through their promise.
+   *
+   * Setting it means there *is* per-image JS work; leave it unset and the
+   * native path stays free of JS round trips entirely.
+   * @default undefined (nothing crosses into JS)
+   */
+  onLoad?: (width: number, height: number) => void;
+  /**
+   * Called when a view fails to load the image, with the underlying error's
+   * message. Cancelling a load (the view detaching before it finishes) is not
+   * a failure and does not call this.
+   * @default undefined (failures are silent)
+   */
+  onError?: (message: string) => void;
 };
 
 export interface NitroImagePipeline extends HybridObject<{
   ios: 'swift';
   android: 'kotlin';
 }> {
+  /**
+   * Loads `url` through the pipeline. Besides `http(s)://`, `url` may be a
+   * `file://` URL or a plain absolute path (read from the file system, cached
+   * in memory only), a `data:` URL, or — on Android — a `content://` URI or
+   * the bare resource name a `require()` resolves to in a release build. Use
+   * `resolveImageUrl(require('./photo.png'))` to pass a bundled asset.
+   */
   loadImage(url: string, options?: Options): Promise<Image>;
   /**
    * Creates an {@linkcode ImageLoader} for `url` that a `<NativeNitroImage>`
@@ -114,6 +197,11 @@ export interface NitroImagePipeline extends HybridObject<{
    * attaches, the load waits for its first layout.
    */
   createImageLoader(url: string, options?: ViewOptions): ImageLoader;
+  /**
+   * Warms the disk cache with the download for `url`, without decoding it.
+   * Local sources (`file://`, paths, resources) have no download to warm it
+   * with and are a no-op.
+   */
   preLoadImage(url: string): Promise<void>;
   preLoadImages(urls: string[]): Promise<void>;
   /**

package/src/useImage.ts

@@ -2,6 +2,7 @@ import { useEffect, useRef, useState } from 'react';
 import type { Image } from 'react-native-nitro-image';
 
 import { NitroImagePipeline } from './NitroImagePipeline';
+import { type ImageSource, resolveImageUrl } from './resolveImageSource';
 import type {
   CacheOption,
   CornerRadii,
@@ -26,11 +27,12 @@ type Result =
     };
 
 /**
- * A hook to asynchronously load an image from the
- * given {@linkcode AsyncImageSource} into memory.
+ * A hook to asynchronously load an image from `url` through the pipeline
+ * into memory.
  * @example
  * ```ts
- * const { image, error } = useImage({ filePath: '/tmp/image.jpg' })
+ * const { image, error } = useImage({ url: 'https://example.com/photo.jpg' });
+ * const { image: logo } = useImage({ url: require('./logo.png') });
  * ```
  */
 export function useImage({
@@ -41,7 +43,11 @@ export function useImage({
   cache,
   enabled = true,
 }: {
-  url: string;
+  /**
+   * The image to load: a URL string (`https://`, `file://`, an absolute path)
+   * or a `require()`d asset — see {@linkcode ImageSource}.
+   */
+  url: ImageSource;
   /**
    * Gaussian blur strength, as the standard deviation (sigma) of the blur in
    * source-image pixels (of the resized bitmap when `resize` is set). Matches
@@ -56,8 +62,9 @@ export function useImage({
    */
   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
+   * Resize the bitmap into this box in pixels before blur/rounding —
+   * aspect-fill + center-crop by default, or another `fit` (see
+   * {@linkcode ResizeOptions}). Typically your display size in points
    * multiplied by `PixelRatio.get()`. Inline object literals are fine.
    */
   resize?: ResizeOptions;
@@ -89,6 +96,8 @@ export function useImage({
   } = isUniformRadius ? {} : cornerRadius;
   const resizeWidth = resize?.width ?? 0;
   const resizeHeight = resize?.height ?? 0;
+  const resizeFit = resize?.fit;
+  const resizeAllowUpscale = resize?.allowUpscale;
 
   useEffect(() => {
     let cancelled = false;
@@ -103,17 +112,27 @@ export function useImage({
     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,
-          });
+          // Resolved inside the try so an unregistered `require()` id
+          // surfaces as the error state instead of throwing from the effect.
+          const result = await NitroImagePipeline.loadImage(
+            resolveImageUrl(url),
+            {
+              blur,
+              cornerRadius: isUniformRadius
+                ? uniformRadius
+                : { topLeft, topRight, bottomLeft, bottomRight },
+              resize:
+                resizeWidth > 0 && resizeHeight > 0
+                  ? {
+                      width: resizeWidth,
+                      height: resizeHeight,
+                      fit: resizeFit,
+                      allowUpscale: resizeAllowUpscale,
+                    }
+                  : undefined,
+              cache,
+            },
+          );
 
           if (!cancelled) {
             setImage({ image: result, error: undefined });
@@ -141,6 +160,8 @@ export function useImage({
     bottomRight,
     resizeWidth,
     resizeHeight,
+    resizeFit,
+    resizeAllowUpscale,
     cache,
     enabled,
   ]);

package/src/usePipelineImageLoader.ts

@@ -1,14 +1,51 @@
-import { useMemo } from 'react';
+import { type RefObject, useLayoutEffect, useMemo, useRef } from 'react';
 import type { ImageLoader } from 'react-native-nitro-image';
 
 import { NitroImagePipeline } from './NitroImagePipeline';
+import {
+  type ImageSource,
+  resolveImageUrlOrFallback,
+} from './resolveImageSource';
 import type {
   CornerRadii,
   ViewOptions,
 } from './specs/nitro-image-toolkit.nitro';
 
+// Identifies a loader in the callbacks below without them capturing it. A
+// callback the native loader owns that captured the loader back would be a
+// cycle across the language boundary — neither side collectable, and the JS
+// runtime left to take it apart at teardown.
+let nextLoaderToken = 0;
+
+type Callbacks = Pick<ViewOptions, 'onLoad' | 'onError'>;
+
 /**
- * Creates (and memoizes) an {@linkcode ImageLoader} for `url` to pass to
+ * The callbacks handed to a native loader. Built out here, where the scope
+ * holds nothing but the token and the two refs, so the loader can't end up
+ * captured by a callback it owns.
+ */
+function makeReporters(
+  token: number,
+  activeToken: RefObject<number>,
+  callbacks: RefObject<Callbacks>,
+): Required<Callbacks> {
+  return {
+    onLoad: (width, height) => {
+      if (activeToken.current === token) {
+        callbacks.current.onLoad?.(width, height);
+      }
+    },
+    onError: (message) => {
+      if (activeToken.current === token) {
+        callbacks.current.onError?.(message);
+      }
+    },
+  };
+}
+
+/**
+ * Creates (and memoizes) an {@linkcode ImageLoader} for `source` — a URL
+ * string or a `require()`d asset, see {@linkcode ImageSource} — 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
@@ -16,10 +53,12 @@ import type {
  *
  * `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.
+ * literals are fine — options are compared by value, not identity, and the
+ * `onLoad`/`onError` callbacks are read through a ref, so inline arrows don't
+ * recreate the loader either.
  */
 export function usePipelineImageLoader(
-  url: string,
+  source: ImageSource,
   options?: ViewOptions,
 ): ImageLoader {
   // Split the options into primitives (like useImage does) so an inline
@@ -39,34 +78,93 @@ export function usePipelineImageLoader(
   } = isUniformRadius || cornerRadius === undefined ? {} : cornerRadius;
   const resizeWidth = options?.resize?.width;
   const resizeHeight = options?.resize?.height;
+  const resizeFit = options?.resize?.fit;
+  const resizeAllowUpscale = options?.resize?.allowUpscale;
+  const fit = options?.fit;
+  const allowUpscale = options?.allowUpscale;
+  const onLoad = options?.onLoad;
+  const onError = options?.onError;
+  // Only *whether* a callback is set can change the loader: what the native
+  // side gets is a wrapper that reads the latest callbacks from a ref (like
+  // PipelineImage does). So an inline arrow — a new identity every render —
+  // doesn't recreate the loader and re-trigger the native load.
+  const hasOnLoad = onLoad !== undefined;
+  const hasOnError = onError !== undefined;
+  const callbacks = useRef({ onLoad, onError });
+  // A layout effect, not a passive one: passive effects are flushed in a later
+  // task, so a load reported between the commit and that flush would read the
+  // previous render's callbacks — a callback added alongside a new loader
+  // could miss its only event. This runs in the same task as the commit, and
+  // the view can't reach the loader before the commit installs it, so the ref
+  // is always current by the time native calls back. (Assigning it during
+  // render instead would mutate on renders React throws away.)
+  useLayoutEffect(() => {
+    callbacks.current = { onLoad, onError };
+  });
+  // The token of the loader the view is currently on. Swapping loaders (a
+  // changed url or options) never drops the old one — the view just stops
+  // referring to it — so a load it already had in flight can still report.
+  // Without this check the wrappers, which read the latest callbacks, would
+  // hand the previous image's size to the current `onLoad`.
+  const activeToken = useRef(-1);
 
-  return useMemo(() => {
+  const memoized = useMemo(() => {
+    // Runs during render, so an unregistered `require()` id must not throw:
+    // it becomes a URL the native loader fails on at load time instead.
+    const url = resolveImageUrlOrFallback(source);
     const cornerRadiusOption: number | CornerRadii | undefined = isUniformRadius
       ? uniformRadius
       : hasCornerObject
         ? { topLeft, topRight, bottomLeft, bottomRight }
         : undefined;
+    // What is loaded — the callbacks are deliberately not part of it, so two
+    // loaders that differ only in them are the same image.
     const stableOptions: ViewOptions = {
       blur,
       cache,
       cornerRadius: cornerRadiusOption,
       resize:
         resizeWidth !== undefined && resizeHeight !== undefined
-          ? { width: resizeWidth, height: resizeHeight }
+          ? {
+              width: resizeWidth,
+              height: resizeHeight,
+              fit: resizeFit,
+              allowUpscale: resizeAllowUpscale,
+            }
           : undefined,
+      fit,
+      allowUpscale,
     };
-    const loader = NitroImagePipeline.createImageLoader(url, stableOptions);
+    const token = nextLoaderToken++;
+    // The reporters read the refs, but only when the native side calls them —
+    // the rule can't see that they aren't called here.
+    // oxlint-disable-next-line react/refs
+    const reporters = makeReporters(token, activeToken, callbacks);
+    const loader = NitroImagePipeline.createImageLoader(url, {
+      ...stableOptions,
+      // Passed only when the caller wants them: without a callback nothing
+      // ever crosses into JS, which is the point of the native path.
+      onLoad: hasOnLoad ? reporters.onLoad : undefined,
+      onError: hasOnError ? reporters.onError : undefined,
+    });
     // `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).
+    // same convention react-native-nitro-image's own loaders use). Toggling a
+    // callback on or off makes a different loader, so the tag has to say so —
+    // otherwise the view keeps the old one installed. Their identities stay
+    // out of it: those don't change what is loaded, or which loader this is.
     Object.defineProperty(loader, '__source', {
       enumerable: true,
       configurable: true,
-      value: { url, options: stableOptions },
+      value: {
+        url,
+        options: stableOptions,
+        callbacks: { onLoad: hasOnLoad, onError: hasOnError },
+      },
     });
-    return loader;
+    return { loader, token };
   }, [
-    url,
+    source,
     blur,
     cache,
     isUniformRadius,
@@ -78,5 +176,22 @@ export function usePipelineImageLoader(
     bottomRight,
     resizeWidth,
     resizeHeight,
+    resizeFit,
+    resizeAllowUpscale,
+    fit,
+    allowUpscale,
+    hasOnLoad,
+    hasOnError,
+    // Stable ref objects; listed to satisfy the exhaustive-deps rules.
+    activeToken,
+    callbacks,
   ]);
+
+  // Same reasoning as the callbacks ref: a layout effect is current before the
+  // view — which the commit has only just handed this loader — can report.
+  useLayoutEffect(() => {
+    activeToken.current = memoized.token;
+  }, [memoized, activeToken]);
+
+  return memoized.loader;
 }