@kesbyte/capacitor-exif-gallery 1.0.0

package/dist/esm/definitions.d.ts

@@ -0,0 +1,539 @@
+/**
+ * Supported languages for built-in translations.
+ */
+export type SupportedLocale = 'en' | 'de' | 'fr' | 'es';
+/**
+ * Distance unit for radius display in filter dialog.
+ *
+ * @since 1.1.0
+ */
+export type DistanceUnit = 'kilometers' | 'miles';
+/**
+ * Complete set of UI text keys used by the plugin.
+ * All keys are required for a complete translation.
+ */
+export interface TranslationSet {
+    /** Gallery screen title */
+    galleryTitle: string;
+    /** "Select" button text */
+    selectButton: string;
+    /** "Cancel" button text (also used for accessibility label on icon-only cancel button) */
+    cancelButton: string;
+    /** "Select All" button text */
+    selectAllButton: string;
+    /** "Deselect All" button text */
+    deselectAllButton: string;
+    /** Selection counter text. Placeholders: {count}, {total} */
+    selectionCounter: string;
+    /** "Confirm" button text (also used for accessibility label on icon-only confirm button) */
+    confirmButton: string;
+    /** "Filter" button accessibility label (optional, falls back to filterDialogTitle) */
+    filterButton?: string;
+    /** Filter dialog title */
+    filterDialogTitle: string;
+    /** "Radius (meters)" label */
+    radiusLabel: string;
+    /** "Start Date" label */
+    startDateLabel: string;
+    /** "End Date" label */
+    endDateLabel: string;
+    /** "Loading images..." message */
+    loadingMessage: string;
+    /** "No images found" message */
+    emptyMessage: string;
+    /** "An error occurred" message */
+    errorMessage: string;
+    /** "Retry" button text */
+    retryButton: string;
+    /** "Plugin not initialized" error */
+    initializationError: string;
+    /** "Permission denied" error */
+    permissionError: string;
+    /** "Invalid filter parameters" error */
+    filterError: string;
+    /** Photo access required message (shown when user denies photo permission) */
+    noStoragePermission?: string;
+    /** Permanent photo denial message (shown when user selects "Don't ask again" on Android) */
+    noStoragePermissionPermanent?: string;
+    /** Photo access restricted message (shown on iOS when restricted by parental controls/MDM) */
+    noStoragePermissionRestricted?: string;
+    /** Location access required message (shown when user denies location permission) */
+    noLocationPermission?: string;
+    /** Location permission fallback message (informational, shown when falling back to time filtering) */
+    locationPermissionFallback?: string;
+    /** "Open Settings" button text (opens system settings for permission management) */
+    openSettings?: string;
+    /** "OK" button text (generic confirmation, used in location fallback dialog) */
+    ok?: string;
+}
+/**
+ * Plugin initialization configuration.
+ * All properties are optional.
+ */
+export interface InitConfig {
+    /**
+     * Optional locale to use for UI text.
+     * If not provided, system language is detected automatically.
+     * Falls back to English if system language is not supported.
+     *
+     * @example
+     * ```typescript
+     * await ExifGallery.initialize({ locale: 'de' });
+     * ```
+     */
+    locale?: SupportedLocale;
+    /**
+     * Optional custom text overrides.
+     * Merges on top of default translations for the selected locale.
+     * Partial object - only override the keys you need.
+     *
+     * @example
+     * ```typescript
+     * await ExifGallery.initialize({
+     *   customTexts: {
+     *     galleryTitle: 'Choose Your Photos',
+     *     confirmButton: 'Done'
+     *   }
+     * });
+     * ```
+     */
+    customTexts?: Partial<TranslationSet>;
+    /**
+     * Whether to request photo library permissions immediately during initialization.
+     * Default: false (permissions requested just-in-time when pick() is called)
+     *
+     * Set to true if you want to request permissions upfront (e.g., during onboarding).
+     *
+     * @example
+     * ```typescript
+     * await ExifGallery.initialize({ requestPermissionsUpfront: true });
+     * ```
+     */
+    requestPermissionsUpfront?: boolean;
+}
+/**
+ * Geographic coordinate with latitude and longitude.
+ */
+export interface LatLng {
+    /** Latitude in decimal degrees */
+    lat: number;
+    /** Longitude in decimal degrees */
+    lng: number;
+}
+/**
+ * Location-based filter configuration.
+ */
+export interface LocationFilter {
+    /**
+     * GPS track as array of coordinates OR encoded polyline string.
+     *
+     * **Coordinate Array Format:**
+     * ```typescript
+     * polyline: [{ lat: 38.5, lng: -120.2 }, { lat: 40.7, lng: -120.95 }]
+     * ```
+     *
+     * **Encoded Polyline Format (Google's Polyline Encoding Algorithm, precision 5):**
+     * ```typescript
+     * polyline: "_p~iF~ps|U_ulLnnqC"
+     * ```
+     *
+     * Note: Precision 5 provides ±1 meter accuracy (Google Maps default).
+     * Higher precision polylines (6+) are also supported.
+     *
+     * Images within `radius` meters of any point on the polyline will match.
+     *
+     * **Limits:**
+     * - Max encoded string: 50 KB
+     * - Max decoded points: 1,000
+     * - Min points: 2 (to define a path)
+     *
+     * @see https://developers.google.com/maps/documentation/utilities/polylinealgorithm
+     * @example
+     * // Using encoded polyline (from Google Maps API)
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       polyline: "_p~iF~ps|U_ulLnnqC",
+     *       radius: 5000
+     *     }
+     *   }
+     * });
+     *
+     * @example
+     * // Using coordinate array
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       polyline: [
+     *         { lat: 48.8566, lng: 2.3522 },
+     *         { lat: 48.8606, lng: 2.3376 }
+     *       ],
+     *       radius: 5000
+     *     }
+     *   }
+     * });
+     */
+    polyline?: LatLng[] | string;
+    /**
+     * Individual coordinate points (e.g., from map markers).
+     * Images within `radius` meters of any coordinate will match.
+     */
+    coordinates?: LatLng[];
+    /**
+     * Search radius in meters.
+     * Default: 100
+     *
+     * @example
+     * ```typescript
+     * {
+     *   polyline: [{lat: 48.1, lng: 11.5}, {lat: 48.2, lng: 11.6}],
+     *   radius: 1000  // 1km radius
+     * }
+     * ```
+     */
+    radius?: number;
+}
+/**
+ * Time range filter configuration.
+ */
+export interface TimeRangeFilter {
+    /**
+     * Start date/time for the filter.
+     * Images taken at or after this time will match.
+     */
+    start: Date;
+    /**
+     * End date/time for the filter.
+     * Images taken at or before this time will match.
+     */
+    end: Date;
+}
+/**
+ * Combined filter configuration for location and/or time.
+ */
+export interface FilterConfig {
+    /**
+     * Optional location-based filter.
+     * If provided with timeRange, both filters are applied (AND condition).
+     */
+    location?: LocationFilter;
+    /**
+     * Optional time range filter.
+     * If provided with location, both filters are applied (AND condition).
+     */
+    timeRange?: TimeRangeFilter;
+}
+/**
+ * Options for the pick() method.
+ */
+export interface PickOptions {
+    /**
+     * Optional filter configuration to pre-configure the gallery.
+     * If not provided, user can manually set filters in the gallery UI.
+     *
+     * @example
+     * ```typescript
+     * await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       coordinates: [{lat: 48.1, lng: 11.5}],
+     *       radius: 500
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    filter?: FilterConfig;
+    /**
+     * Minimum number of results required before automatic fallback to time filter.
+     * If location filter returns fewer images than this threshold,
+     * the plugin automatically falls back to time-based filtering.
+     *
+     * Default: 5
+     *
+     * @example
+     * ```typescript
+     * await ExifGallery.pick({
+     *   filter: { location: {...} },
+     *   fallbackThreshold: 10  // Fallback if < 10 images found
+     * });
+     * ```
+     */
+    fallbackThreshold?: number;
+    /**
+     * Whether to allow user to manually adjust filters in the gallery UI.
+     * Default: true
+     *
+     * Set to false if you want to enforce the provided filter configuration.
+     */
+    allowManualAdjustment?: boolean;
+    /**
+     * Distance unit for radius display in filter dialog.
+     *
+     * **Default:** `'kilometers'`
+     *
+     * **Supported units:**
+     * - `'kilometers'`: Display as km (1000m = 1km)
+     * - `'miles'`: Display as miles (1609.34m = 1mi)
+     *
+     * @since 1.1.0
+     *
+     * @example
+     * ```typescript
+     * // Use miles for US users
+     * await ExifGallery.pick({
+     *   filter: { location: {...} },
+     *   distanceUnit: 'miles'
+     * });
+     *
+     * // Use kilometers (default)
+     * await ExifGallery.pick({
+     *   filter: { location: {...} }
+     * });
+     *
+     * // Based on user preference
+     * const userUnit = userSettings.useMetric ? 'kilometers' : 'miles';
+     * await ExifGallery.pick({
+     *   filter: { location: {...} },
+     *   distanceUnit: userUnit
+     * });
+     * ```
+     */
+    distanceUnit?: DistanceUnit;
+    /**
+     * Step size for distance filter slider (in kilometers).
+     *
+     * Defines the granularity of the radius adjustment slider in the filter dialog.
+     *
+     * **Default:** `5` (5km steps)
+     *
+     * **Range:** 1 - 25 km
+     *
+     * @since 1.2.0
+     *
+     * @example
+     * ```typescript
+     * // Fine-grained control: 1km steps (5, 6, 7, 8, ...)
+     * await ExifGallery.pick({
+     *   filter: { location: {...} },
+     *   distanceStep: 1
+     * });
+     *
+     * // Default: 5km steps (5, 10, 15, 20, ...)
+     * await ExifGallery.pick({
+     *   filter: { location: {...} }
+     *   // distanceStep defaults to 5
+     * });
+     *
+     * // Coarse control: 10km steps (10, 20, 30, 40, 50)
+     * await ExifGallery.pick({
+     *   filter: { location: {...} },
+     *   distanceStep: 10
+     * });
+     *
+     * // Can be combined with distanceUnit
+     * await ExifGallery.pick({
+     *   filter: { location: {...} },
+     *   distanceUnit: 'miles',
+     *   distanceStep: 5  // 5km steps, displayed as miles
+     * });
+     * ```
+     */
+    distanceStep?: number;
+}
+/**
+ * EXIF metadata extracted from an image.
+ */
+export interface ImageExif {
+    /** Latitude from GPS EXIF data (if available) */
+    lat?: number;
+    /** Longitude from GPS EXIF data (if available) */
+    lng?: number;
+    /** Timestamp from EXIF DateTimeOriginal (if available) */
+    timestamp?: Date;
+}
+/**
+ * Single image result from pick().
+ */
+export interface ImageResult {
+    /**
+     * File URI for the image (file:// path).
+     * Can be used to display or upload the image.
+     */
+    uri: string;
+    /**
+     * Web-safe path for displaying the image in a WebView.
+     * This is the Capacitor-converted URL (capacitor://localhost/_capacitor_file_/...).
+     *
+     * Use this for <img src> tags - no manual Capacitor.convertFileSrc() needed.
+     *
+     * @since 1.2.0
+     */
+    webPath?: string;
+    /**
+     * EXIF metadata if available.
+     * May be undefined if image has no EXIF data.
+     */
+    exif?: ImageExif;
+    /**
+     * How this image was filtered.
+     * - 'location': Matched location filter
+     * - 'time': Matched time filter (or fallback from location filter)
+     */
+    filteredBy: 'location' | 'time';
+}
+/**
+ * Result from pick() method.
+ */
+export interface PickResult {
+    /**
+     * Array of selected images.
+     * Empty if user cancelled or no images matched filters.
+     */
+    images: ImageResult[];
+    /**
+     * True if user explicitly cancelled the selection.
+     * False if user confirmed selection (even if no images selected).
+     */
+    cancelled: boolean;
+}
+/**
+ * Main plugin interface.
+ *
+ * @example
+ * ```typescript
+ * import { ExifGallery } from '@kesbyte/capacitor-exif-gallery';
+ *
+ * // Initialize plugin (once at app startup)
+ * await ExifGallery.initialize({
+ *   locale: 'de',
+ *   customTexts: {
+ *     galleryTitle: 'Wähle Fotos'
+ *   }
+ * });
+ *
+ * // Open gallery with filter
+ * const result = await ExifGallery.pick({
+ *   filter: {
+ *     location: {
+ *       polyline: gpsTrack,  // LatLng[]
+ *       radius: 1000
+ *     }
+ *   },
+ *   fallbackThreshold: 5
+ * });
+ *
+ * if (!result.cancelled) {
+ *   console.log(`Selected ${result.images.length} images`);
+ *   result.images.forEach(img => {
+ *     console.log(`Image: ${img.uri}, filtered by: ${img.filteredBy}`);
+ *   });
+ * }
+ * ```
+ */
+export interface ExifGalleryPlugin {
+    /**
+     * Initialize the plugin with optional configuration.
+     *
+     * Must be called before pick(). Can be called multiple times to update configuration.
+     *
+     * **Default behavior (no config):**
+     * - Detects system language automatically
+     * - Uses built-in English/German/French/Spanish translations
+     * - Requests permissions just-in-time (when pick() is called)
+     *
+     * @param config - Optional configuration object
+     * @returns Promise that resolves when initialization is complete
+     *
+     * @throws {Error} If locale is invalid or customTexts contain unknown keys
+     *
+     * @example
+     * ```typescript
+     * // Minimal - use defaults
+     * await ExifGallery.initialize();
+     *
+     * // With locale
+     * await ExifGallery.initialize({ locale: 'de' });
+     *
+     * // With custom text overrides
+     * await ExifGallery.initialize({
+     *   customTexts: {
+     *     galleryTitle: 'Choose Photos',
+     *     confirmButton: 'Done'
+     *   }
+     * });
+     *
+     * // Request permissions upfront
+     * await ExifGallery.initialize({
+     *   requestPermissionsUpfront: true
+     * });
+     * ```
+     */
+    initialize(config?: InitConfig): Promise<void>;
+    /**
+     * Open native gallery with optional filters and return selected images.
+     *
+     * Must call initialize() first, otherwise throws initialization_required error.
+     *
+     * **Filter behavior:**
+     * - If filter provided: Gallery opens with pre-configured filters
+     * - If no filter: User can manually set filters in gallery UI
+     * - Auto-fallback: If location filter returns < fallbackThreshold images, falls back to time filter
+     *
+     * @param options - Optional pick options with filters
+     * @returns Promise with selected images or cancellation status
+     *
+     * @throws {Error} 'initialization_required' if initialize() not called
+     * @throws {Error} 'no_permission' if required permissions denied
+     * @throws {Error} 'filter_error' if filter parameters are invalid
+     *
+     * @example
+     * ```typescript
+     * // No filter - user sets filters manually
+     * const result = await ExifGallery.pick();
+     *
+     * // Location filter with polyline
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       polyline: [{lat: 48.1, lng: 11.5}, {lat: 48.2, lng: 11.6}],
+     *       radius: 1000
+     *     }
+     *   }
+     * });
+     *
+     * // Time range filter
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     timeRange: {
+     *       start: new Date('2024-01-01'),
+     *       end: new Date('2024-01-31')
+     *     }
+     *   }
+     * });
+     *
+     * // Combined filters
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: { coordinates: [{lat: 48.1, lng: 11.5}], radius: 500 },
+     *     timeRange: { start: new Date('2024-01-01'), end: new Date() }
+     *   },
+     *   fallbackThreshold: 10,
+     *   allowManualAdjustment: false
+     * });
+     *
+     * // Handle result
+     * if (!result.cancelled) {
+     *   console.log(`Selected ${result.images.length} images`);
+     *   for (const img of result.images) {
+     *     console.log(`${img.uri} - filtered by ${img.filteredBy}`);
+     *     if (img.exif) {
+     *       console.log(`  GPS: ${img.exif.lat}, ${img.exif.lng}`);
+     *       console.log(`  Time: ${img.exif.timestamp}`);
+     *     }
+     *   }
+     * }
+     * ```
+     */
+    pick(options?: PickOptions): Promise<PickResult>;
+}

