@symbiote-native/camera 0.0.0-stage → 0.0.0

package/src/core/android-barcode.ts

@@ -0,0 +1,48 @@
+// What Google's code scanner adds to a result, Android only
+
+type IAndroidBarcodeKind<TType extends string> = { type: TType };
+
+export type IAndroidBarcode =
+  | (IAndroidBarcodeKind<'contactInfo'> & {
+      firstName?: string;
+      middleName?: string;
+      lastName?: string;
+      title?: string;
+      organization?: string;
+      email?: string;
+      phone?: string;
+      url?: string;
+      address?: string;
+    })
+  | (IAndroidBarcodeKind<'geoPoint'> & { lat: string; lng: string })
+  | (IAndroidBarcodeKind<'sms'> & { phoneNumber?: string; message?: string })
+  | (IAndroidBarcodeKind<'url'> & { url?: string })
+  | (IAndroidBarcodeKind<'calendarEvent'> & {
+      summary?: string;
+      description?: string;
+      location?: string;
+      start?: string;
+      end?: string;
+    })
+  | (IAndroidBarcodeKind<'driverLicense'> & {
+      firstName?: string;
+      middleName?: string;
+      lastName?: string;
+      licenseNumber?: string;
+      expiryDate?: string;
+      issueDate?: string;
+      addressStreet?: string;
+      addressCity?: string;
+      addressState?: string;
+    })
+  | (IAndroidBarcodeKind<'email'> & {
+      address?: string;
+      subject?: string;
+      body?: string;
+    })
+  | (IAndroidBarcodeKind<'phone'> & { number?: string; phoneNumberType?: string })
+  | (IAndroidBarcodeKind<'wifi'> & {
+      ssid?: string;
+      password?: string;
+      encryptionType?: string;
+    });

package/src/core/camera-api.ts

@@ -0,0 +1,99 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import type { EventSubscription, PermissionResponse } from 'expo-modules-core';
+import { CAMERA_PACKAGE_NAME, MODERN_SCANNER_EVENT } from './constants';
+import { expoCamera } from './native-module';
+import type {
+  ICameraBarcodeScanningResult,
+  ICameraBarcodeType,
+  ICameraScanningOptions,
+  ICameraScanningResult,
+  ICameraVideoCodec,
+} from './types';
+
+/** Whether the device has a camera, the permissions are a separate question */
+export async function isCameraAvailableAsync(): Promise<boolean> {
+  if (!expoCamera.isAvailableAsync) {
+    throw new UnavailabilityError(CAMERA_PACKAGE_NAME, 'isAvailableAsync');
+  }
+  return expoCamera.isAvailableAsync();
+}
+
+/** iOS only */
+export async function getAvailableVideoCodecsAsync(): Promise<
+  ICameraVideoCodec[]
+> {
+  if (!expoCamera.getAvailableVideoCodecsAsync) {
+    throw new UnavailabilityError('Camera', 'getAvailableVideoCodecsAsync');
+  }
+  return expoCamera.getAvailableVideoCodecsAsync();
+}
+
+/** Whether the device has `DataScannerViewController` (iOS 16+) or Google's code scanner */
+export function isModernBarcodeScannerAvailable(): boolean {
+  return expoCamera.isModernBarcodeScannerAvailable;
+}
+
+/** A device without the modern scanner does nothing here */
+export async function launchScanner(
+  options: ICameraScanningOptions = { barcodeTypes: [] },
+): Promise<void> {
+  if (expoCamera.isModernBarcodeScannerAvailable) {
+    await expoCamera.launchScanner(options);
+  }
+}
+
+/** Dismisses the scanner on iOS, on Android it closes itself after a scan */
+export async function dismissScanner(): Promise<void> {
+  if (expoCamera.isModernBarcodeScannerAvailable) {
+    await expoCamera.dismissScanner();
+  }
+}
+
+export function onModernBarcodeScanned(
+  listener: (event: ICameraScanningResult) => void,
+): EventSubscription {
+  return expoCamera.addListener(MODERN_SCANNER_EVENT, listener);
+}
+
+/** Only QR codes are scanned on iOS */
+export async function scanFromURLAsync(
+  url: string,
+  barcodeTypes: ICameraBarcodeType[] = ['qr'],
+): Promise<ICameraBarcodeScanningResult[]> {
+  return expoCamera.scanFromURLAsync(url, barcodeTypes);
+}
+
+async function getCameraPermissionsAsync(): Promise<PermissionResponse> {
+  return expoCamera.getCameraPermissionsAsync();
+}
+
+async function requestCameraPermissionsAsync(): Promise<PermissionResponse> {
+  return expoCamera.requestCameraPermissionsAsync();
+}
+
+async function getMicrophonePermissionsAsync(): Promise<PermissionResponse> {
+  return expoCamera.getMicrophonePermissionsAsync();
+}
+
+async function requestMicrophonePermissionsAsync(): Promise<PermissionResponse> {
+  return expoCamera.requestMicrophonePermissionsAsync();
+}
+
+export const Camera = {
+  getCameraPermissionsAsync,
+  requestCameraPermissionsAsync,
+  getMicrophonePermissionsAsync,
+  requestMicrophonePermissionsAsync,
+  scanFromURLAsync,
+};
+
+// What every adapter's `createPermissionHook` binds, `useCameraPermissions` and its twin
+export const cameraPermissionMethods = {
+  getMethod: getCameraPermissionsAsync,
+  requestMethod: requestCameraPermissionsAsync,
+};
+
+export const microphonePermissionMethods = {
+  getMethod: getMicrophonePermissionsAsync,
+  requestMethod: requestMicrophonePermissionsAsync,
+};

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

