react-native-photo-video-editor 0.1.0

package/package.json

@@ -0,0 +1,154 @@
+{
+  "name": "react-native-photo-video-editor",
+  "version": "0.1.0",
+  "description": "Native photo and video editor for React Native, powered by Kotlin and Swift.",
+  "main": "./lib/module/index.js",
+  "module": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "exports": {
+    ".": {
+      "react-native-photo-video-editor-source": "./src/index.ts",
+      "types": "./lib/typescript/src/index.d.ts",
+      "default": "./lib/module/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "lib",
+    "docs",
+    "README.md",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "android",
+    "ios",
+    "cpp",
+    "*.podspec",
+    "react-native.config.js",
+    "!ios/build",
+    "!android/build",
+    "!android/gradle",
+    "!android/gradlew",
+    "!android/gradlew.bat",
+    "!android/local.properties",
+    "!android/src/test",
+    "!ios/Tests",
+    "!**/__tests__",
+    "!**/__fixtures__",
+    "!**/__mocks__",
+    "!**/.*"
+  ],
+  "scripts": {
+    "example": "yarn workspace react-native-photo-video-editor-example",
+    "example:start": "yarn example start",
+    "example:android": "yarn example android",
+    "example:ios": "yarn example ios",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "prepare": "bob build",
+    "typecheck": "tsc",
+    "lint": "eslint \"**/*.{js,ts,tsx}\"",
+    "format": "prettier --write \"**/*.{js,json,md,ts,tsx,yml}\"",
+    "test": "jest",
+    "codegen": "yarn example react-native codegen"
+  },
+  "keywords": [
+    "react-native",
+    "photo",
+    "video",
+    "editor",
+    "android",
+    "ios",
+    "kotlin",
+    "swift",
+    "turbo-module"
+  ],
+  "author": "Babur171",
+  "license": "MIT",
+  "homepage": "https://github.com/Babur171/react-native-photo-video-editor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Babur171/react-native-photo-video-editor.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Babur171/react-native-photo-video-editor/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/"
+  },
+  "devDependencies": {
+    "@eslint/compat": "^2.1.0",
+    "@eslint/eslintrc": "^3.3.5",
+    "@eslint/js": "^10.0.1",
+    "@react-native/babel-preset": "0.85.0",
+    "@react-native/eslint-config": "0.85.0",
+    "@react-native/jest-preset": "0.85.0",
+    "@types/jest": "^29.5.14",
+    "@types/react": "^19.2.0",
+    "del-cli": "^7.0.0",
+    "eslint": "^9.39.4",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-ft-flow": "^3.0.11",
+    "eslint-plugin-prettier": "^5.5.6",
+    "jest": "^29.7.0",
+    "prettier": "^3.8.3",
+    "react": "19.2.3",
+    "react-native": "0.85.0",
+    "react-native-builder-bob": "^0.43.0",
+    "react-test-renderer": "19.2.3",
+    "turbo": "^2.9.16",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*"
+  },
+  "workspaces": [
+    "example"
+  ],
+  "packageManager": "yarn@4.11.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      [
+        "module",
+        {
+          "esm": true
+        }
+      ],
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "codegenConfig": {
+    "name": "PhotoVideoEditorSpec",
+    "type": "modules",
+    "jsSrcsDir": "src",
+    "android": {
+      "javaPackageName": "com.photovideoeditor"
+    }
+  },
+  "prettier": {
+    "quoteProps": "consistent",
+    "singleQuote": true,
+    "tabWidth": 2,
+    "trailingComma": "es5",
+    "useTabs": false
+  },
+  "create-react-native-library": {
+    "type": "turbo-module",
+    "languages": "kotlin-objc",
+    "tools": [
+      "eslint",
+      "jest",
+      "lefthook",
+      "release-it"
+    ],
+    "version": "0.63.0"
+  }
+}

package/src/NativePhotoVideoEditor.ts

