@djangocfg/ui-tools 2.1.431 → 2.1.433

package/src/tools/dev/Map/components/MapContainer/MapInner.tsx

@@ -0,0 +1,326 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState, type ComponentType } from 'react'
+import Map, {
+  type ViewStateChangeEvent,
+  type GeolocateControlInstance,
+} from 'react-map-gl/maplibre'
+import 'maplibre-gl/dist/maplibre-gl.css'
+
+import { useMapContext } from '../../context'
+import { useCompass, useMapScrollProtection, useMapTouchMode, useTerrain } from '../../hooks'
+import { MapToolbar } from './MapToolbar'
+import { ScrollLockOverlay } from './ScrollLockOverlay'
+import { RotateHint } from './RotateHint'
+import { FullscreenDialog } from './FullscreenDialog'
+import { GeolocateHandle, type GeolocateState } from './GeolocateHandle'
+import { GeocoderControl } from '../GeocoderControl'
+import { useBasemapState } from './hooks/useBasemapState'
+import { useExternalMapsUrl } from './hooks/useExternalMapsUrl'
+import { useAutoReset } from './hooks/useAutoReset'
+import type { MapContainerProps, MapInnerProps } from './types'
+
+export function MapInner({
+  children,
+  mapStyle = 'light',
+  interactiveLayerIds,
+  style,
+  cursor,
+  attributionControl = false,
+  // `reuseMaps` pools maplibre instances across mounts. It saves init cost
+  // but in practice (Storybook HMR, switching stories, chat lists mounting/
+  // unmounting map blocks) a reused instance comes back with no style —
+  // a blank white map that never requests its style.json. Default OFF for
+  // correctness; opt back in for a single long-lived full-page map.
+  reuseMaps = false,
+  openInMapsUrl,
+  openInMapsLabel = 'Open in Maps',
+  googleMapsButton = true,
+  autoResetDelay = 0,
+  showResetButton = false,
+  scrollProtection = true,
+  scrollProtectionHint = 'Click to interact',
+  fullscreenButton = true,
+  fullscreenLabel = 'Expand map',
+  fullscreenTitle = 'Map',
+  basemapSwitcher = true,
+  basemaps,
+  basemapLabel = 'Map style',
+  onBasemapChange,
+  terrain = false,
+  terrainButton = true,
+  terrainLabel = '3D terrain',
+  onTerrainChange,
+  compassButton = true,
+  compassLabel = 'Reset bearing to north',
+  geolocate = false,
+  geolocateLabel = 'Show your location',
+  geolocateOptions,
+  onGeolocate,
+  onGeolocateError,
+  geocoder = false,
+  geocoderResolve,
+  geocoderPlaceholder,
+  onGeocoderResult,
+  onClose,
+  ariaLabel = 'Interactive map',
+  MapContainerComponent,
+}: MapInnerProps & { MapContainerComponent: ComponentType<MapContainerProps> }) {
+  const { mapRef, viewport, setViewport, setIsLoaded, resetToInitial, initialViewport } = useMapContext()
+
+  // Active basemap — seeded from `mapStyle`, then driven by the switcher.
+  const { activeKey, effectiveStyle, resolvedStyle, basemapOptions, handleBasemapPick } =
+    useBasemapState({ mapStyle, basemaps, onBasemapChange })
+
+  // 3D terrain — seeded from the `terrain` prop, then driven by the chip.
+  const [terrainOn, setTerrainOn] = useState(terrain)
+  useEffect(() => setTerrainOn(terrain), [terrain])
+  useTerrain({ enabled: terrainOn })
+
+  // Brief gesture hint when 3D turns on — rotation/tilt isn't discoverable
+  // (it's right-drag / Ctrl+drag), so surface it, then auto-hide.
+  const [showRotateHint, setShowRotateHint] = useState(false)
+  useEffect(() => {
+    if (!terrainOn) {
+      setShowRotateHint(false)
+      return
+    }
+    setShowRotateHint(true)
+    const t = setTimeout(() => setShowRotateHint(false), 4500)
+    return () => clearTimeout(t)
+  }, [terrainOn])
+  const handleTerrainToggle = useCallback(() => {
+    setTerrainOn((prev) => {
+      const next = !prev
+      onTerrainChange?.(next)
+      return next
+    })
+  }, [onTerrainChange])
+
+  // Compass — reset the camera to a north-up, top-down view. Google-style:
+  // the chip only shows when the view is rotated or tilted, and its needle
+  // rotates to reflect the current bearing. One click eases back to north.
+  // Math/reset live in `useCompass`; the toolbar gates the chip on it.
+  const { bearing, isOriented, resetNorth } = useCompass()
+
+  // Locate-me (GPS). Drives maplibre's built-in GeolocateControl via its
+  // instance ref; the chip calls `trigger()` and reflects active/error from
+  // the control's events. Privacy: the control is only mounted when
+  // `geolocate` is true, and nothing prompts permission until the chip is
+  // pressed (`trigger()`) — never on mount.
+  const geolocateRef = useRef<GeolocateControlInstance | null>(null)
+  const [geolocateState, setGeolocateState] = useState<GeolocateState>('idle')
+  const handleGeolocateTrigger = useCallback(() => {
+    // A new trigger after an error is a retry — clear the disabled look so
+    // the events can re-drive state.
+    setGeolocateState((s) => (s === 'error' ? 'idle' : s))
+    geolocateRef.current?.trigger()
+  }, [])
+
+  // Geocoder search — a toolbar magnifier chip toggles an on-map autocomplete
+  // (Google-Maps style). Collapsed by default; the chip flips `geocoderOpen`,
+  // which mounts the controlled `GeocoderControl` (autofocused). Picking a
+  // result / Esc / re-clicking the chip closes it.
+  const [geocoderOpen, setGeocoderOpen] = useState(false)
+  const handleGeocoderToggle = useCallback(() => setGeocoderOpen((o) => !o), [])
+  const closeGeocoder = useCallback(() => setGeocoderOpen(false), [])
+
+  // External-maps link (host URL wins, else Google Maps at current center).
+  const { externalMapsUrl, externalMapsLabel } = useExternalMapsUrl({
+    openInMapsUrl,
+    openInMapsLabel,
+    googleMapsButton,
+    viewport,
+  })
+
+  // Fullscreen — opens a fresh map in a large dialog, seeded with the
+  // viewport the user is currently looking at.
+  const [fullscreenOpen, setFullscreenOpen] = useState(false)
+
+  // `onClose` is only ever passed to the dialog's own (fullscreen) map, so
+  // it doubles as "this instance is the expanded one" — there gestures are
+  // always live.
+  const isFullscreenInstance = !!onClose
+
+  // Gesture mode. Touch / narrow inline maps are made fully static (a
+  // finger drags the PAGE, never the map); the user taps to expand into
+  // the fullscreen dialog where the map is fully interactive. Desktop
+  // keeps the Google-Maps scroll-isolation. The expanded map is always
+  // live. Detection is `matchMedia`-based so it reacts to DevTools device
+  // emulation, real touchscreens and window resizes (see useMapTouchMode).
+  const isTouch = useMapTouchMode()
+  const protectionMode = !scrollProtection || isFullscreenInstance
+    ? 'off'
+    : isTouch
+      ? 'mobile'
+      : 'desktop'
+
+  const { locked, unlock, isMobileLock } = useMapScrollProtection(protectionMode)
+
+  // Overlay tap: desktop unlocks in place; mobile opens fullscreen.
+  const handleOverlayActivate = useCallback(() => {
+    if (isMobileLock) {
+      setFullscreenOpen(true)
+    } else {
+      unlock()
+    }
+  }, [isMobileLock, unlock])
+
+  // Hint adapts to the gesture model.
+  const resolvedHint = isMobileLock ? 'Tap to expand' : scrollProtectionHint
+
+  // Check if viewport has changed from initial
+  const hasViewportChanged =
+    Math.abs(viewport.longitude - initialViewport.longitude) > 0.0001 ||
+    Math.abs(viewport.latitude - initialViewport.latitude) > 0.0001 ||
+    Math.abs(viewport.zoom - initialViewport.zoom) > 0.1
+
+  const handleMove = useCallback(
+    (evt: ViewStateChangeEvent) => {
+      setViewport({
+        longitude: evt.viewState.longitude,
+        latitude: evt.viewState.latitude,
+        zoom: evt.viewState.zoom,
+        bearing: evt.viewState.bearing,
+        pitch: evt.viewState.pitch,
+      })
+    },
+    [setViewport]
+  )
+
+  const { handleMoveStart, handleMoveEnd } = useAutoReset({ autoResetDelay, resetToInitial })
+
+  const handleLoad = useCallback(() => {
+    setIsLoaded(true)
+  }, [setIsLoaded])
+
+  return (
+    <>
+      <Map
+        ref={mapRef}
+        {...viewport}
+        onMove={handleMove}
+        onMoveStart={handleMoveStart}
+        onMoveEnd={handleMoveEnd}
+        onLoad={handleLoad}
+        mapStyle={resolvedStyle}
+        interactiveLayerIds={interactiveLayerIds}
+        attributionControl={attributionControl ? {} : false}
+        reuseMaps={reuseMaps}
+        style={{
+          width: '100%',
+          height: '100%',
+          ...style,
+        }}
+        cursor={cursor}
+        aria-label={ariaLabel}
+      >
+        {geolocate && (
+          <GeolocateHandle
+            ref={geolocateRef}
+            options={geolocateOptions ?? {}}
+            onGeolocate={onGeolocate}
+            onGeolocateError={onGeolocateError}
+            onStateChange={setGeolocateState}
+          />
+        )}
+        {/* Toolbar-toggled geocoder. Controlled (open driven by the chip),
+            autofocused on reveal. Rendered inside <Map> so its dropped pin
+            (a react-map-gl Marker) has the map context; the input overlay is
+            absolute-positioned top-left, clear of the top-right chip column. */}
+        {geocoder && (
+          <GeocoderControl
+            open={geocoderOpen}
+            onClose={closeGeocoder}
+            autoFocus
+            resolve={geocoderResolve}
+            placeholder={geocoderPlaceholder}
+            onResult={onGeocoderResult}
+          />
+        )}
+        {children}
+      </Map>
+
+      {locked && (
+        <ScrollLockOverlay
+          isMobileLock={isMobileLock}
+          resolvedHint={resolvedHint}
+          onActivate={handleOverlayActivate}
+        />
+      )}
+
+      <MapToolbar
+        onClose={onClose}
+        fullscreenButton={fullscreenButton}
+        fullscreenLabel={fullscreenLabel}
+        onFullscreenOpen={() => setFullscreenOpen(true)}
+        basemapSwitcher={basemapSwitcher}
+        basemapOptions={basemapOptions}
+        basemapLabel={basemapLabel}
+        activeKey={activeKey}
+        onBasemapPick={handleBasemapPick}
+        terrainButton={terrainButton}
+        terrainLabel={terrainLabel}
+        terrainOn={terrainOn}
+        onTerrainToggle={handleTerrainToggle}
+        compassButton={compassButton}
+        isOriented={isOriented}
+        compassLabel={compassLabel}
+        bearing={bearing}
+        onResetNorth={resetNorth}
+        geolocate={geolocate}
+        geolocateLabel={geolocateLabel}
+        geolocateState={geolocateState}
+        onGeolocateTrigger={handleGeolocateTrigger}
+        geocoder={geocoder}
+        geocoderOpen={geocoderOpen}
+        onGeocoderToggle={handleGeocoderToggle}
+        externalMapsUrl={externalMapsUrl}
+        externalMapsLabel={externalMapsLabel}
+        showResetButton={showResetButton}
+        hasViewportChanged={hasViewportChanged}
+        onResetToInitial={resetToInitial}
+      />
+
+      <RotateHint show={showRotateHint} />
+
+      {fullscreenButton && (
+        <FullscreenDialog
+          MapContainer={MapContainerComponent}
+          open={fullscreenOpen}
+          onOpenChange={setFullscreenOpen}
+          fullscreenTitle={fullscreenTitle}
+          viewport={viewport}
+          effectiveStyle={effectiveStyle}
+          interactiveLayerIds={interactiveLayerIds}
+          openInMapsUrl={openInMapsUrl}
+          openInMapsLabel={openInMapsLabel}
+          googleMapsButton={googleMapsButton}
+          basemapSwitcher={basemapSwitcher}
+          basemaps={basemaps}
+          onBasemapChange={onBasemapChange}
+          terrainOn={terrainOn}
+          terrainButton={terrainButton}
+          terrainLabel={terrainLabel}
+          onTerrainChange={onTerrainChange}
+          compassButton={compassButton}
+          compassLabel={compassLabel}
+          geolocate={geolocate}
+          geolocateLabel={geolocateLabel}
+          geolocateOptions={geolocateOptions}
+          onGeolocate={onGeolocate}
+          onGeolocateError={onGeolocateError}
+          geocoder={geocoder}
+          geocoderResolve={geocoderResolve}
+          geocoderPlaceholder={geocoderPlaceholder}
+          onGeocoderResult={onGeocoderResult}
+          showResetButton={showResetButton}
+          ariaLabel={ariaLabel}
+          onClose={() => setFullscreenOpen(false)}
+        >
+          {children}
+        </FullscreenDialog>
+      )}
+    </>
+  )
+}

