@djangocfg/ui-tools 2.1.110 → 2.1.111

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

@@ -0,0 +1,61 @@
+import type { LayerProps } from 'react-map-gl/maplibre'
+import type { PointLayerOptions } from '../types'
+
+export function createPointLayer(
+  id: string,
+  sourceId: string,
+  options: PointLayerOptions = {}
+): LayerProps {
+  const {
+    color = '#3b82f6',
+    radius = 6,
+    strokeWidth = 2,
+    strokeColor = '#fff',
+  } = options
+
+  return {
+    id,
+    type: 'circle',
+    source: sourceId,
+    paint: {
+      'circle-color': color,
+      'circle-radius': radius,
+      'circle-stroke-width': strokeWidth,
+      'circle-stroke-color': strokeColor,
+    },
+  }
+}
+
+export function createHeatmapLayer(
+  id: string,
+  sourceId: string,
+  options: {
+    intensity?: number
+    radius?: number
+    opacity?: number
+  } = {}
+): LayerProps {
+  const { intensity = 1, radius = 20, opacity = 0.8 } = options
+
+  return {
+    id,
+    type: 'heatmap',
+    source: sourceId,
+    paint: {
+      'heatmap-intensity': intensity,
+      'heatmap-radius': radius,
+      'heatmap-opacity': opacity,
+      'heatmap-color': [
+        'interpolate',
+        ['linear'],
+        ['heatmap-density'],
+        0, 'rgba(0, 0, 255, 0)',
+        0.2, 'rgb(0, 0, 255)',
+        0.4, 'rgb(0, 255, 0)',
+        0.6, 'rgb(255, 255, 0)',
+        0.8, 'rgb(255, 128, 0)',
+        1, 'rgb(255, 0, 0)',
+      ],
+    },
+  }
+}

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

@@ -0,0 +1,73 @@
+import type { LayerProps } from 'react-map-gl/maplibre'
+import type { PolygonLayerOptions } from '../types'
+
+export function createPolygonLayer(
+  id: string,
+  sourceId: string,
+  options: PolygonLayerOptions = {}
+): LayerProps {
+  const {
+    fillColor = '#3b82f6',
+    fillOpacity = 0.3,
+    strokeColor = '#1d4ed8',
+    strokeWidth = 2,
+  } = options
+
+  return {
+    id,
+    type: 'fill',
+    source: sourceId,
+    paint: {
+      'fill-color': fillColor,
+      'fill-opacity': fillOpacity,
+      'fill-outline-color': strokeColor,
+    },
+  }
+}
+
+export function createPolygonOutlineLayer(
+  id: string,
+  sourceId: string,
+  options: {
+    color?: string
+    width?: number
+  } = {}
+): LayerProps {
+  const { color = '#1d4ed8', width = 2 } = options
+
+  return {
+    id,
+    type: 'line',
+    source: sourceId,
+    paint: {
+      'line-color': color,
+      'line-width': width,
+    },
+  }
+}
+
+export function createHighlightLayer(
+  id: string,
+  sourceId: string,
+  options: {
+    fillColor?: string
+    fillOpacity?: number
+    strokeColor?: string
+    strokeWidth?: number
+  } = {}
+): LayerProps {
+  const {
+    fillColor = '#fbbf24',
+    fillOpacity = 0.5,
+  } = options
+
+  return {
+    id,
+    type: 'fill',
+    source: sourceId,
+    paint: {
+      'fill-color': fillColor,
+      'fill-opacity': fillOpacity,
+    },
+  }
+}

