map-gl-offline 0.5.3 → 0.5.6

package/README.md

@@ -20,6 +20,7 @@ A comprehensive **TypeScript** library for **MapLibre GL JS** and **Mapbox GL JS
 
 - 🗺️ **Complete Offline Maps**: Download and store entire map regions with polygon-based selection
 - 🎯 **Smart Tile Management**: Efficient vector/raster tile downloading, caching, and retrieval with zoom-level optimization
+- 🧩 **Extra Tile Sources**: Save additional vector (MVT/PBF) and raster tile layers alongside the style's own sources
 - 🔤 **Font & Glyph Support**: Comprehensive font and glyph management with Unicode range support
 - 🎨 **Sprite Management**: Handle map sprites and icons offline with multi-resolution support (@1x, @2x)
 - 📊 **Real-time Analytics**: Detailed storage analytics, performance metrics, and optimization recommendations
@@ -347,9 +348,45 @@ interface OfflineRegionOptions {
   deleteOnExpiry?: boolean; // Auto-delete on expiration
   multipleRegions?: boolean; // Part of a multi-region download
   tileExtension?: string; // Tile extension (pbf, mvt, png, etc.)
+  extraSources?: ExtraSource[]; // Additional tile sources to download alongside the style
 }
+
+interface ExtraSource {
+  id: string; // Unique source identifier
+  type?: 'vector' | 'raster' | 'raster-dem'; // Defaults to 'vector'
+  tiles: string[]; // Tile URL templates with {z}/{x}/{y}
+  minzoom?: number;
+  maxzoom?: number;
+  attribution?: string;
+}
+```
+
+### Extra Tile Sources
+
+Save additional vector or raster layers (e.g. custom overlays) alongside the style's own sources:
+
+```typescript
+await manager.addRegion({
+  id: 'downtown',
+  name: 'Downtown',
+  bounds: [[-74.05, 40.71], [-74.00, 40.76]],
+  minZoom: 10,
+  maxZoom: 16,
+  styleUrl: 'https://example.com/style.json',
+  extraSources: [
+    {
+      id: 'buildings',
+      type: 'vector',
+      tiles: ['https://tiles.example.com/buildings/{z}/{x}/{y}.pbf'],
+      minzoom: 13,
+      maxzoom: 16,
+    },
+  ],
+});
 ```
 
+When using the `OfflineManagerControl`, the region download form auto-discovers tile sources on the live map and shows them as checkboxes — users pick which extra layers to include.
+
 ## 🎯 Use Cases
 
 - 🏔️ **Outdoor & Recreation Apps**: Hiking, camping, and adventure apps with offline trail maps
@@ -407,60 +444,6 @@ try {
 }
 ```
 
-### Storage Management
-
-```typescript
-// Check available storage
-if ('storage' in navigator && 'estimate' in navigator.storage) {
-  const { usage, quota } = await navigator.storage.estimate();
-  console.log(`Used: ${usage} / ${quota} bytes`);
-}
-
-// Regular cleanup
-await manager.cleanupExpiredRegions();
-
-// Auto-cleanup on startup
-await manager.setupAutoCleanup({
-  intervalHours: 24, // Daily
-  maxAge: 30, // 30 days
-});
-```
-
-## 🔍 Troubleshooting
-
-### Storage Quota Issues
-
-```typescript
-// Check quota
-const { usage, quota } = await navigator.storage.estimate();
-if (usage / quota > 0.9) {
-  await manager.cleanupExpiredRegions();
-}
-
-// Request persistent storage
-if (navigator.storage?.persist) {
-  const isPersisted = await navigator.storage.persist();
-  console.log(`Persistent storage: ${isPersisted}`);
-}
-```
-
-### Performance Issues
-
-```typescript
-// Reduce concurrency for slower devices
-const lightOptions = {
-  maxConcurrency: 2,
-  batchSize: 10,
-  timeout: 30000,
-};
-
-// Use smaller regions
-const smallerRegion = {
-  minZoom: 11, // Start at higher zoom
-  maxZoom: 15, // End at lower zoom
-};
-```
-
 ## 🌐 Browser Compatibility
 
 | Browser | Version | Support |
