@kesbyte/capacitor-exif-gallery 1.0.0

package/dist/esm/ExifGalleryImpl.d.ts

@@ -0,0 +1,176 @@
+import type { ExifGalleryPlugin, InitConfig, PickOptions, PickResult } from './definitions';
+/**
+ * TypeScript implementation of ExifGalleryPlugin.
+ *
+ * Handles:
+ * - Translation loading and merging
+ * - Plugin state management
+ * - Validation
+ * - Native bridge communication
+ *
+ * @internal
+ */
+export declare class ExifGalleryImpl implements ExifGalleryPlugin {
+    /**
+     * Native plugin instance for Capacitor Bridge communication.
+     * @private
+     */
+    private nativePlugin;
+    /**
+     * Create ExifGalleryImpl instance with native bridge dependency.
+     *
+     * @param nativePlugin - Native plugin instance from Capacitor Bridge
+     */
+    constructor(nativePlugin: ExifGalleryPlugin);
+    /**
+     * Initialize the plugin with optional configuration.
+     *
+     * This method performs the following steps:
+     * 1. Language Detection: Detects system language via navigator.language
+     *    (e.g., 'de-DE' → 'de'), or uses explicit config.locale
+     * 2. Default Loading: Loads appropriate translation file (en.json, de.json, fr.json, es.json)
+     * 3. Fallback: Falls back to English if system language is not supported
+     * 4. Merging: Merges config.customTexts on top of default translations
+     * 5. Validation: Validates locale and customTexts keys
+     * 6. Native Bridge: Passes translations and permissions to native layers
+     * 7. State Update: Stores merged translations in PluginState singleton (only after native success)
+     *
+     * All InitConfig properties are optional:
+     * - locale?: 'en' | 'de' | 'fr' | 'es' - Explicit language override
+     * - customTexts?: Partial<TranslationSet> - Custom text overrides
+     * - requestPermissionsUpfront?: boolean - Request Photo Library permissions immediately
+     *
+     * Permission Behavior:
+     * - If requestPermissionsUpfront is true, native layers request Photo Library access
+     * - The promise resolves regardless of whether permission was granted or denied
+     * - If permission is denied, pick() will request it again when called
+     * - Location permissions are NEVER requested upfront (only when filter uses location)
+     * - Check logs for permission grant/deny status on Android
+     *
+     * Placeholder Syntax:
+     * - {count}: Current selection count (e.g., "3")
+     * - {total}: Total available items (e.g., "24")
+     * - Example: "{count} of {total} selected" → "3 of 24 selected"
+     *
+     * @param config - Optional initialization configuration
+     * @returns Promise that resolves when initialization is complete
+     * @throws {Error} If locale is invalid (not 'en' | 'de' | 'fr' | 'es')
+     * @throws {Error} If customTexts contains invalid keys
+     * @throws {Error} If native initialization fails
+     *
+     * @example
+     * ```typescript
+     * // System language detection (navigator.language)
+     * await ExifGallery.initialize();
+     *
+     * // Explicit locale
+     * await ExifGallery.initialize({ locale: 'de' });
+     *
+     * // Custom text overrides with system language detection
+     * await ExifGallery.initialize({
+     *   customTexts: {
+     *     galleryTitle: 'Pick Your Photos',
+     *     confirmButton: 'Done',
+     *   },
+     * });
+     *
+     * // Explicit locale + custom overrides
+     * await ExifGallery.initialize({
+     *   locale: 'en',
+     *   customTexts: {
+     *     galleryTitle: 'Choose Images',
+     *   },
+     * });
+     *
+     * // Request permissions upfront
+     * await ExifGallery.initialize({
+     *   requestPermissionsUpfront: true,
+     * });
+     * ```
+     */
+    initialize(config?: InitConfig): Promise<void>;
+    /**
+     * Open native gallery with optional filter configuration.
+     *
+     * This method performs the following steps:
+     * 1. Initialization Check: Verifies initialize() was called
+     * 2. Concurrent Check: Prevents opening multiple pickers simultaneously
+     * 3. Filter Validation: Validates all filter parameters
+     * 4. Default Values: Applies defaults for fallbackThreshold and allowManualAdjustment
+     * 5. Native Bridge: Calls native layer with filter configuration
+     * 6. Result Handling: Returns PickResult with selected images
+     *
+     * Filter Options:
+     * - filter.location.polyline: Array of LatLng defining a path (min 2 points)
+     * - filter.location.coordinates: Array of LatLng for specific locations
+     * - filter.location.radius: Search radius in meters (default: 100, must be > 0)
+     * - filter.timeRange.start: Start date/time (must be before end)
+     * - filter.timeRange.end: End date/time (must be after start)
+     * - fallbackThreshold: Minimum images to show filter UI (default: 5)
+     * - allowManualAdjustment: Allow user to adjust filters (default: true)
+     *
+     * @param options - Optional picker configuration
+     * @returns Promise<PickResult> with selected images array and cancelled flag
+     * @throws {Error} 'initialization_required' if initialize() not called
+     * @throws {Error} 'picker_in_progress' if picker is already open
+     * @throws {Error} 'filter_error' if filter parameters are invalid
+     *
+     * @example
+     * ```typescript
+     * // Simple pick without filters
+     * const result = await ExifGallery.pick();
+     *
+     * // Location filter with coordinates
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       coordinates: [{ lat: 48.8566, lng: 2.3522 }], // Paris
+     *       radius: 500 // 500 meters
+     *     }
+     *   }
+     * });
+     *
+     * // Time range filter
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     timeRange: {
+     *       start: new Date('2024-01-01'),
+     *       end: new Date('2024-12-31')
+     *     }
+     *   }
+     * });
+     *
+     * // Combined filters with custom options
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       polyline: [
+     *         { lat: 48.8566, lng: 2.3522 },
+     *         { lat: 48.8606, lng: 2.3376 }
+     *       ],
+     *       radius: 200
+     *     },
+     *     timeRange: {
+     *       start: new Date('2024-06-01'),
+     *       end: new Date('2024-06-30')
+     *     }
+     *   },
+     *   fallbackThreshold: 10,
+     *   allowManualAdjustment: false
+     * });
+     * ```
+     */
+    pick(options?: PickOptions): Promise<PickResult>;
+    /**
+     * Detects if active filters are present in pick options.
+     *
+     * **Story 8.2:** Used to determine filter button visibility.
+     *
+     * Note: This is called AFTER FilterValidator.validateFilterConfig(),
+     * so encoded polyline strings have already been decoded to arrays.
+     *
+     * @param options - Pick options to check
+     * @returns true if location or time filters are present
+     */
+    private hasActiveFilters;
+}

