react-native-picture-selector 1.0.0

package/nitrogen/generated/shared/c++/PickerTheme.hpp

@@ -0,0 +1,84 @@
+///
+/// PickerTheme.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/NitroHash.hpp>)
+#include <NitroModules/NitroHash.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+namespace margelo::nitro::margelo::pictureselector {
+
+  /**
+   * An enum which can be represented as a JavaScript union (PickerTheme).
+   */
+  enum class PickerTheme {
+    DEFAULT      SWIFT_NAME(default) = 0,
+    WECHAT      SWIFT_NAME(wechat) = 1,
+    WHITE      SWIFT_NAME(white) = 2,
+    DARK      SWIFT_NAME(dark) = 3,
+  } CLOSED_ENUM;
+
+} // namespace margelo::nitro::margelo::pictureselector
+
+namespace margelo::nitro {
+
+  // C++ PickerTheme <> JS PickerTheme (union)
+  template <>
+  struct JSIConverter<margelo::nitro::margelo::pictureselector::PickerTheme> final {
+    static inline margelo::nitro::margelo::pictureselector::PickerTheme fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("default"): return margelo::nitro::margelo::pictureselector::PickerTheme::DEFAULT;
+        case hashString("wechat"): return margelo::nitro::margelo::pictureselector::PickerTheme::WECHAT;
+        case hashString("white"): return margelo::nitro::margelo::pictureselector::PickerTheme::WHITE;
+        case hashString("dark"): return margelo::nitro::margelo::pictureselector::PickerTheme::DARK;
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum PickerTheme - invalid value!");
+      }
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::margelo::pictureselector::PickerTheme arg) {
+      switch (arg) {
+        case margelo::nitro::margelo::pictureselector::PickerTheme::DEFAULT: return JSIConverter<std::string>::toJSI(runtime, "default");
+        case margelo::nitro::margelo::pictureselector::PickerTheme::WECHAT: return JSIConverter<std::string>::toJSI(runtime, "wechat");
+        case margelo::nitro::margelo::pictureselector::PickerTheme::WHITE: return JSIConverter<std::string>::toJSI(runtime, "white");
+        case margelo::nitro::margelo::pictureselector::PickerTheme::DARK: return JSIConverter<std::string>::toJSI(runtime, "dark");
+        default: [[unlikely]]
+          throw std::invalid_argument("Cannot convert PickerTheme to JS - invalid value: "
+                                    + std::to_string(static_cast<int>(arg)) + "!");
+      }
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isString()) {
+        return false;
+      }
+      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
+      switch (hashString(unionValue.c_str(), unionValue.size())) {
+        case hashString("default"):
+        case hashString("wechat"):
+        case hashString("white"):
+        case hashString("dark"):
+          return true;
+        default:
+          return false;
+      }
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/PictureSelectorOptions.hpp