package/src/tools/dev/Map/components/MapContainer/MapToolbar.tsx

@@ -0,0 +1,286 @@
+'use client'
+
+import { Layers, LocateFixed, MapPin, Maximize2, Mountain, RotateCcw, Search, X } from 'lucide-react'
+import { cn } from '@djangocfg/ui-core/lib'
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components'
+
+import { MAP_STYLE_LABELS } from '../../styles'
+import type { MapStyleKey } from '../../types'
+import { CompassChip } from '../CompassChip'
+import { MAP_CONTROL_CLASS } from './constants'
+import type { GeolocateState } from './GeolocateHandle'
+
+/**
+ * Map controls — one icon-only toolbar, top-right (Google-Maps style). All
+ * chips are a uniform 36×36 square; labels live in tooltips (shown on the LEFT
+ * so they never spill off the map's right edge). Sits above the scroll-lock
+ * overlay so it stays clickable.
+ *
+ * The `data-map-control` attribute is load-bearing: the scroll-protection
+ * re-lock skips clicks inside it.
+ */
+export function MapToolbar({
+  onClose,
+  fullscreenButton,
+  fullscreenLabel,
+  onFullscreenOpen,
+  basemapSwitcher,
+  basemapOptions,
+  basemapLabel,
+  activeKey,
+  onBasemapPick,
+  terrainButton,
+  terrainLabel,
+  terrainOn,
+  onTerrainToggle,
+  compassButton,
+  isOriented,
+  compassLabel,
+  bearing,
+  onResetNorth,
+  geolocate,
+  geolocateLabel,
+  geolocateState,
+  onGeolocateTrigger,
+  geocoder,
+  geocoderOpen,
+  onGeocoderToggle,
+  externalMapsUrl,
+  externalMapsLabel,
+  showResetButton,
+  hasViewportChanged,
+  onResetToInitial,
+}: {
+  onClose: (() => void) | undefined
+  fullscreenButton: boolean
+  fullscreenLabel: string
+  onFullscreenOpen: () => void
+  basemapSwitcher: boolean
+  basemapOptions: MapStyleKey[]
+  basemapLabel: string
+  activeKey: MapStyleKey | undefined
+  onBasemapPick: (key: string) => void
+  terrainButton: boolean
+  terrainLabel: string
+  terrainOn: boolean
+  onTerrainToggle: () => void
+  compassButton: boolean
+  isOriented: boolean
+  compassLabel: string
+  bearing: number
+  onResetNorth: () => void
+  geolocate: boolean
+  geolocateLabel: string
+  geolocateState: GeolocateState
+  onGeolocateTrigger: () => void
+  geocoder: boolean
+  geocoderOpen: boolean
+  onGeocoderToggle: () => void
+  externalMapsUrl: string | undefined
+  externalMapsLabel: string
+  showResetButton: boolean
+  hasViewportChanged: boolean
+  onResetToInitial: () => void
+}) {
+  return (
+    <div
+      data-map-control
+      className="absolute top-3 right-3 z-20 flex flex-col items-end gap-2"
+    >
+      {onClose && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={onClose}
+              aria-label="Close map"
+              className={cn(MAP_CONTROL_CLASS, 'w-9 h-9')}
+            >
+              <X className="w-4 h-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left">Close</TooltipContent>
+        </Tooltip>
+      )}
+
+      {fullscreenButton && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={onFullscreenOpen}
+              aria-label={fullscreenLabel}
+              className={cn(MAP_CONTROL_CLASS, 'w-9 h-9')}
+            >
+              <Maximize2 className="w-4 h-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left">{fullscreenLabel}</TooltipContent>
+        </Tooltip>
+      )}
+
+      {/* Search (geocoder) — Google-Maps-style magnifier that toggles an
+          on-map autocomplete (rendered top-left by MapInner). Tinted
+          text-primary while open; aria-pressed mirrors the open state. */}
+      {geocoder && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={onGeocoderToggle}
+              aria-label="Search the map"
+              aria-pressed={geocoderOpen}
+              className={cn(
+                MAP_CONTROL_CLASS,
+                'w-9 h-9',
+                geocoderOpen && 'bg-popover text-primary',
+              )}
+            >
+              <Search className="w-4 h-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left">
+            {geocoderOpen ? 'Close search' : 'Search'}
+          </TooltipContent>
+        </Tooltip>
+      )}
+
+      {/* Basemap switcher (Google-Maps "Layers") — pick the map style at
+          runtime. Hidden if disabled or there's nothing to switch to. */}
+      {basemapSwitcher && basemapOptions.length > 1 && (
+        <DropdownMenu>
+          <Tooltip>
+            <TooltipTrigger asChild>
+              <DropdownMenuTrigger
+                aria-label={basemapLabel}
+                className={cn(MAP_CONTROL_CLASS, 'w-9 h-9')}
+              >
+                <Layers className="w-4 h-4" aria-hidden="true" />
+              </DropdownMenuTrigger>
+            </TooltipTrigger>
+            <TooltipContent side="left">{basemapLabel}</TooltipContent>
+          </Tooltip>
+          <DropdownMenuContent align="end" side="left" className="min-w-36">
+            <DropdownMenuRadioGroup
+              value={activeKey ?? ''}
+              onValueChange={onBasemapPick}
+            >
+              {basemapOptions.map((key) => (
+                <DropdownMenuRadioItem key={key} value={key}>
+                  {MAP_STYLE_LABELS[key]}
+                </DropdownMenuRadioItem>
+              ))}
+            </DropdownMenuRadioGroup>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      )}
+
+      {/* 3D terrain toggle (Mountain) — adds the free DEM terrain +
+          hillshade and pitches the camera in so it reads as 3D. */}
+      {terrainButton && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={onTerrainToggle}
+              aria-label={terrainLabel}
+              aria-pressed={terrainOn}
+              className={cn(
+                MAP_CONTROL_CLASS,
+                'w-9 h-9',
+                terrainOn && 'bg-popover text-primary',
+              )}
+            >
+              <Mountain className="w-4 h-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left">{terrainLabel}</TooltipContent>
+        </Tooltip>
+      )}
+
+      {/* Compass — shows only when rotated/tilted (gated here); the chip's
+          needle reflects the bearing and tints accent as an off-north cue,
+          click eases back to north-up + top-down (Google style). */}
+      {compassButton && isOriented && (
+        <CompassChip
+          bearing={bearing}
+          oriented={isOriented}
+          onReset={onResetNorth}
+          label={compassLabel}
+        />
+      )}
+
+      {/* Locate me (GPS) — drives maplibre's hidden GeolocateControl via
+          trigger(). Tinted text-primary while actively following (like the
+          terrain chip); muted/disabled look on permission-denied or
+          unavailable, with a tooltip explaining it. Opt-in only. */}
+      {geolocate && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={onGeolocateTrigger}
+              aria-label={geolocateLabel}
+              aria-pressed={geolocateState === 'active'}
+              className={cn(
+                MAP_CONTROL_CLASS,
+                'w-9 h-9',
+                geolocateState === 'active' && 'bg-popover text-primary',
+                geolocateState === 'error' && 'text-muted-foreground',
+              )}
+            >
+              <LocateFixed className="w-4 h-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left">
+            {geolocateState === 'error'
+              ? 'Location unavailable — check permission'
+              : geolocateLabel}
+          </TooltipContent>
+        </Tooltip>
+      )}
+
+      {externalMapsUrl && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <a
+              href={externalMapsUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              aria-label={externalMapsLabel}
+              className={cn(MAP_CONTROL_CLASS, 'w-9 h-9')}
+            >
+              <MapPin className="w-4 h-4" aria-hidden="true" />
+            </a>
+          </TooltipTrigger>
+          <TooltipContent side="left">{externalMapsLabel}</TooltipContent>
+        </Tooltip>
+      )}
+
+      {showResetButton && hasViewportChanged && (
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={onResetToInitial}
+              aria-label="Reset map view"
+              className={cn(MAP_CONTROL_CLASS, 'w-9 h-9')}
+            >
+              <RotateCcw className="w-4 h-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="left">Reset to the initial view</TooltipContent>
+        </Tooltip>
+      )}
+    </div>
+  )
+}