package/dist/esm/ExifGalleryImpl.js

@@ -0,0 +1,295 @@
+import { FilterValidator } from './FilterValidator';
+import { PluginState } from './PluginState';
+import { TranslationLoader } from './TranslationLoader';
+import { InitializationRequiredError, PickerInProgressError, FilterError } from './errors';
+/**
+ * TypeScript implementation of ExifGalleryPlugin.
+ *
+ * Handles:
+ * - Translation loading and merging
+ * - Plugin state management
+ * - Validation
+ * - Native bridge communication
+ *
+ * @internal
+ */
+export class ExifGalleryImpl {
+    /**
+     * Create ExifGalleryImpl instance with native bridge dependency.
+     *
+     * @param nativePlugin - Native plugin instance from Capacitor Bridge
+     */
+    constructor(nativePlugin) {
+        this.nativePlugin = nativePlugin;
+    }
+    /**
+     * Initialize the plugin with optional configuration.
+     *
+     * This method performs the following steps:
+     * 1. Language Detection: Detects system language via navigator.language
+     *    (e.g., 'de-DE' → 'de'), or uses explicit config.locale
+     * 2. Default Loading: Loads appropriate translation file (en.json, de.json, fr.json, es.json)
+     * 3. Fallback: Falls back to English if system language is not supported
+     * 4. Merging: Merges config.customTexts on top of default translations
+     * 5. Validation: Validates locale and customTexts keys
+     * 6. Native Bridge: Passes translations and permissions to native layers
+     * 7. State Update: Stores merged translations in PluginState singleton (only after native success)
+     *
+     * All InitConfig properties are optional:
+     * - locale?: 'en' | 'de' | 'fr' | 'es' - Explicit language override
+     * - customTexts?: Partial<TranslationSet> - Custom text overrides
+     * - requestPermissionsUpfront?: boolean - Request Photo Library permissions immediately
+     *
+     * Permission Behavior:
+     * - If requestPermissionsUpfront is true, native layers request Photo Library access
+     * - The promise resolves regardless of whether permission was granted or denied
+     * - If permission is denied, pick() will request it again when called
+     * - Location permissions are NEVER requested upfront (only when filter uses location)
+     * - Check logs for permission grant/deny status on Android
+     *
+     * Placeholder Syntax:
+     * - {count}: Current selection count (e.g., "3")
+     * - {total}: Total available items (e.g., "24")
+     * - Example: "{count} of {total} selected" → "3 of 24 selected"
+     *
+     * @param config - Optional initialization configuration
+     * @returns Promise that resolves when initialization is complete
+     * @throws {Error} If locale is invalid (not 'en' | 'de' | 'fr' | 'es')
+     * @throws {Error} If customTexts contains invalid keys
+     * @throws {Error} If native initialization fails
+     *
+     * @example
+     * ```typescript
+     * // System language detection (navigator.language)
+     * await ExifGallery.initialize();
+     *
+     * // Explicit locale
+     * await ExifGallery.initialize({ locale: 'de' });
+     *
+     * // Custom text overrides with system language detection
+     * await ExifGallery.initialize({
+     *   customTexts: {
+     *     galleryTitle: 'Pick Your Photos',
+     *     confirmButton: 'Done',
+     *   },
+     * });
+     *
+     * // Explicit locale + custom overrides
+     * await ExifGallery.initialize({
+     *   locale: 'en',
+     *   customTexts: {
+     *     galleryTitle: 'Choose Images',
+     *   },
+     * });
+     *
+     * // Request permissions upfront
+     * await ExifGallery.initialize({
+     *   requestPermissionsUpfront: true,
+     * });
+     * ```
+     */
+    async initialize(config) {
+        var _a;
+        const state = PluginState.getInstance();
+        // Load and merge translations (async: detects device language)
+        const mergedTranslations = await TranslationLoader.loadTranslations(config === null || config === void 0 ? void 0 : config.locale, config === null || config === void 0 ? void 0 : config.customTexts);
+        const requestPermissionsUpfront = (_a = config === null || config === void 0 ? void 0 : config.requestPermissionsUpfront) !== null && _a !== void 0 ? _a : false;
+        // Call native layer FIRST (before updating state)
+        // If native call fails, state remains unchanged
+        await this.nativePlugin.initialize({
+            locale: undefined, // Not needed, we pass full translations
+            customTexts: mergedTranslations, // Full merged TranslationSet
+            requestPermissionsUpfront,
+        });
+        // Only update state after native confirmation
+        state.setRequestPermissionsUpfront(requestPermissionsUpfront);
+        state.setMergedTranslations(mergedTranslations);
+        state.setInitialized(true);
+    }
+    /**
+     * Open native gallery with optional filter configuration.
+     *
+     * This method performs the following steps:
+     * 1. Initialization Check: Verifies initialize() was called
+     * 2. Concurrent Check: Prevents opening multiple pickers simultaneously
+     * 3. Filter Validation: Validates all filter parameters
+     * 4. Default Values: Applies defaults for fallbackThreshold and allowManualAdjustment
+     * 5. Native Bridge: Calls native layer with filter configuration
+     * 6. Result Handling: Returns PickResult with selected images
+     *
+     * Filter Options:
+     * - filter.location.polyline: Array of LatLng defining a path (min 2 points)
+     * - filter.location.coordinates: Array of LatLng for specific locations
+     * - filter.location.radius: Search radius in meters (default: 100, must be > 0)
+     * - filter.timeRange.start: Start date/time (must be before end)
+     * - filter.timeRange.end: End date/time (must be after start)
+     * - fallbackThreshold: Minimum images to show filter UI (default: 5)
+     * - allowManualAdjustment: Allow user to adjust filters (default: true)
+     *
+     * @param options - Optional picker configuration
+     * @returns Promise<PickResult> with selected images array and cancelled flag
+     * @throws {Error} 'initialization_required' if initialize() not called
+     * @throws {Error} 'picker_in_progress' if picker is already open
+     * @throws {Error} 'filter_error' if filter parameters are invalid
+     *
+     * @example
+     * ```typescript
+     * // Simple pick without filters
+     * const result = await ExifGallery.pick();
+     *
+     * // Location filter with coordinates
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       coordinates: [{ lat: 48.8566, lng: 2.3522 }], // Paris
+     *       radius: 500 // 500 meters
+     *     }
+     *   }
+     * });
+     *
+     * // Time range filter
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     timeRange: {
+     *       start: new Date('2024-01-01'),
+     *       end: new Date('2024-12-31')
+     *     }
+     *   }
+     * });
+     *
+     * // Combined filters with custom options
+     * const result = await ExifGallery.pick({
+     *   filter: {
+     *     location: {
+     *       polyline: [
+     *         { lat: 48.8566, lng: 2.3522 },
+     *         { lat: 48.8606, lng: 2.3376 }
+     *       ],
+     *       radius: 200
+     *     },
+     *     timeRange: {
+     *       start: new Date('2024-06-01'),
+     *       end: new Date('2024-06-30')
+     *     }
+     *   },
+     *   fallbackThreshold: 10,
+     *   allowManualAdjustment: false
+     * });
+     * ```
+     */
+    async pick(options) {
+        var _a, _b, _c, _d;
+        const state = PluginState.getInstance();
+        // 1. Verify plugin is initialized
+        if (!state.isInitialized()) {
+            throw new InitializationRequiredError();
+        }
+        // 2. Prevent concurrent picker operations (atomic check-and-set)
+        if (!state.trySetPickerInProgress()) {
+            throw new PickerInProgressError();
+        }
+        try {
+            // Picker is now marked as in progress (atomic operation above)
+            // 3. Validate filter configuration if provided
+            if (options === null || options === void 0 ? void 0 : options.filter) {
+                FilterValidator.validateFilterConfig(options.filter);
+            }
+            // 4. Apply default values and convert Date objects to timestamps
+            const pickOptions = {
+                fallbackThreshold: (_a = options === null || options === void 0 ? void 0 : options.fallbackThreshold) !== null && _a !== void 0 ? _a : 5,
+                allowManualAdjustment: (_b = options === null || options === void 0 ? void 0 : options.allowManualAdjustment) !== null && _b !== void 0 ? _b : true,
+                hasActiveFilters: this.hasActiveFilters(options), // Story 8.2: Detect active filters
+                distanceUnit: (_c = options === null || options === void 0 ? void 0 : options.distanceUnit) !== null && _c !== void 0 ? _c : 'kilometers',
+                distanceStep: (_d = options === null || options === void 0 ? void 0 : options.distanceStep) !== null && _d !== void 0 ? _d : 5,
+            };
+            // Convert filter configuration for native bridge
+            if (options === null || options === void 0 ? void 0 : options.filter) {
+                pickOptions.filter = {};
+                // Copy location filter as-is
+                if (options.filter.location) {
+                    pickOptions.filter.location = options.filter.location;
+                }
+                // Convert Date objects to timestamps (milliseconds) for native bridge
+                if (options.filter.timeRange) {
+                    pickOptions.filter.timeRange = {
+                        start: options.filter.timeRange.start.getTime(),
+                        end: options.filter.timeRange.end.getTime(),
+                    };
+                }
+            }
+            // Validate fallbackThreshold
+            if (pickOptions.fallbackThreshold !== undefined) {
+                if (typeof pickOptions.fallbackThreshold !== 'number' || !isFinite(pickOptions.fallbackThreshold)) {
+                    throw new FilterError('fallbackThreshold must be a finite number');
+                }
+                if (pickOptions.fallbackThreshold < 0) {
+                    throw new FilterError('fallbackThreshold must be greater than or equal to 0');
+                }
+                // Prevent unreasonably large threshold
+                if (pickOptions.fallbackThreshold > 10000) {
+                    throw new FilterError('fallbackThreshold must not exceed 10,000');
+                }
+            }
+            // Validate allowManualAdjustment
+            if (pickOptions.allowManualAdjustment !== undefined) {
+                if (typeof pickOptions.allowManualAdjustment !== 'boolean') {
+                    throw new FilterError('allowManualAdjustment must be a boolean');
+                }
+            }
+            // Validate distanceUnit
+            if (pickOptions.distanceUnit !== undefined) {
+                const validUnits = ['kilometers', 'miles'];
+                if (!validUnits.includes(pickOptions.distanceUnit)) {
+                    throw new FilterError(`distanceUnit must be one of: ${validUnits.join(', ')}`);
+                }
+            }
+            // Validate distanceStep
+            if (pickOptions.distanceStep !== undefined) {
+                if (typeof pickOptions.distanceStep !== 'number' || !isFinite(pickOptions.distanceStep)) {
+                    throw new FilterError('distanceStep must be a finite number');
+                }
+                if (pickOptions.distanceStep < 1) {
+                    throw new FilterError('distanceStep must be at least 1 km');
+                }
+                if (pickOptions.distanceStep > 25) {
+                    throw new FilterError('distanceStep must not exceed 25 km');
+                }
+            }
+            // 5. Call native layer via Capacitor Bridge
+            const result = await this.nativePlugin.pick(pickOptions);
+            return result;
+        }
+        finally {
+            // 6. Always clear picker in progress flag (success or error)
+            state.setPickerInProgress(false);
+        }
+    }
+    /**
+     * Detects if active filters are present in pick options.
+     *
+     * **Story 8.2:** Used to determine filter button visibility.
+     *
+     * Note: This is called AFTER FilterValidator.validateFilterConfig(),
+     * so encoded polyline strings have already been decoded to arrays.
+     *
+     * @param options - Pick options to check
+     * @returns true if location or time filters are present
+     */
+    hasActiveFilters(options) {
+        var _a, _b, _c, _d;
+        if (!(options === null || options === void 0 ? void 0 : options.filter))
+            return false;
+        // Check for location filter (coordinates array or polyline)
+        // Note: polyline can be string OR array, but after validation it's always an array
+        const polyline = (_a = options.filter.location) === null || _a === void 0 ? void 0 : _a.polyline;
+        const hasPolyline = Array.isArray(polyline)
+            ? polyline.length > 0
+            : typeof polyline === 'string'
+                ? polyline.trim().length > 0
+                : false;
+        const hasLocationFilter = !!(((_c = (_b = options.filter.location) === null || _b === void 0 ? void 0 : _b.coordinates) === null || _c === void 0 ? void 0 : _c.length) || hasPolyline);
+        const hasTimeFilter = !!(((_d = options.filter.timeRange) === null || _d === void 0 ? void 0 : _d.start) && options.filter.timeRange.end);
+        return hasLocationFilter || hasTimeFilter;
+    }
+}
+//# sourceMappingURL=ExifGalleryImpl.js.map

