Fix Issue #14: Add marker clustering for large environments

- Implement grid-based clustering for 100+ locations
- Cluster markers automatically adapt to zoom level
- Click clusters to zoom in and see individual markers
- Add progressive loading indicators with status messages
- Optimize rendering with canvas mode (already enabled)
- All 63 tests pass successfully

Co-authored-by: Jackass4life <94110786+Jackass4life@users.noreply.github.com>
Agent-Logs-Url: https://github.com/Jackass4life/Nautobot-maps/sessions/a0e87b75-c988-42b6-bdab-398d68553075

Author: Claude

README.md

@@ -6,6 +6,16 @@ A web application that displays Nautobot locations on an interactive OpenStreetM
 
 - 🗺️ Interactive map showing all Nautobot locations that have GPS coordinates
 - 📍 Color-coded markers by status (Active / Planned / Other)
+- 🔍 **Filtering** locations by:
+  - Status (Active, Planned, etc.)
+  - Location Type
+  - Parent Location (hierarchical)
+  - Tenant
+- ⚡ **Performance optimizations** for large environments:
+  - Automatic marker clustering for 100+ locations
+  - Grid-based clustering that adapts to zoom level
+  - Canvas rendering for improved performance
+  - Progressive loading indicators
 - 🖱️ Click a marker to see a popup with:
   - Location name, type, status, tenant, time zone, and physical address
   - ASN(s) assigned to the location

static/js/map.js

@@ -158,15 +158,17 @@ function renderDetail(locId, detail) {
 // ---------------------------------------------------------------------------
 const markerLayer = L.layerGroup().addTo(map);
 let allLocations = [];
+const CLUSTER_THRESHOLD = 100; // Use clustering if more than 100 locations
 
 async function loadLocations() {
-  showLoading(true);
+  showLoading(true, "Loading locations from Nautobot…");
   try {
     const resp = await fetch("/api/locations");
     if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
     const data = await resp.json();
     if (data.error) throw new Error(data.error);
     allLocations = data.locations || [];
+    showLoading(true, `Processing ${allLocations.length} locations…`);
     populateFilters(allLocations);
     applyFilters();
   } catch (err) {
@@ -203,22 +205,107 @@ function renderMarkers(locations, searchMarker) {
     }).addTo(markerLayer);
   }
 
+  // Use clustering for large datasets
+  if (locations.length > CLUSTER_THRESHOLD && !searchMarker) {
+    renderMarkersWithClustering(locations);
+  } else {
+    renderMarkersSimple(locations);
+  }
+}
+
+function renderMarkersSimple(locations) {
   for (const loc of locations) {
-    const marker = L.marker([loc.latitude, loc.longitude], {
-      icon: iconForStatus(loc.status),
-      title: loc.name,
-    });
+    addMarker(loc);
+  }
+}
 
-    marker.bindPopup(() => buildBasicPopup(loc), { maxWidth: 320, minWidth: 240 });
+function renderMarkersWithClustering(locations) {
+  // Simple grid-based clustering
+  // Group markers by zoom level grid cells
+  const currentZoom = map.getZoom();
+  const gridSize = currentZoom < 5 ? 2 : currentZoom < 8 ? 1 : 0.5;
 
-    marker.on("popupopen", () => {
-      fetchAndRenderDetail(loc.id);
-    });
+  const clusters = {};
 
-    marker.addTo(markerLayer);
+  for (const loc of locations) {
+    const gridLat = Math.floor(loc.latitude / gridSize) * gridSize;
+    const gridLon = Math.floor(loc.longitude / gridSize) * gridSize;
+    const key = `${gridLat},${gridLon}`;
+
+    if (!clusters[key]) {
+      clusters[key] = [];
+    }
+    clusters[key].push(loc);
+  }
+
+  // Render clusters or individual markers
+  for (const key in clusters) {
+    const group = clusters[key];
+
+    if (group.length === 1) {
+      // Single marker
+      addMarker(group[0]);
+    } else if (currentZoom < 8) {
+      // Create cluster marker
+      const lat = group.reduce((sum, l) => sum + l.latitude, 0) / group.length;
+      const lon = group.reduce((sum, l) => sum + l.longitude, 0) / group.length;
+
+      const clusterIcon = L.divIcon({
+        html: `<div style="width:40px;height:40px;background:#3388ff;color:white;border:3px solid #fff;border-radius:50%;display:flex;align-items:center;justify-content:center;font-weight:bold;box-shadow:0 0 8px rgba(0,0,0,.4)">${group.length}</div>`,
+        iconSize: [40, 40],
+        iconAnchor: [20, 20],
+        className: "",
+      });
+
+      const clusterMarker = L.marker([lat, lon], { icon: clusterIcon });
+      clusterMarker.on('click', () => {
+        // Zoom in to show individual markers
+        map.setView([lat, lon], Math.min(currentZoom + 3, 15));
+      });
+
+      const locations = group.map(l => `<li>${escHtml(l.name)}</li>`).slice(0, 10).join('');
+      const more = group.length > 10 ? `<li style="color:#888">… and ${group.length - 10} more</li>` : '';
+      clusterMarker.bindPopup(
+        `<div class="popup-content">
+          <div class="popup-title">${group.length} locations</div>
+          <div style="font-size:0.85rem;margin-top:8px">Click to zoom in</div>
+          <ul style="margin:8px 0 0 0;padding-left:20px;font-size:0.8rem;max-height:150px;overflow-y:auto">
+            ${locations}${more}
+          </ul>
+        </div>`
+      );
+      clusterMarker.addTo(markerLayer);
+    } else {
+      // Zoom level high enough, show individual markers
+      for (const loc of group) {
+        addMarker(loc);
+      }
+    }
   }
 }
 
+function addMarker(loc) {
+  const marker = L.marker([loc.latitude, loc.longitude], {
+    icon: iconForStatus(loc.status),
+    title: loc.name,
+  });
+
+  marker.bindPopup(() => buildBasicPopup(loc), { maxWidth: 320, minWidth: 240 });
+
+  marker.on("popupopen", () => {
+    fetchAndRenderDetail(loc.id);
+  });
+
+  marker.addTo(markerLayer);
+}
+
+// Re-cluster on zoom
+map.on('zoomend', () => {
+  if (allLocations.length > CLUSTER_THRESHOLD) {
+    applyFilters();
+  }
+});
+
 async function fetchAndRenderDetail(locId) {
   try {
     const resp = await fetch(`/api/locations/${encodeURIComponent(locId)}/detail`);
@@ -381,10 +468,15 @@ searchInput.addEventListener("input", () => {
 // ---------------------------------------------------------------------------
 // UI helpers
 // ---------------------------------------------------------------------------
-function showLoading(visible) {
-  document.getElementById("loading-overlay").style.display = visible
-    ? "flex"
-    : "none";
+function showLoading(visible, message) {
+  const overlay = document.getElementById("loading-overlay");
+  const text = document.getElementById("loading-text");
+  if (message) {
+    text.textContent = message;
+  } else {
+    text.textContent = "Loading locations from Nautobot…";
+  }
+  overlay.style.display = visible ? "flex" : "none";
 }
 
 function showError(message) {