@@ -0,0 +1,103 @@
+import type { ISymbioteEvent } from '@symbiote-native/engine';
+import { BARCODE_EVENT_THROTTLE_MS } from './constants';
+import { handlePictureSaved } from './picture-options';
+import type {
+  ICameraAvailableLenses,
+  ICameraBarcodeScanningResult,
+  ICameraCapturedPicture,
+  ICameraMountError,
+  ICameraResponsiveOrientation,
+} from './types';
+
+type IGuard<TPayload> = (value: unknown) => value is TPayload;
+
+function hasField(value: unknown, key: string, kind: string): boolean {
+  return typeof Reflect.get(Object(value), key) === kind;
+}
+
+const isMountError: IGuard<ICameraMountError> = (value): value is ICameraMountError =>
+  hasField(value, 'message', 'string');
+
+const isOrientation: IGuard<ICameraResponsiveOrientation> = (
+  value,
+): value is ICameraResponsiveOrientation =>
+  hasField(value, 'orientation', 'string');
+
+const isLenses: IGuard<ICameraAvailableLenses> = (
+  value,
+): value is ICameraAvailableLenses =>
+  Array.isArray(Reflect.get(Object(value), 'lenses'));
+
+const isScanningResult: IGuard<ICameraBarcodeScanningResult> = (
+  value,
+): value is ICameraBarcodeScanningResult =>
+  hasField(value, 'type', 'string') && hasField(value, 'data', 'string');
+
+function isPictureSaved(
+  value: unknown,
+): value is { data: ICameraCapturedPicture; id: number } {
+  return hasField(value, 'id', 'number') && hasField(value, 'data', 'object');
+}
+
+// Hands the callback the payload inside the native event, and only when it has the expected shape
+function forward<TPayload>(
+  props: object,
+  name: string,
+  isPayload: IGuard<TPayload>,
+) {
+  return (event: ISymbioteEvent): void => {
+    const callback: unknown = Reflect.get(props, name);
+    if (typeof callback === 'function' && isPayload(event.nativeEvent)) {
+      callback(event.nativeEvent);
+    }
+  };
+}
+
+export type ICameraViewEvents = (props: object) => Record<string, unknown>;
+
+/** One per view, the throttle of the barcode events belongs to the view */
+export function createCameraViewEvents(): ICameraViewEvents {
+  const lastScans = new Map<string, { json: string; at: number }>();
+
+  // Equal events of one type inside the window are the same scan seen again
+  const throttledScan =
+    (callback: (result: ICameraBarcodeScanningResult) => void) =>
+    (event: ISymbioteEvent): void => {
+      const result = event.nativeEvent;
+      if (!isScanningResult(result)) return;
+      const json = JSON.stringify(result);
+      const now = Date.now();
+      const last = lastScans.get(result.type);
+      if (last?.json === json && now - last.at < BARCODE_EVENT_THROTTLE_MS) {
+        return;
+      }
+      callback(result);
+      lastScans.set(result.type, { json, at: now });
+    };
+
+  return props => {
+    const onBarcodeScanned: unknown = Reflect.get(props, 'onBarcodeScanned');
+    const onCameraReady: unknown = Reflect.get(props, 'onCameraReady');
+    return {
+      onCameraReady: () => {
+        if (typeof onCameraReady === 'function') onCameraReady();
+      },
+      onMountError: forward(props, 'onMountError', isMountError),
+      onBarcodeScanned:
+        typeof onBarcodeScanned === 'function'
+          ? throttledScan(result => onBarcodeScanned(result))
+          : undefined,
+      onAvailableLensesChanged: forward(props, 'onAvailableLensesChanged', isLenses),
+      onResponsiveOrientationChanged: forward(
+        props,
+        'onResponsiveOrientationChanged',
+        isOrientation,
+      ),
+      onPictureSaved: (event: ISymbioteEvent): void => {
+        if (isPictureSaved(event.nativeEvent)) {
+          handlePictureSaved({ nativeEvent: event.nativeEvent });
+        }
+      },
+    };
+  };
+}

