react-native-fast-image 9.3.6 → 10.0.0

package/src/objectPosition.ts

@@ -0,0 +1,243 @@
+// objectPosition, as CSS's object-position, shared by the native (index.tsx)
+// and web (index.web.tsx) versions: a CSS position string or an object of
+// edges, resolved to what CSS computes for each axis.
+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
+
+/** A length in points (dp on Android), or a percentage: see [`objectPosition`](#objectposition). */
+export type PositionLength = number | `${number}%`
+
+/**
+ * Where the image is in the view: see [`objectPosition`](#objectposition).
+ */
+export type ObjectPosition =
+    | string
+    | ((
+          | { top?: PositionLength; bottom?: never }
+          | { bottom: PositionLength; top?: never }
+      ) &
+          (
+              | { left?: PositionLength; right?: never }
+              | { right: PositionLength; left?: never }
+          ))
+
+// One axis as CSS computes it, calc(fraction * 100% + offset): the image's
+// edge is at (view - image) * fraction + offset, in points.
+export type ResolvedAxis = { fraction: number; offset: number }
+export type ResolvedPosition = { x: ResolvedAxis; y: ResolvedAxis }
+
+const START: ResolvedAxis = { fraction: 0, offset: 0 }
+const CENTER: ResolvedAxis = { fraction: 0.5, offset: 0 }
+const END: ResolvedAxis = { fraction: 1, offset: 0 }
+
+/** The default, `50% 50%`. */
+export const CENTERED: ResolvedPosition = { x: CENTER, y: CENTER }
+
+type Keyword = 'left' | 'right' | 'top' | 'bottom' | 'center'
+type Token = { keyword: Keyword } | { length: ResolvedAxis }
+
+const NUMBER = /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i
+
+// A length in px, a percentage, or 0 without a unit.
+function length(text: string): ResolvedAxis | null {
+    const lower = text.toLowerCase()
+    if (lower.endsWith('%')) {
+        const number = lower.slice(0, -1)
+        return NUMBER.test(number)
+            ? { fraction: Number(number) / 100, offset: 0 }
+            : null
+    }
+    if (lower.endsWith('px')) {
+        const number = lower.slice(0, -2)
+        return NUMBER.test(number)
+            ? { fraction: 0, offset: Number(number) }
+            : null
+    }
+    return NUMBER.test(lower) && Number(lower) === 0 ? START : null
+}
+
+function token(text: string): Token | null {
+    const lower = text.toLowerCase()
+    if (
+        lower === 'left' ||
+        lower === 'right' ||
+        lower === 'top' ||
+        lower === 'bottom' ||
+        lower === 'center'
+    ) {
+        return { keyword: lower }
+    }
+    const axis = length(text)
+    return axis ? { length: axis } : null
+}
+
+const X: Partial<Record<Keyword, ResolvedAxis>> = {
+    left: START,
+    center: CENTER,
+    right: END,
+}
+const Y: Partial<Record<Keyword, ResolvedAxis>> = {
+    top: START,
+    center: CENTER,
+    bottom: END,
+}
+
+const x = (t: Token) => ('length' in t ? t.length : X[t.keyword])
+const y = (t: Token) => ('length' in t ? t.length : Y[t.keyword])
+
+// An offset from an edge: from the left or top as it is, from the right or
+// bottom as 100% minus it.
+function fromEdge(edge: Keyword, axis: ResolvedAxis): ResolvedAxis {
+    return edge === 'left' || edge === 'top'
+        ? axis
+        : { fraction: 1 - axis.fraction, offset: -axis.offset || 0 }
+}
+
+// CSS's <position> (CSS Values 4), as object-position takes it: 1, 2 or 4
+// values, keywords in any case, lengths in px or %, 0 without a unit. Null if
+// it isn't one (CSS ignores it then).
+function parse(text: string): ResolvedPosition | null {
+    const tokens: Token[] = []
+    for (const part of text.trim().split(/\s+/)) {
+        const t = token(part)
+        if (!t) return null
+        tokens.push(t)
+    }
+    if (tokens.length === 1) {
+        const [a] = tokens
+        if ('keyword' in a && (a.keyword === 'top' || a.keyword === 'bottom')) {
+            return { x: CENTER, y: Y[a.keyword]! }
+        }
+        return { x: x(a)!, y: CENTER }
+    }
+    if (tokens.length === 2) {
+        const [a, b] = tokens
+        // [left | center | right | <length-percentage>]
+        // [top | center | bottom | <length-percentage>]
+        const ax = x(a)
+        const by = y(b)
+        if (ax && by) return { x: ax, y: by }
+        // Or two keywords in either order: [left | center | right] &&
+        // [top | center | bottom].
+        if ('keyword' in a && 'keyword' in b) {
+            const bx = X[b.keyword]
+            const ay = Y[a.keyword]
+            if (bx && ay) return { x: bx, y: ay }
+        }
+        return null
+    }
+    if (tokens.length === 4) {
+        // [[left | right] <length-percentage>] &&
+        // [[top | bottom] <length-percentage>]
+        const [a, b, c, d] = tokens
+        if (
+            !(
+                'keyword' in a &&
+                'length' in b &&
+                'keyword' in c &&
+                'length' in d
+            )
+        ) {
+            return null
+        }
+        const horizontal = (k: Keyword) => k === 'left' || k === 'right'
+        const vertical = (k: Keyword) => k === 'top' || k === 'bottom'
+        if (horizontal(a.keyword) && vertical(c.keyword)) {
+            return {
+                x: fromEdge(a.keyword, b.length),
+                y: fromEdge(c.keyword, d.length),
+            }
+        }
+        if (vertical(a.keyword) && horizontal(c.keyword)) {
+            return {
+                x: fromEdge(c.keyword, d.length),
+                y: fromEdge(a.keyword, b.length),
+            }
+        }
+    }
+    return null
+}
+
+const parsed = new Map<string, ResolvedPosition | null>()
+
+function objectLength(value: unknown): ResolvedAxis | null {
+    if (typeof value === 'number') {
+        return Number.isFinite(value) ? { fraction: 0, offset: value } : null
+    }
+    return typeof value === 'string' && value.endsWith('%')
+        ? length(value)
+        : null
+}
+
+/**
+ * The position for objectPosition, or null if it isn't valid. A string is
+ * CSS's syntax; an object has one of `top` and `bottom` and one of `left`
+ * and `right`, each in points or a percentage, and a missing axis is
+ * centered. Unset is centered.
+ */
+export function resolveObjectPosition(
+    position: ObjectPosition | null | undefined,
+): ResolvedPosition | null {
+    if (position == null) return CENTERED
+    if (typeof position === 'string') {
+        // The same few strings, in every row of a list.
+        let result = parsed.get(position)
+        if (result === undefined) {
+            result = parse(position)
+            if (parsed.size < 100) parsed.set(position, result)
+        }
+        return result
+    }
+    if (typeof position !== 'object') return null
+    const edges = position as Record<string, unknown>
+    const axis = (start: Keyword, end: Keyword): ResolvedAxis | null => {
+        const hasStart = edges[start] != null
+        const hasEnd = edges[end] != null
+        if (hasStart && hasEnd) return null
+        if (!hasStart && !hasEnd) return CENTER
+        const edge = hasStart ? start : end
+        const value = objectLength(edges[edge])
+        return value && fromEdge(edge, value)
+    }
+    const resolvedX = axis('left', 'right')
+    const resolvedY = axis('top', 'bottom')
+    return resolvedX && resolvedY ? { x: resolvedX, y: resolvedY } : null
+}
+
+// Without float noise (1 - 1.2 is -0.19999999999999996).
+const round = (n: number) => Math.round(n * 1e6) / 1e6
+
+/**
+ * The position for objectPosition, or centered if it isn't valid (as CSS
+ * ignores it), with a warning in development.
+ */
+export function objectPositionOrCentered(
+    position: ObjectPosition | null | undefined,
+): ResolvedPosition {
+    const resolved = resolveObjectPosition(position)
+    if (resolved) return resolved
+    if (typeof __DEV__ !== 'undefined' && __DEV__) {
+        const value = JSON.stringify(position)
+        warnOnce(
+            `objectPosition ${value}`,
+            `react-native-fast-image: objectPosition ${value} isn't a position, so the image is centered. Use CSS's syntax with px or % (e.g. 'right 10px bottom 20%'), or { top | bottom, left | right } in points or percentages.`,
+            'warn',
+        )
+    }
+    return CENTERED
+}
+
+/** The position as CSS (for the web version's object-position). */
+export function cssPosition({ x, y }: ResolvedPosition) {
+    const axis = ({ fraction, offset }: ResolvedAxis) => {
+        const percent = round(fraction * 100)
+        const px = round(offset)
+        if (px === 0) return `${percent}%`
+        if (percent === 0) return `${px}px`
+        return `calc(${percent}% ${px < 0 ? '-' : '+'} ${Math.abs(px)}px)`
+    }
+    return `${axis(x)} ${axis(y)}`
+}

