react-native-fast-image 10.5.0 → 10.7.0

package/src/index.js.flow

@@ -145,7 +145,7 @@ export type FastImageProps = $ReadOnly<{|
     onLoadStart?: ?() => void,
     onProgress?: ?(event: OnProgressEvent) => void,
 
-    source?: ?(FastImageSource | Array<FastImageSource> | number),
+    source?: ?(FastImageSource | Array<FastImageSource | number> | number),
     placeholder?: ?(number | string | SourcePlaceholder | PlaceholderSource),
     // Deprecated: use placeholder, which is the same.
     defaultSource?: ?number,
@@ -196,4 +196,6 @@ declare export default class FastImage extends React$Component<FastImageProps> {
         source: FastImageSource,
         file: string,
     ) => Promise<CachePathResult>;
+    // On a ref: loads the image again, e.g. to try again after onError.
+    reload(): void;
 }

package/src/index.tsx

@@ -14,7 +14,7 @@ import {
 import { cacheControl, priority, resizeMode } from './constants'
 import { fromStyle, resolveObjectFit } from './objectFit'
 import { objectPositionOrCentered, type ObjectPosition } from './objectPosition'
-import FastImageView from './specs/FastImageViewNativeComponent'
+import FastImageView, { Commands } from './specs/FastImageViewNativeComponent'
 import NativeFastImageModule from './specs/NativeFastImageModule'
 import {
     dataUri,
@@ -22,6 +22,7 @@ import {
     isImageName,
     placeholderSource,
 } from './placeholders'
+import { composeRefs } from './composeRefs'
 import { warnIfChildren, warnOnce } from './warnings'
 
 /** How the image fits the view: see [`objectFit`](#objectfit). */
@@ -362,9 +363,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:
      *
@@ -398,7 +400,8 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
         | SourcePlaceholder
         | PlaceholderSource
     /**
-     * @deprecated Use `placeholder`, which does the same.
+     * @deprecated Use `placeholder`, which does the same. With both,
+     * `placeholder` shows.
      */
     defaultSource?: ImageRequireSource
     /**
@@ -707,25 +710,6 @@ 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 = (
     // A source object here has no url (e.g. { uri: name }, a bundled image).
     placeholder?: ImageRequireSource | string | PlaceholderSource,
@@ -911,58 +895,41 @@ 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 url in `placeholder` goes to the native view as a source, loaded
-    // apart from the image, in place of defaultSource. A thumbhash or
-    // blurDataUri goes in sourcePlaceholders instead: it isn't an image to
-    // show as it is, but defaultSource still is.
-    const resolvedPlaceholder =
-        placeholderSource(placeholder) ??
-        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))
+    const ref = useMemo(
+        () => composeRefs<FastImageRef>(addReload, forwardedRef),
+        [forwardedRef],
+    )
 
     return (
         <FastImageView
             {...props}
-            ref={forwardedRef}
+            ref={ref}
             // Clips the image to borderRadius by default, as React Native's
             // Image does.
             style={[styles.image, style]}
@@ -974,8 +941,6 @@ function FastImageBase({
                 defaultTransition ?? builtInTransition(),
             )}
             source={resolvedSource}
-            sources={sources}
-            sourcePlaceholders={sourcePlaceholders}
             placeholder={resolvedPlaceholder}
             onFastImageLoadStart={onLoadStart}
             onFastImageProgress={onProgress}
@@ -1007,19 +972,37 @@ function FastImageBase({
     )
 }
 
+// The ref is the native view, with reload() added, as React Native's
+// TextInput adds its methods to its native view.
+function addReload(view: FastImageRef | null) {
+    if (view) view.reload = () => Commands.reload(view as any)
+}
+
 const FastImageMemo = memo(FastImageBase)
 
-// What a ref to FastImage or FastImageBackground gets: FastImage's native
-// view, or FastImageBackground's view. Typed as a View's (they have the same
-// methods, e.g. measure). ComponentRef, as
-// React Native's types declare View as a class, and its Strict TypeScript API
-// (opt-in from 0.80, the default from 0.87) as a function component that takes
-// a ref.
+// What a ref to FastImageBackground gets (its view), and, with reload(), one
+// to FastImage (its native view, which has the same methods, e.g. measure).
+// ComponentRef, as React Native's types declare View as a class, and its
+// Strict TypeScript API (opt-in from 0.80, the default from 0.87) as a
+// function component that takes a ref.
 type ViewRef = React.ComponentRef<typeof View>
 
+/**
+ * What a ref to `FastImage` gets: its native view, with a View's methods
+ * (e.g. `measure`), and `reload()`. E.g. `useRef<FastImageRef>(null)`.
+ */
+export type FastImageRef = ViewRef & {
+    /**
+     * Loads the image again, e.g. to try again after `onError`. The image
+     * showing stays until the new one has loaded, and the events are sent as
+     * for a new source. An image in the cache loads from it.
+     */
+    reload(): void
+}
+
 const FastImageComponent: React.ForwardRefExoticComponent<
-    FastImageProps & React.RefAttributes<ViewRef>
-> = forwardRef((props: FastImageProps, ref: React.Ref<ViewRef>) => (
+    FastImageProps & React.RefAttributes<FastImageRef>
+> = forwardRef((props: FastImageProps, ref: React.Ref<FastImageRef>) => (
     <FastImageMemo forwardedRef={ref} {...props} />
 ))
 
@@ -1152,7 +1135,7 @@ export interface FastImageDefaults {
 }
 
 const FastImage: React.ForwardRefExoticComponent<
-    FastImageProps & React.RefAttributes<ViewRef>
+    FastImageProps & React.RefAttributes<FastImageRef>
 > &
     FastImageStaticProperties = FastImageComponent as any
 
@@ -1263,7 +1246,7 @@ export interface FastImageBackgroundProps extends Omit<
     /** The image's style. */
     imageStyle?: StyleProp<ImageStyle>
     /** A ref to the image (the FastImage inside). */
-    imageRef?: React.Ref<any>
+    imageRef?: React.Ref<FastImageRef>
     /** Content shown on top of the image. */
     children?: React.ReactNode
 }

package/src/index.web.tsx

@@ -23,6 +23,7 @@ import React, {
     useEffect,
     useId,
     useLayoutEffect,
+    useMemo,
     useRef,
     useState,
 } from 'react'
@@ -37,12 +38,14 @@ import {
     hasSourcePlaceholder,
     placeholderSource,
 } from './placeholders'
+import { composeRefs } from './composeRefs'
 import { warnIfChildren, warnOnce } from './warnings'
 import type {
     CachePathResult,
     CacheState,
     FastImageBackgroundProps,
     FastImageProps,
+    FastImageRef,
     FastImageStaticProperties,
     ObjectFit,
     PreloadResult,
@@ -126,6 +129,17 @@ function FastImageBase({
     // one doesn't stay while it loads; with several sizes, the <img> stays,
     // and the browser shows the previous image until the new one has loaded.
     const key = srcSet ?? src
+    // Counts the ref's reload() calls: each gives the image a new <img>, which
+    // the browser loads again (as a new view would). The image showing stays
+    // (it has loaded), or stays hidden (it failed), until then.
+    const [reloads, setReloads] = useState(0)
+    const ref = useMemo(
+        () =>
+            composeRefs((view: FastImageRef | null) => {
+                if (view) view.reload = () => setReloads((count) => count + 1)
+            }, forwardedRef),
+        [forwardedRef],
+    )
     const priority = sourcePriority(source)
     // The source's blurDataUri, or its ThumbHash made into one (with
     // `react-native-fast-image/thumbhash`), shows blurred (see PreviewBlur)
@@ -140,15 +154,21 @@ function FastImageBase({
     // 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
+    // reload() gives it a new <img> too, so one that failed is asked for again.
+    const placeholderKey = `${urlPlaceholder} ${reloads}`
     const [failedPlaceholder, setFailedPlaceholder] = useState<string>()
-    // A thumbhash or blurDataUri in `placeholder` isn't an image to show as it
-    // is, nor is a url (above): defaultSource still is.
+    // 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 || urlPlaceholder
+            preview
                 ? defaultSource
-                : (placeholder ?? defaultSource),
+                : urlPlaceholder
+                  ? undefined
+                  : (placeholder ?? defaultSource),
         )
     // Whether the image for `key` loaded, or failed.
     const [result, setResult] = useState<{ key: string; ok: boolean }>()
@@ -175,7 +195,7 @@ function FastImageBase({
         if (key) onLoadStart?.()
         // Once per image the browser is asked for.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [key])
+    }, [key, reloads])
 
     return (
         <View
@@ -184,7 +204,7 @@ function FastImageBase({
             style={[styles.container, style]}
             onLayout={onLayout}
             pointerEvents={pointerEvents}
-            ref={forwardedRef}
+            ref={ref}
         >
             {defaultUri && showDefault ? (
                 <Picture
@@ -222,7 +242,7 @@ function FastImageBase({
             ) : null}
             {urlPlaceholder && showDefault ? (
                 <Picture
-                    key={`placeholder ${urlPlaceholder}`}
+                    key={`placeholder ${placeholderKey}`}
                     src={urlPlaceholder}
                     loading={loading}
                     // It only helps if it comes before the image, as on iOS
@@ -237,14 +257,14 @@ function FastImageBase({
                     // 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)}
+                    hidden={failedPlaceholder === placeholderKey}
+                    onError={() => setFailedPlaceholder(placeholderKey)}
                     alt=""
                 />
             ) : null}
             {key && src ? (
                 <Picture
-                    key={several ? 'sizes' : key}
+                    key={`${several ? 'sizes' : key} ${reloads}`}
                     src={src}
                     srcSet={srcSet}
                     sizes={sizes}
@@ -341,14 +361,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') {
@@ -370,6 +383,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
@@ -379,9 +422,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)),
@@ -625,11 +669,15 @@ const tintStyle = {
 
 const FastImageMemo = memo(FastImageBase)
 
-const FastImageComponent: React.ComponentType<FastImageProps> = forwardRef(
-    (props: FastImageProps, ref: React.Ref<any>) => (
-        <FastImageMemo forwardedRef={ref} {...props} />
-    ),
-)
+// What a ref to FastImageBackground gets, as in index.tsx: a View's
+// (react-native-web's element). FastImage's has reload() too (FastImageRef).
+type ViewRef = React.ComponentRef<typeof View>
+
+const FastImageComponent: React.ForwardRefExoticComponent<
+    FastImageProps & React.RefAttributes<FastImageRef>
+> = forwardRef((props: FastImageProps, ref: React.Ref<FastImageRef>) => (
+    <FastImageMemo forwardedRef={ref} {...props} />
+))
 
 FastImageComponent.displayName = 'FastImage'
 
@@ -644,7 +692,9 @@ function getSize(uri: string) {
     })
 }
 
-const FastImage: React.ComponentType<FastImageProps> &
+const FastImage: React.ForwardRefExoticComponent<
+    FastImageProps & React.RefAttributes<FastImageRef>
+> &
     FastImageStaticProperties = FastImageComponent as any
 
 FastImage.cacheControl = cacheControl
@@ -692,33 +742,29 @@ const styles = StyleSheet.create({
     },
 })
 
-// FastImage forwards its ref, which its type doesn't say.
-const FastImageWithRef = FastImageComponent as React.ComponentType<
-    FastImageProps & { ref?: React.Ref<any> }
->
-
-export const FastImageBackground: React.ComponentType<FastImageBackgroundProps> =
-    forwardRef(
-        (
-            {
-                style,
-                imageStyle,
-                imageRef,
-                children,
-                ...props
-            }: FastImageBackgroundProps,
-            ref: React.Ref<any>,
-        ) => (
-            <View style={style} ref={ref}>
-                <FastImageWithRef
-                    {...props}
-                    style={[StyleSheet.absoluteFill, imageStyle]}
-                    ref={imageRef}
-                />
-                {children}
-            </View>
-        ),
-    )
+export const FastImageBackground: React.ForwardRefExoticComponent<
+    FastImageBackgroundProps & React.RefAttributes<ViewRef>
+> = forwardRef(
+    (
+        {
+            style,
+            imageStyle,
+            imageRef,
+            children,
+            ...props
+        }: FastImageBackgroundProps,
+        ref: React.Ref<ViewRef>,
+    ) => (
+        <View style={style} ref={ref}>
+            <FastImageComponent
+                {...props}
+                style={[StyleSheet.absoluteFill, imageStyle]}
+                ref={imageRef}
+            />
+            {children}
+        </View>
+    ),
+)
 
 FastImageBackground.displayName = 'FastImageBackground'
 

package/src/specs/FastImageViewNativeComponent.ts

@@ -1,15 +1,16 @@
 // The native image view, from React Native's Codegen (the New Architecture's
 // component). FastImage (index.tsx) renders it as its only view, and turns
 // its props into these.
+import type * as React from 'react'
 import type {
     CodegenTypes,
     ColorValue,
     HostComponent,
     ViewProps,
 } from 'react-native'
-// React Native's Babel plugin replaces the call below with the component's
-// view config, so the import isn't used when the app runs.
-import { codegenNativeComponent } from 'react-native'
+// React Native's Babel plugin replaces the calls below with the component's
+// view config and commands, so the imports aren't used when the app runs.
+import { codegenNativeCommands, codegenNativeComponent } from 'react-native'
 
 type LoadStartEvent = Readonly<{}>
 
@@ -40,21 +41,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 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).
+    // 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
@@ -89,6 +87,17 @@ export interface NativeProps extends ViewProps {
     onFastImageLoadEnd?: CodegenTypes.DirectEventHandler<LoadEndEvent>
 }
 
+interface NativeCommands {
+    // Loads the image again, as a new source would (with its events), keeping
+    // the image showing until then. ElementRef, which React Native 0.83's
+    // Codegen needs (later ones also take ComponentRef).
+    reload: (viewRef: React.ElementRef<HostComponent<NativeProps>>) => void
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+    supportedCommands: ['reload'],
+})
+
 export default codegenNativeComponent<NativeProps>(
     'FastImageView',
 ) as HostComponent<NativeProps>