package/src/tools/dev/Map/components/MapContainer/RotateHint.tsx

@@ -0,0 +1,25 @@
+'use client'
+
+import { cn } from '@djangocfg/ui-core/lib'
+
+/**
+ * Gesture hint — appears briefly when 3D turns on, since rotate/tilt
+ * (right-drag / Ctrl+drag / two fingers) isn't otherwise discoverable. The
+ * compass chip then offers a one-click reset back to north.
+ */
+export function RotateHint({ show }: { show: boolean }) {
+  return (
+    <div
+      aria-hidden={!show}
+      className={cn(
+        'pointer-events-none absolute bottom-3 left-1/2 z-20 -translate-x-1/2',
+        'rounded-full px-3 py-1.5 text-xs font-medium',
+        'bg-popover/95 text-popover-foreground border border-border shadow-sm',
+        'transition-opacity duration-300',
+        show ? 'opacity-100' : 'opacity-0',
+      )}
+    >
+      Right-click or Ctrl+drag to rotate &amp; tilt
+    </div>
+  )
+}

package/src/tools/dev/Map/components/MapContainer/ScrollLockOverlay.tsx

@@ -0,0 +1,52 @@
+'use client'
+
+import { useState } from 'react'
+import { cn } from '@djangocfg/ui-core/lib'
+
+/**
+ * Gesture overlay. Desktop: tap unlocks scroll-zoom in place. Mobile: the map
+ * is fully static, tap expands to fullscreen. `touch-action: pan-y` lets a
+ * vertical swipe scroll the PAGE straight through the overlay so the static
+ * map never traps the scroll.
+ */
+export function ScrollLockOverlay({
+  isMobileLock,
+  resolvedHint,
+  onActivate,
+}: {
+  isMobileLock: boolean
+  resolvedHint: string
+  onActivate: () => void
+}) {
+  const [overlayHovered, setOverlayHovered] = useState(false)
+
+  return (
+    <button
+      type="button"
+      onClick={onActivate}
+      onMouseEnter={() => setOverlayHovered(true)}
+      onMouseLeave={() => setOverlayHovered(false)}
+      aria-label={`${resolvedHint} (map interaction is locked)`}
+      style={{ touchAction: 'pan-y' }}
+      className={cn(
+        'absolute inset-0 z-10 flex items-center justify-center',
+        'cursor-pointer border-0 bg-transparent p-0 transition-colors',
+        'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring',
+        overlayHovered && 'bg-foreground/5'
+      )}
+    >
+      <span
+        className={cn(
+          // Same popover surface as the control chips — floating hint.
+          // Mobile has no hover, so the "Tap to expand" hint is shown
+          // persistently; desktop reveals it on hover.
+          'pointer-events-none select-none rounded-full px-3 py-1.5 text-xs font-medium',
+          'bg-popover/95 text-popover-foreground border border-border shadow-sm transition-opacity',
+          isMobileLock || overlayHovered ? 'opacity-100' : 'opacity-0'
+        )}
+      >
+        {resolvedHint}
+      </span>
+    </button>
+  )
+}