@symbiote-native/image 0.0.0-stage → 0.0.0

package/src/core/native-style.ts

@@ -0,0 +1,89 @@
+import { Platform } from 'expo-modules-core';
+import { flattenStyle, processColor } from '@symbiote-native/engine';
+import type { IColorValue, IViewStyle } from '@symbiote-native/engine';
+import type { IImageResizeMode } from './types';
+
+type IStyleBag = Record<string, unknown>;
+
+const SHADOW_KEYS = [
+  'shadowColor',
+  'shadowOffset',
+  'shadowOpacity',
+  'shadowRadius',
+] as const satisfies readonly (keyof IViewStyle)[];
+
+const BORDER_COLOR_KEYS = [
+  'borderColor',
+  'borderStartColor',
+  'borderEndColor',
+  'borderLeftColor',
+  'borderRightColor',
+  'borderTopColor',
+  'borderBottomColor',
+] as const satisfies readonly (keyof IViewStyle)[];
+
+const RESIZE_MODES = new Set<unknown>([
+  'cover',
+  'contain',
+  'stretch',
+  'repeat',
+  'center',
+] as const satisfies readonly IImageResizeMode[]);
+
+export type IImageStyleParts = {
+  resizeMode?: IImageResizeMode;
+  fontWeight?: string | number;
+  fontSize?: number;
+  color?: unknown;
+  /** What is left once the text-like keys are taken out */
+  rest: IStyleBag;
+};
+
+function isResizeMode(value: unknown): value is IImageResizeMode {
+  return RESIZE_MODES.has(value);
+}
+
+function isColorValue(value: unknown): value is IColorValue {
+  return (
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    (typeof value === 'object' && value !== null)
+  );
+}
+
+/** An Expo view has no attribute processor for colors, so they go through here */
+export function toNativeColor(value: unknown): unknown {
+  return isColorValue(value) ? processColor(value) : undefined;
+}
+
+/** `resizeMode` and the SF Symbol keys are props to native, not style */
+export function splitImageStyle(style: unknown): IImageStyleParts {
+  const { resizeMode, fontWeight, fontSize, color, ...rest } = flattenStyle(style);
+  const isWeight = typeof fontWeight === 'string' || typeof fontWeight === 'number';
+  return {
+    resizeMode: isResizeMode(resizeMode) ? resizeMode : undefined,
+    fontWeight: isWeight ? fontWeight : undefined,
+    fontSize: typeof fontSize === 'number' ? fontSize : undefined,
+    color,
+    rest,
+  };
+}
+
+function without(bag: IStyleBag, keys: readonly string[]): IStyleBag {
+  return Object.fromEntries(Object.entries(bag).filter(([key]) => !keys.includes(key)));
+}
+
+/** Android shadows by `elevation` and paints the background itself, iOS by `shadow*` */
+export function platformStyle(style: IStyleBag): IStyleBag {
+  return Platform.select({
+    android: without(style, [...SHADOW_KEYS, 'backgroundColor']),
+    default: without(style, ['elevation']),
+  });
+}
+
+/** `backgroundColor` and the border colors in the form native reads */
+export function nativeColorProps(style: IStyleBag): IStyleBag {
+  return Object.fromEntries(
+    ['backgroundColor', ...BORDER_COLOR_KEYS].map(key => [key, toNativeColor(style[key])]),
+  );
+}

package/src/core/props.ts

