react-native-fast-image 9.3.7 → 10.1.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 import React from 'react';
 import { ColorValue, View, StyleProp, ViewStyle, ImageRequireSource, AccessibilityProps, ViewProps } from 'react-native';
 import { cacheControl, priority, resizeMode } from './constants';
+import { type ObjectPosition } from './objectPosition';
 /** How the image fits the view: see [`objectFit`](#objectfit). */
 export type ObjectFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down';
-/** How the image fits the view: see [`resizeMode`](#resizemode). */
-export type ResizeMode = 'contain' | 'cover' | 'stretch' | 'center' | 'repeat';
+export type { ObjectPosition, PositionLength } from './objectPosition';
 /** An image's load priority: see [`source.priority`](#sourcepriority). */
 export type Priority = 'low' | 'normal' | 'high';
 /** How fresh an image must be: see [`source.cache`](#sourcecache). */
@@ -86,6 +86,31 @@ export type Source = {
      * @default true
      */
     memoryCache?: boolean;
+    /**
+     * Whether the image is kept on disk. With `false` it isn't kept in the
+     * disk cache or an HTTP cache, or read from them. Use it for images the
+     * app shouldn't
+     * keep once they've been shown (e.g. disappearing messages, or where a
+     * security policy doesn't allow caching sensitive images), images that
+     * change every time they load, or large images shown once, which would
+     * push other images out of the disk cache.
+     * The image is downloaded again whenever it isn't in memory, e.g. for a
+     * view of another size (or on Android, a change of `blurRadius` or
+     * `objectFit`), so with `memoryCache: false` too it's downloaded each
+     * time it's shown. With `cache: 'web'` it isn't kept in memory either,
+     * so it's downloaded every time it loads. With `cache: 'cacheOnly'` it's
+     * only looked for in memory. On Android, a large download is held in a
+     * temporary file while it loads, as every download is, deleted as soon
+     * as it's opened.
+     *
+     * `FastImage.preload`, `getCachePath` and `writeToCache` resolve not `ok`
+     * for it: there's no file, and a view decodes the image for its own
+     * size, so it may download a preloaded one again. A source for the same
+     * url (or `cacheKey`) without `diskCache: false` still stores the image.
+     *
+     * @default true
+     */
+    diskCache?: boolean;
     /**
      * With several sources (`source` as an array), the image's width at this
      * uri, in pixels (times `scale`, if given).
@@ -103,7 +128,8 @@ export type Source = {
 export type Transition = {
     /**
      * How long the fade takes, in milliseconds; 0 means no fade. Defaults to
-     * the platform's usual length: 300 ms on Android, 250 ms on iOS.
+     * the default transition's (see `FastImage.setDefaults`) if it fades,
+     * otherwise the platform's usual length: 300 ms on Android, 250 ms on iOS.
      */
     duration?: number;
     /**
@@ -124,17 +150,16 @@ export type Transition = {
      *   usually only the first time (the disk cache usually keeps them too).
      * - `'none'`: always fades.
      *
-     * Downloads, local files and bundled images (`require()`) fade in. On
-     * Android, a `cache: 'web'` image from its HTTP cache, without a request,
+     * On Android, a `cache: 'web'` image from its HTTP cache, without a request,
      * counts as one from the memory cache (these images aren't kept there).
      * @default 'memory'
      */
     skipOnCacheHit?: 'none' | 'memory' | 'all' | null;
 };
 /**
- * `onLoad`'s event: `nativeEvent` has the image's `width` and `height`, in
- * pixels, and `target`, the view's React tag (missing on Android with the
- * legacy architecture).
+ * `onLoad`'s event: `nativeEvent` has the image's own `width` and `height`
+ * (see `onLoad`), and `target`, the view's React tag (on iOS and Android; not
+ * on the web).
  */
 export interface OnLoadEvent {
     nativeEvent: {
@@ -234,7 +259,6 @@ export interface OnProgressEvent {
     };
 }
 export interface ImageStyle extends ViewStyle {
-    overlayColor?: ColorValue;
     tintColor?: ColorValue;
     objectFit?: ObjectFit;
 }
@@ -293,9 +317,9 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * How the image fits the view, as CSS's `object-fit` does.
      *
      * - `'cover'`: scales it uniformly (keeping its aspect ratio) so it covers
-     *   the view (minus padding), cropping what doesn't fit.
+     *   the view (inside its borders), cropping what doesn't fit.
      * - `'contain'`: scales it uniformly (keeping its aspect ratio) so all of
-     *   it fits in the view (minus padding).
+     *   it fits in the view (inside its borders).
      * - `'fill'`: scales its width and height separately to fill the view,
      *   which can change its aspect ratio.
      * - `'none'`: shows it at its own size, centered, cropped if it's larger
@@ -308,36 +332,37 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      * as CSS counts an image's pixels: a 300 × 200 image is 300 × 200 points.
      * A bundled image (`require()`) is its size in points.
      *
-     * It can also be set in `style`; the prop wins. Either one overrides
-     * `resizeMode`.
+     * It can also be set in `style`; the prop wins.
      *
      * @default 'cover'
      */
     objectFit?: ObjectFit;
     /**
-     * How the image fills the view.
-     *
-     * - `'contain'`: as `objectFit="contain"`.
-     * - `'cover'`: as `objectFit="cover"`.
-     * - `'stretch'`: as `objectFit="fill"`.
-     * - `'center'`: as `objectFit="scale-down"`, except that on Android an
-     *   image smaller than the view is shown at its size in pixels on the
-     *   screen, so smaller than on iOS and the web.
-     * - `'repeat'`: repeats it to cover the view, from its top-left corner, at
-     *   the image's own size in pixels (a bundled image at its size in
-     *   points), scaled down to fit if it's larger than the view. An animated
-     *   image repeats its first frame, and `defaultSource` repeats too.
-     *
-     * @default 'cover'
-     * @deprecated Use `objectFit` instead.
-     */
-    resizeMode?: ResizeMode;
-    /**
-     * If true, the image is shown with React Native's `Image` instead, styled
-     * and laid out the same way. FastImage's own features, such as its
-     * caching options, `priority` and `transition`, don't apply.
+     * Where the image is in the view, as CSS's `object-position` places it:
+     * where its edges are when it doesn't fill the view exactly (`contain`,
+     * `cover`, `none` and `scale-down`; with `fill` it always fills it).
+     *
+     * - A string in CSS's syntax: one or two keywords (`'top'`,
+     *   `'left bottom'`), lengths in points (`'10px 20px'`, with `px`) or
+     *   percentages (`'25% 75%'`), or offsets from an edge
+     *   (`'right 10px bottom 20%'`). A percentage puts that point of the image
+     *   at that point of the view: `'0% 0%'` is the top-left corner,
+     *   `'100% 100%'` the bottom-right.
+     * - An object with one of `top` and `bottom` and one of `left` and
+     *   `right`, each in points (a number) or a percentage (`'25%'`), e.g.
+     *   `{ right: 10, bottom: '20%' }`. A missing axis is centered.
+     *
+     * Points are dp on Android. An invalid value is ignored (the image is
+     * centered), with a warning in development. `defaultSource` is placed
+     * the same way.
+     *
+     * @default '50% 50%'
+     * @example
+     * ```jsx
+     * <FastImage source={{ uri }} objectFit="cover" objectPosition="top" />
+     * ```
      */
-    fallback?: boolean;
+    objectPosition?: ObjectPosition;
     /**
      * For views that get reused for other content, such as rows in FlashList
      * or recyclerlistview. Set it to something that identifies the content,
@@ -393,15 +418,21 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      */
     paused?: boolean;
     /**
-     * Fades the image in when it loads. `true` uses the platform's usual
-     * fade, a number is the duration in milliseconds, or pass a `Transition`.
+     * Fades the image in when it loads. `true` fades for the default's
+     * duration (see `FastImage.setDefaults`), or the platform's usual length
+     * if the default doesn't fade; a number is the duration in milliseconds,
+     * `false` (or 0) is no fade, or pass a `Transition`.
+     *
+     * By default, images fade in on Android (300 ms), and not on iOS.
+     * `FastImage.setDefaults` changes that for every image; an image's own
+     * `transition` wins, and the settings it leaves out come from the
+     * default. `null` is the default.
      *
      * Downloads, local files (`file://`, `content://`) and bundled images
      * (`require()`) fade in. In lists that reuse views (e.g. FlashList), set
      * `recyclingKey`, so a reused view starts empty and its image fades in,
      * instead of showing the previous item's image until it loads.
      *
-     * @default false
      * @example
      * ```jsx
      * <FastImage source={{ uri }} transition />
@@ -427,12 +458,9 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      *   draw.
      *
      * It doesn't change `onLoad`'s width and height (the image's own size) or
-     * the cached file. On iOS it needs SDWebImage 5.19.7 or later: before
-     * 5.19 images are decoded at full size, and 5.19.0 to 5.19.6 show photos
-     * stored sideways with an EXIF orientation (most phone photos) sideways.
-     * Photo library images are always decoded at about the view's size.
-     * Android 16 and later decode animated WebP at full size either way, and
-     * scale it as they draw it.
+     * the cached file. Photo library images are always decoded at about the
+     * view's size. Android 16 and later decode animated WebP at full size
+     * either way, and scale it as they draw it.
      *
      * If you control the images, serve them at the size they're shown
      * (resized on your server or by an image CDN), which also saves
@@ -461,8 +489,7 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      *
      * To animate a blur, or to blur an animated image, use React Native's
      * `filter` style instead, which the GPU draws:
-     * `style={{ filter: [{ blur: 6 }] }}`. It needs the New Architecture.
-     * React Native's docs list `blur` for Android 12+ only; on iOS it's behind
+     * `style={{ filter: [{ blur: 6 }] }}`. React Native's docs list `blur` for Android 12+ only; on iOS it's behind
      * an experimental React Native feature flag (`enableSwiftUIBasedFilters`,
      * SwiftUI-based filters).
      *
@@ -525,9 +552,9 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      */
     onLoadEnd?(result: LoadResult): void;
     /**
-     * The image's style: View's style props (`borderRadius` clips the image),
-     * and `tintColor`, as with React Native's `Image` (the `tintColor` prop
-     * wins).
+     * The image's style: View's style props (`borderRadius` clips the image,
+     * and borders inset it, but padding doesn't), and `tintColor`, as with
+     * React Native's `Image` (the `tintColor` prop wins).
      */
     style?: StyleProp<ImageStyle>;
     /**
@@ -536,14 +563,14 @@ export interface FastImageProps extends AccessibilityProps, ViewProps {
      */
     tintColor?: ColorValue;
     /**
-     * Render children within the image.
+     * FastImage is a single native view, which doesn't take children (since
+     * 10.0): use `FastImageBackground` for content over an image.
      *
-     * @deprecated In the next major version, `FastImage` won't render
-     * children: use `FastImageBackground`.
+     * @hidden
      */
-    children?: React.ReactNode;
+    children?: "FastImage doesn't take children: use FastImageBackground for content over an image";
 }
