@kesbyte/capacitor-exif-gallery 1.0.0

package/dist/esm/PolylineDecoder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"PolylineDecoder.js","sourceRoot":"","sources":["../../src/PolylineDecoder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,QAAQ,MAAM,kBAAkB,CAAC;AAI7C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAC1B;;OAEG;IACH,MAAM,CAAC,MAAM,CAAC,OAAe;QAC3B,IAAI,CAAC;YACH,gEAAgE;YAChE,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAEzC,4BAA4B;YAC5B,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,8BAA8B,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACjE,CAAC;IACH,CAAC;CACF","sourcesContent":["import * as polyline from '@mapbox/polyline';\n\nimport type { LatLng } from './definitions';\n\n/**\n * Decodes Google's Encoded Polyline format to coordinate array.\n *\n * Algorithm: https://developers.google.com/maps/documentation/utilities/polylinealgorithm\n *\n * Precision: Uses precision 5 (Google Maps default, ±1 meter accuracy).\n * Higher precision polylines (precision 6+) are also supported automatically.\n *\n * @param encoded - Encoded polyline string (e.g., \"_p~iF~ps|U_ulLnnqC\")\n * @returns Array of LatLng coordinates\n * @throws Error if encoded string is malformed or exceeds limits\n *\n * @example\n * const coords = PolylineDecoder.decode(\"_p~iF~ps|U_ulLnnqC\");\n * // Returns: [{ lat: 38.5, lng: -120.2 }, { lat: 40.7, lng: -120.95 }, ...]\n */\nexport class PolylineDecoder {\n  /**\n   * Decodes an encoded polyline string to LatLng coordinate array.\n   */\n  static decode(encoded: string): LatLng[] {\n    try {\n      // polyline package returns array of [lat, lng] coordinate pairs\n      const decoded = polyline.decode(encoded);\n\n      // Convert to LatLng objects\n      return decoded.map(([lat, lng]) => ({ lat, lng }));\n    } catch (error: any) {\n      throw new Error(`Failed to decode polyline: ${error.message}`);\n    }\n  }\n}\n"]}

package/dist/esm/TranslationLoader.d.ts

