react-native-fast-image 10.4.0 → 10.6.0

package/src/index.tsx

@@ -16,7 +16,12 @@ import { fromStyle, resolveObjectFit } from './objectFit'
 import { objectPositionOrCentered, type ObjectPosition } from './objectPosition'
 import FastImageView from './specs/FastImageViewNativeComponent'
 import NativeFastImageModule from './specs/NativeFastImageModule'
-import { dataUri, hasSourcePlaceholder, isImageName } from './placeholders'
+import {
+    dataUri,
+    hasSourcePlaceholder,
+    isImageName,
+    placeholderSource,
+} from './placeholders'
 import { warnIfChildren, warnOnce } from './warnings'
 
 /** How the image fits the view: see [`objectFit`](#objectfit). */
@@ -175,6 +180,12 @@ export type Source = {
 /** A `thumbhash` or `blurDataUri` as `placeholder`. */
 export type SourcePlaceholder = Pick<Source, 'thumbhash' | 'blurDataUri'>
 
+/** A url as `placeholder`, loaded like a source (see `placeholder`). */
+export type PlaceholderSource = Pick<
+    Source,
+    'uri' | 'headers' | 'cacheKey' | 'cache'
+>
+
 /** How the image fades in: see [`transition`](#transition). */
 export type Transition = {
     /**
@@ -351,9 +362,10 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * - `FastImage.preload`, `getCachePath` and `writeToCache` take one size:
      *   pass the one a view will show. An array fails with
      *   `{ ok: false, error }`.
+     * - A `require()`d image can be one of the sizes: its size is the file's.
      * - An array of one is the same as that source.
      */
-    source?: Source | Source[] | ImageRequireSource
+    source?: Source | Array<Source | ImageRequireSource> | ImageRequireSource
     /**
      * A placeholder shown while the image loads, and if it fails to load:
      *
@@ -365,19 +377,30 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      *   `placeholder={{ thumbhash }}`.
      * - A tiny image as a data uri, shown blurred:
      *   `placeholder={{ blurDataUri }}`.
+     * - A url, loaded and cached like a source:
+     *   `placeholder="https://example.com/placeholder.png"`, or a source with
+     *   `headers` or a `cacheKey`: `placeholder={{ uri, headers }}`.
+     * - A url only shown if it's already cached, e.g. a list's thumbnail while
+     *   the full-size image loads: `placeholder={{ uri, cache: 'cacheOnly' }}`.
      *
      * A source's own `thumbhash` or `blurDataUri` is shown instead, if it has
-     * one.
+     * one; a url placeholder shows over it once it has loaded.
      *
      * Notes:
      *
-     * - A url isn't loaded: it's ignored, with a warning in development.
      * - On Android, a `require()`d image doesn't show in debug builds, where
      *   the dev server serves it. Release builds show it.
+     * - On the web, a url loads like any image, also with `'cacheOnly'`: a
+     *   browser can't look only in its cache.
      */
-    placeholder?: ImageRequireSource | string | SourcePlaceholder
+    placeholder?:
+        | ImageRequireSource
+        | string
+        | SourcePlaceholder
+        | PlaceholderSource
     /**
-     * @deprecated Use `placeholder`, which does the same.
+     * @deprecated Use `placeholder`, which does the same. With both,
+     * `placeholder` shows.
      */
     defaultSource?: ImageRequireSource
     /**
@@ -686,27 +709,9 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
     children?: "FastImage doesn't take children: use FastImageBackground for content over an image"
 }
 
-// A source without its thumbhash and blurDataUri.
-function withoutPlaceholders<T>(source: T): T {
-    if (!hasSourcePlaceholder(source)) return source
-    const {
-        thumbhash: _thumbhash,
-        blurDataUri: _blurDataUri,
-        ...rest
-    } = source as Source
-    return rest as T
-}
-
-// What the native view shows while a source loads: its ThumbHash (decoded
-// natively), or its blurDataUri, or '' for neither.
-function sourcePlaceholder(source: unknown): string {
-    if (!source || typeof source !== 'object') return ''
-    const { thumbhash, blurDataUri } = source as Source
-    return thumbhash || dataUri(blurDataUri) || ''
-}
-
 const resolvePlaceholder = (
-    placeholder?: ImageRequireSource | string,
+    // A source object here has no url (e.g. { uri: name }, a bundled image).
+    placeholder?: ImageRequireSource | string | PlaceholderSource,
 ): string | object | null => {
     if (typeof placeholder === 'string') {
         // An image bundled with the app, by name, as React Native's Image
@@ -725,7 +730,9 @@ const resolvePlaceholder = (
     if (!placeholder) {
         return null
     }
-    const resolved = Image.resolveAssetSource(placeholder)
+    const resolved = Image.resolveAssetSource(
+        placeholder as ImageRequireSource | { uri: string },
+    )
     if (!resolved) {
         return null
     }
@@ -887,49 +894,32 @@ function FastImageBase({
     const fit = resolveObjectFit(objectFit, style)
     const position = objectPositionOrCentered(objectPosition)
 
-    // Memoized on source, so an unchanged source reaches the native view as
-    // the same objects, and React's prop diff stops at them.
-    // `placeholder` as a thumbhash or blurDataUri, for the sources without
-    // their own: a string, so an object made on every render doesn't make
-    // new sourcePlaceholders.
-    const shared = hasSourcePlaceholder(placeholder)
-        ? sourcePlaceholder(placeholder)
-        : ''
-    const { resolvedSource, sources, sourcePlaceholders } = useMemo(() => {
-        // Several sources are picked from natively, for the view's size; one
-        // in an array is a plain source.
-        const sources = Array.isArray(source)
-            ? source.length === 1
-                ? undefined
-                : source
-            : undefined
-        const single = Array.isArray(source) ? source[0] : source
-        // Sources' thumbhashes and blurDataUris go to the native view apart
-        // from the sources, so a new one for the same image doesn't load it
-        // again, by the source's index ('' for none). A source's own wins
-        // over `placeholder`'s.
-        const placeholders = (sources ?? [single]).map(
-            (entry) => sourcePlaceholder(entry) || shared,
-        )
-        return {
-            resolvedSource: sources
-                ? undefined
-                : Image.resolveAssetSource(withoutPlaceholders(single) as any),
-            sources: sources?.some(hasSourcePlaceholder)
-                ? sources.map(withoutPlaceholders)
-                : sources,
-            sourcePlaceholders: placeholders.some(Boolean)
-                ? placeholders
-                : undefined,
+    // One source, or several in an array, picked from natively for the
+    // view's size (one in an array is a plain source), with their thumbhashes
+    // and blurDataUris: the native view doesn't load the image again when
+    // only those change. Memoized on source, so an unchanged source reaches
+    // the native view as the same object, and React's prop diff stops at it.
+    const resolvedSource = useMemo(() => {
+        // A blurDataUri that isn't a data uri is ignored, with a warning.
+        for (const entry of [source].flat()) {
+            dataUri((entry as Source | undefined)?.blurDataUri)
         }
-    }, [source, shared])
-    // A thumbhash or blurDataUri in `placeholder` goes in sourcePlaceholders
-    // instead: it isn't an image to show as it is, but defaultSource still is.
-    const resolvedPlaceholder = resolvePlaceholder(
-        hasSourcePlaceholder(placeholder)
-            ? defaultSource
-            : (placeholder ?? defaultSource),
-    )
+        const single =
+            Array.isArray(source) && source.length === 1 ? source[0] : source
+        return Array.isArray(single)
+            ? single.map((entry) => Image.resolveAssetSource(entry as any))
+            : Image.resolveAssetSource(single as any)
+    }, [source])
+    // `placeholder` as the native view takes it: a thumbhash or blurDataUri
+    // as it is (for the sources without their own), a url as a source loaded
+    // apart from the image, or an image shown at once. defaultSource only
+    // applies without one (an empty thumbhash or blurDataUri is none).
+    const resolvedPlaceholder = hasSourcePlaceholder(placeholder)
+        ? placeholder.thumbhash || dataUri(placeholder.blurDataUri)
+            ? placeholder
+            : resolvePlaceholder(defaultSource)
+        : (placeholderSource(placeholder) ??
+          resolvePlaceholder(placeholder ?? defaultSource))
 
     return (
         <FastImageView
@@ -946,8 +936,6 @@ function FastImageBase({
                 defaultTransition ?? builtInTransition(),
             )}
             source={resolvedSource}
-            sources={sources}
-            sourcePlaceholders={sourcePlaceholders}
             placeholder={resolvedPlaceholder}
             onFastImageLoadStart={onLoadStart}
             onFastImageProgress={onProgress}

package/src/index.web.tsx

@@ -32,7 +32,11 @@ import { getAssetByID } from 'react-native-web/dist/modules/AssetRegistry'
 import { cacheControl, priority, resizeMode } from './constants'
 import { resolveObjectFit } from './objectFit'
 import { cssPosition, objectPositionOrCentered } from './objectPosition'
-import { dataUri, hasSourcePlaceholder } from './placeholders'
+import {
+    dataUri,
+    hasSourcePlaceholder,
+    placeholderSource,
+} from './placeholders'
 import { warnIfChildren, warnOnce } from './warnings'
 import type {
     CachePathResult,
@@ -132,11 +136,24 @@ function FastImageBase({
     const blurUri =
         resolveUri(dataUri(shared(source, 'blurDataUri', preview))) ??
         thumbhashUri(shared(source, 'thumbhash', preview))
-    // A thumbhash or blurDataUri in `placeholder` isn't an image to show as it
-    // is: defaultSource still is.
+    // `placeholder` as a url (or a source with one) shows over the other
+    // placeholders as it loads, as on iOS and Android. The browser loads it
+    // like any image: it can't look in its cache only (cache: 'cacheOnly').
+    const urlPlaceholder = placeholderSource(placeholder)?.uri
+    const [failedPlaceholder, setFailedPlaceholder] = useState<string>()
+    // defaultSource only shows without `placeholder`, as on iOS and Android,
+    // or in place of a thumbhash or blurDataUri the web can't show (one of
+    // several sizes', or a thumbhash without react-native-fast-image/thumbhash,
+    // or an empty one). Not with a url (above).
     const defaultUri =
         blurUri ??
-        resolveUri(preview ? defaultSource : (placeholder ?? defaultSource))
+        resolveUri(
+            preview
+                ? defaultSource
+                : urlPlaceholder
+                  ? undefined
+                  : (placeholder ?? defaultSource),
+        )
     // Whether the image for `key` loaded, or failed.
     const [result, setResult] = useState<{ key: string; ok: boolean }>()
     const ok = result && result.key === key ? result.ok : undefined
@@ -156,7 +173,7 @@ function FastImageBase({
             .filter(Boolean)
             .join(' ') || undefined
     // The placeholder shows until the image has loaded, and if it fails.
-    const showDefault = !!defaultUri && ok !== true
+    const showDefault = ok !== true
 
     useClientLayoutEffect(() => {
         if (key) onLoadStart?.()
@@ -207,6 +224,28 @@ function FastImageBase({
                     alt={key ? '' : (label ?? '')}
                 />
             ) : null}
+            {urlPlaceholder && showDefault ? (
+                <Picture
+                    key={`placeholder ${urlPlaceholder}`}
+                    src={urlPlaceholder}
+                    loading={loading}
+                    // It only helps if it comes before the image, as on iOS
+                    // and Android.
+                    priority="high"
+                    dynamicRangeLimit={dynamicRangeLimit}
+                    // It stands for the image, as a source's preview does.
+                    fit={
+                        fit === 'scale-down' || fit === 'none' ? 'contain' : fit
+                    }
+                    position={position}
+                    // Tinted, not blurred, as on iOS and Android.
+                    filter={tintColor ? `url(#${tintId})` : undefined}
+                    // Nothing (no broken image icon) if it fails.
+                    hidden={failedPlaceholder === urlPlaceholder}
+                    onError={() => setFailedPlaceholder(urlPlaceholder)}
+                    alt=""
+                />
+            ) : null}
             {key && src ? (
                 <Picture
                     key={several ? 'sizes' : key}
@@ -306,14 +345,7 @@ function resolveUri(source: unknown): string | undefined {
     if (typeof source === 'number') {
         const asset: PackagerAsset | undefined = getAssetByID(source)
         if (!asset) return undefined
-        const scale = asset.scales.reduce(
-            (best, scale) =>
-                Math.abs(scale - PixelRatio.get()) <
-                Math.abs(best - PixelRatio.get())
-                    ? scale
-                    : best,
-            asset.scales[0] ?? 1,
-        )
+        const scale = assetScale(asset)
         const suffix = scale !== 1 ? `@${scale}x` : ''
         uri = `${asset.httpServerLocation}/${asset.name}${suffix}.${asset.type}`
     } else if (typeof source === 'string') {
@@ -335,6 +367,36 @@ type PackagerAsset = {
     name: string
     type: string
     scales: number[]
+    width?: number
+    height?: number
+}
+
+// The scale of an asset's file closest to the screen's.
+function assetScale(asset: PackagerAsset): number {
+    return asset.scales.reduce(
+        (best, scale) =>
+            Math.abs(scale - PixelRatio.get()) <
+            Math.abs(best - PixelRatio.get())
+                ? scale
+                : best,
+        asset.scales[0] ?? 1,
+    )
+}
+
+// One of several sizes: a require()d image in react-native-web's asset
+// registry as a source with its file's size (Expo's web builds make it a
+// { uri, width, height } object already).
+function sizedSource(source: Source | number): Source | undefined {
+    if (typeof source !== 'number') return source
+    const asset: PackagerAsset | undefined = getAssetByID(source)
+    return asset
+        ? {
+              uri: resolveUri(source),
+              width: asset.width,
+              height: asset.height,
+              scale: assetScale(asset),
+          }
+        : undefined
 }
 
 // Several sizes of an image, as a srcset (each size's width, times its
@@ -344,9 +406,10 @@ type PackagerAsset = {
 // is laid out at; it only applies to lazy images, and otherwise, or in
 // browsers without it, the next value, 100vw (the viewport's width). src is the largest, for browsers without
 // srcset.
-function sizedSources(sources: Source[]) {
+function sizedSources(entries: (Source | number)[]) {
+    const sources = entries.map(sizedSource)
     const widths = sources
-        .filter((source) => source?.uri && source.width)
+        .filter((source): source is Source => !!source?.uri && !!source.width)
         .map((source) => ({
             uri: source.uri as string,
             width: Math.round((source.width ?? 0) * (source.scale ?? 1)),

package/src/placeholders.ts

@@ -1,20 +1,37 @@
-// Placeholders given as strings (`placeholder`, and a source's `blurDataUri`)
-// are data uris, shared by the native (index.tsx) and web (index.web.tsx)
-// versions, or for `placeholder`, the name of an image bundled with the app.
-// They're decoded at once, so they show in the view's first frame; a url
-// would load like an image (and on iOS and Android, not at all), so it's
-// ignored, with a warning in development.
-import type { SourcePlaceholder } from './index'
+// Placeholders given as strings, shared by the native (index.tsx) and web
+// (index.web.tsx) versions: a source's `blurDataUri` is a data uri, decoded at
+// once, so it shows in the view's first frame (a url there is ignored, with a
+// warning in development). `placeholder` can also be the name of an image
+// bundled with the app, or a url, loaded as a source (placeholderSource).
+import type { PlaceholderSource, SourcePlaceholder } from './index'
 import { warnOnce } from './warnings'
 
 // Metro's (and React Native's Jest preset's) development flag; other web
 // bundlers may not define it.
 declare const __DEV__: boolean | undefined
 
+const SCHEME = /^[a-z][a-z\d+.-]*:/i
+
 // Whether `placeholder` is the name of an image bundled with the app (an iOS
 // asset catalog image, an Android drawable): no scheme, not a path.
 export function isImageName(value: string): boolean {
-    return !/^[a-z][a-z\d+.-]*:/i.test(value) && !value.startsWith('/')
+    return !SCHEME.test(value) && !value.startsWith('/')
+}
+
+// `placeholder` as a source to load: an http or https url, as a string or a
+// source object's uri. Undefined for anything else (a local file or a data uri
+// is decoded at once, as the native placeholder prop).
+export function placeholderSource(
+    value: unknown,
+): PlaceholderSource | undefined {
+    const uri =
+        typeof value === 'string'
+            ? value
+            : value && typeof value === 'object'
+              ? (value as PlaceholderSource).uri
+              : undefined
+    if (typeof uri !== 'string' || !/^https?:/i.test(uri)) return undefined
+    return typeof value === 'string' ? { uri } : (value as PlaceholderSource)
 }
 
 // Whether a source has a thumbhash or blurDataUri, or `placeholder` is one
@@ -37,7 +54,7 @@ export function dataUri(value: unknown): string | undefined {
     if (typeof __DEV__ !== 'undefined' && __DEV__) {
         warnOnce(
             'placeholder-url',
-            `react-native-fast-image: \`placeholder\` and \`blurDataUri\` don't load urls: "${value.slice(0, 60)}" is ignored. Use a data uri (data:image/…), or for \`placeholder\`, a require()d image or the name of an image bundled with the app.`,
+            `react-native-fast-image: \`blurDataUri\` takes a data uri (data:image/…): "${value.slice(0, 60)}" is ignored. For a placeholder loaded from a url, use \`placeholder\`.`,
             'warn',
         )
     }

package/src/specs/FastImageViewNativeComponent.ts

@@ -40,19 +40,18 @@ type LoadEndEvent = Readonly<{
 }>
 
 export interface NativeProps extends ViewProps {
-    // A source ({ uri, headers, priority, cache, ... }), as the native
-    // sides read it.
+    // The `source` prop: a source ({ uri, headers, priority, cache, ... },
+    // with its thumbhash or blurDataUri), or several (sizes of one image) in
+    // an array, picked from for the view's size. A change to the thumbhashes
+    // and blurDataUris only doesn't load the image again.
     source?: CodegenTypes.UnsafeMixed
-    // Several sources (sizes of one image), picked from for the view's size.
-    sources?: CodegenTypes.UnsafeMixed
-    // The `placeholder` prop: a resolved asset source ({ uri, width, height,
-    // scale }) or a data uri ({ uri } on iOS; the uri on Android).
+    // The `placeholder` prop: a thumbhash or blurDataUri ({ thumbhash } or
+    // { blurDataUri }, for the sources without their own), a url to load
+    // apart from the image, as a source ({ uri, headers, cacheKey, cache }),
+    // or an image shown at once: a resolved asset source ({ uri, width,
+    // height, scale }) or a data uri ({ uri } on iOS; the uri on Android, as
+    // a string).
     placeholder?: CodegenTypes.UnsafeMixed
-    // What shows in place of placeholder while a source loads: its ThumbHash,
-    // or its blurDataUri (blurred natively), by the source's index ('' for
-    // none; one for a single source). Apart from the sources, so a new one
-    // for the same image doesn't load it again.
-    sourcePlaceholders?: ReadonlyArray<string>
     // objectFit, resolved (fill, contain, cover, none or scale-down).
     objectFit?: CodegenTypes.WithDefault<string, 'cover'>
     // objectPosition, as CSS computes it: on each axis the image's left or top