@djangocfg/ui-tools 2.1.431 → 2.1.433

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

@@ -0,0 +1,112 @@
+'use client'
+
+import { useCallback, useMemo, useState } from 'react'
+import type { LngLat } from 'maplibre-gl'
+
+import type { MarkerData } from '../types'
+
+/**
+ * A single controlled, draggable position.
+ *
+ * This is the host-facing shape: `{ id, lng, lat }` plain numbers (plus an
+ * optional `label`). It is intentionally *not* `MarkerData` — `MarkerData`
+ * uses `longitude`/`latitude` and is the map's internal marker store shape.
+ */
+export interface DraggablePoint {
+  id: string
+  lng: number
+  lat: number
+  label?: string
+}
+
+export interface UseDraggableMarkersOptions {
+  /** Controlled list of positions. The host owns this array. */
+  positions: DraggablePoint[]
+  /**
+   * Fires with the full, updated array when a marker is dropped (drag-end).
+   * The host persists `next` and feeds it back via `positions`.
+   */
+  onChange: (next: DraggablePoint[]) => void
+  /** Optional live callback fired on every drag frame (not committed). */
+  onDragMove?: (id: string, lng: number, lat: number) => void
+}
+
+/** Drag handlers for one rendered marker, wired to a single position. */
+export interface DraggableMarkerHandlers {
+  onDragStart: () => void
+  onDrag: (marker: MarkerData, lngLat: LngLat) => void
+  onDragEnd: (marker: MarkerData, lngLat: LngLat) => void
+}
+
+export interface UseDraggableMarkersResult {
+  /**
+   * The positions to render, as `MarkerData` (the map's marker shape).
+   * While a marker is being dragged its entry reflects the live cursor
+   * position so the pin follows the pointer smoothly; everything else mirrors
+   * `positions` 1:1.
+   */
+  markers: MarkerData[]
+  /** Returns the drag handlers for the marker with the given `id`. */
+  getHandlers: (id: string) => DraggableMarkerHandlers
+}
+
+/**
+ * Controlled convenience layer over `MapMarker`'s native `draggable` /
+ * `onDrag*` passthrough.
+ *
+ * `positions` in, `onChange` out — the host owns persistence. Internally the
+ * hook only tracks a *transient* live-drag position so the pin follows the
+ * cursor during `onDrag`; the committed source of truth stays in `positions`.
+ * On drag-end it normalizes the maplibre `LngLat` object (`.lng`/`.lat`) to
+ * plain numbers and emits the full updated array through `onChange`.
+ */
+export function useDraggableMarkers({
+  positions,
+  onChange,
+  onDragMove,
+}: UseDraggableMarkersOptions): UseDraggableMarkersResult {
+  // Transient live-drag state: only the marker currently under the pointer.
+  const [dragging, setDragging] = useState<{
+    id: string
+    lng: number
+    lat: number
+  } | null>(null)
+
+  const markers = useMemo<MarkerData[]>(
+    () =>
+      positions.map((p) => {
+        const live = dragging && dragging.id === p.id ? dragging : null
+        return {
+          id: p.id,
+          longitude: live ? live.lng : p.lng,
+          latitude: live ? live.lat : p.lat,
+          data: p.label !== undefined ? { label: p.label } : undefined,
+        }
+      }),
+    [positions, dragging]
+  )
+
+  const getHandlers = useCallback(
+    (id: string): DraggableMarkerHandlers => ({
+      onDragStart: () => {
+        const p = positions.find((pos) => pos.id === id)
+        if (!p) return
+        setDragging({ id, lng: p.lng, lat: p.lat })
+      },
+      onDrag: (_marker, lngLat) => {
+        setDragging({ id, lng: lngLat.lng, lat: lngLat.lat })
+        onDragMove?.(id, lngLat.lng, lngLat.lat)
+      },
+      onDragEnd: (_marker, lngLat) => {
+        setDragging(null)
+        const next = positions.map((pos) =>
+          pos.id === id ? { ...pos, lng: lngLat.lng, lat: lngLat.lat } : pos
+        )
+        onChange(next)
+      },
+    }),
+    [positions, onChange, onDragMove]
+  )
+
+  return { markers, getHandlers }
+}

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