@@ -0,0 +1,12 @@
+import type { CodegenTypes, TurboModule } from 'react-native';
+import { TurboModuleRegistry } from 'react-native';
+
+export interface Spec extends TurboModule {
+  openEditor(request: string): Promise<string>;
+  cancelExport(jobId: string | null): Promise<boolean>;
+  isAvailable(): boolean;
+  readonly onExportProgress: CodegenTypes.EventEmitter<string>;
+  readonly onEditorEvent: CodegenTypes.EventEmitter<string>;
+}
+
+export default TurboModuleRegistry.getEnforcing<Spec>('PhotoVideoEditor');

package/src/errors.ts

@@ -0,0 +1,78 @@
+/** Stable error codes exposed across Android and iOS. */
+export type PhotoVideoEditorErrorCode =
+  | 'E_INVALID_OPTIONS'
+  | 'E_INVALID_URI'
+  | 'E_UNSUPPORTED_MEDIA_TYPE'
+  | 'E_SOURCE_NOT_FOUND'
+  | 'E_SOURCE_UNREADABLE'
+  | 'E_UNSUPPORTED_FORMAT'
+  | 'E_EDITOR_ALREADY_OPEN'
+  | 'E_EDITOR_UNAVAILABLE'
+  | 'E_EDITOR_CANCELLED'
+  | 'E_EXPORT_FAILED'
+  | 'E_EXPORT_IN_PROGRESS'
+  | 'E_EXPORT_CANCELLED'
+  | 'E_INSUFFICIENT_STORAGE'
+  | 'E_OUT_OF_MEMORY'
+  | 'E_CODEC_UNAVAILABLE'
+  | 'E_PROJECT_INVALID'
+  | 'E_PROJECT_VERSION_UNSUPPORTED'
+  | 'E_PERMISSION_DENIED'
+  | 'E_INTERNAL';
+
+const codes = new Set<PhotoVideoEditorErrorCode>([
+  'E_INVALID_OPTIONS',
+  'E_INVALID_URI',
+  'E_UNSUPPORTED_MEDIA_TYPE',
+  'E_SOURCE_NOT_FOUND',
+  'E_SOURCE_UNREADABLE',
+  'E_UNSUPPORTED_FORMAT',
+  'E_EDITOR_ALREADY_OPEN',
+  'E_EDITOR_UNAVAILABLE',
+  'E_EDITOR_CANCELLED',
+  'E_EXPORT_FAILED',
+  'E_EXPORT_IN_PROGRESS',
+  'E_EXPORT_CANCELLED',
+  'E_INSUFFICIENT_STORAGE',
+  'E_OUT_OF_MEMORY',
+  'E_CODEC_UNAVAILABLE',
+  'E_PROJECT_INVALID',
+  'E_PROJECT_VERSION_UNSUPPORTED',
+  'E_PERMISSION_DENIED',
+  'E_INTERNAL',
+]);
+
+/** Error thrown by every public asynchronous operation. */
+export class PhotoVideoEditorError extends Error {
+  /** Stable machine-readable code. */ readonly code: PhotoVideoEditorErrorCode;
+  /** Sanitized original native metadata, when available. */ readonly native?: unknown;
+  constructor(
+    code: PhotoVideoEditorErrorCode,
+    message: string,
+    native?: unknown
+  ) {
+    super(message);
+    this.name = 'PhotoVideoEditorError';
+    this.code = code;
+    this.native = native;
+  }
+}
+
+/** Converts unknown native rejection values to the stable public error class. */
+export function normalizeEditorError(error: unknown): PhotoVideoEditorError {
+  if (error instanceof PhotoVideoEditorError) return error;
+  const value =
+    typeof error === 'object' && error !== null
+      ? (error as { code?: unknown; message?: unknown })
+      : {};
+  const code =
+    typeof value.code === 'string' &&
+    codes.has(value.code as PhotoVideoEditorErrorCode)
+      ? (value.code as PhotoVideoEditorErrorCode)
+      : 'E_INTERNAL';
+  const message =
+    typeof value.message === 'string' && value.message.trim()
+      ? value.message
+      : 'The native editor failed unexpectedly.';
+  return new PhotoVideoEditorError(code, message, { code: value.code });
+}

package/src/events.ts