@@ -480,7 +463,7 @@ const smallerRegion = {
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+Contributions are welcome!
 
 ### Development Setup
 
@@ -538,44 +521,15 @@ map-gl-offline/
 
 ## 🔄 Recent Updates
 
-### v0.5.3 (Latest)
-
-- ✅ **Bundle Size**: Reduced ESM bundle from 783 KB to 565 KB (28% reduction)
-- ✅ **Turf Tree-Shaking**: Replaced `@turf/turf` monorepo with individual packages (`@turf/area`, `@turf/bbox-polygon`, `@turf/difference`, `@turf/helpers`)
-- ✅ **Externalized Dependencies**: `i18next` and `@turf/*` moved to externals
-- ✅ **Removed Unused Dependency**: Removed `@tabler/icons` (unused, 47 MB install)
-- ✅ **Bug Fixes**: 20+ bugs resolved from comprehensive codebase audit
-- ✅ **Import Atomicity**: Region imports use single IndexedDB transactions
-- ✅ **Expired Region Cleanup**: `forceCleanupExpiredRegions` now uses actual expiry timestamps
-- ✅ **XSS Prevention**: User data escaped in all UI templates
-- ✅ **Code Quality**: Dead code removal, `@/` path alias for all imports
-
-### v0.5.2
-
-- ✅ **CLI Command**: `npx map-gl-offline init` to copy the Service Worker into your project
-- ✅ **Vite Plugin**: `offlineSwPlugin()` to auto-copy the Service Worker on each build
-- ✅ **Mapbox GL Example**: Full React + Vite example app for Mapbox GL JS
+See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
-### v0.5.0
+**v0.5.5 (Latest):** Extra tile source selection for offline regions — pick additional vector/raster layers to download alongside the style's own sources.
 
-- ✅ **Mapbox GL JS Support**: Full support for Mapbox styles, including `mapbox://` protocol URL resolution
-- ✅ **Mapbox Standard Style**: 3D models, raster-dem terrain, and import-based style resolution
-- ✅ **Day/Night Light Presets**: Toggle between day and night lighting for Mapbox Standard
-- ✅ **Rain & Snow Weather**: Weather effect controls for Mapbox Standard style
-- ✅ **Import Resolver**: Automatic resolution of Mapbox Standard `imports` in styles
-- ✅ **Internationalization**: English and Arabic language support with full RTL layout
-- ✅ **Auto-detection**: Automatically detects Mapbox vs MapLibre styles
+**v0.5.3:** 28% bundle size reduction (783 KB to 565 KB), 20+ bug fixes, XSS prevention, import atomicity, `@/` path alias for all imports.
 
-### v0.1.0
+**v0.5.2:** CLI command (`npx map-gl-offline init`), Vite plugin for Service Worker, Mapbox GL example app.
 
-- ✅ **Fractional Zoom Fix**: Fixed tile loading at fractional zoom levels
-- ✅ **Modern UI**: Glassmorphic design with dark/light theme
-- ✅ **Polygon Drawing**: Interactive region selection tool
-- ✅ **Enhanced Analytics**: Comprehensive storage insights
-- ✅ **Performance**: Optimized downloads and memory usage
-- ✅ **TypeScript**: Full type safety throughout
-
-See [CHANGELOG.md](CHANGELOG.md) for complete version history.
+**v0.5.0:** Mapbox GL JS support, Standard style with 3D/terrain, day/night presets, rain/snow, i18n (English & Arabic with RTL).
 
 ## 🙏 Acknowledgments
 
@@ -597,4 +551,6 @@ MIT © [Muhammad Imran Siddique](https://github.com/muimsd)
 
 [📖 Documentation](https://map-gl-offline.netlify.app) • [🎮 Live Demo](https://map-gl-offline-demo.netlify.app) • [⭐ Star on GitHub](https://github.com/muimsd/map-gl-offline)
 
+<a href="https://www.buymeacoffee.com/muimsd" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/v2/default-yellow.png" alt="Buy Me A Coffee" style="height: 60px !important;width: 217px !important;" ></a>
+
 </div>

package/dist/index.esm.js

@@ -5356,6 +5356,21 @@ class RegionService {
         if (!Array.isArray(styleEntry.regions)) {
             styleEntry.regions = [];
         }
+        // Inject extra sources into the style so they get patched for offline use
+        if (region.extraSources && region.extraSources.length > 0) {
+            for (const extra of region.extraSources) {
+                if (!styleEntry.style.sources[extra.id]) {
+                    styleEntry.style.sources[extra.id] = {
+                        type: extra.type || 'vector',
+                        tiles: extra.tiles,
+                        ...(extra.minzoom !== undefined ? { minzoom: extra.minzoom } : {}),
+                        ...(extra.maxzoom !== undefined ? { maxzoom: extra.maxzoom } : {}),
+                        ...(extra.attribution ? { attribution: extra.attribution } : {}),
+                    };
+                    regionLogger$1.debug(`Injected extra source into style: ${extra.id}`);
+                }
+            }
+        }
         // Patch style for offline use with the region's maxZoom and tileExtension
         // Pass styleId for sprites since they're stored with the style ID, not region ID
         patchStyleForOffline(styleEntry.style, region.id, region.maxZoom, region.tileExtension, styleId);
@@ -5518,6 +5533,21 @@ class TileService {
         if (!style?.sources || Object.keys(style.sources).length === 0) {
             throw new Error('Style does not contain any sources to download tiles from');
         }
+        // Inject extra sources from the region into the style for downloading
+        if (region.extraSources && region.extraSources.length > 0) {
+            for (const extra of region.extraSources) {
+                if (!style.sources[extra.id]) {
+                    style.sources[extra.id] = {
+                        type: extra.type || 'vector',
+                        tiles: extra.tiles,
+                        ...(extra.minzoom !== undefined ? { minzoom: extra.minzoom } : {}),
+                        ...(extra.maxzoom !== undefined ? { maxzoom: extra.maxzoom } : {}),
+                        ...(extra.attribution ? { attribution: extra.attribution } : {}),
+                    };
+                    tileLogger.debug(`Injected extra source: ${extra.id}`, extra.tiles);
+                }
+            }
+        }
         // Generate tile coordinates once for the region
         const tileCoords = this.generateTileCoordinates(region);
         tileLogger.debug('🔍 ABOUT TO CALL extractTileSources with style:', {
@@ -8077,6 +8107,14 @@ const en = {
     'regionForm.downloadRegion': 'Download Region',
     'regionForm.area': 'Area',
     'regionForm.bounds': 'Bounds',
+    'regionForm.extraSources': 'Additional Tile Sources',
+    'regionForm.extraSourcesInfo': 'Select extra layers from the map to include in this offline region',
+    'regionForm.noExtraSources': 'No additional tile sources found on the map',
+    'regionForm.sourceType.vector': 'Vector',
+    'regionForm.sourceType.raster': 'Raster',
+    'regionForm.sourceType.raster-dem': 'Terrain',
+    'regionForm.selectAll': 'Select All',
+    'regionForm.deselectAll': 'Deselect All',
     // Region List
     'regionList.empty': 'No offline styles or regions found. Click "Add Region" to get started.',
     'regionList.emptyFallback': 'No offline regions found. Click "Add Region" to get started.',
@@ -8292,6 +8330,14 @@ const ar = {
     'regionForm.downloadRegion': 'تحميل المنطقة',
     'regionForm.area': 'المساحة',
     'regionForm.bounds': 'الحدود',
+    'regionForm.extraSources': 'مصادر بلاطات إضافية',
+    'regionForm.extraSourcesInfo': 'اختر طبقات إضافية من الخريطة لتضمينها في هذه المنطقة',
+    'regionForm.noExtraSources': 'لم يتم العثور على مصادر بلاطات إضافية على الخريطة',
+    'regionForm.sourceType.vector': 'متجه',
+    'regionForm.sourceType.raster': 'نقطي',
+    'regionForm.sourceType.raster-dem': 'تضاريس',
+    'regionForm.selectAll': 'تحديد الكل',
+    'regionForm.deselectAll': 'إلغاء تحديد الكل',
     // Region List - قائمة المناطق
     'regionList.empty': 'لم يتم العثور على أنماط أو مناطق غير متصلة. انقر على "إضافة منطقة" للبدء.',
     'regionList.emptyFallback': 'لم يتم العثور على مناطق غير متصلة. انقر على "إضافة منطقة" للبدء.',
@@ -11644,6 +11690,8 @@ class RegionFormModal {
     providerSelect;
     accessTokenInput;
     accessTokenGroup;
+    // Extra sources picker
+    sourceCheckboxes = new Map();
     constructor(options) {
         this.options = options;
     }
@@ -11815,10 +11863,124 @@ class RegionFormModal {
     `;
         this.accessTokenGroup.appendChild(tokenHelp);
         form.appendChild(this.accessTokenGroup);
+        // Extra sources picker
+        if (this.options.mapSources && this.options.mapSources.length > 0) {
+            const sourcesSection = this.createSourcesPicker(this.options.mapSources);
+            form.appendChild(sourcesSection);
+        }
         // Initialize provider detection
         this.detectProviderFromUrl();
         return form;
     }
+    /**
+     * Create the extra sources picker section
+     */
+    createSourcesPicker(sources) {
+        const group = document.createElement('div');
+        group.className = 'flex flex-col gap-3';
+        // Header with label and select all/deselect all
+        const header = document.createElement('div');
+        header.className = 'flex items-center justify-between';
+        header.innerHTML = `
+      <label class="block text-sm font-semibold text-gray-700 dark:text-gray-300">
+        ${t('regionForm.extraSources')}
+      </label>
+    `;
+        const toggleBtn = document.createElement('button');
+        toggleBtn.type = 'button';
+        toggleBtn.className =
+            'text-xs text-primary-600 dark:text-primary-400 hover:underline cursor-pointer font-medium';
+        toggleBtn.textContent = t('regionForm.selectAll');
+        let allSelected = false;
+        toggleBtn.addEventListener('click', () => {
+            allSelected = !allSelected;
+            for (const { checkbox } of this.sourceCheckboxes.values()) {
+                checkbox.checked = allSelected;
+            }
+            toggleBtn.textContent = allSelected ? t('regionForm.deselectAll') : t('regionForm.selectAll');
+        });
+        header.appendChild(toggleBtn);
+        group.appendChild(header);
+        // Info text
+        const info = document.createElement('div');
+        info.className = 'text-xs text-gray-500 dark:text-gray-400 flex items-center gap-1';
+        info.innerHTML = `${icons.infoCircle({ size: 12 })} ${t('regionForm.extraSourcesInfo')}`;
+        group.appendChild(info);
+        // Source list
+        const list = document.createElement('div');
+        list.className =
+            'flex flex-col gap-2 max-h-48 overflow-y-auto p-3 rounded-xl glass-input border border-gray-100/50 dark:border-gray-700/50 bg-gray-50/50 dark:bg-gray-800/50';
+        for (const source of sources) {
+            const row = document.createElement('label');
+            row.className =
+                'flex items-center gap-3 p-2 rounded-lg hover:bg-white/60 dark:hover:bg-gray-700/40 cursor-pointer transition-colors';
+            const checkbox = document.createElement('input');
+            checkbox.type = 'checkbox';
+            checkbox.className =
+                'w-4 h-4 rounded border-gray-300 dark:border-gray-600 text-primary-600 focus:ring-primary-500/50 cursor-pointer flex-shrink-0';
+            checkbox.value = source.id;
+            row.appendChild(checkbox);
+            this.sourceCheckboxes.set(source.id, { checkbox, source });
+            const details = document.createElement('div');
+            details.className = 'flex flex-col min-w-0';
+            const nameRow = document.createElement('div');
+            nameRow.className = 'flex items-center gap-2';
+            const name = document.createElement('span');
+            name.className = 'text-sm font-medium text-gray-800 dark:text-gray-200 truncate';
+            name.textContent = source.id;
+            nameRow.appendChild(name);
+            const typeKey = `regionForm.sourceType.${source.type}`;
+            const badge = document.createElement('span');
+            badge.className =
+                source.type === 'vector'
+                    ? 'text-[10px] px-1.5 py-0.5 rounded-full bg-blue-100 dark:bg-blue-900/40 text-blue-700 dark:text-blue-300 font-medium flex-shrink-0'
+                    : source.type === 'raster'
+                        ? 'text-[10px] px-1.5 py-0.5 rounded-full bg-green-100 dark:bg-green-900/40 text-green-700 dark:text-green-300 font-medium flex-shrink-0'
+                        : 'text-[10px] px-1.5 py-0.5 rounded-full bg-amber-100 dark:bg-amber-900/40 text-amber-700 dark:text-amber-300 font-medium flex-shrink-0';
+            badge.textContent = t(typeKey);
+            nameRow.appendChild(badge);
+            details.appendChild(nameRow);
+            // Zoom range info
+            const zoomMin = source.minzoom ?? 0;
+            const zoomMax = source.maxzoom ?? 22;
+            const meta = document.createElement('span');
+            meta.className = 'text-[11px] text-gray-500 dark:text-gray-400 truncate';
+            meta.textContent = `z${zoomMin}-${zoomMax}`;
+            if (source.tiles.length > 0) {
+                try {
+                    const hostname = new URL(source.tiles[0]).hostname;
+                    meta.textContent += ` · ${escapeHtml$1(hostname)}`;
+                }
+                catch {
+                    // ignore invalid URLs
+                }
+            }
+            details.appendChild(meta);
+            row.appendChild(details);
+            list.appendChild(row);
+        }
+        group.appendChild(list);
+        return group;
+    }
+    /**
+     * Get the selected extra sources from the picker
+     */
+    getSelectedExtraSources() {
+        const selected = [];
+        for (const { checkbox, source } of this.sourceCheckboxes.values()) {
+            if (checkbox.checked) {
+                selected.push({
+                    id: source.id,
+                    type: source.type,
+                    tiles: source.tiles,
+                    minzoom: source.minzoom,
+                    maxzoom: source.maxzoom,
+                    attribution: source.attribution,
+                });
+            }
+        }
+        return selected;
+    }
     /**
      * Handle style URL changes to auto-detect provider
      */
@@ -11905,6 +12067,7 @@ class RegionFormModal {
      */
     async handleSave() {
         try {
+            const selectedSources = this.getSelectedExtraSources();
             const formData = {
                 name: this.nameInput?.value || `Region ${Date.now()}`,
                 minZoom: parseInt(this.minZoomInput?.value || '1'),
@@ -11914,6 +12077,7 @@ class RegionFormModal {
                 // Enhanced Mapbox GL support
                 provider: this.providerSelect?.value,
                 accessToken: this.accessTokenInput?.value || undefined,
+                extraSources: selectedSources.length > 0 ? selectedSources : undefined,
             };
             this.modal?.hide();
             await this.options.onSave(formData);
@@ -12054,10 +12218,77 @@ class RegionControl {
             this.polygonControl.triggerSave();
         }
     }
+    /**
+     * Get the source IDs that belong to the current style URL.
+     * These are the sources the style already includes and will be downloaded automatically.
+     */
+    async getStyleSourceIds() {
+        try {
+            const styleUrl = this.options.styleUrl;
+            if (!styleUrl)
+                return new Set();
+            const response = await fetch(styleUrl);
+            if (!response.ok)
+                return new Set();
+            const styleJson = (await response.json());
+            if (styleJson.sources && typeof styleJson.sources === 'object') {
+                return new Set(Object.keys(styleJson.sources));
+            }
+        }
+        catch (error) {
+            regionLogger.warn('Failed to fetch style for source filtering:', error);
+        }
+        return new Set();
+    }
+    /**
+     * Extract tile sources from the live map instance that are NOT part of the current style.
+     * Returns vector, raster, and raster-dem sources that have tile URLs,
+     * excluding sources that already belong to the style (those are downloaded automatically).
+     */
+    async extractExtraMapSources() {
+        try {
+            const style = this.map?.getStyle?.();
+            if (!style || !style.sources || typeof style.sources !== 'object')
+                return [];
+            // Fetch the original style's source IDs so we can exclude them
+            const styleSourceIds = await this.getStyleSourceIds();
+            const sources = [];
+            for (const [id, raw] of Object.entries(style.sources)) {
+                // Skip sources that belong to the style itself
+                if (styleSourceIds.has(id))
+                    continue;
+                const type = raw.type;
+                if (type !== 'vector' && type !== 'raster' && type !== 'raster-dem')
+                    continue;
+                const tiles = raw.tiles;
+                // Only include sources that have resolvable tile URLs (not idb://)
+                if (!tiles || !Array.isArray(tiles) || tiles.length === 0)
+                    continue;
+                const hasHttpTiles = tiles.some((t) => t.startsWith('http://') || t.startsWith('https://'));
+                if (!hasHttpTiles)
+                    continue;
+                sources.push({
+                    id,
+                    type: type,
+                    tiles: tiles.filter((t) => t.startsWith('http://') || t.startsWith('https://')),
+                    minzoom: typeof raw.minzoom === 'number' ? raw.minzoom : undefined,
+                    maxzoom: typeof raw.maxzoom === 'number' ? raw.maxzoom : undefined,
+                    attribution: typeof raw.attribution === 'string' ? raw.attribution : undefined,
+                });
+            }
+            return sources;
+        }
+        catch (error) {
+            regionLogger.warn('Failed to extract map sources:', error);
+            return [];
+        }
+    }
     /**
      * Show region form modal
      */
-    showRegionForm(bounds, area) {
+    async showRegionForm(bounds, area) {
+        const mapSources = await this.extractExtraMapSources();
+        regionLogger.debug(`Discovered ${mapSources.length} extra tile sources from map`);
         const formOptions = {
             bounds,
             area,
@@ -12066,6 +12297,7 @@ class RegionControl {
             styleUrl: this.options.styleUrl,
             accessToken: this.options.accessToken,
             onThemeToggle: () => this.options.onRegionSaved?.(),
+            mapSources,
         };
         this.regionFormModal = new RegionFormModal(formOptions);
         const modal = this.regionFormModal.show();
@@ -12229,6 +12461,7 @@ class DownloadManager {
             minZoom: formData.minZoom,
             maxZoom: formData.maxZoom,
             styleUrl: formData.styleUrl,
+            extraSources: formData.extraSources,
         };
         const regionId = regionConfig.id;
         try {