package/dist/esm/definitions.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=definitions.js.map

package/dist/esm/definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Supported languages for built-in translations.\n */\nexport type SupportedLocale = 'en' | 'de' | 'fr' | 'es';\n\n/**\n * Distance unit for radius display in filter dialog.\n *\n * @since 1.1.0\n */\nexport type DistanceUnit = 'kilometers' | 'miles';\n\n/**\n * Complete set of UI text keys used by the plugin.\n * All keys are required for a complete translation.\n */\nexport interface TranslationSet {\n  // Gallery UI (8 keys)\n  /** Gallery screen title */\n  galleryTitle: string;\n  /** \"Select\" button text */\n  selectButton: string;\n  /** \"Cancel\" button text (also used for accessibility label on icon-only cancel button) */\n  cancelButton: string;\n  /** \"Select All\" button text */\n  selectAllButton: string;\n  /** \"Deselect All\" button text */\n  deselectAllButton: string;\n  /** Selection counter text. Placeholders: {count}, {total} */\n  selectionCounter: string;\n  /** \"Confirm\" button text (also used for accessibility label on icon-only confirm button) */\n  confirmButton: string;\n  /** \"Filter\" button accessibility label (optional, falls back to filterDialogTitle) */\n  filterButton?: string;\n\n  // Filter Dialog (4 keys)\n  /** Filter dialog title */\n  filterDialogTitle: string;\n  /** \"Radius (meters)\" label */\n  radiusLabel: string;\n  /** \"Start Date\" label */\n  startDateLabel: string;\n  /** \"End Date\" label */\n  endDateLabel: string;\n\n  // UI States (4 keys)\n  /** \"Loading images...\" message */\n  loadingMessage: string;\n  /** \"No images found\" message */\n  emptyMessage: string;\n  /** \"An error occurred\" message */\n  errorMessage: string;\n  /** \"Retry\" button text */\n  retryButton: string;\n\n  // Error Messages (3 keys)\n  /** \"Plugin not initialized\" error */\n  initializationError: string;\n  /** \"Permission denied\" error */\n  permissionError: string;\n  /** \"Invalid filter parameters\" error */\n  filterError: string;\n\n  // Permission Error Messages (Story 5.4) (7 keys - all optional)\n  /** Photo access required message (shown when user denies photo permission) */\n  noStoragePermission?: string;\n  /** Permanent photo denial message (shown when user selects \"Don't ask again\" on Android) */\n  noStoragePermissionPermanent?: string;\n  /** Photo access restricted message (shown on iOS when restricted by parental controls/MDM) */\n  noStoragePermissionRestricted?: string;\n  /** Location access required message (shown when user denies location permission) */\n  noLocationPermission?: string;\n  /** Location permission fallback message (informational, shown when falling back to time filtering) */\n  locationPermissionFallback?: string;\n  /** \"Open Settings\" button text (opens system settings for permission management) */\n  openSettings?: string;\n  /** \"OK\" button text (generic confirmation, used in location fallback dialog) */\n  ok?: string;\n}\n\n/**\n * Plugin initialization configuration.\n * All properties are optional.\n */\nexport interface InitConfig {\n  /**\n   * Optional locale to use for UI text.\n   * If not provided, system language is detected automatically.\n   * Falls back to English if system language is not supported.\n   *\n   * @example\n   * ```typescript\n   * await ExifGallery.initialize({ locale: 'de' });\n   * ```\n   */\n  locale?: SupportedLocale;\n\n  /**\n   * Optional custom text overrides.\n   * Merges on top of default translations for the selected locale.\n   * Partial object - only override the keys you need.\n   *\n   * @example\n   * ```typescript\n   * await ExifGallery.initialize({\n   *   customTexts: {\n   *     galleryTitle: 'Choose Your Photos',\n   *     confirmButton: 'Done'\n   *   }\n   * });\n   * ```\n   */\n  customTexts?: Partial<TranslationSet>;\n\n  /**\n   * Whether to request photo library permissions immediately during initialization.\n   * Default: false (permissions requested just-in-time when pick() is called)\n   *\n   * Set to true if you want to request permissions upfront (e.g., during onboarding).\n   *\n   * @example\n   * ```typescript\n   * await ExifGallery.initialize({ requestPermissionsUpfront: true });\n   * ```\n   */\n  requestPermissionsUpfront?: boolean;\n}\n\n/**\n * Geographic coordinate with latitude and longitude.\n */\nexport interface LatLng {\n  /** Latitude in decimal degrees */\n  lat: number;\n  /** Longitude in decimal degrees */\n  lng: number;\n}\n\n/**\n * Location-based filter configuration.\n */\nexport interface LocationFilter {\n  /**\n   * GPS track as array of coordinates OR encoded polyline string.\n   *\n   * **Coordinate Array Format:**\n   * ```typescript\n   * polyline: [{ lat: 38.5, lng: -120.2 }, { lat: 40.7, lng: -120.95 }]\n   * ```\n   *\n   * **Encoded Polyline Format (Google's Polyline Encoding Algorithm, precision 5):**\n   * ```typescript\n   * polyline: \"_p~iF~ps|U_ulLnnqC\"\n   * ```\n   *\n   * Note: Precision 5 provides ±1 meter accuracy (Google Maps default).\n   * Higher precision polylines (6+) are also supported.\n   *\n   * Images within `radius` meters of any point on the polyline will match.\n   *\n   * **Limits:**\n   * - Max encoded string: 50 KB\n   * - Max decoded points: 1,000\n   * - Min points: 2 (to define a path)\n   *\n   * @see https://developers.google.com/maps/documentation/utilities/polylinealgorithm\n   * @example\n   * // Using encoded polyline (from Google Maps API)\n   * const result = await ExifGallery.pick({\n   *   filter: {\n   *     location: {\n   *       polyline: \"_p~iF~ps|U_ulLnnqC\",\n   *       radius: 5000\n   *     }\n   *   }\n   * });\n   *\n   * @example\n   * // Using coordinate array\n   * const result = await ExifGallery.pick({\n   *   filter: {\n   *     location: {\n   *       polyline: [\n   *         { lat: 48.8566, lng: 2.3522 },\n   *         { lat: 48.8606, lng: 2.3376 }\n   *       ],\n   *       radius: 5000\n   *     }\n   *   }\n   * });\n   */\n  polyline?: LatLng[] | string;\n\n  /**\n   * Individual coordinate points (e.g., from map markers).\n   * Images within `radius` meters of any coordinate will match.\n   */\n  coordinates?: LatLng[];\n\n  /**\n   * Search radius in meters.\n   * Default: 100\n   *\n   * @example\n   * ```typescript\n   * {\n   *   polyline: [{lat: 48.1, lng: 11.5}, {lat: 48.2, lng: 11.6}],\n   *   radius: 1000  // 1km radius\n   * }\n   * ```\n   */\n  radius?: number;\n}\n\n/**\n * Time range filter configuration.\n */\nexport interface TimeRangeFilter {\n  /**\n   * Start date/time for the filter.\n   * Images taken at or after this time will match.\n   */\n  start: Date;\n\n  /**\n   * End date/time for the filter.\n   * Images taken at or before this time will match.\n   */\n  end: Date;\n}\n\n/**\n * Combined filter configuration for location and/or time.\n */\nexport interface FilterConfig {\n  /**\n   * Optional location-based filter.\n   * If provided with timeRange, both filters are applied (AND condition).\n   */\n  location?: LocationFilter;\n\n  /**\n   * Optional time range filter.\n   * If provided with location, both filters are applied (AND condition).\n   */\n  timeRange?: TimeRangeFilter;\n}\n\n/**\n * Options for the pick() method.\n */\nexport interface PickOptions {\n  /**\n   * Optional filter configuration to pre-configure the gallery.\n   * If not provided, user can manually set filters in the gallery UI.\n   *\n   * @example\n   * ```typescript\n   * await ExifGallery.pick({\n   *   filter: {\n   *     location: {\n   *       coordinates: [{lat: 48.1, lng: 11.5}],\n   *       radius: 500\n   *     }\n   *   }\n   * });\n   * ```\n   */\n  filter?: FilterConfig;\n\n  /**\n   * Minimum number of results required before automatic fallback to time filter.\n   * If location filter returns fewer images than this threshold,\n   * the plugin automatically falls back to time-based filtering.\n   *\n   * Default: 5\n   *\n   * @example\n   * ```typescript\n   * await ExifGallery.pick({\n   *   filter: { location: {...} },\n   *   fallbackThreshold: 10  // Fallback if < 10 images found\n   * });\n   * ```\n   */\n  fallbackThreshold?: number;\n\n  /**\n   * Whether to allow user to manually adjust filters in the gallery UI.\n   * Default: true\n   *\n   * Set to false if you want to enforce the provided filter configuration.\n   */\n  allowManualAdjustment?: boolean;\n\n  /**\n   * Distance unit for radius display in filter dialog.\n   *\n   * **Default:** `'kilometers'`\n   *\n   * **Supported units:**\n   * - `'kilometers'`: Display as km (1000m = 1km)\n   * - `'miles'`: Display as miles (1609.34m = 1mi)\n   *\n   * @since 1.1.0\n   *\n   * @example\n   * ```typescript\n   * // Use miles for US users\n   * await ExifGallery.pick({\n   *   filter: { location: {...} },\n   *   distanceUnit: 'miles'\n   * });\n   *\n   * // Use kilometers (default)\n   * await ExifGallery.pick({\n   *   filter: { location: {...} }\n   * });\n   *\n   * // Based on user preference\n   * const userUnit = userSettings.useMetric ? 'kilometers' : 'miles';\n   * await ExifGallery.pick({\n   *   filter: { location: {...} },\n   *   distanceUnit: userUnit\n   * });\n   * ```\n   */\n  distanceUnit?: DistanceUnit;\n\n  /**\n   * Step size for distance filter slider (in kilometers).\n   *\n   * Defines the granularity of the radius adjustment slider in the filter dialog.\n   *\n   * **Default:** `5` (5km steps)\n   *\n   * **Range:** 1 - 25 km\n   *\n   * @since 1.2.0\n   *\n   * @example\n   * ```typescript\n   * // Fine-grained control: 1km steps (5, 6, 7, 8, ...)\n   * await ExifGallery.pick({\n   *   filter: { location: {...} },\n   *   distanceStep: 1\n   * });\n   *\n   * // Default: 5km steps (5, 10, 15, 20, ...)\n   * await ExifGallery.pick({\n   *   filter: { location: {...} }\n   *   // distanceStep defaults to 5\n   * });\n   *\n   * // Coarse control: 10km steps (10, 20, 30, 40, 50)\n   * await ExifGallery.pick({\n   *   filter: { location: {...} },\n   *   distanceStep: 10\n   * });\n   *\n   * // Can be combined with distanceUnit\n   * await ExifGallery.pick({\n   *   filter: { location: {...} },\n   *   distanceUnit: 'miles',\n   *   distanceStep: 5  // 5km steps, displayed as miles\n   * });\n   * ```\n   */\n  distanceStep?: number;\n}\n\n/**\n * EXIF metadata extracted from an image.\n */\nexport interface ImageExif {\n  /** Latitude from GPS EXIF data (if available) */\n  lat?: number;\n  /** Longitude from GPS EXIF data (if available) */\n  lng?: number;\n  /** Timestamp from EXIF DateTimeOriginal (if available) */\n  timestamp?: Date;\n}\n\n/**\n * Single image result from pick().\n */\nexport interface ImageResult {\n  /**\n   * File URI for the image (file:// path).\n   * Can be used to display or upload the image.\n   */\n  uri: string;\n\n  /**\n   * Web-safe path for displaying the image in a WebView.\n   * This is the Capacitor-converted URL (capacitor://localhost/_capacitor_file_/...).\n   *\n   * Use this for <img src> tags - no manual Capacitor.convertFileSrc() needed.\n   *\n   * @since 1.2.0\n   */\n  webPath?: string;\n\n  /**\n   * EXIF metadata if available.\n   * May be undefined if image has no EXIF data.\n   */\n  exif?: ImageExif;\n\n  /**\n   * How this image was filtered.\n   * - 'location': Matched location filter\n   * - 'time': Matched time filter (or fallback from location filter)\n   */\n  filteredBy: 'location' | 'time';\n}\n\n/**\n * Result from pick() method.\n */\nexport interface PickResult {\n  /**\n   * Array of selected images.\n   * Empty if user cancelled or no images matched filters.\n   */\n  images: ImageResult[];\n\n  /**\n   * True if user explicitly cancelled the selection.\n   * False if user confirmed selection (even if no images selected).\n   */\n  cancelled: boolean;\n}\n\n/**\n * Main plugin interface.\n *\n * @example\n * ```typescript\n * import { ExifGallery } from '@kesbyte/capacitor-exif-gallery';\n *\n * // Initialize plugin (once at app startup)\n * await ExifGallery.initialize({\n *   locale: 'de',\n *   customTexts: {\n *     galleryTitle: 'Wähle Fotos'\n *   }\n * });\n *\n * // Open gallery with filter\n * const result = await ExifGallery.pick({\n *   filter: {\n *     location: {\n *       polyline: gpsTrack,  // LatLng[]\n *       radius: 1000\n *     }\n *   },\n *   fallbackThreshold: 5\n * });\n *\n * if (!result.cancelled) {\n *   console.log(`Selected ${result.images.length} images`);\n *   result.images.forEach(img => {\n *     console.log(`Image: ${img.uri}, filtered by: ${img.filteredBy}`);\n *   });\n * }\n * ```\n */\nexport interface ExifGalleryPlugin {\n  /**\n   * Initialize the plugin with optional configuration.\n   *\n   * Must be called before pick(). Can be called multiple times to update configuration.\n   *\n   * **Default behavior (no config):**\n   * - Detects system language automatically\n   * - Uses built-in English/German/French/Spanish translations\n   * - Requests permissions just-in-time (when pick() is called)\n   *\n   * @param config - Optional configuration object\n   * @returns Promise that resolves when initialization is complete\n   *\n   * @throws {Error} If locale is invalid or customTexts contain unknown keys\n   *\n   * @example\n   * ```typescript\n   * // Minimal - use defaults\n   * await ExifGallery.initialize();\n   *\n   * // With locale\n   * await ExifGallery.initialize({ locale: 'de' });\n   *\n   * // With custom text overrides\n   * await ExifGallery.initialize({\n   *   customTexts: {\n   *     galleryTitle: 'Choose Photos',\n   *     confirmButton: 'Done'\n   *   }\n   * });\n   *\n   * // Request permissions upfront\n   * await ExifGallery.initialize({\n   *   requestPermissionsUpfront: true\n   * });\n   * ```\n   */\n  initialize(config?: InitConfig): Promise<void>;\n\n  /**\n   * Open native gallery with optional filters and return selected images.\n   *\n   * Must call initialize() first, otherwise throws initialization_required error.\n   *\n   * **Filter behavior:**\n   * - If filter provided: Gallery opens with pre-configured filters\n   * - If no filter: User can manually set filters in gallery UI\n   * - Auto-fallback: If location filter returns < fallbackThreshold images, falls back to time filter\n   *\n   * @param options - Optional pick options with filters\n   * @returns Promise with selected images or cancellation status\n   *\n   * @throws {Error} 'initialization_required' if initialize() not called\n   * @throws {Error} 'no_permission' if required permissions denied\n   * @throws {Error} 'filter_error' if filter parameters are invalid\n   *\n   * @example\n   * ```typescript\n   * // No filter - user sets filters manually\n   * const result = await ExifGallery.pick();\n   *\n   * // Location filter with polyline\n   * const result = await ExifGallery.pick({\n   *   filter: {\n   *     location: {\n   *       polyline: [{lat: 48.1, lng: 11.5}, {lat: 48.2, lng: 11.6}],\n   *       radius: 1000\n   *     }\n   *   }\n   * });\n   *\n   * // Time range filter\n   * const result = await ExifGallery.pick({\n   *   filter: {\n   *     timeRange: {\n   *       start: new Date('2024-01-01'),\n   *       end: new Date('2024-01-31')\n   *     }\n   *   }\n   * });\n   *\n   * // Combined filters\n   * const result = await ExifGallery.pick({\n   *   filter: {\n   *     location: { coordinates: [{lat: 48.1, lng: 11.5}], radius: 500 },\n   *     timeRange: { start: new Date('2024-01-01'), end: new Date() }\n   *   },\n   *   fallbackThreshold: 10,\n   *   allowManualAdjustment: false\n   * });\n   *\n   * // Handle result\n   * if (!result.cancelled) {\n   *   console.log(`Selected ${result.images.length} images`);\n   *   for (const img of result.images) {\n   *     console.log(`${img.uri} - filtered by ${img.filteredBy}`);\n   *     if (img.exif) {\n   *       console.log(`  GPS: ${img.exif.lat}, ${img.exif.lng}`);\n   *       console.log(`  Time: ${img.exif.timestamp}`);\n   *     }\n   *   }\n   * }\n   * ```\n   */\n  pick(options?: PickOptions): Promise<PickResult>;\n}\n"]}