Configuration and Types

interface ImagePickerOptions {
  /**
   * Whether to show a UI to edit the image after it is picked.
   * On Android: crop and rotate. On iOS: crop only.
   * Mutually exclusive with allowsMultipleSelection.
   * @default false
   * @platform android, ios
   */
  allowsEditing?: boolean;

  /**
   * Aspect ratio [x, y] to maintain if allowsEditing is true.
   * Only applicable on Android (iOS crop is always square).
   */
  aspect?: [number, number];

  /**
   * Shape of crop area if allowsEditing is true.
   * @default 'rectangle'
   * @platform android
   */
  shape?: CropShape;

  /**
   * Quality of compression from 0 to 1.
   * 0 = compress for small size, 1 = compress for maximum quality.
   * @default 1.0
   * @platform android, ios
   */
  quality?: number;

  /**
   * Type of media to pick.
   * @default 'images'
   */
  mediaTypes?: MediaType | MediaType[] | MediaTypeOptions;

  /**
   * Whether to include EXIF data for images.
   * On iOS: EXIF data excludes GPS tags when using camera.
   * @platform android, ios
   */
  exif?: boolean;

  /**
   * Whether to include image data in Base64 format.
   */
  base64?: boolean;

  /**
   * Whether to allow selecting multiple media files.
   * Mutually exclusive with allowsEditing.
   * @default false
   * @platform android, ios 14+, web
   */
  allowsMultipleSelection?: boolean;

  /**
   * Maximum number of items user can select.
   * Only applies when allowsMultipleSelection is true.
   * 0 = system maximum.
   * @default 0
   * @platform android, ios 14+
   */
  selectionLimit?: number;

  /**
   * Whether to display numbered badges on selected assets.
   * Assets returned in selection order.
   * @default false
   * @platform ios 15+
   */
  orderedSelection?: boolean;

  /**
   * Maximum duration for video recording in seconds.
   * @platform android, ios
   */
  videoMaxDuration?: number;

  /**
   * Preset for video compression.
   * @default VideoExportPreset.Passthrough
   * @platform ios 11+
   * @deprecated See Apple documentation for videoExportPreset
   */
  videoExportPreset?: VideoExportPreset;

  /**
   * Quality of recorded videos.
   * @default UIImagePickerControllerQualityType.High
   * @platform ios
   */
  videoQuality?: UIImagePickerControllerQualityType;

  /**
   * Preferred camera to use.
   * @default CameraType.back
   * @platform android, ios
   */
  cameraType?: CameraType;

  /**
   * Presentation style for the picker.
   * @default UIImagePickerPresentationStyle.AUTOMATIC
   * @platform ios
   */
  presentationStyle?: UIImagePickerPresentationStyle;

  /**
   * Preferred asset representation mode.
   * @default UIImagePickerPreferredAssetRepresentationMode.Automatic
   * @platform ios
   */
  preferredAssetRepresentationMode?: UIImagePickerPreferredAssetRepresentationMode;

  /**
   * Default tab to open in picker.
   * @platform android
   */
  defaultTab?: DefaultTab;

  /**
   * Uses the legacy image picker on Android.
   * Allows media selection from outside the user's photo library.
   * @default false
   * @platform android
   */
  legacy?: boolean;
}

import * as ImagePicker from 'expo-image-picker';

// Basic image selection with editing
const basicOptions: ImagePicker.ImagePickerOptions = {
  mediaTypes: 'images',
  allowsEditing: true,
  aspect: [4, 3],
  quality: 0.8,
};

// Multiple selection with limits
const multipleOptions: ImagePicker.ImagePickerOptions = {
  mediaTypes: ['images', 'videos'],
  allowsMultipleSelection: true,
  selectionLimit: 5,
  orderedSelection: true,
  quality: 0.7,
};

// Video recording with constraints
const videoOptions: ImagePicker.ImagePickerOptions = {
  mediaTypes: 'videos',
  videoMaxDuration: 30, // 30 seconds
  videoQuality: ImagePicker.UIImagePickerControllerQualityType.Medium,
  allowsEditing: true,
};

// High-quality capture with metadata
const highQualityOptions: ImagePicker.ImagePickerOptions = {
  mediaTypes: 'images',
  quality: 1.0,
  exif: true,
  base64: false, // Avoid base64 for large images
  allowsEditing: false,
};

// Front camera selfie
const selfieOptions: ImagePicker.ImagePickerOptions = {
  mediaTypes: 'images',
  cameraType: ImagePicker.CameraType.front,
  allowsEditing: true,
  aspect: [1, 1],
  quality: 0.8,
};

/**
 * Media types that can be picked by the image picker.
 */
type MediaType = 'images' | 'videos' | 'livePhotos';

/**
 * @deprecated Use MediaType instead
 */
enum MediaTypeOptions {
  All = 'All',
  Videos = 'Videos',
  Images = 'Images',
}

/**
 * Default tab for image picker.
 * @platform android
 */
type DefaultTab = 'photos' | 'albums';

/**
 * Shape of crop area.
 */
type CropShape = 'rectangle' | 'oval';

/**
 * Camera type selection.
 */
enum CameraType {
  back = 'back',
  front = 'front',
}

/**
 * Video export quality presets.
 */