@@ -0,0 +1,155 @@
+'use client'
+
+/**
+ * useGeocoder — debounced, abortable autocomplete state for an injectable
+ * geocoding `resolve` function (default = public Photon).
+ *
+ * No UI, no map dependency. Debounces the query (~300ms), gates on a minimum
+ * length, and fires ONE `AbortController` per keystroke — the previous
+ * in-flight request is aborted before the next starts. Aborted requests are
+ * swallowed; real failures surface via `error`.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { photonResolve, type GeocodeResult, type ResolveGeocode } from '../geocode'
+
+export interface UseGeocoderOptions {
+  /** Injectable resolver. Defaults to public Photon (`photonResolve`). */
+  resolve?: ResolveGeocode
+  /** Geo-bias — results near this point rank higher (e.g. map center). */
+  near?: { lng: number; lat: number }
+  /** Max results per query. Default 5. */
+  limit?: number
+  /** Minimum query length before a request fires. Default 3. */
+  minLength?: number
+  /** Debounce delay in ms. Default 300. */
+  debounceMs?: number
+}
+
+export interface UseGeocoderResult {
+  /** Current (raw, un-debounced) query text. */
+  query: string
+  /** Update the query — debounced search runs after `debounceMs`. */
+  setQuery: (next: string) => void
+  /** Latest results for the debounced query. */
+  results: GeocodeResult[]
+  /** A request is in flight. */
+  loading: boolean
+  /** Last non-abort error, or `null`. */
+  error: Error | null
+  /** Reset query, results, error and abort any in-flight request. */
+  clear: () => void
+  /**
+   * Convenience for consumers — clears the input and returns the picked
+   * result so it can be wired to e.g. `flyTo`. Purely state-level; it does
+   * not touch the map.
+   */
+  select: (result: GeocodeResult) => GeocodeResult
+}
+
+function isAbortError(err: unknown): boolean {
+  return (
+    err instanceof DOMException
+      ? err.name === 'AbortError'
+      : err instanceof Error && err.name === 'AbortError'
+  )
+}
+
+export function useGeocoder(options: UseGeocoderOptions = {}): UseGeocoderResult {
+  const {
+    resolve = photonResolve,
+    near,
+    limit,
+    minLength = 3,
+    debounceMs = 300,
+  } = options
+
+  const [query, setQueryState] = useState('')
+  const [results, setResults] = useState<GeocodeResult[]>([])
+  const [loading, setLoading] = useState(false)
+  const [error, setError] = useState<Error | null>(null)
+
+  // Keep latest resolver / bias without re-triggering the debounce effect on
+  // identity churn (mirrors the link-preview resolverRef pattern).
+  const resolveRef = useRef(resolve)
+  resolveRef.current = resolve
+  const nearRef = useRef(near)
+  nearRef.current = near
+  const limitRef = useRef(limit)
+  limitRef.current = limit
+
+  // One controller for the in-flight request, aborted on each new keystroke.
+  const controllerRef = useRef<AbortController | null>(null)
+
+  const setQuery = useCallback((next: string) => {
+    setQueryState(next)
+  }, [])
+
+  const clear = useCallback(() => {
+    controllerRef.current?.abort()
+    controllerRef.current = null
+    setQueryState('')
+    setResults([])
+    setError(null)
+    setLoading(false)
+  }, [])
+
+  const select = useCallback((result: GeocodeResult) => {
+    controllerRef.current?.abort()
+    controllerRef.current = null
+    setQueryState('')
+    setResults([])
+    setError(null)
+    setLoading(false)
+    return result
+  }, [])
+
+  useEffect(() => {
+    const q = query.trim()
+
+    // Below the min-length gate: drop stale results, cancel in-flight.
+    if (q.length < minLength) {
+      controllerRef.current?.abort()
+      controllerRef.current = null
+      setResults([])
+      setLoading(false)
+      setError(null)
+      return
+    }
+
+    const timer = setTimeout(() => {
+      controllerRef.current?.abort()
+      const controller = new AbortController()
+      controllerRef.current = controller
+
+      setLoading(true)
+      setError(null)
+
+      resolveRef
+        .current(q, {
+          near: nearRef.current,
+          limit: limitRef.current,
+          signal: controller.signal,
+        })
+        .then((next) => {
+          if (controller.signal.aborted) return
+          setResults(next)
+          setLoading(false)
+        })
+        .catch((err: unknown) => {
+          if (controller.signal.aborted || isAbortError(err)) return
+          setResults([])
+          setError(err instanceof Error ? err : new Error(String(err)))
+          setLoading(false)
+        })
+    }, debounceMs)
+
+    return () => clearTimeout(timer)
+  }, [query, minLength, debounceMs])
+
+  // Abort any in-flight request on unmount.
+  useEffect(() => () => controllerRef.current?.abort(), [])
+
+  return { query, setQuery, results, loading, error, clear, select }
+}

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