package/src/tools/Map/lazy.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+/**
+ * Lazy-loaded Map Components
+ *
+ * Heavy MapLibre GL (~800KB) is loaded only when components are rendered.
+ * Use these for automatic code-splitting with Suspense fallback.
+ *
+ * For direct imports without lazy loading, use:
+ * import { MapContainer } from '@djangocfg/ui-tools/map'
+ */
+
+import * as React from 'react';
+import { createLazyComponent, MapLoadingFallback } from '../../components';
+
+// ============================================================================
+// Lazy Components
+// ============================================================================
+
+/**
+ * LazyMapContainer - Lazy-loaded map container
+ *
+ * Automatically shows loading state while MapLibre GL loads (~800KB)
+ */
+export const LazyMapContainer = createLazyComponent(
+  () => import('./components/MapContainer').then((mod) => ({ default: mod.MapContainer })),
+  {
+    displayName: 'LazyMapContainer',
+    fallback: <MapLoadingFallback minHeight={400} />,
+  }
+);
+
+/**
+ * LazyMapView - Lazy-loaded map view (alias for MapContainer)
+ */
+export const LazyMapView = createLazyComponent(
+  () => import('./components/MapContainer').then((mod) => ({ default: mod.MapView })),
+  {
+    displayName: 'LazyMapView',
+    fallback: <MapLoadingFallback minHeight={400} />,
+  }
+);
+
+// ============================================================================
+// Re-export types for convenience
+// ============================================================================
+
+export type {
+  MapContainerProps,
+} from './components';
+
+export type {
+  MapViewport,
+  MapStyleKey,
+  MarkerData,
+} from './types';

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

@@ -0,0 +1,15 @@
+export const MAP_STYLES = {
+  light: 'https://basemaps.cartocdn.com/gl/positron-gl-style/style.json',
+  dark: 'https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json',
+  streets: 'https://basemaps.cartocdn.com/gl/voyager-gl-style/style.json',
+  satellite: 'https://api.maptiler.com/maps/satellite/style.json',
+} as const
+
+export type MapStyleKey = keyof typeof MAP_STYLES
+
+export function getMapStyle(key: MapStyleKey | string): string {
+  if (key in MAP_STYLES) {
+    return MAP_STYLES[key as MapStyleKey]
+  }
+  return key
+}

package/src/tools/Map/types.ts

