@djangocfg/ui-tools 2.1.110 → 2.1.112

package/src/tools/Map/hooks/useMapEvents.ts

@@ -0,0 +1,147 @@
+'use client'
+
+import { useEffect, useCallback } from 'react'
+import { useMapContext } from '../context'
+import type { MapEventHandlers, MapMouseEvent, MapViewport } from '../types'
+
+/**
+ * Hook for subscribing to map events
+ * Automatically cleans up event listeners on unmount
+ */
+export function useMapEvents(handlers: MapEventHandlers) {
+  const { mapRef, setViewport, setHoveredFeature, isLoaded } = useMapContext()
+
+  const handleClick = useCallback(
+    (event: maplibregl.MapMouseEvent & { features?: GeoJSON.Feature[] }) => {
+      if (!handlers.onClick) return
+
+      const mapEvent: MapMouseEvent = {
+        lngLat: event.lngLat,
+        point: event.point,
+        features: event.features,
+        originalEvent: event.originalEvent,
+      }
+      handlers.onClick(mapEvent)
+    },
+    [handlers]
+  )
+
+  const handleMouseMove = useCallback(
+    (event: maplibregl.MapMouseEvent & { features?: GeoJSON.Feature[] }) => {
+      if (!handlers.onHover) return
+
+      const feature = event.features?.[0] ?? null
+      setHoveredFeature(feature)
+
+      const mapEvent: MapMouseEvent = {
+        lngLat: event.lngLat,
+        point: event.point,
+        features: event.features,
+        originalEvent: event.originalEvent,
+      }
+      handlers.onHover(mapEvent)
+    },
+    [handlers, setHoveredFeature]
+  )
+
+  const handleMoveStart = useCallback(() => {
+    handlers.onMoveStart?.()
+  }, [handlers])
+
+  const handleMoveEnd = useCallback(() => {
+    const map = mapRef.current
+    if (!map) return
+
+    const center = map.getCenter()
+    const zoom = map.getZoom()
+    const bearing = map.getBearing()
+    const pitch = map.getPitch()
+
+    const newViewport: MapViewport = {
+      longitude: center.lng,
+      latitude: center.lat,
+      zoom,
+      bearing,
+      pitch,
+    }
+
+    setViewport(newViewport)
+    handlers.onMoveEnd?.(newViewport)
+  }, [mapRef, setViewport, handlers])
+
+  const handleZoomStart = useCallback(() => {
+    handlers.onZoomStart?.()
+  }, [handlers])
+
+  const handleZoomEnd = useCallback(() => {
+    const zoom = mapRef.current?.getZoom()
+    if (zoom !== undefined) {
+      handlers.onZoomEnd?.(zoom)
+    }
+  }, [mapRef, handlers])
+
+  const handleLoad = useCallback(() => {
+    handlers.onLoad?.()
+  }, [handlers])
+
+  useEffect(() => {
+    const map = mapRef.current?.getMap()
+    if (!map || !isLoaded) return
+
+    if (handlers.onClick) {
+      map.on('click', handleClick)
+    }
+    if (handlers.onHover) {
+      map.on('mousemove', handleMouseMove)
+    }
+    if (handlers.onMoveStart) {
+      map.on('movestart', handleMoveStart)
+    }
+    if (handlers.onMoveEnd) {
+      map.on('moveend', handleMoveEnd)
+    }
+    if (handlers.onZoomStart) {
+      map.on('zoomstart', handleZoomStart)
+    }
+    if (handlers.onZoomEnd) {
+      map.on('zoomend', handleZoomEnd)
+    }
+
+    return () => {
+      if (handlers.onClick) {
+        map.off('click', handleClick)
+      }
+      if (handlers.onHover) {
+        map.off('mousemove', handleMouseMove)
+      }
+      if (handlers.onMoveStart) {
+        map.off('movestart', handleMoveStart)
+      }
+      if (handlers.onMoveEnd) {
+        map.off('moveend', handleMoveEnd)
+      }
+      if (handlers.onZoomStart) {
+        map.off('zoomstart', handleZoomStart)
+      }
+      if (handlers.onZoomEnd) {
+        map.off('zoomend', handleZoomEnd)
+      }
+    }
+  }, [
+    mapRef,
+    isLoaded,
+    handlers,
+    handleClick,
+    handleMouseMove,
+    handleMoveStart,
+    handleMoveEnd,
+    handleZoomStart,
+    handleZoomEnd,
+  ])
+
+  useEffect(() => {
+    if (isLoaded && handlers.onLoad) {
+      handleLoad()
+    }
+  }, [isLoaded, handlers.onLoad, handleLoad])
+}