@@ -0,0 +1,43 @@
+import NativePhotoVideoEditor from './NativePhotoVideoEditor';
+import { PhotoVideoEditorError } from './errors';
+import type {
+  EditorEvent,
+  EditorEventListener,
+  EditorSubscription,
+  ExportProgressEvent,
+} from './types';
+
+export function addEditorEventListener(
+  listener: EditorEventListener
+): EditorSubscription {
+  if (typeof listener !== 'function')
+    throw new PhotoVideoEditorError(
+      'E_INVALID_OPTIONS',
+      'Editor listener must be a function.'
+    );
+  return NativePhotoVideoEditor.onEditorEvent((payload) => {
+    try {
+      listener(JSON.parse(payload) as EditorEvent);
+    } catch {
+      /* malformed native event */
+    }
+  });
+}
+
+/** Subscribes to real native export updates. Milestone one emits none. */
+export function addExportProgressListener(
+  listener: (event: ExportProgressEvent) => void
+): EditorSubscription {
+  if (typeof listener !== 'function')
+    throw new PhotoVideoEditorError(
+      'E_INVALID_OPTIONS',
+      'Progress listener must be a function.'
+    );
+  return NativePhotoVideoEditor.onExportProgress((payload) => {
+    try {
+      listener(JSON.parse(payload) as ExportProgressEvent);
+    } catch {
+      /* Ignore malformed native events. */
+    }
+  });
+}

package/src/index.ts

@@ -0,0 +1,123 @@
+import NativePhotoVideoEditor from './NativePhotoVideoEditor';
+import { PhotoVideoEditorError, normalizeEditorError } from './errors';
+import type {
+  EditorOptions,
+  EditorResult,
+  ExportQuality,
+  ImageExportFormat,
+  MediaType,
+  PhotoEditorOptions,
+  VideoExportFormat,
+  VideoEditorOptions,
+} from './types';
+
+export { addEditorEventListener, addExportProgressListener } from './events';
+export { PhotoVideoEditorError } from './errors';
+export type * from './types';
+export { EDITOR_PROJECT_SCHEMA_VERSION } from './project';
+export type { EditorProject } from './project';
+
+const mediaTypes = new Set<MediaType>(['photo', 'video']);
+const qualities = new Set<ExportQuality>(['low', 'medium', 'high', 'original']);
+const imageFormats = new Set<ImageExportFormat>(['jpeg', 'png', 'webp']);
+const videoFormats = new Set<VideoExportFormat>(['mp4', 'mov']);
+const defaultFeatures = {
+  crop: true,
+  rotate: true,
+  trim: true,
+  filters: true,
+  text: true,
+  stickers: true,
+  overlays: true,
+  onlineStickers: true,
+};
+
+function invalid(message: string): never {
+  throw new PhotoVideoEditorError('E_INVALID_OPTIONS', message);
+}
+function positive(value: number | undefined, name: string): void {
+  if (value !== undefined && (!Number.isFinite(value) || value <= 0))
+    invalid(`${name} must be a positive number.`);
+}
+function normalizeOptions(input: EditorOptions): EditorOptions {
+  if (
+    !input ||
+    typeof input !== 'object' ||
+    !input.source ||
+    typeof input.source !== 'object'
+  )
+    invalid('options.source is required.');
+  if (typeof input.source.uri !== 'string' || !input.source.uri.trim())
+    throw new PhotoVideoEditorError(
+      'E_INVALID_URI',
+      'source.uri must be a non-empty string.'
+    );
+  if (!mediaTypes.has(input.source.type))
+    throw new PhotoVideoEditorError(
+      'E_UNSUPPORTED_MEDIA_TYPE',
+      'source.type must be photo or video.'
+    );
+  const output = input.export ?? {};
+  if (output.quality !== undefined && !qualities.has(output.quality))
+    invalid('export.quality is unsupported.');
+  if (output.imageFormat !== undefined && !imageFormats.has(output.imageFormat))
+    invalid('export.imageFormat is unsupported.');
+  if (output.videoFormat !== undefined && !videoFormats.has(output.videoFormat))
+    invalid('export.videoFormat is unsupported.');
+  positive(output.maxWidth, 'export.maxWidth');
+  positive(output.maxHeight, 'export.maxHeight');
+  positive(output.videoBitrate, 'export.videoBitrate');
+  positive(output.frameRate, 'export.frameRate');
+  if (input.source.type === 'photo' && output.videoFormat !== undefined)
+    invalid('videoFormat is only valid for video sources.');
+  if (input.source.type === 'video' && output.imageFormat !== undefined)
+    invalid('imageFormat is only valid for photo sources.');
+  const features = { ...defaultFeatures, ...input.features };
+  if (input.source.type === 'photo') {
+    features.trim = false;
+  }
+  return {
+    ...input,
+    source: { ...input.source, uri: input.source.uri.trim() },
+    features,
+    export: { quality: 'high', preserveMetadata: true, ...output },
+    saveToGallery: input.saveToGallery ?? false,
+  };
+}
+
+/** Opens the full-screen native editor selected by source.type. */
+export async function openEditor(
+  options: EditorOptions
+): Promise<EditorResult> {
+  try {
+    return JSON.parse(
+      await NativePhotoVideoEditor.openEditor(
+        JSON.stringify(normalizeOptions(options))
+      )
+    ) as EditorResult;
+  } catch (error) {
+    throw normalizeEditorError(error);
+  }
+}
+export function openPhotoEditor(
+  options: PhotoEditorOptions
+): Promise<EditorResult> {
+  return openEditor(options);
+}
+export function openVideoEditor(
+  options: VideoEditorOptions
+): Promise<EditorResult> {
+  return openEditor(options);
+}
+/** Requests cancellation. Returns false in milestone one because no export job exists. */
+export async function cancelExport(jobId?: string): Promise<boolean> {
+  try {
+    return await NativePhotoVideoEditor.cancelExport(jobId ?? null);
+  } catch (error) {
+    throw normalizeEditorError(error);
+  }
+}
+/** Returns whether the linked native module is available on this device. */
+export function isAvailable(): boolean {
+  return NativePhotoVideoEditor.isAvailable();
+}