package/src/core/camera-view-handle.ts

@@ -0,0 +1,93 @@
+import { Platform, requireNativeModule } from 'expo-modules-core';
+import { defineExpoViewMethods, getNativeTag } from '@symbiote-native/engine';
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import { CAMERA_MODULE_NAME } from './constants';
+import { expoCamera } from './native-module';
+import type { ICameraPictureRef } from './native-module';
+import { ensurePictureOptions, ensureRecordingOptions } from './picture-options';
+import type {
+  ICameraCapturedPicture,
+  ICameraPictureOptions,
+  ICameraRecordingOptions,
+  ICameraSupportedFeatures,
+} from './types';
+
+export type ICameraViewHandle = {
+  /** Waits for `onCameraReady` first. With `pictureRef` it resolves to a native image reference */
+  takePictureAsync(
+    options: ICameraPictureOptions & { pictureRef: true },
+  ): Promise<ICameraPictureRef | undefined>;
+  takePictureAsync(
+    options?: ICameraPictureOptions,
+  ): Promise<ICameraCapturedPicture | undefined>;
+  /** Resolves when `stopRecording` runs, a limit is reached or the preview stops */
+  recordAsync(
+    options?: ICameraRecordingOptions,
+  ): Promise<{ uri: string } | undefined>;
+  /** Pauses or resumes the recording, iOS 18 and later on iOS */
+  toggleRecordingAsync(): Promise<void>;
+  stopRecording(): void;
+  pausePreview(): Promise<void>;
+  resumePreview(): Promise<void>;
+  getAvailablePictureSizesAsync(): Promise<string[]>;
+  /** Lenses exist on iOS only */
+  getAvailableLensesAsync(): Promise<string[]>;
+  getSupportedFeatures(): ICameraSupportedFeatures;
+  /** The host node of the mounted view, `createCameraTextureAsync` of a GL view takes it */
+  getHostNode(): ISymbioteNode | null;
+};
+
+const callViewFunction = defineExpoViewMethods(
+  requireNativeModule,
+  CAMERA_MODULE_NAME,
+);
+
+export function createCameraViewHandle(
+  getNode: () => ISymbioteNode | null | undefined,
+): ICameraViewHandle {
+  // Like upstream's `ref.current?.`, a view that has not committed yet answers nothing
+  function call<TResult>(
+    method: string,
+    args: readonly unknown[] = [],
+  ): TResult | undefined {
+    const node = getNode();
+    if (!node || getNativeTag(node) === undefined) return undefined;
+    return callViewFunction<TResult>(node, method, args);
+  }
+
+  async function takePictureAsync(
+    options: ICameraPictureOptions & { pictureRef: true },
+  ): Promise<ICameraPictureRef | undefined>;
+  async function takePictureAsync(
+    options?: ICameraPictureOptions,
+  ): Promise<ICameraCapturedPicture | undefined>;
+  async function takePictureAsync(options?: ICameraPictureOptions) {
+    const pictureOptions = ensurePictureOptions(options);
+    // The picture ref is an iOS feature, Android answers a plain picture
+    if (Platform.select({ ios: Boolean(options?.pictureRef), default: false })) {
+      return call<Promise<ICameraPictureRef>>('takePictureRef', [pictureOptions]);
+    }
+    return call<Promise<ICameraCapturedPicture>>('takePicture', [pictureOptions]);
+  }
+
+  return {
+    takePictureAsync,
+    recordAsync: async options =>
+      call<Promise<{ uri: string }>>('record', [ensureRecordingOptions(options)]),
+    toggleRecordingAsync: async () => call<Promise<void>>('toggleRecording'),
+    stopRecording: () => {
+      call('stopRecording');
+    },
+    pausePreview: async () => call<Promise<void>>('pausePreview'),
+    resumePreview: async () => call<Promise<void>>('resumePreview'),
+    getAvailablePictureSizesAsync: async () =>
+      (await call<Promise<string[]>>('getAvailablePictureSizes')) ?? [],
+    getAvailableLensesAsync: async () =>
+      (await call<Promise<string[]>>('getAvailableLenses')) ?? [],
+    getSupportedFeatures: () => ({
+      isModernBarcodeScannerAvailable: expoCamera.isModernBarcodeScannerAvailable,
+      toggleRecordingAsyncAvailable: expoCamera.toggleRecordingAsyncAvailable,
+    }),
+    getHostNode: () => getNode() ?? null,
+  };
+}