package/src/tools/Map/hooks/useMapLayers.ts

@@ -0,0 +1,83 @@
+'use client'
+
+import { useCallback } from 'react'
+import type { LayerProps } from 'react-map-gl/maplibre'
+import type { FilterSpecification } from 'maplibre-gl'
+import { useMapContext } from '../context'
+
+/**
+ * Hook for dynamic layer management
+ */
+export function useMapLayers() {
+  const { mapRef, isLoaded } = useMapContext()
+
+  const addLayer = useCallback(
+    (layer: LayerProps, beforeId?: string) => {
+      const map = mapRef.current?.getMap()
+      if (!map || !isLoaded) return
+
+      if (layer.id && map.getLayer(layer.id)) {
+        map.removeLayer(layer.id)
+      }
+
+      map.addLayer(layer as Parameters<typeof map.addLayer>[0], beforeId)
+    },
+    [mapRef, isLoaded]
+  )
+
+  const removeLayer = useCallback(
+    (id: string) => {
+      const map = mapRef.current?.getMap()
+      if (!map || !isLoaded) return
+
+      if (map.getLayer(id)) {
+        map.removeLayer(id)
+      }
+    },
+    [mapRef, isLoaded]
+  )
+
+  const setLayerVisibility = useCallback(
+    (id: string, visible: boolean) => {
+      const map = mapRef.current?.getMap()
+      if (!map || !isLoaded) return
+
+      if (map.getLayer(id)) {
+        map.setLayoutProperty(id, 'visibility', visible ? 'visible' : 'none')
+      }
+    },
+    [mapRef, isLoaded]
+  )
+
+  const setLayerFilter = useCallback(
+    (id: string, filter: FilterSpecification | null) => {
+      const map = mapRef.current?.getMap()
+      if (!map || !isLoaded) return
+
+      if (map.getLayer(id)) {
+        map.setFilter(id, filter)
+      }
+    },
+    [mapRef, isLoaded]
+  )
+
+  const setLayerPaint = useCallback(
+    (id: string, property: string, value: unknown) => {
+      const map = mapRef.current?.getMap()
+      if (!map || !isLoaded) return
+
+      if (map.getLayer(id)) {
+        map.setPaintProperty(id, property, value)
+      }
+    },
+    [mapRef, isLoaded]
+  )
+
+  return {
+    addLayer,
+    removeLayer,
+    setLayerVisibility,
+    setLayerFilter,
+    setLayerPaint,
+  }
+}

package/src/tools/Map/hooks/useMapViewport.ts

@@ -0,0 +1,62 @@
+'use client'
+
+import { useCallback, useMemo } from 'react'
+import { useMapContext } from '../context'
+import type { MapViewport } from '../types'
+
+/**
+ * Hook for viewport state and animations
+ */
+export function useMapViewport() {
+  const { mapRef, viewport, setViewport } = useMapContext()
+
+  const animateTo = useCallback(
+    (newViewport: Partial<MapViewport>, duration = 1000) => {
+      const map = mapRef.current
+      if (!map) {
+        setViewport(newViewport)
+        return
+      }
+
+      map.easeTo({
+        center: newViewport.longitude !== undefined && newViewport.latitude !== undefined
+          ? [newViewport.longitude, newViewport.latitude]
+          : undefined,
+        zoom: newViewport.zoom,
+        bearing: newViewport.bearing,
+        pitch: newViewport.pitch,
+        duration,
+      })
+    },
+    [mapRef, setViewport]
+  )
+
+  const center = useMemo<[number, number]>(
+    () => [viewport.longitude, viewport.latitude],
+    [viewport.longitude, viewport.latitude]
+  )
+
+  const bounds = useMemo(() => {
+    const map = mapRef.current
+    if (!map) return null
+
+    const b = map.getBounds()
+    if (!b) return null
+
+    return {
+      north: b.getNorth(),
+      south: b.getSouth(),
+      east: b.getEast(),
+      west: b.getWest(),
+    }
+  }, [mapRef, viewport])
+
+  return {
+    viewport,
+    setViewport,
+    animateTo,
+    zoom: viewport.zoom,
+    center,
+    bounds,
+  }
+}

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