@@ -0,0 +1,132 @@
+///
+/// PictureSelectorOptions.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `MediaType` to properly resolve imports.
+namespace margelo::nitro::margelo::pictureselector { enum class MediaType; }
+// Forward declaration of `CropOptions` to properly resolve imports.
+namespace margelo::nitro::margelo::pictureselector { struct CropOptions; }
+// Forward declaration of `CompressOptions` to properly resolve imports.
+namespace margelo::nitro::margelo::pictureselector { struct CompressOptions; }
+// Forward declaration of `PickerTheme` to properly resolve imports.
+namespace margelo::nitro::margelo::pictureselector { enum class PickerTheme; }
+
+#include "MediaType.hpp"
+#include <optional>
+#include "CropOptions.hpp"
+#include "CompressOptions.hpp"
+#include "PickerTheme.hpp"
+#include <string>
+#include <vector>
+
+namespace margelo::nitro::margelo::pictureselector {
+
+  /**
+   * A struct which can be represented as a JavaScript object (PictureSelectorOptions).
+   */
+  struct PictureSelectorOptions final {
+  public:
+    std::optional<MediaType> mediaType     SWIFT_PRIVATE;
+    std::optional<double> maxCount     SWIFT_PRIVATE;
+    std::optional<bool> enableCamera     SWIFT_PRIVATE;
+    std::optional<CropOptions> crop     SWIFT_PRIVATE;
+    std::optional<CompressOptions> compress     SWIFT_PRIVATE;
+    std::optional<double> maxVideoDuration     SWIFT_PRIVATE;
+    std::optional<double> minVideoDuration     SWIFT_PRIVATE;
+    std::optional<PickerTheme> theme     SWIFT_PRIVATE;
+    std::optional<std::string> themeColor     SWIFT_PRIVATE;
+    std::optional<std::vector<std::string>> selectedAssets     SWIFT_PRIVATE;
+
+  public:
+    PictureSelectorOptions() = default;
+    explicit PictureSelectorOptions(std::optional<MediaType> mediaType, std::optional<double> maxCount, std::optional<bool> enableCamera, std::optional<CropOptions> crop, std::optional<CompressOptions> compress, std::optional<double> maxVideoDuration, std::optional<double> minVideoDuration, std::optional<PickerTheme> theme, std::optional<std::string> themeColor, std::optional<std::vector<std::string>> selectedAssets): mediaType(mediaType), maxCount(maxCount), enableCamera(enableCamera), crop(crop), compress(compress), maxVideoDuration(maxVideoDuration), minVideoDuration(minVideoDuration), theme(theme), themeColor(themeColor), selectedAssets(selectedAssets) {}
+
+  public:
+    friend bool operator==(const PictureSelectorOptions& lhs, const PictureSelectorOptions& rhs) = default;
+  };
+
+} // namespace margelo::nitro::margelo::pictureselector
+
+namespace margelo::nitro {
+
+  // C++ PictureSelectorOptions <> JS PictureSelectorOptions (object)
+  template <>
+  struct JSIConverter<margelo::nitro::margelo::pictureselector::PictureSelectorOptions> final {
+    static inline margelo::nitro::margelo::pictureselector::PictureSelectorOptions fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::margelo::pictureselector::PictureSelectorOptions(
+        JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::MediaType>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "mediaType"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "maxCount"))),
+        JSIConverter<std::optional<bool>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "enableCamera"))),
+        JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::CropOptions>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "crop"))),
+        JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::CompressOptions>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "compress"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "maxVideoDuration"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "minVideoDuration"))),
+        JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::PickerTheme>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "theme"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "themeColor"))),
+        JSIConverter<std::optional<std::vector<std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "selectedAssets")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::margelo::pictureselector::PictureSelectorOptions& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "mediaType"), JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::MediaType>>::toJSI(runtime, arg.mediaType));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "maxCount"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.maxCount));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "enableCamera"), JSIConverter<std::optional<bool>>::toJSI(runtime, arg.enableCamera));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "crop"), JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::CropOptions>>::toJSI(runtime, arg.crop));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "compress"), JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::CompressOptions>>::toJSI(runtime, arg.compress));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "maxVideoDuration"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.maxVideoDuration));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "minVideoDuration"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.minVideoDuration));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "theme"), JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::PickerTheme>>::toJSI(runtime, arg.theme));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "themeColor"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.themeColor));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "selectedAssets"), JSIConverter<std::optional<std::vector<std::string>>>::toJSI(runtime, arg.selectedAssets));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::MediaType>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "mediaType")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "maxCount")))) return false;
+      if (!JSIConverter<std::optional<bool>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "enableCamera")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::CropOptions>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "crop")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::CompressOptions>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "compress")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "maxVideoDuration")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "minVideoDuration")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::margelo::pictureselector::PickerTheme>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "theme")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "themeColor")))) return false;
+      if (!JSIConverter<std::optional<std::vector<std::string>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "selectedAssets")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "react-native-picture-selector",
+  "version": "1.0.0",
+  "description": "High-performance photo/video picker for React Native using Nitro Modules",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "files": [
+    "src",
+    "lib",
+    "android",
+    "ios",
+    "nitrogen",
+    "nitro.json",
+    "*.podspec"
+  ],
+  "scripts": {
+    "generate": "nitrogen src/specs",
+    "typecheck": "tsc --noEmit",
+    "build": "bob build",
+    "prepack": "bob build"
+  },
+  "keywords": [
+    "react-native",
+    "photo",
+    "video",
+    "picker",
+    "nitro",
+    "ios",
+    "android",
+    "camera",
+    "gallery"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourorg/react-native-picture-selector.git"
+  },
+  "license": "MIT",
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": ">=0.20.0"
+  },
+  "peerDependenciesMeta": {
+    "react-native-nitro-modules": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "nitrogen": "latest",
+    "react-native-builder-bob": "^0.30.0",
+    "react-native-nitro-modules": ">=0.20.0",
+    "typescript": "^5.3.0"
+  },
+  "nitro": {
+    "ios": {
+      "iosModuleName": "NitroPictureSelector"
+    },
+    "android": {
+      "androidNamespace": "com.nitro.pictureselector",
+      "androidCxxLibName": "NitroPictureSelector"
+    }
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      "typescript"
+    ]
+  }
+}