package/src/project.ts

@@ -0,0 +1,17 @@
+import type { EditorSource, ExportOptions } from './types';
+export const EDITOR_PROJECT_SCHEMA_VERSION = 1 as const;
+export interface EditorProject {
+  schemaVersion: typeof EDITOR_PROJECT_SCHEMA_VERSION;
+  id: string;
+  source: EditorSource;
+  canvas: {
+    width: number;
+    height: number;
+    backgroundColor: string;
+    durationMs?: number;
+  };
+  tracks: Array<{ id: string; items: string[] }>;
+  adjustments: Record<string, number>;
+  exportDefaults: ExportOptions;
+  metadata: { createdAt: string; updatedAt: string };
+}

package/src/types.ts

@@ -0,0 +1,121 @@
+/** Kind of local media supplied to the editor. */
+export type MediaType = 'photo' | 'video';
+/** Requested export quality preset. */
+export type ExportQuality = 'low' | 'medium' | 'high' | 'original';
+/** Supported photo output container. */
+export type ImageExportFormat = 'jpeg' | 'png' | 'webp';
+/** Supported video output container. */
+export type VideoExportFormat = 'mp4' | 'mov';
+/** Lifecycle state reported by future export jobs. */
+export type EditorStatus =
+  | 'idle'
+  | 'preparing'
+  | 'editing'
+  | 'exporting'
+  | 'completed'
+  | 'cancelled'
+  | 'failed';
+
+/** A local file or platform content URI. Remote URLs are not supported. */
+export interface EditorSource {
+  /** Local file/content URI. */ uri: string;
+  /** Media kind. */ type: MediaType;
+  /** Optional MIME type hint. */ mimeType?: string;
+  /** Optional display filename. */ fileName?: string;
+}
+/** Feature switches. Video-only switches are normalized off for photos. */
+export interface EditorFeatures {
+  /** Enables cropping. */ crop?: boolean;
+  /** Enables rotation. */ rotate?: boolean;
+  /** Enables video trimming. */ trim?: boolean;
+  /** Enables filters. */ filters?: boolean;
+  /** Enables text overlays. */ text?: boolean;
+  /** Enables stickers (built-in, consumer-supplied, and user-uploaded). */ stickers?: boolean;
+  /** Enables the user-uploaded image overlay tool. */ overlays?: boolean;
+  /** Enables browsing/downloading free stickers from the internet (OpenMoji). Disable to prevent any network calls. */ onlineStickers?: boolean;
+}
+/** Future native editor appearance options. */
+export interface EditorTheme {
+  /** CSS-style primary color. */ primaryColor?: string;
+  /** Editor background color. */ backgroundColor?: string;
+  /** Toolbar color. */ toolbarColor?: string;
+  /** Foreground text color. */ textColor?: string;
+  /** Status bar content style. */ statusBarStyle?: 'light' | 'dark';
+}
+/** Export preferences. The milestone-one placeholder does not export media. */
+export interface ExportOptions {
+  /** Quality preset. */ quality?: ExportQuality;
+  /** Photo output format; photo sources only. */ imageFormat?: ImageExportFormat;
+  /** Video output format; video sources only. */ videoFormat?: VideoExportFormat;
+  /** Maximum output width in pixels; must be positive. */ maxWidth?: number;
+  /** Maximum output height in pixels; must be positive. */ maxHeight?: number;
+  /** Video bitrate in bits per second; must be positive. */ videoBitrate?: number;
+  /** Video frame rate in frames per second; must be positive. */ frameRate?: number;
+  /** Whether future exports should retain safe metadata. */ preserveMetadata?: boolean;
+}
+/** A consumer-provided font for text layers. Licensing is the consumer's responsibility. */
+export interface FontAsset {
+  /** Font family name used to select this font from a text layer. */ family: string;
+  /** Local file URI of the font file (e.g. .ttf/.otf). */ uri: string;
+}
+/** A consumer-provided sticker image, selectable from the Stickers tool. */
+export interface StickerAsset {
+  /** Stable identifier, echoed back on layers created from this asset. */ id: string;
+  /** Local file/content URI of the sticker image. */ uri: string;
+}
+/** Options accepted by {@link openEditor}. */
+export interface EditorOptions {
+  /** Required local input. */ source: EditorSource;
+  /** Enabled tools. */ features?: EditorFeatures;
+  /** Native UI theme. */ theme?: EditorTheme;
+  /** Export preferences. */ export?: ExportOptions;
+  /** Requests saving to the gallery. Currently ignored by the placeholder. */ saveToGallery?: boolean;
+  /** Consumer-provided stickers offered by the Stickers tool, in addition to the small built-in set and end-user uploads. */ stickerAssets?: StickerAsset[];
+  /** Consumer-provided fonts selectable from the Text tool. */ fonts?: FontAsset[];
+}
+export interface PhotoEditorOptions extends Omit<EditorOptions, 'source'> {
+  source: EditorSource & { type: 'photo' };
+}
+export interface VideoEditorOptions extends Omit<EditorOptions, 'source'> {
+  source: EditorSource & { type: 'video' };
+}
+export type EditorEventType =
+  | 'editorOpened'
+  | 'editorReady'
+  | 'selectionChanged'
+  | 'projectChanged'
+  | 'exportStarted'
+  | 'exportProgress'
+  | 'exportCompleted'
+  | 'exportCancelled'
+  | 'editorClosed'
+  | 'error';
+export interface EditorEvent {
+  type: EditorEventType;
+  projectId?: string;
+  jobId?: string;
+  progress?: number;
+  status?: EditorStatus;
+}
+export type EditorEventListener = (event: EditorEvent) => void;
+/** Result from the native editor contract. */
+export interface EditorResult {
+  /** Local output URI. */ uri: string;
+  /** Output media kind. */ type: MediaType;
+  /** MIME type when known. */ mimeType?: string;
+  /** Width in pixels when known. */ width?: number;
+  /** Height in pixels when known. */ height?: number;
+  /** Video duration in milliseconds when known. */ duration?: number;
+  /** File size in bytes when known. */ fileSize?: number;
+  /** True only when editing was cancelled. */ cancelled: boolean;
+}
+/** Export progress. Progress is between 0 and 1. */
+export interface ExportProgressEvent {
+  /** Export job identifier. */ jobId: string;
+  /** Fraction complete, from 0 to 1. */ progress: number;
+  /** Current lifecycle state. */ status: EditorStatus;
+}
+/** Removable event subscription. */
+export interface EditorSubscription {
+  /** Stops future callbacks; safe to call repeatedly. */ remove(): void;
+}