package/src/core/camera-view.ts

@@ -0,0 +1,56 @@
+// Ядро `CameraView`: нативный view камеры, чьи функции вызываются через `ViewPrototypes`
+import { requireNativeViewManager } from 'expo-modules-core';
+import { el } from '@symbiote-native/components';
+import type { IDescriptor } from '@symbiote-native/components';
+import { defineExpoNativeView, isDevBuild } from '@symbiote-native/engine';
+import type { ISymbioteNode } from '@symbiote-native/engine';
+import { createCameraViewEvents } from './camera-view-events';
+import { createCameraViewHandle } from './camera-view-handle';
+import type { ICameraViewHandle } from './camera-view-handle';
+import { CAMERA_MODULE_NAME } from './constants';
+import { ensureNativeProps } from './props';
+
+// Регистрация идёт при рендере: побочный эффект барреля теряется в release
+const cameraView = defineExpoNativeView(
+  requireNativeViewManager,
+  CAMERA_MODULE_NAME,
+);
+
+export const cameraViewName = cameraView.name;
+
+export const ensureCameraViewRegistered = cameraView.ensureRegistered;
+
+// What upstream's `defaultProps` gave the class component
+const DEFAULT_VIEW_PROPS = {
+  zoom: 0,
+  facing: 'back',
+  enableTorch: false,
+  mode: 'picture',
+  flash: 'off',
+};
+
+export type ICameraView = {
+  handle: ICameraViewHandle;
+  /** `null` means the view cannot register and the caller renders nothing */
+  render(props: object): IDescriptor | null;
+};
+
+/** One per mounted view, `getNode` answers the host node once it exists */
+export function createCameraView(
+  getNode: () => ISymbioteNode | null | undefined,
+): ICameraView {
+  const toEvents = createCameraViewEvents();
+  return {
+    handle: createCameraViewHandle(getNode),
+    render: props => {
+      if (!ensureCameraViewRegistered()) {
+        if (isDevBuild()) console.warn("'CameraView' is not available.");
+        return null;
+      }
+      return el(cameraViewName(), {
+        ...ensureNativeProps({ ...DEFAULT_VIEW_PROPS, ...props }),
+        ...toEvents(props),
+      });
+    },
+  };
+}

package/src/core/constants.ts

