map-gl-offline 0.5.2 → 0.5.5

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
@@ -171,7 +172,8 @@ map.on('load', () => {
     theme: 'dark',
     showBbox: true,
     accessToken: mapboxgl.accessToken,
-    mapLib: mapboxgl, // Mapbox GL lacks addProtocol, so the library auto-registers a Service Worker
+    // No mapLib needed - Mapbox GL JS v3 lacks addProtocol,
+    // so the library auto-registers a Service Worker fallback
   });
   map.addControl(control, 'top-right');
 });
@@ -346,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
@@ -406,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 |
@@ -479,7 +463,7 @@ const smallerRegion = {
 
 ## 🤝 Contributing
 
-Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+Contributions are welcome!
 
 ### Development Setup
 
@@ -489,21 +473,21 @@ git clone https://github.com/muimsd/map-gl-offline.git
 cd map-gl-offline
 
 # Install dependencies
-pnpm install
+npm install
 
 # Run development server
-pnpm dev
+npm run dev
 
 # Run tests
-pnpm test
+npm test
 
 # Build library
-pnpm build
+npm run build
 
-# Run example app
+# Run MapLibre example app
 cd examples/maplibre
-pnpm install
-pnpm dev
+npm install
+npm run dev
 ```
 
 ### Project Structure
@@ -518,8 +502,11 @@ map-gl-offline/
 │   │   └── translations/  # i18n (English, Arabic)
 │   ├── utils/             # Utilities & helpers
 │   └── types/             # TypeScript definitions
+├── bin/                   # CLI (map-gl-offline init) & Vite plugin
 ├── examples/
-│   └── maplibre/          # Live example app
+│   ├── maplibre/          # MapLibre GL JS example app
+│   └── mapbox-gl/         # Mapbox GL JS example app
+├── docs/                  # Docusaurus documentation site
 └── tests/                 # Test suites
 ```
 
@@ -534,26 +521,15 @@ map-gl-offline/
 
 ## 🔄 Recent Updates
 
-### v0.5.0 (Latest)
+See [CHANGELOG.md](CHANGELOG.md) for complete version history.
 
-- ✅ **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.5 (Latest):** Extra tile source selection for offline regions — pick additional vector/raster layers to download alongside the style's own sources.
 
-### v0.1.0
+**v0.5.3:** 28% bundle size reduction (783 KB to 565 KB), 20+ bug fixes, XSS prevention, import atomicity, `@/` path alias for all imports.
 
-- ✅ **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
+**v0.5.2:** CLI command (`npx map-gl-offline init`), Vite plugin for Service Worker, Mapbox GL example app.
 
-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
 
@@ -575,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>