@@ -0,0 +1,140 @@
+import type { SupportedLocale, TranslationSet } from './definitions';
+/**
+ * Translation loader utility for language detection and merging.
+ *
+ * Handles:
+ * - System language detection via navigator.language
+ * - Default translation loading
+ * - Custom translation merging
+ * - Validation of locale and custom keys
+ *
+ * @internal
+ */
+export declare class TranslationLoader {
+    /**
+     * All required keys in a valid TranslationSet.
+     * Used for validation of custom overrides.
+     */
+    private static readonly REQUIRED_KEYS;
+    /**
+     * Default translations by locale.
+     */
+    private static readonly DEFAULT_TRANSLATIONS;
+    /**
+     * Detect system language from navigator.language.
+     *
+     * Logic:
+     * 1. Get navigator.language (e.g., 'de-DE', 'fr-FR', 'en-US')
+     * 2. Extract language code (first 2 chars: 'de', 'fr', 'en')
+     * 3. Check if supported ('en' | 'de' | 'fr' | 'es')
+     * 4. Fallback to 'en' if not supported
+     *
+     * @returns Detected SupportedLocale, fallback to 'en'
+     *
+     * @example
+     * ```typescript
+     * // navigator.language = 'de-DE'
+     * detectSystemLanguage(); // 'de'
+     *
+     * // navigator.language = 'ja-JP' (not supported)
+     * detectSystemLanguage(); // 'en' (fallback)
+     * ```
+     */
+    static detectSystemLanguage(): Promise<SupportedLocale>;
+    /**
+     * Load default translations for a given locale.
+     *
+     * @param locale - The locale to load translations for
+     * @returns TranslationSet with all 18 keys
+     *
+     * @example
+     * ```typescript
+     * const translations = TranslationLoader.loadDefaults('de');
+     * console.log(translations.galleryTitle); // 'Bilder auswählen'
+     * ```
+     */
+    static loadDefaults(locale: SupportedLocale): TranslationSet;
+    /**
+     * Validate that a locale is supported.
+     *
+     * @param locale - The locale to validate
+     * @throws {Error} If locale is not a SupportedLocale
+     *
+     * @example
+     * ```typescript
+     * TranslationLoader.validateLocale('en'); // OK
+     * TranslationLoader.validateLocale('ja'); // Error: Invalid locale 'ja'
+     * ```
+     */
+    static validateLocale(locale: string): asserts locale is SupportedLocale;
+    /**
+     * Validate that custom text keys match TranslationSet keys.
+     *
+     * @param customTexts - Partial custom overrides
+     * @throws {Error} If any key in customTexts is not a valid TranslationSet key
+     *
+     * @example
+     * ```typescript
+     * TranslationLoader.validateCustomTexts({ galleryTitle: 'Custom' }); // OK
+     * TranslationLoader.validateCustomTexts({ invalidKey: 'X' }); // Error
+     * ```
+     */
+    static validateCustomTexts(customTexts: Partial<TranslationSet>): void;
+    /**
+     * Merge custom overrides on top of default translations.
+     *
+     * Creates a defensive copy to prevent mutation.
+     *
+     * @param defaults - Default TranslationSet
+     * @param customTexts - Partial custom overrides
+     * @returns Merged TranslationSet with all 18 keys
+     *
+     * @example
+     * ```typescript
+     * const defaults = TranslationLoader.loadDefaults('en');
+     * const merged = TranslationLoader.merge(defaults, {
+     *   galleryTitle: 'My Custom Title',
+     * });
+     * console.log(merged.galleryTitle); // 'My Custom Title'
+     * console.log(merged.selectButton); // 'Select' (from defaults)
+     * ```
+     */
+    static merge(defaults: TranslationSet, customTexts?: Partial<TranslationSet>): TranslationSet;
+    /**
+     * Load and merge translations based on configuration.
+     *
+     * This is the main entry point for translation loading.
+     *
+     * Logic:
+     * 1. If locale provided: validate and use it
+     * 2. Else: detect system language (fallback to 'en')
+     * 3. Load default translations for locale
+     * 4. If customTexts provided: validate and merge
+     * 5. Return merged TranslationSet
+     *
+     * @param locale - Optional explicit locale ('en' | 'de' | 'fr' | 'es')
+     * @param customTexts - Optional custom text overrides
+     * @returns Merged TranslationSet with all 18 keys
+     * @throws {Error} If locale is invalid or customTexts has invalid keys
+     *
+     * @example
+     * ```typescript
+     * // System language detection
+     * const t1 = TranslationLoader.loadTranslations();
+     *
+     * // Explicit locale
+     * const t2 = TranslationLoader.loadTranslations('de');
+     *
+     * // Explicit locale + custom overrides
+     * const t3 = TranslationLoader.loadTranslations('en', {
+     *   galleryTitle: 'Pick Photos',
+     * });
+     *
+     * // System language + custom overrides
+     * const t4 = TranslationLoader.loadTranslations(undefined, {
+     *   confirmButton: 'Done',
+     * });
+     * ```
+     */
+    static loadTranslations(locale?: SupportedLocale, customTexts?: Partial<TranslationSet>): Promise<TranslationSet>;
+}

package/dist/esm/TranslationLoader.js

