@djangocfg/ui-tools 2.1.430 → 2.1.432

package/src/tools/dev/Map/components/MeasureControl.tsx

@@ -0,0 +1,219 @@
+'use client'
+
+import { memo } from 'react'
+import { Pentagon, Ruler, Spline, Trash2 } from 'lucide-react'
+import { cn } from '@djangocfg/ui-core/lib'
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@djangocfg/ui-core/components'
+
+import { MapSource, MapLayer } from './MapSource'
+import { useMeasure, type MeasureMode } from '../hooks/useMeasure'
+import { createLineLayer } from '../layers/line'
+import { createPolygonLayer, createPolygonOutlineLayer } from '../layers/polygon'
+
+export interface MeasureControlProps {
+  /** Corner the control toolbar is pinned to. @default 'top-left' */
+  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'
+  /** Mode the tool starts in. @default 'distance' */
+  defaultMode?: MeasureMode
+  /** Accent color for the measure overlay (line stroke / polygon fill). */
+  accentColor?: string
+  className?: string
+}
+
+const positionStyles: Record<
+  NonNullable<MeasureControlProps['position']>,
+  React.CSSProperties
+> = {
+  'top-left': { top: 12, left: 12 },
+  'top-right': { top: 12, right: 12 },
+  'bottom-left': { bottom: 12, left: 12 },
+  'bottom-right': { bottom: 12, right: 12 },
+}
+
+// Same floating-chrome chip style MapContainer uses for its map controls
+// (semantic `popover` tokens — reads like maplibre's own controls in light
+// and dark themes). Kept in sync with MAP_CONTROL_CLASS there.
+const MAP_CONTROL_CLASS = cn(
+  'inline-flex items-center justify-center rounded-lg',
+  'bg-popover/95 text-popover-foreground backdrop-blur-sm shadow-sm border border-border',
+  'hover:bg-popover transition-colors',
+  'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+)
+
+const SOURCE_ID = 'measure-source'
+
+/**
+ * On-map measure control — click to measure a path's length (km) or a
+ * polygon's area (m²/km²), with a live total readout and a clear button.
+ *
+ * Drop it as a child of `MapContainer` / `MapView` (inside the
+ * `MapProvider`), alongside `MapLegend` / `LayerSwitcher`:
+ *
+ * ```tsx
+ * <MapContainer initialViewport={...}>
+ *   <MeasureControl />
+ * </MapContainer>
+ * ```
+ *
+ * Renders the measure geometry through the existing `createLineLayer` /
+ * `createPolygonLayer` factories — no bespoke layer code.
+ */
+function MeasureControlComponent({
+  position = 'top-left',
+  defaultMode = 'distance',
+  accentColor = '#f97316',
+  className = '',
+}: MeasureControlProps) {
+  const { mode, setMode, geojson, totalLabel, points, clear, active, setActive } =
+    useMeasure(defaultMode)
+
+  const hasMeasurement = points.length > 0
+
+  return (
+    <>
+      {/* Overlay geometry — reuses the existing line / polygon factories. */}
+      <MapSource id={SOURCE_ID} data={geojson}>
+        {mode === 'area' ? (
+          <>
+            <MapLayer
+              {...createPolygonLayer(`${SOURCE_ID}-fill`, SOURCE_ID, {
+                fillColor: accentColor,
+                fillOpacity: 0.2,
+              })}
+            />
+            <MapLayer
+              {...createPolygonOutlineLayer(`${SOURCE_ID}-outline`, SOURCE_ID, {
+                color: accentColor,
+                width: 2,
+              })}
+            />
+          </>
+        ) : (
+          <MapLayer
+            {...createLineLayer({
+              id: `${SOURCE_ID}-line`,
+              sourceId: SOURCE_ID,
+              color: accentColor,
+              width: 3,
+            })}
+          />
+        )}
+      </MapSource>
+
+      {/* Toolbar — a single popover chip, same chrome as the map controls. */}
+      <div
+        className={cn(
+          'absolute z-20 flex items-center gap-1 p-1',
+          MAP_CONTROL_CLASS,
+          'rounded-lg',
+          className,
+        )}
+        style={positionStyles[position]}
+        role="group"
+        aria-label="Measure tool"
+      >
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={() => setActive(!active)}
+              aria-pressed={active}
+              aria-label={active ? 'Stop measuring' : 'Start measuring'}
+              className={cn(
+                'inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                active
+                  ? 'bg-primary text-primary-foreground'
+                  : 'hover:bg-accent hover:text-accent-foreground',
+              )}
+            >
+              <Ruler className="h-4 w-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">
+            {active ? 'Stop measuring' : 'Measure'}
+          </TooltipContent>
+        </Tooltip>
+
+        {/* Mode switch — distance / area. */}
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={() => setMode('distance')}
+              aria-pressed={mode === 'distance'}
+              aria-label="Measure distance"
+              className={cn(
+                'inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                mode === 'distance'
+                  ? 'bg-accent text-accent-foreground'
+                  : 'hover:bg-accent hover:text-accent-foreground',
+              )}
+            >
+              <Spline className="h-4 w-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Distance</TooltipContent>
+        </Tooltip>
+
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={() => setMode('area')}
+              aria-pressed={mode === 'area'}
+              aria-label="Measure area"
+              className={cn(
+                'inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                mode === 'area'
+                  ? 'bg-accent text-accent-foreground'
+                  : 'hover:bg-accent hover:text-accent-foreground',
+              )}
+            >
+              <Pentagon className="h-4 w-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Area</TooltipContent>
+        </Tooltip>
+
+        {/* Live total readout. */}
+        <span
+          className="px-2 text-xs font-medium tabular-nums"
+          aria-live="polite"
+          aria-label={`Measured ${mode}: ${totalLabel}`}
+        >
+          {totalLabel}
+        </span>
+
+        {/* Clear. */}
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <button
+              type="button"
+              onClick={clear}
+              disabled={!hasMeasurement}
+              aria-label="Clear measurement"
+              className={cn(
+                'inline-flex h-8 w-8 items-center justify-center rounded-md transition-colors',
+                'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+                'hover:bg-accent hover:text-accent-foreground',
+                'disabled:pointer-events-none disabled:opacity-40',
+              )}
+            >
+              <Trash2 className="h-4 w-4" aria-hidden="true" />
+            </button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Clear</TooltipContent>
+        </Tooltip>
+      </div>
+    </>
+  )
+}
+
+export const MeasureControl = memo(MeasureControlComponent)

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

@@ -7,14 +7,48 @@ export { MapSource, MapLayer } from './MapSource'
 export { CustomOverlay } from './CustomOverlay'
 export { MapLegend } from './MapLegend'
 export { LayerSwitcher } from './LayerSwitcher'
+export { MeasureControl } from './MeasureControl'
 
 // DrawControl and GeocoderControl require optional dependencies
 // See DrawControl.tsx and GeocoderControl.tsx for implementation examples
 
 // Types are exported from ../types.ts
-export type { MapContainerProps } from './MapContainer'
+export type { MapContainerProps, GeolocateOptions, GeolocatePosition } from './MapContainer'
 export type { MapControlsProps } from './MapControls'
 export type { MapMarkerProps } from './MapMarker'
 export type { MapPopupProps } from './MapPopup'
 export type { MapClusterProps } from './MapCluster'
 export type { MapSourceProps, MapLayerProps } from './MapSource'
+export type { MeasureControlProps } from './MeasureControl'
+
+export { DraggableMarkers } from './DraggableMarkers'
+export type { DraggableMarkersProps, DraggablePoint } from './DraggableMarkers'
+
+// Geocoder — free, key-free Photon autocomplete (presentational input +
+// thin map-bound control). Injectable `resolve`; no optional deps.
+export { GeocoderInput } from './GeocoderInput'
+export { GeocoderControl } from './GeocoderControl'
+export type { GeocoderInputProps } from './GeocoderInput'
+export type { GeocoderControlProps } from './GeocoderControl'
+
+// Compass chip — presentational reset-to-north control with a Google-style
+// color cue (accent needle when the view is rotated/tilted). Use inside a
+// MapProvider, fed by `useCompass`.
+export { CompassChip } from './CompassChip'
+export type { CompassChipProps } from './CompassChip'
+
+// Marker info-cards — a Google-Maps-style card popup above a pin. `MarkerCard`
+// is the default presentational card (data-driven, standalone); `MapMarkers`
+// wires click → card-above-pin (one open at a time). Both inside a MapProvider.
+export { MarkerCard } from './MarkerCard'
+export type { MarkerCardProps } from './MarkerCard'
+export { MapMarkers } from './MapMarkers'
+export type { MapMarkersProps, MarkerWithCard } from './MapMarkers'
+// Card data types. NOTE: the `MarkerCard` *type* (card data shape) is exported
+// from the top-level Map barrel / `cards` — here the `MarkerCard` name is the
+// component value, so we only surface the non-colliding card types.
+export type {
+  MarkerCardAction,
+  MarkerCardData,
+  MarkerCardActionData,
+} from '../cards/types'

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

@@ -0,0 +1,2 @@
+export { photonResolve, cameraForResult } from './photon';
+export type { GeocodeResult, GeocodeKind, ResolveGeocode } from './photon';

package/src/tools/dev/Map/geocode/photon.ts

@@ -0,0 +1,265 @@
+/**
+ * Photon geocoder resolver — the data contract + default `fetch` resolver
+ * for the address/place autocomplete.
+ *
+ * Mirrors the link-preview seam (`ResolveLinkPreview`): the UI is purely
+ * presentational and resolution is an INJECTABLE async function. The default
+ * `photonResolve` hits the public, key-free Photon (Komoot) endpoint — good
+ * for dev/internal use. A host can supply its own `resolve` (a Wails/Go
+ * method or a Next.js API route proxying Photon / a self-hosted instance) for
+ * production, dodging CORS + fair-use throttling.
+ *
+ * Pure — no React, no map dependency. Safe on the light (maplibre-free)
+ * surface.
+ */
+
+/** Public Photon search endpoint (OSM data, no API key, fair-use only). */
+const PHOTON_ENDPOINT = 'https://photon.komoot.io/api/';
+
+/**
+ * One normalized geocoding hit. Plain JSON so it survives transport /
+ * persistence. `raw` carries the original GeoJSON feature for hosts that
+ * want more than the friendly fields.
+ */
+export interface GeocodeResult {
+  /** `osm_type+osm_id`, else a synthesized stable key. */
+  id: string;
+  /** Primary line — place `name`, else `street housenumber`. */
+  label: string;
+  /** Secondary line — `"city, state, country"` (filtered, joined). */
+  secondary?: string;
+  /** Longitude (GeoJSON x). */
+  lng: number;
+  /** Latitude (GeoJSON y). */
+  lat: number;
+  /** `[minLng, minLat, maxLng, maxLat]` when Photon returns an extent. */
+  bbox?: [number, number, number, number];
+  /**
+   * Coarse location kind, normalized across providers. Drives a sensible
+   * fallback zoom when there's no `bbox` to fit. `'unknown'` when the
+   * provider didn't say.
+   */
+  kind: GeocodeKind;
+  /** The original Photon GeoJSON feature. */
+  raw?: unknown;
+}
+
+/** Provider-agnostic location granularity (coarse → fine). */
+export type GeocodeKind =
+  | 'country'
+  | 'region' // state / province / county
+  | 'city' // city / town / village / locality
+  | 'district' // suburb / neighbourhood / borough
+  | 'postcode'
+  | 'street'
+  | 'house' // house / building / address point
+  | 'poi' // a named point of interest
+  | 'unknown';
+
+/**
+ * Fallback zoom per kind — used ONLY when a result has no `bbox` to fit
+ * (point results like a house or POI). Bigger area → smaller zoom. These are
+ * sensible defaults, not a hardcode of any specific place; the bbox path
+ * (below) handles extents universally.
+ */
+const KIND_ZOOM: Record<GeocodeKind, number> = {
+  country: 4,
+  region: 7,
+  city: 11,
+  district: 13,
+  postcode: 13,
+  street: 15,
+  house: 17,
+  poi: 16,
+  unknown: 14,
+};
+
+/**
+ * The camera move for a chosen result — the SMART-ZOOM core.
+ *
+ * Prefer the location's own extent: if `bbox` is present, return a
+ * `fitBounds` move so the whole feature frames itself (an island fills the
+ * view, a street reads as a street) with no per-place tuning. Otherwise fall
+ * back to a `flyTo` at a zoom chosen by the result's `kind`.
+ */
+export function cameraForResult(
+  result: GeocodeResult,
+):
+  | { type: 'fit'; bbox: [number, number, number, number] }
+  | { type: 'fly'; center: [number, number]; zoom: number } {
+  if (result.bbox) {
+    // Guard against a degenerate (zero-area) bbox — a point disguised as an
+    // extent — which would over-zoom; fall through to kind zoom then.
+    const [minLng, minLat, maxLng, maxLat] = result.bbox;
+    if (maxLng - minLng > 1e-6 && maxLat - minLat > 1e-6) {
+      return { type: 'fit', bbox: result.bbox };
+    }
+  }
+  return {
+    type: 'fly',
+    center: [result.lng, result.lat],
+    zoom: KIND_ZOOM[result.kind] ?? KIND_ZOOM.unknown,
+  };
+}
+
+/**
+ * Injectable resolver. Given a query string, returns ranked results. Honors
+ * an optional `near` geo-bias (e.g. the current map center), a `limit`, and
+ * an `AbortSignal` (rethrows `AbortError` when cancelled; returns `[]` for an
+ * empty/blank query).
+ */
+export type ResolveGeocode = (
+  query: string,
+  opts?: {
+    near?: { lng: number; lat: number };
+    limit?: number;
+    signal?: AbortSignal;
+  },
+) => Promise<GeocodeResult[]>;
+
+/** Photon feature `properties` (the subset we read). */
+interface PhotonProperties {
+  osm_type?: string;
+  osm_id?: number | string;
+  name?: string;
+  street?: string;
+  housenumber?: string;
+  city?: string;
+  state?: string;
+  country?: string;
+  postcode?: string;
+  /** Photon's coarse type, e.g. `city` / `street` / `house` / `country`. */
+  type?: string;
+  /** OSM tag key/value, e.g. `place`/`city`, `highway`/`residential`. */
+  osm_key?: string;
+  osm_value?: string;
+  /** `[minLng, maxLat, maxLng, minLat]` per Photon's extent ordering. */
+  extent?: [number, number, number, number];
+}
+
+interface PhotonFeature {
+  geometry?: { coordinates?: [number, number] };
+  properties?: PhotonProperties;
+}
+
+interface PhotonResponse {
+  features?: PhotonFeature[];
+}
+
+/** Build a `[minLng, minLat, maxLng, maxLat]` bbox from Photon's extent. */
+function normalizeExtent(
+  extent: PhotonProperties['extent'],
+): GeocodeResult['bbox'] {
+  if (!extent || extent.length !== 4) return undefined;
+  const [minLng, maxLat, maxLng, minLat] = extent;
+  return [minLng, minLat, maxLng, maxLat];
+}
+
+/**
+ * Map Photon's `type` (plus OSM `osm_key`/`osm_value` as a fallback) onto our
+ * coarse, provider-agnostic `GeocodeKind`. Pure lookup — no magic numbers.
+ */
+function normalizeKind(p: PhotonProperties): GeocodeKind {
+  switch ((p.type ?? '').toLowerCase()) {
+    case 'country':
+      return 'country';
+    case 'state':
+    case 'region':
+    case 'province':
+    case 'county':
+      return 'region';
+    case 'city':
+    case 'town':
+    case 'village':
+    case 'locality':
+      return 'city';
+    case 'district':
+    case 'suburb':
+    case 'neighbourhood':
+      return 'district';
+    case 'postcode':
+      return 'postcode';
+    case 'street':
+      return 'street';
+    case 'house':
+    case 'building':
+      return 'house';
+  }
+  // Fallbacks from the OSM tag when `type` is missing/unknown.
+  const key = (p.osm_key ?? '').toLowerCase();
+  if (key === 'highway') return 'street';
+  if (key === 'place') return 'city';
+  if (key === 'boundary') return 'region';
+  if (key === 'building') return 'house';
+  if (key === 'amenity' || key === 'shop' || key === 'tourism' || key === 'leisure') {
+    return 'poi';
+  }
+  return 'unknown';
+}
+
+/** Normalize one Photon GeoJSON feature → `GeocodeResult` (or `null`). */
+function toResult(feature: PhotonFeature, index: number): GeocodeResult | null {
+  const coords = feature.geometry?.coordinates;
+  if (!coords || coords.length !== 2) return null;
+  const [lng, lat] = coords;
+  if (typeof lng !== 'number' || typeof lat !== 'number') return null;
+
+  const p = feature.properties ?? {};
+
+  const label =
+    p.name ||
+    [p.street, p.housenumber].filter(Boolean).join(' ') ||
+    [p.city, p.state, p.country].filter(Boolean).join(', ') ||
+    'Unknown location';
+
+  const secondary = [p.city, p.state, p.country].filter(Boolean).join(', ');
+
+  const id =
+    p.osm_type && p.osm_id != null
+      ? `${p.osm_type}${p.osm_id}`
+      : `${lng.toFixed(6)},${lat.toFixed(6)}#${index}`;
+
+  return {
+    id,
+    label,
+    secondary: secondary || undefined,
+    lng,
+    lat,
+    bbox: normalizeExtent(p.extent),
+    kind: normalizeKind(p),
+    raw: feature,
+  };
+}
+
+/**
+ * Default resolver: a built-in `fetch` to the public, key-free Photon
+ * endpoint. Honors `near` (geo-bias), `limit`, and `signal`. Returns `[]`
+ * for a blank query; rethrows `AbortError` when the request is cancelled.
+ */
+export const photonResolve: ResolveGeocode = async (query, opts) => {
+  const q = query.trim();
+  if (!q) return [];
+
+  const limit = opts?.limit ?? 5;
+  const params = new URLSearchParams({ q, limit: String(limit) });
+  if (opts?.near) {
+    params.set('lat', String(opts.near.lat));
+    params.set('lon', String(opts.near.lng));
+  }
+
+  const response = await fetch(`${PHOTON_ENDPOINT}?${params.toString()}`, {
+    signal: opts?.signal,
+    headers: { Accept: 'application/json' },
+  });
+
+  if (!response.ok) {
+    throw new Error(`Photon request failed: ${response.status}`);
+  }
+
+  const json = (await response.json()) as PhotonResponse;
+  const features = json.features ?? [];
+
+  return features
+    .map((feature, index) => toResult(feature, index))
+    .filter((r): r is GeocodeResult => r !== null);
+};

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

@@ -5,6 +5,43 @@ export { useMapEvents } from './useMapEvents'
 export { useMapViewport } from './useMapViewport'
 export { useMapLayers } from './useMapLayers'
 export { useSpiderfy, type UseSpiderfyOptions, type UseSpiderfyResult } from './useSpiderfy'
+export {
+  useMapScrollProtection,
+  type UseMapScrollProtectionResult,
+  type MapScrollProtectionMode,
+} from './useMapScrollProtection'
+export { useMapTouchMode } from './useMapTouchMode'
+export {
+  useMapImages,
+  type MapImage,
+  type UseMapImagesResult,
+} from './useMapImages'
+export { useTerrain, type UseTerrainOptions } from './useTerrain'
+export { useCompass, type UseCompassResult } from './useCompass'
+export { useMeasure, type UseMeasureResult, type MeasureMode } from './useMeasure'
+export {
+  useGeolocation,
+  type GeolocationFix,
+  type GeolocationStatus,
+  type UseGeolocationOptions,
+  type UseGeolocationResult,
+} from './useGeolocation'
+
+export {
+  useDraggableMarkers,
+  type DraggablePoint,
+  type UseDraggableMarkersOptions,
+  type UseDraggableMarkersResult,
+  type DraggableMarkerHandlers,
+} from './useDraggableMarkers'
+
+export {
+  useGeocoder,
+  type UseGeocoderOptions,
+  type UseGeocoderResult,
+} from './useGeocoder'
+
+export { useMarkerCard, type UseMarkerCardResult } from './useMarkerCard'
 
 // Re-export useControl from react-map-gl for custom control creation
 export { useControl } from 'react-map-gl/maplibre'

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

@@ -0,0 +1,44 @@
+'use client'
+
+import { useCallback } from 'react'
+
+import { useMapContext } from '../context'
+
+/** What `useCompass` exposes for a compass chip / camera-orientation UI. */
+export interface UseCompassResult {
+  /** Current camera bearing in degrees (0 = north-up). */
+  bearing: number
+  /** Current camera pitch in degrees (0 = top-down). */
+  pitch: number
+  /**
+   * Whether the view is rotated or tilted off true north / top-down. Google-
+   * style compasses use this to decide whether to show the chip at all and to
+   * tint the needle as an "off-north" cue. Threshold is a half-degree so
+   * floating-point jitter around 0 doesn't flicker it.
+   */
+  isOriented: boolean
+  /** Ease the camera back to a north-up, top-down view (bearing + pitch → 0). */
+  resetNorth: () => void
+}
+
+/**
+ * Compass state for a map — reads the live `bearing`/`pitch` from the viewport
+ * and exposes a one-call reset to north-up + top-down.
+ *
+ * Pure glue around `useMapContext` (no maplibre runtime import); reusable by
+ * any chip inside a `MapProvider`. Mirrors `useTerrain`'s map-access pattern:
+ * the camera move goes through the map ref's `easeTo`.
+ */
+export function useCompass(): UseCompassResult {
+  const { mapRef, viewport } = useMapContext()
+
+  const bearing = viewport.bearing ?? 0
+  const pitch = viewport.pitch ?? 0
+  const isOriented = Math.abs(bearing) > 0.5 || pitch > 0.5
+
+  const resetNorth = useCallback(() => {
+    mapRef.current?.getMap().easeTo({ bearing: 0, pitch: 0, duration: 500 })
+  }, [mapRef])
+
+  return { bearing, pitch, isOriented, resetNorth }
+}