@@ -0,0 +1,85 @@
+'use client'
+
+import { useCallback } from 'react'
+import { useMapContext } from '../context'
+import { useMapControl } from './useMapControl'
+import type { MarkerActions, MarkerData } from '../types'
+
+let markerId = 0
+const generateMarkerId = () => `marker-${++markerId}`
+
+/**
+ * Hook for marker management
+ * Provides methods to add, remove, update markers
+ */
+export function useMarkers(): MarkerActions {
+  const { markers, setMarkers } = useMapContext()
+  const { fitBounds } = useMapControl()
+
+  const addMarker = useCallback(
+    (marker: Omit<MarkerData, 'id'>): string => {
+      const id = generateMarkerId()
+      setMarkers((prev) => [...prev, { ...marker, id }])
+      return id
+    },
+    [setMarkers]
+  )
+
+  const removeMarker = useCallback(
+    (id: string) => {
+      setMarkers((prev) => prev.filter((m) => m.id !== id))
+    },
+    [setMarkers]
+  )
+
+  const updateMarker = useCallback(
+    (id: string, updates: Partial<Omit<MarkerData, 'id'>>) => {
+      setMarkers((prev) =>
+        prev.map((m) => (m.id === id ? { ...m, ...updates } : m))
+      )
+    },
+    [setMarkers]
+  )
+
+  const clearMarkers = useCallback(() => {
+    setMarkers([])
+  }, [setMarkers])
+
+  const fitToMarkers = useCallback(
+    (padding = 50) => {
+      if (markers.length === 0) return
+
+      if (markers.length === 1) {
+        const marker = markers[0]
+        fitBounds(
+          [
+            [marker.longitude - 0.01, marker.latitude - 0.01],
+            [marker.longitude + 0.01, marker.latitude + 0.01],
+          ],
+          { padding }
+        )
+        return
+      }
+
+      const lngs = markers.map((m) => m.longitude)
+      const lats = markers.map((m) => m.latitude)
+
+      const bounds: [[number, number], [number, number]] = [
+        [Math.min(...lngs), Math.min(...lats)],
+        [Math.max(...lngs), Math.max(...lats)],
+      ]
+
+      fitBounds(bounds, { padding })
+    },
+    [markers, fitBounds]
+  )
+
+  return {
+    markers,
+    addMarker,
+    removeMarker,
+    updateMarker,
+    clearMarkers,
+    fitToMarkers,
+  }
+}

package/src/tools/Map/index.ts