@@ -0,0 +1,218 @@
+import { Device } from '@capacitor/device';
+// Import translation files
+import deTranslations from './translations/de.json';
+import enTranslations from './translations/en.json';
+import esTranslations from './translations/es.json';
+import frTranslations from './translations/fr.json';
+/**
+ * Translation loader utility for language detection and merging.
+ *
+ * Handles:
+ * - System language detection via navigator.language
+ * - Default translation loading
+ * - Custom translation merging
+ * - Validation of locale and custom keys
+ *
+ * @internal
+ */
+export class TranslationLoader {
+    /**
+     * Detect system language from navigator.language.
+     *
+     * Logic:
+     * 1. Get navigator.language (e.g., 'de-DE', 'fr-FR', 'en-US')
+     * 2. Extract language code (first 2 chars: 'de', 'fr', 'en')
+     * 3. Check if supported ('en' | 'de' | 'fr' | 'es')
+     * 4. Fallback to 'en' if not supported
+     *
+     * @returns Detected SupportedLocale, fallback to 'en'
+     *
+     * @example
+     * ```typescript
+     * // navigator.language = 'de-DE'
+     * detectSystemLanguage(); // 'de'
+     *
+     * // navigator.language = 'ja-JP' (not supported)
+     * detectSystemLanguage(); // 'en' (fallback)
+     * ```
+     */
+    static async detectSystemLanguage() {
+        try {
+            const deviceInfo = await Device.getLanguageCode();
+            const langCode = deviceInfo.value.split('-')[0].toLowerCase();
+            const supportedLocales = ['en', 'de', 'fr', 'es'];
+            if (supportedLocales.includes(langCode)) {
+                return langCode;
+            }
+        }
+        catch (error) {
+            console.warn('[TranslationLoader] Failed to detect device language, falling back to English:', error);
+        }
+        return 'en'; // Fallback to English
+    }
+    /**
+     * Load default translations for a given locale.
+     *
+     * @param locale - The locale to load translations for
+     * @returns TranslationSet with all 18 keys
+     *
+     * @example
+     * ```typescript
+     * const translations = TranslationLoader.loadDefaults('de');
+     * console.log(translations.galleryTitle); // 'Bilder auswählen'
+     * ```
+     */
+    static loadDefaults(locale) {
+        return Object.assign({}, this.DEFAULT_TRANSLATIONS[locale]);
+    }
+    /**
+     * Validate that a locale is supported.
+     *
+     * @param locale - The locale to validate
+     * @throws {Error} If locale is not a SupportedLocale
+     *
+     * @example
+     * ```typescript
+     * TranslationLoader.validateLocale('en'); // OK
+     * TranslationLoader.validateLocale('ja'); // Error: Invalid locale 'ja'
+     * ```
+     */
+    static validateLocale(locale) {
+        const supportedLocales = ['en', 'de', 'fr', 'es'];
+        if (!supportedLocales.includes(locale)) {
+            throw new Error(`Invalid locale '${locale}'. Supported locales: ${supportedLocales.join(', ')}`);
+        }
+    }
+    /**
+     * Validate that custom text keys match TranslationSet keys.
+     *
+     * @param customTexts - Partial custom overrides
+     * @throws {Error} If any key in customTexts is not a valid TranslationSet key
+     *
+     * @example
+     * ```typescript
+     * TranslationLoader.validateCustomTexts({ galleryTitle: 'Custom' }); // OK
+     * TranslationLoader.validateCustomTexts({ invalidKey: 'X' }); // Error
+     * ```
+     */
+    static validateCustomTexts(customTexts) {
+        const invalidKeys = Object.keys(customTexts).filter((key) => !this.REQUIRED_KEYS.includes(key));
+        if (invalidKeys.length > 0) {
+            throw new Error(`Invalid customTexts keys: ${invalidKeys.join(', ')}. ` + `Valid keys: ${this.REQUIRED_KEYS.join(', ')}`);
+        }
+    }
+    /**
+     * Merge custom overrides on top of default translations.
+     *
+     * Creates a defensive copy to prevent mutation.
+     *
+     * @param defaults - Default TranslationSet
+     * @param customTexts - Partial custom overrides
+     * @returns Merged TranslationSet with all 18 keys
+     *
+     * @example
+     * ```typescript
+     * const defaults = TranslationLoader.loadDefaults('en');
+     * const merged = TranslationLoader.merge(defaults, {
+     *   galleryTitle: 'My Custom Title',
+     * });
+     * console.log(merged.galleryTitle); // 'My Custom Title'
+     * console.log(merged.selectButton); // 'Select' (from defaults)
+     * ```
+     */
+    static merge(defaults, customTexts) {
+        if (!customTexts) {
+            return Object.assign({}, defaults);
+        }
+        return Object.assign(Object.assign({}, defaults), customTexts);
+    }
+    /**
+     * Load and merge translations based on configuration.
+     *
+     * This is the main entry point for translation loading.
+     *
+     * Logic:
+     * 1. If locale provided: validate and use it
+     * 2. Else: detect system language (fallback to 'en')
+     * 3. Load default translations for locale
+     * 4. If customTexts provided: validate and merge
+     * 5. Return merged TranslationSet
+     *
+     * @param locale - Optional explicit locale ('en' | 'de' | 'fr' | 'es')
+     * @param customTexts - Optional custom text overrides
+     * @returns Merged TranslationSet with all 18 keys
+     * @throws {Error} If locale is invalid or customTexts has invalid keys
+     *
+     * @example
+     * ```typescript
+     * // System language detection
+     * const t1 = TranslationLoader.loadTranslations();
+     *
+     * // Explicit locale
+     * const t2 = TranslationLoader.loadTranslations('de');
+     *
+     * // Explicit locale + custom overrides
+     * const t3 = TranslationLoader.loadTranslations('en', {
+     *   galleryTitle: 'Pick Photos',
+     * });
+     *
+     * // System language + custom overrides
+     * const t4 = TranslationLoader.loadTranslations(undefined, {
+     *   confirmButton: 'Done',
+     * });
+     * ```
+     */
+    static async loadTranslations(locale, customTexts) {
+        // Determine locale to use
+        let targetLocale;
+        if (locale !== undefined) {
+            this.validateLocale(locale);
+            targetLocale = locale;
+        }
+        else {
+            targetLocale = await this.detectSystemLanguage();
+        }
+        // Load default translations
+        const defaults = this.loadDefaults(targetLocale);
+        // Validate and merge custom overrides
+        if (customTexts !== undefined) {
+            this.validateCustomTexts(customTexts);
+            return this.merge(defaults, customTexts);
+        }
+        return defaults;
+    }
+}
+/**
+ * All required keys in a valid TranslationSet.
+ * Used for validation of custom overrides.
+ */
+TranslationLoader.REQUIRED_KEYS = [
+    'galleryTitle',
+    'selectButton',
+    'cancelButton',
+    'selectAllButton',
+    'deselectAllButton',
+    'selectionCounter',
+    'confirmButton',
+    'filterDialogTitle',
+    'radiusLabel',
+    'startDateLabel',
+    'endDateLabel',
+    'loadingMessage',
+    'emptyMessage',
+    'errorMessage',
+    'retryButton',
+    'initializationError',
+    'permissionError',
+    'filterError',
+];
+/**
+ * Default translations by locale.
+ */
+TranslationLoader.DEFAULT_TRANSLATIONS = {
+    en: enTranslations,
+    de: deTranslations,
+    fr: frTranslations,
+    es: esTranslations,
+};
+//# sourceMappingURL=TranslationLoader.js.map