@@ -0,0 +1,11 @@
+// Apart from `native-module`, which resolves the module on import: the view needs the name too
+
+export const CAMERA_MODULE_NAME = 'ExpoCamera';
+
+/** The label upstream puts into its `UnavailabilityError` */
+export const CAMERA_PACKAGE_NAME = 'expo-camera';
+
+/** Equal barcode events of one type inside this window are dropped */
+export const BARCODE_EVENT_THROTTLE_MS = 500;
+
+export const MODERN_SCANNER_EVENT = 'onModernBarcodeScanned';

package/src/core/index.ts

@@ -0,0 +1,57 @@
+export {
+  Camera,
+  cameraPermissionMethods,
+  dismissScanner,
+  getAvailableVideoCodecsAsync,
+  isCameraAvailableAsync,
+  isModernBarcodeScannerAvailable,
+  launchScanner,
+  microphonePermissionMethods,
+  onModernBarcodeScanned,
+  scanFromURLAsync,
+} from './camera-api';
+export {
+  cameraViewName,
+  createCameraView,
+  ensureCameraViewRegistered,
+  type ICameraView,
+} from './camera-view';
+export type { ICameraViewHandle } from './camera-view-handle';
+export { CAMERA_MODULE_NAME } from './constants';
+export type { ICameraPictureRef } from './native-module';
+export { PictureRef } from './picture-ref';
+export type { IAndroidBarcode } from './android-barcode';
+export type {
+  ICameraAvailableLenses,
+  ICameraBarcodeBounds,
+  ICameraBarcodePoint,
+  ICameraBarcodeScanningResult,
+  ICameraBarcodeSettings,
+  ICameraBarcodeType,
+  ICameraCapturedPicture,
+  ICameraFlashMode,
+  ICameraFocusMode,
+  ICameraMode,
+  ICameraMountError,
+  ICameraOrientation,
+  ICameraPhotoResult,
+  ICameraPictureOptions,
+  ICameraRatio,
+  ICameraRecordingOptions,
+  ICameraResponsiveOrientation,
+  ICameraSavePictureOptions,
+  ICameraScanningOptions,
+  ICameraScanningResult,
+  ICameraSupportedFeatures,
+  ICameraType,
+  ICameraVideoCodec,
+  ICameraVideoQuality,
+  ICameraVideoStabilization,
+  ICameraViewProps,
+} from './types';
+export {
+  PermissionStatus,
+  type EventSubscription,
+  type PermissionExpiration,
+  type PermissionResponse,
+} from 'expo-modules-core';

package/src/core/native-module.ts

@@ -0,0 +1,57 @@
+import { requireNativeModule } from 'expo-modules-core';
+import type {
+  EventSubscription,
+  PermissionResponse,
+  SharedRef,
+} from 'expo-modules-core';
+import { CAMERA_MODULE_NAME } from './constants';
+import type {
+  ICameraBarcodeScanningResult,
+  ICameraBarcodeType,
+  ICameraPhotoResult,
+  ICameraSavePictureOptions,
+  ICameraScanningOptions,
+  ICameraScanningResult,
+  ICameraVideoCodec,
+} from './types';
+
+/** A reference to a native instance of an image, other Expo packages accept it as is */
+export type ICameraPictureRef = SharedRef<'image'> & {
+  width: number;
+  height: number;
+  /** Saves the image into the cache directory */
+  savePictureAsync(options?: ICameraSavePictureOptions): Promise<ICameraPhotoResult>;
+};
+
+export type ICameraPictureRefClass = abstract new (
+  ...args: never[]
+) => ICameraPictureRef;
+
+// `Type` and `FlashMode` map the friendly prop values to what the native view takes
+export type ICameraNativeModule = {
+  Picture: ICameraPictureRefClass;
+  readonly isModernBarcodeScannerAvailable: boolean;
+  readonly toggleRecordingAsyncAvailable: boolean;
+  readonly Type: Record<string, string>;
+  readonly FlashMode: Record<string, string>;
+  isAvailableAsync?(): Promise<boolean>;
+  launchScanner(options?: ICameraScanningOptions): Promise<void>;
+  dismissScanner(): Promise<void>;
+  scanFromURLAsync(
+    url: string,
+    barcodeTypes?: ICameraBarcodeType[],
+  ): Promise<ICameraBarcodeScanningResult[]>;
+  getCameraPermissionsAsync(): Promise<PermissionResponse>;
+  requestCameraPermissionsAsync(): Promise<PermissionResponse>;
+  getMicrophonePermissionsAsync(): Promise<PermissionResponse>;
+  requestMicrophonePermissionsAsync(): Promise<PermissionResponse>;
+  getAvailableVideoCodecsAsync?(): Promise<ICameraVideoCodec[]>;
+  addListener(
+    eventName: string,
+    listener: (event: ICameraScanningResult) => void,
+  ): EventSubscription;
+};
+
+export const expoCamera = requireNativeModule<ICameraNativeModule>(
+  CAMERA_MODULE_NAME,
+);