@@ -0,0 +1,259 @@
+import type { RefObject, ReactElement } from 'react'
+import type {
+  MapRef,
+  ViewState,
+  LayerProps,
+  FillLayerSpecification,
+  CircleLayerSpecification,
+  LineLayerSpecification,
+  SymbolLayerSpecification,
+  ControlPosition,
+  MarkerProps,
+} from 'react-map-gl/maplibre'
+import type { LngLatBoundsLike, LngLat, FilterSpecification } from 'maplibre-gl'
+
+export type { ControlPosition, MarkerProps }
+
+// ============================================================================
+// Marker Types
+// ============================================================================
+
+export interface MarkerData {
+  id: string
+  longitude: number
+  latitude: number
+  data?: Record<string, unknown>
+}
+
+// ============================================================================
+// Viewport Types
+// ============================================================================
+
+export interface MapViewport extends Partial<ViewState> {
+  longitude: number
+  latitude: number
+  zoom: number
+  bearing?: number
+  pitch?: number
+  transitionDuration?: number
+}
+
+// ============================================================================
+// Context Types
+// ============================================================================
+
+export interface MapContextValue {
+  mapRef: RefObject<MapRef | null>
+  viewport: MapViewport
+  setViewport: (viewport: Partial<MapViewport>) => void
+  initialViewport: MapViewport
+  resetToInitial: () => void
+  markers: MarkerData[]
+  setMarkers: React.Dispatch<React.SetStateAction<MarkerData[]>>
+  selectedMarker: MarkerData | null
+  setSelectedMarker: (marker: MarkerData | null) => void
+  hoveredFeature: GeoJSON.Feature | null
+  setHoveredFeature: (feature: GeoJSON.Feature | null) => void
+  isLoaded: boolean
+  setIsLoaded: (loaded: boolean) => void
+}
+
+// ============================================================================
+// Hook Return Types
+// ============================================================================
+
+export interface MapControlActions {
+  flyTo: (center: [number, number], zoom?: number, options?: { duration?: number }) => void
+  easeTo: (center: [number, number], zoom?: number, options?: { duration?: number }) => void
+  fitBounds: (bounds: LngLatBoundsLike, options?: { padding?: number; duration?: number }) => void
+  zoomIn: () => void
+  zoomOut: () => void
+  resetView: (initialViewport: MapViewport) => void
+  getCenter: () => [number, number] | null
+  getZoom: () => number | null
+  getBounds: () => LngLatBoundsLike | null
+}
+
+export interface MarkerActions {
+  markers: MarkerData[]
+  addMarker: (marker: Omit<MarkerData, 'id'>) => string
+  removeMarker: (id: string) => void
+  updateMarker: (id: string, updates: Partial<Omit<MarkerData, 'id'>>) => void
+  clearMarkers: () => void
+  fitToMarkers: (padding?: number) => void
+}
+
+// ============================================================================
+// Event Types
+// ============================================================================
+
+export interface MapEventHandlers {
+  onClick?: (event: MapMouseEvent) => void
+  onHover?: (event: MapMouseEvent) => void
+  onMoveStart?: () => void
+  onMoveEnd?: (viewport: MapViewport) => void
+  onZoomStart?: () => void
+  onZoomEnd?: (zoom: number) => void
+  onLoad?: () => void
+}
+
+export interface MapMouseEvent {
+  lngLat: LngLat
+  point: { x: number; y: number }
+  features?: GeoJSON.Feature[]
+  originalEvent: MouseEvent
+}
+
+// ============================================================================
+// Style Types
+// ============================================================================
+
+export type MapStyleKey = 'light' | 'dark' | 'streets' | 'satellite'
+
+// ============================================================================
+// Layer Types (from react-map-gl & maplibre-gl)
+// ============================================================================
+
+export type {
+  LayerProps,
+  FillLayerSpecification,
+  CircleLayerSpecification,
+  LineLayerSpecification,
+  SymbolLayerSpecification,
+  FilterSpecification,
+}
+
+export interface ClusterLayerOptions {
+  sourceId: string
+  colors?: [string, string, string]
+  radii?: [number, number, number]
+  thresholds?: [number, number]
+  hoverColor?: string
+}
+
+export interface PointLayerOptions {
+  color?: string
+  radius?: number
+  strokeWidth?: number
+  strokeColor?: string
+}
+
+export interface PolygonLayerOptions {
+  fillColor?: string
+  fillOpacity?: number
+  strokeColor?: string
+  strokeWidth?: number
+}
+
+// ============================================================================
+// Line Layer Types
+// ============================================================================
+
+export interface LineLayerOptions {
+  id: string
+  sourceId: string
+  color?: string
+  width?: number
+  opacity?: number
+  dashArray?: number[]
+  lineCap?: 'butt' | 'round' | 'square'
+  lineJoin?: 'bevel' | 'round' | 'miter'
+  blur?: number
+  minZoom?: number
+  maxZoom?: number
+}
+
+export interface RouteLayerOptions extends Omit<LineLayerOptions, 'id'> {
+  sourceId: string
+}
+
+// ============================================================================
+// Control Types
+// ============================================================================
+
+export interface DrawControlProps {
+  position?: ControlPosition
+  displayControlsDefault?: boolean
+  controls?: {
+    point?: boolean
+    line_string?: boolean
+    polygon?: boolean
+    trash?: boolean
+    combine_features?: boolean
+    uncombine_features?: boolean
+  }
+  defaultMode?: string
+  onCreate?: (evt: { features: object[] }) => void
+  onUpdate?: (evt: { features: object[]; action: string }) => void
+  onDelete?: (evt: { features: object[] }) => void
+}
+
+export interface GeocoderControlProps {
+  position: ControlPosition
+  marker?: boolean | Omit<MarkerProps, 'longitude' | 'latitude'>
+  placeholder?: string
+  collapsed?: boolean
+  clearOnBlur?: boolean
+  showResultsWhileTyping?: boolean
+  minLength?: number
+  limit?: number
+  language?: string
+  countries?: string
+  zoom?: number
+  flyTo?: boolean | object
+  onLoading?: (e: object) => void
+  onResults?: (e: object) => void
+  onResult?: (e: object) => void
+  onError?: (e: object) => void
+}
+
+export interface CustomOverlayProps {
+  children: React.ReactNode
+}
+
+// ============================================================================
+// Legend Types
+// ============================================================================
+
+export interface LegendItem {
+  id: string
+  label: string
+  color?: string
+  icon?: React.ReactNode
+  type?: 'circle' | 'line' | 'fill' | 'symbol'
+  visible?: boolean
+}
+
+export interface MapLegendProps {
+  items: LegendItem[]
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  title?: string
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  className?: string
+  style?: React.CSSProperties
+  onItemClick?: (item: LegendItem) => void
+}
+
+// ============================================================================
+// Layer Switcher Types
+// ============================================================================
+
+export interface LayerConfig {
+  id: string
+  label: string
+  defaultVisible?: boolean
+  group?: string
+}
+
+export interface LayerSwitcherProps {
+  layers: LayerConfig[]
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  title?: string
+  collapsible?: boolean
+  defaultCollapsed?: boolean
+  showToggleAll?: boolean
+  className?: string
+  style?: React.CSSProperties
+  onChange?: (layerId: string, visible: boolean) => void
+}

