maplibre-gl-layer-control 0.15.1 → 0.16.0

package/README.md

@@ -24,6 +24,7 @@ A comprehensive layer control for MapLibre GL with advanced styling capabilities
 - ✅ **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
+- ✅ **Saved configurations** - Save the current basemap element visibility as a named preset and re-apply it with one click; presets persist across sessions and projects via `localStorage`
 - ✅ **Accessibility** - Full ARIA support and keyboard navigation
 - ✅ **TypeScript** - Full type safety and IntelliSense support
 - ✅ **React integration** - Optional React components and hooks
@@ -175,6 +176,9 @@ function MapComponent() {
 | `excludeLayers` | `string[]` | `undefined` | Array of wildcard patterns to exclude layers by name (e.g., `['*-temp-*', 'debug-*']`) |
 | `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) |
+| `enableBackgroundPresets` | `boolean` | `true` | Show the "Saved configurations" controls in the Background Layers panel |
+| `backgroundPresetStorageKey` | `string` | `'maplibre-layer-control:background-presets'` | `localStorage` key under which background visibility presets are stored |
+| `onBackgroundPresetsChange` | `(presets: BackgroundPresets) => void` | `undefined` | Called whenever the saved preset set changes (created or deleted); applying a preset does not change the set, so it does not fire |
 
 ### LayerState
 
@@ -293,9 +297,31 @@ When using the `layers` option to specify specific layers, all other layers are
 - 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
+- **Saved configurations** - Save the current set of visibility toggles as a named preset and re-apply it later with one click
 
 This allows fine-grained control over which basemap layers are visible while maintaining a simplified layer control interface.
 
+#### Saved configurations (presets)
+
+The Background Layers panel includes a **Saved configurations** section that lets users save the current basemap element visibility as a named preset and re-apply it with a single click. Presets are stored in `localStorage`, so they persist across page reloads and apply to any project that uses the same basemap layers. Toggle the UI off with `enableBackgroundPresets: false`, or change the storage location with `backgroundPresetStorageKey`.
+
+The same functionality is available programmatically:
+
+```javascript
+// Capture the current basemap element visibility
+const visibility = layerControl.getBackgroundLayerVisibility();
+// → { 'water': true, 'road-primary': false, ... }
+
+// Apply a configuration (only layers present in the style are affected)
+layerControl.applyBackgroundLayerVisibility(visibility);
+
+// Named presets (persisted to localStorage)
+layerControl.saveBackgroundPreset('Minimal');   // save current visibility
+layerControl.getBackgroundPresets();            // → { Minimal: { ... } }
+layerControl.applyBackgroundPreset('Minimal');  // → true if it existed
+layerControl.deleteBackgroundPreset('Minimal');
+```
+
 ### Custom Layer Adapters
 
 The layer control supports non-MapLibre layers (such as deck.gl or Zarr layers) through the Custom Layer Adapter interface. This allows you to integrate any custom layer type with the layer control's visibility toggle, opacity slider, and layer list.

package/dist/index.cjs

@@ -730,6 +730,10 @@ class LayerControl {
     __publicField(this, "onLayerRename");
     __publicField(this, "onLayerReorder");
     __publicField(this, "onLayerRemove");
+    // Background-layer visibility presets
+    __publicField(this, "enableBackgroundPresets");
+    __publicField(this, "backgroundPresetStorageKey");
+    __publicField(this, "onBackgroundPresetsChange");
     this.minPanelWidth = options.panelMinWidth || 240;
     this.maxPanelWidth = options.panelMaxWidth || 420;
     this.initialPanelWidth = options.panelWidth || 350;
@@ -746,6 +750,9 @@ class LayerControl {
     this.onLayerRename = options.onLayerRename;
     this.onLayerReorder = options.onLayerReorder;
     this.onLayerRemove = options.onLayerRemove;
+    this.enableBackgroundPresets = options.enableBackgroundPresets !== false;
+    this.backgroundPresetStorageKey = options.backgroundPresetStorageKey || "maplibre-layer-control:background-presets";
+    this.onBackgroundPresetsChange = options.onBackgroundPresetsChange;
     this.initialLayerStates = options.layerStates || {};
     this.state = {
       collapsed: options.collapsed !== false,
@@ -2234,8 +2241,112 @@ class LayerControl {
     panel.appendChild(actionsRow);
     panel.appendChild(filterRow);
     panel.appendChild(layerList);
+    if (this.enableBackgroundPresets) {
+      panel.appendChild(this.createBackgroundPresetsRow());
+    }
     return panel;
   }
+  /**
+   * Build the "Saved configurations" controls: a dropdown of saved presets with
+   * Apply/Delete actions, plus a name field and Save button to capture the
+   * current basemap element visibility as a reusable, persisted preset.
+   */
+  createBackgroundPresetsRow() {
+    const section = document.createElement("div");
+    section.className = "background-legend-presets";
+    const label = document.createElement("div");
+    label.className = "background-legend-presets-label";
+    label.textContent = "Saved configurations";
+    section.appendChild(label);
+    const selectRow = document.createElement("div");
+    selectRow.className = "background-legend-presets-row";
+    const select = document.createElement("select");
+    select.className = "background-legend-presets-select";
+    select.title = "Saved configurations";
+    const applyBtn = document.createElement("button");
+    applyBtn.className = "background-legend-action-btn";
+    applyBtn.textContent = "Apply";
+    applyBtn.title = "Apply the selected configuration";
+    const deleteBtn = document.createElement("button");
+    deleteBtn.className = "background-legend-action-btn";
+    deleteBtn.textContent = "Delete";
+    deleteBtn.title = "Delete the selected configuration";
+    const refreshSelect = (selected) => {
+      const presets = this.getBackgroundPresets();
+      const names = Object.keys(presets).sort(
+        (a, b) => a.localeCompare(b, void 0, { sensitivity: "base" })
+      );
+      select.innerHTML = "";
+      const placeholder = document.createElement("option");
+      placeholder.value = "";
+      placeholder.textContent = names.length ? "Select a configuration…" : "No saved configurations";
+      placeholder.disabled = names.length > 0;
+      select.appendChild(placeholder);
+      names.forEach((name) => {
+        const option = document.createElement("option");
+        option.value = name;
+        option.textContent = name;
+        select.appendChild(option);
+      });
+      select.value = selected && names.includes(selected) ? selected : "";
+      const hasSelection = select.value !== "";
+      applyBtn.disabled = !hasSelection;
+      deleteBtn.disabled = !hasSelection;
+    };
+    select.addEventListener("change", () => {
+      const hasSelection = select.value !== "";
+      applyBtn.disabled = !hasSelection;
+      deleteBtn.disabled = !hasSelection;
+    });
+    applyBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      if (select.value) this.applyBackgroundPreset(select.value);
+    });
+    deleteBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      if (select.value) {
+        this.deleteBackgroundPreset(select.value);
+        refreshSelect();
+      }
+    });
+    selectRow.appendChild(select);
+    selectRow.appendChild(applyBtn);
+    selectRow.appendChild(deleteBtn);
+    const saveRow = document.createElement("div");
+    saveRow.className = "background-legend-presets-row";
+    const nameInput = document.createElement("input");
+    nameInput.type = "text";
+    nameInput.className = "background-legend-presets-input";
+    nameInput.placeholder = "Configuration name…";
+    nameInput.maxLength = 60;
+    const saveBtn = document.createElement("button");
+    saveBtn.className = "background-legend-action-btn";
+    saveBtn.textContent = "Save";
+    saveBtn.title = "Save the current visibility as a configuration";
+    const commitSave = () => {
+      const name = nameInput.value.trim();
+      if (!name) return;
+      this.saveBackgroundPreset(name);
+      nameInput.value = "";
+      refreshSelect(name);
+    };
+    saveBtn.addEventListener("click", (e) => {
+      e.stopPropagation();
+      commitSave();
+    });
+    nameInput.addEventListener("keydown", (e) => {
+      if (e.key === "Enter") {
+        e.preventDefault();
+        commitSave();
+      }
+    });
+    saveRow.appendChild(nameInput);
+    saveRow.appendChild(saveBtn);
+    section.appendChild(selectRow);
+    section.appendChild(saveRow);
+    refreshSelect();
+    return section;
+  }
   /**
    * Check if a layer is currently rendered in the map viewport
    */
@@ -2383,6 +2494,147 @@ class LayerControl {
       this.state.layerStates["Background"].visible = anyVisible;
     }
   }
+  /**
+   * Return the IDs of the background (basemap) style layers the control can
+   * toggle, honoring the drawn-layer and user-defined exclusion filters but not
+   * the transient "only rendered" view filter.
+   */
+  getControllableBackgroundLayerIds() {
+    const styleLayers = this.map.getStyle().layers || [];
+    return styleLayers.filter((layer) => {
+      if (this.isUserAddedLayer(layer.id)) return false;
+      if (this.excludeDrawnLayers && this.isDrawnLayer(layer.id)) return false;
+      if (this.isExcludedByPattern(layer.id)) return false;
+      return true;
+    }).map((layer) => layer.id);
+  }
+  /**
+   * Get the current visibility of every controllable background (basemap) layer.
+   *
+   * @returns A map of style-layer ID to whether it is currently visible.
+   */
+  getBackgroundLayerVisibility() {
+    const visibility = {};
+    for (const layerId of this.getControllableBackgroundLayerIds()) {
+      const value = this.map.getLayoutProperty(layerId, "visibility");
+      visibility[layerId] = value !== "none";
+    }
+    return visibility;
+  }
+  /**
+   * Apply a saved background-layer visibility configuration to the map. Only
+   * layers that currently exist in the style are affected, so a configuration
+   * captured on one basemap degrades gracefully when applied to another.
+   *
+   * @param visibility - Map of style-layer ID to desired visibility.
+   */
+  applyBackgroundLayerVisibility(visibility) {
+    for (const [layerId, visible] of Object.entries(visibility)) {
+      if (this.isUserAddedLayer(layerId)) continue;
+      if (!this.map.getLayer(layerId)) continue;
+      this.state.backgroundLayerVisibility.set(layerId, visible);
+      this.map.setLayoutProperty(
+        layerId,
+        "visibility",
+        visible ? "visible" : "none"
+      );
+    }
+    const legendPanel = this.panel.querySelector(
+      ".background-legend-layer-list"
+    );
+    if (legendPanel) {
+      this.populateBackgroundLayerList(legendPanel);
+    }
+    this.updateBackgroundCheckboxState();
+  }
+  /**
+   * Read all saved background-layer presets from localStorage. Returns an empty
+   * object when storage is unavailable or the stored value is malformed.
+   */
+  getBackgroundPresets() {
+    try {
+      const raw = typeof localStorage !== "undefined" ? localStorage.getItem(this.backgroundPresetStorageKey) : null;
+      if (!raw) return {};
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        return {};
+      }
+      const presets = {};
+      for (const [name, value] of Object.entries(parsed)) {
+        if (this.isUnsafePresetKey(name)) continue;
+        if (value && typeof value === "object" && !Array.isArray(value)) {
+          presets[name] = value;
+        }
+      }
+      return presets;
+    } catch {
+      return {};
+    }
+  }
+  /**
+   * Reject preset names that, used as object keys, could pollute the prototype
+   * chain or otherwise alias built-in object members.
+   */
+  isUnsafePresetKey(name) {
+    return name === "__proto__" || name === "constructor" || name === "prototype";
+  }
+  /**
+   * Persist the full preset map to localStorage and notify listeners.
+   */
+  writeBackgroundPresets(presets) {
+    var _a;
+    try {
+      if (typeof localStorage !== "undefined") {
+        localStorage.setItem(
+          this.backgroundPresetStorageKey,
+          JSON.stringify(presets)
+        );
+      }
+    } catch {
+    }
+    (_a = this.onBackgroundPresetsChange) == null ? void 0 : _a.call(this, presets);
+  }
+  /**
+   * Save the current background-layer visibility as a named preset. Reusing an
+   * existing name overwrites that preset.
+   *
+   * @param name - Preset name; whitespace is trimmed. Empty names are ignored.
+   * @returns The updated preset map.
+   */
+  saveBackgroundPreset(name) {
+    const trimmed = name.trim();
+    const presets = this.getBackgroundPresets();
+    if (!trimmed || this.isUnsafePresetKey(trimmed)) return presets;
+    presets[trimmed] = this.getBackgroundLayerVisibility();
+    this.writeBackgroundPresets(presets);
+    return presets;
+  }
+  /**
+   * Apply a previously saved preset to the map.
+   *
+   * @param name - The preset name to apply.
+   * @returns `true` if a preset with that name existed and was applied.
+   */
+  applyBackgroundPreset(name) {
+    const presets = this.getBackgroundPresets();
+    if (!Object.prototype.hasOwnProperty.call(presets, name)) return false;
+    this.applyBackgroundLayerVisibility(presets[name]);
+    return true;
+  }
+  /**
+   * Delete a saved preset.
+   *
+   * @param name - The preset name to remove.
+   * @returns The updated preset map.
+   */
+  deleteBackgroundPreset(name) {
+    const presets = this.getBackgroundPresets();
+    if (Object.prototype.hasOwnProperty.call(presets, name)) {
+      delete presets[name];
+      this.writeBackgroundPresets(presets);
+    }
+    return presets;
+  }
   /**
    * Create style button for a layer
    */