package/src/core/picture-options.ts

@@ -0,0 +1,46 @@
+import type {
+  ICameraCapturedPicture,
+  ICameraPictureOptions,
+  ICameraRecordingOptions,
+} from './types';
+
+const MIRROR_DEPRECATED =
+  'The `mirror` option is deprecated. Please use the `mirror` prop on the `CameraView` instead.';
+
+// The callbacks wait here for the native event that carries their picture
+const pictureSavedCallbacks = new Map<
+  number,
+  (picture: ICameraCapturedPicture) => void
+>();
+let nextPictureId = 1;
+
+export function ensurePictureOptions(
+  options?: ICameraPictureOptions,
+): ICameraPictureOptions {
+  if (!options || typeof options !== 'object') return {};
+  if (options.mirror) console.warn(MIRROR_DEPRECATED);
+  const { onPictureSaved, ...rest } = options;
+  const withQuality = { ...rest, quality: options.quality ?? 1 };
+  if (!onPictureSaved) return withQuality;
+  const id = nextPictureId++;
+  pictureSavedCallbacks.set(id, onPictureSaved);
+  return { ...withQuality, id, fastMode: true };
+}
+
+export function ensureRecordingOptions(
+  options: ICameraRecordingOptions = {},
+): ICameraRecordingOptions {
+  if (options.mirror) console.warn(MIRROR_DEPRECATED);
+  return options;
+}
+
+export function handlePictureSaved({
+  nativeEvent,
+}: {
+  nativeEvent: { data: ICameraCapturedPicture; id: number };
+}): void {
+  const callback = pictureSavedCallbacks.get(nativeEvent.id);
+  if (!callback) return;
+  pictureSavedCallbacks.delete(nativeEvent.id);
+  callback(nativeEvent.data);
+}

package/src/core/picture-ref.ts

@@ -0,0 +1,4 @@
+import { expoCamera } from './native-module';
+
+/** The native image class, `takePictureAsync({ pictureRef: true })` resolves to an instance */
+export const PictureRef = expoCamera.Picture;

package/src/core/props.ts

@@ -0,0 +1,31 @@
+import { expoCamera } from './native-module';
+
+type INativeProps = Record<string, unknown>;
+
+// Values under these keys become native options, the tables come from the native module
+function conversionTableFor(key: string): Record<string, unknown> | undefined {
+  if (key === 'type') return expoCamera.Type;
+  if (key === 'flash') return expoCamera.FlashMode;
+  return undefined;
+}
+
+function convertNativeProps(props: object): INativeProps {
+  return Object.fromEntries(
+    Object.entries(props).map(([key, value]) => {
+      const table = conversionTableFor(key);
+      return [key, typeof value === 'string' && table ? table[value] : value];
+    }),
+  );
+}
+
+/** The props the native view takes, built from the friendly ones of the view */
+export function ensureNativeProps(props: object): INativeProps {
+  const { poster: _poster, ...native } = convertNativeProps(props);
+  return {
+    ...native,
+    barcodeScannerEnabled: Boolean(Reflect.get(props, 'onBarcodeScanned')),
+    flashMode: Reflect.get(props, 'flash') ?? 'off',
+    mute: Reflect.get(props, 'mute') ?? false,
+    autoFocus: Reflect.get(props, 'autofocus') ?? 'off',
+  };
+}