@symbiote-native/image 0.0.0-stage → 0.1.0

package/build-ngc/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build-ngc/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":""}

package/native-link.json

@@ -0,0 +1,13 @@
+{
+  "android": {
+    "gradleProjectName": "expo-image",
+    "requiresKsp": true,
+    "modules": [
+      {
+        "importPath": "expo.modules.image.ExpoImageModule",
+        "className": "ExpoImageModule",
+        "nativeName": "ExpoImage"
+      }
+    ]
+  }
+}

package/package.json

@@ -1,6 +1,148 @@
 {
   "name": "@symbiote-native/image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "expo-image wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. The image view with caching, placeholders and SF Symbols, plus the image cache and hash functions.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/image"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/image#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-image",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "image"
+  ],
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./svelte": "./src/svelte/index.ts",
+    "./solid": {
+      "types": "./build/solid/index.d.ts",
+      "default": "./build/solid/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-image": "57.0.5",
+    "expo-modules-core": "57.0.20",
+    "sf-symbols-typescript": "^2.0.0",
+    "@symbiote-native/components": "3.2.0"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "solid-js": ">=1.9.0",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "^3.3.0",
+    "@symbiote-native/engine": "^1.6.0",
+    "@symbiote-native/react": "^3.3.0",
+    "@symbiote-native/solid": "^3.2.0",
+    "@symbiote-native/svelte": "^3.2.0",
+    "@symbiote-native/vue": "^3.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/solid": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "solid-js": "^1.9.14",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/angular": "3.3.0",
+    "@symbiote-native/engine": "1.6.0",
+    "@symbiote-native/react": "3.3.0",
+    "@symbiote-native/solid": "3.2.0",
+    "@symbiote-native/svelte": "3.2.0",
+    "@symbiote-native/test-utils": "0.4.7",
+    "@symbiote-native/vue": "3.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
 }

package/src/angular/image/index.ts

@@ -0,0 +1,79 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core';
+import { DescriptorOutlet, NativeViewBase } from '@symbiote-native/angular';
+import type { IDescriptor } from '@symbiote-native/components';
+import type { IStyleProp } from '@symbiote-native/engine';
+import { createImageView } from '../../core';
+import type { IImageStyle, IImageViewProps } from '../../core';
+
+// One list is the inputs of the component and the props it hands to the native view
+const IMAGE_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',
+] as const;
+
+// Types the inputs for the template, the decorators that would do it are replaced by `inputs`
+export interface ExpoImage extends Partial<
+  Pick<IImageViewProps, (typeof IMAGE_INPUTS)[number]>
+> {}
+
+/** Angular twin of `expo-image`'s `Image`, `Image` itself is a primitive tag of the adapter */
+@Component({
+  selector: 'ExpoImage',
+  standalone: true,
+  imports: [DescriptorOutlet],
+  inputs: [...IMAGE_INPUTS],
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: `@if (descriptor; as node) {
+    <symbiote-descriptor-outlet [node]="node" />
+  }`,
+})
+export class ExpoImage extends NativeViewBase {
+  // The `style` input of the base, typed with the image keys such as `tintColor`
+  declare style?: IStyleProp<IImageStyle>;
+
+  private readonly view = createImageView(() => this.hostNode());
+
+  // The functions of the view are members of the component, a `@ViewChild` reaches them
+  readonly startAnimating = this.view.handle.startAnimating;
+  readonly stopAnimating = this.view.handle.stopAnimating;
+  readonly lockResourceAsync = this.view.handle.lockResourceAsync;
+  readonly unlockResourceAsync = this.view.handle.unlockResourceAsync;
+  readonly reloadAsync = this.view.handle.reloadAsync;
+
+  protected override readonly propNames = IMAGE_INPUTS;
+
+  protected override renderView(props: object): IDescriptor | null {
+    return this.view.render(props);
+  }
+}

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

@@ -0,0 +1,72 @@
+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,29 @@
+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,77 @@
+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,47 @@
+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,72 @@
+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,47 @@
+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?.();
+    },
+  };
+}