@amazon-devices/expo-image 2.0.1758683737

package/src/web/AnimationManager.tsx

@@ -0,0 +1,224 @@
+import React from 'react';
+
+import { ImageTransition } from '../Image.types';
+
+type Callbacks = {
+  onReady?: (() => void) | null;
+  onAnimationFinished?: (() => void) | null;
+  onMount?: (() => void) | null;
+  onError?: (() => void) | null;
+};
+
+export type AnimationManagerNode = [
+  key: string,
+  renderFunction: (
+    renderProps: NonNullable<Callbacks>
+  ) => (className: string, style: React.CSSProperties) => React.ReactElement,
+];
+
+const SUPPORTED_ANIMATIONS: ImageTransition['effect'][] = [
+  'cross-dissolve',
+  'flip-from-left',
+  'flip-from-right',
+  'flip-from-top',
+  'flip-from-bottom',
+];
+
+type NodeStatus = 'mounted' | 'in' | 'active' | 'out' | 'errored';
+
+function useAnimationManagerNode(node: AnimationManagerNode | null, initialStatus?: NodeStatus) {
+  const newNode = React.useMemo(() => {
+    if (!node) {
+      return null;
+    }
+    const [animationKey, renderFunction] = node;
+    // key, ReactElement, ref, callbacks
+    return {
+      animationKey,
+      persistedElement: renderFunction,
+      status: (initialStatus || 'mounted') as NodeStatus,
+    };
+  }, [node?.[0]]);
+  return newNode;
+}
+
+function validateTimingFunctionForAnimation(
+  animationClass: ImageTransition['effect'],
+  timingFunction: ImageTransition['timing']
+) {
+  if (animationClass?.includes('flip')) {
+    if (timingFunction?.includes('ease')) {
+      return 'ease-in-out';
+    }
+    return 'linear';
+  }
+  return timingFunction || null;
+}
+
+function validateAnimationClass(effect: ImageTransition['effect']) {
+  if (SUPPORTED_ANIMATIONS.includes(effect)) {
+    return effect;
+  }
+  return 'cross-dissolve';
+}
+
+export function getAnimatorFromTransition(transition: ImageTransition | null | undefined) {
+  if (!transition?.duration) {
+    return null;
+  }
+  const animationClass = validateAnimationClass(transition.effect);
+  if (!animationClass) {
+    return {
+      startingClass: '',
+      animateInClass: '',
+      animateOutClass: '',
+      containerClass: '',
+      timingFunction: 'linear',
+      animationClass: '',
+      duration: 0,
+    };
+  }
+
+  const timingFunction = validateTimingFunctionForAnimation(animationClass, transition.timing);
+  const timingClass = `image-timing-${timingFunction}`;
+
+  return {
+    startingClass: `${animationClass}-start`,
+    animateInClass: [animationClass, 'transitioning', `${animationClass}-active`, timingClass].join(
+      ' '
+    ),
+    animateOutClass: [animationClass, `${animationClass}-end`, timingClass].join(' '),
+    containerClass: `${animationClass}-container`,
+    timingFunction,
+    animationClass,
+    duration: transition?.duration || 0,
+  };
+}
+
+type MountedAnimationNode = {
+  animationKey: string;
+  persistedElement: (
+    renderProps: Callbacks
+  ) => (className: string, style: React.CSSProperties) => React.ReactElement;
+  status: NodeStatus;
+};
+
+export default function AnimationManager({
+  children: renderFunction,
+  initial,
+  transition,
+  recyclingKey,
+}: {
+  children: AnimationManagerNode;
+  initial: AnimationManagerNode | null;
+  transition: ImageTransition | null | undefined;
+  recyclingKey?: string | null | undefined;
+}) {
+  const animation = getAnimatorFromTransition(transition);
+
+  const initialNode = useAnimationManagerNode(initial, 'active');
+
+  const [nodes, setNodes] = React.useState<MountedAnimationNode[]>(
+    initialNode ? [initialNode] : []
+  );
+
+  const [prevRecyclingKey, setPrevRecyclingKey] = React.useState<string>(recyclingKey ?? '');
+  if (prevRecyclingKey !== (recyclingKey ?? '')) {
+    setPrevRecyclingKey(recyclingKey ?? '');
+    setNodes(initialNode ? [initialNode] : []);
+  }
+
+  const removeAllNodesOfKeyExceptShowing = (key?: string) => {
+    setNodes((n) =>
+      n.filter(
+        (node) =>
+          (key ? node.animationKey !== key : false) ||
+          node.status === 'in' ||
+          node.status === 'active'
+      )
+    );
+  };
+
+  const newNode = useAnimationManagerNode(renderFunction);
+
+  React.useEffect(() => {
+    setNodes((n) => {
+      if (!newNode) {
+        return n;
+      }
+      const existingNodeIndex = n.findIndex((node) => node.animationKey === newNode.animationKey);
+      if (existingNodeIndex >= 0) {
+        if (animation) {
+          return n.map((n2) =>
+            n2.animationKey === newNode.animationKey
+              ? { ...newNode, status: 'in' }
+              : { ...n2, status: 'out' }
+          );
+        } else {
+          return [{ ...newNode, status: 'in' }];
+        }
+      }
+      return [...n, newNode];
+    });
+  }, [newNode]);
+
+  function wrapNodeWithCallbacks(node: MountedAnimationNode) {
+    if (renderFunction[0] === node.animationKey) {
+      return renderFunction[1]({
+        onReady: () => {
+          if (animation) {
+            setNodes((nodes) =>
+              nodes.map((n) => (n === newNode ? { ...n, status: 'in' } : { ...n, status: 'out' }))
+            );
+          } else {
+            setNodes([{ ...node, status: 'in' }]);
+          }
+        },
+        onAnimationFinished: () => {
+          setNodes([{ ...node, status: 'in' }]);
+        },
+        onError: () => {
+          setNodes((nodes) => nodes.map((n) => (n === node ? { ...n, status: 'errored' } : n)));
+        },
+      });
+    }
+    if (initial?.[0] === node.animationKey) {
+      return initial[1]({
+        onAnimationFinished: () => {
+          if (node.status === 'out') {
+            removeAllNodesOfKeyExceptShowing(node.animationKey);
+          }
+        },
+        onError: () => {
+          setNodes((nodes) => nodes.map((n) => (n === node ? { ...n, status: 'errored' } : n)));
+        },
+      });
+    }
+    return node.persistedElement({
+      onAnimationFinished: () => {
+        removeAllNodesOfKeyExceptShowing(node.animationKey);
+      },
+    });
+  }
+  const styles = {
+    transitionDuration: `${animation?.duration || 0}ms`,
+    transitionTimingFunction: animation?.timingFunction || 'linear',
+  };
+  const classes = {
+    in: animation?.animateInClass,
+    out: animation?.animateOutClass,
+    mounted: animation?.startingClass,
+  };
+
+  return (
+    <>
+      {[...nodes]
+        .filter((n) => n.status !== 'errored')
+        .map((n) => (
+          <div className={animation?.containerClass} key={n.animationKey}>
+            {wrapNodeWithCallbacks(n)(classes[n.status], styles)}
+          </div>
+        ))}
+    </>
+  );
+}

