Upload 2 files

depth_interactive_map_alpha.R

@@ -864,6 +864,11 @@ WEB_SPEC <- list(
 # --- Lucide icons + JS helpers --------------------------------------------------
 LUCIDE_JS <- tags$head(
   tags$script(src = "https://unpkg.com/lucide@latest/dist/umd/lucide.min.js"),
+  # Driver.js -- guided spotlight tour (MIT). unpkg matches Lucide's origin so
+  # the same CSP allowlist covers it. Drives existing DOM elements; no R logic.
+  tags$link(rel = "stylesheet",
+            href = "https://unpkg.com/driver.js@1.3.1/dist/driver.css"),
+  tags$script(src = "https://unpkg.com/driver.js@1.3.1/dist/driver.js.iife.js"),
   tags$script(HTML("
     // gridMenuOpen = is the N4-N8 resolution menu visible (purely visual);
     // gridActive   = is the grid overlay currently shown on the map.
@@ -910,6 +915,13 @@ LUCIDE_JS <- tags$head(
           Shiny.setInputValue('grid_nivel',  '6',             { priority: 'event' });
         }, 300);
 
+        // First-visit auto-tour: wait for the map to settle, then run once.
+        try {
+          if (!localStorage.getItem('depth_tour_seen')) {
+            setTimeout(function() { if (window.startTour) window.startTour(); }, 1200);
+          }
+        } catch (e) {}
+
         // Hook up the native draw buttons so our custom ones can mirror their
         // active state. Retries until mapgl has mounted the draw control.
         var navTries = 0;
@@ -955,6 +967,99 @@ LUCIDE_JS <- tags$head(
       if (tip) tip.style.display = 'none';
     }
 
+    // -- Guided spotlight tour (Driver.js) --------------------------------------
+    // Highlights the real controls one step at a time. Auto-runs once on first
+    // visit (localStorage flag); the nav '?' button replays it on demand.
+    // Some targets live in collapsed panels, so steps open them on enter and
+    // restore them on leave; onDestroyed guarantees nothing is left open.
+    var _tourLayersOpened = false;
+
+    function _isLayersOpen() {
+      var body = document.getElementById('layer-ctrl-body');
+      return !!(body && body.style.display !== 'none');
+    }
+    function _restoreLayers() {
+      if (_tourLayersOpened && _isLayersOpen()) toggleLayerPanel();
+      _tourLayersOpened = false;
+    }
+
+    function startTour() {
+      if (!window.driver || !window.driver.js) return;
+      var driver = window.driver.js.driver;
+
+      var d = driver({
+        showProgress: true,
+        allowClose: true,
+        overlayOpacity: 0.6,
+        nextBtnText: 'Next',
+        prevBtnText: 'Back',
+        doneBtnText: 'Done',
+        onDestroyed: function() {
+          _restoreLayers();
+          try { localStorage.setItem('depth_tour_seen', '1'); } catch (e) {}
+        },
+        steps: [
+          { popover: {
+              title: 'Welcome to DEPTH',
+              description: 'An interactive map of migration risk in Mexico. This quick tour points out what each control does -- about 60 seconds. Use Next, or close it any time.'
+          }},
+          { element: '#nav-search-wrap', popover: {
+              title: 'Search',
+              description: 'Jump to a place, municipality, or exact coordinates (e.g. \"19.43,-99.13\").',
+              side: 'bottom', align: 'start'
+          }},
+          { element: '#home_btn', popover: {
+              title: 'Overview',
+              description: 'Reset the map back to the full view of Mexico at any point.',
+              side: 'bottom', align: 'end'
+          }},
+          { element: '#nav-tools-select', popover: {
+              title: 'Select an area to analyse',
+              description: 'Draw a lasso, box, circle or line -- or click a single municipality. The sidebar then summarises every indicator inside your selection.',
+              side: 'bottom', align: 'center'
+          }},
+          { element: '#btn_state_filter', popover: {
+              title: 'Filter by state',
+              description: 'Restrict the analysis to one Mexican state.',
+              side: 'bottom', align: 'center'
+          }},
+          { element: '#grid-icon-btn', popover: {
+              title: 'Spatial grid',
+              description: 'Overlay an equal-cell grid and switch resolution from N4 (national overview) to N7 (local detail). Grid colours follow the active layer.',
+              side: 'bottom', align: 'center'
+          }},
+          { element: '.style-btn-wrap', popover: {
+              title: 'Basemap',
+              description: 'Switch the background map between light, dark, and a labelled style.',
+              side: 'bottom', align: 'center'
+          }},
+          { element: '#toggle_3d', popover: {
+              title: '2D / 3D',
+              description: 'Tilt the map into a 3D perspective view.',
+              side: 'bottom', align: 'end'
+          }},
+          { element: '#layer-ctrl-body', popover: {
+              title: 'Data layers',
+              description: 'Turn indicators on and off here. They are grouped into Hazards, Exposure and Vulnerability. Each layer has a short description and its own legend.',
+              side: 'right', align: 'start'
+            },
+            onHighlightStarted: function() {
+              if (!_isLayersOpen()) { toggleLayerPanel(); _tourLayersOpened = true; }
+            },
+            onDeselected: function() { _restoreLayers(); }
+          },
+          { element: '#panel-tmri', popover: {
+              title: 'Analysis sidebar',
+              description: 'Live totals, charts over time, and breakdowns for whatever you have selected -- plus a button to download the selection as an .xlsx spreadsheet.',
+              side: 'left', align: 'start'
+          }}
+        ]
+      });
+
+      d.drive();
+    }
+    window.startTour = startTour;
+
     function clearDrawing() {
       var btn = document.getElementById('clear_btn');
       if (btn) btn.click();
@@ -1862,10 +1967,10 @@ ui <- page_fillable(
                   class        = "grid-nivel-item",
                   `data-nivel` = nv,
                   onclick      = paste0("setGridNivel('", nv, "')"),
-                  `aria-label` = paste0("Set grid to ", info$name, ", ", info$size, " squared, ", info$desc),
+                  `aria-label` = paste0("Set grid to ", info$name, ", ", info$size, ", ", info$desc),
                   div(class = "grid-nivel-item-row",
                       span(class = "grid-nivel-item-name", paste0("N", nv, " ", info$name)),
-                      span(class = "grid-nivel-item-size", paste0(info$size, "²"))),
+                      span(class = "grid-nivel-item-size", info$size)),
                   div(class = "grid-nivel-item-desc", info$desc)
                 )
               })
@@ -1876,7 +1981,7 @@ ui <- page_fillable(
                           title = "Coming soon",
                           div(class = "grid-nivel-item-row",
                               span(class = "grid-nivel-item-name", paste0("N", nv)),
-                              span(class = "grid-nivel-item-size", "~0.8 km²")),
+                              span(class = "grid-nivel-item-size", "~1.3 km cell length")),
                           div(class = "grid-nivel-item-desc", "High resolution")))
         )
       ),
