maplibre-gl-layer-control 0.7.2 → 0.8.0

package/README.md

@@ -73,7 +73,17 @@ map.on('load', () => {
     panelMaxWidth: 450
   });
 
-  // Option 2: Show ALL layers individually (no layers parameter)
+  // Option 2: Auto-detect with basemapStyleUrl (recommended for reliable basemap detection)
+  // - Fetches the basemap style to identify basemap layers
+  // - All basemap layers are grouped under "Background"
+  // - User-added layers are shown individually
+  // const BASEMAP_STYLE = 'https://demotiles.maplibre.org/style.json';
+  // const layerControl = new LayerControl({
+  //   collapsed: false,
+  //   basemapStyleUrl: BASEMAP_STYLE
+  // });
+
+  // Option 3: Show ALL layers individually (no layers parameter)
   // - Auto-detects ALL layers from the map
   // - Generates friendly names from layer IDs (e.g., 'countries-layer' → 'Countries Layer')
   // const layerControl = new LayerControl({
@@ -83,7 +93,7 @@ map.on('load', () => {
   //   panelMaxWidth: 450
   // });
 
-  // Option 3: Manually specify layer states (for full control over names)
+  // Option 4: Manually specify layer states (for full control over names)
   // const layerControl = new LayerControl({
   //   collapsed: false,
   //   layerStates: {
@@ -161,6 +171,7 @@ function MapComponent() {
 | `showLayerSymbol` | `boolean` | `true` | Show layer type symbols (colored icons) next to layer names |
 | `excludeDrawnLayers` | `boolean` | `true` | Exclude layers from drawing libraries (Geoman, Mapbox GL Draw, etc.) |
 | `customLayerAdapters` | `CustomLayerAdapter[]` | `undefined` | Adapters for non-MapLibre layers (deck.gl, Zarr, etc.) |
+| `basemapStyleUrl` | `string` | `undefined` | URL of basemap style JSON for reliable layer detection (see below) |
 
 ### LayerState
 
@@ -172,14 +183,76 @@ interface LayerState {
 }
 ```
 
+### Basemap Style URL Detection
+
+When using auto-detection (without specifying `layers`), the control needs to distinguish between basemap layers and user-added layers. By default, it uses heuristics based on source detection, which may not always be reliable.
+
+For **reliable detection**, provide the `basemapStyleUrl` option with the same URL used for the map's style:
+
+```typescript
+const BASEMAP_STYLE_URL = 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json';
+
+const map = new maplibregl.Map({
+  container: 'map',
+  style: BASEMAP_STYLE_URL,
+  center: [0, 0],
+  zoom: 2
+});
+
+map.on('load', () => {
+  // Add your custom layers
+  map.addLayer({
+    id: 'my-custom-layer',
+    type: 'fill',
+    source: 'my-source',
+    paint: { 'fill-color': '#088' }
+  });
+
+  // Create layer control with basemapStyleUrl for reliable detection
+  const layerControl = new LayerControl({
+    collapsed: false,
+    basemapStyleUrl: BASEMAP_STYLE_URL  // All layers from this URL go to "Background"
+  });
+
+  map.addControl(layerControl, 'top-right');
+});
+```
+
+When `basemapStyleUrl` is provided:
+- The control fetches the style JSON and extracts all layer IDs
+- Layers that exist in the basemap style are grouped under "Background"
+- All other layers (user-added) are shown individually in the control
+- New layers added later are automatically detected as user layers
+
+### Automatic Detection Without basemapStyleUrl
+
+Even without `basemapStyleUrl`, the control uses source-based heuristics to detect user-added layers. Custom MapLibre layers (using `map.addLayer()`) are automatically detected whether they are added **before** or **after** the layer control - no custom adapter is needed for standard MapLibre layer types!
+
+```typescript
+map.on('load', () => {
+  // Add custom layers BEFORE the control - they will be detected
+  map.addSource('my-source', { type: 'geojson', data: myGeoJson });
+  map.addLayer({ id: 'my-layer', type: 'fill', source: 'my-source', ... });
+
+  // Add the control - it detects existing custom layers
+  const layerControl = new LayerControl({ collapsed: false });
+  map.addControl(layerControl, 'top-right');
+
+  // Add more layers AFTER the control - they will also be detected automatically
+  map.addLayer({ id: 'another-layer', type: 'circle', source: 'another-source', ... });
+});
+```
+
 ## Examples
 
 See the [examples](./examples) folder for complete working examples:
 
 - **[basic](./examples/basic)** - Simple vanilla JavaScript example
-- **[full-demo](./examples/full-demo)** - Full demo with multiple layer types
+- **[full-demo](./examples/full-demo)** - Full demo with multiple layer types and `basemapStyleUrl` for reliable basemap detection
+- **[dynamic-layers](./examples/dynamic-layers)** - Auto-detect layers added before or after control
 - **[background-legend](./examples/background-legend)** - Background layer visibility control
 - **[react](./examples/react)** - React integration example
+- **[cdn](./examples/cdn)** - Browser-only example using CDN (no build step required)
 
 ### Layer Symbols
 
@@ -386,6 +459,41 @@ npm test
 npm run build
 ```
 
+## Docker
+
+The examples can be run using Docker. The image is automatically built and published to GitHub Container Registry.
+
+### Pull and Run
+
+```bash
+# Pull the latest image
+docker pull ghcr.io/opengeos/maplibre-gl-layer-control:latest
+
+# Run the container
+docker run -p 8080:80 ghcr.io/opengeos/maplibre-gl-layer-control:latest
+```
+
+Then open http://localhost:8080/maplibre-gl-layer-control/ in your browser to view the examples.
+
+### Build Locally
+
+```bash
+# Build the image
+docker build -t maplibre-gl-layer-control .
+
+# Run the container
+docker run -p 8080:80 maplibre-gl-layer-control
+```
+
+### Available Tags
+
+| Tag | Description |
+|-----|-------------|
+| `latest` | Latest release |
+| `x.y.z` | Specific version (e.g., `1.0.0`) |
+| `x.y` | Minor version (e.g., `1.0`) |
+
+
 ## License
 
 MIT © Qiusheng Wu

package/dist/index.cjs

@@ -643,6 +643,7 @@ class LayerControl {
     __publicField(this, "targetLayers");
     __publicField(this, "styleEditors");
     __publicField(this, "initialSourceIds", null);
+    __publicField(this, "initialLayerIds", null);
     // Panel width management
     __publicField(this, "minPanelWidth");
     __publicField(this, "maxPanelWidth");
@@ -653,6 +654,8 @@ class LayerControl {
     __publicField(this, "excludeDrawnLayers");
     __publicField(this, "customLayerRegistry", null);
     __publicField(this, "customLayerUnsubscribe", null);
+    __publicField(this, "basemapStyleUrl", null);
+    __publicField(this, "basemapLayerIds", null);
     __publicField(this, "widthSliderEl", null);
     __publicField(this, "widthThumbEl", null);
     __publicField(this, "widthValueEl", null);
@@ -687,6 +690,7 @@ class LayerControl {
         this.customLayerRegistry.register(adapter);
       });
     }
+    this.basemapStyleUrl = options.basemapStyleUrl || null;
   }
   /**
    * Called when the control is added to the map
@@ -700,8 +704,10 @@ class LayerControl {
     } else {
       this.initialSourceIds = /* @__PURE__ */ new Set();
     }
-    if (Object.keys(this.state.layerStates).length === 0) {
-      this.autoDetectLayers();
+    if (style && style.layers) {
+      this.initialLayerIds = new Set(style.layers.map((layer) => layer.id));
+    } else {
+      this.initialLayerIds = /* @__PURE__ */ new Set();
     }
     this.container = this.createContainer();
     this.button = this.createToggleButton();
@@ -710,7 +716,25 @@ class LayerControl {
     this.mapContainer.appendChild(this.panel);
     this.updateWidthDisplay();
     this.setupEventListeners();
-    this.buildLayerItems();
+    if (this.basemapStyleUrl && !this.basemapLayerIds) {
+      this.fetchBasemapStyle().then(() => {
+        if (Object.keys(this.state.layerStates).length === 0) {
+          this.autoDetectLayers();
+        }
+        this.buildLayerItems();
+      }).catch((error) => {
+        console.warn("Failed to fetch basemap style, falling back to heuristic detection:", error);
+        if (Object.keys(this.state.layerStates).length === 0) {
+          this.autoDetectLayers();
+        }
+        this.buildLayerItems();
+      });
+    } else {
+      if (Object.keys(this.state.layerStates).length === 0) {
+        this.autoDetectLayers();
+      }
+      this.buildLayerItems();
+    }
     if (!this.state.collapsed) {
       requestAnimationFrame(() => {
         this.updatePanelPosition();
@@ -718,6 +742,30 @@ class LayerControl {
     }
     return this.container;
   }
+  /**
+   * Fetch the basemap style JSON and extract layer IDs.
+   * This provides reliable distinction between basemap and user-added layers.
+   */
+  async fetchBasemapStyle() {
+    if (!this.basemapStyleUrl) return;
+    try {
+      const response = await fetch(this.basemapStyleUrl);
+      if (!response.ok) {
+        throw new Error(`HTTP error! status: ${response.status}`);
+      }
+      const styleJson = await response.json();
+      if (styleJson && Array.isArray(styleJson.layers)) {
+        this.basemapLayerIds = new Set(
+          styleJson.layers.map((layer) => layer.id)
+        );
+      } else {
+        this.basemapLayerIds = /* @__PURE__ */ new Set();
+      }
+    } catch (error) {
+      console.warn("Failed to fetch basemap style from URL:", this.basemapStyleUrl, error);
+      throw error;
+    }
+  }
   /**
    * Called when the control is removed from the map
    */
@@ -754,7 +802,8 @@ class LayerControl {
     if (this.targetLayers.length === 0) {
       const userAddedLayers = [];
       const backgroundLayerIds = [];
-      const userAddedSourceIds = this.detectUserAddedSources();
+      const useBasemapStyleDetection = this.basemapLayerIds !== null && this.basemapLayerIds.size > 0;
+      const userAddedSourceIds = useBasemapStyleDetection ? /* @__PURE__ */ new Set() : this.detectUserAddedSources();
       allLayerIds.forEach((layerId) => {
         const layer = this.map.getLayer(layerId);
         if (!layer) return;
@@ -762,11 +811,19 @@ class LayerControl {
           backgroundLayerIds.push(layerId);
           return;
         }
-        const sourceId = layer.source;
-        if (sourceId && userAddedSourceIds.has(sourceId)) {
-          userAddedLayers.push(layerId);
+        if (useBasemapStyleDetection) {
+          if (this.basemapLayerIds.has(layerId)) {
+            backgroundLayerIds.push(layerId);
+          } else {
+            userAddedLayers.push(layerId);
+          }
         } else {
-          backgroundLayerIds.push(layerId);
+          const sourceId = layer.source;
+          if (sourceId && userAddedSourceIds.has(sourceId)) {
+            userAddedLayers.push(layerId);
+          } else {
+            backgroundLayerIds.push(layerId);
+          }
         }
       });
       if (backgroundLayerIds.length > 0) {
@@ -1532,9 +1589,27 @@ class LayerControl {
   }
   /**
    * Check if a layer is a user-added layer (vs basemap layer)
+   * Used primarily for the background legend to determine which layers are background
    */
   isUserAddedLayer(layerId) {
-    return this.state.layerStates[layerId] !== void 0 && layerId !== "Background";
+    if (this.state.layerStates[layerId] !== void 0 && layerId !== "Background") {
+      return true;
+    }
+    if (this.basemapLayerIds !== null && this.basemapLayerIds.size > 0) {
+      return !this.basemapLayerIds.has(layerId);
+    }
+    if (this.initialLayerIds !== null && !this.initialLayerIds.has(layerId)) {
+      return true;
+    }
+    const layer = this.map.getLayer(layerId);
+    if (layer) {
+      const sourceId = layer.source;
+      if (sourceId) {
+        const userAddedSourceIds = this.detectUserAddedSources();
+        return userAddedSourceIds.has(sourceId);
+      }
+    }
+    return false;
   }
   /**
    * Toggle visibility for all background layers (basemap layers)
@@ -2324,7 +2399,8 @@ class LayerControl {
       const currentMapLayerIds = new Set(style.layers.map((layer) => layer.id));
       const isAutoDetectMode = this.targetLayers.length === 0 || this.targetLayers.length === 1 && this.targetLayers[0] === "Background" || this.targetLayers.every((id) => id === "Background" || this.state.layerStates[id]);
       const newLayers = [];
-      const userAddedSourceIds = isAutoDetectMode ? this.detectUserAddedSources() : /* @__PURE__ */ new Set();
+      const useBasemapStyleDetection = this.basemapLayerIds !== null && this.basemapLayerIds.size > 0;
+      const useInitialLayerDetection = !useBasemapStyleDetection && this.initialLayerIds !== null && this.initialLayerIds.size > 0;
       currentMapLayerIds.forEach((layerId) => {
         if (layerId !== "Background" && !this.state.layerStates[layerId]) {
           const layer = this.map.getLayer(layerId);
@@ -2333,9 +2409,24 @@ class LayerControl {
               if (this.excludeDrawnLayers && this.isDrawnLayer(layerId)) {
                 return;
               }
-              const sourceId = layer.source;
-              if (!sourceId || !userAddedSourceIds.has(sourceId)) {
-                return;
+              if (useBasemapStyleDetection) {
+                if (this.basemapLayerIds.has(layerId)) {
+                  return;
+                }
+              } else if (useInitialLayerDetection) {
+                if (this.initialLayerIds.has(layerId)) {
+                  const userAddedSourceIds = this.detectUserAddedSources();
+                  const sourceId = layer.source;
+                  if (!sourceId || !userAddedSourceIds.has(sourceId)) {
+                    return;
+                  }
+                }
+              } else {
+                const userAddedSourceIds = this.detectUserAddedSources();
+                const sourceId = layer.source;
+                if (!sourceId || !userAddedSourceIds.has(sourceId)) {
+                  return;
+                }
               }
             }
             newLayers.push(layerId);