enum VideoExportPreset {
  Passthrough = 0,      // No compression
  LowQuality = 1,       // Device-dependent, H.264/AAC
  MediumQuality = 2,    // Device-dependent, H.264/AAC
  HighestQuality = 3,   // Device-dependent, H.264/AAC
  H264_640x480 = 4,     // 640×480, H.264/AAC
  H264_960x540 = 5,     // 960×540, H.264/AAC
  H264_1280x720 = 6,    // 1280×720, H.264/AAC
  H264_1920x1080 = 7,   // 1920×1080, H.264/AAC
  H264_3840x2160 = 8,   // 3840×2160, H.264/AAC
  HEVC_1920x1080 = 9,   // 1920×1080, HEVC/AAC
  HEVC_3840x2160 = 10,  // 3840×2160, HEVC/AAC
}

/**
 * iOS video quality types.
 * @platform ios
 */
enum UIImagePickerControllerQualityType {
  High = 0,    // Highest available resolution
  Medium = 1,  // Device-dependent
  Low = 2,     // Device-dependent
  VGA640x480 = 3,      // 640×480
  IFrame1280x720 = 4,  // 1280×720
  IFrame960x540 = 5,   // 960×540
}

/**
 * iOS presentation styles.
 * @platform ios
 */
enum UIImagePickerPresentationStyle {
  FULL_SCREEN = 'fullScreen',
  PAGE_SHEET = 'pageSheet',
  FORM_SHEET = 'formSheet',
  CURRENT_CONTEXT = 'currentContext',
  OVER_FULL_SCREEN = 'overFullScreen',
  OVER_CURRENT_CONTEXT = 'overCurrentContext',
  POPOVER = 'popover',
  AUTOMATIC = 'automatic',
}

/**
 * iOS asset representation modes.
 * @platform ios
 */
enum UIImagePickerPreferredAssetRepresentationMode {
  Automatic = 'automatic',   // System chooses
  Compatible = 'compatible', // Most compatible
  Current = 'current',       // Avoid transcoding
}

/**
 * Represents an asset (image or video) returned by the picker.
 */
interface ImagePickerAsset {
  /** URI to the local image or video file */
  uri: string;
  
  /** Width of the image or video */
  width: number;
  
  /** Height of the image or video */
  height: number;
  
  /** Type of the asset */
  type?: 'image' | 'video' | 'livePhoto' | 'pairedVideo';
  
  /** 
   * Unique ID for the asset (library picks only).
   * May be null with limited permissions or direct file selection.
   * @platform android, ios
   */
  assetId?: string | null;
  
  /** 
   * Preferred filename for the asset.
   * May be null with limited permissions.
   */
  fileName?: string | null;
  
  /** File size in bytes */
  fileSize?: number;
  
  /** 
   * Base64-encoded image data (if base64 option enabled).
   * Prepend with 'data:image/jpeg;base64,' for data URI.
   */
  base64?: string | null;
  
  /** 
   * EXIF metadata (if exif option enabled).
   * GPS tags excluded when using camera on iOS.
   * @platform android, ios
   */
  exif?: Record<string, any> | null;
  
  /** Video duration in milliseconds (videos only) */
  duration?: number | null;
  
  /** MIME type of the asset */
  mimeType?: string;
  
  /** 
   * Video asset paired with live photo (iOS only).
   * Only present when livePhotos media type selected.
   * @platform ios
   */
  pairedVideoAsset?: ImagePickerAsset | null;
  
  /** 
   * Web File object for server uploads.
   * @platform web
   */
  file?: File;
}

// Complete configuration examples
const examples = {
  // Professional photo capture
  professional: {
    mediaTypes: 'images' as const,
    quality: 1.0,
    exif: true,
    allowsEditing: false,
    presentationStyle: ImagePicker.UIImagePickerPresentationStyle.FULL_SCREEN,
  },

  // Social media post
  socialMedia: {
    mediaTypes: 'images' as const,
    allowsEditing: true,
    aspect: [1, 1] as [number, number],
    quality: 0.8,
    base64: false,
  },

  // Document scanning
  document: {
    mediaTypes: 'images' as const,
    allowsEditing: true,
    shape: 'rectangle' as const,
    quality: 0.9,
    cameraType: ImagePicker.CameraType.back,
  },

  // Video story
  videoStory: {
    mediaTypes: 'videos' as const,
    videoMaxDuration: 15,
    videoQuality: ImagePicker.UIImagePickerControllerQualityType.Medium,
    allowsEditing: true,
    cameraType: ImagePicker.CameraType.front,
  },

  // Multi-selection gallery
  gallery: {
    mediaTypes: ['images'] as const,
    allowsMultipleSelection: true,
    selectionLimit: 10,
    orderedSelection: true,
    quality: 0.7,
  },

  // Live photos (iOS)
  livePhotos: {
    mediaTypes: ['images', 'livePhotos'] as const,
    quality: 1.0,
    allowsEditing: false, // Live photos ignore editing
  },
} satisfies Record<string, ImagePicker.ImagePickerOptions>;

/**
 * @deprecated Use ImagePickerAsset instead
 */
type ImageInfo = ImagePickerAsset;

/**
 * @deprecated Use ImagePickerCanceledResult instead
 */
type ImagePickerCancelledResult = ImagePickerCanceledResult;

/**
 * @deprecated Use ImagePickerResult instead
 */
type ImagePickerMultipleResult = ImagePickerResult;