@@ -1907,7 +2012,14 @@ ui <- page_fillable(
       actionButton("toggle_3d", class = "nav-btn",
                    `aria-label` = "Toggle 2D / 3D view",
                    title        = "Toggle 2D / 3D",
-                   HTML('<i data-lucide="box" style="width:16px;height:16px;stroke-width:2"></i>'))
+                   HTML('<i data-lucide="box" style="width:16px;height:16px;stroke-width:2"></i>')),
+
+      # Guided tour replay
+      tags$button(class = "nav-btn", type = "button",
+                  onclick      = "startTour()",
+                  `aria-label` = "Take a guided tour",
+                  title        = "Take a guided tour",
+                  HTML('<i data-lucide="circle-help" style="width:16px;height:16px;stroke-width:2"></i>'))
     ),
 
     div(class = "nav-divider"),

styles.css

@@ -2389,3 +2389,43 @@ button.mapbox-gl-draw_uncombine { display: none !important; }
   color: var(--c-text);
   letter-spacing: -0.01em;
 }
+
+/* --- Guided tour (Driver.js) -------------------------------------------------
+   Theme the spotlight popover to the DEPTH brand. Driver.js sets its own high
+   z-index on the overlay/popover; we keep it above the maplibre canvas. */
+.driver-popover.depth-popover,
+.driver-popover {
+  background: #fff;
+  color: var(--c-text);
+  border: 1px solid var(--c-border-str);
+  border-radius: 10px;
+  box-shadow: 0 10px 30px rgba(3, 36, 37, 0.18);
+  max-width: 320px;
+}
+.driver-popover .driver-popover-title {
+  font-weight: 700;
+  color: var(--c-text);
+}
+.driver-popover .driver-popover-description {
+  color: var(--c-text-mid);
+  line-height: 1.45;
+}
+.driver-popover .driver-popover-progress-text {
+  color: var(--c-text-dim);
+}
+.driver-popover .driver-popover-navigation-btns button {
+  background: var(--c-accent);
+  color: #fff;
+  text-shadow: none;
+  border: none;
+  border-radius: 6px;
+  font-weight: 600;
+}
+.driver-popover .driver-popover-navigation-btns button.driver-popover-prev-btn {
+  background: transparent;
+  color: var(--c-text-mid);
+  border: 1px solid var(--c-border);
+}
+.driver-popover .driver-popover-close-btn {
+  color: var(--c-text-dim);
+}