package/src/tools/Map/utils/geo.ts

@@ -0,0 +1,88 @@
+import type { LngLatBoundsLike } from 'maplibre-gl'
+
+/**
+ * Calculate bounding box from an array of coordinates
+ */
+export function calculateBounds(points: [number, number][]): LngLatBoundsLike {
+  if (points.length === 0) {
+    throw new Error('Cannot calculate bounds for empty array')
+  }
+
+  const lngs = points.map((p) => p[0])
+  const lats = points.map((p) => p[1])
+
+  return [
+    [Math.min(...lngs), Math.min(...lats)],
+    [Math.max(...lngs), Math.max(...lats)],
+  ]
+}
+
+/**
+ * Calculate center point from an array of coordinates
+ */
+export function calculateCenter(points: [number, number][]): [number, number] {
+  if (points.length === 0) {
+    throw new Error('Cannot calculate center for empty array')
+  }
+
+  const sumLng = points.reduce((acc, p) => acc + p[0], 0)
+  const sumLat = points.reduce((acc, p) => acc + p[1], 0)
+
+  return [sumLng / points.length, sumLat / points.length]
+}
+
+/**
+ * Calculate distance between two points in kilometers (Haversine formula)
+ */
+export function calculateDistance(
+  from: [number, number],
+  to: [number, number]
+): number {
+  const R = 6371 // Earth's radius in km
+  const dLat = toRad(to[1] - from[1])
+  const dLng = toRad(to[0] - from[0])
+
+  const a =
+    Math.sin(dLat / 2) * Math.sin(dLat / 2) +
+    Math.cos(toRad(from[1])) *
+      Math.cos(toRad(to[1])) *
+      Math.sin(dLng / 2) *
+      Math.sin(dLng / 2)
+
+  const c = 2 * Math.atan2(Math.sqrt(a), Math.sqrt(1 - a))
+  return R * c
+}
+
+function toRad(deg: number): number {
+  return deg * (Math.PI / 180)
+}
+
+/**
+ * Check if a point is within bounds
+ */
+export function isPointInBounds(
+  point: [number, number],
+  bounds: [[number, number], [number, number]]
+): boolean {
+  const [[minLng, minLat], [maxLng, maxLat]] = bounds
+  const [lng, lat] = point
+
+  return lng >= minLng && lng <= maxLng && lat >= minLat && lat <= maxLat
+}
+
+/**
+ * Expand bounds by a percentage
+ */
+export function expandBounds(
+  bounds: [[number, number], [number, number]],
+  percentage: number
+): [[number, number], [number, number]] {
+  const [[minLng, minLat], [maxLng, maxLat]] = bounds
+  const lngDiff = (maxLng - minLng) * (percentage / 100)
+  const latDiff = (maxLat - minLat) * (percentage / 100)
+
+  return [
+    [minLng - lngDiff, minLat - latDiff],
+    [maxLng + lngDiff, maxLat + latDiff],
+  ]
+}

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

