@symbiote-native/image 0.0.0-stage → 0.0.0

package/src/angular/image-background/index.ts

@@ -0,0 +1,69 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { DescriptorHost, NativeViewBase } from '@symbiote-native/angular';
+import type { IDescriptor } from '@symbiote-native/components';
+import { renderImageBackground } from '../../core';
+import type { IStyleProp } from '@symbiote-native/engine';
+import type { IImageBackgroundProps, IImageStyle } from '../../core';
+
+// One list is the inputs of the component and the props it hands to the image
+const IMAGE_BACKGROUND_INPUTS = [
+  'source',
+  'placeholder',
+  'contentFit',
+  'placeholderContentFit',
+  'contentPosition',
+  'transition',
+  'blurRadius',
+  'tintColor',
+  'priority',
+  'loading',
+  'cachePolicy',
+  'responsivePolicy',
+  'recyclingKey',
+  'autoplay',
+  'sfEffect',
+  'onLoadStart',
+  'onLoad',
+  'onProgress',
+  'onError',
+  'onLoadEnd',
+  'onDisplay',
+  'defaultSource',
+  'loadingIndicatorSource',
+  'resizeMode',
+  'fadeDuration',
+  'alt',
+  'enableLiveTextInteraction',
+  'allowDownscaling',
+  'decodeFormat',
+  'useAppleWebpCodec',
+  'enforceEarlyResizing',
+  'preferHighDynamicRange',
+  'draggable',
+  'imageStyle',
+] as const;
+
+export interface ExpoImageBackground
+  extends Partial<Pick<IImageBackgroundProps, (typeof IMAGE_BACKGROUND_INPUTS)[number]>> {}
+
+/** Angular twin of `expo-image`'s `ImageBackground`, the content paints over the image */
+@Component({
+  selector: 'ExpoImageBackground',
+  standalone: true,
+  imports: [DescriptorHost],
+  inputs: [...IMAGE_BACKGROUND_INPUTS],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `@if (descriptor; as node) {
+    <symbiote-descriptor-host [node]="node"><ng-content /></symbiote-descriptor-host>
+  }`,
+})
+export class ExpoImageBackground extends NativeViewBase {
+  // The `style` input of the base, typed like the one of `ExpoImage`
+  declare style?: IStyleProp<IImageStyle>;
+
+  protected override readonly propNames = IMAGE_BACKGROUND_INPUTS;
+
+  protected override renderView(props: object): IDescriptor {
+    return renderImageBackground(props);
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,7 @@
+// @symbiote-native/image/angular: the image view, its cache and hash functions on a shared core
+// The selectors are `ExpoImage*`, `Image` and `ImageBackground` are tags of the adapter
+
+export { ExpoImage } from './image';
+export { ExpoImageBackground } from './image-background';
+export { injectImage } from './inject-image';
+export * from '../core';

package/src/angular/inject-image.ts

@@ -0,0 +1,29 @@
+import { computed, effect, signal, untracked } from '@angular/core';
+import type { Signal } from '@angular/core';
+import { createImageRefLoader, resolveSource } from '../core';
+import type { IImageLoadOptions, IImageSource, ImageRef } from '../core';
+
+/**
+ * Angular twin of `useImage`, `null` until the first image has loaded
+ *
+ * It loads again when the uri of the source or a signal read by `dependencies` changes
+ */
+export function injectImage(
+  source: () => IImageSource | string | number,
+  options: () => IImageLoadOptions = () => ({}),
+  dependencies: () => unknown[] = () => [],
+): Signal<ImageRef | null> {
+  const image = signal<ImageRef | null>(null);
+  const key = computed(() => resolveSource(source())?.uri);
+
+  effect(onCleanup => {
+    // Read so the effect tracks them, the source itself is not a trigger
+    key();
+    dependencies();
+    const loader = createImageRefLoader(loaded => image.set(loaded), options);
+    untracked(() => loader.load(source()));
+    onCleanup(loader.cancel);
+  });
+
+  return image.asReadonly();
+}

package/src/core/constants.ts

@@ -0,0 +1,6 @@
+// Apart from `native-module`, which resolves the module on import: the view needs the name too
+
+export const IMAGE_MODULE_NAME = 'ExpoImage';
+
+/** `sf:name` in a source string, the native side reads `sf:/name` */
+export const SF_SYMBOL_PREFIX = 'sf:';

package/src/core/hash-strings.ts

@@ -0,0 +1,27 @@
+import type { IImageSource } from './types';
+
+type IImageHashType = 'blurhash' | 'thumbhash';
+
+const DEFAULT_HASH_SIZE = 16;
+
+function hashToUri(type: IImageHashType, hash: string): string {
+  const encoded = encodeURI(hash).replace(/#/g, '%23').replace(/\?/g, '%3F');
+  return `${type}:/${encoded}`;
+}
+
+/** `blurhash:/<hash>/<width>/<height>` or `<hash>/<width>/<height>` */
+export function resolveBlurhashString(str: string): IImageSource {
+  const [hash = '', width = '', height = ''] = str.replace(/^blurhash:\//, '').split('/');
+  return {
+    uri: hashToUri('blurhash', hash),
+    width: parseInt(width, 10) || DEFAULT_HASH_SIZE,
+    height: parseInt(height, 10) || DEFAULT_HASH_SIZE,
+  };
+}
+
+/** `thumbhash:/<hash>` or `<hash>` */
+export function resolveThumbhashString(str: string): IImageSource {
+  // A slash at the start of the hash would break the uri path
+  const hash = str.replace(/^thumbhash:\//, '').replace(/\//g, '\\');
+  return { uri: hashToUri('thumbhash', hash) };
+}

package/src/core/image-api.ts

@@ -0,0 +1,67 @@
+import { toNativeColor } from './native-style';
+import { expoImage } from './native-module';
+import { resolveSource } from './sources';
+import type {
+  IImageCacheConfig,
+  IImageLoadOptions,
+  IImagePrefetchOptions,
+  IImageSource,
+  ImageRef,
+} from './types';
+
+const DEFAULT_CACHE_POLICY = 'memory-disk';
+
+type IPrefetchOptions = IImagePrefetchOptions['cachePolicy'] | IImagePrefetchOptions;
+
+/** The caching policy as a string, or with request headers as an object */
+export function prefetchImages(
+  urls: string | string[],
+  options?: IPrefetchOptions,
+): Promise<boolean> {
+  const { cachePolicy = DEFAULT_CACHE_POLICY, headers } =
+    typeof options === 'string' ? { cachePolicy: options } : (options ?? {});
+  return expoImage.prefetch(Array.isArray(urls) ? urls : [urls], cachePolicy, headers);
+}
+
+export const clearMemoryCache = (): Promise<boolean> => expoImage.clearMemoryCache();
+
+export const clearDiskCache = (): Promise<boolean> => expoImage.clearDiskCache();
+
+export const getCachePathAsync = (cacheKey: string): Promise<string | null> =>
+  expoImage.getCachePathAsync(cacheKey);
+
+export const writeToCacheAsync = (
+  source: string | ImageRef,
+  cacheKey: string,
+): Promise<void> => expoImage.writeToCacheAsync(source, cacheKey);
+
+export const readFromCacheAsync = (cacheKey: string): Promise<ImageRef | null> =>
+  expoImage.readFromCacheAsync(cacheKey);
+
+export const configureCache = (config: IImageCacheConfig): void =>
+  expoImage.configureCache(config);
+
+export const generateBlurhashAsync = (
+  source: string | ImageRef,
+  numberOfComponents: [number, number] | { width: number; height: number },
+): Promise<string | null> => expoImage.generateBlurhashAsync(source, numberOfComponents);
+
+export const generateThumbhashAsync = (source: string | ImageRef): Promise<string> =>
+  expoImage.generateThumbhashAsync(source);
+
+/** Loads the image into a native `ImageRef`, the caller releases it */
+export async function loadImageAsync(
+  source: IImageSource | string | number,
+  options: IImageLoadOptions = {},
+): Promise<ImageRef> {
+  const resolved = resolveSource(source);
+  if (!resolved) {
+    throw new Error('[expo-image]: the image source could not be resolved');
+  }
+  const { maxWidth, maxHeight, tintColor } = options;
+  return expoImage.loadAsync(resolved, {
+    maxWidth,
+    maxHeight,
+    tintColor: toNativeColor(tintColor),
+  });
+}

package/src/core/image-background.ts

@@ -0,0 +1,42 @@
+import { el } from '@symbiote-native/components';
+import type { IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp } from '@symbiote-native/engine';
+import { createImageView } from './image-view';
+import type { IImageStyle, IImageViewProps } from './types';
+
+export type IImageBackgroundProps = IImageViewProps & {
+  /** Style of the image itself, `style` goes to the wrapping view */
+  imageStyle?: IStyleProp<IImageStyle>;
+  /** Goes to the wrapping view, as `style` does */
+  className?: string;
+};
+
+type IClassKey = 'className' | 'class';
+const CLASS_KEYS: ReadonlySet<string> = new Set<IClassKey>(['className', 'class']);
+
+function isClassEntry([key]: [string, unknown]): boolean {
+  return CLASS_KEYS.has(key);
+}
+
+const ABSOLUTE_FILL = {
+  position: 'absolute',
+  left: 0,
+  right: 0,
+  top: 0,
+  bottom: 0,
+} as const satisfies IImageStyle;
+
+// The background image has no handle, so nobody asks it for a host node
+const backgroundImage = createImageView(() => null);
+
+/** A view with an image filling it, the children of the app go after this descriptor */
+export function renderImageBackground(props: IImageBackgroundProps): IDescriptor {
+  const { style, imageStyle, ...rest } = props;
+  const entries = Object.entries(rest);
+  const image = backgroundImage.render({
+    ...Object.fromEntries(entries.filter(entry => !isClassEntry(entry))),
+    style: [ABSOLUTE_FILL, imageStyle],
+  });
+  const viewClass = Object.fromEntries(entries.filter(isClassEntry));
+  return el('view', { style, ...viewClass }, image ? [image] : []);
+}

package/src/core/image-loader.ts

@@ -0,0 +1,65 @@
+import type { IImageLoadOptions, IImageSource } from './types';
+
+export type IImageLoaderConfig<TImage extends { release(): void }> = {
+  load(source: IImageSource | string | number, options: IImageLoadOptions): Promise<TImage>;
+  /** Called with each image that finished loading */
+  onImage(image: TImage): void;
+  /** Read at the time of a failure, so the latest callback wins */
+  getOptions(): IImageLoadOptions;
+};
+
+export type IImageLoader = {
+  /** Starts a load and drops the result of the one before */
+  load(source: IImageSource | string | number): void;
+  /** Drops a load in flight and releases the image loaded last */
+  cancel(): void;
+};
+
+/** What a `useImage` hook drives with its own lifecycle */
+export function createImageLoader<TImage extends { release(): void }>(
+  config: IImageLoaderConfig<TImage>,
+): IImageLoader {
+  let token = 0;
+  let loaded: TImage | null = null;
+
+  function release(): void {
+    loaded?.release();
+    loaded = null;
+  }
+
+  function fail(source: IImageSource | string | number, error: unknown, retry: () => void): void {
+    const { onError } = config.getOptions();
+    if (onError) {
+      onError(error instanceof Error ? error : new Error(String(error)), retry);
+      return;
+    }
+    console.error(
+      `Loading an image from '${JSON.stringify(source)}' failed, use 'onError' to handle errors`,
+    );
+    console.error(error);
+  }
+
+  function load(source: IImageSource | string | number): void {
+    release();
+    token += 1;
+    const mine = token;
+    config
+      .load(source, config.getOptions())
+      .then(image => {
+        if (mine !== token) return;
+        loaded = image;
+        config.onImage(image);
+      })
+      .catch((error: unknown) => {
+        if (mine === token) fail(source, error, () => load(source));
+      });
+  }
+
+  return {
+    load,
+    cancel: () => {
+      token += 1;
+      release();
+    },
+  };
+}

package/src/core/image-ref-loader.ts

@@ -0,0 +1,16 @@
+import { loadImageAsync } from './image-api';
+import { createImageLoader } from './image-loader';
+import type { IImageLoader } from './image-loader';
+import type { IImageLoadOptions, ImageRef } from './types';
+
+/** The loader every `useImage` hook drives, `getOptions` is read at each load and failure */
+export function createImageRefLoader(
+  onImage: (image: ImageRef) => void,
+  getOptions: () => IImageLoadOptions,
+): IImageLoader {
+  return createImageLoader<ImageRef>({
+    load: loadImageAsync,
+    onImage,
+    getOptions,
+  });
+}

package/src/core/image-view-events.ts

@@ -0,0 +1,41 @@
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import type {
+  IImageErrorEventData,
+  IImageLoadEventData,
+  IImageProgressEventData,
+  IImageViewProps,
+} from './types';
+
+function field(value: unknown, key: string): unknown {
+  return Reflect.get(Object(value), key);
+}
+
+function isLoad(value: unknown): value is IImageLoadEventData {
+  return typeof field(value, 'cacheType') === 'string' && typeof field(value, 'source') === 'object';
+}
+
+function isProgress(value: unknown): value is IImageProgressEventData {
+  return typeof field(value, 'loaded') === 'number' && typeof field(value, 'total') === 'number';
+}
+
+function isError(value: unknown): value is IImageErrorEventData {
+  return typeof field(value, 'error') === 'string';
+}
+
+/** The native payload sits in `nativeEvent`, callbacks get it as the event itself */
+export function toImageEvents(props: IImageViewProps) {
+  return {
+    onLoadStart: () => props.onLoadStart?.(),
+    onLoad: (event: ISymbioteEvent) => {
+      if (isLoad(event.nativeEvent)) props.onLoad?.(event.nativeEvent);
+      props.onLoadEnd?.();
+    },
+    onProgress: (event: ISymbioteEvent) => {
+      if (isProgress(event.nativeEvent)) props.onProgress?.(event.nativeEvent);
+    },
+    onError: (event: ISymbioteEvent) => {
+      if (isError(event.nativeEvent)) props.onError?.(event.nativeEvent);
+      props.onLoadEnd?.();
+    },
+  };
+}

package/src/core/image-view.ts

@@ -0,0 +1,156 @@
+import { requireNativeModule, requireNativeViewManager } from 'expo-modules-core';
+import { el } from '@symbiote-native/components';
+import type { IDescriptor } from '@symbiote-native/components';
+import {
+  defineExpoNativeView,
+  defineExpoViewMethods,
+  getNativeTag,
+  isDevBuild,
+  styleOfProps,
+} from '@symbiote-native/engine';
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import { IMAGE_MODULE_NAME, SF_SYMBOL_PREFIX } from './constants';
+import { toImageEvents } from './image-view-events';
+import {
+  nativeColorProps,
+  platformStyle,
+  splitImageStyle,
+  toNativeColor,
+} from './native-style';
+import type { IImageStyleParts } from './native-style';
+import {
+  resolveContentFit,
+  resolveContentPosition,
+  resolveSfEffect,
+  resolveTransition,
+  warnOnce,
+} from './props';
+import { resolveSources } from './sources';
+import type { IImageViewHandle, IImageViewProps } from './types';
+
+// Registered on render: a barrel side effect is lost in a release build
+const imageView = defineExpoNativeView(requireNativeViewManager, IMAGE_MODULE_NAME);
+
+const callViewFunction = defineExpoViewMethods(requireNativeModule, IMAGE_MODULE_NAME);
+
+export const imageViewName = imageView.name;
+
+export const ensureImageViewRegistered = imageView.ensureRegistered;
+
+export type IImageView = {
+  handle: IImageViewHandle;
+  /** `null` means the view cannot register and the caller renders nothing */
+  render(props: IImageViewProps): IDescriptor | null;
+};
+
+type IGetNode = () => ISymbioteNode | null | undefined;
+
+// Props the view reads itself and native has no use for
+const OWN_PROPS = [
+  'style',
+  'source',
+  'placeholder',
+  'contentFit',
+  'contentPosition',
+  'transition',
+  'fadeDuration',
+  'resizeMode',
+  'defaultSource',
+  'loadingIndicatorSource',
+  'sfEffect',
+  'alt',
+] as const satisfies readonly (keyof IImageViewProps)[];
+
+function hasSfSymbol(sources: ReturnType<typeof resolveSources>): boolean {
+  return (
+    Array.isArray(sources) &&
+    sources.some(source => source.uri?.startsWith(`${SF_SYMBOL_PREFIX}/`))
+  );
+}
+
+function withoutOwnProps(props: IImageViewProps): Record<string, unknown> {
+  const own: readonly string[] = OWN_PROPS;
+  return Object.fromEntries(Object.entries(props).filter(([key]) => !own.includes(key)));
+}
+
+function placeholderOf(props: IImageViewProps) {
+  const { defaultSource, loadingIndicatorSource } = props;
+  if (defaultSource || loadingIndicatorSource) {
+    warnOnce('`defaultSource` and `loadingIndicatorSource` props are deprecated, use `placeholder`');
+  }
+  return resolveSources(props.placeholder ?? defaultSource ?? loadingIndicatorSource);
+}
+
+// For an SF Symbol `fontSize` sizes both the symbol and its container
+function symbolProps(parts: IImageStyleParts, isSfSymbol: boolean) {
+  if (!isSfSymbol) return { symbolWeight: null, symbolSize: null };
+  const { fontWeight, fontSize } = parts;
+  return {
+    symbolWeight: fontWeight === undefined ? null : String(fontWeight),
+    symbolSize: fontSize || null,
+  };
+}
+
+function sizedStyle(parts: IImageStyleParts, isSfSymbol: boolean) {
+  const { fontSize, rest } = parts;
+  return isSfSymbol && fontSize ? { width: fontSize, height: fontSize, ...rest } : rest;
+}
+
+function nativeProps(props: IImageViewProps): Record<string, unknown> {
+  const parts = splitImageStyle(styleOfProps(props));
+  const source = resolveSources(props.source);
+  const isSfSymbol = hasSfSymbol(source);
+  const sized = sizedStyle(parts, isSfSymbol);
+  const style = platformStyle(sized);
+  const symbolColor = isSfSymbol ? parts.color : undefined;
+  return {
+    ...withoutOwnProps(props),
+    ...style,
+    accessibilityLabel: props.accessibilityLabel ?? props.alt,
+    style,
+    source,
+    placeholder: placeholderOf(props),
+    contentFit: resolveContentFit(
+      props.contentFit,
+      props.resizeMode ?? parts.resizeMode,
+      isSfSymbol,
+    ),
+    contentPosition: resolveContentPosition(props.contentPosition),
+    transition: resolveTransition(props.transition, props.fadeDuration),
+    sfEffect: resolveSfEffect(props.sfEffect),
+    ...symbolProps(parts, isSfSymbol),
+    ...nativeColorProps(sized),
+    tintColor: toNativeColor(props.tintColor || symbolColor || style.tintColor),
+    ...toImageEvents(props),
+  };
+}
+
+function createImageViewHandle(getNode: IGetNode): IImageViewHandle {
+  // Like upstream's `ref.current?.`, a view that has not committed yet answers nothing
+  async function call(method: string): Promise<void> {
+    const node = getNode();
+    if (!node || getNativeTag(node) === undefined) return;
+    await callViewFunction(node, method, []);
+  }
+  return {
+    startAnimating: () => call('startAnimating'),
+    stopAnimating: () => call('stopAnimating'),
+    lockResourceAsync: () => call('lockResourceAsync'),
+    unlockResourceAsync: () => call('unlockResourceAsync'),
+    reloadAsync: () => call('reloadAsync'),
+  };
+}
+
+/** One per mounted view, `getNode` answers the host node once it exists */
+export function createImageView(getNode: IGetNode): IImageView {
+  return {
+    handle: createImageViewHandle(getNode),
+    render: props => {
+      if (!ensureImageViewRegistered()) {
+        if (isDevBuild()) console.warn("'Image' is not available.");
+        return null;
+      }
+      return el(imageViewName(), nativeProps(props));
+    },
+  };
+}

package/src/core/index.ts

@@ -0,0 +1,50 @@
+export { IMAGE_MODULE_NAME } from './constants';
+export {
+  clearDiskCache,
+  clearMemoryCache,
+  configureCache,
+  generateBlurhashAsync,
+  generateThumbhashAsync,
+  getCachePathAsync,
+  loadImageAsync,
+  prefetchImages,
+  readFromCacheAsync,
+  writeToCacheAsync,
+} from './image-api';
+export { renderImageBackground } from './image-background';
+export type { IImageBackgroundProps } from './image-background';
+export { createImageRefLoader } from './image-ref-loader';
+export { createImageLoader } from './image-loader';
+export type { IImageLoader, IImageLoaderConfig } from './image-loader';
+export {
+  createImageView,
+  ensureImageViewRegistered,
+  imageViewName,
+  type IImageView,
+} from './image-view';
+export { isImageRef, resolveSource, resolveSources } from './sources';
+export type {
+  IImageCacheConfig,
+  IImageContentFit,
+  IImageContentPosition,
+  IImageContentPositionObject,
+  IImageContentPositionString,
+  IImageContentPositionValue,
+  IImageDecodeFormat,
+  IImageErrorEventData,
+  IImageLoadEventData,
+  IImageLoadOptions,
+  IImagePrefetchOptions,
+  IImageProgressEventData,
+  IImageResizeMode,
+  IImageSource,
+  IImageSources,
+  IImageStyle,
+  IImageTransition,
+  IImageViewHandle,
+  IImageViewProps,
+  ISfSymbolEffect,
+  ISfSymbolEffectObject,
+  ISfSymbolEffectType,
+  ImageRef,
+} from './types';

package/src/core/native-module.ts

@@ -0,0 +1,45 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type { EventSubscription } from 'expo-modules-core';
+import { IMAGE_MODULE_NAME } from './constants';
+import type {
+  IImageCacheConfig,
+  IImageLoadOptions,
+  IImagePrefetchOptions,
+  IImageSource,
+  ImageRef,
+} from './types';
+
+export type INativeImageModule = {
+  Image: typeof ImageRef;
+  loadAsync(
+    source: IImageSource,
+    options?: Omit<IImageLoadOptions, 'onError' | 'tintColor'> & {
+      /** What `processColor` answers */
+      tintColor?: unknown;
+    },
+  ): Promise<ImageRef>;
+  prefetch(
+    urls: string[],
+    cachePolicy: IImagePrefetchOptions['cachePolicy'],
+    headers?: Record<string, string>,
+  ): Promise<boolean>;
+  clearMemoryCache(): Promise<boolean>;
+  clearDiskCache(): Promise<boolean>;
+  configureCache(config: IImageCacheConfig): void;
+  getCachePathAsync(cacheKey: string): Promise<string | null>;
+  writeToCacheAsync(source: string | ImageRef, cacheKey: string): Promise<void>;
+  readFromCacheAsync(cacheKey: string): Promise<ImageRef | null>;
+  generateBlurhashAsync(
+    source: string | ImageRef,
+    numberOfComponents: [number, number] | { width: number; height: number },
+  ): Promise<string | null>;
+  generateThumbhashAsync(source: string | ImageRef): Promise<string>;
+  addListener(
+    eventName: string,
+    listener: (event: { url: string; width: number; height: number }) => void,
+  ): EventSubscription;
+};
+
+export const expoImage = requireNativeModule<INativeImageModule>(
+  IMAGE_MODULE_NAME,
+);