@bitforgehq/angular-ionic-image-cropper/README.md

An Ionic Angular library for cross platform image cropping.

# Angular Ionic Image Cropper

A lightweight Angular library for image cropping with Ionic integration. This library provides a simple and customizable image cropper component that works seamlessly with Ionic applications.

## Features

- 🖼️ **Image Cropping**: Crop images with customizable aspect ratios
- 📱 **Ionic Integration**: Built specifically for Ionic applications
- 📷 **Camera Support**: Optional camera integration via Capacitor
- 📦 **Lightweight**: Minimal dependencies
- 🔧 **TypeScript**: Full TypeScript support

## Installation

```bash
npm install @bitforgehq/angular-ionic-image-cropper
```

### Import Global Styles (Recommended)

To ensure proper styling, especially for iOS builds, import the global styles in your application:

**In your main styles file (e.g., `src/styles.scss`):**
```scss
@use '@bitforgehq/angular-ionic-image-cropper/index.scss';
```

**Or in your `angular.json`:**
```json
{
  "styles": [
    "src/styles.scss",
    "node_modules/@bitforgehq/angular-ionic-image-cropper/index.scss"
  ]
}
```

**Note:** The styles are automatically included when you import the library, but for iOS builds, it's recommended to explicitly import the styles to ensure proper functionality. This library includes iOS-specific fixes for common rendering issues.

## Dependencies

This library requires the following peer dependencies:

```json
{
  "@angular/common": "^20.1.0",
  "@angular/core": "^20.1.0",
  "@ionic/angular": "^8.0.0"
}
```

For camera functionality, install the optional dependency:

```bash
npm install @capacitor/camera
```

## Usage

### 1. Import the Module

In your Angular module or standalone component:

```typescript
import { ImageCropperComponent, ImageCropperService } from '@bitforgehq/angular-ionic-image-cropper';

@Component({
  // ... your component config
  imports: [ImageCropperComponent]
})
export class YourComponent {
  private imageCropperService = inject(ImageCropperService);
}
```

### 2. Basic Usage

#### Using the Service (Recommended)

```typescript
import { ImageCropperService, ImageCropperConfig } from '@bitforgehq/angular-ionic-image-cropper';

export class YourComponent {
  private imageCropperService = inject(ImageCropperService);

  async cropImage() {
    try {
      // Open cropper with an image URL
      const croppedBlob = await this.imageCropperService.openCropper(
        'path/to/your/image.jpg',
        {
          aspectRatio: 16 / 9,   // optional, defaults to 16/9
          cancelText: 'Cancel',  // optional, defaults to 'Cancel'
          doneText: 'Done'       // optional, defaults to 'Done'
        }
      );
      
      console.log('Cropped image:', croppedBlob);
    } catch (error) {
      console.error('Crop cancelled or failed:', error);
    }
  }

  async takeAndCropPhoto() {
    try {
      // Take a photo and crop it
      const croppedBlob = await this.imageCropperService.takeAndCropPhoto({
        aspectRatio: 1,                // square aspect ratio
        cancelText: 'Cancel',          // 'cancel' button text
        doneText: 'Done',              // 'confirm' button text
        quality: 0.8,                  // 80% quality
        outputFormat: 'image/png'      // PNG format
      });
      
      console.log('Cropped photo:', croppedBlob);
    } catch (error) {
      console.error('Photo capture or crop failed:', error);
    }
  }
}
```

## API Reference

### ImageCropperService

#### Configuration Interface

```typescript
interface ImageCropperConfig {
  /**
   * Text to display on the cancel button
   * @default 'Cancel'
   */
  cancelText?: string;
  
  /**
   * Text to display on the done/confirm button
   * @default 'Done'
   */
  doneText?: string;
  
  /**
   * Aspect ratio for the crop area (width / height)
   * Common values: 1 (square), 16/9 (widescreen), 4/3 (standard)
   * @default 16/9
   */
  aspectRatio?: number;
  
  /**
   * Quality of the output image (0.1 to 1.0)
   * @default 0.9
   */
  quality?: number;
  
  /**
   * Output format for the cropped image
   * @default 'image/jpeg'
   */
  outputFormat?: 'image/jpeg' | 'image/png' | 'image/webp';
}
```

#### Methods

- `openCropper(imagePath: string, config?: ImageCropperConfig): Promise<Blob>`
  - Opens the cropper modal with the specified image
  - Returns a Promise that resolves to the cropped image as a Blob
  - Throws an error if the crop is cancelled

- `takeAndCropPhoto(config?: ImageCropperConfig): Promise<Blob>`
  - Opens the camera, takes a photo, then opens the cropper
  - Returns a Promise that resolves to the cropped image as a Blob
  - Requires `@capacitor/camera` to be installed

## Browser Support

This library supports all modern browsers that support:
- ES2015+ features
- Canvas API
- File API

## Troubleshooting

### iOS Build Issues

If you experience rendering issues on iOS builds, ensure you have imported the global styles:

```scss
// In your global styles file
@use '@bitforgehq/angular-ionic-image-cropper/index.scss';
```

### Cropper Not Displaying Properly

If the cropper modal doesn't display correctly, check that:
1. The cropper CSS is properly imported
2. Your app has proper viewport meta tags
3. The modal container has sufficient z-index

## License

MIT

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.