@@ -0,0 +1,116 @@
+// Types (single source of truth)
+export type {
+  // Marker
+  MarkerData,
+  // Viewport
+  MapViewport,
+  // Context
+  MapContextValue,
+  // Hook return types
+  MapControlActions,
+  MarkerActions,
+  MapEventHandlers,
+  MapMouseEvent,
+  // Style
+  MapStyleKey,
+  // Layer specs (re-exported from react-map-gl)
+  LayerProps,
+  FillLayerSpecification,
+  CircleLayerSpecification,
+  LineLayerSpecification,
+  SymbolLayerSpecification,
+  FilterSpecification,
+  ControlPosition,
+  MarkerProps,
+  // Layer options
+  ClusterLayerOptions,
+  PointLayerOptions,
+  PolygonLayerOptions,
+  LineLayerOptions,
+  RouteLayerOptions,
+  // Control props
+  DrawControlProps,
+  GeocoderControlProps,
+  CustomOverlayProps,
+  // Legend
+  LegendItem,
+  MapLegendProps,
+  // Layer switcher
+  LayerConfig,
+  LayerSwitcherProps,
+} from './types'
+
+// Context
+export { MapProvider, useMapContext, MapContext } from './context'
+export type { MapProviderProps } from './context'
+
+// Hooks
+export {
+  useMap,
+  useMapControl,
+  useMarkers,
+  useMapEvents,
+  useMapViewport,
+  useMapLayers,
+  useControl,
+} from './hooks'
+
+// Components
+export {
+  MapContainer,
+  MapView,
+  MapControls,
+  MapMarker,
+  MapPopup,
+  MapCluster,
+  MapSource,
+  MapLayer,
+  CustomOverlay,
+  MapLegend,
+  LayerSwitcher,
+} from './components'
+export type {
+  MapContainerProps,
+  MapControlsProps,
+  MapMarkerProps,
+  MapPopupProps,
+  MapClusterProps,
+  MapSourceProps,
+  MapLayerProps,
+} from './components'
+
+// Layers
+export {
+  createClusterLayers,
+  createPointLayer,
+  createHeatmapLayer,
+  createPolygonLayer,
+  createPolygonOutlineLayer,
+  createHighlightLayer,
+  createLineLayer,
+  createRouteLayers,
+  createDashedLineLayer,
+  createAnimatedLineLayer,
+} from './layers'
+
+// Styles
+export { MAP_STYLES, getMapStyle } from './styles'
+
+// Utils
+export {
+  calculateBounds,
+  calculateCenter,
+  calculateDistance,
+  isPointInBounds,
+  expandBounds,
+  toGeoJSON,
+  fromGeoJSON,
+  createPoint,
+  createPolygon,
+  createLineString,
+  createFeatureCollection,
+} from './utils'
+
+// Re-export useful types from react-map-gl
+export type { ViewState, MapRef } from 'react-map-gl/maplibre'
+export { Source, Layer, Marker, Popup } from 'react-map-gl/maplibre'

package/src/tools/Map/layers/cluster.ts

@@ -0,0 +1,94 @@
+import type { LayerProps } from 'react-map-gl/maplibre'
+import type { ClusterLayerOptions } from '../types'
+
+const DEFAULT_COLORS: [string, string, string] = ['#51bbd6', '#f1f075', '#f28cb1']
+const DEFAULT_RADII: [number, number, number] = [20, 30, 40]
+const DEFAULT_THRESHOLDS: [number, number] = [100, 750]
+const DEFAULT_HOVER_COLOR = '#3b82f6' // blue-500
+
+export function createClusterLayers(options: ClusterLayerOptions): {
+  cluster: LayerProps
+  clusterCount: LayerProps
+  unclusteredPoint: LayerProps
+} {
+  const {
+    sourceId,
+    colors = DEFAULT_COLORS,
+    radii = DEFAULT_RADII,
+    thresholds = DEFAULT_THRESHOLDS,
+    hoverColor = DEFAULT_HOVER_COLOR,
+  } = options
+
+  const cluster: LayerProps = {
+    id: `${sourceId}-clusters`,
+    type: 'circle',
+    source: sourceId,
+    filter: ['has', 'point_count'],
+    paint: {
+      'circle-color': [
+        'case',
+        ['boolean', ['feature-state', 'hover'], false],
+        hoverColor,
+        [
+          'step',
+          ['get', 'point_count'],
+          colors[0],
+          thresholds[0],
+          colors[1],
+          thresholds[1],
+          colors[2],
+        ],
+      ],
+      'circle-radius': [
+        'step',
+        ['get', 'point_count'],
+        radii[0],
+        thresholds[0],
+        radii[1],
+        thresholds[1],
+        radii[2],
+      ],
+      'circle-stroke-width': 2,
+      'circle-stroke-color': '#fff',
+    },
+  }
+
+  const clusterCount: LayerProps = {
+    id: `${sourceId}-cluster-count`,
+    type: 'symbol',
+    source: sourceId,
+    filter: ['has', 'point_count'],
+    layout: {
+      'text-field': ['get', 'point_count_abbreviated'],
+      'text-size': 12,
+    },
+    paint: {
+      'text-color': '#000',
+    },
+  }
+
+  const unclusteredPoint: LayerProps = {
+    id: `${sourceId}-unclustered-point`,
+    type: 'circle',
+    source: sourceId,
+    filter: ['!', ['has', 'point_count']],
+    paint: {
+      'circle-color': [
+        'case',
+        ['boolean', ['feature-state', 'hover'], false],
+        hoverColor,
+        colors[0],
+      ],
+      'circle-radius': [
+        'case',
+        ['boolean', ['feature-state', 'hover'], false],
+        10,
+        8,
+      ],
+      'circle-stroke-width': 2,
+      'circle-stroke-color': '#fff',
+    },
+  }
+
+  return { cluster, clusterCount, unclusteredPoint }
+}

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