package/src/web/ColorTintFilter.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+
+export function getTintColorStyle(tintColor?: string | null) {
+  if (!tintColor) {
+    return {};
+  }
+  return {
+    filter: `url(#expo-image-tint-${tintColor})`,
+  };
+}
+
+type TintColorFilterProps = { tintColor?: string | null };
+
+export default function TintColorFilter({ tintColor }: TintColorFilterProps) {
+  if (!tintColor) {
+    return null;
+  }
+  return (
+    <svg style={styles.svg}>
+      <defs>
+        <filter id={`expo-image-tint-${tintColor}`} x="0" y="0" width="0" height="0">
+          <feFlood floodColor={tintColor} floodOpacity="1" result="flood" />
+          <feComposite in="flood" in2="SourceAlpha" operator="in" />
+        </filter>
+      </defs>
+    </svg>
+  );
+}
+
+const styles = StyleSheet.create({
+  svg: {
+    width: 0,
+    height: 0,
+  },
+});

package/src/web/ImageWrapper.tsx

@@ -0,0 +1,85 @@
+import React, { useEffect, Ref } from 'react';
+
+import ColorTintFilter, { getTintColorStyle } from './ColorTintFilter';
+import { ImageWrapperProps } from './ImageWrapper.types';
+import { getImageWrapperEventHandler } from './getImageWrapperEventHandler';
+import { useHeaders, useImageHashes } from './hooks';
+import { absoluteFilledPosition, getObjectPositionFromContentPositionObject } from './positioning';
+import { SrcSetSource } from './useSourceSelection';
+import { ImageNativeProps, ImageSource } from '../Image.types';
+
+function getFetchPriorityFromImagePriority(priority: ImageNativeProps['priority'] = 'normal') {
+  return priority && ['low', 'high'].includes(priority) ? priority : 'auto';
+}
+
+function getImgPropsFromSource(source: ImageSource | SrcSetSource | null | undefined) {
+  if (source && 'srcset' in source) {
+    return {
+      srcSet: source.srcset,
+      sizes: source.sizes,
+    };
+  }
+  return {};
+}
+
+const ImageWrapper = React.forwardRef(
+  (
+    {
+      source,
+      events,
+      contentPosition,
+      hashPlaceholderContentPosition,
+      priority,
+      style,
+      hashPlaceholderStyle,
+      tintColor,
+      className,
+      accessibilityLabel,
+      cachePolicy,
+      ...props
+    }: ImageWrapperProps,
+    ref: Ref<HTMLImageElement>
+  ) => {
+    useEffect(() => {
+      events?.onMount?.forEach((e) => e?.());
+    }, []);
+
+    // Thumbhash uri always has to start with 'thumbhash:/'
+    const { resolvedSource, isImageHash } = useImageHashes(source);
+    const objectPosition = getObjectPositionFromContentPositionObject(
+      isImageHash ? hashPlaceholderContentPosition : contentPosition
+    );
+
+    const sourceWithHeaders = useHeaders(resolvedSource, cachePolicy, events?.onError);
+    if (!sourceWithHeaders) {
+      return null;
+    }
+    return (
+      <>
+        <ColorTintFilter tintColor={tintColor} />
+        <img
+          ref={ref}
+          alt={accessibilityLabel}
+          className={className}
+          src={sourceWithHeaders?.uri || undefined}
+          key={source?.uri}
+          style={{
+            objectPosition,
+            ...absoluteFilledPosition,
+            ...getTintColorStyle(tintColor),
+            ...style,
+            ...(isImageHash ? hashPlaceholderStyle : {}),
+          }}
+          // @ts-ignore
+          // eslint-disable-next-line react/no-unknown-property
+          fetchpriority={getFetchPriorityFromImagePriority(priority || 'normal')}
+          {...getImageWrapperEventHandler(events, sourceWithHeaders)}
+          {...getImgPropsFromSource(source)}
+          {...props}
+        />
+      </>
+    );
+  }
+);
+
+export default ImageWrapper;