package/src/specs/FastImageViewNativeComponent.ts

@@ -0,0 +1,83 @@
+// 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 {
+    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'
+
+type LoadStartEvent = Readonly<{}>
+
+// progress is loaded / total, from 0 to 1 (the views don't send an unknown
+// total).
+type ProgressEvent = Readonly<{
+    loaded: CodegenTypes.Double
+    total: CodegenTypes.Double
+    progress: CodegenTypes.Double
+}>
+
+// The image's own size.
+type LoadEvent = Readonly<{
+    width: CodegenTypes.Double
+    height: CodegenTypes.Double
+}>
+
+type ErrorEvent = Readonly<{
+    error: string
+}>
+
+// onLoad's or onError's event, with whether it loaded.
+type LoadEndEvent = Readonly<{
+    ok: boolean
+    width?: CodegenTypes.Double
+    height?: CodegenTypes.Double
+    error?: string
+}>
+
+export interface NativeProps extends ViewProps {
+    // A source ({ uri, headers, priority, cache, ... }), as the native
+    // sides read it.
+    source?: CodegenTypes.UnsafeMixed
+    // Several sources (sizes of one image), picked from for the view's size.
+    sources?: CodegenTypes.UnsafeMixed
+    // A resolved asset source ({ uri, width, height, scale }).
+    defaultSource?: CodegenTypes.UnsafeMixed
+    // 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
+    // edge is at (view - image) * fraction + offset, in points.
+    objectPositionX?: CodegenTypes.WithDefault<CodegenTypes.Float, 0.5>
+    objectPositionXOffset?: CodegenTypes.Float
+    objectPositionY?: CodegenTypes.WithDefault<CodegenTypes.Float, 0.5>
+    objectPositionYOffset?: CodegenTypes.Float
+    tintColor?: ColorValue
+    recyclingKey?: string
+    loopCount?: CodegenTypes.WithDefault<CodegenTypes.Int32, -1>
+    imageRendering?: string
+    paused?: boolean
+    transitionDuration?: CodegenTypes.Double
+    transitionBetweenImages?: boolean
+    transitionSkipOnCacheHit?: string
+    downsample?: CodegenTypes.WithDefault<boolean, true>
+    blurRadius?: CodegenTypes.Float
+    // The events JS has a handler for, as bits: 1 onFastImageLoadStart,
+    // 2 onFastImageProgress, 4 onFastImageLoad, 8 onFastImageError, 16
+    // onFastImageLoadEnd. The native views only send those (most images have
+    // no handlers), and only track progress with 2. (Not `events`: iOS's
+    // ViewProps already has a member by that name.)
+    handledEvents?: CodegenTypes.Int32
+    onFastImageLoadStart?: CodegenTypes.DirectEventHandler<LoadStartEvent>
+    onFastImageProgress?: CodegenTypes.DirectEventHandler<ProgressEvent>
+    onFastImageLoad?: CodegenTypes.DirectEventHandler<LoadEvent>
+    onFastImageError?: CodegenTypes.DirectEventHandler<ErrorEvent>
+    onFastImageLoadEnd?: CodegenTypes.DirectEventHandler<LoadEndEvent>
+}
+
+export default codegenNativeComponent<NativeProps>(
+    'FastImageView',
+) as HostComponent<NativeProps>

