@djangocfg/ui-tools 2.1.431 → 2.1.432

package/src/tools/dev/Map/hooks/useMapScrollProtection.ts

@@ -0,0 +1,155 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { useMapContext } from '../context'
+
+export type MapScrollProtectionMode = 'off' | 'desktop' | 'mobile'
+
+export interface UseMapScrollProtectionResult {
+  /** Whether the lock overlay should be shown. */
+  locked: boolean
+  /**
+   * Click/tap handler for the overlay. On desktop it unlocks scroll-zoom
+   * in place; on mobile it stays locked (the caller opens fullscreen).
+   */
+  unlock: () => void
+  /** True when running in mobile mode — the caller should expand to
+   *  fullscreen on tap instead of unlocking in place. */
+  isMobileLock: boolean
+}
+
+/**
+ * Gesture guard for an inline map.
+ *
+ * - `'desktop'` — Google-Maps-style scroll isolation. Only the wheel/
+ *   trackpad **scroll-zoom** is blocked until the user clicks the map;
+ *   drag-pan / double-click / pinch stay live. Click inside unlocks,
+ *   click outside re-locks. So scrolling a page past the map never
+ *   hijacks the zoom, but the map is never fully inert.
+ *
+ * - `'mobile'` — the map is made **fully static**: scroll-zoom, drag-pan,
+ *   touch pinch/rotate, double-click and keyboard are all disabled, so a
+ *   finger dragging over the map scrolls the PAGE. There is no in-place
+ *   unlock; the caller turns a tap into "open fullscreen", where a fresh
+ *   map runs with all gestures enabled. This is the native-app pattern
+ *   (static map preview in a feed → tap to open the full map).
+ *
+ * - `'off'` — every gesture enabled, no overlay.
+ */
+export function useMapScrollProtection(
+  mode: MapScrollProtectionMode,
+): UseMapScrollProtectionResult {
+  const { mapRef, isLoaded } = useMapContext()
+  const [locked, setLocked] = useState(true)
+
+  // Latest `locked` without forcing the document-listener effect to
+  // re-subscribe on every toggle.
+  const lockedRef = useRef(locked)
+  lockedRef.current = locked
+
+  // On mobile the lock is permanent (tap opens fullscreen); only desktop
+  // unlocks in place.
+  const unlock = useCallback(() => {
+    if (mode === 'desktop') setLocked(false)
+  }, [mode])
+
+  // All the maplibre gesture handlers we toggle in mobile mode. Listed
+  // defensively (some are absent depending on options) — each is guarded.
+  const setAllGestures = useCallback(
+    (map: maplibregl.Map, enable: boolean) => {
+      const handlers = [
+        map.scrollZoom,
+        map.boxZoom,
+        map.dragRotate,
+        map.dragPan,
+        map.keyboard,
+        map.doubleClickZoom,
+        map.touchZoomRotate,
+        (map as unknown as { touchPitch?: { enable(): void; disable(): void } }).touchPitch,
+      ]
+      for (const h of handlers) {
+        if (h && typeof h.enable === 'function') {
+          enable ? h.enable() : h.disable()
+        }
+      }
+    },
+    [],
+  )
+
+  // Apply the lock to maplibre. Re-runs on load and whenever mode/lock change.
+  useEffect(() => {
+    const map = mapRef.current?.getMap()
+    if (!map) return
+
+    if (mode === 'off') {
+      // Make sure nothing we may have disabled stays off.
+      map.scrollZoom.enable()
+      return
+    }
+
+    if (mode === 'mobile') {
+      // Fully static while locked; fully live once unlocked (never happens
+      // on mobile, but keep the branch symmetric).
+      setAllGestures(map, !locked)
+      return
+    }
+
+    // desktop: only the scroll-zoom is gated.
+    if (locked) {
+      map.scrollZoom.disable()
+    } else {
+      map.scrollZoom.enable()
+    }
+  }, [mapRef, isLoaded, mode, locked, setAllGestures])
+
+  // Re-lock (desktop only) when the user clicks anywhere OUTSIDE the map.
+  // We do NOT re-lock on mouse-leave: once you've clicked into the map you
+  // keep interacting even as the pointer wanders off and back — the Google
+  // Maps behavior. Capture phase so we see the click before inner handlers
+  // can stop it. Mobile never unlocks in place, so it needs no re-lock.
+  useEffect(() => {
+    if (mode !== 'desktop') return
+    const container = mapRef.current?.getMap()?.getContainer()
+    if (!container) return
+
+    const handleDocPointerDown = (e: Event) => {
+      const target = e.target as Element | null
+      // A toolbar chip (or a menu/tooltip it opens) — never re-locks, and
+      // when the map is LOCKED, pressing a control unlocks it: the user is
+      // clearly working with the map, so the scroll guard should step aside.
+      const onControl = !!target?.closest?.(
+        '[data-map-control],[data-radix-popper-content-wrapper],[role="menu"],[role="tooltip"]',
+      )
+
+      if (lockedRef.current) {
+        // Only desktop unlocks in place; `unlock()` is a no-op on mobile.
+        if (onControl) unlock()
+        return
+      }
+
+      // Unlocked: clicking a control must NOT re-lock (otherwise pressing a
+      // toolbar button would immediately re-lock the map).
+      if (onControl) return
+      if (!container.contains(e.target as Node)) {
+        setLocked(true)
+      }
+    }
+
+    document.addEventListener('pointerdown', handleDocPointerDown, true)
+    return () => {
+      document.removeEventListener('pointerdown', handleDocPointerDown, true)
+    }
+  }, [mapRef, isLoaded, mode, unlock])
+
+  // Reset to locked whenever the feature is (re)enabled.
+  useEffect(() => {
+    if (mode !== 'off') setLocked(true)
+  }, [mode])
+
+  return {
+    locked: mode !== 'off' && locked,
+    unlock,
+    isMobileLock: mode === 'mobile' && locked,
+  }
+}