package/dist/esm/ExifGalleryImpl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExifGalleryImpl.js","sourceRoot":"","sources":["../../src/ExifGalleryImpl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAExD,OAAO,EAAE,2BAA2B,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAE3F;;;;;;;;;;GAUG;AACH,MAAM,OAAO,eAAe;IAO1B;;;;OAIG;IACH,YAAY,YAA+B;QACzC,IAAI,CAAC,YAAY,GAAG,YAAY,CAAC;IACnC,CAAC;IACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiEG;IACH,KAAK,CAAC,UAAU,CAAC,MAAmB;;QAClC,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;QAExC,+DAA+D;QAC/D,MAAM,kBAAkB,GAAG,MAAM,iBAAiB,CAAC,gBAAgB,CAAC,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,MAAM,EAAE,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,WAAW,CAAC,CAAC;QAEzG,MAAM,yBAAyB,GAAG,MAAA,MAAM,aAAN,MAAM,uBAAN,MAAM,CAAE,yBAAyB,mCAAI,KAAK,CAAC;QAE7E,kDAAkD;QAClD,gDAAgD;QAChD,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC;YACjC,MAAM,EAAE,SAAS,EAAE,wCAAwC;YAC3D,WAAW,EAAE,kBAAkB,EAAE,6BAA6B;YAC9D,yBAAyB;SAC1B,CAAC,CAAC;QAEH,8CAA8C;QAC9C,KAAK,CAAC,4BAA4B,CAAC,yBAAyB,CAAC,CAAC;QAC9D,KAAK,CAAC,qBAAqB,CAAC,kBAAkB,CAAC,CAAC;QAChD,KAAK,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsEG;IACH,KAAK,CAAC,IAAI,CAAC,OAAqB;;QAC9B,MAAM,KAAK,GAAG,WAAW,CAAC,WAAW,EAAE,CAAC;QAExC,kCAAkC;QAClC,IAAI,CAAC,KAAK,CAAC,aAAa,EAAE,EAAE,CAAC;YAC3B,MAAM,IAAI,2BAA2B,EAAE,CAAC;QAC1C,CAAC;QAED,iEAAiE;QACjE,IAAI,CAAC,KAAK,CAAC,sBAAsB,EAAE,EAAE,CAAC;YACpC,MAAM,IAAI,qBAAqB,EAAE,CAAC;QACpC,CAAC;QAED,IAAI,CAAC;YACH,+DAA+D;YAE/D,+CAA+C;YAC/C,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,EAAE,CAAC;gBACpB,eAAe,CAAC,oBAAoB,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YACvD,CAAC;YAED,iEAAiE;YACjE,MAAM,WAAW,GAAQ;gBACvB,iBAAiB,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,iBAAiB,mCAAI,CAAC;gBAClD,qBAAqB,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,qBAAqB,mCAAI,IAAI;gBAC7D,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,EAAE,mCAAmC;gBACrF,YAAY,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,YAAY,mCAAI,YAAY;gBACnD,YAAY,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,YAAY,mCAAI,CAAC;aACzC,CAAC;YAEF,iDAAiD;YACjD,IAAI,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,EAAE,CAAC;gBACpB,WAAW,CAAC,MAAM,GAAG,EAAE,CAAC;gBAExB,6BAA6B;gBAC7B,IAAI,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;oBAC5B,WAAW,CAAC,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC;gBACxD,CAAC;gBAED,sEAAsE;gBACtE,IAAI,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;oBAC7B,WAAW,CAAC,MAAM,CAAC,SAAS,GAAG;wBAC7B,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,OAAO,EAAE;wBAC/C,GAAG,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE;qBAC5C,CAAC;gBACJ,CAAC;YACH,CAAC;YAED,6BAA6B;YAC7B,IAAI,WAAW,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;gBAChD,IAAI,OAAO,WAAW,CAAC,iBAAiB,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;oBAClG,MAAM,IAAI,WAAW,CAAC,2CAA2C,CAAC,CAAC;gBACrE,CAAC;gBACD,IAAI,WAAW,CAAC,iBAAiB,GAAG,CAAC,EAAE,CAAC;oBACtC,MAAM,IAAI,WAAW,CAAC,sDAAsD,CAAC,CAAC;gBAChF,CAAC;gBACD,uCAAuC;gBACvC,IAAI,WAAW,CAAC,iBAAiB,GAAG,KAAK,EAAE,CAAC;oBAC1C,MAAM,IAAI,WAAW,CAAC,0CAA0C,CAAC,CAAC;gBACpE,CAAC;YACH,CAAC;YAED,iCAAiC;YACjC,IAAI,WAAW,CAAC,qBAAqB,KAAK,SAAS,EAAE,CAAC;gBACpD,IAAI,OAAO,WAAW,CAAC,qBAAqB,KAAK,SAAS,EAAE,CAAC;oBAC3D,MAAM,IAAI,WAAW,CAAC,yCAAyC,CAAC,CAAC;gBACnE,CAAC;YACH,CAAC;YAED,wBAAwB;YACxB,IAAI,WAAW,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC3C,MAAM,UAAU,GAAG,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;gBAC3C,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,CAAC;oBACnD,MAAM,IAAI,WAAW,CAAC,gCAAgC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACjF,CAAC;YACH,CAAC;YAED,wBAAwB;YACxB,IAAI,WAAW,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBAC3C,IAAI,OAAO,WAAW,CAAC,YAAY,KAAK,QAAQ,IAAI,CAAC,QAAQ,CAAC,WAAW,CAAC,YAAY,CAAC,EAAE,CAAC;oBACxF,MAAM,IAAI,WAAW,CAAC,sCAAsC,CAAC,CAAC;gBAChE,CAAC;gBACD,IAAI,WAAW,CAAC,YAAY,GAAG,CAAC,EAAE,CAAC;oBACjC,MAAM,IAAI,WAAW,CAAC,oCAAoC,CAAC,CAAC;gBAC9D,CAAC;gBACD,IAAI,WAAW,CAAC,YAAY,GAAG,EAAE,EAAE,CAAC;oBAClC,MAAM,IAAI,WAAW,CAAC,oCAAoC,CAAC,CAAC;gBAC9D,CAAC;YACH,CAAC;YAED,4CAA4C;YAC5C,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAEzD,OAAO,MAAM,CAAC;QAChB,CAAC;gBAAS,CAAC;YACT,6DAA6D;YAC7D,KAAK,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED;;;;;;;;;;OAUG;IACK,gBAAgB,CAAC,OAAqB;;QAC5C,IAAI,CAAC,CAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,MAAM,CAAA;YAAE,OAAO,KAAK,CAAC;QAEnC,4DAA4D;QAC5D,mFAAmF;QACnF,MAAM,QAAQ,GAAG,MAAA,OAAO,CAAC,MAAM,CAAC,QAAQ,0CAAE,QAAQ,CAAC;QACnD,MAAM,WAAW,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;YACzC,CAAC,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC;YACrB,CAAC,CAAC,OAAO,QAAQ,KAAK,QAAQ;gBAC5B,CAAC,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;gBAC5B,CAAC,CAAC,KAAK,CAAC;QAEZ,MAAM,iBAAiB,GAAG,CAAC,CAAC,CAAC,CAAA,MAAA,MAAA,OAAO,CAAC,MAAM,CAAC,QAAQ,0CAAE,WAAW,0CAAE,MAAM,KAAI,WAAW,CAAC,CAAC;QAE1F,MAAM,aAAa,GAAG,CAAC,CAAC,CAAC,CAAA,MAAA,OAAO,CAAC,MAAM,CAAC,SAAS,0CAAE,KAAK,KAAI,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAE1F,OAAO,iBAAiB,IAAI,aAAa,CAAC;IAC5C,CAAC;CACF","sourcesContent":["import { FilterValidator } from './FilterValidator';\nimport { PluginState } from './PluginState';\nimport { TranslationLoader } from './TranslationLoader';\nimport type { ExifGalleryPlugin, InitConfig, PickOptions, PickResult } from './definitions';\nimport { InitializationRequiredError, PickerInProgressError, FilterError } from './errors';\n\n/**\n * TypeScript implementation of ExifGalleryPlugin.\n *\n * Handles:\n * - Translation loading and merging\n * - Plugin state management\n * - Validation\n * - Native bridge communication\n *\n * @internal\n */\nexport class ExifGalleryImpl implements ExifGalleryPlugin {\n  /**\n   * Native plugin instance for Capacitor Bridge communication.\n   * @private\n   */\n  private nativePlugin: ExifGalleryPlugin;\n\n  /**\n   * Create ExifGalleryImpl instance with native bridge dependency.\n   *\n   * @param nativePlugin - Native plugin instance from Capacitor Bridge\n   */\n  constructor(nativePlugin: ExifGalleryPlugin) {\n    this.nativePlugin = nativePlugin;\n  }\n  /**\n   * Initialize the plugin with optional configuration.\n   *\n   * This method performs the following steps:\n   * 1. Language Detection: Detects system language via navigator.language\n   *    (e.g., 'de-DE' → 'de'), or uses explicit config.locale\n   * 2. Default Loading: Loads appropriate translation file (en.json, de.json, fr.json, es.json)\n   * 3. Fallback: Falls back to English if system language is not supported\n   * 4. Merging: Merges config.customTexts on top of default translations\n   * 5. Validation: Validates locale and customTexts keys\n   * 6. Native Bridge: Passes translations and permissions to native layers\n   * 7. State Update: Stores merged translations in PluginState singleton (only after native success)\n   *\n   * All InitConfig properties are optional:\n   * - locale?: 'en' | 'de' | 'fr' | 'es' - Explicit language override\n   * - customTexts?: Partial<TranslationSet> - Custom text overrides\n   * - requestPermissionsUpfront?: boolean - Request Photo Library permissions immediately\n   *\n   * Permission Behavior:\n   * - If requestPermissionsUpfront is true, native layers request Photo Library access\n   * - The promise resolves regardless of whether permission was granted or denied\n   * - If permission is denied, pick() will request it again when called\n   * - Location permissions are NEVER requested upfront (only when filter uses location)\n   * - Check logs for permission grant/deny status on Android\n   *\n   * Placeholder Syntax:\n   * - {count}: Current selection count (e.g., \"3\")\n   * - {total}: Total available items (e.g., \"24\")\n   * - Example: \"{count} of {total} selected\" → \"3 of 24 selected\"\n   *\n   * @param config - Optional initialization configuration\n   * @returns Promise that resolves when initialization is complete\n   * @throws {Error} If locale is invalid (not 'en' | 'de' | 'fr' | 'es')\n   * @throws {Error} If customTexts contains invalid keys\n   * @throws {Error} If native initialization fails\n   *\n   * @example\n   * ```typescript\n   * // System language detection (navigator.language)\n   * await ExifGallery.initialize();\n   *\n   * // Explicit locale\n   * await ExifGallery.initialize({ locale: 'de' });\n   *\n   * // Custom text overrides with system language detection\n   * await ExifGallery.initialize({\n   *   customTexts: {\n   *     galleryTitle: 'Pick Your Photos',\n   *     confirmButton: 'Done',\n   *   },\n   * });\n   *\n   * // Explicit locale + custom overrides\n   * await ExifGallery.initialize({\n   *   locale: 'en',\n   *   customTexts: {\n   *     galleryTitle: 'Choose Images',\n   *   },\n   * });\n   *\n   * // Request permissions upfront\n   * await ExifGallery.initialize({\n   *   requestPermissionsUpfront: true,\n   * });\n   * ```\n   */\n  async initialize(config?: InitConfig): Promise<void> {\n    const state = PluginState.getInstance();\n\n    // Load and merge translations (async: detects device language)\n    const mergedTranslations = await TranslationLoader.loadTranslations(config?.locale, config?.customTexts);\n\n    const requestPermissionsUpfront = config?.requestPermissionsUpfront ?? false;\n\n    // Call native layer FIRST (before updating state)\n    // If native call fails, state remains unchanged\n    await this.nativePlugin.initialize({\n      locale: undefined, // Not needed, we pass full translations\n      customTexts: mergedTranslations, // Full merged TranslationSet\n      requestPermissionsUpfront,\n    });\n\n    // Only update state after native confirmation\n    state.setRequestPermissionsUpfront(requestPermissionsUpfront);\n    state.setMergedTranslations(mergedTranslations);\n    state.setInitialized(true);\n  }\n\n  /**\n   * Open native gallery with optional filter configuration.\n   *\n   * This method performs the following steps:\n   * 1. Initialization Check: Verifies initialize() was called\n   * 2. Concurrent Check: Prevents opening multiple pickers simultaneously\n   * 3. Filter Validation: Validates all filter parameters\n   * 4. Default Values: Applies defaults for fallbackThreshold and allowManualAdjustment\n   * 5. Native Bridge: Calls native layer with filter configuration\n   * 6. Result Handling: Returns PickResult with selected images\n   *\n   * Filter Options:\n   * - filter.location.polyline: Array of LatLng defining a path (min 2 points)\n   * - filter.location.coordinates: Array of LatLng for specific locations\n   * - filter.location.radius: Search radius in meters (default: 100, must be > 0)\n   * - filter.timeRange.start: Start date/time (must be before end)\n   * - filter.timeRange.end: End date/time (must be after start)\n   * - fallbackThreshold: Minimum images to show filter UI (default: 5)\n   * - allowManualAdjustment: Allow user to adjust filters (default: true)\n   *\n   * @param options - Optional picker configuration\n   * @returns Promise<PickResult> with selected images array and cancelled flag\n   * @throws {Error} 'initialization_required' if initialize() not called\n   * @throws {Error} 'picker_in_progress' if picker is already open\n   * @throws {Error} 'filter_error' if filter parameters are invalid\n   *\n   * @example\n   * ```typescript\n   * // Simple pick without filters\n   * const result = await ExifGallery.pick();\n   *\n   * // Location filter with coordinates\n   * const result = await ExifGallery.pick({\n   *   filter: {\n   *     location: {\n   *       coordinates: [{ lat: 48.8566, lng: 2.3522 }], // Paris\n   *       radius: 500 // 500 meters\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-12-31')\n   *     }\n   *   }\n   * });\n   *\n   * // Combined filters with custom options\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: 200\n   *     },\n   *     timeRange: {\n   *       start: new Date('2024-06-01'),\n   *       end: new Date('2024-06-30')\n   *     }\n   *   },\n   *   fallbackThreshold: 10,\n   *   allowManualAdjustment: false\n   * });\n   * ```\n   */\n  async pick(options?: PickOptions): Promise<PickResult> {\n    const state = PluginState.getInstance();\n\n    // 1. Verify plugin is initialized\n    if (!state.isInitialized()) {\n      throw new InitializationRequiredError();\n    }\n\n    // 2. Prevent concurrent picker operations (atomic check-and-set)\n    if (!state.trySetPickerInProgress()) {\n      throw new PickerInProgressError();\n    }\n\n    try {\n      // Picker is now marked as in progress (atomic operation above)\n\n      // 3. Validate filter configuration if provided\n      if (options?.filter) {\n        FilterValidator.validateFilterConfig(options.filter);\n      }\n\n      // 4. Apply default values and convert Date objects to timestamps\n      const pickOptions: any = {\n        fallbackThreshold: options?.fallbackThreshold ?? 5,\n        allowManualAdjustment: options?.allowManualAdjustment ?? true,\n        hasActiveFilters: this.hasActiveFilters(options), // Story 8.2: Detect active filters\n        distanceUnit: options?.distanceUnit ?? 'kilometers',\n        distanceStep: options?.distanceStep ?? 5,\n      };\n\n      // Convert filter configuration for native bridge\n      if (options?.filter) {\n        pickOptions.filter = {};\n\n        // Copy location filter as-is\n        if (options.filter.location) {\n          pickOptions.filter.location = options.filter.location;\n        }\n\n        // Convert Date objects to timestamps (milliseconds) for native bridge\n        if (options.filter.timeRange) {\n          pickOptions.filter.timeRange = {\n            start: options.filter.timeRange.start.getTime(),\n            end: options.filter.timeRange.end.getTime(),\n          };\n        }\n      }\n\n      // Validate fallbackThreshold\n      if (pickOptions.fallbackThreshold !== undefined) {\n        if (typeof pickOptions.fallbackThreshold !== 'number' || !isFinite(pickOptions.fallbackThreshold)) {\n          throw new FilterError('fallbackThreshold must be a finite number');\n        }\n        if (pickOptions.fallbackThreshold < 0) {\n          throw new FilterError('fallbackThreshold must be greater than or equal to 0');\n        }\n        // Prevent unreasonably large threshold\n        if (pickOptions.fallbackThreshold > 10000) {\n          throw new FilterError('fallbackThreshold must not exceed 10,000');\n        }\n      }\n\n      // Validate allowManualAdjustment\n      if (pickOptions.allowManualAdjustment !== undefined) {\n        if (typeof pickOptions.allowManualAdjustment !== 'boolean') {\n          throw new FilterError('allowManualAdjustment must be a boolean');\n        }\n      }\n\n      // Validate distanceUnit\n      if (pickOptions.distanceUnit !== undefined) {\n        const validUnits = ['kilometers', 'miles'];\n        if (!validUnits.includes(pickOptions.distanceUnit)) {\n          throw new FilterError(`distanceUnit must be one of: ${validUnits.join(', ')}`);\n        }\n      }\n\n      // Validate distanceStep\n      if (pickOptions.distanceStep !== undefined) {\n        if (typeof pickOptions.distanceStep !== 'number' || !isFinite(pickOptions.distanceStep)) {\n          throw new FilterError('distanceStep must be a finite number');\n        }\n        if (pickOptions.distanceStep < 1) {\n          throw new FilterError('distanceStep must be at least 1 km');\n        }\n        if (pickOptions.distanceStep > 25) {\n          throw new FilterError('distanceStep must not exceed 25 km');\n        }\n      }\n\n      // 5. Call native layer via Capacitor Bridge\n      const result = await this.nativePlugin.pick(pickOptions);\n\n      return result;\n    } finally {\n      // 6. Always clear picker in progress flag (success or error)\n      state.setPickerInProgress(false);\n    }\n  }\n\n  /**\n   * Detects if active filters are present in pick options.\n   *\n   * **Story 8.2:** Used to determine filter button visibility.\n   *\n   * Note: This is called AFTER FilterValidator.validateFilterConfig(),\n   * so encoded polyline strings have already been decoded to arrays.\n   *\n   * @param options - Pick options to check\n   * @returns true if location or time filters are present\n   */\n  private hasActiveFilters(options?: PickOptions): boolean {\n    if (!options?.filter) return false;\n\n    // Check for location filter (coordinates array or polyline)\n    // Note: polyline can be string OR array, but after validation it's always an array\n    const polyline = options.filter.location?.polyline;\n    const hasPolyline = Array.isArray(polyline)\n      ? polyline.length > 0\n      : typeof polyline === 'string'\n        ? polyline.trim().length > 0\n        : false;\n\n    const hasLocationFilter = !!(options.filter.location?.coordinates?.length || hasPolyline);\n\n    const hasTimeFilter = !!(options.filter.timeRange?.start && options.filter.timeRange.end);\n\n    return hasLocationFilter || hasTimeFilter;\n  }\n}\n"]}

package/dist/esm/FilterValidator.d.ts

@@ -0,0 +1,126 @@
+import type { FilterConfig, LatLng, LocationFilter, TimeRangeFilter } from './definitions';
+/**
+ * Validation utilities for filter parameters.
+ *
+ * Ensures filter configurations are valid before passing to native layers.
+ *
+ * @internal
+ */
+export declare class FilterValidator {
+    /**
+     * Validate that an object is a valid LatLng coordinate.
+     *
+     * Valid coordinates must have:
+     * - lat: number between -90 and 90
+     * - lng: number between -180 and 180
+     *
+     * @param obj - Object to validate
+     * @returns True if valid LatLng
+     *
+     * @example
+     * ```typescript
+     * isValidLatLng({ lat: 48.8566, lng: 2.3522 }); // true
+     * isValidLatLng({ lat: 200, lng: 0 }); // false (lat out of range)
+     * isValidLatLng({ lat: 0 }); // false (missing lng)
+     * ```
+     */
+    static isValidLatLng(obj: any): obj is LatLng;
+    /**
+     * Validate location filter configuration.
+     *
+     * Valid location filter must have:
+     * - Either polyline OR coordinates array (not both)
+     * - polyline/coordinates must be non-empty array of valid LatLng
+     * - radius must be > 0 if provided
+     *
+     * ⚠️ **MUTATION WARNING:** If polyline is provided as an encoded string,
+     * it will be decoded and replaced with a LatLng[] array in-place.
+     * This is an optimization to prevent double-decoding. If you need to
+     * preserve the original filter object, pass a deep copy.
+     *
+     * @mutates locationFilter.polyline - Replaces encoded string with decoded LatLng[]
+     * @param locationFilter - Location filter to validate
+     * @throws {Error} If validation fails
+     *
+     * @example
+     * ```typescript
+     * // Valid - coordinate array
+     * validateLocationFilter({
+     *   coordinates: [{ lat: 48.8566, lng: 2.3522 }],
+     *   radius: 500
+     * });
+     *
+     * // Valid - encoded polyline (will be decoded in-place)
+     * const filter = { polyline: "_p~iF~ps|U_ulLnnqC", radius: 1000 };
+     * validateLocationFilter(filter);
+     * // Note: filter.polyline is now LatLng[] (not string)
+     *
+     * // Invalid: empty coordinates array
+     * validateLocationFilter({ coordinates: [] }); // throws
+     *
+     * // Invalid: negative radius
+     * validateLocationFilter({ coordinates: [...], radius: -1 }); // throws
+     * ```
+     */
+    static validateLocationFilter(locationFilter: LocationFilter): void;
+    /**
+     * Validate time range filter configuration.
+     *
+     * Valid time range must have:
+     * - start and end as Date objects
+     * - start must be before end
+     *
+     * @param timeRange - Time range filter to validate
+     * @throws {Error} If validation fails
+     *
+     * @example
+     * ```typescript
+     * // Valid
+     * validateTimeRangeFilter({
+     *   start: new Date('2024-01-01'),
+     *   end: new Date('2024-12-31')
+     * });
+     *
+     * // Invalid: end before start
+     * validateTimeRangeFilter({
+     *   start: new Date('2024-12-31'),
+     *   end: new Date('2024-01-01')
+     * }); // throws
+     * ```
+     */
+    static validateTimeRangeFilter(timeRange: TimeRangeFilter): void;
+    /**
+     * Validate complete filter configuration.
+     *
+     * Valid filter must have:
+     * - At least one of: location or timeRange
+     * - Valid location filter (if present)
+     * - Valid time range filter (if present)
+     *
+     * @param filter - Filter configuration to validate
+     * @throws {Error} If validation fails
+     *
+     * @example
+     * ```typescript
+     * // Valid: location only
+     * validateFilterConfig({
+     *   location: { coordinates: [{ lat: 0, lng: 0 }] }
+     * });
+     *
+     * // Valid: time only
+     * validateFilterConfig({
+     *   timeRange: { start: new Date(), end: new Date() }
+     * });
+     *
+     * // Valid: both
+     * validateFilterConfig({
+     *   location: { coordinates: [...] },
+     *   timeRange: { start: ..., end: ... }
+     * });
+     *
+     * // Invalid: neither
+     * validateFilterConfig({}); // throws
+     * ```
+     */
+    static validateFilterConfig(filter: FilterConfig): void;
+}