package/src/specs/NativeFastImageModule.ts

@@ -0,0 +1,35 @@
+// FastImage's functions (preload, the caches), as a TurboModule from React
+// Native's Codegen. FastImage (index.tsx) checks their arguments and shapes
+// their results.
+import type { CodegenTypes, TurboModule } from 'react-native'
+import { TurboModuleRegistry } from 'react-native'
+
+export interface Spec extends TurboModule {
+    // A result per source, in order: { ok, width, height } or { ok, error }.
+    preload(
+        sources: Array<CodegenTypes.UnsafeObject>,
+    ): Promise<Array<CodegenTypes.UnsafeObject>>
+    // { ok, path } or { ok, error }.
+    getCachePath(
+        source: CodegenTypes.UnsafeObject,
+    ): Promise<CodegenTypes.UnsafeObject>
+    // { ok, path } or { ok, error }.
+    writeToCache(
+        source: CodegenTypes.UnsafeObject,
+        file: string,
+    ): Promise<CodegenTypes.UnsafeObject>
+    // { maxDiskSize: number, ..., reset: [names] }: the limits to set, and the
+    // names of those to reset (null isn't sent: iOS would drop it). Resolves
+    // with the limits in effect.
+    configureCache(
+        limits: CodegenTypes.UnsafeObject,
+    ): Promise<CodegenTypes.UnsafeObject>
+    // { ok } or { ok, error }.
+    clearMemoryCache(): Promise<CodegenTypes.UnsafeObject>
+    clearDiskCache(): Promise<CodegenTypes.UnsafeObject>
+}
+
+// null where the app doesn't have the native module (Jest, Expo Go, an app
+// not rebuilt after installing): FastImage's functions throw when they're
+// called, rather than importing FastImage throwing.
+export default TurboModuleRegistry.get<Spec>('FastImageModule')

