react-native-fast-image 10.3.0 → 10.5.0

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,
@@ -82,6 +86,7 @@ function FastImageBase({
     objectPosition,
     loading,
     sizes,
+    dynamicRangeLimit,
     forwardedRef,
     // On the wrapper, the view the layout and touches are for here (on
     // native, FastImage's only view).
@@ -131,11 +136,20 @@ function FastImageBase({
     const blurUri =
         resolveUri(dataUri(shared(source, 'blurDataUri', preview))) ??
         thumbhashUri(shared(source, 'thumbhash', preview))
+    // `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>()
     // A thumbhash or blurDataUri in `placeholder` isn't an image to show as it
-    // is: defaultSource still is.
+    // is, nor is a url (above): defaultSource still is.
     const defaultUri =
         blurUri ??
-        resolveUri(preview ? defaultSource : (placeholder ?? defaultSource))
+        resolveUri(
+            preview || urlPlaceholder
+                ? defaultSource
+                : (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
@@ -155,7 +169,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?.()
@@ -179,6 +193,7 @@ function FastImageBase({
                     // Loaded when the image is (a data uri needs no request).
                     loading={loading}
                     priority={priority}
+                    dynamicRangeLimit={dynamicRangeLimit}
                     // A source's placeholder stands for an image whose size
                     // isn't known yet: as contain for scale-down and none,
                     // which show an image at its own size.
@@ -205,6 +220,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}
@@ -213,6 +250,7 @@ function FastImageBase({
                     sizes={sizes}
                     loading={loading}
                     priority={priority}
+                    dynamicRangeLimit={dynamicRangeLimit}
                     fit={fit}
                     position={position}
                     filter={filter}
@@ -414,6 +452,7 @@ function Picture({
     sizes,
     loading,
     priority,
+    dynamicRangeLimit,
     fit,
     position,
     filter,
@@ -429,6 +468,9 @@ function Picture({
     loading?: 'lazy' | 'eager'
     // source.priority, as the <img>'s fetchpriority.
     priority?: Priority
+    // The prop, as CSS's dynamic-range-limit (the browser's default when
+    // not set).
+    dynamicRangeLimit?: 'standard' | 'constrained' | 'no-limit'
     fit: ObjectFit
     // objectPosition, as CSS.
     position: string
@@ -513,6 +555,8 @@ function Picture({
                 objectPosition: position,
                 filter,
                 opacity: hidden ? 0 : undefined,
+                // Not in React's CSS types yet.
+                ...({ dynamicRangeLimit } as object),
             }}
             onLoad={(event) =>
                 loaded(event.currentTarget as unknown as LoadedImage)

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

@@ -45,8 +45,10 @@ export interface NativeProps extends ViewProps {
     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 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
@@ -70,6 +72,9 @@ export interface NativeProps extends ViewProps {
     transitionBetweenImages?: boolean
     transitionSkipOnCacheHit?: string
     downsample?: CodegenTypes.WithDefault<boolean, true>
+    // standard, constrained or no-limit ('' when not set). iOS and tvOS 17+
+    // (Android ignores it).
+    dynamicRangeLimit?: string
     blurRadius?: CodegenTypes.Float
     // The events JS has a handler for, as bits: 1 onFastImageLoadStart,
     // 2 onFastImageProgress, 4 onFastImageLoad, 8 onFastImageError, 16