@@ -0,0 +1,118 @@
+import type {
+  IImageContentFit,
+  IImageContentPosition,
+  IImageContentPositionObject,
+  IImageContentPositionString,
+  IImageResizeMode,
+  IImageTransition,
+  IImageViewProps,
+  ISfSymbolEffectObject,
+} from './types';
+
+const CENTER: IImageContentPositionObject = { top: '50%', left: '50%' };
+
+const POSITION_BY_KEYWORD: Record<IImageContentPositionString, IImageContentPositionObject> = {
+  center: CENTER,
+  top: { top: 0, left: '50%' },
+  right: { top: '50%', right: 0 },
+  bottom: { bottom: 0, left: '50%' },
+  left: { top: '50%', left: 0 },
+  'top center': { top: 0, left: '50%' },
+  'top right': { top: 0, right: 0 },
+  'top left': { top: 0, left: 0 },
+  'right center': { top: '50%', right: 0 },
+  'right top': { top: 0, right: 0 },
+  'right bottom': { bottom: 0, right: 0 },
+  'bottom center': { bottom: 0, left: '50%' },
+  'bottom right': { bottom: 0, right: 0 },
+  'bottom left': { bottom: 0, left: 0 },
+  'left center': { top: '50%', left: 0 },
+  'left top': { top: 0, left: 0 },
+  'left bottom': { bottom: 0, left: 0 },
+};
+
+const warned = new Set<string>();
+
+export function warnOnce(message: string): void {
+  if (warned.has(message)) {
+    return;
+  }
+  warned.add(message);
+  console.warn(`[expo-image]: ${message}`);
+}
+
+export function resetDeprecationWarnings(): void {
+  warned.clear();
+}
+
+function fitFromResizeMode(resizeMode: IImageResizeMode): IImageContentFit {
+  warnOnce('Prop "resizeMode" is deprecated, use "contentFit" instead');
+  switch (resizeMode) {
+    case 'contain':
+    case 'cover':
+      return resizeMode;
+    case 'stretch':
+      return 'fill';
+    case 'center':
+      return 'scale-down';
+    case 'repeat':
+      warnOnce('Resize mode "repeat" is no longer supported');
+      return 'cover';
+  }
+}
+
+/** An SF Symbol defaults to `contain` to keep its aspect ratio */
+export function resolveContentFit(
+  contentFit?: IImageContentFit,
+  resizeMode?: IImageResizeMode,
+  isSfSymbol?: boolean,
+): IImageContentFit {
+  if (contentFit) {
+    return contentFit;
+  }
+  if (resizeMode) {
+    return fitFromResizeMode(resizeMode);
+  }
+  return isSfSymbol ? 'contain' : 'cover';
+}
+
+/** Native reads only the two-edge object form */
+export function resolveContentPosition(
+  contentPosition?: IImageContentPosition,
+): IImageContentPositionObject {
+  if (typeof contentPosition !== 'string') {
+    return contentPosition ?? CENTER;
+  }
+  const resolved = POSITION_BY_KEYWORD[contentPosition];
+  if (!resolved) {
+    warnOnce(`Content position "${contentPosition}" is invalid`);
+    return CENTER;
+  }
+  return resolved;
+}
+
+/** Every form of `sfEffect` becomes a list of effect objects */
+export function resolveSfEffect(
+  sfEffect: IImageViewProps['sfEffect'],
+): ISfSymbolEffectObject[] | null {
+  if (sfEffect == null) {
+    return null;
+  }
+  const effects = Array.isArray(sfEffect) ? sfEffect : [sfEffect];
+  return effects.map(item => (typeof item === 'string' ? { effect: item } : item));
+}
+
+/** A number is the duration of a cross dissolve */
+export function resolveTransition(
+  transition?: IImageViewProps['transition'],
+  fadeDuration?: IImageViewProps['fadeDuration'],
+): IImageTransition | null {
+  if (typeof transition === 'number') {
+    return { duration: transition };
+  }
+  if (!transition && typeof fadeDuration === 'number') {
+    warnOnce('Prop "fadeDuration" is deprecated, use "transition" instead');
+    return { duration: fadeDuration };
+  }
+  return transition ?? null;
+}

package/src/core/sources.ts