@@ -0,0 +1,16 @@
+export {
+  calculateBounds,
+  calculateCenter,
+  calculateDistance,
+  isPointInBounds,
+  expandBounds,
+} from './geo'
+
+export {
+  toGeoJSON,
+  fromGeoJSON,
+  createPoint,
+  createPolygon,
+  createLineString,
+  createFeatureCollection,
+} from './transform'

package/src/tools/Map/utils/transform.ts

@@ -0,0 +1,107 @@
+/**
+ * Convert an array of items to GeoJSON FeatureCollection
+ */
+export function toGeoJSON<T>(
+  items: T[],
+  getLngLat: (item: T) => [number, number],
+  getProperties?: (item: T) => Record<string, unknown>
+): GeoJSON.FeatureCollection {
+  return {
+    type: 'FeatureCollection',
+    features: items.map((item, index) => {
+      const [lng, lat] = getLngLat(item)
+      return {
+        type: 'Feature',
+        id: index,
+        geometry: {
+          type: 'Point',
+          coordinates: [lng, lat],
+        },
+        properties: getProperties ? getProperties(item) : {},
+      }
+    }),
+  }
+}
+
+/**
+ * Convert GeoJSON FeatureCollection to array of items
+ */
+export function fromGeoJSON<T>(
+  fc: GeoJSON.FeatureCollection,
+  transform: (feature: GeoJSON.Feature) => T
+): T[] {
+  return fc.features.map(transform)
+}
+
+/**
+ * Create a GeoJSON Point
+ */
+export function createPoint(
+  coordinates: [number, number],
+  properties: Record<string, unknown> = {}
+): GeoJSON.Feature<GeoJSON.Point> {
+  return {
+    type: 'Feature',
+    geometry: {
+      type: 'Point',
+      coordinates,
+    },
+    properties,
+  }
+}
+
+/**
+ * Create a GeoJSON Polygon
+ */
+export function createPolygon(
+  coordinates: [number, number][],
+  properties: Record<string, unknown> = {}
+): GeoJSON.Feature<GeoJSON.Polygon> {
+  // Ensure the polygon is closed
+  const closed = [...coordinates]
+  if (
+    coordinates.length > 0 &&
+    (coordinates[0][0] !== coordinates[coordinates.length - 1][0] ||
+      coordinates[0][1] !== coordinates[coordinates.length - 1][1])
+  ) {
+    closed.push(coordinates[0])
+  }
+
+  return {
+    type: 'Feature',
+    geometry: {
+      type: 'Polygon',
+      coordinates: [closed],
+    },
+    properties,
+  }
+}
+
+/**
+ * Create a GeoJSON LineString
+ */
+export function createLineString(
+  coordinates: [number, number][],
+  properties: Record<string, unknown> = {}
+): GeoJSON.Feature<GeoJSON.LineString> {
+  return {
+    type: 'Feature',
+    geometry: {
+      type: 'LineString',
+      coordinates,
+    },
+    properties,
+  }
+}
+
+/**
+ * Create an empty FeatureCollection
+ */
+export function createFeatureCollection(
+  features: GeoJSON.Feature[] = []
+): GeoJSON.FeatureCollection {
+  return {
+    type: 'FeatureCollection',
+    features,
+  }
+}