package/src/tools/dev/Map/hooks/useMapTouchMode.ts

@@ -0,0 +1,21 @@
+'use client'
+
+import { useIsTouch, useMediaQuery, MEDIA_BREAKPOINTS } from '@djangocfg/ui-core/hooks'
+
+/**
+ * Should the map behave as a "mobile / touch" surface?
+ *
+ * True when the primary pointer is coarse (a finger) OR the viewport is
+ * narrow. Both signals come from ui-core's `matchMedia`-based hooks, NOT
+ * the userAgent — so this reflects real touchscreens, DevTools device
+ * emulation, narrow windows and tablets, and updates live. (UA sniffing
+ * misses touch laptops, mis-detects iPadOS, and won't react to a resize.)
+ *
+ * @param breakpoint width (px) at/under which the map is treated as mobile
+ *   even with a fine pointer. Default 768 (Tailwind `md`).
+ */
+export function useMapTouchMode(breakpoint = MEDIA_BREAKPOINTS.md): boolean {
+  const isTouch = useIsTouch()
+  const isNarrow = useMediaQuery(`(max-width: ${breakpoint - 1}px)`)
+  return isTouch || isNarrow
+}

package/src/tools/dev/Map/hooks/useMarkerCard.ts

@@ -0,0 +1,39 @@
+'use client'
+
+import { useCallback, useMemo, useState } from 'react'
+
+export interface UseMarkerCardResult {
+  /** The currently open marker id, or `null` when none is open. */
+  openId: string | null
+  /** Open the card for `id` (closes any other open card). */
+  open: (id: string) => void
+  /** Close the open card. */
+  close: () => void
+  /** Toggle `id` — closes it if it's already the open one. */
+  toggle: (id: string) => void
+  /** Whether `id` is the currently open card. */
+  isOpen: (id: string) => boolean
+}
+
+/**
+ * useMarkerCard — selection state for marker info-cards. Holds a single
+ * `openId` so only ONE card is open at a time; opening a new id closes the
+ * previous, and `toggle` closes the same id. Pure React glue — no UI, no map
+ * dependency. Drives `MapMarkers`, or use it standalone for manual control.
+ */
+export function useMarkerCard(): UseMarkerCardResult {
+  const [openId, setOpenId] = useState<string | null>(null)
+
+  const open = useCallback((id: string) => setOpenId(id), [])
+  const close = useCallback(() => setOpenId(null), [])
+  const toggle = useCallback(
+    (id: string) => setOpenId((prev) => (prev === id ? null : id)),
+    []
+  )
+  const isOpen = useCallback((id: string) => openId === id, [openId])
+
+  return useMemo(
+    () => ({ openId, open, close, toggle, isOpen }),
+    [openId, open, close, toggle, isOpen]
+  )
+}