package/src/warnings.ts

@@ -0,0 +1,37 @@
+// FastImage's development warnings and errors, each once per app (a list would
+// repeat it for every image), shared by the native (index.tsx) and web
+// (index.web.tsx) versions.
+import { Children } from 'react'
+import type { ReactNode } from 'react'
+
+const warned = new Set<string>()
+
+export function warnOnce(
+    key: string,
+    message: string,
+    level: 'warn' | 'error',
+) {
+    if (!warned.has(key)) {
+        warned.add(key)
+        console[level](message)
+    }
+}
+
+// For the tests (test/setup.ts): `bun test` loads this module once for the
+// native and web versions' tests together.
+export function resetWarnings() {
+    warned.clear()
+}
+
+// FastImage doesn't render children: on native it's a single view, and the
+// web version does the same. toArray, as a Touchable clones its child with
+// children: undefined.
+export function warnIfChildren(children: unknown) {
+    if (Children.toArray(children as ReactNode).length > 0) {
+        warnOnce(
+            'children',
+            "react-native-fast-image: FastImage doesn't render children (since 10.0): use FastImageBackground for content over an image.",
+            'error',
+        )
+    }
+}

package/android/src/main/AndroidManifestNew.xml

@@ -1,3 +0,0 @@
-<!-- Used instead of AndroidManifest.xml when the namespace is set in build.gradle. -->
-<manifest>
-</manifest>

package/android/src/main/java/com/dylanvann/fastimage/FastImageCookieHandler.java

@@ -1,63 +0,0 @@
-package com.dylanvann.fastimage;
-
-import android.text.TextUtils;
-import android.webkit.CookieManager;
-
-import androidx.annotation.Nullable;
-
-import java.net.CookieHandler;
-import java.net.URI;
-import java.util.Collections;
-import java.util.List;
-import java.util.Map;
-
-// Reads and stores cookies in Android's cookie store (the WebView's
-// CookieManager), which React Native's networking (fetch) and its Image
-// component use. Image requests then send the cookies the app's other requests
-// got, as on iOS. Does what React Native's ForwardingCookieHandler does,
-// without the ReactContext that one needs (up to at least 0.77). Used through
-// OkHttp's JavaNetCookieJar, which parses the cookies.
-final class FastImageCookieHandler extends CookieHandler {
-    @Nullable
-    private CookieManager cookieManager;
-
-    @Override
-    public Map<String, List<String>> get(URI uri, Map<String, List<String>> requestHeaders) {
-        CookieManager cookieManager = cookieManager();
-        if (cookieManager == null) return Collections.emptyMap();
-        String cookies = cookieManager.getCookie(uri.toString());
-        if (TextUtils.isEmpty(cookies)) return Collections.emptyMap();
-        return Collections.singletonMap("Cookie", Collections.singletonList(cookies));
-    }
-
-    @Override
-    public void put(URI uri, Map<String, List<String>> responseHeaders) {
-        CookieManager cookieManager = cookieManager();
-        if (cookieManager == null) return;
-        String url = uri.toString();
-        boolean added = false;
-        for (Map.Entry<String, List<String>> header : responseHeaders.entrySet()) {
-            String name = header.getKey();
-            if (!"Set-Cookie".equalsIgnoreCase(name) && !"Set-Cookie2".equalsIgnoreCase(name)) continue;
-            for (String cookie : header.getValue()) {
-                cookieManager.setCookie(url, cookie);
-                added = true;
-            }
-        }
-        if (added) cookieManager.flush();
-    }
-
-    // null while the WebView isn't available (not installed, or being
-    // updated): requests go without cookies then, instead of failing.
-    @Nullable
-    private synchronized CookieManager cookieManager() {
-        if (cookieManager == null) {
-            try {
-                cookieManager = CookieManager.getInstance();
-            } catch (Exception e) {
-                return null;
-            }
-        }
-        return cookieManager;
-    }
-}

