@symbiote-native/image 0.0.0-stage → 0.1.0

package/src/core/image-view.ts

@@ -0,0 +1,173 @@
+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,44 @@
+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);

package/src/core/native-style.ts

@@ -0,0 +1,96 @@
+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,123 @@
+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,75 @@
+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);
+}