@symbiote-native/image 0.0.0-stage → 0.1.0

package/src/core/types.ts

@@ -0,0 +1,275 @@
+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,16 @@
+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,17 @@
+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,12 @@
+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,9 @@
+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;
+}

package/src/svelte/image-background-props.ts

@@ -0,0 +1,6 @@
+import type { Snippet } from 'svelte';
+import type { IImageBackgroundProps } from '../core';
+
+export type IImageBackgroundSvelteProps = IImageBackgroundProps & {
+  children?: Snippet;
+};

package/src/svelte/image-background.svelte

@@ -0,0 +1,10 @@
+<script lang="ts">
+  import DescriptorHost from '@symbiote-native/svelte/descriptor-host';
+  import { renderImageBackground } from '../core';
+  import type { IImageBackgroundSvelteProps } from './image-background-props';
+
+  const { children, ...rest }: IImageBackgroundSvelteProps = $props();
+  const descriptor = $derived(renderImageBackground({ ...rest }));
+</script>
+
+<DescriptorHost {descriptor} {children} />

package/src/svelte/image.svelte

@@ -0,0 +1,26 @@
+<script lang="ts">
+  // The native view name is mixed-case, which a literal tag would parse as a component reference,
+  // so the tag is dynamic
+  import { hostProps } from '@symbiote-native/svelte/native-view-bridge';
+  import { useNativeViewController } from '@symbiote-native/svelte/runes/use-native-view-controller';
+  import { createImageView } from '../core';
+  import type { IImageViewProps } from '../core';
+
+  const props: IImageViewProps = $props();
+  const view = useNativeViewController(createImageView, () => ({ ...props }));
+
+  // The functions of the view are instance members, `bind:this` reaches them
+  export const startAnimating = view.handle.startAnimating;
+  export const stopAnimating = view.handle.stopAnimating;
+  export const lockResourceAsync = view.handle.lockResourceAsync;
+  export const unlockResourceAsync = view.handle.unlockResourceAsync;
+  export const reloadAsync = view.handle.reloadAsync;
+</script>
+
+{#if view.descriptor}
+  <svelte:element
+    this={view.descriptor.type}
+    {@attach view.attachHost}
+    {@attach hostProps(view.descriptor.props)}
+  />
+{/if}

package/src/svelte/index.ts

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

package/src/svelte/svelte-ambient.d.ts

@@ -0,0 +1,3 @@
+// Pulls in svelte's ambient globals ($state/$effect/...) for this package's tsc program
+// This package has no value import from 'svelte', so a triple-slash reference does it explicitly
+/// <reference types="svelte" />

package/src/svelte/svelte-compile.test-helper.ts

@@ -0,0 +1,6 @@
+// Re-exports the existing harness instead of another copy
+export {
+  createSvelteHarness,
+  loadComponent,
+  type ISvelteHarness,
+} from '../../../sqlite/src/svelte/svelte-compile.test-helper';

package/src/svelte/use-image.svelte.ts

@@ -0,0 +1,38 @@
+import { untrack } from 'svelte';
+import { createImageRefLoader, resolveSource } from '../core';
+import type { IImageLoadOptions, IImageSource, ImageRef } from '../core';
+
+export type IUseImageResult = {
+  readonly current: ImageRef | null;
+};
+
+/**
+ * Svelte twin of `expo-image`'s `useImage`, boxed getter shape of the other hooks
+ *
+ * It loads again when the uri of the source or a value read by `getDependencies` changes
+ */
+export function useImage(
+  getSource: () => IImageSource | string | number,
+  getOptions: () => IImageLoadOptions = () => ({}),
+  getDependencies: () => unknown[] = () => [],
+): IUseImageResult {
+  let image = $state.raw<ImageRef | null>(null);
+  const key = $derived(resolveSource(getSource())?.uri);
+
+  $effect(() => {
+    // Read so the effect tracks them, the source itself is not a trigger
+    void key;
+    getDependencies();
+    const loader = createImageRefLoader(loaded => {
+      image = loaded;
+    }, getOptions);
+    untrack(() => loader.load(getSource()));
+    return loader.cancel;
+  });
+
+  return {
+    get current(): ImageRef | null {
+      return image;
+    },
+  };
+}

package/src/vue/image-background.ts

@@ -0,0 +1,17 @@
+import { defineComponent, type VNode } from '@vue/runtime-core';
+import { descriptorToVue, normalizeVueAttrs } from '@symbiote-native/vue';
+import { renderImageBackground } from '../core';
+
+/** Vue twin of `expo-image`'s `ImageBackground`, the default slot paints over the image */
+export const ImageBackground = defineComponent({
+  name: 'ImageBackground',
+  // Every attribute is a prop of the image or the view, nothing leaks onto the wrapper
+  inheritAttrs: false,
+  setup(_props, { attrs, slots }) {
+    return (): VNode =>
+      descriptorToVue(
+        renderImageBackground(normalizeVueAttrs(attrs)),
+        slots.default?.() ?? [],
+      );
+  },
+});

package/src/vue/image.ts

@@ -0,0 +1,5 @@
+import { defineNativeViewComponent } from '@symbiote-native/vue';
+import { createImageView } from '../core';
+
+/** Vue twin of `expo-image`'s `Image`, `ref` gets the handle of the view */
+export const Image = defineNativeViewComponent('Image', createImageView);

package/src/vue/index.ts

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

package/src/vue/use-image.ts

@@ -0,0 +1,38 @@
+import { shallowRef, toValue, watch } from '@vue/runtime-core';
+import type {
+  MaybeRefOrGetter,
+  ShallowRef,
+  WatchSource,
+} from '@vue/runtime-core';
+import { createImageRefLoader, resolveSource } from '../core';
+import type { IImageLoadOptions, IImageSource, ImageRef } from '../core';
+
+/**
+ * Vue twin of `expo-image`'s `useImage`, `null` until the first image has loaded
+ *
+ * It loads again when the uri of the source or a watched `dependencies` source changes
+ */
+export function useImage(
+  source: MaybeRefOrGetter<IImageSource | string | number>,
+  options: MaybeRefOrGetter<IImageLoadOptions> = {},
+  dependencies: WatchSource[] = [],
+): Readonly<ShallowRef<ImageRef | null>> {
+  const image = shallowRef<ImageRef | null>(null);
+
+  watch(
+    [() => resolveSource(toValue(source))?.uri, ...dependencies],
+    (_next, _previous, onCleanup) => {
+      const loader = createImageRefLoader(
+        loaded => {
+          image.value = loaded;
+        },
+        () => toValue(options),
+      );
+      loader.load(toValue(source));
+      onCleanup(loader.cancel);
+    },
+    { immediate: true },
+  );
+
+  return image;
+}