package/android/src/main/java/com/dylanvann/fastimage/FastImageEvents.java

@@ -1,49 +0,0 @@
-package com.dylanvann.fastimage;
-
-import android.view.View;
-
-import com.facebook.react.bridge.Arguments;
-import com.facebook.react.bridge.ReactContext;
-import com.facebook.react.bridge.WritableMap;
-import com.facebook.react.uimanager.UIManagerHelper;
-import com.facebook.react.uimanager.events.EventDispatcher;
-
-// Sends FastImage view events through React Native's EventDispatcher.
-final class FastImageEvents {
-    private FastImageEvents() {
-    }
-
-    static void send(View view, String name) {
-        send(view, name, Arguments.createMap());
-    }
-
-    // onLoadEnd with the load's result: ok with the image's size, as onLoad
-    // sent it.
-    static void sendLoadEnd(View view, int width, int height) {
-        WritableMap event = Arguments.createMap();
-        event.putBoolean("ok", true);
-        event.putInt("width", width);
-        event.putInt("height", height);
-        send(view, FastImageRequestListener.REACT_ON_LOAD_END_EVENT, event);
-    }
-
-    // onLoadEnd with the load's result: not ok, with the error onError sent.
-    static void sendLoadEnd(View view, String error) {
-        WritableMap event = Arguments.createMap();
-        event.putBoolean("ok", false);
-        event.putString("error", error);
-        send(view, FastImageRequestListener.REACT_ON_LOAD_END_EVENT, event);
-    }
-
-    static void send(View view, String name, WritableMap data) {
-        ReactContext context = FastImageViewManager.getReactContext(view.getContext());
-        if (context == null) return;
-        // The view's event dispatcher, on either architecture (also
-        // bridgeless).
-        EventDispatcher dispatcher = UIManagerHelper.getEventDispatcherForReactTag(context, view.getId());
-        if (dispatcher != null) {
-            dispatcher.dispatchEvent(new FastImageEvent(
-                    UIManagerHelper.getSurfaceId(view), view.getId(), name, data));
-        }
-    }
-}

package/android/src/main/java/com/dylanvann/fastimage/FastImageProgressListener.java

@@ -1,18 +0,0 @@
-package com.dylanvann.fastimage;
-
-// No longer used: FastImage sends progress through FastImageViewManager's
-// onDownloadProgress. Kept, as a public type, so code that refers to it still
-// compiles.
-@Deprecated
-public interface FastImageProgressListener {
-
-    void onProgress(String key, long bytesRead, long expectedLength);
-
-    /**
-     * Control how often the listener needs an update. 0% and 100% will always be dispatched.
-     *
-     * @return in percentage (0.2 = call {@link #onProgress} around every 0.2 percent of progress)
-     */
-    float getGranularityPercentage();
-
-}

package/android/src/main/java/com/dylanvann/fastimage/FastImageShadowNode.java

@@ -1,21 +0,0 @@
-package com.dylanvann.fastimage;
-
-import com.facebook.react.uimanager.LayoutShadowNode;
-import com.facebook.react.uimanager.UIViewOperationQueue;
-
-// Legacy architecture only. React Native only lays out a view when its frame
-// changes, so a view that stays 0×0 at its parent's origin is never laid out,
-// and Glide waits for its size forever (#865). When the computed size is zero,
-// tell the view, so it can lay itself out and load as it does on the New
-// Architecture. Remove with legacy architecture support.
-public class FastImageShadowNode extends LayoutShadowNode {
-    static final Object ZERO_LAYOUT = new Object();
-
-    @Override
-    public void onCollectExtraUpdates(UIViewOperationQueue uiViewOperationQueue) {
-        super.onCollectExtraUpdates(uiViewOperationQueue);
-        if (Math.round(getLayoutWidth()) == 0 && Math.round(getLayoutHeight()) == 0) {
-            uiViewOperationQueue.enqueueUpdateExtraData(getReactTag(), ZERO_LAYOUT);
-        }
-    }
-}