react-native-picture-selector 1.0.0

package/README.md

@@ -0,0 +1,627 @@
+# react-native-picture-selector
+
+High-performance photo and video picker for React Native, built on **[Nitro Modules](https://github.com/mrousavy/nitro)** (JSI, zero bridge overhead).
+
+| Platform | Native library | Min OS |
+|----------|---------------|--------|
+| Android  | [LuckSiege/PictureSelector](https://github.com/LuckSiege/PictureSelector) v3.11.2 | Android 7.0 (API 24) |
+| iOS      | [SilenceLove/HXPhotoPicker](https://github.com/SilenceLove/HXPhotoPicker) v5.0.5  | iOS 13.0 |
+
+---
+
+## Features
+
+- **Photos and videos** — single or multi-selection, mixed media
+- **Camera capture** — photo and video directly from the picker
+- **Cropping** — fixed ratio, free-style, circular (iOS)
+- **Compression** — JPEG quality + max dimensions
+- **Video duration limits** — min / max in seconds
+- **Pre-selected assets** — restore a previous selection
+- **Themes** — WeChat / White / Dark (Android), hex accent color (iOS)
+- **Strict TypeScript** — fully typed API and result objects
+- **Promise-based** — async/await friendly, cancel → rejection
+- **React hook** — `usePictureSelector` manages loading / error state
+
+---
+
+## Installation
+
+```sh
+npm install react-native-picture-selector react-native-nitro-modules
+# or
+yarn add react-native-picture-selector react-native-nitro-modules
+```
+
+### iOS — CocoaPods
+
+```sh
+cd ios && pod install
+```
+
+Add required keys to **`ios/YourApp/Info.plist`**:
+
+```xml
+<key>NSPhotoLibraryUsageDescription</key>
+<string>Used to select photos and videos</string>
+
+<key>NSPhotoLibraryAddUsageDescription</key>
+<string>Used to save photos to your library</string>
+
+<key>NSCameraUsageDescription</key>
+<string>Used to capture photos and videos</string>
+
+<key>NSMicrophoneUsageDescription</key>
+<string>Used to record video with audio</string>
+```
+
+### Android — Gradle
+
+Permissions are declared in the library manifest and merged automatically. If you target **Android 13+ (API 33)** and also support older versions you need no extra steps — the manifest already uses `maxSdkVersion` to apply the right permission per API level.
+
+Add the FileProvider authority to your app's `AndroidManifest.xml` if you override the default:
+
+```xml
+<!-- Only needed if you customise the FileProvider authority -->
+<provider
+  android:name="androidx.core.content.FileProvider"
+  android:authorities="${applicationId}.fileprovider"
+  android:exported="false"
+  android:grantUriPermissions="true">
+  <meta-data
+    android:name="android.support.FILE_PROVIDER_PATHS"
+    android:resource="@xml/file_paths" />
+</provider>
+```
+
+#### Manual package registration (non-autolinking setups)
+
+```kotlin
+// android/app/src/main/java/.../MainApplication.kt
+override fun getPackages() =
+  PackageList(this).packages + NitroPictureSelectorPackage()
+```
+
+---
+
+## Quick start
+
+```tsx
+import { PictureSelector, MediaType } from 'react-native-picture-selector'
+
+const assets = await PictureSelector.openPicker({
+  mediaType: MediaType.IMAGE,
+  maxCount: 1,
+})
+
+console.log(assets[0].uri)   // file:///...
+console.log(assets[0].width) // 1280
+```
+
+---
+
+## API Reference
+
+### `PictureSelector.openPicker(options?)`
+
+Opens the native gallery picker. Returns a `Promise<MediaAsset[]>`.
+
+```ts
+const assets = await PictureSelector.openPicker({
+  mediaType: MediaType.ALL,
+  maxCount: 9,
+  compress: { enabled: true, quality: 0.7 },
+})
+```
+
+Rejects with `PickerError` when the user dismisses without selecting:
+
+```ts
+try {
+  const assets = await PictureSelector.openPicker()
+} catch (e) {
+  if ((e as PickerError).code === 'CANCELLED') {
+    // user tapped back / cancel — not an error
+  }
+}
+```
+
+---
+
+### `PictureSelector.openCamera(options?)`
+
+Opens the device camera for capture. Returns `Promise<MediaAsset[]>` (always one item).
+
+```ts
+const [photo] = await PictureSelector.openCamera({
+  mediaType: MediaType.IMAGE,
+  crop: { enabled: true, ratioX: 1, ratioY: 1 },
+})
+```
+
+---
+
+### `usePictureSelector(defaultOptions?)`
+
+React hook that manages loading state and the selected asset list.
+
+```tsx
+import { usePictureSelector, MediaType } from 'react-native-picture-selector'
+
+function PhotoPicker() {
+  const { assets, loading, error, pick, shoot, clear } = usePictureSelector({
+    mediaType: MediaType.IMAGE,
+    maxCount: 9,
+  })
+
+  return (
+    <>
+      <Button onPress={() => pick()} title="Gallery" disabled={loading} />
+      <Button onPress={() => shoot()} title="Camera" disabled={loading} />
+      <Button onPress={clear} title="Clear" />
+
+      {error && <Text>Error: {error.message}</Text>}
+
+      {assets.map((a, i) => (
+        <Image key={i} source={{ uri: a.uri }} style={{ width: 80, height: 80 }} />
+      ))}
+    </>
+  )
+}
+```
+
+#### Hook state
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `assets` | `MediaAsset[]` | Currently selected assets |
+| `loading` | `boolean` | `true` while the picker is open |
+| `error` | `PickerError \| null` | Last non-cancel error |
+
+#### Hook actions
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `pick` | `(options?) => Promise<MediaAsset[]>` | Open gallery picker |
+| `shoot` | `(options?) => Promise<MediaAsset[]>` | Open camera |
+| `clear` | `() => void` | Reset assets and error |
+
+> **Cancellation** — `CANCELLED` errors are swallowed by the hook. `pick()` and `shoot()` return `[]` on cancel instead of throwing.
+
+---
+
+## Configuration (`PictureSelectorOptions`)
+
+All fields are optional.
+
+### Media type
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `mediaType` | `MediaType` | `IMAGE` | `IMAGE`, `VIDEO`, or `ALL` |
+| `maxCount` | `number` | `1` | Maximum selectable items |
+| `enableCamera` | `boolean` | `true` | Show camera button inside the gallery |
+
+```ts
+import { MediaType } from 'react-native-picture-selector'
+
+// images only
+openPicker({ mediaType: MediaType.IMAGE })
+
+// videos only
+openPicker({ mediaType: MediaType.VIDEO })
+
+// mixed, up to 9
+openPicker({ mediaType: MediaType.ALL, maxCount: 9 })
+```
+
+---
+
+### Cropping (`crop`)
+
+Crop applies only when `maxCount === 1`.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `crop.enabled` | `boolean` | — | Enable crop after selection |
+| `crop.ratioX` | `number` | `1` | Width ratio |
+| `crop.ratioY` | `number` | `1` | Height ratio |
+| `crop.freeStyle` | `boolean` | `false` | Free-form crop (ignores ratio) |
+| `crop.circular` | `boolean` | `false` | Circular crop mask **(iOS only)** |
+
+```ts
+// Square crop
+openPicker({ crop: { enabled: true, ratioX: 1, ratioY: 1 } })
+
+// 16:9 crop
+openPicker({ crop: { enabled: true, ratioX: 16, ratioY: 9 } })
+
+// Free-style
+openPicker({ crop: { enabled: true, freeStyle: true } })
+
+// Circular (iOS)
+openPicker({ crop: { enabled: true, circular: true } })
+```
+
+> Android uses **uCrop**. iOS uses the built-in **HXPhotoPicker editor**.
+
+---
+
+### Compression (`compress`)
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `compress.enabled` | `boolean` | — | Enable compression |
+| `compress.quality` | `number` | `0.8` | JPEG quality `0.0`–`1.0` |
+| `compress.maxWidth` | `number` | `1920` | Max output width (px) |
+| `compress.maxHeight` | `number` | `1920` | Max output height (px) |
+
+```ts
+openPicker({
+  compress: {
+    enabled: true,
+    quality: 0.6,
+    maxWidth: 1280,
+    maxHeight: 1280,
+  },
+})
+```
+
+> Android uses **Luban**. iOS uses **HXPhotoPicker** native compression.
+
+---
+
+### Video limits
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `maxVideoDuration` | `number` | Max video duration in **seconds** |
+| `minVideoDuration` | `number` | Min video duration in **seconds** |
+
+```ts
+openPicker({
+  mediaType: MediaType.VIDEO,
+  maxVideoDuration: 60,
+  minVideoDuration: 3,
+})
+```
+
+---
+
+### Themes
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `theme` | `PickerTheme` | Preset theme: `DEFAULT`, `WECHAT`, `WHITE`, `DARK` (Android) |
+| `themeColor` | `string` | Hex accent color, e.g. `"#007AFF"` (iOS: `themeColor`; Android: accent) |
+
+```ts
+import { PickerTheme } from 'react-native-picture-selector'
+
+// Android WeChat style
+openPicker({ theme: PickerTheme.WECHAT })
+
+// Custom accent color (both platforms)
+openPicker({ themeColor: '#1DB954' })
+```
+
+---
+
+### Pre-selected assets
+
+Pass `file://` URIs of previously selected files to restore the selection state:
+
+```ts
+openPicker({
+  maxCount: 9,
+  selectedAssets: previousAssets.map((a) => a.uri),
+})
+```
+
+---
+
+## Result (`MediaAsset`)
+
+Every item in the returned array has this shape:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `uri` | `string` | `file://` URI of the final file |
+| `type` | `"image" \| "video"` | Media type |
+| `mimeType` | `string` | e.g. `"image/jpeg"`, `"video/mp4"` |
+| `width` | `number` | Width in pixels |
+| `height` | `number` | Height in pixels |
+| `duration` | `number` | Duration in **milliseconds** (0 for images) |
+| `fileName` | `string` | File name with extension |
+| `fileSize` | `number` | Size in bytes |
+| `editedUri?` | `string` | URI after crop/edit (when editing was applied) |
+| `isOriginal?` | `boolean` | iOS: user tapped the Original button |
+| `bucketName?` | `string` | Android: album/folder name |
+
+```ts
+const [asset] = await PictureSelector.openPicker()
+
+console.log(asset.uri)       // "file:///data/user/0/.../image.jpg"
+console.log(asset.type)      // "image"
+console.log(asset.mimeType)  // "image/jpeg"
+console.log(asset.width)     // 4032
+console.log(asset.height)    // 3024
+console.log(asset.fileSize)  // 2457600  (bytes)
+console.log(asset.duration)  // 0        (image)
+console.log(asset.editedUri) // "file:///..." or undefined
+```
+
+---
+
+## Error handling
+
+```ts
+import { toPickerError } from 'react-native-picture-selector'
+import type { PickerError } from 'react-native-picture-selector'
+
+try {
+  const assets = await PictureSelector.openPicker()
+} catch (err) {
+  const e = toPickerError(err)
+
+  switch (e.code) {
+    case 'CANCELLED':
+      // user dismissed — treat as no-op
+      break
+    case 'PERMISSION_DENIED':
+      // show settings prompt
+      break
+    case 'UNKNOWN':
+      // unexpected error
+      console.error(e.message)
+      break
+  }
+}
+```
+
+| Code | When |
+|------|------|
+| `CANCELLED` | User tapped Back / Cancel |
+| `PERMISSION_DENIED` | Runtime permission not granted |
+| `UNKNOWN` | Any other native error |
+
+---
+
+## TypeScript enums
+
+```ts
+import { MediaType, PickerTheme } from 'react-native-picture-selector'
+
+MediaType.IMAGE   // 'image'
+MediaType.VIDEO   // 'video'
+MediaType.ALL     // 'all'
+
+PickerTheme.DEFAULT  // 'default'
+PickerTheme.WECHAT   // 'wechat'   (Android)
+PickerTheme.WHITE    // 'white'    (Android)
+PickerTheme.DARK     // 'dark'     (Android)
+```
+
+---
+
+## Common recipes
+
+### Avatar picker (square crop)
+
+```ts
+const [avatar] = await PictureSelector.openPicker({
+  mediaType: MediaType.IMAGE,
+  maxCount: 1,
+  crop: { enabled: true, ratioX: 1, ratioY: 1 },
+  compress: { enabled: true, quality: 0.85, maxWidth: 512, maxHeight: 512 },
+})
+```
+
+### Multi-photo with compression
+
+```ts
+const photos = await PictureSelector.openPicker({
+  mediaType: MediaType.IMAGE,
+  maxCount: 9,
+  compress: { enabled: true, quality: 0.7, maxWidth: 1920, maxHeight: 1920 },
+})
+```
+
+### Short video clips
+
+```ts
+const [clip] = await PictureSelector.openPicker({
+  mediaType: MediaType.VIDEO,
+  maxCount: 1,
+  minVideoDuration: 1,
+  maxVideoDuration: 30,
+})
+```
+
+### Upload immediately after capture
+
+```ts
+async function captureAndUpload() {
+  const [photo] = await PictureSelector.openCamera({
+    mediaType: MediaType.IMAGE,
+    compress: { enabled: true, quality: 0.8 },
+  })
+
+  const body = new FormData()
+  body.append('file', {
+    uri: photo.uri,
+    type: photo.mimeType,
+    name: photo.fileName,
+  } as any)
+
+  await fetch('https://api.example.com/upload', { method: 'POST', body })
+}
+```
+
+### Chat-style picker with hook
+
+```tsx
+function ChatInput() {
+  const { assets, loading, pick, clear } = usePictureSelector({
+    mediaType: MediaType.ALL,
+    maxCount: 9,
+  })
+
+  const send = async () => {
+    if (assets.length === 0) return
+    await uploadAll(assets)
+    clear()
+  }
+
+  return (
+    <View>
+      <Pressable onPress={() => pick()} disabled={loading}>
+        <Text>📎 Attach</Text>
+      </Pressable>
+
+      {assets.length > 0 && (
+        <Pressable onPress={send}>
+          <Text>Send ({assets.length})</Text>
+        </Pressable>
+      )}
+    </View>
+  )
+}
+```
+
+---
+
+## Architecture
+
+```
+JavaScript / TypeScript
+  PictureSelector.openPicker()
+  usePictureSelector()
+        │
+        │  JSI (zero serialization overhead)
+        │  react-native-nitro-modules
+        ▼
+  HybridPictureSelector
+  ┌──────────────────────┬───────────────────────┐
+  │ Android (Kotlin)     │ iOS (Swift 5.9)       │
+  │                      │                       │
+  │ PictureSelector v3   │ HXPhotoPicker v5      │
+  │  ├─ GlideEngine      │  ├─ PickerConfiguration│
+  │  ├─ UCropEngine      │  ├─ PhotoPickerController│
+  │  └─ LubanCompress    │  └─ async result map  │
+  └──────────────────────┴───────────────────────┘
+```
+
+Communication goes through a **statically compiled JSI binding** generated by `nitrogen`. There is no JSON serialization and no async bridge queue — results are returned via native Promises resolved directly on the JS thread.
+
+---
+
+## Development workflow
+
+### Generate native bridge code
+
+After modifying `src/specs/PictureSelector.nitro.ts` run:
+
+```sh
+npx nitrogen generate
+# or
+bun run generate
+```
+
+This populates `nitrogen/generated/` with:
+- `android/kotlin/com/nitro/pictureselector/` — Kotlin abstract spec classes
+- `ios/` — Swift protocol files and Objective-C++ bridge
+
+**Do not edit files inside `nitrogen/generated/` manually** — they are overwritten on each codegen run.
+
+### Build TypeScript
+
+```sh
+bun run build
+# or
+npx bob build
+```
+
+### Run example
+
+```sh
+cd example
+npm install
+# iOS
+npx pod-install
+npx react-native run-ios
+
+# Android
+npx react-native run-android
+```
+
+---
+
+## Platform-specific notes
+
+### Android
+
+- Minimum SDK: **24** (Android 7.0)
+- PictureSelector v3 handles runtime permissions internally. On Android 13+ it requests `READ_MEDIA_IMAGES` / `READ_MEDIA_VIDEO`. On older versions it requests `READ_EXTERNAL_STORAGE`.
+- The `theme` option uses PictureSelector's built-in style presets. `PickerTheme.WECHAT` is the most polished.
+- Video files captured by camera are placed in the app cache directory.
+- Glide is used for thumbnail rendering inside the gallery grid.
+- uCrop handles all cropping; circular crop uses uCrop's `setCircleDimmedLayer(true)`.
+- Luban handles compression; files under 100 KB are passed through unchanged.
+
+### iOS
+
+- Minimum deployment target: **iOS 13.0**
+- Swift 5.9 is required for the C++ interop used by Nitro Modules.
+- HXPhotoPicker requests permissions automatically the first time the picker is opened. The `Info.plist` keys must be present or the app will crash.
+- The `circular` crop option is iOS-only; on Android it falls back to a 1:1 fixed ratio.
+- `isOriginal` in `MediaAsset` is only populated on iOS (when the user taps the "Original" button).
+- `bucketName` is only populated on Android.
+- `themeColor` sets HXPhotoPicker's global `themeColor` property.
+- The `theme` enum values `WECHAT`, `WHITE`, `DARK` have no effect on iOS (only `themeColor` is used).
+
+---
+
+## Permissions summary
+
+### Android
+
+| Permission | When requested |
+|-----------|----------------|
+| `CAMERA` | Camera capture |
+| `READ_EXTERNAL_STORAGE` | Android ≤ 12 |
+| `READ_MEDIA_IMAGES` | Android 13+ |
+| `READ_MEDIA_VIDEO` | Android 13+ |
+| `WRITE_EXTERNAL_STORAGE` | Android ≤ 9 only |
+
+### iOS (`Info.plist`)
+
+| Key | Purpose |
+|-----|---------|
+| `NSPhotoLibraryUsageDescription` | Read photos/videos |
+| `NSPhotoLibraryAddUsageDescription` | Save to library |
+| `NSCameraUsageDescription` | Camera capture |
+| `NSMicrophoneUsageDescription` | Video with audio |
+
+---
+
+## Known limitations (v1.0)
+
+| Feature | Status |
+|---------|--------|
+| Audio file selection | Not supported |
+| iCloud Photos (iOS) | Partial — depends on HXPhotoPicker internals |
+| LivePhoto | Not exposed |
+| Background upload / processing | Out of scope |
+| Save to gallery | Out of scope |
+| Document picker | Out of scope |
+
+---
+
+## License
+
+MIT © react-native-picture-selector contributors
+
+Native libraries:
+- [LuckSiege/PictureSelector](https://github.com/LuckSiege/PictureSelector) — Apache 2.0
+- [SilenceLove/HXPhotoPicker](https://github.com/SilenceLove/HXPhotoPicker) — MIT
+- [mrousavy/nitro](https://github.com/mrousavy/nitro) — MIT

package/android/CMakeLists.txt

@@ -0,0 +1,30 @@
+cmake_minimum_required(VERSION 3.22.1)
+project(NitroPictureSelector)
+
+# ─── React Native & Nitro Modules ────────────────────────────────────────────
+find_package(ReactAndroid REQUIRED CONFIG)
+find_package(fbjni REQUIRED CONFIG)
+find_package(react-native-nitro-modules REQUIRED CONFIG)
+
+# ─── Nitrogen-generated C++ bridge ───────────────────────────────────────────
+# nitrogen writes platform-agnostic JSI glue into nitrogen/generated/android/jni/
+file(GLOB NITRO_GENERATED_SRCS
+  "${CMAKE_CURRENT_SOURCE_DIR}/../nitrogen/generated/android/jni/*.cpp"
+)
+
+if(NITRO_GENERATED_SRCS)
+  add_library(${CMAKE_PROJECT_NAME} SHARED ${NITRO_GENERATED_SRCS})
+
+  target_include_directories(${CMAKE_PROJECT_NAME} PRIVATE
+    "${CMAKE_CURRENT_SOURCE_DIR}/../nitrogen/generated/android/jni"
+  )
+
+  target_link_libraries(${CMAKE_PROJECT_NAME}
+    ReactAndroid::jsi
+    ReactAndroid::reactnative
+    fbjni::fbjni
+    react-native-nitro-modules::NitroModules
+    android
+    log
+  )
+endif()