@@ -0,0 +1,70 @@
+import { resolveAssetSource } from '@symbiote-native/engine';
+import { SharedRef } from 'expo-modules-core';
+import { SF_SYMBOL_PREFIX } from './constants';
+import { resolveBlurhashString, resolveThumbhashString } from './hash-strings';
+import type { IImageSource, IImageSources } from './types';
+
+const BLURHASH_PATTERN = /^(blurhash:\/)+[\w#$%*+,\-.:;=?@[\]^_{}|~]+(\/[\d.]+)*$/;
+const THUMBHASH_PREFIX = 'thumbhash:/';
+
+type IImageSourceInput = IImageSource | string | number | null | undefined;
+
+// Any native image reference, an `ImageRef` or a `VideoThumbnail`, the view takes both
+export function isImageRef(value: unknown): value is SharedRef<'image'> {
+  return value instanceof SharedRef && value.nativeRefType === 'image';
+}
+
+function sharedIdOf(ref: SharedRef<'image'>): number {
+  const id: unknown = Reflect.get(ref, '__expo_shared_object_id__');
+  return typeof id === 'number' ? id : 0;
+}
+
+function isImageSource(value: unknown): value is IImageSource {
+  return typeof value === 'object' && value !== null;
+}
+
+function nativeAssetSource(id: number): IImageSource | null {
+  const asset = resolveAssetSource(id);
+  return isImageSource(asset) ? asset : null;
+}
+
+export function resolveSource(source: IImageSourceInput): IImageSource | null {
+  if (typeof source === 'string') {
+    if (BLURHASH_PATTERN.test(source)) {
+      return resolveBlurhashString(source);
+    }
+    if (source.startsWith(THUMBHASH_PREFIX)) {
+      return resolveThumbhashString(source);
+    }
+    if (source.startsWith(SF_SYMBOL_PREFIX)) {
+      return { uri: `${SF_SYMBOL_PREFIX}/${source.slice(SF_SYMBOL_PREFIX.length)}` };
+    }
+    return { uri: source };
+  }
+  if (typeof source === 'number') {
+    return nativeAssetSource(source);
+  }
+  if (source?.blurhash || source?.thumbhash) {
+    const { blurhash, thumbhash, ...rest } = source;
+    const resolved = thumbhash
+      ? resolveThumbhashString(thumbhash)
+      : resolveBlurhashString(blurhash ?? '');
+    return { ...resolved, ...rest };
+  }
+  return source ?? null;
+}
+
+function isPresent(source: IImageSource | null): source is IImageSource {
+  return source !== null;
+}
+
+/** The shape the native view takes: a list of sources or a shared object id */
+export function resolveSources(sources: IImageSources | undefined): IImageSource[] | number {
+  if (Array.isArray(sources)) {
+    return sources.map(resolveSource).filter(isPresent);
+  }
+  if (isImageRef(sources)) {
+    return sharedIdOf(sources);
+  }
+  return [resolveSource(sources)].filter(isPresent);
+}

package/src/core/types.ts

@@ -0,0 +1,278 @@
+import type {
+  IAccessibilityProps,
+  IAriaProps,
+  IResponderProps,
+} from '@symbiote-native/components';
+import type {
+  IColorValue,
+  IStyleProp,
+  ITextStyle,
+  IViewStyle,
+} from '@symbiote-native/engine';
+import type { SharedRef } from 'expo-modules-core';
+import type { SFSymbol } from 'sf-symbols-typescript';
+
+export type IImageSource = {
+  /** `http(s)`, `file`, `data`, an asset URI and the `sf:/` and `blurhash:/` schemes */
+  uri?: string;
+  /** Sent with the request */
+  headers?: Record<string, string>;
+  /** Used for layout while the image loads, and the size of a hash placeholder */
+  width?: number | null;
+  height?: number | null;
+  /** A Blurhash string, the source becomes a `blurhash:/` uri */
+  blurhash?: string;
+  /** A Thumbhash string, the source becomes a `thumbhash:/` uri */
+  thumbhash?: string;
+  /** The key of the cache entry, the uri by default */
+  cacheKey?: string;
+  /** Web only */
+  webMaxViewportWidth?: number;
+  /** Plays the image as an animation, detected from the content by default */
+  isAnimated?: boolean;
+};
+
+export type IImageContentFit = 'cover' | 'contain' | 'fill' | 'none' | 'scale-down';
+
+export type IImageDecodeFormat = 'argb' | 'rgb';
+
+export type IImageResizeMode = 'cover' | 'contain' | 'stretch' | 'repeat' | 'center';
+
+export type IImageContentPositionValue =
+  | number
+  | string
+  | `${number}%`
+  | `${number}`
+  | 'center';
+
+export type IImageContentPositionString =
+  | 'center'
+  | 'top'
+  | 'right'
+  | 'bottom'
+  | 'left'
+  | 'top center'
+  | 'top right'
+  | 'top left'
+  | 'right center'
+  | 'right top'
+  | 'right bottom'
+  | 'bottom center'
+  | 'bottom right'
+  | 'bottom left'
+  | 'left center'
+  | 'left top'
+  | 'left bottom';
+
+/** Two edges, the native side takes only this form */
+export type IImageContentPositionObject =
+  | { top?: IImageContentPositionValue; right?: IImageContentPositionValue }
+  | { top?: IImageContentPositionValue; left?: IImageContentPositionValue }
+  | { bottom?: IImageContentPositionValue; right?: IImageContentPositionValue }
+  | { bottom?: IImageContentPositionValue; left?: IImageContentPositionValue };
+
+export type IImageContentPosition =
+  | IImageContentPositionObject
+  | IImageContentPositionString;
+
+export type IImageTransition = {
+  /** In milliseconds */
+  duration?: number;
+  timing?: 'ease-in-out' | 'ease-in' | 'ease-out' | 'linear';
+  effect?:
+    | 'cross-dissolve'
+    | 'flip-from-top'
+    | 'flip-from-right'
+    | 'flip-from-bottom'
+    | 'flip-from-left'
+    | 'curl-up'
+    | 'curl-down'
+    | 'sf:replace'
+    | 'sf:down-up'
+    | 'sf:up-up'
+    | 'sf:off-up'
+    | null;
+};
+
+export type ISfSymbolEffectType =
+  | 'bounce'
+  | 'bounce/up'
+  | 'bounce/down'
+  | 'pulse'
+  | 'variable-color'
+  | 'variable-color/iterative'
+  | 'variable-color/cumulative'
+  | 'scale'
+  | 'scale/up'
+  | 'scale/down'
+  | 'appear'
+  | 'disappear'
+  | 'wiggle'
+  | 'rotate'
+  | 'breathe'
+  | 'draw/on'
+  | 'draw/off';
+
+export type ISfSymbolEffectObject = {
+  effect: ISfSymbolEffectType;
+  /** `-1` repeats forever */
+  repeat?: number;
+  scope?: 'by-layer' | 'whole-symbol' | null;
+};
+
+/** iOS 17+ for an SF Symbol source */
+export type ISfSymbolEffect =
+  | ISfSymbolEffectType
+  | ISfSymbolEffectObject
+  | (ISfSymbolEffectType | ISfSymbolEffectObject)[];
+
+export type IImageLoadEventData = {
+  cacheType: 'none' | 'disk' | 'memory';
+  source: {
+    url: string;
+    width: number;
+    height: number;
+    mediaType: string | null;
+    isAnimated?: boolean;
+  };
+};
+
+export type IImageProgressEventData = { loaded: number; total: number };
+
+export type IImageErrorEventData = { error: string };
+
+export type IImagePrefetchOptions = {
+  /** `memory-disk` by default */
+  cachePolicy?: 'disk' | 'memory-disk' | 'memory';
+  headers?: Record<string, string>;
+};
+
+export type IImageCacheConfig = {
+  /** In bytes */
+  maxDiskSize?: number;
+  /** In bytes */
+  maxMemoryCost?: number;
+  maxMemoryCount?: number;
+};
+
+export type IImageLoadOptions = {
+  maxWidth?: number;
+  maxHeight?: number;
+  tintColor?: IColorValue | number;
+  /** `retry` loads again */
+  onError?(error: Error, retry: () => void): void;
+};
+
+/** A reference to a native image, an image view takes it as its source */
+export declare class ImageRef extends SharedRef<'image'> {
+  readonly width: number;
+  readonly height: number;
+  readonly scale: number;
+  readonly mediaType: string | null;
+  readonly isAnimated?: boolean;
+  /** The id the native view looks the shared object up by */
+  readonly __expo_shared_object_id__: number;
+}
+
+export type IImageStyle = IViewStyle & {
+  tintColor?: IColorValue;
+  resizeMode?: IImageResizeMode;
+  /** With `color` and `fontSize` for an SF Symbol */
+  fontWeight?: ITextStyle['fontWeight'];
+  color?: IColorValue;
+  fontSize?: number;
+};
+
+export type IImageSources =
+  | IImageSource
+  | `sf:${SFSymbol}`
+  | (string & {})
+  | number
+  | IImageSource[]
+  | string[]
+  | SharedRef<'image'>
+  | null;
+
+export type IImageViewProps = IAccessibilityProps &
+  IAriaProps &
+  IResponderProps & {
+    style?: IStyleProp<IImageStyle>;
+    /** A uri, an asset, a source object, a list of them or an `ImageRef` */
+    source?: IImageSources;
+    /** Shown while `source` loads */
+    placeholder?:
+      | IImageSource
+      | string
+      | number
+      | IImageSource[]
+      | string[]
+      | SharedRef<'image'>
+      | null;
+    /** `cover` by default, `contain` for an SF Symbol */
+    contentFit?: IImageContentFit;
+    placeholderContentFit?: IImageContentFit;
+    /** `center` by default */
+    contentPosition?: IImageContentPosition;
+    /** A number is the duration of a cross dissolve */
+    transition?: IImageTransition | number | null;
+    blurRadius?: number;
+    tintColor?: IColorValue | null;
+    priority?: 'low' | 'normal' | 'high' | null;
+    loading?: 'lazy' | 'eager';
+    cachePolicy?: 'none' | 'disk' | 'memory' | 'memory-disk' | null;
+    /** How the image follows a changing view size */
+    responsivePolicy?: 'live' | 'initial' | 'static';
+    /** Lets a recycled list cell tell its images apart */
+    recyclingKey?: string | null;
+    /** Plays an animated image on its own, `true` by default */
+    autoplay?: boolean;
+    /** An effect of an SF Symbol source, iOS 17+ */
+    sfEffect?: ISfSymbolEffect | null;
+    onLoadStart?: () => void;
+    onLoad?: (event: IImageLoadEventData) => void;
+    onProgress?: (event: IImageProgressEventData) => void;
+    onError?: (event: IImageErrorEventData) => void;
+    onLoadEnd?: () => void;
+    onDisplay?: () => void;
+    /** @deprecated Use `placeholder` */
+    defaultSource?: IImageSource | null;
+    /** @deprecated Use `placeholder` */
+    loadingIndicatorSource?: IImageSource | null;
+    /** @deprecated Use `contentFit` */
+    resizeMode?: IImageResizeMode;
+    /** @deprecated Use `transition` */
+    fadeDuration?: number;
+    focusable?: boolean;
+    accessible?: boolean;
+    accessibilityLabel?: string;
+    /** The accessibility label when none is given */
+    alt?: string;
+    /** iOS only, lets the user select text in the image */
+    enableLiveTextInteraction?: boolean;
+    /** Downscales a larger image to the view, `true` by default */
+    allowDownscaling?: boolean;
+    /** Android only, `argb` by default */
+    decodeFormat?: IImageDecodeFormat;
+    /** iOS only */
+    useAppleWebpCodec?: boolean;
+    /** Android only */
+    enforceEarlyResizing?: boolean;
+    /** iOS only */
+    preferHighDynamicRange?: boolean;
+    /** Web only */
+    draggable?: boolean;
+    testID?: string;
+    nativeID?: string;
+  };
+
+/** What a ref to the view hands out */
+export type IImageViewHandle = {
+  /** Starts an animated image */
+  startAnimating(): Promise<void>;
+  stopAnimating(): Promise<void>;
+  /** Keeps the resource from being reloaded */
+  lockResourceAsync(): Promise<void>;
+  unlockResourceAsync(): Promise<void>;
+  /** Reloads the resource, the lock is ignored */
+  reloadAsync(): Promise<void>;
+};

package/src/react/image-background.ts

@@ -0,0 +1,14 @@
+import type { ReactElement, ReactNode } from 'react';
+import { descriptorToReactWithChildren } from '@symbiote-native/react';
+import { renderImageBackground } from '../core';
+import type { IImageBackgroundProps } from '../core';
+
+export type IImageBackgroundReactProps = IImageBackgroundProps & {
+  children?: ReactNode;
+};
+
+/** React twin of `expo-image`'s `ImageBackground`, children paint over the image */
+export function ImageBackground(props: IImageBackgroundReactProps): ReactElement {
+  const { children, ...rest } = props;
+  return descriptorToReactWithChildren(renderImageBackground(rest), children);
+}

package/src/react/image.ts

@@ -0,0 +1,14 @@
+import type { ReactElement, Ref } from 'react';
+import { useNativeViewController } from '@symbiote-native/react';
+import { createImageView } from '../core';
+import type { IImageViewHandle, IImageViewProps } from '../core';
+
+export type IImageReactProps = IImageViewProps & {
+  ref?: Ref<IImageViewHandle>;
+  className?: string;
+};
+
+/** React twin of `expo-image`'s `Image` */
+export function Image({ ref, ...props }: IImageReactProps): ReactElement | null {
+  return useNativeViewController(ref, createImageView, props);
+}

package/src/react/index.ts

@@ -0,0 +1,8 @@
+// @symbiote-native/image/react: the image view, its cache and hash functions on a shared core
+
+export { Image } from './image';
+export type { IImageReactProps } from './image';
+export { ImageBackground } from './image-background';
+export type { IImageBackgroundReactProps } from './image-background';
+export { useImage } from './use-image';
+export * from '../core';

package/src/react/use-image.ts

@@ -0,0 +1,29 @@
+import { useEffect, useRef, useState } from 'react';
+import type { DependencyList } from 'react';
+import { createImageRefLoader, resolveSource } from '../core';
+import type { IImageLoadOptions, IImageSource, ImageRef } from '../core';
+
+/**
+ * Loads an image into a native `ImageRef`, `null` until the first one has loaded
+ *
+ * It loads again when the uri of the source or an item of `dependencies` changes
+ */
+export function useImage(
+  source: IImageSource | string | number,
+  options: IImageLoadOptions = {},
+  dependencies: DependencyList = [],
+): ImageRef | null {
+  const [image, setImage] = useState<ImageRef | null>(null);
+  // The effect reads the options of the latest render, not the ones it started with
+  const latestOptions = useRef(options);
+  latestOptions.current = options;
+  const key = resolveSource(source)?.uri;
+
+  useEffect(() => {
+    const loader = createImageRefLoader(setImage, () => latestOptions.current);
+    loader.load(source);
+    return loader.cancel;
+  }, [key, ...dependencies]);
+
+  return image;
+}

package/src/solid/image-background.ts

@@ -0,0 +1,13 @@
+import type { JSX } from 'solid-js';
+import { defineDescriptorComponent } from '@symbiote-native/solid';
+import { renderImageBackground } from '../core';
+import type { IImageBackgroundProps } from '../core';
+
+export type IImageBackgroundSolidProps = IImageBackgroundProps & {
+  children?: JSX.Element;
+};
+
+/** Solid twin of `expo-image`'s `ImageBackground`, children paint over the image */
+export const ImageBackground = defineDescriptorComponent<IImageBackgroundSolidProps>(
+  renderImageBackground,
+);

package/src/solid/image.ts

@@ -0,0 +1,8 @@
+import { defineNativeViewComponent } from '@symbiote-native/solid';
+import { createImageView } from '../core';
+import type { IImageViewHandle, IImageViewProps } from '../core';
+
+/** Solid twin of `expo-image`'s `Image`, `ref` gets the handle of the view */
+export const Image = defineNativeViewComponent<IImageViewHandle, IImageViewProps>(
+  createImageView,
+);

package/src/solid/index.ts

@@ -0,0 +1,7 @@
+// @symbiote-native/image/solid: the image view, its cache and hash functions on a shared core
+
+export { Image } from './image';
+export { ImageBackground } from './image-background';
+export type { IImageBackgroundSolidProps } from './image-background';
+export { useImage } from './use-image';
+export * from '../core';

package/src/solid/use-image.ts

@@ -0,0 +1,30 @@
+import { createEffect, createSignal, on, onCleanup } from 'solid-js';
+import type { Accessor } from 'solid-js';
+import { createImageRefLoader, resolveSource } from '../core';
+import type { IImageLoadOptions, IImageSource, ImageRef } from '../core';
+
+/**
+ * Solid twin of `expo-image`'s `useImage`, `null` until the first image has loaded
+ *
+ * It loads again when the uri of the source or a `dependencies` accessor changes
+ */
+export function useImage(
+  source: Accessor<IImageSource | string | number>,
+  options: Accessor<IImageLoadOptions> = () => ({}),
+  dependencies: Accessor<unknown>[] = [],
+): Accessor<ImageRef | null> {
+  const [image, setImage] = createSignal<ImageRef | null>(null);
+
+  createEffect(
+    on(
+      () => [resolveSource(source())?.uri, ...dependencies.map(read => read())],
+      () => {
+        const loader = createImageRefLoader(setImage, options);
+        loader.load(source());
+        onCleanup(loader.cancel);
+      },
+    ),
+  );
+
+  return image;
+}