-type ViewRef = React.ElementRef<typeof View>;
+type ViewRef = React.ComponentRef<typeof View>;
 /** A preloaded source that loaded (and is now cached). */
 export interface PreloadSuccess {
     /** The source's uri. */
@@ -570,10 +597,18 @@ export interface PreloadFailure {
 export type PreloadResult = PreloadSuccess | PreloadFailure;
 export interface FastImageStaticProperties {
     /**
-     * @deprecated Use the `objectFit` prop instead of `resizeMode`.
+     * @deprecated `resizeMode` was removed in 10.0, and a `resizeMode` prop
+     * is ignored: use `objectFit` instead (`stretch` is `fill`, `center` is
+     * `scale-down`). Kept so code that reads it doesn't throw.
      */
     resizeMode: typeof resizeMode;
+    /**
+     * @deprecated Use the strings instead, e.g. `priority: 'high'`.
+     */
     priority: typeof priority;
+    /**
+     * @deprecated Use the strings instead, e.g. `cache: 'immutable'`.
+     */
     cacheControl: typeof cacheControl;
     preload: (sources: Source[]) => Promise<PreloadResult[]>;
     /**
@@ -617,6 +652,22 @@ export interface FastImageStaticProperties {
      * to read the disk cache's size).
      */
     configureCache: (limits?: CacheLimits) => Promise<CacheState>;
+    /**
+     * Changes the defaults of every image (only those given; null goes back
+     * to the built-in one). An image already showing uses a change once one
+     * of its props changes, for its next load. Not saved: call it before
+     * images render, e.g. in index.js.
+     */
+    setDefaults: (defaults: FastImageDefaults) => void;
+}
+/** `FastImage.setDefaults`'s settings. */
+export interface FastImageDefaults {
+    /**
+     * The `transition` of images that don't set one (an image's own settings
+     * win, and those it leaves out come from this). `null` goes back to the
+     * built-in default (see `transition`).
+     */
+    transition?: boolean | number | Transition | null;
 }
 declare const FastImage: React.ForwardRefExoticComponent<FastImageProps & React.RefAttributes<ViewRef>> & FastImageStaticProperties;
 export interface FastImageBackgroundProps extends Omit<FastImageProps, 'style' | 'children'> {
@@ -631,9 +682,8 @@ export interface FastImageBackgroundProps extends Omit<FastImageProps, 'style' |
 }
 /**
  * An image with content on top of it, like React Native's `ImageBackground`: a
- * view that the image fills, with the children on top. Use it rather than
- * giving `FastImage` children, which it won't render in the next major version
- * (the image will be a single native view). The other props go to the image;
+ * view that the image fills, with the children on top (`FastImage` is a single
+ * native view, which doesn't take children). The other props go to the image;
  * the ref is the view's.
  */
 export declare const FastImageBackground: React.ForwardRefExoticComponent<FastImageBackgroundProps & React.RefAttributes<ViewRef>>;