@@ -0,0 +1,15 @@
+export { createClusterLayers } from './cluster'
+export { createPointLayer, createHeatmapLayer } from './point'
+export {
+  createPolygonLayer,
+  createPolygonOutlineLayer,
+  createHighlightLayer,
+} from './polygon'
+export {
+  createLineLayer,
+  createRouteLayers,
+  createDashedLineLayer,
+  createAnimatedLineLayer,
+} from './line'
+
+// Types are exported from ../types.ts

package/src/tools/Map/layers/line.ts

@@ -0,0 +1,93 @@
+import type { LayerProps, LineLayerSpecification } from 'react-map-gl/maplibre'
+import type { LineLayerOptions, RouteLayerOptions } from '../types'
+
+export function createLineLayer({
+  id,
+  sourceId,
+  color = '#3b82f6',
+  width = 3,
+  opacity = 1,
+  dashArray,
+  lineCap = 'round',
+  lineJoin = 'round',
+  blur = 0,
+  minZoom,
+  maxZoom,
+}: LineLayerOptions): LayerProps {
+  const paint: LineLayerSpecification['paint'] = {
+    'line-color': color,
+    'line-width': width,
+    'line-opacity': opacity,
+  }
+
+  if (dashArray) {
+    paint['line-dasharray'] = dashArray
+  }
+
+  if (blur > 0) {
+    paint['line-blur'] = blur
+  }
+
+  const layer: LayerProps = {
+    id,
+    type: 'line',
+    source: sourceId,
+    layout: {
+      'line-cap': lineCap,
+      'line-join': lineJoin,
+    },
+    paint,
+  }
+
+  if (minZoom !== undefined) layer.minzoom = minZoom
+  if (maxZoom !== undefined) layer.maxzoom = maxZoom
+
+  return layer
+}
+
+export function createRouteLayers({
+  sourceId,
+  color = '#3b82f6',
+  width = 4,
+  ...rest
+}: RouteLayerOptions): {
+  outline: LayerProps
+  route: LayerProps
+} {
+  return {
+    outline: createLineLayer({
+      id: `${sourceId}-outline`,
+      sourceId,
+      color: '#ffffff',
+      width: width + 2,
+      lineCap: 'round',
+      lineJoin: 'round',
+      ...rest,
+    }),
+    route: createLineLayer({
+      id: `${sourceId}-route`,
+      sourceId,
+      color,
+      width,
+      lineCap: 'round',
+      lineJoin: 'round',
+      ...rest,
+    }),
+  }
+}
+
+export function createDashedLineLayer(
+  options: Omit<LineLayerOptions, 'dashArray'>
+): LayerProps {
+  return createLineLayer({
+    ...options,
+    dashArray: [2, 2],
+  })
+}
+
+export function createAnimatedLineLayer(options: LineLayerOptions): LayerProps {
+  return createLineLayer({
+    ...options,
+    dashArray: [0, 4, 3],
+  })
+}