@@ -0,0 +1,174 @@
+'use client'
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/**
+ * Live user position from the browser Geolocation API — independent of the
+ * map (no `useMapContext`). Use it for custom "where am I" UI or logic; for
+ * the on-map dot + accuracy circle + follow-mode, prefer `MapContainer`'s
+ * `geolocate` chip (which wraps maplibre's `GeolocateControl`).
+ *
+ * Privacy: nothing happens until you call `request()` or `watch()` — those
+ * trigger the OS permission prompt. Never auto-started.
+ *
+ * Secure context: `navigator.geolocation` requires HTTPS or localhost (it
+ * works in the cmdop Wails webview). Off a secure context the status is
+ * `'unavailable'` and the request methods no-op.
+ */
+
+/** A single position fix, flattened from `GeolocationCoordinates`. */
+export interface GeolocationFix {
+  lat: number
+  lng: number
+  /** Accuracy radius in meters (1σ). */
+  accuracy: number
+  /** Compass heading in degrees (0 = north), or null when unknown/stationary. */
+  heading: number | null
+  /** Ground speed in m/s, or null when unknown. */
+  speed: number | null
+  /** Fix timestamp (ms epoch). */
+  timestamp: number
+}
+
+export type GeolocationStatus =
+  | 'idle' // nothing requested yet
+  | 'locating' // a request/watch is in flight, no fix yet
+  | 'granted' // have a fix
+  | 'denied' // user blocked the permission (PERMISSION_DENIED)
+  | 'unavailable' // no secure context / no geolocation API / POSITION_UNAVAILABLE
+  | 'timeout' // the request timed out
+
+export interface UseGeolocationOptions {
+  /** Higher precision (GPS) at a battery cost. @default false */
+  highAccuracy?: boolean
+  /** Accept a cached fix up to this age (ms). @default 0 (always fresh) */
+  maximumAge?: number
+  /** Give up after this long (ms). @default 10000 */
+  timeout?: number
+}
+
+export interface UseGeolocationResult {
+  /** Latest fix, or null until one arrives. */
+  position: GeolocationFix | null
+  status: GeolocationStatus
+  /** The raw error from the last failure, if any. */
+  error: GeolocationPositionError | null
+  /** True only on HTTPS/localhost with a geolocation API present. */
+  supported: boolean
+  /** One-shot: request a single fix (prompts permission on first use). */
+  request: () => void
+  /** Continuous: start watching the position until `stop()`. */
+  watch: () => void
+  /** Stop an active watch and return to idle (keeps the last fix). */
+  stop: () => void
+}
+
+function toFix(p: GeolocationPosition): GeolocationFix {
+  const c = p.coords
+  return {
+    lat: c.latitude,
+    lng: c.longitude,
+    accuracy: c.accuracy,
+    heading: c.heading != null && !Number.isNaN(c.heading) ? c.heading : null,
+    speed: c.speed != null && !Number.isNaN(c.speed) ? c.speed : null,
+    timestamp: p.timestamp,
+  }
+}
+
+function statusForError(err: GeolocationPositionError): GeolocationStatus {
+  switch (err.code) {
+    case err.PERMISSION_DENIED:
+      return 'denied'
+    case err.TIMEOUT:
+      return 'timeout'
+    default:
+      return 'unavailable' // POSITION_UNAVAILABLE
+  }
+}
+
+export function useGeolocation(
+  options: UseGeolocationOptions = {},
+): UseGeolocationResult {
+  const { highAccuracy = false, maximumAge = 0, timeout = 10_000 } = options
+
+  // Secure-context + API presence. `isSecureContext` is true on
+  // localhost/HTTPS (and in the Wails webview); false on plain http.
+  const supported =
+    typeof navigator !== 'undefined' &&
+    'geolocation' in navigator &&
+    (typeof window === 'undefined' || window.isSecureContext)
+
+  const [position, setPosition] = useState<GeolocationFix | null>(null)
+  const [status, setStatus] = useState<GeolocationStatus>('idle')
+  const [error, setError] = useState<GeolocationPositionError | null>(null)
+
+  const watchIdRef = useRef<number | null>(null)
+  // Keep the latest options in a ref so request/watch identities stay stable.
+  const posOptsRef = useRef<PositionOptions>({})
+  posOptsRef.current = {
+    enableHighAccuracy: highAccuracy,
+    maximumAge,
+    timeout,
+  }
+
+  const onSuccess = useCallback((p: GeolocationPosition) => {
+    setPosition(toFix(p))
+    setError(null)
+    setStatus('granted')
+  }, [])
+
+  const onError = useCallback((err: GeolocationPositionError) => {
+    setError(err)
+    setStatus(statusForError(err))
+  }, [])
+
+  const stop = useCallback(() => {
+    if (watchIdRef.current != null) {
+      navigator.geolocation.clearWatch(watchIdRef.current)
+      watchIdRef.current = null
+    }
+    setStatus((s) => (s === 'locating' || s === 'granted' ? 'idle' : s))
+  }, [])
+
+  const request = useCallback(() => {
+    if (!supported) {
+      setStatus('unavailable')
+      return
+    }
+    setStatus('locating')
+    navigator.geolocation.getCurrentPosition(
+      onSuccess,
+      onError,
+      posOptsRef.current,
+    )
+  }, [supported, onSuccess, onError])
+
+  const watch = useCallback(() => {
+    if (!supported) {
+      setStatus('unavailable')
+      return
+    }
+    // Replace any existing watch.
+    if (watchIdRef.current != null) {
+      navigator.geolocation.clearWatch(watchIdRef.current)
+    }
+    setStatus('locating')
+    watchIdRef.current = navigator.geolocation.watchPosition(
+      onSuccess,
+      onError,
+      posOptsRef.current,
+    )
+  }, [supported, onSuccess, onError])
+
+  // Clear any active watch on unmount.
+  useEffect(() => {
+    return () => {
+      if (watchIdRef.current != null) {
+        navigator.geolocation.clearWatch(watchIdRef.current)
+        watchIdRef.current = null
+      }
+    }
+  }, [])
+
+  return { position, status, error, supported, request, watch, stop }
+}

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

