@interactify-live/pindo-wizard-react-native/README.md

React Native PindoWizard component for media capture and interaction management

# @interactify-live/pindo-wizard-react-native

A powerful React Native component for capturing media (photos/videos) and managing interactive overlays with a wizard-like interface. Perfect for creating interactive content with text overlays, geometric positioning, and seamless media management.

## Features

- 📸 **Media Capture**: Capture photos and videos using device camera
- 🎯 **Interactive Overlays**: Add text overlays with precise geometric positioning
- 🎨 **Visual Editor**: Intuitive interface for positioning and editing interactions
- 📱 **React Native**: Built specifically for React Native applications
- 🔧 **Customizable**: Flexible settings and configuration options
- 📤 **Upload Integration**: Built-in upload handling with progress tracking
- 🎭 **Cover Selection**: Choose cover images for video content
- 🌐 **Persian Support**: Built-in Persian number conversion utilities

## Installation

```bash
yarn add @interactify-live/pindo-wizard-react-native
```

### Peer Dependencies

This package requires the following peer dependencies:

```bash
yarn add react-native-vision-camera react-native-image-picker @interactify-live/player-react-native
```

## Quick Start

```tsx
import React from "react";
import { PindoWizard } from "@interactify-live/pindo-wizard-react-native";

const App = () => {
  const handleFinish = (medias) => {
    console.log("Captured media with interactions:", medias);
  };

  const handleUpload = async ({ uri, type }) => {
    // Implement your upload logic here
    const response = await uploadToServer(uri, type);
    return {
      url: response.url,
      thumbnail: response.thumbnail,
    };
  };

  return (
    <PindoWizard
      onFinish={handleFinish}
      handleUpload={handleUpload}
      settings={{
        isVideoActive: true,
        isInteractionActive: true,
        isCoverActive: true,
        numMedias: 3,
        flashEnabled: false,
      }}
    />
  );
};
```

## API Reference

### PindoWizard Props

| Prop           | Type                                                                  | Required | Description                    |
| -------------- | --------------------------------------------------------------------- | -------- | ------------------------------ |
| `onFinish`     | `(medias: MediaWithInteractions[]) => void`                           | ✅       | Callback when wizard completes |
| `handleUpload` | `(file: { uri: string; type: 'photo' \| 'video' }) => Promise<any>`   | ❌       | Upload handler function        |
| `uploadFile`   | `(file: any, onProgress: (progress: number) => void) => Promise<any>` | ❌       | Legacy upload handler          |
| `initialData`  | `MediaWithInteractions[]`                                             | ❌       | Pre-existing media data        |
| `settings`     | `Settings`                                                            | ❌       | Configuration settings         |

### Settings Interface

```typescript
interface Settings {
  isVideoActive?: boolean; // Enable video capture
  isInteractionActive?: boolean; // Enable interaction overlays
  isCoverActive?: boolean; // Enable cover selection
  numMedias?: number; // Maximum number of media items
  flashEnabled?: boolean; // Enable camera flash
}
```

### MediaWithInteractions Interface

```typescript
interface MediaWithInteractions {
  id: string;
  type: "video" | "image";
  url: string;
  thumbnail?: string;
  interactions: InteractionItem[];
  response?: any;
}
```

### InteractionItem Interface

```typescript
interface InteractionItem {
  interaction: string;
  payload: any;
  geometric: {
    x: number;
    y: number;
    width: number;
    height: number;
  };
}
```

## Usage Examples

### Basic Photo Capture

```tsx
import { PindoWizard } from "@interactify-live/pindo-wizard-react-native";

const PhotoCapture = () => {
  const handleFinish = (medias) => {
    medias.forEach((media) => {
      console.log(`Captured ${media.type}:`, media.url);
      console.log("Interactions:", media.interactions);
    });
  };

  return (
    <PindoWizard
      onFinish={handleFinish}
      settings={{
        isVideoActive: false,
        isInteractionActive: true,
        numMedias: 1,
      }}
    />
  );
};
```

### Video with Upload Integration

```tsx
const VideoCapture = () => {
  const handleUpload = async ({ uri, type }) => {
    const formData = new FormData();
    formData.append("file", {
      uri,
      type: type === "photo" ? "image/jpeg" : "video/mp4",
      name: `capture.${type === "photo" ? "jpg" : "mp4"}`,
    });

    const response = await fetch("https://your-api.com/upload", {
      method: "POST",
      body: formData,
    });

    return response.json();
  };

  return (
    <PindoWizard
      onFinish={console.log}
      handleUpload={handleUpload}
      settings={{
        isVideoActive: true,
        isInteractionActive: true,
        isCoverActive: true,
        numMedias: 3,
      }}
    />
  );
};
```

### Pre-populated Data

```tsx
const PrePopulatedWizard = () => {
  const initialData = [
    {
      id: "existing-1",
      type: "image",
      url: "https://example.com/image.jpg",
      thumbnail: "https://example.com/thumb.jpg",
      interactions: [
        {
          interaction: "text",
          payload: { text: "Hello World" },
          geometric: { x: 100, y: 100, width: 200, height: 50 },
        },
      ],
    },
  ];

  return (
    <PindoWizard
      onFinish={console.log}
      initialData={initialData}
      settings={{
        isVideoActive: true,
        isInteractionActive: true,
        numMedias: 5,
      }}
    />
  );
};
```

## Component Architecture

The PindoWizard consists of several key components:

- **CameraComponent**: Handles media capture using device camera
- **MediaThumbnails**: Displays captured media thumbnails
- **InteractionHeader**: Manages interaction editing interface
- **MainContent**: Main content area for media display
- **BottomControls**: Navigation and action buttons
- **TextInputModal**: Modal for adding/editing text overlays
- **CoverSelector**: Interface for selecting video covers

## Workflow

1. **Camera Step**: User captures photos/videos using device camera
2. **Interaction Step**: User adds and positions text overlays on media
3. **Cover Selection**: User selects cover image for video content (if enabled)
4. **Completion**: All media with interactions is returned via `onFinish` callback

## Permissions

This package requires the following permissions in your React Native app:

### iOS (Info.plist)

```xml
<key>NSCameraUsageDescription</key>
<string>This app needs access to camera to capture photos and videos</string>
<key>NSMicrophoneUsageDescription</key>
<string>This app needs access to microphone to record videos</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>This app needs access to photo library to save captured media</string>
```

### Android (AndroidManifest.xml)

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
```

## Styling

The component uses React Native's StyleSheet for styling. You can customize the appearance by modifying the component styles or wrapping it in your own styled container.

## Error Handling

The component includes built-in error handling for:

- Camera permission denials
- Upload failures
- Invalid media formats
- Network connectivity issues

## Browser Support

This package is designed specifically for React Native and is not compatible with web browsers.

## Contributing

We welcome contributions! Please see our contributing guidelines for more information.

## License

MIT License - see LICENSE file for details.

## Support

For support and questions, please open an issue on our GitHub repository or contact our support team.

## Changelog

### 1.0.0

- Initial release
- Camera capture functionality
- Interactive overlay system
- Upload integration
- Persian language support
- Cover selection for videos