package/src/web/ImageWrapper.types.ts

@@ -0,0 +1,36 @@
+import { CSSProperties, SyntheticEvent } from 'react';
+
+import { SrcSetSource } from './useSourceSelection';
+import { ImageContentPositionObject, ImageProps, ImageSource } from '../Image.types';
+
+export type OnErrorEvent =
+  | (({ source }: { source: ImageSource | null }) => void)
+  | undefined
+  | null;
+export type OnLoadEvent =
+  | ((event: SyntheticEvent<HTMLImageElement, Event>) => void)
+  | undefined
+  | null;
+export type OnTransitionEndEvent = (() => void) | undefined | null;
+export type OnMountEvent = (() => void) | undefined | null;
+
+export type ImageWrapperEvents = {
+  onLoad?: OnLoadEvent[];
+  onError?: OnErrorEvent[];
+  onTransitionEnd?: OnTransitionEndEvent[];
+  onMount?: OnMountEvent[];
+};
+
+export type ImageWrapperProps = {
+  source?: ImageSource | SrcSetSource | null;
+  events?: ImageWrapperEvents;
+  contentPosition?: ImageContentPositionObject;
+  hashPlaceholderContentPosition?: ImageContentPositionObject;
+  priority?: string | null;
+  style: CSSProperties;
+  tintColor?: string | null;
+  hashPlaceholderStyle?: CSSProperties;
+  className?: string;
+  accessibilityLabel?: string;
+  cachePolicy?: ImageProps['cachePolicy'];
+};

package/src/web/getImageWrapperEventHandler.ts

@@ -0,0 +1,29 @@
+import { ImageWrapperEvents } from './ImageWrapper.types';
+import { ImageSource } from '../Image.types';
+import { isBlurhashString } from '../utils/resolveSources';
+
+export function getImageWrapperEventHandler(
+  events: ImageWrapperEvents | undefined,
+  source: ImageSource
+) {
+  return {
+    onLoad: (event) => {
+      if (typeof window !== 'undefined') {
+        // this ensures the animation will run, since the starting class is applied at least 1 frame before the target class set in the onLoad event callback
+        window.requestAnimationFrame(() => {
+          events?.onLoad?.forEach((e) => e?.(event));
+        });
+      } else {
+        events?.onLoad?.forEach((e) => e?.(event));
+      }
+    },
+    onTransitionEnd: () => events?.onTransitionEnd?.forEach((e) => e?.()),
+    onError: () => {
+      // A temporary workaround for blurhash blobs throwing opaque errors when used in an img tag.
+      if (source?.uri && isBlurhashString(source?.uri)) {
+        return;
+      }
+      events?.onError?.forEach((e) => e?.({ source: source || null }));
+    },
+  };
+}