package/dist/esm/TranslationLoader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TranslationLoader.js","sourceRoot":"","sources":["../../src/TranslationLoader.ts"],"names":[],"mappings":"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","sourcesContent":["import { Device } from '@capacitor/device';\n\nimport type { SupportedLocale, TranslationSet } from './definitions';\n// Import translation files\nimport deTranslations from './translations/de.json';\nimport enTranslations from './translations/en.json';\nimport esTranslations from './translations/es.json';\nimport frTranslations from './translations/fr.json';\n\n/**\n * Translation loader utility for language detection and merging.\n *\n * Handles:\n * - System language detection via navigator.language\n * - Default translation loading\n * - Custom translation merging\n * - Validation of locale and custom keys\n *\n * @internal\n */\nexport class TranslationLoader {\n  /**\n   * All required keys in a valid TranslationSet.\n   * Used for validation of custom overrides.\n   */\n  private static readonly REQUIRED_KEYS: (keyof TranslationSet)[] = [\n    'galleryTitle',\n    'selectButton',\n    'cancelButton',\n    'selectAllButton',\n    'deselectAllButton',\n    'selectionCounter',\n    'confirmButton',\n    'filterDialogTitle',\n    'radiusLabel',\n    'startDateLabel',\n    'endDateLabel',\n    'loadingMessage',\n    'emptyMessage',\n    'errorMessage',\n    'retryButton',\n    'initializationError',\n    'permissionError',\n    'filterError',\n  ];\n\n  /**\n   * Default translations by locale.\n   */\n  private static readonly DEFAULT_TRANSLATIONS: Record<SupportedLocale, TranslationSet> = {\n    en: enTranslations as TranslationSet,\n    de: deTranslations as TranslationSet,\n    fr: frTranslations as TranslationSet,\n    es: esTranslations as TranslationSet,\n  };\n\n  /**\n   * Detect system language from navigator.language.\n   *\n   * Logic:\n   * 1. Get navigator.language (e.g., 'de-DE', 'fr-FR', 'en-US')\n   * 2. Extract language code (first 2 chars: 'de', 'fr', 'en')\n   * 3. Check if supported ('en' | 'de' | 'fr' | 'es')\n   * 4. Fallback to 'en' if not supported\n   *\n   * @returns Detected SupportedLocale, fallback to 'en'\n   *\n   * @example\n   * ```typescript\n   * // navigator.language = 'de-DE'\n   * detectSystemLanguage(); // 'de'\n   *\n   * // navigator.language = 'ja-JP' (not supported)\n   * detectSystemLanguage(); // 'en' (fallback)\n   * ```\n   */\n  public static async detectSystemLanguage(): Promise<SupportedLocale> {\n    try {\n      const deviceInfo = await Device.getLanguageCode();\n      const langCode = deviceInfo.value.split('-')[0].toLowerCase();\n\n      const supportedLocales: SupportedLocale[] = ['en', 'de', 'fr', 'es'];\n      if (supportedLocales.includes(langCode as SupportedLocale)) {\n        return langCode as SupportedLocale;\n      }\n    } catch (error) {\n      console.warn('[TranslationLoader] Failed to detect device language, falling back to English:', error);\n    }\n\n    return 'en'; // Fallback to English\n  }\n\n  /**\n   * Load default translations for a given locale.\n   *\n   * @param locale - The locale to load translations for\n   * @returns TranslationSet with all 18 keys\n   *\n   * @example\n   * ```typescript\n   * const translations = TranslationLoader.loadDefaults('de');\n   * console.log(translations.galleryTitle); // 'Bilder auswählen'\n   * ```\n   */\n  public static loadDefaults(locale: SupportedLocale): TranslationSet {\n    return { ...this.DEFAULT_TRANSLATIONS[locale] };\n  }\n\n  /**\n   * Validate that a locale is supported.\n   *\n   * @param locale - The locale to validate\n   * @throws {Error} If locale is not a SupportedLocale\n   *\n   * @example\n   * ```typescript\n   * TranslationLoader.validateLocale('en'); // OK\n   * TranslationLoader.validateLocale('ja'); // Error: Invalid locale 'ja'\n   * ```\n   */\n  public static validateLocale(locale: string): asserts locale is SupportedLocale {\n    const supportedLocales: readonly string[] = ['en', 'de', 'fr', 'es'];\n    if (!supportedLocales.includes(locale)) {\n      throw new Error(`Invalid locale '${locale}'. Supported locales: ${supportedLocales.join(', ')}`);\n    }\n  }\n\n  /**\n   * Validate that custom text keys match TranslationSet keys.\n   *\n   * @param customTexts - Partial custom overrides\n   * @throws {Error} If any key in customTexts is not a valid TranslationSet key\n   *\n   * @example\n   * ```typescript\n   * TranslationLoader.validateCustomTexts({ galleryTitle: 'Custom' }); // OK\n   * TranslationLoader.validateCustomTexts({ invalidKey: 'X' }); // Error\n   * ```\n   */\n  public static validateCustomTexts(customTexts: Partial<TranslationSet>): void {\n    const invalidKeys = Object.keys(customTexts).filter(\n      (key) => !this.REQUIRED_KEYS.includes(key as keyof TranslationSet),\n    );\n\n    if (invalidKeys.length > 0) {\n      throw new Error(\n        `Invalid customTexts keys: ${invalidKeys.join(', ')}. ` + `Valid keys: ${this.REQUIRED_KEYS.join(', ')}`,\n      );\n    }\n  }\n\n  /**\n   * Merge custom overrides on top of default translations.\n   *\n   * Creates a defensive copy to prevent mutation.\n   *\n   * @param defaults - Default TranslationSet\n   * @param customTexts - Partial custom overrides\n   * @returns Merged TranslationSet with all 18 keys\n   *\n   * @example\n   * ```typescript\n   * const defaults = TranslationLoader.loadDefaults('en');\n   * const merged = TranslationLoader.merge(defaults, {\n   *   galleryTitle: 'My Custom Title',\n   * });\n   * console.log(merged.galleryTitle); // 'My Custom Title'\n   * console.log(merged.selectButton); // 'Select' (from defaults)\n   * ```\n   */\n  public static merge(defaults: TranslationSet, customTexts?: Partial<TranslationSet>): TranslationSet {\n    if (!customTexts) {\n      return { ...defaults };\n    }\n\n    return {\n      ...defaults,\n      ...customTexts,\n    };\n  }\n\n  /**\n   * Load and merge translations based on configuration.\n   *\n   * This is the main entry point for translation loading.\n   *\n   * Logic:\n   * 1. If locale provided: validate and use it\n   * 2. Else: detect system language (fallback to 'en')\n   * 3. Load default translations for locale\n   * 4. If customTexts provided: validate and merge\n   * 5. Return merged TranslationSet\n   *\n   * @param locale - Optional explicit locale ('en' | 'de' | 'fr' | 'es')\n   * @param customTexts - Optional custom text overrides\n   * @returns Merged TranslationSet with all 18 keys\n   * @throws {Error} If locale is invalid or customTexts has invalid keys\n   *\n   * @example\n   * ```typescript\n   * // System language detection\n   * const t1 = TranslationLoader.loadTranslations();\n   *\n   * // Explicit locale\n   * const t2 = TranslationLoader.loadTranslations('de');\n   *\n   * // Explicit locale + custom overrides\n   * const t3 = TranslationLoader.loadTranslations('en', {\n   *   galleryTitle: 'Pick Photos',\n   * });\n   *\n   * // System language + custom overrides\n   * const t4 = TranslationLoader.loadTranslations(undefined, {\n   *   confirmButton: 'Done',\n   * });\n   * ```\n   */\n  public static async loadTranslations(\n    locale?: SupportedLocale,\n    customTexts?: Partial<TranslationSet>,\n  ): Promise<TranslationSet> {\n    // Determine locale to use\n    let targetLocale: SupportedLocale;\n    if (locale !== undefined) {\n      this.validateLocale(locale);\n      targetLocale = locale;\n    } else {\n      targetLocale = await this.detectSystemLanguage();\n    }\n\n    // Load default translations\n    const defaults = this.loadDefaults(targetLocale);\n\n    // Validate and merge custom overrides\n    if (customTexts !== undefined) {\n      this.validateCustomTexts(customTexts);\n      return this.merge(defaults, customTexts);\n    }\n\n    return defaults;\n  }\n}\n"]}