@@ -37,10 +37,14 @@ export function useMapControl(): MapControlActions {
   )
 
   const fitBounds = useCallback(
-    (bounds: LngLatBoundsLike, options?: { padding?: number; duration?: number }) => {
+    (
+      bounds: LngLatBoundsLike,
+      options?: { padding?: number; duration?: number; maxZoom?: number },
+    ) => {
       mapRef.current?.fitBounds(bounds, {
         padding: options?.padding ?? 50,
         duration: options?.duration ?? 1000,
+        ...(options?.maxZoom !== undefined ? { maxZoom: options.maxZoom } : {}),
       })
     },
     [mapRef]

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

@@ -0,0 +1,112 @@
+'use client'
+
+import { useEffect, useState } from 'react'
+
+import { useMapContext } from '../context'
+
+/**
+ * A single icon image to register with the map's sprite at runtime.
+ */
+export interface MapImage {
+  /** Image id — reference this from a symbol layer's `icon-image`. */
+  id: string
+  /** URL to load the image from (PNG/SVG/data-URL). */
+  url: string
+  /**
+   * Treat the image as an SDF (signed-distance field) so `icon-color` can
+   * recolor it per-feature. Use for single-color glyph icons.
+   */
+  sdf?: boolean
+  /** Ratio of image pixels to screen pixels (e.g. `2` for @2x assets). */
+  pixelRatio?: number
+}
+
+export interface UseMapImagesResult {
+  /** `true` once every requested image has been registered on the map. */
+  ready: boolean
+}
+
+/**
+ * Register icon images on the map so a `symbol` layer can reference them by
+ * id via `icon-image`. Images are loaded with `map.loadImage(url)` (MapLibre
+ * 4 returns a Promise resolving to `{ data }`) and added with
+ * `map.addImage(id, data, { sdf, pixelRatio })`.
+ *
+ * - Guards against double-add via `map.hasImage(id)`.
+ * - Re-registers on `styledata` — a style swap drops runtime images, so we
+ *   re-add them whenever the style reloads.
+ * - Removes the images it added on unmount.
+ *
+ * @example
+ * ```tsx
+ * useMapImages([{ id: 'pin', url: '/icons/pin.png' }])
+ * // then: createSymbolLayer({ id: 'pins', sourceId: 'places', iconImage: 'pin' })
+ * ```
+ */
+export function useMapImages(images: MapImage[]): UseMapImagesResult {
+  const { mapRef, isLoaded } = useMapContext()
+  const [ready, setReady] = useState(false)
+
+  // Stable key so the effect re-runs only when the image set actually changes.
+  const key = images
+    .map((img) => `${img.id}|${img.url}|${img.sdf ? 1 : 0}|${img.pixelRatio ?? ''}`)
+    .join('::')
+
+  useEffect(() => {
+    const map = mapRef.current?.getMap()
+    if (!map || !isLoaded) return
+
+    let cancelled = false
+
+    const registerAll = async () => {
+      let registered = 0
+      await Promise.all(
+        images.map(async (img) => {
+          try {
+            if (map.hasImage(img.id)) {
+              registered += 1
+              return
+            }
+            const response = await map.loadImage(img.url)
+            if (cancelled || map.hasImage(img.id)) {
+              registered += 1
+              return
+            }
+            map.addImage(img.id, response.data, {
+              sdf: img.sdf,
+              pixelRatio: img.pixelRatio,
+            })
+            registered += 1
+          } catch {
+            // Image failed to load — skip it; a symbol layer referencing a
+            // missing icon simply renders no icon for that feature.
+          }
+        }),
+      )
+      if (!cancelled) setReady(registered === images.length)
+    }
+
+    void registerAll()
+
+    // A style reload (`setStyle`) drops runtime-added images — re-add them.
+    const onStyleData = () => {
+      void registerAll()
+    }
+    map.on('styledata', onStyleData)
+
+    return () => {
+      cancelled = true
+      map.off('styledata', onStyleData)
+      for (const img of images) {
+        try {
+          if (map.hasImage(img.id)) map.removeImage(img.id)
+        } catch {
+          // map may already be torn down
+        }
+      }
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mapRef, isLoaded, key])
+
+  return { ready }
+}