package/src/tools/dev/Map/hooks/useMarkers.ts

@@ -48,9 +48,15 @@ export function useMarkers(): MarkerActions {
   }, [setMarkers])
 
   const fitToMarkers = useCallback(
-    (padding = 50) => {
+    // Accepts a plain `padding` number (back-compat) or an options object.
+    // `maxZoom` (default 16) stops a single / tightly-clustered set from
+    // zooming all the way in and losing surrounding context.
+    (paddingOrOpts: number | { padding?: number; maxZoom?: number } = 50) => {
       if (markers.length === 0) return
 
+      const { padding = 50, maxZoom = 16 } =
+        typeof paddingOrOpts === 'number' ? { padding: paddingOrOpts } : paddingOrOpts
+
       if (markers.length === 1) {
         const marker = markers[0]
         fitBounds(
@@ -58,7 +64,7 @@ export function useMarkers(): MarkerActions {
             [marker.longitude - 0.01, marker.latitude - 0.01],
             [marker.longitude + 0.01, marker.latitude + 0.01],
           ],
-          { padding }
+          { padding, maxZoom }
         )
         return
       }
@@ -71,7 +77,7 @@ export function useMarkers(): MarkerActions {
         [Math.max(...lngs), Math.max(...lats)],
       ]
 
-      fitBounds(bounds, { padding })
+      fitBounds(bounds, { padding, maxZoom })
     },
     [markers, fitBounds]
   )

package/src/tools/dev/Map/hooks/useMeasure.ts

@@ -0,0 +1,169 @@
+'use client'
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react'
+import { length as turfLength, area as turfArea } from '@turf/turf'
+
+import { useMapContext } from '../context'
+import { createLineString, createPolygon, createFeatureCollection } from '../utils'
+
+/** Measure interaction mode. */
+export type MeasureMode = 'distance' | 'area'
+
+export interface UseMeasureResult {
+  /** Current measure mode (`'distance'` = path length, `'area'` = polygon area). */
+  mode: MeasureMode
+  /** Switch the measure mode. Clears the in-progress vertices. */
+  setMode: (mode: MeasureMode) => void
+  /** Vertices collected so far, as `[lng, lat]` pairs in click order. */
+  points: [number, number][]
+  /**
+   * The collected geometry as a FeatureCollection ready for `MapSource`.
+   * A LineString in `'distance'` mode, a Polygon in `'area'` mode (empty
+   * until enough vertices exist to form the geometry).
+   */
+  geojson: GeoJSON.FeatureCollection
+  /**
+   * The running total — kilometres in `'distance'` mode, square metres in
+   * `'area'` mode. `0` until at least two (distance) / three (area) points.
+   */
+  total: number
+  /** Human-readable total, e.g. `"1.24 km"`, `"3,420 m²"`, `"0.34 km²"`. */
+  totalLabel: string
+  /** Remove all collected vertices. */
+  clear: () => void
+  /** Whether the measure interaction is listening for map clicks. */
+  active: boolean
+  /** Start / stop listening for map clicks. Stopping clears the vertices. */
+  setActive: (active: boolean) => void
+}
+
+const numberFormat = new Intl.NumberFormat('en-US', { maximumFractionDigits: 0 })
+
+/** Format a distance in kilometres into a compact `m`/`km` label. */
+function formatDistance(km: number): string {
+  if (km <= 0) return '0 m'
+  if (km < 1) return `${numberFormat.format(km * 1000)} m`
+  return `${km.toFixed(2)} km`
+}
+
+/** Format an area in square metres into a compact `m²`/`km²` label. */
+function formatArea(m2: number): string {
+  if (m2 <= 0) return '0 m²'
+  if (m2 < 1_000_000) return `${numberFormat.format(m2)} m²`
+  return `${(m2 / 1_000_000).toFixed(2)} km²`
+}
+
+/**
+ * Click-to-measure interaction for the Map tool.
+ *
+ * Subscribes to map clicks while `active` and appends each `[lng, lat]` to
+ * the vertex list, recomputing a running total with turf:
+ * - `'distance'` → a LineString, total via `turf.length` (km).
+ * - `'area'` → a Polygon, total via `turf.area` (m²).
+ *
+ * Geometry is built with the tool's own `createLineString` / `createPolygon`
+ * helpers so it matches house style and renders through the existing
+ * `createLineLayer` / `createPolygonLayer` factories.
+ *
+ * Must be used inside a `MapProvider` (it reads `useMapContext`).
+ */
+export function useMeasure(initialMode: MeasureMode = 'distance'): UseMeasureResult {
+  const { mapRef, isLoaded } = useMapContext()
+
+  const [mode, setModeState] = useState<MeasureMode>(initialMode)
+  const [active, setActiveState] = useState(false)
+  const [points, setPoints] = useState<[number, number][]>([])
+
+  // Latest mode/active read inside the (re-subscribed only on isLoaded) click
+  // handler, so changing mode/active never re-binds the underlying listener.
+  const modeRef = useRef(mode)
+  const activeRef = useRef(active)
+  useEffect(() => {
+    modeRef.current = mode
+  }, [mode])
+  useEffect(() => {
+    activeRef.current = active
+  }, [active])
+
+  const clear = useCallback(() => {
+    setPoints([])
+  }, [])
+
+  const setMode = useCallback((next: MeasureMode) => {
+    setModeState(next)
+    setPoints([])
+  }, [])
+
+  const setActive = useCallback((next: boolean) => {
+    setActiveState(next)
+    // Stopping the interaction discards the in-progress measurement.
+    if (!next) setPoints([])
+  }, [])
+
+  // Subscribe to map clicks. Listener is attached once per `isLoaded`; the
+  // handler reads the latest mode/active via refs (same pattern as
+  // `useMapEvents`).
+  useEffect(() => {
+    const map = mapRef.current?.getMap()
+    if (!map || !isLoaded) return
+
+    const handleClick = (event: maplibregl.MapMouseEvent) => {
+      if (!activeRef.current) return
+      const { lng, lat } = event.lngLat
+      setPoints((prev) => [...prev, [lng, lat]])
+    }
+
+    map.on('click', handleClick)
+    return () => {
+      map.off('click', handleClick)
+    }
+  }, [mapRef, isLoaded])
+
+  // Reflect the active state as a crosshair cursor on the map canvas.
+  useEffect(() => {
+    const map = mapRef.current?.getMap()
+    if (!map || !isLoaded) return
+    const canvas = map.getCanvas()
+    if (!canvas) return
+    const previous = canvas.style.cursor
+    if (active) canvas.style.cursor = 'crosshair'
+    return () => {
+      canvas.style.cursor = previous
+    }
+  }, [mapRef, isLoaded, active])
+
+  const geojson = useMemo<GeoJSON.FeatureCollection>(() => {
+    if (mode === 'distance') {
+      if (points.length < 2) return createFeatureCollection()
+      return createFeatureCollection([createLineString(points)])
+    }
+    if (points.length < 3) return createFeatureCollection()
+    return createFeatureCollection([createPolygon(points)])
+  }, [mode, points])
+
+  const total = useMemo<number>(() => {
+    if (mode === 'distance') {
+      if (points.length < 2) return 0
+      return turfLength(createLineString(points), { units: 'kilometers' })
+    }
+    if (points.length < 3) return 0
+    return turfArea(createPolygon(points))
+  }, [mode, points])
+
+  const totalLabel = useMemo<string>(
+    () => (mode === 'distance' ? formatDistance(total) : formatArea(total)),
+    [mode, total]
+  )
+
+  return {
+    mode,
+    setMode,
+    points,
+    geojson,
+    total,
+    totalLabel,
+    clear,
+    active,
+    setActive,
+  }
+}

package/src/tools/dev/Map/hooks/useTerrain.ts

@@ -0,0 +1,123 @@
+'use client'
+
+import { useEffect, useRef } from 'react'
+
+import { useMapContext } from '../context'
+import { TERRAIN_DEM } from '../styles'
+
+import type { RasterDEMSourceSpecification } from 'maplibre-gl'
+
+/** Stable source / layer ids the hook owns. */
+const DEM_SOURCE_ID = 'terrain-dem'
+const HILLSHADE_LAYER_ID = 'terrain-hillshade'
+
+/** Default vertical exaggeration — subtle, reads as 3D without caricature. */
+const DEFAULT_EXAGGERATION = 1.2
+/** Pitch eased in when terrain is enabled so it actually reads as 3D. */
+const TERRAIN_PITCH = 60
+
+export interface UseTerrainOptions {
+  /** Turn 3D terrain on/off. */
+  enabled?: boolean
+  /**
+   * `raster-dem` source spec to use. Defaults to the free AWS Terrarium DEM
+   * (`TERRAIN_DEM`) — no API key required.
+   */
+  source?: RasterDEMSourceSpecification
+  /** Vertical exaggeration passed to `setTerrain`. @default 1.2 */
+  exaggeration?: number
+  /** Also add a `hillshade` layer from the same DEM. @default true */
+  hillshade?: boolean
+  /**
+   * Ease the camera pitch in (to ~60°) when enabling and back to 0 when
+   * disabling, so a flat map visibly becomes 3D. Opt out for hosts that
+   * drive pitch themselves. @default true
+   */
+  autoPitch?: boolean
+}
+
+/**
+ * 3D terrain + hillshade from a free `raster-dem` source.
+ *
+ * When `enabled`, adds the DEM source (if absent), calls `setTerrain`, and
+ * optionally a `hillshade` layer. On disable/unmount it clears terrain and
+ * removes the source + layer cleanly. Re-applies on `styledata` because a
+ * style reload drops terrain. Terrain only reads as 3D with `pitch > 0`, so
+ * `autoPitch` eases the camera in/out (default on).
+ *
+ * Mirrors the map-access + add/remove + cleanup pattern of `useMapLayers`.
+ */
+export function useTerrain({
+  enabled = false,
+  source = TERRAIN_DEM,
+  exaggeration = DEFAULT_EXAGGERATION,
+  hillshade = true,
+  autoPitch = true,
+}: UseTerrainOptions) {
+  const { mapRef, isLoaded } = useMapContext()
+
+  // Keep latest opts in refs so the styledata listener always reads current
+  // values without re-subscribing.
+  const optsRef = useRef({ source, exaggeration, hillshade })
+  optsRef.current = { source, exaggeration, hillshade }
+
+  useEffect(() => {
+    const map = mapRef.current?.getMap()
+    if (!map || !isLoaded) return
+
+    const apply = () => {
+      const m = mapRef.current?.getMap()
+      if (!m || !m.isStyleLoaded()) return
+      const { source: src, exaggeration: ex, hillshade: shade } = optsRef.current
+
+      if (!m.getSource(DEM_SOURCE_ID)) {
+        m.addSource(DEM_SOURCE_ID, src)
+      }
+      m.setTerrain({ source: DEM_SOURCE_ID, exaggeration: ex })
+
+      if (shade) {
+        if (!m.getLayer(HILLSHADE_LAYER_ID)) {
+          m.addLayer({
+            id: HILLSHADE_LAYER_ID,
+            type: 'hillshade',
+            source: DEM_SOURCE_ID,
+          })
+        }
+      } else if (m.getLayer(HILLSHADE_LAYER_ID)) {
+        m.removeLayer(HILLSHADE_LAYER_ID)
+      }
+    }
+
+    const teardown = () => {
+      const m = mapRef.current?.getMap()
+      if (!m) return
+      try {
+        if (m.getTerrain()) m.setTerrain(null)
+        if (m.getLayer(HILLSHADE_LAYER_ID)) m.removeLayer(HILLSHADE_LAYER_ID)
+        if (m.getSource(DEM_SOURCE_ID)) m.removeSource(DEM_SOURCE_ID)
+      } catch {
+        // style may have been swapped out mid-teardown — ignore.
+      }
+    }
+
+    if (!enabled) {
+      teardown()
+      if (autoPitch && map.getPitch() > 0) {
+        map.easeTo({ pitch: 0, duration: 600 })
+      }
+      return
+    }
+
+    apply()
+    if (autoPitch && map.getPitch() === 0) {
+      map.easeTo({ pitch: TERRAIN_PITCH, duration: 800 })
+    }
+
+    // A style reload drops terrain/sources — re-apply when the style settles.
+    map.on('styledata', apply)
+    return () => {
+      map.off('styledata', apply)
+      teardown()
+    }
+  }, [mapRef, isLoaded, enabled, autoPitch])
+}

package/src/tools/dev/Map/index.ts

@@ -28,9 +28,9 @@ export type {
   PolygonLayerOptions,
   LineLayerOptions,
   RouteLayerOptions,
+  SymbolLayerOptions,
   // Control props
   DrawControlProps,
-  GeocoderControlProps,
   CustomOverlayProps,
   // Legend
   LegendItem,
@@ -52,7 +52,32 @@ export {
   useMapEvents,
   useMapViewport,
   useMapLayers,
+  useMapImages,
+  useMeasure,
+  useTerrain,
+  useCompass,
+  useGeolocation,
   useControl,
+  useDraggableMarkers,
+  useGeocoder,
+  useMarkerCard,
+  type UseMarkerCardResult,
+  type UseCompassResult,
+  type UseGeocoderOptions,
+  type UseGeocoderResult,
+  type MapImage,
+  type UseMapImagesResult,
+  type UseMeasureResult,
+  type MeasureMode,
+  type UseTerrainOptions,
+  type GeolocationFix,
+  type GeolocationStatus,
+  type UseGeolocationOptions,
+  type UseGeolocationResult,
+  type DraggablePoint,
+  type UseDraggableMarkersOptions,
+  type UseDraggableMarkersResult,
+  type DraggableMarkerHandlers,
 } from './hooks'
 
 // Components
@@ -68,17 +93,45 @@ export {
   CustomOverlay,
   MapLegend,
   LayerSwitcher,
+  MeasureControl,
+  DraggableMarkers,
+  GeocoderInput,
+  GeocoderControl,
+  CompassChip,
+  MarkerCard,
+  MapMarkers,
 } from './components'
 export type {
   MapContainerProps,
+  GeolocateOptions,
+  GeolocatePosition,
   MapControlsProps,
   MapMarkerProps,
   MapPopupProps,
   MapClusterProps,
   MapSourceProps,
   MapLayerProps,
+  MeasureControlProps,
+  DraggableMarkersProps,
+  GeocoderInputProps,
+  GeocoderControlProps,
+  CompassChipProps,
+  MarkerCardProps,
+  MapMarkersProps,
+  MarkerWithCard,
+  MarkerCardAction,
+  MarkerCardData,
+  MarkerCardActionData,
 } from './components'
 
+// The card-data shape. `MarkerCard` (value) is the component above; the data
+// type ships as `MarkerCardInfo` to avoid colliding with that value export.
+export type { MarkerCard as MarkerCardInfo } from './cards'
+
+// Geocoder resolver — pure, key-free (light; no maplibre runtime).
+export { photonResolve, cameraForResult } from './geocode'
+export type { GeocodeResult, GeocodeKind, ResolveGeocode } from './geocode'
+
 // Layers
 export {
   createClusterLayers,
@@ -91,10 +144,14 @@ export {
   createRouteLayers,
   createDashedLineLayer,
   createAnimatedLineLayer,
+  createSymbolLayer,
 } from './layers'
 
 // Styles
-export { MAP_STYLES, getMapStyle } from './styles'
+export { MAP_STYLES, getMapStyle, TERRAIN_DEM, TERRAIN_DEM_URL } from './styles'
+
+// PMTiles protocol — opt-in self-hosted / offline basemaps (no tile server)
+export { addPMTilesProtocol, pmtilesSourceUrl } from './protocols/pmtiles'
 
 // Utils
 export {

package/src/tools/dev/Map/layers/index.ts

@@ -11,5 +11,6 @@ export {
   createDashedLineLayer,
   createAnimatedLineLayer,
 } from './line'
+export { createSymbolLayer } from './symbol'
 
 // Types are exported from ../types.ts