package/src/web/hooks.ts

@@ -0,0 +1,72 @@
+import { useEffect, useMemo, useState } from 'react';
+
+import { OnErrorEvent } from './ImageWrapper.types';
+import { ImageNativeProps, ImageSource } from '../Image.types';
+import { useBlurhash } from '../utils/blurhash/useBlurhash';
+import { isThumbhashString } from '../utils/resolveSources';
+import { thumbHashStringToDataURL } from '../utils/thumbhash/thumbhash';
+
+export function useThumbhash(source: ImageSource | null | undefined) {
+  const isThumbhash = isThumbhashString(source?.uri || '');
+  const strippedThumbhashString = source?.uri?.replace(/thumbhash:\//, '') ?? '';
+  const thumbhashSource = useMemo(
+    () => (isThumbhash ? { uri: thumbHashStringToDataURL(strippedThumbhashString) } : null),
+    [strippedThumbhashString, isThumbhash]
+  );
+  return thumbhashSource;
+}
+
+export function useImageHashes(source: ImageSource | null | undefined) {
+  const thumbhash = useThumbhash(source);
+  const blurhash = useBlurhash(source);
+  return useMemo(
+    () => ({
+      resolvedSource: blurhash ?? thumbhash ?? source,
+      isImageHash: !!blurhash || !!thumbhash,
+    }),
+    [blurhash, thumbhash]
+  );
+}
+
+export function useHeaders(
+  source: ImageSource | null | undefined,
+  cachePolicy: ImageNativeProps['cachePolicy'],
+  onError?: OnErrorEvent[]
+): ImageSource | null | undefined {
+  const [objectURL, setObjectURL] = useState<string | null>(null);
+  useEffect(() => {
+    (async () => {
+      if (!source?.headers || !source.uri) {
+        return;
+      }
+      try {
+        const result = await fetch(source.uri, {
+          headers: source.headers,
+          cache: cachePolicy === 'none' ? 'no-cache' : 'default',
+          redirect: 'follow',
+        });
+        if (!result.ok) {
+          throw new Error(`Failed to fetch image: ${result.status} ${result.statusText}`);
+        }
+        const blob = await result.blob();
+        setObjectURL((prevObjURL) => {
+          if (prevObjURL) {
+            URL.revokeObjectURL(prevObjURL);
+          }
+          return URL.createObjectURL(blob);
+        });
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      } catch (error) {
+        onError?.forEach((e) => e?.({ source }));
+      }
+    })();
+  }, [source]);
+  if (!source?.headers) {
+    return source;
+  }
+  if (!objectURL) {
+    // Avoid fetching a URL without headers if we have headers
+    return null;
+  }
+  return { ...source, uri: objectURL };
+}

package/src/web/imageStyles.tsx

@@ -0,0 +1,136 @@
+const style = `
+[data-expoimage] .cross-dissolve {
+  transition-property: opacity;
+  animation-fill-mode: forwards;
+}
+[data-expoimage] .cross-dissolve-start:not(.transitioning) {
+  opacity: 0;
+}
+[data-expoimage] .cross-dissolve-active {
+  opacity: 1;
+}
+[data-expoimage] .cross-dissolve-end {
+  opacity: 0;
+}
+[data-expoimage] .flip-from-left {
+  transition-property: transform, opacity;
+  transition-timing-function: var(--expo-image-timing,linear), steps(2, jump-none) !important;
+  transform-origin: center;
+
+}
+[data-expoimage] .flip-from-left-container {
+  width: 100%;
+  height: 100%;
+  position: absolute;
+  left: 0;
+  top: 0;
+  perspective: 1000px;
+}
+[data-expoimage] .flip-from-left-start:not(.transitioning) {
+  transform:  translateZ(calc(var(--expo-image-width,1000px) * -1.25)) rotateY(-180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-left-active {
+  transform: translateZ(0px) rotateY(0) ;
+  opacity:1;
+}
+[data-expoimage] .flip-from-left-end {
+  transform:  translateZ(calc(var(--expo-image-width,1000px) * -1.25)) rotateY(180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-right {
+  transition-property: transform, opacity;
+  transition-timing-function: var(--expo-image-timing,linear), steps(2, jump-none) !important;
+  transform-origin: center;
+}
+[data-expoimage] .flip-from-right-container {
+  width: 100%;
+  height: 100%;
+  position: absolute;
+  left: 0;
+  top: 0;
+  perspective: 1000px;
+}
+[data-expoimage] .flip-from-right-start:not(.transitioning) {
+  transform:  translateZ(calc(var(--expo-image-width,1000px) * -1.25)) rotateY(180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-right-active {
+  transform: translateZ(0px) rotateY(0) ;
+  opacity:1;
+}
+[data-expoimage] .flip-from-right-end {
+  transform:  translateZ(calc(var(--expo-image-width,1000px) * -1.25)) rotateY(-180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-top {
+  transition-property: transform, opacity;
+  transition-timing-function: var(--expo-image-timing,linear), steps(2, jump-none) !important;
+  transform-origin: center;
+}
+[data-expoimage] .flip-from-top-container {
+  width: 100%;
+  height: 100%;
+  position: absolute;
+  left: 0;
+  top: 0;
+  perspective: 1000px;
+}
+[data-expoimage] .flip-from-top-start:not(.transitioning) {
+  transform:  translateZ(calc(var(--expo-image-height,1000px) * -1.5)) rotateX(180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-top-active {
+  transform: translateZ(0px) rotateX(0) ;
+  opacity:1;
+}
+[data-expoimage] .flip-from-top-end {
+  transform:  translateZ(calc(var(--expo-image-height,1000px) * -1.5)) rotateX(-180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-bottom {
+  transition-property: transform, opacity;
+  transition-timing-function: var(--expo-image-timing,linear), steps(2, jump-none) !important;
+  transform-origin: center;
+}
+[data-expoimage] .flip-from-bottom-container {
+  width: 100%;
+  height: 100%;
+  position: absolute;
+  left: 0;
+  top: 0;
+  perspective: 1000px;
+}
+[data-expoimage] .flip-from-bottom-start:not(.transitioning) {
+  transform:  translateZ(calc(var(--expo-image-height,1000px) * -1.25)) rotateX(-180deg);
+  opacity: 0;
+}
+[data-expoimage] .flip-from-bottom-active {
+  transform: translateZ(0px) rotateX(0) ;
+  opacity:1;
+}
+[data-expoimage] .flip-from-bottom-end {
+  transform:  translateZ(calc(var(--expo-image-height,1000px) * -1.25)) rotateX(180deg);
+  opacity: 0;
+}
+[data-expoimage] .image-timing-linear {
+  --expo-image-timing: linear;
+}
+[data-expoimage] .image-timing-ease-in {
+  --expo-image-timing: ease-in;
+}
+[data-expoimage] .image-timing-ease-out {
+  --expo-image-timing: ease-out;
+}
+[data-expoimage] .image-timing-ease-in-out {
+  --expo-image-timing: ease-in-out;
+}
+`;
+export default function loadStyle() {
+  if (typeof document !== 'undefined') {
+    const styleTag = document.createElement('style');
+    styleTag.innerHTML = style;
+    styleTag.id = 'expo-image-styles';
+    document.head.appendChild(styleTag);
+  }
+}

package/src/web/positioning.ts

@@ -0,0 +1,48 @@
+import { ImageContentPositionObject, ImageContentPositionValue } from '../Image.types';
+
+export function ensureValueIsWebUnits(value: string | number) {
+  const trimmedValue = String(value).trim();
+  if (trimmedValue.endsWith('%')) {
+    return trimmedValue;
+  }
+  return `${trimmedValue}px`;
+}
+
+type KeysOfUnion<T> = T extends T ? keyof T : never;
+
+export const absoluteFilledPosition = {
+  width: '100%',
+  height: '100%',
+  position: 'absolute',
+  left: 0,
+  top: 0,
+} as const;
+
+export function getObjectPositionFromContentPositionObject(
+  contentPosition?: ImageContentPositionObject
+): string {
+  const resolvedPosition = { ...contentPosition } as Record<
+    KeysOfUnion<ImageContentPositionObject>,
+    ImageContentPositionValue
+  >;
+  if (!resolvedPosition) {
+    return '50% 50%';
+  }
+  if (resolvedPosition.top == null && resolvedPosition.bottom == null) {
+    resolvedPosition.top = '50%';
+  }
+  if (resolvedPosition.left == null && resolvedPosition.right == null) {
+    resolvedPosition.left = '50%';
+  }
+
+  return (
+    ['top', 'bottom', 'left', 'right']
+      .map((key) => {
+        if (key in resolvedPosition) {
+          return `${key} ${ensureValueIsWebUnits(resolvedPosition[key])}`;
+        }
+        return '';
+      })
+      .join(' ') || '50% 50%'
+  );
+}