package/src/PictureSelector.ts

@@ -0,0 +1,72 @@
+import { NitroModules } from 'react-native-nitro-modules'
+import type { HybridPictureSelector } from './specs/PictureSelector.nitro'
+import type { MediaAsset, PictureSelectorOptions } from './types'
+import { MediaType, toPickerError } from './types'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Lazy singleton — created once and reused across calls
+// ─────────────────────────────────────────────────────────────────────────────
+
+let _native: HybridPictureSelector | null = null
+
+function getNative(): HybridPictureSelector {
+  if (_native == null) {
+    _native = NitroModules.createHybridObject<HybridPictureSelector>(
+      'PictureSelector'
+    )
+  }
+  return _native
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Default options
+// ─────────────────────────────────────────────────────────────────────────────
+
+const defaultOptions: PictureSelectorOptions = {
+  mediaType: MediaType.IMAGE,
+  maxCount: 1,
+  enableCamera: true,
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Static API
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const PictureSelector = {
+  /**
+   * Open the gallery picker.
+   *
+   * @example
+   * const assets = await PictureSelector.openPicker({ maxCount: 9 })
+   *
+   * @throws PickerError with code CANCELLED when the user dismisses
+   * @throws PickerError with code PERMISSION_DENIED on permission failure
+   */
+  async openPicker(
+    options: PictureSelectorOptions = {}
+  ): Promise<MediaAsset[]> {
+    try {
+      return await getNative().openPicker({ ...defaultOptions, ...options })
+    } catch (err) {
+      throw toPickerError(err)
+    }
+  },
+
+  /**
+   * Open the camera for capture.
+   *
+   * @example
+   * const [asset] = await PictureSelector.openCamera({ mediaType: MediaType.VIDEO })
+   *
+   * @throws PickerError with code CANCELLED when the user dismisses
+   */
+  async openCamera(
+    options: PictureSelectorOptions = {}
+  ): Promise<MediaAsset[]> {
+    try {
+      return await getNative().openCamera({ ...defaultOptions, ...options })
+    } catch (err) {
+      throw toPickerError(err)
+    }
+  },
+}

package/src/index.ts

@@ -0,0 +1,16 @@
+export { PictureSelector } from './PictureSelector'
+export { usePictureSelector } from './usePictureSelector'
+export type {
+  PictureSelectorState,
+  PictureSelectorActions,
+  UsePictureSelectorReturn,
+} from './usePictureSelector'
+export type {
+  MediaAsset,
+  PictureSelectorOptions,
+  CropOptions,
+  CompressOptions,
+  PickerResult,
+  PickerError,
+} from './types'
+export { MediaType, PickerTheme, toPickerError } from './types'

package/src/specs/PictureSelector.nitro.ts

@@ -0,0 +1,121 @@
+import type { HybridObject } from 'react-native-nitro-modules'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Enums
+// ─────────────────────────────────────────────────────────────────────────────
+
+export enum MediaType {
+  IMAGE = 'image',
+  VIDEO = 'video',
+  ALL = 'all',
+}
+
+export enum PickerTheme {
+  DEFAULT = 'default',
+  WECHAT = 'wechat',
+  WHITE = 'white',
+  DARK = 'dark',
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Config sub-structures
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface CropOptions {
+  /** Enable cropping after selection */
+  enabled: boolean
+  /** Allow free-form aspect ratio. Default: false */
+  freeStyle?: boolean
+  /** Circular crop mask. iOS-only. Default: false */
+  circular?: boolean
+  /** Width part of the crop aspect ratio. Default: 1 */
+  ratioX?: number
+  /** Height part of the crop aspect ratio. Default: 1 */
+  ratioY?: number
+}
+
+export interface CompressOptions {
+  /** Enable compression */
+  enabled: boolean
+  /** JPEG quality, 0.0–1.0. Default: 0.8 */
+  quality?: number
+  /** Max output width in pixels. Default: 1920 */
+  maxWidth?: number
+  /** Max output height in pixels. Default: 1920 */
+  maxHeight?: number
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Picker options
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PictureSelectorOptions {
+  /** Media type to display. Default: IMAGE */
+  mediaType?: MediaType
+  /** Maximum number of selectable items. Default: 1 */
+  maxCount?: number
+  /** Show camera button inside the picker. Default: true */
+  enableCamera?: boolean
+  /** Crop configuration. Only applies when maxCount === 1 */
+  crop?: CropOptions
+  /** Compression configuration */
+  compress?: CompressOptions
+  /** Max video duration in seconds */
+  maxVideoDuration?: number
+  /** Min video duration in seconds. Default: 0 */
+  minVideoDuration?: number
+  /** Picker UI theme */
+  theme?: PickerTheme
+  /** Accent color as hex string, e.g. "#007AFF". iOS: themeColor; Android: accent */
+  themeColor?: string
+  /** Pre-selected asset URIs (file:// URIs) */
+  selectedAssets?: string[]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Result structure
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface MediaAsset {
+  /** file:// URI of the final file (compressed or original) */
+  uri: string
+  /** "image" | "video" */
+  type: string
+  /** MIME type, e.g. "image/jpeg", "video/mp4" */
+  mimeType: string
+  /** Width in pixels */
+  width: number
+  /** Height in pixels */
+  height: number
+  /** Duration in milliseconds (0 for images) */
+  duration: number
+  /** Original filename with extension */
+  fileName: string
+  /** File size in bytes */
+  fileSize: number
+  /** file:// URI after crop or edit. Undefined if no edit was applied */
+  editedUri?: string
+  /** iOS: true if user tapped "Original" quality button */
+  isOriginal?: boolean
+  /** Android: album/bucket name the file belongs to */
+  bucketName?: string
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// HybridObject — the main bridge
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface HybridPictureSelector
+  extends HybridObject<{ ios: 'swift'; android: 'kotlin' }> {
+  /**
+   * Open the photo/video gallery picker.
+   * Rejects with message "CANCELLED" when the user dismisses without selection.
+   */
+  openPicker(options: PictureSelectorOptions): Promise<MediaAsset[]>
+
+  /**
+   * Open the device camera for capture.
+   * Rejects with message "CANCELLED" when the user dismisses.
+   */
+  openCamera(options: PictureSelectorOptions): Promise<MediaAsset[]>
+}

package/src/types.ts

@@ -0,0 +1,38 @@
+// Re-export spec types for public consumption
+export type {
+  MediaAsset,
+  PictureSelectorOptions,
+  CropOptions,
+  CompressOptions,
+} from './specs/PictureSelector.nitro'
+
+export { MediaType, PickerTheme } from './specs/PictureSelector.nitro'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Convenience aliases
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type PickerResult = import('./specs/PictureSelector.nitro').MediaAsset[]
+
+/**
+ * Errors thrown by openPicker / openCamera.
+ *
+ * code === 'CANCELLED'         — user dismissed the picker
+ * code === 'PERMISSION_DENIED' — runtime permission not granted
+ * code === 'UNKNOWN'           — any other native error
+ */
+export interface PickerError extends Error {
+  code: 'CANCELLED' | 'PERMISSION_DENIED' | 'UNKNOWN'
+}
+
+/** Normalise a raw native error to a typed PickerError. */
+export function toPickerError(err: unknown): PickerError {
+  const base = err instanceof Error ? err : new Error(String(err))
+  const msg = base.message ?? ''
+
+  let code: PickerError['code'] = 'UNKNOWN'
+  if (msg.includes('CANCELLED')) code = 'CANCELLED'
+  else if (msg.includes('PERMISSION_DENIED')) code = 'PERMISSION_DENIED'
+
+  return Object.assign(base, { code }) as PickerError
+}

package/src/usePictureSelector.ts

@@ -0,0 +1,102 @@
+import { useState, useCallback, useRef } from 'react'
+import { PictureSelector } from './PictureSelector'
+import type { MediaAsset, PictureSelectorOptions, PickerError } from './types'
+import { toPickerError } from './types'
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook state shape
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface PictureSelectorState {
+  assets: MediaAsset[]
+  loading: boolean
+  error: PickerError | null
+}
+
+export interface PictureSelectorActions {
+  /** Open gallery picker */
+  pick: (options?: PictureSelectorOptions) => Promise<MediaAsset[]>
+  /** Open camera */
+  shoot: (options?: PictureSelectorOptions) => Promise<MediaAsset[]>
+  /** Clear selected assets and error state */
+  clear: () => void
+}
+
+export type UsePictureSelectorReturn = PictureSelectorState &
+  PictureSelectorActions
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * React hook that manages picker state.
+ *
+ * @example
+ * const { assets, loading, pick, shoot, clear } = usePictureSelector({ maxCount: 9 })
+ *
+ * <Button onPress={() => pick()} title="Pick Photos" />
+ * {assets.map(a => <Image source={{ uri: a.uri }} />)}
+ */
+export function usePictureSelector(
+  defaultOptions?: PictureSelectorOptions
+): UsePictureSelectorReturn {
+  const [state, setState] = useState<PictureSelectorState>({
+    assets: [],
+    loading: false,
+    error: null,
+  })
+
+  // Stable ref to avoid re-creating callbacks when defaultOptions changes
+  const defaultOptionsRef = useRef(defaultOptions)
+  defaultOptionsRef.current = defaultOptions
+
+  const pick = useCallback(
+    async (options?: PictureSelectorOptions): Promise<MediaAsset[]> => {
+      setState((s) => ({ ...s, loading: true, error: null }))
+      try {
+        const merged = { ...defaultOptionsRef.current, ...options }
+        const results = await PictureSelector.openPicker(merged)
+        setState({ assets: results, loading: false, error: null })
+        return results
+      } catch (err) {
+        const pickerErr = toPickerError(err)
+        // Do not surface CANCELLED as an error — just restore loading state
+        if (pickerErr.code === 'CANCELLED') {
+          setState((s) => ({ ...s, loading: false }))
+          return []
+        }
+        setState((s) => ({ ...s, loading: false, error: pickerErr }))
+        throw pickerErr
+      }
+    },
+    []
+  )
+
+  const shoot = useCallback(
+    async (options?: PictureSelectorOptions): Promise<MediaAsset[]> => {
+      setState((s) => ({ ...s, loading: true, error: null }))
+      try {
+        const merged = { ...defaultOptionsRef.current, ...options }
+        const results = await PictureSelector.openCamera(merged)
+        setState({ assets: results, loading: false, error: null })
+        return results
+      } catch (err) {
+        const pickerErr = toPickerError(err)
+        if (pickerErr.code === 'CANCELLED') {
+          setState((s) => ({ ...s, loading: false }))
+          return []
+        }
+        setState((s) => ({ ...s, loading: false, error: pickerErr }))
+        throw pickerErr
+      }
+    },
+    []
+  )
+
+  const clear = useCallback(() => {
+    setState({ assets: [], loading: false, error: null })
+  }, [])
+
+  return { ...state, pick, shoot, clear }
+}