maplibre-gl-layer-control 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # maplibre-gl-layer-control
 
+[![npm version](https://img.shields.io/npm/v/maplibre-gl-layer-control.svg)](https://www.npmjs.com/package/maplibre-gl-layer-control)
+[![npm downloads](https://img.shields.io/npm/dm/maplibre-gl-layer-control.svg)](https://www.npmjs.com/package/maplibre-gl-layer-control)
+[![license](https://img.shields.io/npm/l/maplibre-gl-layer-control.svg)](https://github.com/opengeos/maplibre-gl-layer-control/blob/main/LICENSE)
+
 A comprehensive layer control for MapLibre GL with advanced styling capabilities. Built with TypeScript and React, providing both vanilla JavaScript and React integration options.
 
 ## Features
@@ -16,6 +20,7 @@ A comprehensive layer control for MapLibre GL with advanced styling capabilities
   - **Raster layers**: opacity, brightness, saturation, contrast, hue-rotate
 - ✅ **Dynamic layer detection** - Automatically detect and manage new layers
 - ✅ **Background layer grouping** - Control all basemap layers as one group
+- ✅ **Background layer legend** - Gear icon to toggle individual background layer visibility
 - ✅ **Accessibility** - Full ARIA support and keyboard navigation
 - ✅ **TypeScript** - Full type safety and IntelliSense support
 - ✅ **React integration** - Optional React components and hooks
@@ -165,8 +170,21 @@ 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
+- **[background-legend](./examples/background-legend)** - Background layer visibility control
 - **[react](./examples/react)** - React integration example
 
+### Background Layer Legend
+
+When using the `layers` option to specify specific layers, all other layers are grouped under a "Background" entry. The Background layer includes a **gear icon** that opens a detailed legend panel showing:
+
+- Individual visibility toggles for each background layer
+- Layer type indicators (fill, line, symbol, etc.)
+- Quick "Show All" / "Hide All" buttons
+- **"Only rendered" filter** - Shows only layers that are currently rendered in the map viewport
+- Indeterminate checkbox state when some layers are hidden
+
+This allows fine-grained control over which basemap layers are visible while maintaining a simplified layer control interface.
+
 ## Development
 
 ```bash

package/dist/index.cjs

@@ -197,7 +197,10 @@ class LayerControl {
       activeStyleEditor: null,
       layerStates: options.layerStates || {},
       originalStyles: /* @__PURE__ */ new Map(),
-      userInteractingWithSlider: false
+      userInteractingWithSlider: false,
+      backgroundLegendOpen: false,
+      backgroundLayerVisibility: /* @__PURE__ */ new Map(),
+      onlyRenderedFilter: false
     };
     this.targetLayers = options.layers || Object.keys(this.state.layerStates);
     this.styleEditors = /* @__PURE__ */ new Map();
@@ -629,7 +632,10 @@ class LayerControl {
     row.appendChild(checkbox);
     row.appendChild(name);
     row.appendChild(opacity);
-    if (layerId !== "Background") {
+    if (layerId === "Background") {
+      const legendButton = this.createBackgroundLegendButton();
+      row.appendChild(legendButton);
+    } else {
       const styleButton = this.createStyleButton(layerId);
       if (styleButton) {
         row.appendChild(styleButton);
@@ -683,9 +689,19 @@ class LayerControl {
     const styleLayers = this.map.getStyle().layers || [];
     styleLayers.forEach((layer) => {
       if (!this.isUserAddedLayer(layer.id)) {
+        this.state.backgroundLayerVisibility.set(layer.id, visible);
         this.map.setLayoutProperty(layer.id, "visibility", visible ? "visible" : "none");
       }
     });
+    if (this.state.backgroundLegendOpen) {
+      const legendPanel = this.panel.querySelector(".layer-control-background-legend");
+      if (legendPanel) {
+        const checkboxes = legendPanel.querySelectorAll(".background-legend-checkbox");
+        checkboxes.forEach((checkbox) => {
+          checkbox.checked = visible;
+        });
+      }
+    }
   }
   /**
    * Change opacity for all background layers (basemap layers)
@@ -704,6 +720,260 @@ class LayerControl {
       }
     });
   }
+  // ===== Background Legend Methods =====
+  /**
+   * Create legend button for Background layer
+   */
+  createBackgroundLegendButton() {
+    const button = document.createElement("button");
+    button.className = "layer-control-style-button layer-control-background-legend-button";
+    button.innerHTML = "⚙";
+    button.title = "Show background layer details";
+    button.setAttribute("aria-label", "Show background layer visibility controls");
+    button.setAttribute("aria-expanded", String(this.state.backgroundLegendOpen));
+    button.addEventListener("click", (e) => {
+      e.stopPropagation();
+      this.toggleBackgroundLegend();
+    });
+    return button;
+  }
+  /**
+   * Toggle background legend panel visibility
+   */
+  toggleBackgroundLegend() {
+    if (this.state.backgroundLegendOpen) {
+      this.closeBackgroundLegend();
+    } else {
+      this.openBackgroundLegend();
+    }
+  }
+  /**
+   * Open background legend panel
+   */
+  openBackgroundLegend() {
+    if (this.state.activeStyleEditor) {
+      this.closeStyleEditor(this.state.activeStyleEditor);
+    }
+    const itemEl = this.panel.querySelector('[data-layer-id="Background"]');
+    if (!itemEl) return;
+    let legendPanel = itemEl.querySelector(".layer-control-background-legend");
+    if (legendPanel) {
+      const layerList = legendPanel.querySelector(".background-legend-layer-list");
+      if (layerList) {
+        this.populateBackgroundLayerList(layerList);
+      }
+    } else {
+      legendPanel = this.createBackgroundLegendPanel();
+      itemEl.appendChild(legendPanel);
+    }
+    this.state.backgroundLegendOpen = true;
+    const button = itemEl.querySelector(".layer-control-background-legend-button");
+    if (button) {
+      button.setAttribute("aria-expanded", "true");
+      button.classList.add("active");
+    }
+    setTimeout(() => {
+      legendPanel == null ? void 0 : legendPanel.scrollIntoView({ behavior: "smooth", block: "nearest" });
+    }, 50);
+  }
+  /**
+   * Close background legend panel
+   */
+  closeBackgroundLegend() {
+    const itemEl = this.panel.querySelector('[data-layer-id="Background"]');
+    if (!itemEl) return;
+    const legendPanel = itemEl.querySelector(".layer-control-background-legend");
+    if (legendPanel) {
+      legendPanel.remove();
+    }
+    this.state.backgroundLegendOpen = false;
+    const button = itemEl.querySelector(".layer-control-background-legend-button");
+    if (button) {
+      button.setAttribute("aria-expanded", "false");
+      button.classList.remove("active");
+    }
+  }
+  /**
+   * Create the background legend panel with individual layer controls
+   */
+  createBackgroundLegendPanel() {
+    const panel = document.createElement("div");
+    panel.className = "layer-control-background-legend";
+    const header = document.createElement("div");
+    header.className = "background-legend-header";
+    const title = document.createElement("span");
+    title.className = "background-legend-title";
+    title.textContent = "Background Layers";
+    const closeBtn = document.createElement("button");
+    closeBtn.className = "background-legend-close";
+    closeBtn.innerHTML = "×";
+    closeBtn.title = "Close";
+    closeBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      this.closeBackgroundLegend();
+    });
+    header.appendChild(title);
+    header.appendChild(closeBtn);
+    const actionsRow = document.createElement("div");
+    actionsRow.className = "background-legend-actions";
+    const showAllBtn = document.createElement("button");
+    showAllBtn.className = "background-legend-action-btn";
+    showAllBtn.textContent = "Show All";
+    showAllBtn.addEventListener("click", () => this.setAllBackgroundLayersVisibility(true));
+    const hideAllBtn = document.createElement("button");
+    hideAllBtn.className = "background-legend-action-btn";
+    hideAllBtn.textContent = "Hide All";
+    hideAllBtn.addEventListener("click", () => this.setAllBackgroundLayersVisibility(false));
+    actionsRow.appendChild(showAllBtn);
+    actionsRow.appendChild(hideAllBtn);
+    const filterRow = document.createElement("div");
+    filterRow.className = "background-legend-filter";
+    const filterCheckbox = document.createElement("input");
+    filterCheckbox.type = "checkbox";
+    filterCheckbox.className = "background-legend-filter-checkbox";
+    filterCheckbox.id = "background-legend-only-rendered";
+    filterCheckbox.checked = this.state.onlyRenderedFilter;
+    filterCheckbox.addEventListener("change", () => {
+      this.state.onlyRenderedFilter = filterCheckbox.checked;
+      const layerList2 = panel.querySelector(".background-legend-layer-list");
+      if (layerList2) {
+        this.populateBackgroundLayerList(layerList2);
+      }
+    });
+    const filterLabel = document.createElement("label");
+    filterLabel.className = "background-legend-filter-label";
+    filterLabel.htmlFor = "background-legend-only-rendered";
+    filterLabel.textContent = "Only rendered";
+    filterRow.appendChild(filterCheckbox);
+    filterRow.appendChild(filterLabel);
+    const layerList = document.createElement("div");
+    layerList.className = "background-legend-layer-list";
+    this.populateBackgroundLayerList(layerList);
+    panel.appendChild(header);
+    panel.appendChild(actionsRow);
+    panel.appendChild(filterRow);
+    panel.appendChild(layerList);
+    return panel;
+  }
+  /**
+   * Check if a layer is currently rendered in the map viewport
+   */
+  isLayerRendered(layerId) {
+    try {
+      const layer = this.map.getLayer(layerId);
+      if (!layer) return false;
+      const visibility = this.map.getLayoutProperty(layerId, "visibility");
+      if (visibility === "none") return false;
+      if (layer.type === "raster" || layer.type === "hillshade") {
+        return true;
+      }
+      if (layer.type === "background") {
+        return true;
+      }
+      const features = this.map.queryRenderedFeatures({ layers: [layerId] });
+      return features.length > 0;
+    } catch (error) {
+      return true;
+    }
+  }
+  /**
+   * Populate the background layer list with individual layers
+   */
+  populateBackgroundLayerList(container) {
+    container.innerHTML = "";
+    const styleLayers = this.map.getStyle().layers || [];
+    styleLayers.forEach((layer) => {
+      if (!this.isUserAddedLayer(layer.id)) {
+        if (this.state.onlyRenderedFilter && !this.isLayerRendered(layer.id)) {
+          return;
+        }
+        const layerRow = document.createElement("div");
+        layerRow.className = "background-legend-layer-row";
+        layerRow.setAttribute("data-background-layer-id", layer.id);
+        const checkbox = document.createElement("input");
+        checkbox.type = "checkbox";
+        checkbox.className = "background-legend-checkbox";
+        const visibility = this.map.getLayoutProperty(layer.id, "visibility");
+        const isVisible = visibility !== "none";
+        checkbox.checked = isVisible;
+        this.state.backgroundLayerVisibility.set(layer.id, isVisible);
+        checkbox.addEventListener("change", () => {
+          this.toggleIndividualBackgroundLayer(layer.id, checkbox.checked);
+        });
+        const name = document.createElement("span");
+        name.className = "background-legend-layer-name";
+        name.textContent = this.generateFriendlyName(layer.id);
+        name.title = layer.id;
+        const typeIndicator = document.createElement("span");
+        typeIndicator.className = "background-legend-layer-type";
+        typeIndicator.textContent = layer.type;
+        layerRow.appendChild(checkbox);
+        layerRow.appendChild(name);
+        layerRow.appendChild(typeIndicator);
+        container.appendChild(layerRow);
+      }
+    });
+    if (container.children.length === 0) {
+      const emptyMsg = document.createElement("p");
+      emptyMsg.className = "background-legend-empty";
+      emptyMsg.textContent = this.state.onlyRenderedFilter ? "No rendered layers in current view." : "No background layers found.";
+      container.appendChild(emptyMsg);
+    }
+  }
+  /**
+   * Toggle visibility of an individual background layer
+   */
+  toggleIndividualBackgroundLayer(layerId, visible) {
+    this.state.backgroundLayerVisibility.set(layerId, visible);
+    this.map.setLayoutProperty(layerId, "visibility", visible ? "visible" : "none");
+    this.updateBackgroundCheckboxState();
+  }
+  /**
+   * Set visibility for all background layers
+   */
+  setAllBackgroundLayersVisibility(visible) {
+    const styleLayers = this.map.getStyle().layers || [];
+    styleLayers.forEach((layer) => {
+      if (!this.isUserAddedLayer(layer.id)) {
+        this.state.backgroundLayerVisibility.set(layer.id, visible);
+        this.map.setLayoutProperty(layer.id, "visibility", visible ? "visible" : "none");
+      }
+    });
+    const legendPanel = this.panel.querySelector(".layer-control-background-legend");
+    if (legendPanel) {
+      const checkboxes = legendPanel.querySelectorAll(".background-legend-checkbox");
+      checkboxes.forEach((checkbox) => {
+        checkbox.checked = visible;
+      });
+    }
+    this.updateBackgroundCheckboxState();
+  }
+  /**
+   * Update the main Background checkbox based on individual layer states
+   */
+  updateBackgroundCheckboxState() {
+    const styleLayers = this.map.getStyle().layers || [];
+    let anyVisible = false;
+    let allVisible = true;
+    styleLayers.forEach((layer) => {
+      if (!this.isUserAddedLayer(layer.id)) {
+        const visible = this.state.backgroundLayerVisibility.get(layer.id);
+        if (visible === true) anyVisible = true;
+        if (visible === false) allVisible = false;
+      }
+    });
+    const backgroundItem = this.panel.querySelector('[data-layer-id="Background"]');
+    if (backgroundItem) {
+      const checkbox = backgroundItem.querySelector(".layer-control-checkbox");
+      if (checkbox) {
+        checkbox.checked = anyVisible;
+        checkbox.indeterminate = anyVisible && !allVisible;
+      }
+    }
+    if (this.state.layerStates["Background"]) {
+      this.state.layerStates["Background"].visible = anyVisible;
+    }
+  }
   /**
    * Create style button for a layer
    */